common.cmdline
Class Parser

java.lang.Object
  common.cmdline.Parser

public class Parser
extends java.lang.Object

Parses options on a command line. This class should not be instantiated; all its methods are static. The application should first create options (objects that implement the Option interface); the options will automatically register themselves with the Parser. Then the application should call Parser.parse, passing in the argument array that was given to the application's main method. The parse method uses the Option objects to parse all the options on the command line; if the command line is ill-formed, it prints an error message and exits the program. The resulting option values are stored by the Option objects. Any non-option arguments are returned by the parse method.

This class supports the same command line syntax as the Unix getopt function. If a command line argument begins with a single dash followed by a non-dash character, the parser looks for an option that has that character as a short form. If such an option exists and does not expect a value, then the parser moves on to the next character in the argument, treating it as a short-form option as well. This continues until the parser reaches an option that expects a value. If there are any characters remaining in the argument at this point, they constitute the option value. Otherwise, the next command line argument is interpreted as the option value. Here are some examples of how short-form options are parsed, assuming that options "d" and "P" take values but "c", "e", and "k" don't.

 -c                 // option "c", no value
 -d 12              // option "d", value "12"
 -d12               // option "d", value "12"
 -cek               // options "c", "e", "k", with no values
 -Pprinter          // option "P", value "printer"
 -cP printer        // option "c" with no value, "P" with value "printer"
 -Palpha=12         // option "P" with value "alpha=12"
 

If a command line argument begins with two dashes ("--"), then all remaining characters in the argument (up to the first = sign, if any) are interpreted as a long option string. If there is an equals sign in the argument, then all characters after the first equals sign are interpreted as the option value. Otherwise, if the option expects a value, the next command line argument is interpreted as the value. Some examples:

 --copy             // option "copy", no value
 --ncopies=12       // option "ncopies", value "12"
 --ncopies 12       // option "ncopies", value "12"
 --ncopies12        // option "ncopies12", no value
 

Method Summary

static void	addOption(Option opt) Adds the given option to the set that this parser will recognize.
static void	main(java.lang.String[] args) Test program.
static java.util.List	parse(java.lang.String[] args) Parses the given array of command line arguments.
static void	printUsage(java.io.PrintStream s) Prints a usage message for the program to the given stream.
static void	setProgramDesc(java.lang.String description) Sets the program description that will be printed by printUsage.
static void	setUsageLine(java.lang.String usage) Sets the basic usage message that will be printed by printUsage.

Methods inherited from class java.lang.Object

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

Method Detail

setProgramDesc

public static void setProgramDesc(java.lang.String description)

Sets the program description that will be printed by printUsage.

setUsageLine

public static void setUsageLine(java.lang.String usage)

Sets the basic usage message that will be printed by printUsage. This message should include the non-option arguments that the program expects.

addOption

public static void addOption(Option opt)

Adds the given option to the set that this parser will recognize. The order in which options are added only influences the order in which they're listed by the printUsage method.

Throws:

java.lang.IllegalArgumentException - if any of the short or long forms of the given option also belong to an option that was already added

parse

public static java.util.List parse(java.lang.String[] args)

Parses the given array of command line arguments. Option occurrences and values are recorded by the Option objects. If there is a syntax error in the command line, this method prints an error message and exits the program.

Returns:

List of Strings representing the non-option command line arguments, in the order they were given

printUsage

public static void printUsage(java.io.PrintStream s)

Prints a usage message for the program to the given stream. The message consists of the program description, then the program usage message, and then a list of available options. Option documentation strings are obtained by calling getUsageString on the Option objects.

main

public static void main(java.lang.String[] args)

Test program. This program defines some options, parses the command line (which, of course, is specified by the user), and then prints the option values and the non-option arguments.