com.bristle.javalib.util
Class GetOpt

java.lang.Object
  com.bristle.javalib.util.GetOpt

public class GetOpt
extends Object

This class contains utility routines for extracting positional arguments and named options from any "option source" (the command line or any specified array, List, Iterator, Enumeration, Map, etc.). It handles required values, default values, conversion of values to various data types (String, Boolean, Integer, Float, etc.), checking values against constraints (min, max, etc.), and other argument and option processing features.

Usage:
   - A typical scenario for extracting positional arguments and named options 
     from the command line is:
       public static void main(String[] args)
       { 
           GetOpt getopt = new GetOpt(args);
           Integer intWidth  = GetOpt.getOptionInteger("width");
           Integer intHeight = GetOpt.getOptionInteger("height");
           String strFilename = GetOpt.getNextArgString();
       } 

   - To extract positional arguments and named options from a List:
       GetOpt getopt = new GetOpt(list);
       Integer intWidth  = GetOpt.getOptionInteger("width");
       Integer intHeight = GetOpt.getOptionInteger("height");
       String strFilename = GetOpt.getNextArgString();

   - To extract values from a Map (for example, the parameter Map of a 
     ServletRequest) via key value:
       GetOpt getopt = new GetOpt(request.getParameterMap());
       Integer intWidth  = GetOpt.getOptionInteger("width");
       Integer intHeight = GetOpt.getOptionInteger("height");
     Note:  The getNextArg...() methods don't apply when the option source 
            is a Map, rather than an ordered array or List.

   - To operate on an Iterator:
       GetOpt getopt = new GetOpt(ListUtil.toList(iterator));

   - To operate on an Enumeration:
       GetOpt getopt = new GetOpt(ListUtil.toList(enum));

   - To operate on parallel arrays of option names and values, or parallel
     Lists, parallel Iterators, or parallel Enumerations, use one of:
       GetOpt getopt = new GetOpt(MapUtil.createMap(arr1, arr2));
       GetOpt getopt = new GetOpt(MapUtil.createMap(list1, list2));
       GetOpt getopt = new GetOpt(MapUtil.createMap(iter1, iter2));
       GetOpt getopt = new GetOpt(MapUtil.createMap(enum1, enum2));

   - See the source code of the inner Tester class for more examples.
  
Assumptions:
Effects:
       - The various get...() methods return the requested value if present
         in the option source, and delete it from the internally stored copy 
         of the option source, similar to way the "shift" operation in Unix 
         shell scripts, perl scripts, and Windows batch files delete values
         from the parameter list specified on the command line.    
         Therefore, you should make all calls to getOption...() first, to 
         extract the options and then make all calls to getNextArg...() in 
         the expected order of the remaining positional arguments.
Anticipated Changes:
Notes:
Implementation Notes:
Portability Issues:
Revision History:
   $Log$

Nested Class Summary

static class	GetOpt.DefaultBoolean This class represents a default value for an Boolean.
static class	GetOpt.DefaultInteger This class represents a default value for an Integer.
static class	GetOpt.DefaultString This class represents a default value for a String.
static class	GetOpt.LessThanMinException This exception is thrown when a numeric value is less than the specified minimum.
static class	GetOpt.MaxInteger This class represents a maximum allowable value for an Integer.
static class	GetOpt.MinInteger This class represents a minimum allowable value for an Integer.
static class	GetOpt.MissingArgException This exception is thrown when a required argument is missing or null.
static class	GetOpt.MissingOptionException This exception is thrown when a required option is missing.
static class	GetOpt.MissingValueException This exception is thrown when an option with a required value has a missing or null value.
static class	GetOpt.MoreThanMaxException This exception is thrown when a numeric value is more than the specified maximum.
static class	GetOpt.NotAnIntegerException This exception is thrown when a value required to be an integer was not.
static class	GetOpt.Required This class represents a value that specifies whether arguments and options are required.
static class	GetOpt.Tester Each class contains a Tester inner class with a main() for easier unit testing.
static class	GetOpt.ValueRequired This class represents a value that specifies whether options are required to have values.

