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:
  `Cloneable`

public class Commandline extends Object implements 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 String`
  `DISCLAIMER`

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addArguments​(String[] line)`
  Append the arguments to the existing command.
  `void`
  `addArgumentsToList​(ListIterator<String> list)`
  Append all the arguments to the tail of a supplied list.
  `void`
  `addCommandToList​(ListIterator<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.
  `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.
  `String`
  `describeArguments()`
  Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
  `static String`
  `describeArguments​(String[] args)`
  Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
  `protected static String`
  `describeArguments​(String[] args, int offset)`
  Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
  `static String`
  `describeArguments​(Commandline line)`
  Return a String that describes the arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
  `String`
  `describeCommand()`
  Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
  `static String`
  `describeCommand​(String[] args)`
  Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
  `static String`
  `describeCommand​(Commandline line)`
  Return a String that describes the command and arguments suitable for verbose output before a call to `Runtime.exec(String[])`.
  `String[]`
  `getArguments()`
  Returns all arguments defined by `addLine`, `addValue` or the argument object.
  `String[]`
  `getCommandline()`
  Return the executable and all defined arguments.
  `String`
  `getExecutable()`
  Get the executable.
  `Iterator<Commandline.Argument>`
  `iterator()`
  Get an iterator to the arguments list.
  `static String`
  `quoteArgument​(String argument)`
  Put quotes around the given String if necessary.
  `void`
  `setExecutable​(String executable)`
  Set the executable to run.
  `void`
  `setExecutable​(String executable, boolean translateFileSeparator)`
  Set the executable to run.
  `int`
  `size()`
  Size operator.
  `String`
  `toString()`
  Return the command line as a string.
  `static String`
  `toString​(String[] line)`
  Quote the parts of the given array in way that makes them usable as command line arguments.
  `static String[]`
  `translateCommandline​(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 String DISCLAIMER

- ## Constructor Details

  - ### Commandline

    public Commandline​(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​(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​(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 String getExecutable()
    Get the executable.
    Returns:
      the program to run--null if not yet set.

  - ### addArguments

    public void addArguments​(String[] line)
    Append the arguments to the existing command.
    Parameters:
      `line` - an array of arguments to append.

  - ### getCommandline

    public String[] getCommandline()
    Return the executable and all defined arguments.
    Returns:
      the commandline as an array of strings.

  - ### addCommandToList

    public void addCommandToList​(ListIterator<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 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​(ListIterator<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 String toString()
    Return the command line as a string.
    Overrides:
      `toString` in class `Object`
    Returns:
      the command line.

  - ### quoteArgument

    public static String quoteArgument​(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 String toString​(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 String[] translateCommandline​(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 Object clone()
    Generate a deep clone of the contained object.
    Overrides:
      `clone` in class `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 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 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 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 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 String describeCommand​(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 String describeArguments​(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 String describeArguments​(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 Iterator<Commandline.Argument> iterator()
    Get an iterator to the arguments list.
    Returns:
      an Iterator.
    Since:
      Ant 1.7