Package org.apache.tools.ant.types

## Class Commandline

- java.lang.Object
- - org.apache.tools.ant.types.Commandline

All Implemented Interfaces:
  `java.lang.Cloneable`

    public class Commandline
    extends java.lang.Object
    implements java.lang.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.

### Nested Class Summary

Nested Classes
`static class` `Commandline.Argument` Used for nested xml command line definitions.
`class` `Commandline.Marker` Class to keep track of the position of an Argument.

### Field Summary

Fields
`protected static java.lang.String` `DISCLAIMER`

### Constructor Summary

Constructors
`Commandline()` Create an empty command line.
`Commandline​(java.lang.String toProcess)` Create a command line from a string.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `addArguments​(java.lang.String[] line)` Append the arguments to the existing command.
`void` `addArgumentsToList​(java.util.ListIterator<java.lang.String> list)` Append all the arguments to the tail of a supplied list.
`void` `addCommandToList​(java.util.ListIterator<java.lang.String> list)` Add the entire command, including (optional) executable to a list.
`void` `clear()` Clear out the whole command line.
`void` `clearArgs()` Clear out the arguments but leave the executable in place for another operation.
`java.lang.Object` `clone()` Generate a deep clone of the contained object.
`Commandline.Argument` `createArgument()` Create an argument object.
`Commandline.Argument` `createArgument​(boolean insertAtStart)` Create an argument object and add it to our list of args.
`Commandline.Marker` `createMarker()` Return a marker.
`java.lang.String` `describeArguments()` Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
`static java.lang.String` `describeArguments​(java.lang.String[] args)` Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
`protected static java.lang.String` `describeArguments​(java.lang.String[] args, int offset)` Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
`static java.lang.String` `describeArguments​(Commandline line)` Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
`java.lang.String` `describeCommand()` Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
`static java.lang.String` `describeCommand​(java.lang.String[] args)` Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
`static java.lang.String` `describeCommand​(Commandline line)` Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
`java.lang.String[]` `getArguments()` Returns all arguments defined by `addLine`, `addValue` or the argument object.
`java.lang.String[]` `getCommandline()` Return the executable and all defined arguments.
`java.lang.String` `getExecutable()` Get the executable.
`java.util.Iterator<Commandline.Argument>` `iterator()` Get an iterator to the arguments list.
`static java.lang.String` `quoteArgument​(java.lang.String argument)` Put quotes around the given String if necessary.
`void` `setExecutable​(java.lang.String executable)` Set the executable to run.
`void` `setExecutable​(java.lang.String executable, boolean translateFileSeparator)` Set the executable to run.
`int` `size()` Size operator.
`java.lang.String` `toString()` Return the command line as a string.
`static java.lang.String` `toString​(java.lang.String[] line)` Quote the parts of the given array in way that makes them usable as command line arguments.
`static java.lang.String[]` `translateCommandline​(java.lang.String toProcess)` Crack a command line.

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

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

### Field Detail

#### DISCLAIMER

    protected static final java.lang.String DISCLAIMER

### Constructor Detail

#### Commandline

    public Commandline​(java.lang.String toProcess)

Create a command line from a string.

Parameters:
  `toProcess` - the line: the first element becomes the executable, the rest the arguments.

#### Commandline

    public Commandline()

Create an empty command line.

### Method Detail

#### createArgument

    public Commandline.Argument createArgument()

Create 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

    public Commandline.Argument createArgument​(boolean insertAtStart)

Create an argument object and add 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:
  an argument to be configured

#### setExecutable

    public void setExecutable​(java.lang.String executable)

Set the executable to run. All file separators in the string are converted to the platform specific value.

Parameters:
  `executable` - the String executable name.

#### setExecutable

    public void setExecutable​(java.lang.String executable,
                              boolean translateFileSeparator)

Set the executable to run.

Parameters:
  `executable` - the String executable name.
  `translateFileSeparator` - if `true` all file separators in the string are converted to the platform specific value.
Since:
  Ant 1.9.7

#### getExecutable

    public java.lang.String getExecutable()

Get the executable.

Returns:
  the program to run--null if not yet set.

