|
qflib 0.98.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--de.qfs.lib.util.ArgsParser
This class implements convenient command line parsing. It is not as sophisticated as other command line parsers, e.g. the GNU getopt package, but it is easy to use and has a straightforward interface.
An ArgsParser reads options and their parameters from an array of strings, the standard format for command line arguments passed to an application's main method. Additional support is provided for reading options from a property file.
The options the ArgsParser expects can either be passed to the constructor,
or be set or modified with setOptions
or addOptions
.
During parsing, all arguments starting with '-' are interpreted as options. If an option has a required paramter, the following argument is used, causing a MalformedArgumentListException if no further arguments are given. If an option's parameter starts with '-', the option must be set in the form '-option=-value'.
If an option has an optional paramter, the argument following an option is
interpreted as that option's paramter, if it does not start with '-',
otherwise the options paramter remains empty and the following argument is
considered to be another option. This kind of guessing is suppressed, if
the option's parameter indicator is '=' (see setOptions
)
If an argument is of the form '-option=value' the option must have a required or optional parameter and its name and value are extracted accordingly.
Parsing stops when either the argument '--' is encountered, or an argument that is not a parameter and does not start with '-' is encoutered.
Additional options can be read from a property file. This file can be
specified in three ways: directly via setPropertyFile
, through a system property, or via a command line
argument, in increasing order of precedence. The property to use can be set
with setProperty
, the name of the option to interpret
as source for extra options with setDefaultOption
. In all cases the source may either be a file name or a
valid URL. Arguments from the command line take precedence over options
read from the property file, unless the option is allowed to have multiple
values, in which case the values are combined.
Inner Class Summary | |
static class |
ArgsParser.UnitTest
Test cases for the ArgsParser class. |
Constructor Summary | |
ArgsParser()
Create a new ArgsParser that will accept all options it encounters with an optional parameter. |
|
ArgsParser(java.lang.String[] opts)
Create a new ArgsParser, defining the options it should accept. |
Method Summary | |
void |
addOptions(java.lang.String[] opts)
Set some additional options the ArgsParser should know about. |
boolean |
getBoolean(java.lang.String name,
boolean deflt)
Get a boolean value from the parsed options. |
int |
getInt(java.lang.String name,
int deflt)
Get an int value from the parsed options. |
java.util.Hashtable |
getOptions()
Get the parsed command line options. |
java.lang.String |
getString(java.lang.String name,
java.lang.String deflt)
Get a String value from the parsed options. |
java.lang.String[] |
getStrings(java.lang.String name,
java.lang.String[] deflt)
Get a String array value from the parsed options. |
int |
parse(java.lang.String[] args)
Parse an array of command line options. |
void |
setDefault(java.lang.String name,
java.lang.String value)
Set a default value for an option. |
void |
setDefaultOption(java.lang.String option)
Set the option whose argument should be interpreted as source for the default options. |
void |
setOptions(java.lang.String[] opts)
Set the options the ArgsParser should know about. |
void |
setProperty(java.lang.String property)
Set the system property name for the default options. |
void |
setPropertyFile(java.lang.String name)
Set the file name or URL to read options from. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
public ArgsParser()
setOptions
with the single option definition '?*'.public ArgsParser(java.lang.String[] opts) throws java.lang.IllegalArgumentException
opts
- The options to set. See setOptions
for the format specification.java.lang.IllegalArgumentException
- If the option definitions are
incorrect.Method Detail |
public void setOptions(java.lang.String[] opts) throws java.lang.IllegalArgumentException
-name=value
syntax. This is very useful for boolean options that normally don't
require a parameter. If a boolean option is set in a properties file
and should be negated on the commandline, either a negative option must
be defined, or the option must accept a parameter. However if the '?'
indicator is used, setting such an option as the last one just before
the rest of the arguments would require the '--' separator to avoid
interpreting the first non-option argument as the option's parameter
value.
opts
- The options to set.java.lang.IllegalArgumentException
- If the option definitions are
incorrect.public void addOptions(java.lang.String[] opts) throws java.lang.IllegalArgumentException
opts
- The options to add. See setOptions
for the format specification.java.lang.IllegalArgumentException
- If the option definitions are
incorrect.public void setDefault(java.lang.String name, java.lang.String value) throws UnknownOptionException, MissingParameterException, UnexpectedParameterException
setOptions
or addOptions
and before parse
. For options with multiple values each default value will be part of the result, independent of whether the option was set on the command line or not.
name
- The name of the option.value
- The default value.UnknownOptionException
- If an option hasn't been defined.MissingParameterException
- If a required parameter is
missing.UnexpectedParameterException
- If an unexpected parameter is
encountered.public void setPropertyFile(java.lang.String name)
name
- The file name or URL to set.public final void setProperty(java.lang.String property)
property
- The property to set.public final void setDefaultOption(java.lang.String option)
setOptions
).option
- The option name to set, without leading '-'.public int parse(java.lang.String[] args) throws UnknownOptionException, MissingParameterException, UnexpectedParameterException
args
- The arguments from the command line.UnknownOptionException
- If an option hasn't been defined.MissingParameterException
- If a required parameter is
missing.UnexpectedParameterException
- If an unexpected parameter is
encountered.public java.util.Hashtable getOptions()
public java.lang.String getString(java.lang.String name, java.lang.String deflt)
name
- The name of the option to look up.deflt
- A default value in case the option is missing or the
value is not a String.public java.lang.String[] getStrings(java.lang.String name, java.lang.String[] deflt)
name
- The name of the option to look up.deflt
- A default value in case the option is missing or the
value is not a String array.public int getInt(java.lang.String name, int deflt)
name
- The name of the option to look up.deflt
- A default value in case the option is missing or the
value is not a Number.public boolean getBoolean(java.lang.String name, boolean deflt)
name
- The name of the option to look up.deflt
- A default value in case the option is missing.
|
qflib 0.98.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |