ml.options
Class Options

java.lang.Object
  extended by ml.options.Options

public class Options
extends Object

The central class for option processing. Sets are identified by their name, but there is also an anonymous default set, which is very convenient if an application requieres only one set.


Nested Class Summary
static class Options.Multiplicity
          An enum encapsulating the possible multiplicities for options
static class Options.Prefix
          An enum encapsulating the possible prefixes identifying options (and separating them from command line data items)
static class Options.Separator
          An enum encapsulating the possible separators between value options and their actual values.
 
Field Summary
static String DEFAULT_SET
          The name used internally for the default set
 
Constructor Summary
Options(String[] args)
          Constructor.
Options(String[] args, int data)
          Constructor.
Options(String[] args, int defMinData, int defMaxData)
          Constructor.
Options(String[] args, Options.Multiplicity defaultMultiplicity)
          Constructor.
Options(String[] args, Options.Multiplicity defaultMultiplicity, int data)
          Constructor.
Options(String[] args, Options.Multiplicity defaultMultiplicity, int defMinData, int defMaxData)
          Constructor.
Options(String[] args, Options.Prefix prefix)
          Constructor.
Options(String[] args, Options.Prefix prefix, int data)
          Constructor.
Options(String[] args, Options.Prefix prefix, int defMinData, int defMaxData)
          Constructor.
Options(String[] args, Options.Prefix prefix, Options.Multiplicity defaultMultiplicity)
          Constructor.
Options(String[] args, Options.Prefix prefix, Options.Multiplicity defaultMultiplicity, int data)
          Constructor
Options(String[] args, Options.Prefix prefix, Options.Multiplicity defaultMultiplicity, int defMinData, int defMaxData)
          Constructor
 
Method Summary
 void addOptionAllSets(String key)
          Add the given non-value option to all known sets.
 void addOptionAllSets(String key, boolean details, Options.Separator separator)
          Add the given value option to all known sets.
 void addOptionAllSets(String key, boolean details, Options.Separator separator, Options.Multiplicity multiplicity)
          Add the given value option to all known sets.
 void addOptionAllSets(String key, Options.Multiplicity multiplicity)
          Add the given non-value option to all known sets.
 void addOptionAllSets(String key, Options.Separator separator)
          Add the given value option to all known sets.
 void addOptionAllSets(String key, Options.Separator separator, Options.Multiplicity multiplicity)
          Add the given value option to all known sets.
 OptionSet addSet(String setName)
          Add an option set.
 OptionSet addSet(String setName, int data)
          Add an option set.
 OptionSet addSet(String setName, int minData, int maxData)
          Add an option set.
 boolean check()
          Run the checks for the default set.
 boolean check(boolean ignoreUnmatched, boolean requireDataLast)
          Run the checks for the default set.
 boolean check(String setName)
          Run the checks for the given set.
 boolean check(String setName, boolean ignoreUnmatched, boolean requireDataLast)
          Run the checks for the given set.
 String getCheckErrors()
          The error messages collected during the last option check (invocation of any of the check() methods).
 OptionSet getMatchingSet()
          Return the (first) matching set.
 OptionSet getMatchingSet(boolean ignoreUnmatched, boolean requireDataLast)
          Return the (first) matching set.
 OptionSet getSet()
          This returns the (anonymous) default set
 OptionSet getSet(String setName)
          Return an option set - or null, if no set with the given name exists
 String toString()
          This is the overloaded Object.toString() method, and it is provided mainly for debugging purposes.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_SET

public static final String DEFAULT_SET
The name used internally for the default set

See Also:
Constant Field Values
Constructor Detail

Options

public Options(String[] args,
               Options.Prefix prefix,
               Options.Multiplicity defaultMultiplicity,
               int defMinData,
               int defMaxData)
Constructor

Parameters:
args - The command line arguments to check
prefix - The prefix to use for all command line options. It can only be set here for all options at the same time
defaultMultiplicity - The default multiplicity to use for all options (can be overridden when adding an option)
defMinData - The default minimum number of data items for all sets (can be overridden when adding a set)
defMaxData - The default maximum number of data items for all sets (can be overridden when adding a set)

Throws:
IllegalArgumentException - If either args, prefix, or defaultMultiplicity is null - or if the data range values don't make sense

Options

public Options(String[] args,
               Options.Prefix prefix,
               Options.Multiplicity defaultMultiplicity,
               int data)
Constructor

Parameters:
args - The command line arguments to check
prefix - The prefix to use for all command line options. It can only be set here for all options at the same time
defaultMultiplicity - The default multiplicity to use for all options (can be overridden when adding an option)
data - The default minimum and maximum number of data items for all sets (can be overridden when adding a set)

