org.pfsw.text

Class CommandLineArguments

java.lang.Object

org.pfsw.text.CommandLineArguments

public class CommandLineArguments
extends java.lang.Object

Utility class for easy evaluation of command line arguments.

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	DEFAULT_SWITCH_INDICATOR
protected static java.lang.String	QUOTE
protected static java.lang.String	STRING_DELIMITER

Constructor Summary

Constructors

Modifier	Constructor and Description
	CommandLineArguments() Initialize the new instance with no arguments.
	CommandLineArguments(boolean switchAndValuesMustBeSeparated) Initialize the new instance to handle arguments with separated option flag and option value.
	CommandLineArguments(java.lang.String[] args) Initialize the new instance with an array of arguments.
	CommandLineArguments(java.lang.String[] args, boolean switchAndValuesMustBeSeparated) Initialize the new instance with an array of arguments.
	CommandLineArguments(java.lang.String[] args, java.lang.String switchIndicator) Initialize the new instance with an array of arguments and a prefix indicator for options.
	CommandLineArguments(java.lang.String[] args, java.lang.String switchIndicator, boolean switchAndValuesMustBeSeparated) Initialize the new instance with an array of arguments and a prefix indicator for options.
protected	CommandLineArguments(java.lang.String[] args, java.lang.String switchIndicator, boolean switchAndValuesMustBeSeparated, boolean supportQuotedArguments) Initialize the new instance with an array of arguments and a prefix indicator for options.

Method Summary

Modifier and Type	Method and Description
void	addOption(java.lang.String option) Adds the given option to the command line.
void	addOptionWithArgument(java.lang.String option, java.lang.String argument) Adds the given option to the command line.
protected void	addOptionWithValue(java.util.Map<java.lang.String,java.lang.String[]> map, java.lang.String option, java.lang.String value)
protected void	addOptionWithValues(java.util.Map<java.lang.String,java.lang.String[]> map, java.lang.String option, java.util.List<java.lang.String> values)
protected java.lang.String[]	arguments()
protected void	arguments(java.lang.String[] newValue)
boolean	containsAny(java.lang.String... argNames) Returns true one of the given argument names has been specified on the command line.
boolean	containsArgument(java.lang.String argName) Returns whether or not the given argument was specified in the command line.
CommandLineArguments	copy() Returns a copy of this object, with all internal state being the same as in the original.
protected java.lang.String[]	copyOfArguments() Returns a copy of the original arguments.
static CommandLineArguments	create(java.lang.String... options) Convenience method with varargs to create a new instance.
protected java.lang.String	findOptionValue(java.lang.String option)
protected java.lang.String[]	findValues(java.lang.String option)
java.lang.String	getArgumentAt(int index) Returns the argument at the specified index or null if the index is outside the bounds of the argument list.
java.lang.String[]	getArguments() Returns a string array containing all arguments.
java.lang.String	getArgumentValue(java.lang.String option) Returns the value following the specified option.
java.lang.String	getArgumentValue(java.lang.String option, java.lang.String defaultValue) Returns the value following the specified option.
java.lang.String[]	getArgumentValues(java.lang.String option) Returns all values that are found for the specified option.
java.lang.String[]	getArgumentValues(java.lang.String option, java.lang.String... defaultValues) Returns the values following the specified option.
java.lang.String	getFirstFoundValue(java.lang.String... options) Returns the value following the first option found that matches one of the specified options.
protected java.util.Map<java.lang.String,java.lang.String[]>	getOptionsWithValues()
java.lang.String[]	getOptionValues(java.lang.String option) Returns all values after the given option which do NOT start with the configured switch indicator.
boolean	getSupportQuotedArguments() Returns whether or not quoted arguments are supported.
protected boolean	getSwitchAndValuesMustBeSeparated()
java.lang.String	getSwitchIndicator() Returns the prefix which must proceed each command line switch (option).
protected void	init()
boolean	isEmpty() Returns true if no argument is set.
protected boolean	isOption(java.lang.String arg)
boolean	isOptionSet(java.lang.String option) Returns whether or not the specified option is set in the command line arguments.
void	removeOption(java.lang.String option) Remove the specified option from the command line arguments.
void	removeOptionWithArgument(java.lang.String option) Remove the specified option from the command line arguments.
protected void	setOptionsWithValues(java.util.Map<java.lang.String,java.lang.String[]> newValue)
void	setSupportQuotedArguments(boolean supportThem) Defines whether or not quoted arguments are supported.
protected void	setSwitchAndValuesMustBeSeparated(boolean newValue)
void	setSwitchIndicator(java.lang.String newValue) Sets the prefix which must proceed each command line switch.
int	size() Returns the current number of argument
protected StringUtil	strUtil()
protected java.lang.String	switchIndicator()
protected void	switchIndicator(java.lang.String newValue)
java.lang.String	toString() Returns a String with all arguments separated by blanks
protected java.lang.String	unquoted(java.lang.String value)
protected java.lang.String	unquotedIfSupported(java.lang.String value)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

