ml.options
Class Options

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

public class Options
extends java.lang.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.

The default values used in this class are:

Default Values
ID Parameter Default Individual Setting
1 Prefix Prefix.SLASH (Windows)
Prefix.DASH (all others)
No
2 Alternate Prefix Prefix.DOUBLEDASH No
3 Separator for value options Separator.BLANK No
4 Separator for detail options Separator.EQUALS No
5 Min. Data 0 Option set level
6 Max. Data 0 Option set level
7 Multiplicity Multiplicity.ZERO_OR_ONCE Option level

All of these values can be changed using one of the setDefault() methods. However, for 1 - 4 this can only be done before any actual set or option has been created (otherwise an UnsupportedOperationException is thrown). 5 - 7 can be called anytime, but they affect only sets and options which are created afterwards.


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.
 
Constructor Summary
Options(java.lang.String[] args)
          Constructor
Options(java.lang.String[] args, java.io.Reader reader)
          This constructor uses the XML file provided by the reader to set up option sets and options.
 
Method Summary
 void addOptionAllSets(OptionData.Type type, java.lang.String key)
          Add the given option to all known sets.
 void addOptionAllSets(OptionData.Type type, java.lang.String key, Options.Multiplicity multiplicity)
          Add the given option to all known sets.
 void addOptionAllSets(OptionData.Type type, java.lang.String key, java.lang.String altKey)
          Add the given option to all known sets.
 void addOptionAllSets(OptionData.Type type, java.lang.String key, java.lang.String altKey, Options.Multiplicity multiplicity)
          Add the given option to all known sets.
 OptionSet addSet(java.lang.String name)
          Add an option set.
 OptionSet addSet(java.lang.String name, int data)
          Add an option set.
 OptionSet addSet(java.lang.String name, int minData, int maxData)
          Add an option set.
 OptionSet addSet(java.lang.String name, OptionSet set)
          Add an option set by cloning an existing set.
 boolean check()
          Run the checks for the default set with default parameters.
 boolean check(boolean ignoreUnmatched, boolean requireDataLast)
          Run the checks for the default set.
 boolean check(java.lang.String name)
          Run the checks for the given set with default parameters.
 boolean check(java.lang.String name, boolean ignoreUnmatched, boolean requireDataLast)
          Run the checks for the given set.
 java.lang.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(java.lang.String name)
          Return an option set - or null, if no set with the given name exists
 void printHelp(HelpPrinter helpPrinter, java.lang.String leadingText, boolean lineBreak, boolean printTexts)
          Print a help description for this instance using the provided HelpPrinter.
 void printHelp(java.lang.String leadingText, boolean lineBreak, boolean printTexts)
          Print a help description for this instance using a DefaultHelpPrinter.
 Options setDefault(int defaultData)
          Define the defaults to use for the number of data items for a set.
 Options setDefault(int defaultMinData, int defaultMaxData)
          Define the defaults to use for the number of data items for a set.
 Options setDefault(Options.Multiplicity defaultMultiplicity)
          Define the default to use for the multiplicity for options.
 Options setDefault(Options.Prefix defaultPrefix)
          Define the default to use for the option prefix.
 Options setDefault(Options.Prefix defaultPrefix, Options.Prefix defaultAltPrefix)
          Define the defaults to use for the option prefixes.
 Options setDefault(Options.Separator defaultValueSeparator)
          Define the default to use for the separator for value options.
 Options setDefault(Options.Separator defaultValueSeparator, Options.Separator defaultDetailSeparator)
          Define the defaults to use for the separators for value and detail options.
 java.lang.String toString()
          This is the overloaded Object.toString() method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Options

public Options(java.lang.String[] args)
Constructor

Parameters:
args - The command line arguments to check

Options

public Options(java.lang.String[] args,
               java.io.Reader reader)
        throws org.jdom.JDOMException
This constructor uses the XML file provided by the reader to set up option sets and options.

Parameters:
args - The command line arguments to check
reader - The reader instance providing the XML file
Throws:
org.jdom.JDOMException
Method Detail

setDefault

public Options setDefault(Options.Separator defaultValueSeparator)
Define the default to use for the separator for value options. Note that this method can only be invoked before any option set has been created.

Parameters:
defaultValueSeparator - The default separator to use for all value options

Returns:
This instance to allow for invocation chaining

setDefault

public Options setDefault(Options.Separator defaultValueSeparator,
                          Options.Separator defaultDetailSeparator)
Define the defaults to use for the separators for value and detail options. Note that this method can only be invoked before any option set has been created.

Parameters:
defaultValueSeparator - The default separator to use for all value options
defaultDetailSeparator - The default separator to use for all detail options

Returns:
This instance to allow for invocation chaining

setDefault

public Options setDefault(Options.Prefix defaultPrefix)
Define the default to use for the option prefix. Note that this method can only be invoked before any option set has been created.

Parameters:
defaultPrefix - The prefix to use for all options

Returns:
This instance to allow for invocation chaining

setDefault

public Options setDefault(Options.Prefix defaultPrefix,
                          Options.Prefix defaultAltPrefix)
Define the defaults to use for the option prefixes. Note that this method can only be invoked before any option set has been created.

Parameters:
defaultPrefix - The prefix to use for all options
defaultAltPrefix - The prefix to use for all alternate keys for options