Throws:
IllegalArgumentException - If either args, prefix, or defaultMultiplicity is null - or if the data range value doesn't make sense

Options

public Options(String[] args,
               Options.Prefix prefix,
               Options.Multiplicity defaultMultiplicity)
Constructor. The default number of data items is set to 0.

Parameters:
args - The command line arguments to check
prefix - The prefix to use for all command line options. It can only be set here for all options at the same time
defaultMultiplicity - The default multiplicity to use for all options (can be overridden when adding an option)

Throws:
IllegalArgumentException - If either args, prefix, or defaultMultiplicity is null

Options

public Options(String[] args,
               Options.Multiplicity defaultMultiplicity,
               int defMinData,
               int defMaxData)
Constructor. The prefix is set to Options.Prefix.DASH.

Parameters:
args - The command line arguments to check
defaultMultiplicity - The default multiplicity to use for all options (can be overridden when adding an option)
defMinData - The default minimum number of data items for all sets (can be overridden when adding a set)
defMaxData - The default maximum number of data items for all sets (can be overridden when adding a set)

Throws:
IllegalArgumentException - If either args or defaultMultiplicity is null - or if the data range values don't make sense

Options

public Options(String[] args,
               Options.Multiplicity defaultMultiplicity,
               int data)
Constructor. The prefix is set to Options.Prefix.DASH.

Parameters:
args - The command line arguments to check
defaultMultiplicity - The default multiplicity to use for all options (can be overridden when adding an option)
data - The default minimum and maximum number of data items for all sets (can be overridden when adding a set)

Throws:
IllegalArgumentException - If either args or defaultMultiplicity is null - or if the data range value doesn't make sense

Options

public Options(String[] args,
               Options.Multiplicity defaultMultiplicity)
Constructor. The prefix is set to Options.Prefix.DASH, and the default number of data items is set to 0.

Parameters:
args - The command line arguments to check
defaultMultiplicity - The default multiplicity to use for all options (can be overridden when adding an option)

Throws:
IllegalArgumentException - If either args or defaultMultiplicity is null

Options

public Options(String[] args)
Constructor. The prefix is set to Options.Prefix.DASH, the default number of data items is set to 0, and the multiplicity is set to Options.Multiplicity.ONCE.

Parameters:
args - The command line arguments to check

Throws:
IllegalArgumentException - If args is null

Options

public Options(String[] args,
               int data)
Constructor. The prefix is set to Options.Prefix.DASH, and the multiplicity is set to Options.Multiplicity.ONCE.

Parameters:
args - The command line arguments to check
data - The default minimum and maximum number of data items for all sets (can be overridden when adding a set)

Throws:
IllegalArgumentException - If args is null - or if the data range value doesn't make sense

Options

public Options(String[] args,
               int defMinData,
               int defMaxData)
Constructor. The prefix is set to Options.Prefix.DASH, and the multiplicity is set to Options.Multiplicity.ONCE.

Parameters:
args - The command line arguments to check
defMinData - The default minimum number of data items for all sets (can be overridden when adding a set)
defMaxData - The default maximum number of data items for all sets (can be overridden when adding a set)

Throws:
IllegalArgumentException - If args is null - or if the data range values don't make sense

Options

public Options(String[] args,
               Options.Prefix prefix)
Constructor. The default number of data items is set to 0, and the multiplicity is set to Options.Multiplicity.ONCE.

Parameters:
args - The command line arguments to check
prefix - The prefix to use for all command line options. It can only be set here for all options at the same time

Throws:
IllegalArgumentException - If either args or prefix is null

Options

public Options(String[] args,
               Options.Prefix prefix,
               int data)
Constructor. The multiplicity is set to Options.Multiplicity.ONCE.

Parameters:
args - The command line arguments to check
prefix - The prefix to use for all command line options. It can only be set here for all options at
data - The default minimum and maximum number of data items for all sets (can be overridden when adding a set)

Throws:
IllegalArgumentException - If either args or prefix is null - or if the data range value doesn't make sense

Options

public Options(String[] args,
               Options.Prefix prefix,
               int defMinData,
               int defMaxData)
Constructor. The multiplicity is set to Options.Multiplicity.ONCE.

Parameters:
args - The command line arguments to check
prefix - The prefix to use for all command line options. It can only be set here for all options at the same time
defMinData - The default minimum number of data items for all sets (can be overridden when adding a set)
defMaxData - The default maximum number of data items for all sets (can be overridden when adding a set)

Throws:
IllegalArgumentException - If either args or prefix is null - or if the data range values don't make sense
Method Detail

getMatchingSet

public OptionSet getMatchingSet()
Return the (first) matching set. This invocation does not ignore unmatched options and requires that data items are the last ones on the command line.

