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
Modifier and Type | Class | Description
--- | --- | ---
`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
Modifier and Type | Field | Description
--- | --- | ---
`protected static java.lang.String` | `DISCLAIMER` |

## Constructor Summary

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

## Method Summary

Modifier and Type | Method | Description
--- | --- | ---
`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 Details

### DISCLAIMER

protected static final java.lang.String DISCLAIMER

## Constructor Details

### 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 Details

### 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