info.rolandkrueger.roklib.cli
Class CommandLineOption

java.lang.Object
  info.rolandkrueger.roklib.cli.CommandLineOption

public class CommandLineOption
extends Object

This class constitutes a single command line option that is managed by a CommandLineArgumentEvaluator. An option has several properties that can be configured through this class. An option can have the following properties:

• Long option name and short option name: There are two ways for the user to provide an option: either as a long option or as a short option. Both variants are equal. An example for that is --server for the long option and -s for the short option. Both variants are configured through the constructor of class CommandLineOption. It is possible to omit one of these variants if, for instance, only a long option should be available.
• Option type: Each option can be of one of the following types flag option, list option, or singular option. For more information about that see CommandLineOptionType.
• Mandatory vs. optional options: Some options can be marked as mandatory. In that case, the user is compelled to provide a value for that option. An example would be the target parameter for a copy command. If the user forgets to provide a value for a mandatory option, the CommandLineArgumentEvaluator will detect this. Note that it makes no sense to mark flag options as mandatory. Therefore, trying to do so will raise an unchecked exception.
• Default values: Non-mandatory options can be provided with default values. These values are set for the respective option if the user omits them on the command line. To set an option's default values, you can use one of the methods addDefaultValue(String) and addDefaultValues(String[]).

Creating CommandLineOption objects

Since class CommandLineOption is a public inner class, a special syntax has to be applied in order to create new instances of this class. To do so, you need an object of CommandLineOption's enclosing class CommandLineArgumentEvaluator. Say such an object is named evaluator. A new Option can then be created with

     Option option = evaluator.new Option (...);
 

Querying an CommandLineOption's status, i.e. the user input

After invoking method CommandLineArgumentEvaluator.evaluate(), the status of an option can be queried. That is, you can check whether the user's input is valid, which values she has provided for list and singular options, and which flag options she has used. To check if a flag option has been used, you can call method isSet(). To obtain the list of values that have been provided for a list or a singular option, method getInputList() can be used. This method will return a one-element list for singular options. A simple idiom for querying the user-provided value of a singular option is the following:

 Option singularOption;
 CommandLineArgumentEvaluator evaluator;
 // ...
 evaluator.evaluate ();
 // ...
 String value = singularOption.getInputList ()[0];
 

Author:

Roland Krueger

See Also:

CommandLineOptionType

Nested Class Summary

private static class

CommandLineOption.EmptyCallback

Field Summary

private Set<CommandLineOption>	mAssociateOptions Set of other option objects which must be provided in combination with this option.
private ICommandLineOptionCallback	mCallback
private boolean	mDefaultValueSet
private String	mDescription
private boolean	mIsSet
private String	mLongOptionName
private boolean	mMandatory
private Set<CommandLineOption>	mMutuallyExclusiveOptions List of other options which must not be provided together with this option.
private boolean	mRepetionsAllowed
private int	mRepetitionCount
private String	mShortOptionName
private CommandLineOptionType	mType
private List<String>	mValues

Constructor Summary

private	CommandLineOption() Private default constructor.
	CommandLineOption(Character shortOption, String longOption, CommandLineOptionType type, boolean mandatory) Constructor for creating a CommandLineOption without a description.
	CommandLineOption(Character shortOption, String longOption, String description, CommandLineOptionType type)
	CommandLineOption(Character shortOption, String longOption, String description, CommandLineOptionType type, boolean mandatory)
	CommandLineOption(Character shortOption, String longOption, String description, CommandLineOptionType type, boolean mandatory, ICommandLineOptionCallback callback) Constructor.

Method Summary

void	addAssociateOptions(CommandLineOption... associates)
void	addDefaultValue(String defaultValue) Adds a default value for this option.
void	addDefaultValues(String... values) Adds a list of values to the default values of this option.
void	addMutuallyExclusiveOptions(CommandLineOption... otherOptions)
protected boolean	addUserInput(String input)
void	allowOptionRepetition(boolean yesNo)
boolean	equals(Object obj)
String	getDescription() Returns the description of this option as provided through the constructor.
String[]	getInputList() Returns the list of values that have been provided by the user for an option.
String	getLongOption() Returns the option name's long version.
int	getRepetitionCount()
String	getShortOption() Returns the option name's short version.
String	getSingleParameterValue()
CommandLineOptionType	getType()
int	hashCode()
void	increaseRepetitions()
protected void	invokeCallback(CommandLineArgumentEvaluator source)
boolean	isAssociateTo(CommandLineOption otherOption)
boolean	isFlag() Checks whether this option is a flag option.
boolean	isMandatory() Returns whether this option is mandatory or optional.
boolean	isMutuallyExclusiveWith(CommandLineOption otherOption)
boolean	isOptionRepetitionAllowed()
boolean	isSet() Checks whether the option was used on the command line.
protected void	set() Mark this option as set.
void	setCallback(ICommandLineOptionCallback callback)
void	setMandatory(boolean mandatory)
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

mShortOptionName

private String mShortOptionName

mLongOptionName

private String mLongOptionName

mDescription

private String mDescription

mType

private CommandLineOptionType mType

mIsSet

private boolean mIsSet

mMandatory

private boolean mMandatory

mDefaultValueSet

