marf.util
Class OptionProcessor

java.lang.Object
  marf.util.OptionProcessor

All Implemented Interfaces:

IOptionProvider

public class OptionProcessor
extends java.lang.Object
implements IOptionProvider

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.38 2007/12/23 06:29:47 mokhov Exp $

Since:

0.3.0.2

Version:

$Revision: 1.38 $

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 options from a Hashtable by converting its contents to internal data structures.

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	addActiveOption(java.lang.String pstrOptionString) Allows adding a value option.
void	addActiveOption(java.lang.String pstrOptionString, java.lang.String pstrOptionValue) Allows adding a valid option to the set of valid options.
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	addValidOption(java.lang.String pstrOptionString) Allows adding a value 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	getArgumentString() Returns active and invalid options (in that order) in a form suitable to feed back as an argument string to an external application.
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 options from a Hashtable by converting its contents to internal data structures. This expects the Hashtable to contain String:Integer pairs; the pairs that do not conform to this requirement are added to the invalid options collection.

Parameters:

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

Method Detail

addActiveOption

public void addActiveOption(java.lang.String pstrOptionString,
                            java.lang.String pstrOptionValue)

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.

Specified by:

addActiveOption in interface IOptionProvider

Parameters:

pstrOptionString - option's name

pstrOptionValue - option's value

Since:

0.3.0.6

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.

Specified by:

addValidOption in interface IOptionProvider

Parameters:

piOptionCode - option's numerical code to use, a value

pstrOptionString - option's lexical representation, a key

addValidOption

public final void addValidOption(java.lang.String pstrOptionString)

Allows adding a value option. The code is computed from the option string using hash code.

Specified by:

addValidOption in interface IOptionProvider

Parameters:

pstrOptionString - option's lexical representation, a key

Since:

0.3.0.6

See Also:

IOptionProvider.addValidOption(java.lang.String)

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.

Specified by:

addValidOption in interface IOptionProvider

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.

Specified by:

addActiveOption in interface IOptionProvider

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

addActiveOption

public final void addActiveOption(java.lang.String pstrOptionString)

Allows adding a value option. The code is computed from the option string using hash code.

Specified by:

addActiveOption in interface IOptionProvider

Parameters:

pstrOptionString - option's lexical representation, a key

Since:

0.3.0.6

See Also:

IOptionProvider.addValidOption(java.lang.String)

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 compared to the currently active subset of them as well as possibly invalid options, which represent more of a dynamic state.

Specified by:

size in interface IOptionProvider

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.

Specified by:

getArgumentVector in interface IOptionProvider

Returns:

array of strings of active and invalid options

Since:

0.3.0.4

getArgumentString

public java.lang.String getArgumentString()

Returns active and invalid options (in that order) in a form suitable to feed back as an argument string to an external application.

Specified by:

getArgumentString in interface IOptionProvider

Returns:

a space-delimited String of active and invalid options

Since:

0.3.0.5

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 between 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.

Specified by:

getOption in interface IOptionProvider

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.

Specified by:

getOption in interface IOptionProvider

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.

Specified by:

getOption in interface IOptionProvider

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.

Specified by:

getOption in interface IOptionProvider

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.

Specified by:

getOptionArgument in interface IOptionProvider

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.

Specified by:

getOptionArgument in interface IOptionProvider

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.

Specified by:

getOptionArgument in interface IOptionProvider

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.

Specified by:

getOptionArgument in interface IOptionProvider

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.

Specified by:

getInvalidOptions in interface IOptionProvider

Returns:

Vector, the list of rejected options

getActiveOptions

public final java.util.Hashtable getActiveOptions()

Allows querying for the set of active options.

Specified by:

getActiveOptions in interface IOptionProvider

Returns:

Hashtable, containing the mapping of active options

getValidOptions

public final java.util.Hashtable getValidOptions()

Allows querying for the set of active options.

Specified by:

getValidOptions in interface IOptionProvider

Returns:

Hashtable, containing the mapping of active options

isActiveOption

public boolean isActiveOption(java.lang.String pstrOption)

Checks whether supplied string option is active.

Specified by:

isActiveOption in interface IOptionProvider

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.

Specified by:

isActiveOption in interface IOptionProvider

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.

Specified by:

isValidOption in interface IOptionProvider

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.

Specified by:

isValidOption in interface IOptionProvider

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.

Specified by:

isInvalidOption in interface IOptionProvider

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