Field Summary

private List	m_list The remaining portions of the option source when it was specified as an array or List.
private Map	m_map The remaining portions of the option source when it was specified as a Map.

Constructor Summary

GetOpt(List list)
Constructor.

GetOpt(Map map)
Constructor.

GetOpt(String[] args)
Constructor.

Method Summary

int	findOptionInList(String strName) Get the zero-based index of the specified option in the previously specified option source, or -1 if not found.
Integer	getNextArgInteger() Return the next argument from the previously specified option source, defaulting to null.
Integer	getNextArgInteger(GetOpt.Required required) Return the next argument from the previously specified option source, defaulting to null.
Integer	getNextArgInteger(GetOpt.Required required, GetOpt.DefaultInteger intDefault) Return the next argument from the previously specified option source, defaulting to the specified value.
Integer	getNextArgInteger(GetOpt.Required required, GetOpt.DefaultInteger intDefault, GetOpt.MinInteger intMin, GetOpt.MaxInteger intMax) Return the next argument from the previously specified option source, defaulting to the specified value.
String	getNextArgString() Return the next argument from the previously specified option source, defaulting to null.
String	getNextArgString(GetOpt.Required required) Return the next argument from the previously specified option source, defaulting to null.
String	getNextArgString(GetOpt.Required required, GetOpt.DefaultString strDefault) Return the next argument from the previously specified option source, defaulting to the specified value.
Integer	getOptionInteger(String strName) Return an Integer option from the previously specified option source, defaulting to null.
Integer	getOptionInteger(String strName, GetOpt.Required optionRequired, GetOpt.ValueRequired valueRequired) Return an Integer option from the previously specified option source, defaulting to null.
Integer	getOptionInteger(String strName, GetOpt.Required optionRequired, GetOpt.ValueRequired valueRequired, GetOpt.DefaultInteger intDefault) Return an Integer option from the previously specified option source.
Integer	getOptionInteger(String strName, GetOpt.Required optionRequired, GetOpt.ValueRequired valueRequired, GetOpt.DefaultInteger intMissingOptionDefault, GetOpt.DefaultInteger intMissingValueDefault) Return an Integer option from the previously specified option source.
Integer	getOptionInteger(String strName, GetOpt.Required optionRequired, GetOpt.ValueRequired valueRequired, GetOpt.DefaultInteger intMissingOptionDefault, GetOpt.DefaultInteger intMissingValueDefault, GetOpt.MinInteger intMin, GetOpt.MaxInteger intMax) Return an Integer option from the previously specified option source.
Boolean	getOptionPresent(String strName) Return Boolean.TRUE if the specified option is present on the previously specified option source, null otherwise.
Boolean	getOptionPresent(String strName, GetOpt.Required optionRequired) Return Boolean.TRUE if the specified option is present on the previously specified option source, null otherwise.
Boolean	getOptionPresent(String strName, GetOpt.Required optionRequired, GetOpt.DefaultBoolean blnDefault) Return Boolean.TRUE if the specified option is present on the previously specified option source, blnDefault otherwise.
String	getOptionString(String strName) Return a String option from the previously specified option source, defaulting to null.
String	getOptionString(String strName, GetOpt.Required optionRequired, GetOpt.ValueRequired valueRequired) Return a String option from the previously specified option source, defaulting to null.
String	getOptionString(String strName, GetOpt.Required optionRequired, GetOpt.ValueRequired valueRequired, GetOpt.DefaultString strDefault) Return a String option from the previously specified option source.
String	getOptionString(String strName, GetOpt.Required optionRequired, GetOpt.ValueRequired valueRequired, GetOpt.DefaultString strMissingOptionDefault, GetOpt.DefaultString strMissingValueDefault) Return a String option from the previously specified option source.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_list

private List m_list

The remaining portions of the option source when it was specified as an array or List. Note: Only one of m_list or m_map is valued.

m_map

private Map m_map

The remaining portions of the option source when it was specified as a Map. Note: Only one of m_list or m_map is valued.

