satin.common
Class CmdLineParser

java.lang.Object
  |
  +--satin.common.CmdLineParser

public class CmdLineParser
extends java.lang.Object

Parses command lines that are passed to a Java main method. This class allows you to define the syntax for the command-line arguments that are passed to a Java program when it is launched, and made available through the argument to the main method. Java treats a command line as a series of tokens which are delimited by whitespace or enclosed by double quotes. This class recognizes three fundamental kinds of tokens:

• Switches begin with the hyphen character "-". For example, the "-verbose" switch for the Java compiler "javac".
• Switch Arguments are tokens that may follow a switch and are associated with it. For example, the Java compiler has a switch "-d" for specifying the output directory; the name of the output directory following the switch is a switch argument.
• Non-Switch Arguments are tokens which are neither switches nor switch arguments. For example, the name of the source file that is passed to the Java compiler.

The command-line syntax recognized by this class is as follows:

command_line	:= [element [whitespace element]...]
element	:= non_switch | (switch [arg_list])
arg_list	:= (whitespace switch_arg)...
switch_arg	:= token
switch	:= "-" token
non_switch	:= token
token	:= any sequence of non-space characters, not beginning with "-" | any sequence of characters enclosed in double-quotes
whitespace	:= space | tab

Each defined switch may appear at most once in a command line; including the same switch twice will result in a run-time exception being thrown. The following kinds of switches are currently supported:

Boolean Switch

This kind of switch has no arguments; each switch is either present or not present.

String Switch

This switch expects a single string argument to follow it.

Integer Switch

This switch expects a single integer argument to follow it.

String List Switch

This switch expects one or more string arguments to follow it, up to (but not including) the next switch, or the end of the command line.

Integer List Switch

This switch expects one or more integer arguments to follow it, up to (but not including) the next non-integer argument, or the end of the command line.

Help Switch

The switches "-help" and "-?" are pre-defined by the CmdLineParser class. If one of these switches is present on the commmand line, the parser displays a help message and then terminates the program.

The parser recognizes any non-ambiguous prefix for a switch. That is, if you define a switch named "foobar", the parser will recognize "-foo" as matching that switch, as long as there are no other switches beginning with "-foo". Switches are not case-sensitive.

How to Use It

1. Instantiate a CmdLineParser object.

2. Instantiate whatever BooleanHolder, IntHolder, StringBuffer, and/or Vector objects you will need to receive the results of parsing the command line. Initialize them with whatever default values you want to use if the corresponding switch doesn't appear in the command line.

3. Define your switches by calling the appropriate define*** methods, passing them the appropriate value objects you instantiated in the previous step.

4. Call parse to parse the command line arguments. If any errors are encountered, parse will throw a SyntaxError.

5. The value objects you created in step 2 will now contain whatever information was provided on the command line.

Example

 public class MyProgram
 {
     public static void main (String[] args)
     {
         CmdLineParser clp = new CmdLineParser();

         // create the value objects
         BooleanHolder simple = new BooleanHolder(false);
         IntHolder oneInt = new IntHolder(0);
         StringBuffer oneString = new StringBuffer();

         // define the switches
         clp.defineSwitch("simple", simple, "A simple switch.");
         clp.defineIntSwitch("oneInt", oneInt, "One integer.");
         clp.defineStringSwitch("oneString", oneString, 
             "This is a switch that takes a single string as an argument.");

         // parse the command line
         clp.parse(args);

         // display the results
         System.out.println("simple" + (simple.value ? " " : " NOT ") + "specified");
         System.out.println("oneInt = " + oneInt.value);
         System.out.println("oneString = " + oneString.toString());
     }
 }

At runtime, you might invoke this program as follows:

java MyProgram -simple
java MyProgram -oneInt 4 java MyProgram -oneString Hello java MyProgram -oneStr "hello, world" java MyProgram -simple -oneInt 10 -oneString foobar

Author:

Ed Stauff

Inner Class Summary

static class

CmdLineParser.SyntaxError Indicates a syntax error in a command line.

Constructor Summary

CmdLineParser()
Constructs a command line parser.

