org.das2.util

Class ArgumentList

java.lang.Object

org.das2.util.ArgumentList

public class ArgumentList
extends java.lang.Object

Utility class for processing the String[] arguments passed into the main routine, handing positional and switch parameters. Also automatically generates the usage documentation. Note in Autoplot's pngwalk, we add a parameter and positional argument with the same name. This should continue to be supported.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	FALSE
static java.lang.String	TRUE

Constructor Summary

Constructors

Constructor and Description
ArgumentList(java.lang.String programName) creates the processor for the program.

Method Summary

Modifier and Type	Method and Description
void	addBooleanSwitchArgument(java.lang.String name, java.lang.String abbrev, java.lang.String key, java.lang.String description) specify a named switch argument that is named, and we only care whether it was used or not.
void	addOptionalPositionArgument(int position, java.lang.String key, java.lang.String defaultValue, java.lang.String description) Specify the ith positional argument, which may be left unspecified by the user.
void	addOptionalSwitchArgument(java.lang.String name, java.lang.String abbrev, java.lang.String key, java.lang.String defaultValue, java.lang.String description) specify a named switch argument that may be specified by the user.
void	addPositionArgument(int position, java.lang.String key, java.lang.String description) Specify the ith positional argument.
void	addSwitchArgument(java.lang.String name, java.lang.String abbrev, java.lang.String key, java.lang.String description) specify a named switch argument that must be specified by the user.
boolean	getBooleanValue(java.lang.String key)
int	getExitCode() return 0 if the exit code for a checkArgs()==false is 0 or non-zero.
java.util.Map<java.lang.String,java.lang.String>	getMap() return a Map of all the specified values.
java.util.Map<java.lang.String,java.lang.String>	getOptions() returns a Map of optional arguments that were specified, so you can see exactly what was specified.
java.util.prefs.Preferences	getPreferences() returns the options as a java.util.prefs.Preferences object, for batch processes.
java.lang.String	getValue(java.lang.String key) get the value for this parameter
void	logPrefsSettings(java.util.logging.Logger logger) dump the configuration to the given logger at Level.CONFIG.
static java.lang.String	makeFileReferenceAbsolute(java.lang.String ref) make a standard way to make file names absolute
void	printPrefsSettings() see Vg1pws app for example use.
void	printUsage() print the usage statement out to stderr.
boolean	process(java.lang.String[] args) given the specification, process the argument list.
void	requireOneOf(java.lang.String[] keyNames) requires the user specify one of these values, otherwise the usage statement is printed.

Methods inherited from class java.lang.Object

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

Field Detail

FALSE

public static final java.lang.String FALSE

See Also:

Constant Field Values

TRUE

public static final java.lang.String TRUE

See Also:

Constant Field Values

Constructor Detail

ArgumentList

public ArgumentList(java.lang.String programName)

creates the processor for the program. programName is provided for the usage statement. After creating the object, arguments are specified one by one, and then the process method is called.

Parameters:

programName - the program name

Method Detail

getValue

public java.lang.String getValue(java.lang.String key)

get the value for this parameter

Parameters:

key - the argument identifier.

Returns:

the parameter's value.

Throws:

java.lang.IllegalArgumentException - if the parameter name was never described.

makeFileReferenceAbsolute

public static java.lang.String makeFileReferenceAbsolute(java.lang.String ref)

make a standard way to make file names absolute

Parameters:

ref - e.g. files/afile/foo.txt

Returns:

/home/jbf/data/files/afile/foo.txt because PWD is /home/jbf/data

getPreferences

public java.util.prefs.Preferences getPreferences()

returns the options as a java.util.prefs.Preferences object, for batch processes. The idea is that a process which grabs default settings from the user Preferences can instead get them from the command line, to support batch processes. See the Vg1pws app for an example of how this is used.

Returns:

a Preferences object, loaded with the command line values.

getBooleanValue

public boolean getBooleanValue(java.lang.String key)

addPositionArgument

public void addPositionArgument(int position,
                                java.lang.String key,
                                java.lang.String description)