Constructor Detail

GetOpt

public GetOpt(String[] args)

Constructor.

Parameters:

args - Option source.

GetOpt

public GetOpt(List list)

Constructor.

Parameters:

list - Option source.

GetOpt

public GetOpt(Map map)

Constructor.

Parameters:

map - Option source.

Method Detail

getNextArgString

public String getNextArgString(GetOpt.Required required,
                               GetOpt.DefaultString strDefault)
                        throws GetOpt.MissingArgException

Return the next argument from the previously specified option source, defaulting to the specified value. Note: This removes the argument from the internally stored option source, so the next call returns a different argument.

Parameters:

required - Flag indicating whether the argument is required to be present and not null in the option source.

strDefault - Default value, if argument has missing or null value in the option source.

Returns:

Argument value.

Throws:

GetOpt.MissingArgException - When argument is required but missing or null.

getNextArgString

public String getNextArgString(GetOpt.Required required)
                        throws GetOpt.MissingArgException

Return the next argument from the previously specified option source, defaulting to null. Note: This removes the argument from the internally stored option source, so the next call returns a different argument.

Parameters:

required - Flag indicating whether the argument is required to be present and not null in the option source.

Returns:

Argument value.

Throws:

GetOpt.MissingArgException - When argument is required but missing or null.

getNextArgString

public String getNextArgString()

Return the next argument from the previously specified option source, defaulting to null. Note: This removes the argument from the internally stored option source, so the next call returns a different argument.

Returns:

Argument value.

getNextArgInteger

public Integer getNextArgInteger(GetOpt.Required required,
                                 GetOpt.DefaultInteger intDefault,
                                 GetOpt.MinInteger intMin,
                                 GetOpt.MaxInteger intMax)
                          throws GetOpt.MissingArgException,
                                 GetOpt.NotAnIntegerException,
                                 GetOpt.LessThanMinException,
                                 GetOpt.MoreThanMaxException

Return the next argument from the previously specified option source, defaulting to the specified value. Note: This removes the argument from the internally stored option source, so the next call returns a different argument.

Parameters:

required - Flag indicating whether the argument is required to be present and not null in the option source.

intDefault - Default value, if argument has missing or null value in the option source.

intMin - Minimum acceptable value, or null for unrestricted. Note: Only applies when the argument value (whether from the option source or from the default) is not null.

intMax - Maximum acceptable value, or null for unrestricted. Note: Only applies when the argument value (whether from the option source or from the default) is not null.

Returns:

Argument value.

Throws:

GetOpt.MissingArgException - When argument is required but missing or null.

GetOpt.NotAnIntegerException - When argument is not an integer.

GetOpt.LessThanMinException - When argument is less than the specified min.

GetOpt.MoreThanMaxException - When argument is more than the specified max.

getNextArgInteger

public Integer getNextArgInteger(GetOpt.Required required,
                                 GetOpt.DefaultInteger intDefault)
                          throws GetOpt.MissingArgException,
                                 GetOpt.NotAnIntegerException

Return the next argument from the previously specified option source, defaulting to the specified value. Note: This removes the argument from the internally stored option source, so the next call returns a different argument.

Parameters:

required - Flag indicating whether the argument is required to be present and not null in the option source.

intDefault - Default value, if argument has missing or null value in the option source.

Returns:

Argument value.

Throws:

GetOpt.MissingArgException - When argument is required but missing or null.

GetOpt.NotAnIntegerException - When argument is not an integer.

getNextArgInteger

public Integer getNextArgInteger(GetOpt.Required required)
                          throws GetOpt.MissingArgException,
                                 GetOpt.NotAnIntegerException

Return the next argument from the previously specified option source, defaulting to null. Note: This removes the argument from the internally stored option source, so the next call returns a different argument.

Parameters:

required - Flag indicating whether the argument is required to be present and not null in the option source.

Returns:

Argument value.

Throws:

GetOpt.MissingArgException - When argument is required but missing or null.

GetOpt.NotAnIntegerException - When argument is not an integer.

