org.sadun.util
Class CmdLineOptions

java.lang.Object
  org.sadun.util.CmdLineOptions

public class CmdLineOptions

extends java.lang.Object

A class to handle command line options.

Client code either uses the setObjectOnOption() and/or setOnOption methods; or subclasses CmdLineOptions.Handler by implementing a method with signature

    public void option(String option, CmdLineOptions.Handler.ParamSet ps, boolean value);
 

with callback code for each option and registers the subclasses with an instance of this class.

Invoking the parse() method examines the command line and executes the callback code.

An option may be given a priority (the default priority is 0). When parsing arguments with parse(String[], String), options with higher priorities will be handled first.

Other features are the possibility of definining option aliases, option descriptions an automatic usage printout build up over this information.

Version:

1.7.1

Author:

Cristiano Sadun

Nested Class Summary

static class	CmdLineOptions.ChainedHandler A chained handler: executes two handlers one after the other.
static interface	CmdLineOptions.DefaultsStreamParser Objects implementing this interface translate an input stream into a map of default values per options for the CmdLineOptions#useDefaultStream(InputStream, DefaultsStreamParser) method of CmdLineOptions.
static class	CmdLineOptions.Handler This class handles an option and can be subclassed to define the reaction to the discovery of an option.
class	CmdLineOptions.OptionException A base class for options-related exceptions.
static class	CmdLineOptions.PropertiesFileParser A CmdLineOptions.DefaultsStreamParser which interprets the stream as coming from a Properties file.
static class	CmdLineOptions.Resources String resources for OptionException messages.

Constructor Summary

CmdLineOptions()
Build an handler which recognizes options with the "-" prefix, allows only plain options, and fails if an option is not recognized.

CmdLineOptions(boolean allowNegatedOptions)
Build an handler which recognizes options with the "-" prefix, specifies whether to allow or no the negation of options(by using +/- after the option itself), and fails if an option is not recognized.

CmdLineOptions(boolean allowNegatedOptions, java.lang.String optPrefix)
Build an handler which recognizes options with the given prefix, specifies whether to allow or no the negation of options(by using +/- after the option itself), and fails if an option is not recognized.

CmdLineOptions(boolean allowNegatedOptions, java.lang.String optPrefix, boolean failOnUnrecognizedOption)
Build an handler which recognizes options with the given prefix and specifies whether to allow or no the negation of options(by using +/- after the option itself).

CmdLineOptions(java.lang.String usageDescription)
Build an handler which recognizes options with the "-" prefix, allows only plain options, and fails if an option is not recognized.

CmdLineOptions(java.lang.String usageDescription, boolean allowNegatedOptions)
Build an handler which recognizes options with the "-" prefix, specifies whether to allow or no the negation of options(by using +/- after the option itself), and fails if an option is not recognized.

CmdLineOptions(java.lang.String usageDescription, boolean allowNegatedOptions, java.lang.String optPrefix)
Build an handler which recognizes options with the given prefix, specifies whether to allow or no the negation of options(by using +/- after the option itself), and fails if an option is not recognized.

CmdLineOptions(java.lang.String usageDescription, boolean allowNegatedOptions, java.lang.String optPrefix, boolean failOnUnrecognizedOption)
Build an handler with the given usage description, which recognizes options with the given prefix and specifies whether to allow or no the negation of options(by using +/- after the option itself).

Method Summary

