util
Class CommandLineParser<Opt extends Enum<Opt> & CommandLineParser.OptionSpec<? super Cxt>,Cxt>

java.lang.Object
  util.CommandLineParser<Opt,Cxt>

Type Parameters:

Opt - The enum specifying the command-line options accepted. Must implement CommandLineParser.OptionSpec, and each field must have a CommandLineParser.OptionSpec.Option attribute.

Cxt - The type of the context in which the members of Opt run the CommandLineParser.OptionSpec.execute(String, Object) handler method.

public final class CommandLineParser<Opt extends Enum<Opt> & CommandLineParser.OptionSpec<? super Cxt>,Cxt>
extends Object

Parses the command line arguments and options passed to a program. The specifications for the options are given in an enum that implements CommandLineParser.OptionSpec at construction; the parser can then be passed the array of arguments (typically the argument to the main() method), and it will sort out which of them are options to the program, perform actions for each, (see CommandLineParser.OptionSpec.execute(String, Object)), and return the other arguments.

Nested Class Summary

static class	CommandLineParser.InvalidCommandLineException Exception thrown by parse(Object, String[]) on invalid command-line input.
static interface	CommandLineParser.OptionSpec<Cxt> The interface which the enum passed to buildParser(Class) must implement.
static interface	CommandLineParser.Usage Annotates an CommandLineParser.OptionSpec enum with the usage message to be displayed by the "--help" output or when an error occurs.

Method Summary

static <Opt extends Enum<Opt> & CommandLineParser.OptionSpec<? super Cxt>,Cxt> CommandLineParser<Opt,Cxt>	buildParser(Class<Opt> specClass) Construct a parser for the given command-line option specifications.
String[]	extractArguments(String... cmdLine) Look for the plain arguments (i.e.
String[]	getArgs() Retrieve the arguments found by the last call to parse(Object, String[]).
String	getHelp() Format a help message, suitable for output by a "--help" option.
Map<Opt,String[]>	getOptMap() Retrieve the parsed options, as a map from the option enum constants to the arguments given.
Pair<Opt,String>[]	getOpts() Retrieve the options found by the last call to parse(Object, String[]).
String	getUsage() Get the usage line for the given CommandLineParser.OptionSpec enum, or the empty string if none was specified.
String[]	parse(Cxt context, String... cmdLine) Process the options in the command line, and return the other arguments.

Methods inherited from class java.lang.Object

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

Method Detail

getOptMap

public Map<Opt,String[]> getOptMap()

Retrieve the parsed options, as a map from the option enum constants to the arguments given. If the order of the options is important, use getOpts() instead.

Returns:

A map of the options found by the last call to parse(Object, String[]) to an array of the arguments passed to the option (or null for options without arguments) each time it occurred.

getHelp

public String getHelp()

Format a help message, suitable for output by a "--help" option. Includes the usage line (see getUsage()), followed by a list of all options with their names, abbreviations, and descriptions.

Returns:

The help message.

extractArguments

public String[] extractArguments(String... cmdLine)
                          throws CommandLineParser.InvalidCommandLineException

Look for the plain arguments (i.e. not options) given on the command line, and return them without processing the options.

This is something of a hack; it may go away, as I found a better way to do what I wrote this method for.

Parameters:

cmdLine - The command line. This will typically be whatever the argument to the main() method was.

Returns:

The arguments to the program.

Throws:

CommandLineParser.InvalidCommandLineException - If the command line fails to parse; for instance, if no argument is given to an option that requires one.

parse

public String[] parse(Cxt context,
                      String... cmdLine)
               throws CommandLineParser.InvalidCommandLineException

Process the options in the command line, and return the other arguments.

Parameters:

context - The context to pass to the CommandLineParser.OptionSpec.execute(String, Object) method of the OptionSpec enum for this parser.

cmdLine - The command line. This will typically be whatever the argument to the main() method was.

Returns:

The non-option arguments. The options can later be retrieved by the getOpts() or getOptMap() method if necessary, and this return value will also be available as getArgs().

Throws:

CommandLineParser.InvalidCommandLineException - If there is an error in the command line.

getArgs

public String[] getArgs()

Retrieve the arguments found by the last call to parse(Object, String[]).

Returns:

The arguments found by the last call to parse(), or null if parse() has not yet been called.

getOpts

public Pair<Opt,String>[] getOpts()

Retrieve the options found by the last call to parse(Object, String[]).

Returns:

An array of (option, argument) pairs corresponding to the options found by the last call to parse() and their arguments, or null if parse() has not yet been called.

getUsage

public String getUsage()

Get the usage line for the given CommandLineParser.OptionSpec enum, or the empty string if none was specified.

Returns:

The usage line.

See Also:

CommandLineParser.Usage

buildParser

public static <Opt extends Enum<Opt> & CommandLineParser.OptionSpec<? super Cxt>,Cxt> CommandLineParser<Opt,Cxt> buildParser(Class<Opt> specClass)

Construct a parser for the given command-line option specifications.

Type Parameters:

Opt - The CommandLineParser.OptionSpec-implementing enum type specifying the command-line options recognized.

Cxt - The context type for Opt.

Parameters:

specClass - The Class object for Opt.

Returns:

A CommandLineParser for the given specifications.