Returns:
The first set which matches (i. e. the check() method returns true) - or null, if no set matches.

getMatchingSet

public OptionSet getMatchingSet(boolean ignoreUnmatched,
                                boolean requireDataLast)
Return the (first) matching set.

Parameters:
ignoreUnmatched - A boolean to select whether unmatched options can be ignored in the checks or not
requireDataLast - A boolean to indicate whether the data items have to be the last ones on the command line or not

Returns:
The first set which matches (i. e. the check() method returns true) - or null, if no set matches.

addSet

public OptionSet addSet(String setName,
                        int minData,
                        int maxData)
Add an option set.

Parameters:
setName - The name for the set. This must be a unique identifier
minData - The minimum number of data items for this set
maxData - The maximum number of data items for this set

Returns:
The new Optionset instance created. This is useful to allow chaining of addOption() calls right after this method

addSet

public OptionSet addSet(String setName,
                        int data)
Add an option set.

Parameters:
setName - The name for the set. This must be a unique identifier
data - The minimum and maximum number of data items for this set

Returns:
The new Optionset instance created. This is useful to allow chaining of addOption() calls right after this method

addSet

public OptionSet addSet(String setName)
Add an option set. The defaults for the number of data items are used.

Parameters:
setName - The name for the set. This must be a unique identifier

Returns:
The new Optionset instance created. This is useful to allow chaining of addOption() calls right after this method

getSet

public OptionSet getSet(String setName)
Return an option set - or null, if no set with the given name exists

Parameters:
setName - The name for the set to retrieve

Returns:
The set to retrieve (or null, if no set with the given name exists)

getSet

public OptionSet getSet()
This returns the (anonymous) default set

Returns:
The default set

getCheckErrors

public String getCheckErrors()
The error messages collected during the last option check (invocation of any of the check() methods). This is useful to determine what was wrong with the command line arguments provided

Returns:
A string with all collected error messages

check

public boolean check()
Run the checks for the default set. ignoreUnmatched is set to false, and requireDataLast is set to true.

Returns:
A boolean indicating whether all checks were successful or not

check

public boolean check(boolean ignoreUnmatched,
                     boolean requireDataLast)
Run the checks for the default set.

Parameters:
ignoreUnmatched - A boolean to select whether unmatched options can be ignored in the checks or not
requireDataLast - A boolean to indicate whether the data items have to be the last ones on the command line or not

Returns:
A boolean indicating whether all checks were successful or not

check

public boolean check(String setName)
Run the checks for the given set. ignoreUnmatched is set to false, and requireDataLast is set to true.

Parameters:
setName - The name for the set to check

Returns:
A boolean indicating whether all checks were successful or not

Throws:
IllegalArgumentException - If either setName is null, or the set is unknown.

check

public boolean check(String setName,
                     boolean ignoreUnmatched,
                     boolean requireDataLast)
Run the checks for the given set.

Parameters:
setName - The name for the set to check
ignoreUnmatched - A boolean to select whether unmatched options can be ignored in the checks or not
requireDataLast - A boolean to indicate whether the data items have to be the last ones on the command line or not

Returns:
A boolean indicating whether all checks were successful or not

Throws:
IllegalArgumentException - If either setName is null, or the set is unknown.

addOptionAllSets

public void addOptionAllSets(String key)
Add the given non-value option to all known sets. See OptionSet.addOption(String) for details.


addOptionAllSets

public void addOptionAllSets(String key,
                             Options.Multiplicity multiplicity)
Add the given non-value option to all known sets. See OptionSet.addOption(String, Options.Multiplicity) for details.


addOptionAllSets

public void addOptionAllSets(String key,
                             Options.Separator separator)
Add the given value option to all known sets. See OptionSet.addOption(String, Options.Separator) for details.


addOptionAllSets

public void addOptionAllSets(String key,
                             Options.Separator separator,
                             Options.Multiplicity multiplicity)
Add the given value option to all known sets. See OptionSet.addOption(String, Options.Separator, Options.Multiplicity) for details.


addOptionAllSets

public void addOptionAllSets(String key,
                             boolean details,
                             Options.Separator separator)
Add the given value option to all known sets. See OptionSet.addOption(String, boolean, Options.Separator) for details.


addOptionAllSets

public void addOptionAllSets(String key,
                             boolean details,
                             Options.Separator separator,
                             Options.Multiplicity multiplicity)
Add the given value option to all known sets. See OptionSet.addOption(String, boolean, Options.Separator, Options.Multiplicity) for details.


toString

public String toString()
This is the overloaded Object.toString() method, and it is provided mainly for debugging purposes.

Overrides:
toString in class Object
Returns:
A string representing the instance