Class JSAP
- Direct Known Subclasses:
SimpleJSAP
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:</p.
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final BigDecimalStringParser
The only instance of aBigDecimalStringParser
.static final BigIntegerStringParser
The only instance of aBigIntegerStringParser
.static final BooleanStringParser
The only instance of aBooleanStringParser
.static final ByteStringParser
The only instance of aByteStringParser
.static final CharacterStringParser
The only instance of aCharacterStringParser
.static final ClassStringParser
The only instance of aClassStringParser
.static final ColorStringParser
The only instance of aColorStringParser
.static final char
The default separator for list parameters (equivalent to java.io.File.pathSeparatorChar)static final String
The default separator between parameters in generated help (a newline by default)static final int
The default screen width used for formatting help.static final DoubleStringParser
The only instance of aDoubleStringParser
.static final FloatStringParser
The only instance of aFloatStringParser
.static final boolean
The parameter consumes the command line.static final InetAddressStringParser
The only instance of aInetAddressStringParser
.static final IntegerStringParser
The only instance of aIntegerStringParser
.static final IntSizeStringParser
The only instance of aIntSizeStringParser
.static final boolean
The parameter is a list.static final LongStringParser
The only instance of aLongStringParser
.static final LongSizeStringParser
The only instance of aLongSizeStringParser
.static final boolean
The parameter allows multiple declarations.static final String
The parameter has no default value.static final String
The parameter has no help text.static final String
Does not have a long flag.static final boolean
The parameter does not allow multiple declarations.static final char
Does not have a short flag.static final boolean
The parameter does not consume the command line.static final boolean
The parameter is not a list.static final boolean
The parameter is not required.static final PackageStringParser
The only instance of aPackageStringParser
.static final boolean
The parameter is required.static final ShortStringParser
The only instance of aShortStringParser
.static final StringStringParser
The only instance of aStringStringParser
.static final URLStringParser
The only instance of aURLStringParser
. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
finalize()
Unregisters all registered AbstractParameters, allowing them to perform their cleanup.Returns the requested Switch, FlaggedOption, or UnflaggedOption with the specified ID.getByLongFlag
(String longFlag) Returns the requested Switch or FlaggedOption with the specified long flag.getByShortFlag
(char shortFlag) Returns the requested Switch or FlaggedOption with the specified short flag.getByShortFlag
(Character shortFlag) Returns the requested Switch or FlaggedOption with the specified short flag.protected Defaults
getDefaults
(ExceptionMap exceptionMap) Returns a Defaults object representing the merged Defaults of every DefaultSource in the DefaultSource chain and the default values specified in the AbstractParameters themselves.getHelp()
A shortcut method for calling getHelp(80, "\n").getHelp
(int screenWidth) A shortcut method for calling getHelp(screenWidth, "\n").If the help text has been manually set, this method simply returns it, ignoring the screenWidth parameter.getIDMap()
Returns an IDMap associating long and short flags with their associated parameters' IDs, and allowing the listing of IDs.Returns an Iterator over all UnflaggedOptions currently registered with this JSAP.getUsage()
Returns an automatically generated usage description based upon this JSAP's current configuration.Parses the specified command line.Parses the specified command line array.void
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
Sets the help string manually, overriding the automatically- generated String.void
Sets the usage string manually, overriding the automatically- generated String.toString()
Returns an automatically generated usage description based upon this JSAP's current configuration.void
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.
-
Field Details
-
NO_SHORTFLAG
public static final char NO_SHORTFLAGDoes not have a short flag. -
NO_LONGFLAG
Does not have a long flag.- See Also:
-
DEFAULT_LISTSEPARATOR
public static final char DEFAULT_LISTSEPARATORThe default separator for list parameters (equivalent to java.io.File.pathSeparatorChar)- See Also:
-
DEFAULT_PARAM_HELP_SEPARATOR
The default separator between parameters in generated help (a newline by default)- See Also:
-
REQUIRED
public static final boolean REQUIREDThe parameter is required. -
NOT_REQUIRED
public static final boolean NOT_REQUIREDThe parameter is not required. -
LIST
public static final boolean LISTThe parameter is a list. -
NOT_LIST
public static final boolean NOT_LISTThe parameter is not a list. -
MULTIPLEDECLARATIONS
public static final boolean MULTIPLEDECLARATIONSThe parameter allows multiple declarations. -
NO_MULTIPLEDECLARATIONS
public static final boolean NO_MULTIPLEDECLARATIONSThe parameter does not allow multiple declarations. -
GREEDY
public static final boolean GREEDYThe parameter consumes the command line. -
NOT_GREEDY
public static final boolean NOT_GREEDYThe parameter does not consume the command line. -
NO_DEFAULT
The parameter has no default value. -
NO_HELP
The parameter has no help text.- See Also:
-
BIGDECIMAL_PARSER
The only instance of aBigDecimalStringParser
. -
BIGINTEGER_PARSER
The only instance of aBigIntegerStringParser
. -
BOOLEAN_PARSER
The only instance of aBooleanStringParser
. -
BYTE_PARSER
The only instance of aByteStringParser
. -
CHARACTER_PARSER
The only instance of aCharacterStringParser
. -
CLASS_PARSER
The only instance of aClassStringParser
. -
COLOR_PARSER
The only instance of aColorStringParser
. -
DOUBLE_PARSER
The only instance of aDoubleStringParser
. -
FLOAT_PARSER
The only instance of aFloatStringParser
. -
INETADDRESS_PARSER
The only instance of aInetAddressStringParser
. -
INTEGER_PARSER
The only instance of aIntegerStringParser
. -
INTSIZE_PARSER
The only instance of aIntSizeStringParser
. -
LONGSIZE_PARSER
The only instance of aLongSizeStringParser
. -
LONG_PARSER
The only instance of aLongStringParser
. -
PACKAGE_PARSER
The only instance of aPackageStringParser
. -
SHORT_PARSER
The only instance of aShortStringParser
. -
STRING_PARSER
The only instance of aStringStringParser
. -
URL_PARSER
The only instance of aURLStringParser
. -
DEFAULT_SCREENWIDTH
public static final int DEFAULT_SCREENWIDTHThe default screen width used for formatting help.- See Also:
-
-
Constructor Details
-
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
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 occursJSAPException
- if the configuration is not valid
-
JSAP
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 occursJSAPException
- if the configuration is not valid
-
-
Method Details
-
setUsage
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
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
A shortcut method for calling getHelp(80, "\n").- Returns:
- the same as gethelp(80, "\n")
- See Also:
-
getHelp
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
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
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
Returns an automatically generated usage description based upon this JSAP's current configuration. This returns exactly the same result as getUsage(). -
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
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
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
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
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
Returns an Iterator over all UnflaggedOptions currently registered with this JSAP.- Returns:
- an Iterator over all UnflaggedOptions currently registered with this JSAP.
- See Also:
-
registerDefaultSource
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:
-
unregisterDefaultSource
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.
-
getDefaults
Returns a Defaults object representing the merged Defaults of every DefaultSource in the DefaultSource chain and the default values specified in the AbstractParameters themselves.- Parameters:
exceptionMap
- the ExceptionMap object within which any encountered exceptions will be returned.- Returns:
- a Defaults object representing the Defaults of the entire JSAP.
- See Also:
-
registerParameter
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
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
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
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.
-