net.sf.kdgcommons.util

Class SimpleCLIParser

java.lang.Object

net.sf.kdgcommons.util.SimpleCLIParser

public class SimpleCLIParser
extends Object

A simplified command-line processor. Will extract options from an argument list, with optional parameters, leaving the rest of the arguments for the caller. Will also generate an invocation message that lists the available options (and optionally exits with error code 1).

This class can be used on its own, but is normally subclassed. The subclass is responsible for defining the set of options and presenting a constructor that just takes the command-line argument vector. The subclass also normally defines an enum that corresponds to the available options, as a shorthand for accessing the option values.

The SimpleCLIParser.OptionDefinition nested class is how the caller defines legal options. Options have two forms:

Enable/disable

The option always has a value, either enabled or disabled. The user can specify distinct strings to enable or disable it, and there is a default value.

Parameterized

The option takes zero or more parameters. These parameters are specified as separate command-line arguments (eg: "--opt param"), or as embedded parameters (eg: "--opt=param"). Parameterized options may be repeated (eg: "--opt param1 --opt param2"), and embedded parameters may also be repeated (eg: "--opt param1,param2"). A parameterized option is considered "enabled" if it appears in the argument list, with or without parmaeters.

The non-option command-line arguments are available in a number of ways. They can be retrieved all at once using the getParameters() method, or one at a time using the shift() method.

Design note: this class is intended for internal use in a narrow phase of program operation. As a result, it makes no attempt to protect its internal state. If you wish to modify the option data after construction, have at it (but beware that some lists are unmodifiable as implementation choices).

Note also that this class does not attempt to perform validation. The caller is responsible for ensuring that all required options are present, and that option parameters are valid.

Since:

1.0.8

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SimpleCLIParser.OptionDefinition This class defines a single command-line option.

Constructor Summary

Constructors

Constructor and Description
SimpleCLIParser(String[] argv, SimpleCLIParser.OptionDefinition... optionDefs) Processes the supplied list of arguments into options, option params, and non-options.

Method Summary

Modifier and Type	Method and Description
List<SimpleCLIParser.OptionDefinition>	getAllDefinitions() Returns the complete list of option definitions.
SimpleCLIParser.OptionDefinition	getDefinition(Object key) Returns a single option definition, by key, null if there's no such definition.
String	getHelp() Returns a help message that describes the various options.
List<Object>	getOptions() Returns the keys for all specified options, in the order that they appear on the command line.
List<String>	getOptionValues(Object key) For options that take parameters, returns the parameters.
List<String>	getParameters() Returns the complete list of non-option parameters.
boolean	isOptionEnabled(Object key) Indicates whether the option identified by the passed key is enabled or not.
String	shift() Returns the next non-option parameter, null if there are none remaining.

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleCLIParser

public SimpleCLIParser(String[] argv,
                       SimpleCLIParser.OptionDefinition... optionDefs)

Processes the supplied list of arguments into options, option params, and non-options. Subclasses will normally expose a constructor that just accepts an argument vector, and hide the option definitions.

Parameters:

argv - The argument vector passed to main().

optionDefs - Definitions for all expected options.

Method Detail

getDefinition

public SimpleCLIParser.OptionDefinition getDefinition(Object key)

Returns a single option definition, by key, null if there's no such definition.

getAllDefinitions

public List<SimpleCLIParser.OptionDefinition> getAllDefinitions()

Returns the complete list of option definitions. This may be used to display information about the options (although getHelp() is usually a better choice.

getHelp

public String getHelp()

Returns a help message that describes the various options. This is normally reported for invalid output.

isOptionEnabled

public boolean isOptionEnabled(Object key)

Indicates whether the option identified by the passed key is enabled or not. For options that take parameters, the option is enabled if it appears on the command-line (regardless of the number of parameters).

Throws:

IllegalArgumentException - if given a key that does not match any definition.

getOptions

public List<Object> getOptions()

Returns the keys for all specified options, in the order that they appear on the command line.

getOptionValues

public List<String> getOptionValues(Object key)

For options that take parameters, returns the parameters. Will return an empty list if the option is not present (even if the option is an enable/disable type).

getParameters

public List<String> getParameters()

Returns the complete list of non-option parameters. You can call this as many times as desired, regardless of calls to shift(). The returned list is array-backed.

shift

public String shift()

Returns the next non-option parameter, null if there are none remaining. This method iterates through the list of parameters once, and may not be reset.