com.martiansoftware.jsap
Class JSAP

java.lang.Object
  com.martiansoftware.jsap.JSAP

Direct Known Subclasses:

SimpleJSAP

public class JSAP

extends Object

The core class of the JSAP (Java Simple Argument Parser) API.

A JSAP is responsible for converting an array of Strings, typically received from a command line in the main class' main() method, into a collection of Objects that are retrievable by a unique ID assigned by the developer.

Before a JSAP parses a command line, it is configured with the Switches, FlaggedOptions, and UnflaggedOptions it will accept. As a result, the developer can rest assured that if no Exceptions are thrown by the JSAP's parse() method, the entire command line was parsed successfully.

For example, to parse a command line with the syntax "[--verbose] {-n|--number} Mynumber", the following code could be used:

 JSAP myJSAP = new JSAP();
 myJSAP.registerParameter( new Switch( "verboseSwitch", JSAP.NO_SHORTFLAG,
 "verbose" ) );
 myJSAP.registerParameter( new FlaggedOption( "numberOption", new
 IntegerStringParser(), JSAP.NO_DEFAULT,
 JSAP.NOT_REQUIRED, 'n', "number" ) );
 JSAPResult result = myJSAP.parse(args);
 

The results of the parse could then be obtained with:

 int n = result.getInt("numberOption");
 boolean isVerbose = result.getBoolean("verboseSwitch");
 

Generating a JSAP from ANT

If you don't want to register all your parameters manually as shown above, the JSAP API provides a custom ANT task that will generate a custom JSAP subclass to suit your needs. See com.martiansoftware.jsap.ant.JSAPAntTask for details.

See the accompanying documentation for examples and further information.

Author:

Marty Lamb, Klaus Berg (bug fixes in help generation), Wolfram Esser (contributed code for custom line separators in help)

See Also:

JSAPAntTask

Field Summary

static BigDecimalStringParser	BIGDECIMAL_PARSER The only instance of a BigDecimalStringParser.
static BigIntegerStringParser	BIGINTEGER_PARSER The only instance of a BigIntegerStringParser.
static BooleanStringParser	BOOLEAN_PARSER The only instance of a BooleanStringParser.
static ByteStringParser	BYTE_PARSER The only instance of a ByteStringParser.
static CharacterStringParser	CHARACTER_PARSER The only instance of a CharacterStringParser.
static ClassStringParser	CLASS_PARSER The only instance of a ClassStringParser.
static ColorStringParser	COLOR_PARSER The only instance of a ColorStringParser.
static char	DEFAULT_LISTSEPARATOR The default separator for list parameters (equivalent to java.io.File.pathSeparatorChar)
static String	DEFAULT_PARAM_HELP_SEPARATOR The default separator between parameters in generated help (a newline by default)
static int	DEFAULT_SCREENWIDTH The default screen width used for formatting help.
static DoubleStringParser	DOUBLE_PARSER The only instance of a DoubleStringParser.
static FloatStringParser	FLOAT_PARSER The only instance of a FloatStringParser.
static boolean	GREEDY The parameter consumes the command line.
static InetAddressStringParser	INETADDRESS_PARSER The only instance of a InetAddressStringParser.
static IntegerStringParser	INTEGER_PARSER The only instance of a IntegerStringParser.
static IntSizeStringParser	INTSIZE_PARSER The only instance of a IntSizeStringParser.
static boolean	LIST The parameter is a list.
static LongStringParser	LONG_PARSER The only instance of a LongStringParser.
static LongSizeStringParser	LONGSIZE_PARSER The only instance of a LongSizeStringParser.
static boolean	MULTIPLEDECLARATIONS The parameter allows multiple declarations.
static String	NO_DEFAULT The parameter has no default value.
static String	NO_HELP The parameter has no help text.
static String	NO_LONGFLAG Does not have a long flag.
static boolean	NO_MULTIPLEDECLARATIONS The parameter does not allow multiple declarations.
static char	NO_SHORTFLAG Does not have a short flag.
static boolean	NOT_GREEDY The parameter does not consume the command line.
static boolean	NOT_LIST The parameter is not a list.
static boolean	NOT_REQUIRED The parameter is not required.
static PackageStringParser	PACKAGE_PARSER The only instance of a PackageStringParser.
static boolean	REQUIRED The parameter is required.
static ShortStringParser	SHORT_PARSER The only instance of a ShortStringParser.
static StringStringParser	STRING_PARSER The only instance of a StringStringParser.
static URLStringParser	URL_PARSER The only instance of a URLStringParser.

Constructor Summary

JSAP()
Creates a new JSAP with an empty configuration.

JSAP(String resourceName)
Creates a new JSAP configured as specified in the referenced xml.

JSAP(URL jsapXML)
Creates a new JSAP configured as specified in the referenced xml.

Method Summary

