Package com.intellij.execution.configurations

Class GeneralCommandLine

java.lang.Object

com.intellij.execution.configurations.GeneralCommandLine

All Implemented Interfaces:

UserDataHolder

Direct Known Subclasses:

PtyCommandLine

public class GeneralCommandLine
extends java.lang.Object
implements UserDataHolder

OS-independent way of executing external processes with complex parameters.

Main idea of the class is to accept parameters "as-is", just as they should look to an external process, and quote/escape them as required by the underlying platform - so to run some program with a "parameter with space" all that's needed is new GeneralCommandLine("some program", "parameter with space").createProcess().

Consider the following things when using this class.

Working directory

By default, a current directory of the IDE process is used (usually a "bin/" directory of IDE installation). If a child process may create files in it, this choice is unwelcome. On the other hand, informational commands (e.g. "git --version") are safe. When unsure, set it to something neutral - like user's home or a temp directory.

Parent Environment

Three options here. For commands designed from the ground up for typing into a terminal, use CONSOLE (typical cases: version controls, Node.js and all the surrounding stuff, Python and Ruby interpreters and utilities, etc). For GUI apps and CLI tools that aren't primarily intended to be launched by humans, use SYSTEM (examples: UI builders, browsers, XCode components). And for the empty environment, there is NONE. According to an extensive research conducted by British scientists (tm) on a diverse population of both wild and domesticated tools (no one was harmed), most of them are either insensitive to an environment or fall into the first category, thus backing up the choice of CONSOLE as the default value.

Encoding/Charset

The getCharset() method is used by classes like OSProcessHandler or ExecUtil to decode bytes of a child's output stream. For proper conversion, the same value should be used on another side of the pipe. Chances are you don't have to mess with the setting - because a platform-dependent guessing behind Charset.defaultCharset() is used by default and a child process may happen to use a similar heuristic. If the above automagic fails or more control is needed, the charset may be set explicitly. Again, do not forget the other side - call addParameter("-Dfile.encoding=...") for Java-based tools, or use withEnvironment("HGENCODING", "...") for Mercurial, etc.

See Also:

com.intellij.execution.util.ExecUtil, OSProcessHandler

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GeneralCommandLine.ParentEnvironmentType Determines the scope of a parent environment passed to a child process.

Constructor Summary

Constructors

Modifier	Constructor and Description
	GeneralCommandLine()
protected	GeneralCommandLine(GeneralCommandLine original)
	GeneralCommandLine(java.util.List<java.lang.String> command)
	GeneralCommandLine(java.lang.String... command)

Method Summary