STRING_DELIMITER

protected static final java.lang.String STRING_DELIMITER

See Also:

Constant Field Values

DEFAULT_SWITCH_INDICATOR

protected static final java.lang.String DEFAULT_SWITCH_INDICATOR

See Also:

Constant Field Values

QUOTE

protected static final java.lang.String QUOTE

See Also:

Constant Field Values

Constructor Detail

CommandLineArguments

public CommandLineArguments()

Initialize the new instance with no arguments.

CommandLineArguments

public CommandLineArguments(boolean switchAndValuesMustBeSeparated)

Initialize the new instance to handle arguments with separated option flag and option value.

Parameters:

switchAndValuesMustBeSeparated - If true no switches with length > 2 will be treated as a one character option switch plus the remaining string as its value.

CommandLineArguments

public CommandLineArguments(java.lang.String[] args)

Initialize the new instance with an array of arguments.

Parameters:

args - The arguments of the command line

CommandLineArguments

public CommandLineArguments(java.lang.String[] args,
                            boolean switchAndValuesMustBeSeparated)

Initialize the new instance with an array of arguments.

Parameters:

args - The arguments of the command line

switchAndValuesMustBeSeparated - If true no switches with length > 2 will be treated as a one character option switch plus the remaining string as its value.

CommandLineArguments

public CommandLineArguments(java.lang.String[] args,
                            java.lang.String switchIndicator)

Initialize the new instance with an array of arguments and a prefix indicator for options.

Parameters:

args - The arguments of the command line

switchIndicator - A prefix for options

CommandLineArguments

public CommandLineArguments(java.lang.String[] args,
                            java.lang.String switchIndicator,
                            boolean switchAndValuesMustBeSeparated)

Initialize the new instance with an array of arguments and a prefix indicator for options.

Parameters:

args - The arguments of the command line

switchIndicator - A prefix for options

switchAndValuesMustBeSeparated - If true no switches with length > 2 will be treated as a one character option switch plus the remaining string as its value.

CommandLineArguments

protected CommandLineArguments(java.lang.String[] args,
                               java.lang.String switchIndicator,
                               boolean switchAndValuesMustBeSeparated,
                               boolean supportQuotedArguments)

Initialize the new instance with an array of arguments and a prefix indicator for options.

Parameters:

args - The arguments of the command line

switchIndicator - A prefix for options

switchAndValuesMustBeSeparated - If true no switches with length > 2 will be treated as a one character option switch plus the remaining string as its value.

supportQuotedArguments - Handle wildcard patterns enclosed in quotes.

Method Detail

create

public static CommandLineArguments create(java.lang.String... options)

Convenience method with varargs to create a new instance.

Parameters:

options - The options to be used as arguments.

Returns:

A new instance of CommandLineArguments initialized with the specified options.

toString

public java.lang.String toString()

Returns a String with all arguments separated by blanks

Overrides:

toString in class java.lang.Object

isOptionSet

public boolean isOptionSet(java.lang.String option)

Returns whether or not the specified option is set in the command line arguments. The search for the option is case-sensitive.

Examples:

boolean append = commandLine.isOptionSet( "-a" ) ;
boolean move = commandLine.isOptionSet( "/move" ) ;

Parameters:

option - The option to be looked for

Throws:

java.lang.IllegalArgumentException - If the given option is null

containsArgument

