org.sadun.util
Class CmdLineOptions

java.lang.Object
  extended byorg.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


Copyright © 1999-2004 Cristiano Sadun. This software is released under GPL.