void	addAliases(java.lang.String aliases) Add aliases to the last accessed option
void	addAliases(java.lang.String option, java.lang.String aliases) Adds aliases for a given option.
java.lang.String	getDescription(java.lang.String option) Retrieve the description for a given option.
java.lang.String	getHelpOption() Return the current help option See setHelpOption() or null if no help option is set.
CmdLineOptions.Handler.ParamSet	hasOption(java.lang.String opt, java.lang.String[] args) Return the set of parameters of the given option.
boolean	isFailOnMixedHelpOptionEncountered() Return the value for the 'failOnMixedHelpOptionEncountered' flag.
boolean	isFailOnUnrecognizedOption() Return the failOnUnrecognizedOption.
boolean	isMandatory(java.lang.String option) Returns the mandatory state of the given option.
boolean	isPrintUsageOnException()
static boolean	isSortUsageOnPriority() Return whether or not options are sorted also considering priority (besides alphabetical order) when usage() is called.
java.lang.String[]	parse(java.lang.String[] args) Parse the cmdline arguments (usually received by main) looking for the options managed by the handler.
java.lang.String[]	parse(java.lang.String[] _args, java.lang.String context) Parses the cmdline arguments (usually received by main) looking for the options managed by the handler.
void	registerHandler(CmdLineOptions.Handler handler) Registers an handler.
void	setActionOnParse(java.lang.Runnable action) For non-user defined handlers, set an action to be executed when the last created option is parsed.
void	setActionOnParse(java.lang.String option, java.lang.Runnable action) For non-user defined handlers, set an action to be executed when the option is parsed.
void	setAlternativeMandatory(java.lang.String[] options) Sets up a group of options, for which already exist handlers, as mutually exclusive and where at least one is mandatory.
void	setAlternativeMandatory(java.lang.String[] options, boolean mandatory) Sets/removes the mandatory state of a group of mutually exclusive options, for which already exist handlers, where at least one is mandatory.
void	setAlternativeMandatoryOnOption(java.lang.String options, java.lang.String optionsToSet) Specifies that one among the given options set become mandatory only if one option is encountered.
void	setAlternativeMandatoryOnOption(java.lang.String options, java.lang.String[] optionsToSet) Specifies that one among the given options set become mandatory only if one option is encountered.
void	setAlternativeMandatoryOnOptions(java.lang.String options, java.lang.String optionsToSet) Specifies that one among the given options set become mandatory only if one in another set of options is encountered.
void	setAlternativeMandatoryOnOptions(java.lang.String options, java.lang.String[] optionsToSet) Specifies that one among the given options set become mandatory only if one in another set of options is encountered.
void	setDescription(java.lang.String description) Set the description for the last accessed option
void	setDescription(java.lang.String option, java.lang.String description) Sets the description for a given option.
void	setFailOnMixedHelpOptionEncountered(boolean failOnMixedHelpOptionEncountered) Set the value for the 'failOnMixedHelpOptionEncountered' flag.
void	setFailOnUnrecognizedOption(boolean failOnUnrecognizedOption) Set the failOnUnrecognizedOption.
void	setHelpOption()
void	setHelpOption(java.lang.String option) Set the given option an help option.
void	setHelpOption(java.lang.String option, boolean value) Set/unset an option as the "help option".
void	setMandatory() Set the last accessed option as mandatory.
void	setMandatory(boolean mandatory) Set or unset the 'mandatory' state of the last accessed option.
void	setMandatory(java.lang.String option) Set an option as mandatory.
void	setMandatory(java.lang.String option, boolean mandatory) Set or unset the 'mandatory' state of an option.
void	setMandatoryOnOption(java.lang.String option, java.lang.String optionsToSet) Specifies that the given options set are mandatory only if one other option is encountered.
void	setMandatoryOnOption(java.lang.String option, java.lang.String[] optionsToSet) Specifies that all the options in the given set become mandatory only if one other option is encountered
void	setMandatoryOnOptions(java.lang.String options, java.lang.String optionsToSet) Specifies that the given options set are mandatory only if one in another set of options is encountered.
void	setMandatoryOnOptions(java.lang.String options, java.lang.String[] optionsToSet) Specifies that the given options set are mandatory only if one in another set of options is encountered.
void	setObjectOnOption(java.lang.String option, java.lang.Object target) Registers an handler which sets a member variable (of Object type) of on the target object when encountered, having the same name as the option, and no default value (null).
void	setObjectOnOption(java.lang.String option, java.lang.Object target, java.lang.Object defaultValue) Registers an handler which sets a member variable (of Object type) of on the target object when encountered, having the same name as the option.
void	setObjectOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, java.lang.Object defaultValue) Registers an handler which sets a member variable (of Object type) on the target object when encountered.
void	setObjectOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, java.lang.Object defaultValue, boolean defaultOnly) Registers an handler which sets a member variable (of Object type) of the target object when found (without defining any description nor aliases).
void	setObjectOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, java.lang.Object defaultValue, boolean defaultOnly) Registers an handler which sets a member variable (of Object type) of on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target) Registers an handler which sets a member variable of String type, on the target object when encountered, having the same name as the option.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName) Registers an handler which sets a member variable of String type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, boolean defaultValue) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, boolean defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, byte defaultValue) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, byte defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, char defaultValue) Registers an handler which sets a member variable of char primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, char defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of char primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, double defaultValue) Registers an handler which sets a member variable of double primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, double defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of double primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, float defaultValue) Registers an handler which sets a member variable of float primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, float defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of float primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, int defaultValue) Registers an handler which sets a member variable of int primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, int defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of int primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, long defaultValue) Registers an handler which sets a member variable of long primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, long defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of long primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, short defaultValue) Registers an handler which sets a member variable of short primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, short defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of short primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, java.lang.String defaultValue) Registers an handler which sets a member variable of String type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.Object target, java.lang.String memberName, java.lang.String defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, boolean defaultValue) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, boolean defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, byte defaultValue) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, byte defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, char defaultValue) Registers an handler which sets a member variable of char primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, char defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of char primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, double defaultValue) Registers an handler which sets a member variable of double primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, double defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of double primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, float defaultValue) Registers an handler which sets a member variable of float primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, float defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of float primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, int defaultValue) Registers an handler which sets a member variable of int primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, int defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of int primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, long defaultValue) Registers an handler which sets a member variable of long primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, long defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of long primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, short defaultValue) Registers an handler which sets a member variable of short primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, short defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of short primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, java.lang.String defaultValue) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, java.lang.String defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, boolean defaultValue) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, boolean defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, byte defaultValue) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, byte defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, char defaultValue) Registers an handler which sets a member variable of char primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, char defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of char primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, double defaultValue) Registers an handler which sets a member variable of double primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, double defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of double primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, float defaultValue) Registers an handler which sets a member variable of float primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, float defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of float primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, int defaultValue) Registers an handler which sets a member variable of int primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, int defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of int primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, long defaultValue) Registers an handler which sets a member variable of long primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, long defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of long primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, short defaultValue) Registers an handler which sets a member variable of short primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, short defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of short primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, java.lang.String defaultValue) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setOnOption(java.lang.String option, java.lang.String description, java.lang.String aliases, java.lang.Object target, java.lang.String memberName, java.lang.String defaultValue, boolean defaultOnly) Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.
void	setPrintUsageOnException(boolean printUsageOnException)
void	setPriority(int priority) Set the priority for the last accessed option
void	setPriority(java.lang.String option, int priority) Set the priority for a given option.
static void	setSortUsageOnPriority(boolean sortUsageOnPriority) Set whether or not options are sorted also considering priority (besides alphabetical order) when usage() is called.
void	setValuesOnOptions(java.lang.String[] options, java.lang.Object target, java.lang.String member) An overload for setValuesOnOptions() for String target members, that uses the option literals themselves as option values.
void	setValuesOnOptions(java.lang.String[] options, java.lang.String[] values, java.lang.Object target, java.lang.String member) Sets the same member with different values when different options are encountered.
void	setValuesOnOptions(java.lang.String options, java.lang.Object target, java.lang.String member) An overload for setValuesOnOptions() for String target members, that uses the option literals themselves as option values.
void	setValuesOnOptions(java.lang.String options, java.lang.String values, java.lang.Object target, java.lang.String member) Sets the same member with different values when different options are encountered.
java.lang.String	usage() Creates an usage string by combining the usage description provided at construction (if any) and the descriptions/aliases of every option.
void	useDefaultProperties(java.util.Properties properties)
void	useDefaultPropertyFile(java.io.File propertiesFile) Read the properties file containing the defaults.
void	useDefaultPropertyFile(java.io.File propertiesFile, boolean required) Read the properties file containing the defaults.
void	useDefaultPropertyFile(java.lang.String propertiesFile) Set the properties file containing the defaults.
void	useDefaultPropertyFile(java.lang.String propertiesFile, boolean required) Set the properties file containing the defaults.
void	useDefaultStream(java.io.InputStream is, CmdLineOptions.DefaultsStreamParser parser)
void	useDefaultXMLFile(java.io.File XMLFile) Read the XML file containing the defaults.
void	useDefaultXMLFile(java.io.File XMLFile, boolean required) Read the XML file containing the defaults.
void	useDefaultXMLFile(java.lang.String XMLFile) Set the XML file containing the defaults.
void	useDefaultXMLFile(java.lang.String XMLFile, boolean required) Set the XML file containing the defaults.

