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.

  • 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