Commandline (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.types, class: Commandline

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