Commandline (Apache Ant API)
Date: 2018-03-24

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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
    Modifier and Type | Method and 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(Commandline line)` 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[])`.
    `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(Commandline line)` 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[])`.
    `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