Class JSAP
- java.lang.Object
-
- com.martiansoftware.jsap.JSAP
-
- Direct Known Subclasses:
SimpleJSAP
public class JSAP extends java.lang.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
Fields Modifier and Type Field Description static BigDecimalStringParser
BIGDECIMAL_PARSER
The only instance of aBigDecimalStringParser
.static BigIntegerStringParser
BIGINTEGER_PARSER
The only instance of aBigIntegerStringParser
.static BooleanStringParser
BOOLEAN_PARSER
The only instance of aBooleanStringParser
.static ByteStringParser
BYTE_PARSER
The only instance of aByteStringParser
.static CharacterStringParser
CHARACTER_PARSER
The only instance of aCharacterStringParser
.static ClassStringParser
CLASS_PARSER
The only instance of aClassStringParser
.static ColorStringParser
COLOR_PARSER
The only instance of aColorStringParser
.static char
DEFAULT_LISTSEPARATOR
The default separator for list parameters (equivalent to java.io.File.pathSeparatorChar)static java.lang.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 aDoubleStringParser
.static FloatStringParser
FLOAT_PARSER
The only instance of aFloatStringParser
.static boolean
GREEDY
The parameter consumes the command line.static InetAddressStringParser
INETADDRESS_PARSER
The only instance of aInetAddressStringParser
.static IntegerStringParser
INTEGER_PARSER
The only instance of aIntegerStringParser
.static IntSizeStringParser
INTSIZE_PARSER
The only instance of aIntSizeStringParser
.static boolean
LIST
The parameter is a list.static LongStringParser
LONG_PARSER
The only instance of aLongStringParser
.static LongSizeStringParser
LONGSIZE_PARSER
The only instance of aLongSizeStringParser
.static boolean
MULTIPLEDECLARATIONS
The parameter allows multiple declarations.static java.lang.String
NO_DEFAULT
The parameter has no default value.static java.lang.String
NO_HELP
The parameter has no help text.static java.lang.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 aPackageStringParser
.static boolean
REQUIRED
The parameter is required.static ShortStringParser
SHORT_PARSER
The only instance of aShortStringParser
.static StringStringParser
STRING_PARSER
The only instance of aStringStringParser
.static URLStringParser
URL_PARSER
The only instance of aURLStringParser
.
-
Constructor Summary
Constructors Constructor Description JSAP()
Creates a new JSAP with an empty configuration.JSAP(java.lang.String resourceName)
Creates a new JSAP configured as specified in the referenced xml.JSAP(java.net.URL jsapXML)
Creates a new JSAP configured as specified in the referenced xml.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
finalize()
Unregisters all registered AbstractParameters, allowing them to perform their cleanup.Parameter
getByID(java.lang.String id)
Returns the requested Switch, FlaggedOption, or UnflaggedOption with the specified ID.Flagged
getByLongFlag(java.lang.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(java.lang.Character shortFlag)
Returns the requested Switch or FlaggedOption with the specified short flag.java.lang.String
getHelp()
A shortcut method for calling getHelp(80, "\n").java.lang.String
getHelp(int screenWidth)
A shortcut method for calling getHelp(screenWidth, "\n").java.lang.String
getHelp(int screenWidth, java.lang.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.java.util.Iterator
getUnflaggedOptionsIterator()
Returns an Iterator over all UnflaggedOptions currently registered with this JSAP.java.lang.String
getUsage()
Returns an automatically generated usage description based upon this JSAP's current configuration.JSAPResult
parse(java.lang.String cmdLine)
Parses the specified command line.JSAPResult
parse(java.lang.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(java.lang.String help)
Sets the help string manually, overriding the automatically- generated String.void
setUsage(java.lang.String usage)
Sets the usage string manually, overriding the automatically- generated String.java.lang.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.
-
-
-
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 java.lang.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 java.lang.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.
-
NOT_REQUIRED
public static final boolean NOT_REQUIRED
The parameter is not required.
-
LIST
public static final boolean LIST
The parameter is a list.
-
NOT_LIST
public static final boolean NOT_LIST
The parameter is not a list.
-
MULTIPLEDECLARATIONS
public static final boolean MULTIPLEDECLARATIONS
The parameter allows multiple declarations.
-
NO_MULTIPLEDECLARATIONS
public static final boolean NO_MULTIPLEDECLARATIONS
The parameter does not allow multiple declarations.
-
GREEDY
public static final boolean GREEDY
The parameter consumes the command line.
-
NOT_GREEDY
public static final boolean NOT_GREEDY
The parameter does not consume the command line.
-
NO_DEFAULT
public static final java.lang.String NO_DEFAULT
The parameter has no default value.
-
NO_HELP
public static final java.lang.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 aBigDecimalStringParser
.
-
BIGINTEGER_PARSER
public static final BigIntegerStringParser BIGINTEGER_PARSER
The only instance of aBigIntegerStringParser
.
-
BOOLEAN_PARSER
public static final BooleanStringParser BOOLEAN_PARSER
The only instance of aBooleanStringParser
.
-
BYTE_PARSER
public static final ByteStringParser BYTE_PARSER
The only instance of aByteStringParser
.
-
CHARACTER_PARSER
public static final CharacterStringParser CHARACTER_PARSER
The only instance of aCharacterStringParser
.
-
CLASS_PARSER
public static final ClassStringParser CLASS_PARSER
The only instance of aClassStringParser
.
-
COLOR_PARSER
public static final ColorStringParser COLOR_PARSER
The only instance of aColorStringParser
.
-
DOUBLE_PARSER
public static final DoubleStringParser DOUBLE_PARSER
The only instance of aDoubleStringParser
.
-
FLOAT_PARSER
public static final FloatStringParser FLOAT_PARSER
The only instance of aFloatStringParser
.
-
INETADDRESS_PARSER
public static final InetAddressStringParser INETADDRESS_PARSER
The only instance of aInetAddressStringParser
.
-
INTEGER_PARSER
public static final IntegerStringParser INTEGER_PARSER
The only instance of aIntegerStringParser
.
-
INTSIZE_PARSER
public static final IntSizeStringParser INTSIZE_PARSER
The only instance of aIntSizeStringParser
.
-
LONGSIZE_PARSER
public static final LongSizeStringParser LONGSIZE_PARSER
The only instance of aLongSizeStringParser
.
-
LONG_PARSER
public static final LongStringParser LONG_PARSER
The only instance of aLongStringParser
.
-
PACKAGE_PARSER
public static final PackageStringParser PACKAGE_PARSER
The only instance of aPackageStringParser
.
-
SHORT_PARSER
public static final ShortStringParser SHORT_PARSER
The only instance of aShortStringParser
.
-
STRING_PARSER
public static final StringStringParser STRING_PARSER
The only instance of aStringStringParser
.
-
URL_PARSER
public static final URLStringParser URL_PARSER
The only instance of aURLStringParser
.
-
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(java.net.URL jsapXML) throws java.io.IOException, JSAPException
Creates a new JSAP configured as specified in the referenced xml.- Parameters:
jsapXML
- reference to xml representation of the JSAP configuration- Throws:
java.io.IOException
- if an I/O error occursJSAPException
- if the configuration is not valid
-
JSAP
public JSAP(java.lang.String resourceName) throws java.io.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:
java.io.IOException
- if an I/O error occursJSAPException
- if the configuration is not valid
-
-
Method Detail
-
setUsage
public void setUsage(java.lang.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(java.lang.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 java.lang.String getHelp()
A shortcut method for calling getHelp(80, "\n").- Returns:
- the same as gethelp(80, "\n")
- See Also:
getHelp(int,String)
-
getHelp
public java.lang.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 java.lang.String getHelp(int screenWidth, java.lang.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 java.lang.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 java.lang.String toString()
Returns an automatically generated usage description based upon this JSAP's current configuration. This returns exactly the same result as getUsage().- Overrides:
toString
in classjava.lang.Object
- 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(java.lang.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(java.lang.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(java.lang.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 java.util.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(java.lang.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(java.lang.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.
-
-