getNextArgInteger

public Integer getNextArgInteger()
                          throws GetOpt.NotAnIntegerException

Return the next argument from the previously specified option source, defaulting to null. Note: This removes the argument from the internally stored option source, so the next call returns a different argument.

Returns:

Argument value.

Throws:

GetOpt.NotAnIntegerException - When argument is not an integer.

findOptionInList

public int findOptionInList(String strName)

Get the zero-based index of the specified option in the previously specified option source, or -1 if not found.

Parameters:

strName - Name of option (e.g., "width" for -width option).

Returns:

Option index

getOptionPresent

public Boolean getOptionPresent(String strName,
                                GetOpt.Required optionRequired,
                                GetOpt.DefaultBoolean blnDefault)
                         throws GetOpt.MissingOptionException

Return Boolean.TRUE if the specified option is present on the previously specified option source, blnDefault otherwise. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

blnDefault - Default value, if option not found in the option source.

Returns:

Boolean indicating presence of option.

Throws:

GetOpt.MissingOptionException - When option is required but missing.

getOptionPresent

public Boolean getOptionPresent(String strName,
                                GetOpt.Required optionRequired)
                         throws GetOpt.MissingOptionException

Return Boolean.TRUE if the specified option is present on the previously specified option source, null otherwise. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

Returns:

Boolean indicating presence of option.

Throws:

GetOpt.MissingOptionException - When option is required but missing.

getOptionPresent

public Boolean getOptionPresent(String strName)

Return Boolean.TRUE if the specified option is present on the previously specified option source, null otherwise. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

Returns:

Boolean indicating presence of option.

getOptionString

public String getOptionString(String strName,
                              GetOpt.Required optionRequired,
                              GetOpt.ValueRequired valueRequired,
                              GetOpt.DefaultString strMissingOptionDefault,
                              GetOpt.DefaultString strMissingValueDefault)
                       throws GetOpt.MissingOptionException,
                              GetOpt.MissingValueException

Return a String option from the previously specified option source. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

valueRequired - Flag indicating whether the option is required to have a non-null value when it occurs in the option source.

strMissingOptionDefault - Default value, if option not found in the option source.

strMissingValueDefault - Default value, if option found in the option source with missing or null value.

Returns:

Option value

Throws:

GetOpt.MissingOptionException - When option is missing from option source.

GetOpt.MissingValueException - When option has missing or null value.

getOptionString

public String getOptionString(String strName,
                              GetOpt.Required optionRequired,
                              GetOpt.ValueRequired valueRequired,
                              GetOpt.DefaultString strDefault)
                       throws GetOpt.MissingOptionException,
                              GetOpt.MissingValueException

Return a String option from the previously specified option source. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

valueRequired - Flag indicating whether the option is required to have a non-null value when it occurs in the option source.

strDefault - Default value, if option not found in the option source or option found in the option source with missing or null value.

Returns:

Option value

Throws:

GetOpt.MissingOptionException - When option is missing from option source.

GetOpt.MissingValueException - When option has missing or null value.

getOptionString

public String getOptionString(String strName,
                              GetOpt.Required optionRequired,
                              GetOpt.ValueRequired valueRequired)
                       throws GetOpt.MissingOptionException,
                              GetOpt.MissingValueException

Return a String option from the previously specified option source, defaulting to null. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

valueRequired - Flag indicating whether the option is required to have a non-null value when it occurs in the option source.

Returns:

Option value

Throws:

GetOpt.MissingOptionException - When option is missing from option source.

GetOpt.MissingValueException - When option has missing or null value.

getOptionString

public String getOptionString(String strName)

Return a String option from the previously specified option source, defaulting to null. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

Returns:

Option value

getOptionInteger

public Integer getOptionInteger(String strName,
                                GetOpt.Required optionRequired,
                                GetOpt.ValueRequired valueRequired,
                                GetOpt.DefaultInteger intMissingOptionDefault,
                                GetOpt.DefaultInteger intMissingValueDefault,
                                GetOpt.MinInteger intMin,
                                GetOpt.MaxInteger intMax)
                         throws GetOpt.MissingOptionException,
                                GetOpt.MissingValueException,
                                GetOpt.NotAnIntegerException,
                                GetOpt.LessThanMinException,
                                GetOpt.MoreThanMaxException