void	finalize() Unregisters all registered AbstractParameters, allowing them to perform their cleanup.
Parameter	getByID(String id) Returns the requested Switch, FlaggedOption, or UnflaggedOption with the specified ID.
Flagged	getByLongFlag(String longFlag) Returns the requested Switch or FlaggedOption with the specified long flag.
Flagged	getByShortFlag(char shortFlag) Returns the requested Switch or FlaggedOption with the specified short flag.
Flagged	getByShortFlag(Character shortFlag) Returns the requested Switch or FlaggedOption with the specified short flag.
String	getHelp() A shortcut method for calling getHelp(80, "\n").
String	getHelp(int screenWidth) A shortcut method for calling getHelp(screenWidth, "\n").
String	getHelp(int screenWidth, String paramSeparator) If the help text has been manually set, this method simply returns it, ignoring the screenWidth parameter.
IDMap	getIDMap() Returns an IDMap associating long and short flags with their associated parameters' IDs, and allowing the listing of IDs.
Iterator	getUnflaggedOptionsIterator() Returns an Iterator over all UnflaggedOptions currently registered with this JSAP.
String	getUsage() Returns an automatically generated usage description based upon this JSAP's current configuration.
JSAPResult	parse(String cmdLine) Parses the specified command line.
JSAPResult	parse(String[] args) Parses the specified command line array.
void	registerDefaultSource(DefaultSource ds) Registers a new DefaultSource with this JSAP, at the end of the current DefaultSource chain, but before the defaults defined within the AbstractParameters themselves.
void	registerParameter(Parameter param) Registers the specified Parameter (i.e., Switch, FlaggedOption, or UnflaggedOption) with this JSAP.
void	setHelp(String help) Sets the help string manually, overriding the automatically- generated String.
void	setUsage(String usage) Sets the usage string manually, overriding the automatically- generated String.
String	toString() Returns an automatically generated usage description based upon this JSAP's current configuration.
void	unregisterDefaultSource(DefaultSource ds) Removes the specified DefaultSource from this JSAP's DefaultSource chain.
void	unregisterParameter(Parameter param) Unregisters the specified Parameter (i.e., Switch, FlaggedOption, or UnflaggedOption) from this JSAP.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NO_SHORTFLAG

public static final char NO_SHORTFLAG

Does not have a short flag.

See Also:

FlaggedOption, UnflaggedOption, Constant Field Values

NO_LONGFLAG

public static final String NO_LONGFLAG

Does not have a long flag.

See Also:

FlaggedOption, UnflaggedOption

DEFAULT_LISTSEPARATOR

public static final char DEFAULT_LISTSEPARATOR

The default separator for list parameters (equivalent to java.io.File.pathSeparatorChar)

See Also:

FlaggedOption.setListSeparator(char)

DEFAULT_PARAM_HELP_SEPARATOR

public static final String DEFAULT_PARAM_HELP_SEPARATOR

The default separator between parameters in generated help (a newline by default)

See Also:

Constant Field Values

REQUIRED

public static final boolean REQUIRED

The parameter is required.

See Also:

FlaggedOption.setRequired(boolean), Constant Field Values

NOT_REQUIRED

public static final boolean NOT_REQUIRED

The parameter is not required.

See Also:

FlaggedOption.setRequired(boolean), Constant Field Values

LIST

public static final boolean LIST

The parameter is a list.

See Also:

FlaggedOption.setList(boolean), Constant Field Values

NOT_LIST

public static final boolean NOT_LIST

The parameter is not a list.

See Also:

FlaggedOption.setList(boolean), Constant Field Values

MULTIPLEDECLARATIONS

public static final boolean MULTIPLEDECLARATIONS

The parameter allows multiple declarations.

See Also:

FlaggedOption.setAllowMultipleDeclarations(boolean), Constant Field Values

NO_MULTIPLEDECLARATIONS

public static final boolean NO_MULTIPLEDECLARATIONS

The parameter does not allow multiple declarations.

See Also:

FlaggedOption.setAllowMultipleDeclarations(boolean), Constant Field Values

GREEDY

public static final boolean GREEDY

The parameter consumes the command line.

See Also:

UnflaggedOption.setGreedy(boolean), Constant Field Values

NOT_GREEDY

public static final boolean NOT_GREEDY

The parameter does not consume the command line.

See Also:

UnflaggedOption.setGreedy(boolean), Constant Field Values

NO_DEFAULT

public static final String NO_DEFAULT

The parameter has no default value.

NO_HELP

public static final String NO_HELP

The parameter has no help text.

See Also:

Parameter.setHelp(String)

BIGDECIMAL_PARSER

public static final BigDecimalStringParser BIGDECIMAL_PARSER

The only instance of a BigDecimalStringParser.

BIGINTEGER_PARSER

public static final BigIntegerStringParser BIGINTEGER_PARSER

