Usage_Phases

Config Class Usage Phases

Parsing of the single-character option command line with Config class has three distinct phases:
1. Instantiate the Config parser. This configures the parser with the option string
+ Pass the command line argument array to the parser. The parser indicates whether or not all the demands for mandatory option value arguments have been satisfied.
+ Query the parser instance for options and argument values seen at the command line.

The Config class has not been designed with concern in thread safety, but by principle only the two first phases are thread-unsafe. From that time on, the obtained values are read-only, so using it simultaneously from several threads is possible.

1. Instantiation
The Config class provides two different constructors. Both of them require the option string as the first argument. The standard constructor Config(String) uses the default error handler.
The two-argument constructor Config(String, ErrorHandler) allows assignment of an alternate error handler just at the moment of instantiation, which ensures that even syntax errors found during the initialization phase when the option string is analyzed are routed through the that alternate error handler. That error handler is subsequently used in all operations of the parser as if set using setHandler() method.

2. Parsing command line arguments
An initialized instance of Config accepts the String[] with command line arguments as an argument to the parseArguments() method.
The mentioned method scans sequentially the array and switches on the options it has seen, eventually collecting their mandatory and/or optional argument values, and gathering the non-optional arguments. The method returns true when all used options requiring an argument value have been found to have at least one argument value specified.
Note that any option can be specified multiple times: while it does not have any effect on boolean options, for options with an argument value this results in the option having multiple argument values. For example, if your program specifies options "a:b:", then parsing the command line

program -a one -b two -a three -b four

will yield both options 'a' and 'b' switched on and the getOptionArgs() for option 'a' shall yield *String[] {"one", "three"} and for option 'b' String[] {"two", "four"}. See Option String page for details.

3. Querying parsed values
There are generally three types of queries issued to Config instances that should
1. find out, whether an option has been specified (seen) on the command line,
2. obtain the option argument values for a specific option, and
3. obtain the non-option argument values.
This queries can be issued anytime during the program run, and, considering the read-only nature of those queries, they should be thread-safe.
- To query the boolean status of the option, use the isOn(char option) method.
- To obtain the list of argument values specified for that option, use getOptionArgs(char option) method. This method returns:
- A non-empty array for every option for which the command line specified an argument value,
- an empty array for options that had no argument value specified, and
- null for options that haven't been specified in the option string.
- To obtain the array of non-option arguments, use getArguments() method. This method returns:
- A non-empty array if any non-option arguments have been found, or
- null when no non-option arguments have been specified.