marf.util
Class OptionProcessor

java.lang.Object
  |
  +--marf.util.OptionProcessor

public class OptionProcessor
extends java.lang.Object

Command-Line Option Processing Facilitating Utility. Helps to maintain and validate command-line options and their arguments. The class is properly synchronized as of 0.3.0.4.

$Id: OptionProcessor.java,v 1.29 2005/08/11 00:44:50 mokhov Exp $

Since:
0.3.0.2
Version:
$Revision: 1.29 $
Author:
Serguei Mokhov

Nested Class Summary
protected  class OptionProcessor.Option
          Main Option placeholder.
protected  class OptionProcessor.OptionsHashtable
          A hashtable designed for to hold options.
 
Field Summary
protected  java.util.Hashtable oActiveOptionsNumbers
          A hash-table that contains active numerical options amp.
protected  java.util.Hashtable oActiveOptionsStrings
          A hash-table that contains active string options map.
protected  java.util.Vector oInvalidOptions
          A vector that contains invalid options for error reporting.
protected  java.util.Hashtable oValidOptionsNumbers
          A hash-table that contains valid numerical options map.
protected  java.util.Hashtable oValidOptionsStrings
          A hash-table that contains valid string options map.
static int UNDEF
          Indicates undefined option (-1).
 
Constructor Summary
OptionProcessor()
          Constructs options-free OptionProcessor.
OptionProcessor(java.util.Hashtable poValidOptions)
          Constructs OptionProcessor with known list of valid options.
 
Method Summary
 void addActiveOption(int piOptionCode, java.lang.String pstrOptionString)
          Allows adding an active option to the set of active options directly.
protected  void addActiveOption(OptionProcessor.Option poOption)
          Adds active option.
 void addValidOption(int piOptionCode, java.lang.String pstrOptionString)
          Allows adding a valid option to the set of valid options.
 void addValidOption(int piOptionCode, java.lang.String pstrOptionString, boolean pbRequiresArgument)
          Allows adding a valid option to the set of valid options indicating the necessity of argument to it.
protected  void addValidOption(OptionProcessor.Option poOption)
          Adds valid option.
 void clear()
          Clears out all the option lists of this option processor.
 java.util.Hashtable getActiveOptions()
          Allows querying for the set of active options.
 java.lang.String[] getArgumentVector()
          Returns active and invalid options (in that order) in a form suitable to feed back as an argument vector argv to another application's main().
 java.util.Vector getInvalidOptions()
          Allows querying for the set of invalid options.
static java.lang.String getMARFSourceCodeRevision()
          Retrieves class' revision.
 java.lang.String getOption(int piOption)
          Returns string equivalent of a numerical option.
 java.lang.String getOption(int piOption, boolean pbReturnOnError)
          Returns string equivalent of a numerical option.
 int getOption(java.lang.String pstrOption)
          Returns numerical equivalent of an option string.
 int getOption(java.lang.String pstrOption, boolean pbReturnOnError)
          Returns numerical equivalent of an option string.
 java.lang.String getOptionArgument(int piOption)
          Allows querying for option argument by option number.
 java.lang.String getOptionArgument(int piOption, boolean pbReturnOnError)
          Allows querying for option argument by option number.
 java.lang.String getOptionArgument(java.lang.String pstrOption)
          Allows querying for option argument by option name.
 java.lang.String getOptionArgument(java.lang.String pstrOption, boolean pbReturnOnError)
          Allows querying for option argument by option name.
 java.util.Hashtable getValidOptions()
          Allows querying for the set of active options.
 boolean isActiveOption(int piOption)
          Checks whether supplied integer option is active.
 boolean isActiveOption(java.lang.String pstrOption)
          Checks whether supplied string option is active.
 boolean isInvalidOption(java.lang.String pstrOption)
          Checks whether supplied string option is invalid.
 boolean isValidOption(int piOption)
          Checks whether supplied integer option is valid.
 boolean isValidOption(java.lang.String pstrOption)
          Checks whether supplied string option is valid.
 int parse(java.lang.String[] argv)
          Parses option strings from the argument vector.
 int size()
          Retrieves the option count currently known to the option processor as a sum of active and invalid options.
 java.lang.String toString()
          Converts the internals of the OptionProcessor to a string and returns it.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