Methods inherited from class java.lang.Object

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

Constructor Detail

CmdLineOptions

public CmdLineOptions(boolean allowNegatedOptions,
                      java.lang.String optPrefix,
                      boolean failOnUnrecognizedOption)

Build an handler which recognizes options with the given prefix and specifies whether to allow or no the negation of options(by using +/- after the option itself).

Parameters:

failOnUnrecognizedOption - if true, a ProgrammingError will occur if an option is not recognized by parse().

optPrefix - the prefix which identifies an option.

allowNegatedOptions - if true, options can be followed by +/- to switch them on or off.

CmdLineOptions

public CmdLineOptions(java.lang.String usageDescription,
                      boolean allowNegatedOptions,
                      java.lang.String optPrefix,
                      boolean failOnUnrecognizedOption)

Build an handler with the given usage description, which recognizes options with the given prefix and specifies whether to allow or no the negation of options(by using +/- after the option itself).

Parameters:

usageDescription - a human-readable description of the tool embedding this object

failOnUnrecognizedOption - if true, a ProgrammingError will occur if an option is not recognized by parse().

optPrefix - the prefix which identifies an option.

allowNegatedOptions - if true, options can be followed by +/- to switch them on or off.

CmdLineOptions

public CmdLineOptions(boolean allowNegatedOptions,
                      java.lang.String optPrefix)