Method Summary

void	defineHelp(java.lang.String help) Defines a help overview message.
void	defineIntSwitch(java.lang.String switchName, int[] values, java.lang.String help) Defines an integer list switch.
void	defineIntSwitch(java.lang.String switchName, IntHolder valueRcvr, java.lang.String help) Defines an integer switch.
void	defineIntSwitch(java.lang.String switchName, java.util.Vector values, java.lang.String help) Defines an integer list switch.
void	defineNonSwitch(java.lang.String[] values, java.lang.String help) Defines where to put non-switch arguments.
void	defineNonSwitch(java.util.Vector values, java.lang.String help) Defines where to put non-switch arguments.
void	defineStringSwitch(java.lang.String switchName, java.lang.String[] values, java.lang.String help) Defines a string list switch.
void	defineStringSwitch(java.lang.String switchName, java.lang.StringBuffer valueRcvr, java.lang.String help) Defines a string switch.
void	defineStringSwitch(java.lang.String switchName, java.util.Vector values, java.lang.String help) Defines a string list switch.
void	defineSwitch(java.lang.String switchName, BooleanHolder valueRcvr, java.lang.String help) Defines a simple switch.
void	parse(java.lang.String[] cmdLineArgs) Parses the command line arguments, and places any switch values in the value objects defined by the define*** methods.
boolean	switchWasFound(java.lang.String switchName) Returns whether a switch was found by parse.

Methods inherited from class java.lang.Object

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

Constructor Detail

CmdLineParser

public CmdLineParser()

Constructs a command line parser. The help switches "-help" and "-?" are defined automatically.

Method Detail

defineSwitch

public void defineSwitch(java.lang.String switchName,
                         BooleanHolder valueRcvr,
                         java.lang.String help)

Defines a simple switch. When the command line is parsed, valueRcvr.value is set to true if the switch is encountered. You should initialize the value object's value to false sometime before parsing the command line. Fails an assertion if the switch name has already been defined.

Parameters:

switchName

the name of the switch, without any leading switch character (i.e. "foo", not "-foo").

valueRcvr

this will receive the value of the switch (whether the switch was specified) when the command line is parsed.

help

a help string for the switch. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineIntSwitch

public void defineIntSwitch(java.lang.String switchName,
                            IntHolder valueRcvr,
                            java.lang.String help)

Defines an integer switch. When this switch is encountered during parsing, it must be followed by an integer, or the parser will throw a SyntaxError. The value of the integer will be placed in valueRcvr.value. Fails an assertion if the switch name has already been defined.

Parameters:

switchName

the name of the switch, without any leading switch character (i.e. "foo", not "-foo").

valueRcvr

this will receive the value of the switch when the command line is parsed.

help

a help string for the switch. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineStringSwitch

public void defineStringSwitch(java.lang.String switchName,
                               java.lang.StringBuffer valueRcvr,
                               java.lang.String help)

Defines a string switch. When this switch is encountered during parsing, it must be followed by a string (any sequence of non-space characters), or the parser will throw a SyntaxError. The string will be placed in the StringBuffer. Fails an assertion if the switch name has already been defined.

Parameters:

switchName

the name of the switch, without any leading switch character (i.e. "foo", not "-foo").

valueRcvr

this will receive the value of the switch when the command line is parsed.

help

a help string for the switch. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineIntSwitch

public void defineIntSwitch(java.lang.String switchName,
                            java.util.Vector values,
                            java.lang.String help)

Defines an integer list switch. When this switch is encountered during parsing, it must be followed by one or more integers, or the parser will throw a SyntaxError. Fails an assertion if the switch name has already been defined.

Parameters:

switchName

the name of the switch, without any leading switch character (i.e. "foo", not "-foo").

values

this vector will receive the values of the switch when the command line is parsed. Each value will be an Integer object.

help

a help string for the switch. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineIntSwitch

public void defineIntSwitch(java.lang.String switchName,
                            int[] values,
                            java.lang.String help)

Defines an integer list switch. When this switch is encountered during parsing, it must be followed by one or more integers, or the parser will throw a SyntaxError. Fails an assertion if the switch name has already been defined.

