cz.phalanx.config

Class Config

java.lang.Object

cz.phalanx.config.Config

public class Config
extends Object

Class Config is a getopt-like command line argument parser mimicking the POSIX behavior of getopt. GNU longopts are not supported. The class usage has usually three phases:

1. Create the Config parser instance by calling its constructor, which accepts a getopt-style option string.
2. Let the instance parse the command line
3. Use access methods to find out whether an option is set or which arguments it has.

Command line arguments:
Config allows for three option types:

• a boolean option does not have any arguments. It is specified only by a single letter within the option string.
• an argument-mandatory option is denoted by a letter followed by a colon in the option string. When used at the command line, it must be followed by an argument, otherwise the parseArguments() returns false.
• an argument-optional option is denoted by a letter followed by a double colon. The option can be followed by an argument.

The option can be used multiple times at the command line. This has no effect on boolean options, but for argument-accepting options this allows for multiple values, for example -o opt1 -o opt2 sets the option 'o' on and assigns it a list of arguments ["opt1", "opt2"]. The options can be grouped, e.g. one can use -abc instead of -a -b -c. However, this has an effect on the argument-accepting options:

• when an option with mandatory argument is found in the middle of a group, the rest of the group is considered its argument. Thus if option string "ab:c" has been fed to the constructor, then parsing "-abc" does not set all three options up, but yields a=on, b=on, c=off and the 'b' option having the first argument value "c".
• when an option with optional argument is found in the middle of a group, it is considered having no argument and the parsing continues with the rest of the options. Changing the previous example to "ab::c" changes the parse result of "-abc" to a=on, b=on, c=on with b having no argument values.

Only the immediately following argument element is considered a value for an option accepting arguments. Any following arguments not prefixed with an option would be gathered to non-option arguments, i.e. for "ab:c" the "-ab" "one" "two" -c "three" would yield a=on, b=on, c=on, arguments of b = ["one"], and non-option arguments ["two", "three"]. The "three" string is included in non-option as -c is a boolean option and as such it cannot have argument.

An option character must not be '-' (minus) and ':' (colon).

To obtain the parsed values one calls parseArguments() with the argument array passed to main(), however any suitable array would do. This way the Config instances can be used for e.g. interprocess communication etc. When parseArguments() returns true, all the options used have been satisfied with the arguments. When the return value is false, at least one option requiring argument hasn't received any. The Config reports the missing information using the ErrorHandler (see below). A missing argument is not considered a fatal error by Config, which allows the programer to decide whether or not to continue with processing.

The access to the parsed values is quite simple:

• to find out whether an option has been specified, query the instance with the isOn() method
• to obtain the list of arguments that have been specified at the command line for a specific option, query the instance with getOptionArgs()
• to obtain the non-option arguments, query the instance with getArguments()

Fine-tuning:
The class has a default built-in ErrorHandler, which simply uses System.err to print out the messages. If you need a different approach (e.g. GUI applications are most likely to display dialog boxes instead of writing to the console), write your class implementing the Config.ErrorHandler interface and pass it to the instance using setHandler(), or use the alternative constructor to pass the error handler at the beginning. The later method has an advantage - you get the error messages for incorrectly specified option strings through your handler as well.

Example code snippet:

        public static void main(String ... args)
        {
                // construct the parser:
                Config config = new Config("ab:c::d");
                // parse the arguments
                if (!config.parseArguments(args))
                        System.exit(1); // the error is already written
                else
                {
                        // process the arguments. For a command line like:
                        // example -abone -cb two -a three -c four five
                        // yields this results:
                        //config.isOn('a') == true;
                        //config.isOn('b') == true;
                        //config.isOn('c') == true;
                        //config.isOn('d') == false;
                        //config.getOptionArgs('b') is {"one", "two"}
                        //config.getOptionArgs('c') is {"four"}
                        //config.getArguments() is {"three", "five"}
 
                        for (char opt: "abcd".toCharArray())
                        {
                                if (config.isOn(opt))
                                {
                                        System.out.println("Option `"+opt+"' is on.");
                                        String[] optarg = config.getOptionArgs(opt);
                                        if (optargs.length > 0)
                                        {
                                                System.out.print("Option `"+opt+"' has following values:");
                                                for (String optval: optarg)
                                                        System.out.print(" "+optval);
                                                System.out.println();
                                        }
                                }
                                else
                                        System.out.println("Option `"+opt+"' is off.");
                        }
                        System.out.print("Non-option arguments:");
                        for (String optval: config.getArguments())
                                System.out.print(" "+optval);
                        System.out.println();
                }
        }
        