private boolean mDefaultValueSet

mValues

private List<String> mValues

mRepetionsAllowed

private boolean mRepetionsAllowed

mRepetitionCount

private int mRepetitionCount

mMutuallyExclusiveOptions

private Set<CommandLineOption> mMutuallyExclusiveOptions

List of other options which must not be provided together with this option.

mAssociateOptions

private Set<CommandLineOption> mAssociateOptions

Set of other option objects which must be provided in combination with this option.

mCallback

private ICommandLineOptionCallback mCallback

Constructor Detail

CommandLineOption

public CommandLineOption(Character shortOption,
                         String longOption,
                         String description,
                         CommandLineOptionType type,
                         boolean mandatory,
                         ICommandLineOptionCallback callback)

Constructor.

Parameters:

shortOption - short version of the option name. For example, -s

longOption - long version of the option name. For example, --server_address

description - short description for the option. This description will be used for assembling a help message by method CommandLineArgumentEvaluator.getOptionDescription().

type - type of the option. An option can be a flag option, a singular option, or a list option.

mandatory - true if the option is mandatory. Is only allowed for list and singular options

Throws:

IllegalArgumentException - either if an option was both configured to be a flag option and mandatory or if both short and long option name were left blank

CommandLineOption

public CommandLineOption(Character shortOption,
                         String longOption,
                         String description,
                         CommandLineOptionType type)

CommandLineOption

public CommandLineOption(Character shortOption,
                         String longOption,
                         String description,
                         CommandLineOptionType type,
                         boolean mandatory)

CommandLineOption

private CommandLineOption()

Private default constructor.

CommandLineOption

public CommandLineOption(Character shortOption,
                         String longOption,
                         CommandLineOptionType type,
                         boolean mandatory)

Constructor for creating a CommandLineOption without a description.

Method Detail

setCallback

public void setCallback(ICommandLineOptionCallback callback)

allowOptionRepetition

public void allowOptionRepetition(boolean yesNo)

setMandatory

public void setMandatory(boolean mandatory)

isOptionRepetitionAllowed

public boolean isOptionRepetitionAllowed()

isFlag

public boolean isFlag()

Checks whether this option is a flag option.

Returns:

true if this option was configured as a flag option

invokeCallback

protected void invokeCallback(CommandLineArgumentEvaluator source)

isSet

public boolean isSet()

Checks whether the option was used on the command line. This is useful for both flag options and non-mandatory options. Mandatory options that haven't been provided by the user can be queried with CommandLineArgumentEvaluator.getMissingOptions().

Returns:

true if the option was used by the user on the command line.

addAssociateOptions

public void addAssociateOptions(CommandLineOption... associates)

addMutuallyExclusiveOptions

public void addMutuallyExclusiveOptions(CommandLineOption... otherOptions)

isMutuallyExclusiveWith

public boolean isMutuallyExclusiveWith(CommandLineOption otherOption)

isAssociateTo

public boolean isAssociateTo(CommandLineOption otherOption)

getInputList

public String[] getInputList()

Returns the list of values that have been provided by the user for an option. If this CommandLineOption object is a singular option, the returned list has exactly one element.

Returns:

the list of values that have been provided by the user for an option or null if there aren't any values for this option

getSingleParameterValue

public String getSingleParameterValue()

set

protected void set()

Mark this option as set.

isMandatory

public boolean isMandatory()

Returns whether this option is mandatory or optional.

Returns:

true if this option is marked as mandatory

addUserInput

protected boolean addUserInput(String input)

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

getDescription

public String getDescription()

Returns the description of this option as provided through the constructor.

Returns:

the description of this option.

addDefaultValue

public void addDefaultValue(String defaultValue)

Adds a default value for this option. Every non-mandatory CommandLineOption object maintains a list of default values. If the user has omitted an option on the command line, querying the option with getInputList() will yield its default values. Additionally, each option with default values will return true wenn invoking its isSet() method.

Repeated calls to addDefaultValue(String) will add each provided value to the list of default values for list options. This is not the case for singular options. Here, only the value provided with the last call to addDefaultValue(String) will be used as the only default value.

Note that default values should usually be set before evaluating the command line arguments with CommandLineArgumentEvaluator.evaluate() . Otherwise the actual data provided by the user will be overwritten for singular options or the default values will be added to the user's data for list options, respectively.

Parameters:

defaultValue - the default value to be added

Throws:

IllegalStateException - if this option is either a flag option (which aren't meant to be provided with a value by definition) or a mandatory option (where the user is forced to provide a value himself).

addDefaultValues

public void addDefaultValues(String... values)

Adds a list of values to the default values of this option. For singular options, this list must not contain more than one element.

Parameters:

values - list of default values

Throws:

UnsupportedOperationException - if this option is a flag option or if the passed values list has more than one element for singular options

See Also:

addDefaultValue(String)

getLongOption

public String getLongOption()

Returns the option name's long version.

Returns:

the option name's long version

getShortOption

public String getShortOption()

Returns the option name's short version.

Returns:

the option name's short version

getType

public CommandLineOptionType getType()

increaseRepetitions

public void increaseRepetitions()

getRepetitionCount

public int getRepetitionCount()

toString

public String toString()

Overrides:

toString in class Object