org.apache.tools.ant.types

Class Commandline

Implemented Interfaces:
Cloneable

public class Commandline
extends java.lang.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

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

protected static String
DISCLAIMER

Constructor Summary

Commandline()
Create an empty command line
Commandline(String toProcess)
create a command line from a string

Method Summary

void
addArguments(String[] line)
append the arguments to the existing command
void
addArgumentsToList(ListIterator list)
append all the arguments to the tail of a supplied list
void
addCommandToList(ListIterator 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()
Creates an argument object.
Commandline.Argument
createArgument(boolean insertAtStart)
Creates an argument object and adds it to our list of args.
Commandline.Marker
createMarker()
Return a marker.
String
describeArguments()
Returns a String that describes the arguments suitable for verbose output before a call to Runtime.exec(String[])
static String
describeArguments(String[] args)
Returns 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)
Returns a String that describes the arguments suitable for verbose output before a call to Runtime.exec(String[])
static String
describeArguments(Commandline line)
Returns a String that describes the arguments suitable for verbose output before a call to Runtime.exec(String[])
String
describeCommand()
Returns a String that describes the command and arguments suitable for verbose output before a call to Runtime.exec(String[])
static String
describeCommand(String[] args)
Returns a String that describes the command and arguments suitable for verbose output before a call to Runtime.exec(String[]).
static String
describeCommand(Commandline line)
Returns 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()
Returns the executable and all defined arguments.
String
getExecutable()
get the executable
static String
quoteArgument(String argument)
Put quotes around the given String if necessary.
void
setExecutable(String executable)
Sets the executable to run.
int
size()
size operator.
String
toString()
stringify operator returns the command line as a string
static String
toString(String[] line)
Quotes 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

Field Details

DISCLAIMER

protected static final String DISCLAIMER

Constructor Details

Commandline

public Commandline()
Create an empty command line

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

Method Details

addArguments

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

addArgumentsToList

public void addArgumentsToList(ListIterator list)
append all the arguments to the tail of a supplied list
Parameters:
list -
Since:
Ant 1.6

addCommandToList

public void addCommandToList(ListIterator list)
add the entire command, including (optional) executable to a list
Parameters:
list -
Since:
Ant 1.6

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.

clone

public Object clone()
Generate a deep clone of the contained object.
Returns:
a clone of the contained object

createArgument

public Commandline.Argument createArgument()
Creates 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.

createArgument

public Commandline.Argument createArgument(boolean insertAtStart)
Creates an argument object and adds 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.

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.


describeArguments

public String describeArguments()
Returns a String that describes the arguments suitable for verbose output before a call to Runtime.exec(String[])
Since:
Ant 1.5

describeArguments

public static String describeArguments(String[] args)
Returns a String that describes the arguments suitable for verbose output before a call to Runtime.exec(String[])
Since:
Ant 1.5

describeArguments

protected static String describeArguments(String[] args,
                                          int offset)
Returns a String that describes the arguments suitable for verbose output before a call to Runtime.exec(String[])
Parameters:
offset - ignore entries before this index
Since:
Ant 1.5

describeArguments

public static String describeArguments(Commandline line)
Returns a String that describes the arguments suitable for verbose output before a call to Runtime.exec(String[])
Since:
Ant 1.5

describeCommand

public String describeCommand()
Returns a String that describes the command and arguments suitable for verbose output before a call to Runtime.exec(String[])
Since:
Ant 1.5

describeCommand

public static String describeCommand(String[] args)
Returns 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.

Since:
Ant 1.5

describeCommand

public static String describeCommand(Commandline line)
Returns a String that describes the command and arguments suitable for verbose output before a call to Runtime.exec(String[])
Since:
Ant 1.5

getArguments

public String[] getArguments()
Returns all arguments defined by addLine, addValue or the argument object.

getCommandline

public String[] getCommandline()
Returns the executable and all defined arguments.

getExecutable

public String getExecutable()
get the executable
Returns:
the program to run -null if not yet set

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.


setExecutable

public void setExecutable(String executable)
Sets the executable to run. All file separators in the string are converted to the platform specific value

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

toString

public String toString()
stringify operator returns the command line as a string
Returns:
the command line

toString

public static String toString(String[] line)
Quotes the parts of the given array in way that makes them usable as command line arguments.
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

Copyright © 2000-2006 Apache Software Foundation. All Rights Reserved.