#### addArguments

    public void addArguments​(java.lang.String[] line)

Append the arguments to the existing command.

Parameters:
  `line` - an array of arguments to append.

#### getCommandline

    public java.lang.String[] getCommandline()

Return the executable and all defined arguments.

Returns:
  the commandline as an array of strings.

#### addCommandToList

    public void addCommandToList​(java.util.ListIterator<java.lang.String> list)

Add the entire command, including (optional) executable to a list.

Parameters:
  `list` - the list to add to.
Since:
  Ant 1.6

#### getArguments

    public java.lang.String[] getArguments()

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

Returns:
  the arguments as an array of strings.

#### addArgumentsToList

    public void addArgumentsToList​(java.util.ListIterator<java.lang.String> list)

Append all the arguments to the tail of a supplied list.

Parameters:
  `list` - the list of arguments.
Since:
  Ant 1.6

#### toString

    public java.lang.String toString()

Return the command line as a string.

Overrides:
  `toString` in class `java.lang.Object`
Returns:
  the command line.

#### quoteArgument

    public static java.lang.String quoteArgument​(java.lang.String argument)

Put quotes around the given String if necessary.

If the argument doesn't include spaces or quotes, return it as is. If it contains double quotes, use single quotes - else surround the argument by double quotes.

Parameters:
  `argument` - the argument to quote if necessary.
Returns:
  the quoted argument.
Throws:
  `BuildException` - if the argument contains both, single and double quotes.

#### toString

    public static java.lang.String toString​(java.lang.String[] line)

Quote the parts of the given array in way that makes them usable as command line arguments.

Parameters:
  `line` - the list of arguments to quote.
Returns:
  empty string for null or no command, else every argument split by spaces and quoted by quoting rules.

#### translateCommandline

    public static java.lang.String[] translateCommandline​(java.lang.String toProcess)

Crack a command line.

Parameters:
  `toProcess` - the command line to process.
Returns:
  the command line broken into strings. An empty or null toProcess parameter results in a zero sized array.

#### size

    public int size()

Size operator. This actually creates the command line, so it is not a zero cost operation.

Returns:
  number of elements in the command, including the executable.

#### clone

    public java.lang.Object clone()

Generate a deep clone of the contained object.

Overrides:
  `clone` in class `java.lang.Object`
Returns:
  a clone of the contained 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()

Return a marker.

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

Returns:
  a marker

#### describeCommand

    public java.lang.String describeCommand()

Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.

Returns:
  a string that describes the command and arguments.
Since:
  Ant 1.5

#### describeArguments

    public java.lang.String describeArguments()

Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.

Returns:
  a string that describes the arguments.
Since:
  Ant 1.5

#### describeCommand

    public static java.lang.String describeCommand​(Commandline line)

Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.

Parameters:
  `line` - the Commandline to describe.
Returns:
  a string that describes the command and arguments.
Since:
  Ant 1.5

#### describeArguments

    public static java.lang.String describeArguments​(Commandline line)

Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.

Parameters:
  `line` - the Commandline whose arguments to describe.
Returns:
  a string that describes the arguments.
Since:
  Ant 1.5

#### describeCommand

    public static java.lang.String describeCommand​(java.lang.String[] args)

Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.

This method assumes that the first entry in the array is the executable to run.

Parameters:
  `args` - the command line to describe as an array of strings
Returns:
  a string that describes the command and arguments.
Since:
  Ant 1.5

#### describeArguments

    public static java.lang.String describeArguments​(java.lang.String[] args)

Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.

Parameters:
  `args` - the command line to describe as an array of strings.
Returns:
  a string that describes the arguments.
Since:
  Ant 1.5

#### describeArguments

    protected static java.lang.String describeArguments​(java.lang.String[] args,
                                                        int offset)

Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.

Parameters:
  `args` - the command line to describe as an array of strings.
  `offset` - ignore entries before this index.
Returns:
  a string that describes the arguments
Since:
  Ant 1.5

#### iterator

    public java.util.Iterator<Commandline.Argument> iterator()

Get an iterator to the arguments list.

Returns:
  an Iterator.
Since:
  Ant 1.7