UNDEF

public static final int UNDEF
Indicates undefined option (-1).

See Also:
Constant Field Values

oValidOptionsStrings

protected java.util.Hashtable oValidOptionsStrings
A hash-table that contains valid string options map.


oValidOptionsNumbers

protected java.util.Hashtable oValidOptionsNumbers
A hash-table that contains valid numerical options map.

Since:
0.3.0.3

oActiveOptionsStrings

protected java.util.Hashtable oActiveOptionsStrings
A hash-table that contains active string options map. A proper subset of valid options.


oActiveOptionsNumbers

protected java.util.Hashtable oActiveOptionsNumbers
A hash-table that contains active numerical options amp. A proper subset of valid options.

Since:
0.3.0.3

oInvalidOptions

protected java.util.Vector oInvalidOptions
A vector that contains invalid options for error reporting.

Constructor Detail

OptionProcessor

public OptionProcessor()
Constructs options-free OptionProcessor.


OptionProcessor

public OptionProcessor(java.util.Hashtable poValidOptions)
Constructs OptionProcessor with known list of valid options.

Parameters:
poValidOptions - a collection of valid options; if null then the internal hashtable remains empty and is not set to null.
Method Detail

addValidOption

public final void addValidOption(int piOptionCode,
                                 java.lang.String pstrOptionString)
Allows adding a valid option to the set of valid options. If the entry with that name was already in the set, it gets replaced.

Parameters:
piOptionCode - option's numerical code to use, a value
pstrOptionString - option's lexical representation, a key

addValidOption

public final void addValidOption(int piOptionCode,
                                 java.lang.String pstrOptionString,
                                 boolean pbRequiresArgument)
Allows adding a valid option to the set of valid options indicating the necessity of argument to it. If the entry with that name was already in the set, it gets replaced.

Parameters:
piOptionCode - option's numerical code to use, a value
pstrOptionString - option's lexical representation, a key
pbRequiresArgument - set to true if the option requires argument. An exception will be thrown during parsing if an option that requires an argument doesn't get one.
Since:
0.3.0.3
See Also:
parse(String[])

addValidOption

protected final void addValidOption(OptionProcessor.Option poOption)
Adds valid option. This is an Option object helper method.

Parameters:
poOption - option object to add to valid options
Since:
0.3.0.3

addActiveOption

public final void addActiveOption(int piOptionCode,
                                  java.lang.String pstrOptionString)
Allows adding an active option to the set of active options directly. If the entry with that name was already in the set, it gets replaced. Also makes sure that the active option is also added to the valid options set.

Parameters:
piOptionCode - option's numerical code to use, a value
pstrOptionString - option's lexical representation, a key

addActiveOption

protected final void addActiveOption(OptionProcessor.Option poOption)
Adds active option. This is an Option object helper method.

Parameters:
poOption - option object to add to active options
Since:
0.3.0.3

clear

public void clear()
Clears out all the option lists of this option processor.

Since:
0.3.0.3

size

public int size()
Retrieves the option count currently known to the option processor as a sum of active and invalid options. Valid options are omitted from the count because they are more of a static state comparted to the currently active subset of them as well as possibly invalid options, which represent more of a dynamic state.

Returns:
active plus invalid options count
Since:
0.3.0.4

getArgumentVector

public java.lang.String[] getArgumentVector()
Returns active and invalid options (in that order) in a form suitable to feed back as an argument vector argv to another application's main(). Essentially, this allows reconstruct the original argv except that the only ordering guaranteed is that all active are followed by all invalid options.

Returns:
array of strings of active and invalid options
Since:
0.3.0.4

parse

public final int parse(java.lang.String[] argv)

Parses option strings from the argument vector. Does not alter the argument vector itself, but initializes internal active and invalid options. If the same options occurs more than once, the last occurrence only takes effect.

NOTICE, since 0.3.0.3 '=' has a special meaning as a separator bewteen options and values, and, therefore, cannot appear inside option strings or by itself on the command line.

Parameters:
argv - argument vector (array of command-line options)
Returns:
number of valid options found
Throws:
java.lang.RuntimeException - if some valid option that requires an argument doesn't have one.