Modifier and Type	Method and Description
void	addParameter(java.lang.String parameter)
void	addParameters(java.util.List<java.lang.String> parameters)
void	addParameters(java.lang.String... parameters)
protected java.lang.ProcessBuilder	buildProcess(java.lang.ProcessBuilder builder) Executed with pre-filled ProcessBuilder as the param and gives the last chance to configure starting process parameters before a process is started
java.lang.Process	createProcess()
java.nio.charset.Charset	getCharset()
java.util.List<java.lang.String>	getCommandLineList(java.lang.String exeName)
java.lang.String	getCommandLineString() Returns string representation of this command line. Warning: resulting string is not OS-dependent - do not use it for executing this command line.
java.lang.String	getCommandLineString(java.lang.String exeName) Returns string representation of this command line. Warning: resulting string is not OS-dependent - do not use it for executing this command line.
java.util.Map<java.lang.String,java.lang.String>	getEffectiveEnvironment() Returns an environment as seen by a child process, that is the environment merged with the parent one.
java.util.Map<java.lang.String,java.lang.String>	getEnvironment() Note: the map returned is forgiving to passing null values into putAll().
java.lang.String	getExePath()
java.io.File	getInputFile()
ParametersList	getParametersList()
java.util.Map<java.lang.String,java.lang.String>	getParentEnvironment() Returns an environment that will be inherited by a child process.
GeneralCommandLine.ParentEnvironmentType	getParentEnvironmentType()
java.lang.String	getPreparedCommandLine() Prepares command (quotes and escapes all arguments) and returns it as a newline-separated list.
java.lang.String	getPreparedCommandLine(Platform platform) Prepares command (quotes and escapes all arguments) and returns it as a newline-separated list (suitable e.g.
<T> T	getUserData(Key<T> key)
java.io.File	getWorkDirectory()
static java.lang.String	inescapableQuote(java.lang.String parameter) Normally, double quotes in parameters are escaped, so they arrive to a called program as-is.
boolean	isPassParentEnvironment()
boolean	isRedirectErrorStream()
protected java.util.List<java.lang.String>	prepareCommandLine(java.lang.String command, java.util.List<java.lang.String> parameters, Platform platform)
<T> void	putUserData(Key<T> key, T value) Add a new user data value to this object.
void	setCharset(java.nio.charset.Charset charset)
void	setExePath(java.lang.String exePath)
void	setPassParentEnvironment(boolean passParentEnvironment) Deprecated. use withParentEnvironmentType(ParentEnvironmentType)
void	setRedirectErrorStream(boolean redirectErrorStream)
protected void	setupEnvironment(java.util.Map<java.lang.String,java.lang.String> environment)
void	setWorkDirectory(java.io.File workDirectory)
void	setWorkDirectory(java.lang.String path)
protected java.lang.Process	startProcess(java.util.List<java.lang.String> escapedCommands)
java.lang.String	toString()
GeneralCommandLine	withCharset(java.nio.charset.Charset charset)
GeneralCommandLine	withEnvironment(java.util.Map<java.lang.String,java.lang.String> environment)
GeneralCommandLine	withEnvironment(java.lang.String key, java.lang.String value)
GeneralCommandLine	withExePath(java.lang.String exePath)
GeneralCommandLine	withInput(java.io.File file)
GeneralCommandLine	withParameters(java.util.List<java.lang.String> parameters)
GeneralCommandLine	withParameters(java.lang.String... parameters)
GeneralCommandLine	withParentEnvironmentType(GeneralCommandLine.ParentEnvironmentType type)
GeneralCommandLine	withRedirectErrorStream(boolean redirectErrorStream)
GeneralCommandLine	withWorkDirectory(java.io.File workDirectory)
GeneralCommandLine	withWorkDirectory(java.lang.String path)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

GeneralCommandLine

public GeneralCommandLine()

GeneralCommandLine

public GeneralCommandLine(java.lang.String... command)

GeneralCommandLine

public GeneralCommandLine(java.util.List<java.lang.String> command)

GeneralCommandLine

protected GeneralCommandLine(GeneralCommandLine original)

Method Detail

getExePath

public java.lang.String getExePath()

withExePath

public GeneralCommandLine withExePath(java.lang.String exePath)

setExePath

public void setExePath(java.lang.String exePath)

getWorkDirectory

public java.io.File getWorkDirectory()

withWorkDirectory

public GeneralCommandLine withWorkDirectory(java.lang.String path)

withWorkDirectory

public GeneralCommandLine withWorkDirectory(java.io.File workDirectory)

setWorkDirectory

public void setWorkDirectory(java.lang.String path)

setWorkDirectory

public void setWorkDirectory(java.io.File workDirectory)

getEnvironment

public java.util.Map<java.lang.String,java.lang.String> getEnvironment()

Note: the map returned is forgiving to passing null values into putAll().

withEnvironment

public GeneralCommandLine withEnvironment(java.util.Map<java.lang.String,java.lang.String> environment)

withEnvironment

public GeneralCommandLine withEnvironment(java.lang.String key,
                                          java.lang.String value)

isPassParentEnvironment

public boolean isPassParentEnvironment()

setPassParentEnvironment

@Deprecated
public void setPassParentEnvironment(boolean passParentEnvironment)

Deprecated. use withParentEnvironmentType(ParentEnvironmentType)

getParentEnvironmentType

public GeneralCommandLine.ParentEnvironmentType getParentEnvironmentType()

withParentEnvironmentType

public GeneralCommandLine withParentEnvironmentType(GeneralCommandLine.ParentEnvironmentType type)

getParentEnvironment

public java.util.Map<java.lang.String,java.lang.String> getParentEnvironment()

Returns an environment that will be inherited by a child process.

See Also:

getEffectiveEnvironment()

getEffectiveEnvironment

public java.util.Map<java.lang.String,java.lang.String> getEffectiveEnvironment()

Returns an environment as seen by a child process, that is the environment merged with the parent one.

addParameters

public void addParameters(java.lang.String... parameters)

addParameters

public void addParameters(java.util.List<java.lang.String> parameters)

withParameters

public GeneralCommandLine withParameters(java.lang.String... parameters)

withParameters

public GeneralCommandLine withParameters(java.util.List<java.lang.String> parameters)

addParameter

public void addParameter(java.lang.String parameter)

getParametersList

public ParametersList getParametersList()

getCharset

public java.nio.charset.Charset getCharset()

withCharset

public GeneralCommandLine withCharset(java.nio.charset.Charset charset)

setCharset

public void setCharset(java.nio.charset.Charset charset)

isRedirectErrorStream

public boolean isRedirectErrorStream()

withRedirectErrorStream

public GeneralCommandLine withRedirectErrorStream(boolean redirectErrorStream)

setRedirectErrorStream

public void setRedirectErrorStream(boolean redirectErrorStream)

getInputFile

public java.io.File getInputFile()

withInput

public GeneralCommandLine withInput(java.io.File file)

getCommandLineString

public java.lang.String getCommandLineString()

Returns string representation of this command line.
Warning: resulting string is not OS-dependent - do not use it for executing this command line.

Returns:

single-string representation of this command line.

getCommandLineString

public java.lang.String getCommandLineString(java.lang.String exeName)

Returns string representation of this command line.
Warning: resulting string is not OS-dependent - do not use it for executing this command line.

Parameters:

exeName - use this executable name instead of given by setExePath(String)

Returns:

single-string representation of this command line.

getCommandLineList

public java.util.List<java.lang.String> getCommandLineList(java.lang.String exeName)

getPreparedCommandLine

public java.lang.String getPreparedCommandLine()

Prepares command (quotes and escapes all arguments) and returns it as a newline-separated list.

Returns:

command as a newline-separated list.

See Also:

getPreparedCommandLine(Platform)

getPreparedCommandLine

public java.lang.String getPreparedCommandLine(Platform platform)

Prepares command (quotes and escapes all arguments) and returns it as a newline-separated list (suitable e.g. for passing in an environment variable).

Parameters:

platform - a target platform

Returns:

command as a newline-separated list.

prepareCommandLine

protected java.util.List<java.lang.String> prepareCommandLine(java.lang.String command,
                                                              java.util.List<java.lang.String> parameters,
                                                              Platform platform)

createProcess

public java.lang.Process createProcess()
                                throws ExecutionException

Throws:

ExecutionException

startProcess

protected java.lang.Process startProcess(java.util.List<java.lang.String> escapedCommands)
                                  throws java.io.IOException

Throws:

java.io.IOException

buildProcess

protected java.lang.ProcessBuilder buildProcess(java.lang.ProcessBuilder builder)

Executed with pre-filled ProcessBuilder as the param and gives the last chance to configure starting process parameters before a process is started

Parameters:

builder - filed ProcessBuilder

setupEnvironment

protected void setupEnvironment(java.util.Map<java.lang.String,java.lang.String> environment)

inescapableQuote

public static java.lang.String inescapableQuote(java.lang.String parameter)

Normally, double quotes in parameters are escaped, so they arrive to a called program as-is. But some commands (e.g. 'cmd /c start "title" ...') should get their quotes non-escaped. Wrapping a parameter by this method (instead of using quotes) will do exactly this.

See Also:

com.intellij.execution.util.ExecUtil#getTerminalCommand(String, String)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getUserData

public <T> T getUserData(Key<T> key)

Specified by:

getUserData in interface UserDataHolder

Returns:

a user data value associated with this object. Doesn't require read action.

putUserData

public <T> void putUserData(Key<T> key,
                            T value)

Description copied from interface: UserDataHolder

Add a new user data value to this object. Doesn't require write action.

Specified by:

putUserData in interface UserDataHolder