Commandline (Apache Ant API)

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