Build an handler which recognizes options with the given prefix, specifies whether to allow or no the negation of options(by using +/- after the option itself), and fails if an option is not recognized.

Parameters:

allowNegatedOptions - if true, options can be followed by +/- to switch them on or off.

optPrefix - the prefix which identifies an option.

CmdLineOptions

public CmdLineOptions(java.lang.String usageDescription,
                      boolean allowNegatedOptions,
                      java.lang.String optPrefix)

Build an handler which recognizes options with the given prefix, specifies whether to allow or no the negation of options(by using +/- after the option itself), and fails if an option is not recognized.

Parameters:

usageDescription - a human-readable description of the tool embedding this object.

allowNegatedOptions - if true, options can be followed by +/- to switch them on or off.

optPrefix - the prefix which identifies an option.

CmdLineOptions

public CmdLineOptions(java.lang.String usageDescription,
                      boolean allowNegatedOptions)

Build an handler which recognizes options with the "-" prefix, specifies whether to allow or no the negation of options(by using +/- after the option itself), and fails if an option is not recognized.

Parameters:

usageDescription - a human-readable description of the tool embedding this object.

allowNegatedOptions - if true, options can be followed by +/- to switch them on or off.

CmdLineOptions

public CmdLineOptions(java.lang.String usageDescription)

Build an handler which recognizes options with the "-" prefix, allows only plain options, and fails if an option is not recognized.

Parameters:

usageDescription - a human-readable description of the tool embedding this object.

CmdLineOptions

public CmdLineOptions(boolean allowNegatedOptions)

Build an handler which recognizes options with the "-" prefix, specifies whether to allow or no the negation of options(by using +/- after the option itself), and fails if an option is not recognized.

Parameters:

allowNegatedOptions - if true, options can be followed by +/- to switch them on or off.

CmdLineOptions

public CmdLineOptions()

Build an handler which recognizes options with the "-" prefix, allows only plain options, and fails if an option is not recognized.

Method Detail

isPrintUsageOnException

public boolean isPrintUsageOnException()

setPrintUsageOnException

public void setPrintUsageOnException(boolean printUsageOnException)

useDefaultProperties

public void useDefaultProperties(java.util.Properties properties)

useDefaultPropertyFile

public void useDefaultPropertyFile(java.io.File propertiesFile,
                                   boolean required)

Read the properties file containing the defaults.

Parameters:

propertiesFile - the properties file to open

required - if true, an exception is thrown if the properties file is not found

useDefaultPropertyFile

public void useDefaultPropertyFile(java.io.File propertiesFile)

Read the properties file containing the defaults.

Parameters:

propertiesFile - the properties file to open

useDefaultPropertyFile

public void useDefaultPropertyFile(java.lang.String propertiesFile,
                                   boolean required)

Set the properties file containing the defaults.

Parameters:

propertiesFile - the properties file to open

required - if true, an exception is thrown if the properties file is not found

useDefaultPropertyFile

public void useDefaultPropertyFile(java.lang.String propertiesFile)

Set the properties file containing the defaults.

Parameters:

propertiesFile - the properties file to open

useDefaultXMLFile

public void useDefaultXMLFile(java.io.File XMLFile,
                              boolean required)

Read the XML file containing the defaults. The tags in the XML file must match the name of an option (or alias). The text content is the value.

Parameters:

XMLFile - the XML file to open

required - if true, an exception is thrown if the XML file is not found

useDefaultXMLFile

public void useDefaultXMLFile(java.io.File XMLFile)

Read the XML file containing the defaults. The tags in the XML file must match the name of an option (or alias). The text content is the value.

Parameters:

XMLFile - the XML file to open

useDefaultXMLFile

public void useDefaultXMLFile(java.lang.String XMLFile,
                              boolean required)

Set the XML file containing the defaults. The tags in the XML file must match the name of an option (or alias). The text content is the value.

Parameters:

XMLFile - the XML file to open

required - if true, an exception is thrown if the XML file is not found

useDefaultXMLFile

public void useDefaultXMLFile(java.lang.String XMLFile)

Set the XML file containing the defaults. The tags in the XML file must match the name of an option (or alias). The text content is the value.

Parameters:

XMLFile - the XML file to open

useDefaultStream

public void useDefaultStream(java.io.InputStream is,
                             CmdLineOptions.DefaultsStreamParser parser)