Returns:
This instance to allow for invocation chaining

setDefault

public Options setDefault(Options.Multiplicity defaultMultiplicity)
Define the default to use for the multiplicity for options. This applies only to option sets and options within these sets which are created after this call.

Parameters:
defaultMultiplicity - The default multiplicity to use for all options

Returns:
This instance to allow for invocation chaining

setDefault

public Options setDefault(int defaultData)
Define the defaults to use for the number of data items for a set. This applies only to option sets which are created after this call.

Parameters:
defaultData - The default minimum and maximum number of data items

Returns:
This instance to allow for invocation chaining

setDefault

public Options setDefault(int defaultMinData,
                          int defaultMaxData)
Define the defaults to use for the number of data items for a set. This applies only to option sets which are created after this call.

Parameters:
defaultMinData - The default minimum number of data items
defaultMaxData - The default maximum number of data items

Returns:
This instance to allow for invocation chaining

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. It is equivalent to calling getMatchingSet(false, true).

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(java.lang.String name,
                        int minData,
                        int maxData)
Add an option set.

Parameters:
name - 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 (if set to OptionSet.INF, this effectively corresponds to an unlimited number)

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

addSet

public OptionSet addSet(java.lang.String name,
                        int data)
Add an option set.

Parameters:
name - 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(java.lang.String name)
Add an option set. The defaults for the number of data items are used.

Parameters:
name - 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

addSet

public OptionSet addSet(java.lang.String name,
                        OptionSet set)
Add an option set by cloning an existing set. Note that is designed for setup purposes only, i. e. no check result data is copied either for the set or any options. This method can be very handy if an application requires two (or more) sets which have a lot of options in common and differ only in a few of them. In this case, one would first create a set with the common options, then clone any number of additionally required sets, and add the non-common options to each of these sets.

Note that it is not possible to change the number of data items required for the new set.

Parameters:
name - The name for the new set. This must be a unique identifier
set - The set to clone the new set from

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

getSet

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

Parameters:
name - The name for the set to retrieve

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

printHelp

public void printHelp(java.lang.String leadingText,
                      boolean lineBreak,
                      boolean printTexts)
Print a help description for this instance using a DefaultHelpPrinter. This method provides a basic service in the sense that it loops over all known option sets and prints the command line for each set. If printTexts is true, also descriptive texts are printed for all options and the data arguments.

Note that default values are used for all the components of the helper text, which can be overridden by various methods available in the OptionSet and OptionData classes.

Parameters:
leadingText - The text to precede the command line for each option set (see HelpPrinter.getCommandLine(OptionSet, String, boolean))
lineBreak - A boolean indicating whether the command lines for the option sets should be printed with line breaks or not (see HelpPrinter.getCommandLine(OptionSet, String, boolean))
printTexts - A boolean indicating whether the full help information should be printer (command lines and description texts) or just the command lines

printHelp

public void printHelp(HelpPrinter helpPrinter,
                      java.lang.String leadingText,
                      boolean lineBreak,
                      boolean printTexts)
Print a help description for this instance using the provided HelpPrinter. This method provides a basic service in the sense that it loops over all known option sets and prints the command line for each set. If printTexts is true, also descriptive texts are printed for all options and the data arguments.

Note that default values are used for all the components of the helper text, which can be overridden by various methods available in the OptionSet and OptionData classes.

Parameters:
helpPrinter - The HelpPrinter to use to format the output
leadingText - The text to precede the command line for each option set (see HelpPrinter.getCommandLine(OptionSet, String, boolean))
lineBreak - A boolean indicating whether the command lines for the option sets should be printed with line breaks or not (see HelpPrinter.getCommandLine(OptionSet, String, boolean))
printTexts - A boolean indicating whether the full help information should be printer (command lines and description texts) or just the command lines

getSet

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

Returns:
The default set

toString

public java.lang.String toString()
This is the overloaded Object.toString() method.

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

getCheckErrors

public java.lang.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 with default parameters. This is equivalent to calling check(false, true). If the default set has not yet been used at all, it is created here with the default settings.

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. If the default set has not yet been used at all, it is created here with the default settings.

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(java.lang.String name)
Run the checks for the given set with default parameters. This is equivalent to calling check(name, false, true).

Parameters:
name - The name for the set to check

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

check

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

Parameters:
name - 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

addOptionAllSets

public void addOptionAllSets(OptionData.Type type,
                             java.lang.String key)
Add the given option to all known sets.

Parameters:
type - The type of the option
key - The name of the option

addOptionAllSets

public void addOptionAllSets(OptionData.Type type,
                             java.lang.String key,
                             Options.Multiplicity multiplicity)
Add the given option to all known sets.

Parameters:
type - The type of the option
key - The name of the option
multiplicity - The multiplicity of the option

addOptionAllSets

public void addOptionAllSets(OptionData.Type type,
                             java.lang.String key,
                             java.lang.String altKey)
Add the given option to all known sets.

Parameters:
type - The type of the option
key - The name of the option
altKey - The alternate name of the option

addOptionAllSets

public void addOptionAllSets(OptionData.Type type,
                             java.lang.String key,
                             java.lang.String altKey,
                             Options.Multiplicity multiplicity)
Add the given option to all known sets.

Parameters:
type - The type of the option
key - The name of the option
altKey - The alternate name of the option
multiplicity - The multiplicity of the option