qflib 0.98.1

de.qfs.lib.util
Class ArgsParser

java.lang.Object
  |
  +--de.qfs.lib.util.ArgsParser

public class ArgsParser
extends java.lang.Object

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.

Version:
$Revision: 1.10 $
Author:
Gregor Schmid

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

ArgsParser

public ArgsParser()
Create a new ArgsParser that will accept all options it encounters with an optional parameter. Using this constructor is equivalent to calling setOptions with the single option definition '?*'.

ArgsParser

public ArgsParser(java.lang.String[] opts)
           throws java.lang.IllegalArgumentException
Create a new ArgsParser, defining the options it should accept.
Parameters:
opts - The options to set. See setOptions for the format specification.
Throws:
java.lang.IllegalArgumentException - If the option definitions are incorrect.
Method Detail

setOptions

public void setOptions(java.lang.String[] opts)
                throws java.lang.IllegalArgumentException
Set the options the ArgsParser should know about. Each String in the array designates one option (or multiple similar ones) and must have the following format:

addOptions

public void addOptions(java.lang.String[] opts)
                throws java.lang.IllegalArgumentException
Set some additional options the ArgsParser should know about.
Parameters:
opts - The options to add. See setOptions for the format specification.
Throws:
java.lang.IllegalArgumentException - If the option definitions are incorrect.

setDefault

public void setDefault(java.lang.String name,
                       java.lang.String value)
                throws UnknownOptionException,
                       MissingParameterException,
                       UnexpectedParameterException
Set a default value for an option. This must be called after initializing all options with 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.

Parameters:
name - The name of the option.
value - The default value.
Throws:
UnknownOptionException - If an option hasn't been defined.
MissingParameterException - If a required parameter is missing.
UnexpectedParameterException - If an unexpected parameter is encountered.
Since:
0.98.0

setPropertyFile

public void setPropertyFile(java.lang.String name)
Set the file name or URL to read options from.
Parameters:
name - The file name or URL to set.

setProperty

public final void setProperty(java.lang.String property)
Set the system property name for the default options.
Parameters:
property - The property to set.

setDefaultOption

public final void setDefaultOption(java.lang.String option)
Set the option whose argument should be interpreted as source for the default options. You should specify this option as requiring an argument (see setOptions).
Parameters:
option - The option name to set, without leading '-'.

parse

public int parse(java.lang.String[] args)
          throws UnknownOptionException,
                 MissingParameterException,
                 UnexpectedParameterException
Parse an array of command line options.
Parameters:
args - The arguments from the command line.
Returns:
The index of the first non-option argument on the command line.
Throws:
UnknownOptionException - If an option hasn't been defined.
MissingParameterException - If a required parameter is missing.
UnexpectedParameterException - If an unexpected parameter is encountered.

getOptions

public java.util.Hashtable getOptions()
Get the parsed command line options. The keys are the options and the values are their parameters, where the empty String can either mean no parameter or an empty one. For options with multiple parameters the value is a String array.
Returns:
The parsed options.

getString

public java.lang.String getString(java.lang.String name,
                                  java.lang.String deflt)
Get a String value from the parsed options.
Parameters:
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.
Returns:
The option value or the default.
Since:
0.98.0

getStrings

public java.lang.String[] getStrings(java.lang.String name,
                                     java.lang.String[] deflt)
Get a String array value from the parsed options.
Parameters:
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.
Returns:
The option value or the default.
Since:
0.98.0

getInt

public int getInt(java.lang.String name,
                  int deflt)
Get an int value from the parsed options.
Parameters:
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.
Returns:
The option value or the default.
Since:
0.98.0

getBoolean

public boolean getBoolean(java.lang.String name,
                          boolean deflt)
Get a boolean value from the parsed options.
Parameters:
name - The name of the option to look up.
deflt - A default value in case the option is missing.
Returns:
The option value or the default. This is a special case of a String to boolean conversion, since the empty String also means true.
Since:
0.98.0

qflib 0.98.1