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