parse

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

Parse the cmdline arguments (usually received by main) looking for the options managed by the handler.

Options are parsed according to their priority - options with higher priority are parsed first.

If the handlers has been built with the failOnUnrecognizedOption parameter true, this method will throw an OptionException on unrecognized options.

Parameters:

args - the cmdline arguments.

Returns:

the cmdline arguments stripped by the options found.

parse

public java.lang.String[] parse(java.lang.String[] _args,
                                java.lang.String context)

Parses the cmdline arguments (usually received by main) looking for the options managed by the handler. Options are parsed according to their priority - options with higher priority are parsed first.

If the handlers has been built with the failOnUnrecognizedOption parameter true, this method will throw an OptionException on unrecognized options.

Parameters:

context - in case of parsing problem, it's used in the diagnostics to tell the user the context of the problem (for example, if the parsing is done on a String[] synthetized by the program and not directly on command line arguments).

Returns:

the cmdline arguments stripped by the options found.

usage

public java.lang.String usage()

Creates an usage string by combining the usage description provided at construction (if any) and the descriptions/aliases of every option.

setMandatory

public void setMandatory(java.lang.String option,
                         boolean mandatory)

Set or unset the 'mandatory' state of an option. The option must have an handler. Mandatory options will generate an OptionException at runtime on parse() if they're not included in the parsed arguments.

Parameters:

option - the option whose mandatory state is to be set.

mandatory - the mandatory state to set.

setMandatory

public void setMandatory(java.lang.String option)

Set an option as mandatory. The option must have an handler. Mandatory options will generate an OptionException at runtime on parse() if they're not included in the parsed arguments.

Parameters:

option - the option whose mandatory state is to be set.

setMandatory

public void setMandatory()

Set the last accessed option as mandatory. Mandatory options will generate an OptionException at runtime on parse() if they're not included in the parsed arguments.

setMandatory

public void setMandatory(boolean mandatory)

Set or unset the 'mandatory' state of the last accessed option. Mandatory options will generate an OptionException at runtime on parse() if they're not included in the parsed arguments.

Parameters:

mandatory - the mandatory state to set.

setHelpOption

public void setHelpOption(java.lang.String option,
                          boolean value)

Set/unset an option as the "help option".

An "help option" is an option which the user uses when he wants only to receive help.

It affects the parsing in that, when parse() is invoked, the parser will not complain about mandatory options missing if the help option is the only one present.

If the help option is mixed with other options, the parsing result (exceptional or correct) depend on the result of isFailOnMixedHelpOptionEncountered() method (which defaults to true).

It is s client code responsability to react properly (for example displaying the usage() string) when the user specifies an help option.

Parameters:

option - the option to be set or unset as help option.

value - if true, the given option is set as help option. If false, the given option (which must be the current help option) is unset as help option.

setHelpOption

public void setHelpOption(java.lang.String option)

Set the given option an help option. The option must have an handler.

See setHelpOption() for details on help options.

Parameters:

option - the option to be set as help option.

setHelpOption

public void setHelpOption()

getHelpOption

public java.lang.String getHelpOption()

Return the current help option See setHelpOption() or null if no help option is set.

Returns:

the current help option or null if no help option is set.

isMandatory

public boolean isMandatory(java.lang.String option)

Returns the mandatory state of the given option. The option must have an handler.

Parameters:

option - the option whose mandatory state is to be verified.

Returns:

the mandatory state of the given option.

setAlternativeMandatory

public void setAlternativeMandatory(java.lang.String[] options,
                                    boolean mandatory)

Sets/removes the mandatory state of a group of mutually exclusive options, for which already exist handlers, where at least one is mandatory. Alternative mandatory options will generate a ProgrammingError at runtime on parse() if at least one is included in the parsed arguments.

Parameters:

options - an array of option names.

mandatory - the mandatory state.

setMandatoryOnOption

public void setMandatoryOnOption(java.lang.String option,
                                 java.lang.String[] optionsToSet)

Specifies that all the options in the given set become mandatory only if one other option is encountered

Parameters:

option - the option with triggers the mandatory state of the given others.

optionsToSet - the options which become mandatory.

setMandatoryOnOption

public void setMandatoryOnOption(java.lang.String option,
                                 java.lang.String optionsToSet)

Specifies that the given options set are mandatory only if one other option is encountered. The options to set as mandatory are specified as a comma separated string.

Parameters:

option - the option with triggers the mandatory state of the given others.

optionsToSet - the options which become mandatory, as a comma separated string.

setMandatoryOnOptions

public void setMandatoryOnOptions(java.lang.String options,
                                  java.lang.String[] optionsToSet)