Parameters:

switchName

the name of the switch, without any leading switch character (i.e. "foo", not "-foo").

values

this array will receive the values of the switch when the command line is parsed. If the user provides more values than will fit in this array, the parser will throw a SyntaxError.

help

a help string for the switch. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineStringSwitch

public void defineStringSwitch(java.lang.String switchName,
                               java.util.Vector values,
                               java.lang.String help)

Defines a string list switch. When this switch is encountered during parsing, it must be followed by one or more non-switch strings (sequences of non-white-space characters), or the parser will throw a SyntaxError. Fails an assertion if the switch name has already been defined.

Parameters:

switchName

the name of the switch, without any leading switch character (i.e. "foo", not "-foo").

values

this vector will receive the values of the switch when the command line is parsed. Each value will be an String object.

help

a help string for the switch. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineStringSwitch

public void defineStringSwitch(java.lang.String switchName,
                               java.lang.String[] values,
                               java.lang.String help)

Defines a string list switch. When this switch is encountered during parsing, it must be followed by one or more non-switch strings (sequences of non-white-space characters), or the parser will throw a SyntaxError. Fails an assertion if the switch name has already been defined.

Parameters:

switchName

the name of the switch, without any leading switch character (i.e. "foo", not "-foo").

values

this array will receive the values of the switch when the command line is parsed. If the user provides more values than will fit in this array, the parser will throw a SyntaxError.

help

a help string for the switch. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineNonSwitch

public void defineNonSwitch(java.util.Vector values,
                            java.lang.String help)

Defines where to put non-switch arguments. If you call this method, then the parser will accept arguments that are neither switches nor switch arguments, and place them in the specified vector. If you do not call this method, then when the parser encounters an argument that is neither a switch nor a switch argument, it throws a SyntaxError. This method may be called at most once during the lifetime of each CmdLineParser object. If it is called more than once, an assertion will fail.

Parameters:

values

this vector will receive the values of the non-switch arguments when the command line is parsed. Each value will be an String object.

help

a help string describing the expected arguments. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineNonSwitch

public void defineNonSwitch(java.lang.String[] values,
                            java.lang.String help)

Defines where to put non-switch arguments. If you call this method, then the parser will accept arguments that are neither switches nor switch arguments, and place them in the specified array. If you do not call this method, then when the parser encounters an argument that is neither a switch nor a switch argument, it throws a SyntaxError. This method may be called at most once during the lifetime of each CmdLineParser object. If it is called more than once, an assertion will fail.

Parameters:

values

this array will receive the values of the non- switch arguments when the command line is parsed. If the user provides more non-switch arguments than will fit in this array, the parser will throw a SyntaxError.

help

a help string describing the expected arguments. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

defineHelp

public void defineHelp(java.lang.String help)

Defines a help overview message. This string will be printed when help is requested, before the help for the individual switches. It is intended to provide an overall description of what the program does. It need not contain any newlines; help output is automatically word-wrapped.

Parameters:

help

the help string.

parse

public void parse(java.lang.String[] cmdLineArgs)
           throws CmdLineParser.SyntaxError

Parses the command line arguments, and places any switch values in the value objects defined by the define*** methods. If any syntax errors are encountered it throws a SyntaxError. This method may be called at most once during the lifetime of each CmdLineParser object. If it is called more than once, an assertion will fail.

Parameters:

cmdLineArgs

the command line arguments that were passed to main().

switchWasFound

public boolean switchWasFound(java.lang.String switchName)

Returns whether a switch was found by parse. You can use this method if you need to know whether a switch was actually found. In most cases you shouldn't need to call this method. You may only call this after parse has been called; if you call it before calling parse, it will fail an assertion.

Parameters:

switchName

the name of the switch. If the switch has not been defined, an assertion fails.

Revision History

7/15/01 Ed Stauff - added defineHelp.

6/15/01 Ed Stauff - made changes per code review.

6/12/01 Ed Stauff - made changes per API review.

6/11/01 - Initial review by Satin team.