Specify the ith positional argument.

Parameters:

position - the position number, 0 is the first argument position after the class name.

key - the internal reference name to get the value specified.

description - a short (40 character) description of the argument.

requireOneOf

public void requireOneOf(java.lang.String[] keyNames)

requires the user specify one of these values, otherwise the usage statement is printed.

Parameters:

keyNames - an array of internal key names that identify parameters.

addOptionalPositionArgument

public void addOptionalPositionArgument(int position,
                                        java.lang.String key,
                                        java.lang.String defaultValue,
                                        java.lang.String description)

Specify the ith positional argument, which may be left unspecified by the user. Note that all positional arguments after this one must also be optional.

Parameters:

position - the position number, 0 is the first argument position after the class name.

key - the internal reference name to get the value specified.

defaultValue - the value that is returned if a value is not provided by the user.

description - a short (40 character) description of the argument.

addSwitchArgument

public void addSwitchArgument(java.lang.String name,
                              java.lang.String abbrev,
                              java.lang.String key,
                              java.lang.String description)

specify a named switch argument that must be specified by the user. For example, --level=3 or -l=3

Parameters:

name - the long parameter name, which the user may enter. e.g. "level"

abbrev - short (one letter) parameter version. e.g. "l" for -l=3

key - the internal reference name to get the value specified, not necessarily but often the same as name.

description - a short (40 character) description of the argument.

addOptionalSwitchArgument

public void addOptionalSwitchArgument(java.lang.String name,
                                      java.lang.String abbrev,
                                      java.lang.String key,
                                      java.lang.String defaultValue,
                                      java.lang.String description)

specify a named switch argument that may be specified by the user. For example, --level=3 or -l=3

Parameters:

name - the long parameter name, which the user may enter. e.g. "level"

abbrev - short (one letter) parameter version. e.g. "l" for -l=3

defaultValue - value to return if the user doesn't specify. If TRUE or FALSE is used, then the user may use a number of different inputs such as "T" or "true", and getBooleanValue can be used to read the value

key - the internal reference name to get the value specified, not necessarily but often the same as name.

description - a short (40 character) description of the argument.

addBooleanSwitchArgument

public void addBooleanSwitchArgument(java.lang.String name,
                                     java.lang.String abbrev,
                                     java.lang.String key,
                                     java.lang.String description)

specify a named switch argument that is named, and we only care whether it was used or not. e.g. --debug

Parameters:

name - the long parameter name, which the user may enter. e.g. "level"

abbrev - short (one letter) parameter version. e.g. "l" for -l=3

key - the internal reference name to get the value specified, not necessarily but often the same as name.

description - a short (40 character) description of the argument.

printUsage

public void printUsage()

print the usage statement out to stderr.

getExitCode

public int getExitCode()

return 0 if the exit code for a checkArgs()==false is 0 or non-zero. It will be 0 if --help was used.

Returns:

the exit code.

getMap

public java.util.Map<java.lang.String,java.lang.String> getMap()

return a Map of all the specified values. The keys are all the internal String keys, and the values are all Strings.

Returns:

a Map of the specified values, including defaults.

getOptions

public java.util.Map<java.lang.String,java.lang.String> getOptions()

returns a Map of optional arguments that were specified, so you can see exactly what was specified.

Returns:

a Map of the specified values, without defaults.

process

public boolean process(java.lang.String[] args)

given the specification, process the argument list. If the list is in error, the usage statement is generated, and the System.exit is called (sorry!). Otherwise the method returns and getValue() may be used to retrieve the values. Again, note that System.exit may be called. This is probably a bad idea and another method will probably be added that would return true if processing was successful.

Parameters:

args - as in public static void main( String[] args ).

Returns:

false if System.exit should be called.

printPrefsSettings

public void printPrefsSettings()

see Vg1pws app for example use.

logPrefsSettings

public void logPrefsSettings(java.util.logging.Logger logger)

dump the configuration to the given logger at Level.CONFIG.

Parameters:

logger -