Specifies that the given options set are mandatory only if one in another set of options is encountered.

Parameters:

optionsToSet - the options which become mandatory.

setMandatoryOnOptions

public void setMandatoryOnOptions(java.lang.String options,
                                  java.lang.String optionsToSet)

Specifies that the given options set are mandatory only if one in another set of options is encountered. The options to set as mandatory are specified as a comma separated string.

Parameters:

optionsToSet - the options which become mandatory, as a comma separated string.

setAlternativeMandatoryOnOption

public void setAlternativeMandatoryOnOption(java.lang.String options,
                                            java.lang.String[] optionsToSet)

Specifies that one among the given options set become mandatory only if one option is encountered.

Parameters:

optionsToSet - the options which become alternative-mandatory.

setAlternativeMandatoryOnOption

public void setAlternativeMandatoryOnOption(java.lang.String options,
                                            java.lang.String optionsToSet)

Specifies that one among the given options set become mandatory only if one option is encountered. The options to set as mandatory are specified as a comma separated string.

Parameters:

optionsToSet - the options which become alternative-mandatory, as a comma separated string.

setAlternativeMandatoryOnOptions

public void setAlternativeMandatoryOnOptions(java.lang.String options,
                                             java.lang.String[] optionsToSet)

Specifies that one among the given options set become mandatory only if one in another set of options is encountered.

Parameters:

optionsToSet - the options which become alternative-mandatory.

setAlternativeMandatoryOnOptions

public void setAlternativeMandatoryOnOptions(java.lang.String options,
                                             java.lang.String optionsToSet)

Specifies that one among the given options set become mandatory only if one in another set of options is encountered. The options to set as mandatory are specified as a comma separated string.

Parameters:

optionsToSet - the options which become alternative-mandatory, as a comma separated string.

setAlternativeMandatory

public void setAlternativeMandatory(java.lang.String[] options)

Sets up a group of options, for which already exist handlers, as mutually exclusive and where at least one is mandatory.

Alternative-mandatory options will generate a ProgrammingError at runtime on parse() if at least one is included in the parsed arguments.

Parameters:

options - an array of option names.

registerHandler

public void registerHandler(CmdLineOptions.Handler handler)

Registers an handler. Only one handler for a given option literal may be registered.

Parameters:

handler - the option handler to register.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target)

Registers an handler which sets a member variable of String type, on the target object when encountered, having the same name as the option.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

setObjectOnOption

public void setObjectOnOption(java.lang.String option,
                              java.lang.Object target,
                              java.lang.Object defaultValue)

Registers an handler which sets a member variable (of Object type) of on the target object when encountered, having the same name as the option.

If the member type is boolean, the member will be set to true if the option exists. For other types, a single following parameter is required, unless a default is specified.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

defaultValue - a default value of the member - may be null.

setObjectOnOption

public void setObjectOnOption(java.lang.String option,
                              java.lang.Object target)

Registers an handler which sets a member variable (of Object type) of on the target object when encountered, having the same name as the option, and no default value (null).

Parameters:

option - the option and member name to be set.

target - the object which contains the member to be set.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName)

Registers an handler which sets a member variable of String type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

setObjectOnOption

public void setObjectOnOption(java.lang.String option,
                              java.lang.Object target,
                              java.lang.String memberName,
                              java.lang.Object defaultValue)

Registers an handler which sets a member variable (of Object type) on the target object when encountered. If the member type is boolean, the member will be set to true if the option exists. For other types, a single following parameter is required, unless a default is specified.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member - may be null.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        java.lang.String defaultValue)

Registers an handler which sets a member variable of String type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        boolean defaultValue)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        char defaultValue)

Registers an handler which sets a member variable of char primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        byte defaultValue)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        short defaultValue)

Registers an handler which sets a member variable of short primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        int defaultValue)

Registers an handler which sets a member variable of int primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        long defaultValue)

Registers an handler which sets a member variable of long primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        float defaultValue)

Registers an handler which sets a member variable of float primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        double defaultValue)

Registers an handler which sets a member variable of double primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

setObjectOnOption

public void setObjectOnOption(java.lang.String option,
                              java.lang.String description,
                              java.lang.String aliases,
                              java.lang.Object target,
                              java.lang.String memberName,
                              java.lang.Object defaultValue,
                              boolean defaultOnly)

Registers an handler which sets a member variable (of Object type) of on the target object when encountered. If the member type is boolean, the member will be set to true if the option exists. For other types, a single following parameter is required, unless a default is specified.

Parameters:

option - the option to be set.

description - a description for the option.

aliases - the option aliases, in comma-separated format.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member - may be null.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setObjectOnOption