public boolean containsArgument(java.lang.String argName)

Returns whether or not the given argument was specified in the command line. The search for the option is case-sensitive.

Examples:

commandLine = new CommandLineArguments("-a -f file.txt"); boolean append = commandLine.containsArgument( "-a" ) ;
boolean move = commandLine.containsArgument( "-f" ) ; boolean file = commandLine.containsArgument( "file.txt" ) ;

Parameters:

argName - The name of the argument to look for

Throws:

java.lang.IllegalArgumentException - If the given argName is null

containsAny

public boolean containsAny(java.lang.String... argNames)

Returns true one of the given argument names has been specified on the command line.

getArgumentValue

public java.lang.String getArgumentValue(java.lang.String option,
                                         java.lang.String defaultValue)

Returns the value following the specified option. Returns the given default value if the specified option doesn't occur at all in the arguments array.
For more details see getArgumentValue(String).

Parameters:

option - The option which indicates that the next argument is the desired value

defaultValue - The default value to return if the option is not found

Throws:

java.lang.IllegalArgumentException - If the given option is null

getArgumentValue

public java.lang.String getArgumentValue(java.lang.String option)

Returns the value following the specified option. Returns null if the specified option doesn't occur at all in the arguments array.
An empty String will be returned if the option is followed by another option (detected by the switchIndicator prefix) or no further argument follows the specified option.
If an argument exists that starts with the given option name then the rest of the argument is returned as the option's value.

Examples:

Arguments: -v -f sample.xml -t
getArgumentValue( "-f" ) returns "sample.xml"

Arguments: -v -m -t
getArgumentValue( "-f" ) returns null

Arguments: -v -t -f
getArgumentValue( "-f" ) returns ""

Arguments: -v -f -t sample.xml
getArgumentValue( "-f" ) returns ""

Arguments: -v -x2000 -t
getArgumentValue( "-x" ) returns "2000"

Arguments: -v"first draft" -x -t
getArgumentValue( "-v" ) returns "first draft"

Parameters:

option - The option which indicates that the next argument is the desired value

Throws:

java.lang.IllegalArgumentException - If the given option is null.

getFirstFoundValue

public java.lang.String getFirstFoundValue(java.lang.String... options)

Returns the value following the first option found that matches one of the specified options. Returns null if none of the specified options occurs at all in the arguments.
An empty String will be returned if the found option is followed by another option (detected by the switchIndicator prefix) or no further argument follows the specified option.

Parameters:

options - The option which indicates that the next argument is the desired value

Throws:

java.lang.IllegalArgumentException - If no option is specified.

getArgumentValues

public java.lang.String[] getArgumentValues(java.lang.String option)

Returns all values that are found for the specified option. Helps to collect all values for options that can be used more than once.

Example:
Arguments: -v -x2000 -t -x 120 -xFM
getArgumentValues( "-x" ) returns { "2000", "120", "FM" }

Parameters:

option - The option which is the prefix for the desired values

Throws:

java.lang.IllegalArgumentException - If the given option is null

getArgumentValues

public java.lang.String[] getArgumentValues(java.lang.String option,
                                            java.lang.String... defaultValues)

Returns the values following the specified option. Returns the given default values if the specified option doesn't occur at all in the arguments array.
For more details see getArgumentValue(String, String).

Parameters:

option - The option which indicates that the next arguments are the desired values

defaultValues - The default values to return if the option is not found

Throws:

java.lang.IllegalArgumentException - If the given option is null

getOptionValues

public java.lang.String[] getOptionValues(java.lang.String option)

Returns all values after the given option which do NOT start with the configured switch indicator. Returns null if the specified option doesn't occur at all in the arguments array.