getOption

public final int getOption(java.lang.String pstrOption)
Returns numerical equivalent of an option string.

Parameters:
pstrOption - option string to look the integer equivalent for
Returns:
int, the option enumeration value
Throws:
java.lang.RuntimeException - if the named option is not found to be active/valid

getOption

public final int getOption(java.lang.String pstrOption,
                           boolean pbReturnOnError)
Returns numerical equivalent of an option string.

Parameters:
pstrOption - option string to look the integer equivalent for
pbReturnOnError - tells getOption to return UNDEF instead of throwing an exception if set to true
Returns:
int, the option enumeration value
Throws:
java.lang.RuntimeException - if the named option is not found to be active/valid

getOption

public final java.lang.String getOption(int piOption)
Returns string equivalent of a numerical option.

Parameters:
piOption - option to look the String equivalent for
Returns:
the option string
Throws:
java.lang.RuntimeException - if the named option is not found to be active/valid

getOption

public final java.lang.String getOption(int piOption,
                                        boolean pbReturnOnError)
Returns string equivalent of a numerical option.

Parameters:
piOption - option to look the String equivalent for
pbReturnOnError - tells getOption to return an empty string instead of throwing an exception if set to true
Returns:
the option string
Throws:
java.lang.RuntimeException - if the named option is not found to be active/valid

getOptionArgument

public java.lang.String getOptionArgument(java.lang.String pstrOption)
Allows querying for option argument by option name.

Parameters:
pstrOption - option name
Returns:
option argument
Since:
0.3.0.3

getOptionArgument

public java.lang.String getOptionArgument(java.lang.String pstrOption,
                                          boolean pbReturnOnError)
Allows querying for option argument by option name.

Parameters:
pstrOption - option name
pbReturnOnError - tells to return an empty string instead of throwing an exception if set to true
Returns:
option argument
Since:
0.3.0.3

getOptionArgument

public java.lang.String getOptionArgument(int piOption)
Allows querying for option argument by option number.

Parameters:
piOption - option number
Returns:
option argument
Since:
0.3.0.3

getOptionArgument

public java.lang.String getOptionArgument(int piOption,
                                          boolean pbReturnOnError)
Allows querying for option argument by option number.

Parameters:
piOption - option number
pbReturnOnError - tells to return an empty string instead of throwing an exception if set to true
Returns:
option argument
Since:
0.3.0.3

getInvalidOptions

public final java.util.Vector getInvalidOptions()
Allows querying for the set of invalid options.

Returns:
Vector, the list of rejected options

getActiveOptions

public final java.util.Hashtable getActiveOptions()
Allows querying for the set of active options.

Returns:
Hashtable, containing the mapping of active options

getValidOptions

public final java.util.Hashtable getValidOptions()
Allows querying for the set of active options.

Returns:
Hashtable, containing the mapping of active options

isActiveOption

public boolean isActiveOption(java.lang.String pstrOption)
Checks whether supplied string option is active.

Parameters:
pstrOption - option to verify
Returns:
true if the option is active, false otherwise

isActiveOption

public boolean isActiveOption(int piOption)
Checks whether supplied integer option is active.

Parameters:
piOption - option to verify
Returns:
true if the option is active, false otherwise

isValidOption

public boolean isValidOption(java.lang.String pstrOption)
Checks whether supplied string option is valid.

Parameters:
pstrOption - option to verify
Returns:
true if the option is valid, false otherwise

isValidOption

public boolean isValidOption(int piOption)
Checks whether supplied integer option is valid.

Parameters:
piOption - option to verify
Returns:
true if the option is active, false otherwise

isInvalidOption

public boolean isInvalidOption(java.lang.String pstrOption)
Checks whether supplied string option is invalid.

Parameters:
pstrOption - option to verify
Returns:
true if the option is invalid, false otherwise

toString

public java.lang.String toString()
Converts the internals of the OptionProcessor to a string and returns it. Very useful for debugging.

Overrides:
toString in class java.lang.Object
Returns:
String representation of an OptionProcessor object

getMARFSourceCodeRevision

public static java.lang.String getMARFSourceCodeRevision()
Retrieves class' revision.

Returns:
revision string
Since:
0.3.0.2