public void setObjectOnOption(java.lang.String option,
                              java.lang.Object target,
                              java.lang.String memberName,
                              java.lang.Object defaultValue,
                              boolean defaultOnly)

Registers an handler which sets a member variable (of Object type) of the target object when found (without defining any description nor aliases). If the member type is boolean, the member will be set to true if the option exists. For other types, a single following parameter is required, unless a default is specified.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member - may be null.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        java.lang.String defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        boolean defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        char defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of char primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        byte defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        short defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of short primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        int defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of int primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        long defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of long primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null) (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        float defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of float primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.Object target,
                        java.lang.String memberName,
                        double defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of double primitive type on the target object when encountered.

Parameters:

option - the option to be set.

target - the object which contains the member to be set.

memberName - the name of the member to be set.

defaultValue - a default value of the member.

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null).

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        java.lang.String defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        boolean defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        char defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of char primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        byte defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        short defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of short primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        int defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of int primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        long defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of long primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null) (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        float defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of float primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        double defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of double primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        java.lang.String defaultValue)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        boolean defaultValue)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        char defaultValue)

Registers an handler which sets a member variable of char primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        byte defaultValue)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        short defaultValue)

Registers an handler which sets a member variable of short primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        int defaultValue)

Registers an handler which sets a member variable of int primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        long defaultValue)

Registers an handler which sets a member variable of long primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        float defaultValue)

Registers an handler which sets a member variable of float primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String description,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        double defaultValue)

Registers an handler which sets a member variable of double primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        java.lang.String defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        boolean defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        char defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of char primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        byte defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        short defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of short primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        int defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of int primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        long defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of long primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null) (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        float defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of float primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        double defaultValue,
                        boolean defaultOnly)

Registers an handler which sets a member variable of double primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

defaultOnly - if true, the option will not allow parameters, but the associated member will be set to the default if passed on the command line (defaultValue must be not null)

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        java.lang.String defaultValue)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        boolean defaultValue)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        char defaultValue)

Registers an handler which sets a member variable of char primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        byte defaultValue)

Registers an handler which sets a member variable of boolean primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        short defaultValue)

Registers an handler which sets a member variable of short primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        int defaultValue)

Registers an handler which sets a member variable of int primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        long defaultValue)

Registers an handler which sets a member variable of long primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        float defaultValue)

Registers an handler which sets a member variable of float primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setOnOption

public void setOnOption(java.lang.String option,
                        java.lang.String aliases,
                        java.lang.Object target,
                        java.lang.String memberName,
                        double defaultValue)

Registers an handler which sets a member variable of double primitive type on the target object when encountered.

Parameters:

option - the option to be set

target - the object which contains the member to be set

memberName - the name of the member to be set

defaultValue - a default value of the member

setValuesOnOptions

public void setValuesOnOptions(java.lang.String options,
                               java.lang.String values,
                               java.lang.Object target,
                               java.lang.String member)

Sets the same member with different values when different options are encountered. When a user specifies an option, the member is set with the corresponding value. The user will not be able/need to specify any parameter for the option.

It's just a shortcut to multiple setOnOptions() calls referring to the same member in the target object and allowing only the default value to be set.

An example:

setValuesOnOptions("doThis, doThat", "this, that", this, "thingToDo");

sets the member "thingToDo" in the target (this) to either this or that when the user specifies either doThis or doThat.

Parameters:

options - the options which trigger the assignment, in comma separated format

values - the values to assign the target object's member, in comma separated format, in 1-1 correspondence with the options

target - the target object, owning the member to be set

member - the member variable to be set in the target object when one of the options is encountered

setValuesOnOptions

public void setValuesOnOptions(java.lang.String[] options,
                               java.lang.String[] values,
                               java.lang.Object target,
                               java.lang.String member)

Sets the same member with different values when different options are encountered. When a user specifies an option, the member is set with the corresponding value. The user will not be able/need to specify any parameter for the option.

It's just a shortcut to multiple setOnOptions() calls referring to the same member in the target object and allowing only the default value to be set.

An example:

setValuesOnOptions(new String[] { "doThis", "doThat" }, new String[] { "his", "that" }, this, "thingToDo");

sets the member "thingToDo" in the target (this) to either this or that when the user specifies either doThis or doThat.

Parameters:

options - the options which trigger the assignment

values - the values to assign the target object's member, in 1-1 correspondence with the options

target - the target object, owning the member to be set

member - the member variable to be set in the target object when one of the options is encountered

setValuesOnOptions