Return an Integer option from the previously specified option source. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

valueRequired - Flag indicating whether the option is required to have a non-null value when it occurs in the option source.

intMissingOptionDefault - Default value, if option not found in the option source.

intMissingValueDefault - Default value, if option found in the option source with missing or null value.

intMin - Minimum acceptable value, or null for unrestricted. Note: Only applies when the option value (whether from the option source or from the default) is not null.

intMax - Maximum acceptable value, or null for unrestricted. Note: Only applies when the option value (whether from the option source or from the default) is not null.

Returns:

Option value

Throws:

GetOpt.MissingOptionException - When option is missing from option source.

GetOpt.MissingValueException - When option has missing or null value.

GetOpt.NotAnIntegerException - When option value is not an integer.

GetOpt.LessThanMinException - When option value is less than the specified min.

GetOpt.MoreThanMaxException - When option value is more than the specified max.

getOptionInteger

public Integer getOptionInteger(String strName,
                                GetOpt.Required optionRequired,
                                GetOpt.ValueRequired valueRequired,
                                GetOpt.DefaultInteger intMissingOptionDefault,
                                GetOpt.DefaultInteger intMissingValueDefault)
                         throws GetOpt.MissingOptionException,
                                GetOpt.MissingValueException,
                                GetOpt.NotAnIntegerException

Return an Integer option from the previously specified option source. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

valueRequired - Flag indicating whether the option is required to have a non-null value when it occurs in the option source.

intMissingOptionDefault - Default value, if option not found in the option source.

intMissingValueDefault - Default value, if option found in the option source with missing or null value.

Returns:

Option value

Throws:

GetOpt.MissingOptionException - When option is missing from option source.

GetOpt.MissingValueException - When option has missing or null value.

GetOpt.NotAnIntegerException - When option value is not an integer.

getOptionInteger

public Integer getOptionInteger(String strName,
                                GetOpt.Required optionRequired,
                                GetOpt.ValueRequired valueRequired,
                                GetOpt.DefaultInteger intDefault)
                         throws GetOpt.MissingOptionException,
                                GetOpt.MissingValueException,
                                GetOpt.NotAnIntegerException

Return an Integer option from the previously specified option source. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

valueRequired - Flag indicating whether the option is required to have a non-null value when it occurs in the option source.

intDefault - Default value, if option not found in the option source or option found in the option source with missing or null value.

Returns:

Option value

Throws:

GetOpt.MissingOptionException - When option is missing from option source.

GetOpt.MissingValueException - When option has missing or null value.

GetOpt.NotAnIntegerException - When option value is not an integer.

getOptionInteger

public Integer getOptionInteger(String strName,
                                GetOpt.Required optionRequired,
                                GetOpt.ValueRequired valueRequired)
                         throws GetOpt.MissingOptionException,
                                GetOpt.MissingValueException,
                                GetOpt.NotAnIntegerException

Return an Integer option from the previously specified option source, defaulting to null. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

optionRequired - Flag indicating whether the option is required to be present in the option source.

valueRequired - Flag indicating whether the option is required to have a non-null value when it occurs in the option source.

Returns:

Option value

Throws:

GetOpt.MissingOptionException - When option is missing from option source.

GetOpt.MissingValueException - When option has missing or null value.

GetOpt.NotAnIntegerException - When option value is not an integer.

getOptionInteger

public Integer getOptionInteger(String strName)
                         throws GetOpt.NotAnIntegerException

Return an Integer option from the previously specified option source, defaulting to null. Note: When the option source is an Array or List, this removes the option from the internally stored option source, so subsequent calls would not find it present again.

Parameters:

strName - Name of option (e.g., "width" for -width option).

Returns:

Option value

Throws:

GetOpt.NotAnIntegerException - When option value is not an integer.