Package org.codehaus.plexus.util.cli

# Class Commandline

java.lang.Object
org.codehaus.plexus.util.cli.Commandline

All Implemented Interfaces:
  `Cloneable`

public class Commandline extends Object implements Cloneable

Commandline objects help handling command lines specifying processes to execute.

The class can be used to define a command line as nested elements or as a helper to define a command line by an application.

`<someelement>
<acommandline executable="/executable/to/run">
<argument value="argument 1" />
<argument line="argument_1 argument_2 argument_3" />
<argument value="argument 4" />
</acommandline>
</someelement>
`

The element `someelement` must provide a method `createAcommandline` which returns an instance of this class.

Author:
  thomas.haas@softwired-inc.com, Stefan Bodewig

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`Commandline.Argument`
`class`
`Commandline.Marker`
Class to keep track of the position of an Argument.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected Vector<Arg>`
`arguments`
`protected Map<String,String>`
`envVars`
`protected String`
`executable`
Deprecated.
Use `setExecutable(String)` instead.
`protected static final String`
`OS_NAME`
Deprecated.
Use `Os` class instead.
`protected static final String`
`WINDOWS`
Deprecated.
Use `Os` class instead.

## Constructor Summary

Constructors
Constructor
Description
`Commandline()`
Create a new command line object.
`Commandline(String toProcess)`
Create a new command line object, given a command following POSIX sh quoting rules
`Commandline(String toProcess, Shell shell)`
Create a new command line object.
`Commandline(Shell shell)`
Create a new command line object.

## Method Summary

Modifier and Type
Method
Description
`void`
`addArg(Arg argument)`
`void`
`addArg(Arg argument, boolean insertAtStart)`
Adds an argument object to our list of args.
`void`
`addArguments(String[] line)`
`void`
`addEnvironment(String name, String value)`
Add an environment variable
`void`
`addSystemEnvironment()`
Add system environment variables
`void`
`clear()`
Clear out the whole command line.
`void`
`clearArgs()`
Clear out the arguments but leave the executable in place for another operation.
`Object`
`clone()`
`Arg`
`createArg()`
Creates an argument object.
`Arg`
`createArg(boolean insertAtStart)`
`Commandline.Argument`
`createArgument()`
Deprecated.
Use `createArg()` instead
`Commandline.Argument`
`createArgument(boolean insertAtStart)`
Deprecated.
Use `createArg(boolean)` instead
`Commandline.Marker`
`createMarker()`
This marker can be used to locate a position on the commandline - to insert something for example - when all parameters have been set.
`Process`
`execute()`
Executes the command.
`String[]`
`getArguments()`
`String[]`
`getCommandline()`
`String[]`
`getEnvironmentVariables()`
`String`
`getExecutable()`
Return an executable name, quoted for shell use.
`String`
`getLiteralExecutable()`
`long`
`getPid()`
`String[]`
`getRawCommandline()`
Returns the executable and all defined arguments.
`Shell`
`getShell()`
Get the shell to be used in this command line.
`String[]`
`getShellCommandline()`
Returns the shell, executable and all defined arguments.
`Properties`
`getSystemEnvVars()`
`File`
`getWorkingDirectory()`
`static String`
`quoteArgument(String argument)`
Deprecated.
Use `CommandLineUtils.quote(String)` instead.
`void`
`setExecutable(String executable)`
Sets the executable to run.
`void`
`setPid(long pid)`
`void`
`setShell(Shell shell)`
Allows to set the shell to be used in this command line.
`void`
`setWorkingDirectory(File workingDirectory)`
Sets execution directory.
`void`
`setWorkingDirectory(String path)`
Sets execution directory.
`int`
`size()`
`String`
`toString()`
`static String`
`toString(String[] line)`
Deprecated.
Use `CommandLineUtils.toString(String[])` instead.
`static String[]`
`translateCommandline(String toProcess)`
Deprecated.
Use `CommandLineUtils.translateCommandline(String)` instead.

### Methods inherited from class java.lang.Object

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

## Field Details

### OS_NAME

@Deprecated protected static final String OS_NAME
Deprecated.
Use `Os` class instead.

See Also:
  - Constant Field Values

### WINDOWS

@Deprecated protected static final String WINDOWS
Deprecated.
Use `Os` class instead.

See Also:
  - Constant Field Values

### arguments

protected Vector<Arg> arguments

### envVars

protected Map<String,String> envVars

### executable

@Deprecated protected String executable
Deprecated.
Use `setExecutable(String)` instead.

## Constructor Details

### Commandline

public Commandline(String toProcess, Shell shell)
Create a new command line object. Shell is autodetected from operating system Shell usage is only desirable when generating code for remote execution.

Parameters:
  `toProcess` - sh to process
  `shell` - Shell to use

### Commandline

public Commandline(Shell shell)
Create a new command line object. Shell is autodetected from operating system Shell usage is only desirable when generating code for remote execution.

Parameters:
  `shell` - the Shell

### Commandline

public Commandline(String toProcess)
Create a new command line object, given a command following POSIX sh quoting rules

Parameters:
  `toProcess` - the process

### Commandline

public Commandline()
Create a new command line object.

## Method Details

### getPid

public long getPid()

### setPid

public void setPid(long pid)

### createArgument

@Deprecated public Commandline.Argument createArgument()
Deprecated.
Use `createArg()` instead

Creates an argument object.

Each commandline object has at most one instance of the argument class. This method calls `this.createArgument(false)`.

Returns:
  the argument object.
See Also:
  - `createArgument(boolean)`

### createArgument

@Deprecated public Commandline.Argument createArgument(boolean insertAtStart)
Deprecated.
Use `createArg(boolean)` instead

Creates an argument object and adds it to our list of args.

Each commandline object has at most one instance of the argument class.

Parameters:
  `insertAtStart` - if true, the argument is inserted at the beginning of the list of args, otherwise it is appended.
Returns:
  Argument the argument Object

### createArg

public Arg createArg()

Creates an argument object.

Each commandline object has at most one instance of the argument class. This method calls `this.createArgument(false)`.

Returns:
  the argument object.
See Also:
  - `createArgument(boolean)`

### createArg

public Arg createArg(boolean insertAtStart)

Parameters:
  `insertAtStart` - if true, the argument is inserted at the beginning of the list of args, otherwise it is appended.
Returns:
  Creates an argument object and adds it to our list of args.

  Each commandline object has at most one instance of the argument class.

### addArg

public void addArg(Arg argument)

Parameters:
  `argument` - the argument
See Also:
  - `addArg(Arg,boolean)`

### addArg

public void addArg(Arg argument, boolean insertAtStart)
Adds an argument object to our list of args.

Parameters:
  `argument` - the argument
  `insertAtStart` - if true, the argument is inserted at the beginning of the list of args, otherwise it is appended.

### setExecutable

public void setExecutable(String executable)
Sets the executable to run.

Parameters:
  `executable` - the executable

### getLiteralExecutable

public String getLiteralExecutable()

Returns:
  Executable to be run, as a literal string (no shell quoting/munging)

### getExecutable

public String getExecutable()
Return an executable name, quoted for shell use. Shell usage is only desirable when generating code for remote execution.

Returns:
  Executable to be run, quoted for shell interpretation

### addArguments

public void addArguments(String[] line)

### addEnvironment

public void addEnvironment(String name, String value)
Add an environment variable

Parameters:
  `name` - name
  `value` - value

### addSystemEnvironment

public void addSystemEnvironment() throws Exception
Add system environment variables

Throws:
  `Exception` - if error

### getEnvironmentVariables

public String[] getEnvironmentVariables() throws CommandLineException

Returns:
  String[] Return the list of environment variables
Throws:
  `CommandLineException` - if error

### getCommandline

public String[] getCommandline()

Returns:
  Returns the executable and all defined arguments. For Windows Family, `getShellCommandline()` is returned

### getRawCommandline

public String[] getRawCommandline()
Returns the executable and all defined arguments.

Returns:
  the command line as array not escaped neither quoted

### getShellCommandline

public String[] getShellCommandline()
Returns the shell, executable and all defined arguments. Shell usage is only desirable when generating code for remote execution.

Returns:
  the command line as array

### getArguments

public String[] getArguments()

Returns:
  Returns all arguments defined by `addLine`, `addValue` or the argument object.

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### size

public int size()

### clone

public Object clone()

Overrides:
  `clone` in class `Object`

### clear

public void clear()
Clear out the whole command line.

### clearArgs

public void clearArgs()
Clear out the arguments but leave the executable in place for another operation.

### createMarker

public Commandline.Marker createMarker()

This marker can be used to locate a position on the commandline - to insert something for example - when all parameters have been set.

Returns:
  Return a marker.

### setWorkingDirectory

public void setWorkingDirectory(String path)
Sets execution directory.

Parameters:
  `path` - the working directory as String

### setWorkingDirectory

public void setWorkingDirectory(File workingDirectory)
Sets execution directory.

Parameters:
  `workingDirectory` - the File used as working directory

### getWorkingDirectory

public File getWorkingDirectory()

### execute

public Process execute() throws CommandLineException
Executes the command.

Returns:
  the Process
Throws:
  `CommandLineException` - if error

### getSystemEnvVars

public Properties getSystemEnvVars() throws Exception

Throws:
  `Exception`

### setShell

public void setShell(Shell shell)
Allows to set the shell to be used in this command line. Shell usage is only desirable when generating code for remote execution.

Parameters:
  `shell` - Shell to use
Since:
  1.2

### getShell

public Shell getShell()
Get the shell to be used in this command line. Shell usage is only desirable when generating code for remote execution.

Returns:
  the Shell
Since:
  1.2

### translateCommandline

@Deprecated public static String[] translateCommandline(String toProcess) throws Exception
Deprecated.
Use `CommandLineUtils.translateCommandline(String)` instead.

Parameters:
  `toProcess` - the process
Returns:
  the command line arguments
Throws:
  `Exception` - if error happen

### quoteArgument

@Deprecated public static String quoteArgument(String argument) throws CommandLineException
Deprecated.
Use `CommandLineUtils.quote(String)` instead.

Parameters:
  `argument` - the argument
Returns:
  the quote arg
Throws:
  `CommandLineException` - if error happen

### toString

@Deprecated public static String toString(String[] line)
Deprecated.
Use `CommandLineUtils.toString(String[])` instead.

Parameters:
  `line` - the lines
Returns:
  lines as single String