public void setValuesOnOptions(java.lang.String options,
                               java.lang.Object target,
                               java.lang.String member)

An overload for setValuesOnOptions() for String target members, that uses the option literals themselves as option values. The net effect is that the member target is set with the name of the option, whenever one of the given options is specified by the user.

Parameters:

options - the options which trigger the assignment, in comma separated format

target - the target object, owning the member to be set

member - the member variable to be set in the target object when one of the options is encountered

setValuesOnOptions

public void setValuesOnOptions(java.lang.String[] options,
                               java.lang.Object target,
                               java.lang.String member)

An overload for setValuesOnOptions() for String target members, that uses the option literals themselves as option values. The net effect is that the member target is set with the name of the option, whenever one of the given options is specified by the user.

Parameters:

options - the options which trigger the assignment, in comma separated format

target - the target object, owning the member to be set

member - the member variable to be set in the target object when one of the options is encountered

setDescription

public void setDescription(java.lang.String option,
                           java.lang.String description)

Sets the description for a given option.

Parameters:

option - the option (for which an handler must already exist)

description - the description of the option

setDescription

public void setDescription(java.lang.String description)

Set the description for the last accessed option

Parameters:

description - the description of the option

setActionOnParse

public void setActionOnParse(java.lang.String option,
                             java.lang.Runnable action)

For non-user defined handlers, set an action to be executed when the option is parsed. (user-defined handlers simply override CmdLineOptions.Handler#option(String, ParamSet, boolean)).

The action will be executed when the option is parsed and the relative members are set.

Parameters:

option - the option (for which an handler must already exist)

action - the action to execute (besides the automatic field-setting)

setActionOnParse

public void setActionOnParse(java.lang.Runnable action)

For non-user defined handlers, set an action to be executed when the last created option is parsed. (user-defined handlers simply override CmdLineOptions.Handler#option(String, ParamSet, boolean)).

The action will be executed when the option is parsed and the relative members are set.

Parameters:

action - the action to execute (besides the automatic field-setting)

setPriority

public void setPriority(java.lang.String option,
                        int priority)

Set the priority for a given option.

Parameters:

option - the option (for which an handler must already exist)

setPriority

public void setPriority(int priority)

Set the priority for the last accessed option

Parameters:

priority - the priority of the option

hasOption

public CmdLineOptions.Handler.ParamSet hasOption(java.lang.String opt,
                                                 java.lang.String[] args)

Return the set of parameters of the given option.

Parameters:

opt -

args -

Returns:

getDescription

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

Retrieve the description for a given option.

Parameters:

option - the option (for which an handler must exist)

Returns:

the description of the option

addAliases

public void addAliases(java.lang.String option,
                       java.lang.String aliases)

Adds aliases for a given option.

Parameters:

option - the option (for which an handler must already exist)

aliases - the new aliases for the option. If an alias is already set it's ignored.

addAliases

public void addAliases(java.lang.String aliases)

Add aliases to the last accessed option

Parameters:

aliases -

isFailOnUnrecognizedOption

public boolean isFailOnUnrecognizedOption()

Return the failOnUnrecognizedOption.

Returns:

boolean

setFailOnUnrecognizedOption

public void setFailOnUnrecognizedOption(boolean failOnUnrecognizedOption)

Set the failOnUnrecognizedOption.

Parameters:

failOnUnrecognizedOption - The failOnUnrecognizedOption to set

isFailOnMixedHelpOptionEncountered

public boolean isFailOnMixedHelpOptionEncountered()

Return the value for the 'failOnMixedHelpOptionEncountered' flag. If the flag is true, encountering an 'help option' when parsing will result in an OptionException.

See setHelpOption() for details on help options.

Returns:

boolean

setFailOnMixedHelpOptionEncountered

public void setFailOnMixedHelpOptionEncountered(boolean failOnMixedHelpOptionEncountered)

Set the value for the 'failOnMixedHelpOptionEncountered' flag. If the flag is true, encountering an 'help option' when parsing will result in an OptionException.

See setHelpOption() for details on help options.

Parameters:

failOnMixedHelpOptionEncountered - The failOnMixedHelpOptionEncountered to set

isSortUsageOnPriority

public static boolean isSortUsageOnPriority()

Return whether or not options are sorted also considering priority (besides alphabetical order) when usage() is called.

Returns:

whether or not options are sorted also considering priority (besides alphabetical order) when usage() is called.

setSortUsageOnPriority

public static void setSortUsageOnPriority(boolean sortUsageOnPriority)

Set whether or not options are sorted also considering priority (besides alphabetical order) when usage() is called.

Parameters:

sortUsageOnPriority - if true, options are sorted also considering priority (besides alphabetical order) when usage() is called