Example:
Arguments: -v -x 2000 south 30 west -t -f test.txt -Uc22
getOptionValues( "-x" ) returns { "2000", "south", "30", "west }
getOptionValues( "-v" ) returns String[0]
getOptionValues( "-f" ) returns { "test.txt" }
getOptionValues( "-M" ) returns null

Parameters:

option - The option which is the prefix for the desired values

Throws:

java.lang.IllegalArgumentException - If the given option is null

addOption

public void addOption(java.lang.String option)

Adds the given option to the command line. If it is already set it is not added a second time.

Parameters:

option - An option including the switch indicator if necessary (e.g. "-x")

Throws:

java.lang.IllegalArgumentException - If the given option is null

addOptionWithArgument

public void addOptionWithArgument(java.lang.String option,
                                  java.lang.String argument)

Adds the given option to the command line. If it is already set it is not added a second time.

Parameters:

option - An option including the switch indicator if necessary (e.g. "-x")

argument - The argument of the option

Throws:

java.lang.IllegalArgumentException - If the given option or argument is null

removeOption

public void removeOption(java.lang.String option)

Remove the specified option from the command line arguments.

Parameters:

option - The option to be removed

removeOptionWithArgument

public void removeOptionWithArgument(java.lang.String option)

Remove the specified option from the command line arguments. If there's an argument following the option, it will be removed as well.

Parameters:

option - The option to be removed

copy

public CommandLineArguments copy()

Returns a copy of this object, with all internal state being the same as in the original.

getSwitchIndicator

public java.lang.String getSwitchIndicator()

Returns the prefix which must proceed each command line switch (option). The default value is "-".

setSwitchIndicator

public void setSwitchIndicator(java.lang.String newValue)

Sets the prefix which must proceed each command line switch. For example to change to Windows style call setSwitchIndicator( "/" )

size

public int size()

Returns the current number of argument

isEmpty

public boolean isEmpty()

Returns true if no argument is set.

getArguments

public java.lang.String[] getArguments()

Returns a string array containing all arguments. The array will be a copy, so modifications of that array will not alter any argument in this object.

getArgumentAt

public java.lang.String getArgumentAt(int index)

Returns the argument at the specified index or null if the index is outside the bounds of the argument list.

getSupportQuotedArguments

public boolean getSupportQuotedArguments()

Returns whether or not quoted arguments are supported. The default if not explicitly set is: false.

If true, arguments starting and ending with a single quote "'" will be stripped off these delimiters. This is useful to allow arguments with wildcard characters like '*.*'. Without the quotes such patterns might be resolved by the OS (e.g. Windows) to filenames which are then passed as arguments to the Java program.

setSupportQuotedArguments

public void setSupportQuotedArguments(boolean supportThem)

Defines whether or not quoted arguments are supported.

If true, arguments starting and ending with a single quote "'" will be stripped off these delimiters. This is useful to allow arguments with wildcard characters like '*.*'. Without the quotes such patterns might be resolved by the OS (e.g. Windows) to filenames which are then passed as arguments to the Java program.

init

protected void init()

addOptionWithValue

protected void addOptionWithValue(java.util.Map<java.lang.String,java.lang.String[]> map,
                                  java.lang.String option,
                                  java.lang.String value)

addOptionWithValues

protected void addOptionWithValues(java.util.Map<java.lang.String,java.lang.String[]> map,
                                   java.lang.String option,
                                   java.util.List<java.lang.String> values)

isOption

protected boolean isOption(java.lang.String arg)

findOptionValue

protected java.lang.String findOptionValue(java.lang.String option)

findValues

protected java.lang.String[] findValues(java.lang.String option)

copyOfArguments

protected java.lang.String[] copyOfArguments()

Returns a copy of the original arguments. If supportQuotedArguments is true the quotes will be removed in the returned array.

unquotedIfSupported

protected java.lang.String unquotedIfSupported(java.lang.String value)

unquoted

protected java.lang.String unquoted(java.lang.String value)

arguments

protected java.lang.String[] arguments()

arguments

protected void arguments(java.lang.String[] newValue)

switchIndicator

protected java.lang.String switchIndicator()

switchIndicator

protected void switchIndicator(java.lang.String newValue)

getOptionsWithValues

protected java.util.Map<java.lang.String,java.lang.String[]> getOptionsWithValues()

setOptionsWithValues

protected void setOptionsWithValues(java.util.Map<java.lang.String,java.lang.String[]> newValue)

getSwitchAndValuesMustBeSeparated

protected boolean getSwitchAndValuesMustBeSeparated()

setSwitchAndValuesMustBeSeparated

protected void setSwitchAndValuesMustBeSeparated(boolean newValue)

strUtil

protected StringUtil strUtil()