Version:

1.2

Author:

Rene Lauer (ray@phalanx.cz)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Config.ErrorHandler ErrorHandler is used to report errors.

Constructor Summary

Constructors

Constructor and Description
Config(String config) Standard constructor.
Config(String config, Config.ErrorHandler handler) The constructor that allows change of the ErrorHandler.

Method Summary

Methods

Modifier and Type	Method and Description
String[]	getArguments() Return an array of non-option arguments, i.e. the strings that have been found at the command line not belonging to any of the options.
Config.ErrorHandler	getHandler() Return the current ErrorHandler of the instance.
String[]	getOptionArgs(char option) Return an array of the option argument values as scanned at the command line.
boolean	isOn(char option) Answer whether the specified option has been seen on the command line.
boolean	parseArguments(String... args) Scan sequentially the elements of the argument array and set the option values accordingly.
void	setHandler(Config.ErrorHandler handler) Set the alternative error handler.

Methods inherited from class java.lang.Object

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

Constructor Detail

Config

public Config(String config)

Standard constructor. When used, errors found during the initialization phase (option string parsing) are reported using the default error handler. The config string has the following regex syntax:
([^- :\t]:?:?)+ - it allows any character different from minus, colon, space and tab to become an option character. It can be followed by one (=mandatory) or two (=optional) colons specifying the demand for argument value.

Parameters:

config - the option string

Config

public Config(String config,
      Config.ErrorHandler handler)

The constructor that allows change of the ErrorHandler. Using this constructor, the errors encountered during parsing the argument shall be reported through the specified error handler. See the standard constructor for further details on the option string syntax.

Parameters:

config - option string

handler - the handler to use for error reporting

Method Detail

parseArguments

public boolean parseArguments(String... args)

Scan sequentially the elements of the argument array and set the option values accordingly. This method is the actual workhorse of the class. The argument array should have the same form as the array passed to main(), although it can be truncated, extended or obtained elsewhere. Two strings are handled specially:

• A single dash or minus (-) is handled as an option value. This is necessary for the usus of specifying minus in the place of a filename whenever standard input or output is to be used
• A double dash (--) switches off the option recognition. After this is encountered, any following strings are merely added to the non-option arguments

Otherwise, if the string begins with a dash (-), it is considered to be an option. If such option hasn't been specified in the option string, a warning is issued and the option is ignored. When recognized, the option is set to ON and depending on whether the option requires or allows for an argument value the scanning of the following string is adjusted.

Parameters:

args - the argument array in the main() style

Returns:

true when the parsing has been successful, false when at least one argument-requiring option hasn't been satisfied

Throws:

IllegalStateException - whenever an error handler is undefined

getHandler

public Config.ErrorHandler getHandler()

Return the current ErrorHandler of the instance.

Returns:

an error handler either previously set by setHandler or the default one

setHandler

public final void setHandler(Config.ErrorHandler handler)

Set the alternative error handler. All subsequent messages shall be routed through the specified handler instead of the one that was used until the call.

Parameters:

handler - a class that implements ErrorHandler interface

isOn

public boolean isOn(char option)

Answer whether the specified option has been seen on the command line. When the parseArguments method identifies the option on the command line, it sets it on. The default implementation has no way of switching the once-turned-on options back off. For example, if -c is seen somewhere in the argument array, then isOn('c') returns true. Any undefined option is off by default, so this method returns false on any character that hasn't been found in the option string.

Parameters:

option - the option character used to discern the option at the command line

Returns:

true when the option has been seen (regardless of argument values)

getOptionArgs

public String[] getOptionArgs(char option)

Return an array of the option argument values as scanned at the command line. The order of the values is not guaranteed, although it usually follows the same order in which the argument values have been found at the command line.

Parameters:

option - the option character

Returns:

a (possibly empty) array of strings for defined options, null for undefined options

getArguments

public String[] getArguments()

Return an array of non-option arguments, i.e. the strings that have been found at the command line not belonging to any of the options. The array order is not guaranteed, although the default implementation returns them usually in the order as found in the array.

Returns:

a string array or null