The only instance of a BigIntegerStringParser.

BOOLEAN_PARSER

public static final BooleanStringParser BOOLEAN_PARSER

The only instance of a BooleanStringParser.

BYTE_PARSER

public static final ByteStringParser BYTE_PARSER

The only instance of a ByteStringParser.

CHARACTER_PARSER

public static final CharacterStringParser CHARACTER_PARSER

The only instance of a CharacterStringParser.

CLASS_PARSER

public static final ClassStringParser CLASS_PARSER

The only instance of a ClassStringParser.

COLOR_PARSER

public static final ColorStringParser COLOR_PARSER

The only instance of a ColorStringParser.

DOUBLE_PARSER

public static final DoubleStringParser DOUBLE_PARSER

The only instance of a DoubleStringParser.

FLOAT_PARSER

public static final FloatStringParser FLOAT_PARSER

The only instance of a FloatStringParser.

INETADDRESS_PARSER

public static final InetAddressStringParser INETADDRESS_PARSER

The only instance of a InetAddressStringParser.

INTEGER_PARSER

public static final IntegerStringParser INTEGER_PARSER

The only instance of a IntegerStringParser.

INTSIZE_PARSER

public static final IntSizeStringParser INTSIZE_PARSER

The only instance of a IntSizeStringParser.

LONGSIZE_PARSER

public static final LongSizeStringParser LONGSIZE_PARSER

The only instance of a LongSizeStringParser.

LONG_PARSER

public static final LongStringParser LONG_PARSER

The only instance of a LongStringParser.

PACKAGE_PARSER

public static final PackageStringParser PACKAGE_PARSER

The only instance of a PackageStringParser.

SHORT_PARSER

public static final ShortStringParser SHORT_PARSER

The only instance of a ShortStringParser.

STRING_PARSER

public static final StringStringParser STRING_PARSER

The only instance of a StringStringParser.

URL_PARSER

public static final URLStringParser URL_PARSER

The only instance of a URLStringParser.

DEFAULT_SCREENWIDTH

public static final int DEFAULT_SCREENWIDTH

The default screen width used for formatting help.

See Also:

Constant Field Values

Constructor Detail

JSAP

public JSAP()

Creates a new JSAP with an empty configuration. It must be configured with registerParameter() before its parse() methods may be called.

JSAP

public JSAP(URL jsapXML)
     throws IOException,
            JSAPException

Creates a new JSAP configured as specified in the referenced xml.

Parameters:

jsapXML - reference to xml representation of the JSAP configuration

Throws:

IOException - if an I/O error occurs

JSAPException - if the configuration is not valid

JSAP

public JSAP(String resourceName)
     throws IOException,
            JSAPException

Creates a new JSAP configured as specified in the referenced xml.

Parameters:

resourceName - name of the resource (accessible via this JSAP's classloader) containing the xml representation of the JSAP configuration

Throws:

IOException - if an I/O error occurs

JSAPException - if the configuration is not valid

Method Detail

setUsage

public void setUsage(String usage)

Sets the usage string manually, overriding the automatically- generated String. To remove the override, call setUsage(null).

Parameters:

usage - the manually-set usage string.

setHelp

public void setHelp(String help)

Sets the help string manually, overriding the automatically- generated String. To remove the override, call setHelp(null).

Parameters:

help - the manualy-set help string.

getHelp

public String getHelp()

A shortcut method for calling getHelp(80, "\n").

Returns:

the same as gethelp(80, "\n")

See Also:

getHelp(int,String)

getHelp

public String getHelp(int screenWidth)

A shortcut method for calling getHelp(screenWidth, "\n").

Parameters:

screenWidth - the screen width for which to format the help.

Returns:

the same as gethelp(screenWidth, "\n")

See Also:

getHelp(int,String)

getHelp

public String getHelp(int screenWidth,
                      String paramSeparator)

If the help text has been manually set, this method simply returns it, ignoring the screenWidth parameter. Otherwise, an automatically-formatted help message is returned, tailored to the specified screen width.

Parameters:

screenWidth - the screen width (in characters) for which the help text will be formatted. If zero, help will not be line-wrapped.

Returns:

complete help text for this JSAP.

getUsage

public String getUsage()

Returns an automatically generated usage description based upon this JSAP's current configuration.

Returns:

an automatically generated usage description based upon this JSAP's current configuration.

toString

public String toString()

Returns an automatically generated usage description based upon this JSAP's current configuration. This returns exactly the same result as getUsage().

Returns:

an automatically generated usage description based upon this JSAP's current configuration.

getIDMap

public IDMap getIDMap()

Returns an IDMap associating long and short flags with their associated parameters' IDs, and allowing the listing of IDs. This is probably only useful for developers creating their own DefaultSource classes.

Returns:

an IDMap based upon this JSAP's current configuration.

getByID

public Parameter getByID(String id)

Returns the requested Switch, FlaggedOption, or UnflaggedOption with the specified ID. Depending upon what you intend to do with the result, it may be necessary to re-cast the result as a Switch, FlaggedOption, or UnflaggedOption as appropriate.

Parameters:

id - the ID of the requested Switch, FlaggedOption, or UnflaggedOption.

Returns:

the requested Switch, FlaggedOption, or UnflaggedOption, or null if no Parameter with the specified ID is defined in this JSAP.

getByLongFlag

public Flagged getByLongFlag(String longFlag)

Returns the requested Switch or FlaggedOption with the specified long flag. Depending upon what you intend to do with the result, it may be necessary to re-cast the result as a Switch or FlaggedOption as appropriate.

Parameters:

longFlag - the long flag of the requested Switch or FlaggedOption.

Returns:

the requested Switch or FlaggedOption, or null if no Flagged object with the specified long flag is defined in this JSAP.

getByShortFlag

public Flagged getByShortFlag(Character shortFlag)

Returns the requested Switch or FlaggedOption with the specified short flag. Depending upon what you intend to do with the result, it may be necessary to re-cast the result as a Switch or FlaggedOption as appropriate.

Parameters:

shortFlag - the short flag of the requested Switch or FlaggedOption.

Returns:

the requested Switch or FlaggedOption, or null if no Flagged object with the specified short flag is defined in this JSAP.

getByShortFlag

public Flagged getByShortFlag(char shortFlag)

Returns the requested Switch or FlaggedOption with the specified short flag. Depending upon what you intend to do with the result, it may be necessary to re-cast the result as a Switch or FlaggedOption as appropriate.

Parameters:

shortFlag - the short flag of the requested Switch or FlaggedOption.

Returns:

the requested Switch or FlaggedOption, or null if no Flagged object with the specified short flag is defined in this JSAP.

getUnflaggedOptionsIterator

public Iterator getUnflaggedOptionsIterator()

Returns an Iterator over all UnflaggedOptions currently registered with this JSAP.

Returns:

an Iterator over all UnflaggedOptions currently registered with this JSAP.

See Also:

Iterator

registerDefaultSource

public void registerDefaultSource(DefaultSource ds)

Registers a new DefaultSource with this JSAP, at the end of the current DefaultSource chain, but before the defaults defined within the AbstractParameters themselves.

Parameters:

ds - the DefaultSource to append to the DefaultSource chain.

See Also:

DefaultSource

unregisterDefaultSource

public void unregisterDefaultSource(DefaultSource ds)

Removes the specified DefaultSource from this JSAP's DefaultSource chain. If this specified DefaultSource is not currently in this JSAP's DefaultSource chain, this method does nothing.

Parameters:

ds - the DefaultSource to remove from the DefaultSource chain.

registerParameter

public void registerParameter(Parameter param)
                       throws JSAPException

Registers the specified Parameter (i.e., Switch, FlaggedOption, or UnflaggedOption) with this JSAP.

Registering an Parameter locks the parameter. Attempting to change its properties (ID, flags, etc.) while it is locked will result in a JSAPException. To unlock an Parameter, it must be unregistered from the JSAP.

Parameters:

param - the Parameter to register.

Throws:

JSAPException - if this Parameter cannot be added. Possible reasons include:

• Another Parameter with the same ID has already been registered.
• You are attempting to register a Switch or FlaggedOption with neither a short nor long flag.
• You are attempting to register a Switch or FlaggedOption with a long or short flag that is already defined in this JSAP.
• You are attempting to register a second greedy UnflaggedOption

unregisterParameter

public void unregisterParameter(Parameter param)

Unregisters the specified Parameter (i.e., Switch, FlaggedOption, or UnflaggedOption) from this JSAP. Unregistering an Parameter also unlocks it, allowing changes to its properties (ID, flags, etc.).

Parameters:

param - the Parameter to unregister from this JSAP.

parse

public JSAPResult parse(String[] args)

Parses the specified command line array. If no Exception is thrown, the entire command line has been parsed successfully, and its results have been successfully instantiated.

Parameters:

args - An array of command line arguments to parse. This array is typically provided in the application's main class' main() method.

Returns:

a JSAPResult containing the resulting Objects.

parse

public JSAPResult parse(String cmdLine)

Parses the specified command line. The specified command line is first parsed into an array, much like the operating system does for the JVM prior to calling your application's main class' main() method. If no Exception is thrown, the entire command line has been parsed successfully, and its results have been successfully instantiated.

Parameters:

cmdLine - An array of command line arguments to parse. This array is typically provided in the application's main class' main() method.

Returns:

a JSAPResult containing the resulting Objects.

finalize

public void finalize()

Unregisters all registered AbstractParameters, allowing them to perform their cleanup.