public class JSAP
extends java.lang.Object
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");
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.
JSAPAntTask
Modifier and Type | Field and Description |
---|---|
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 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 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 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 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 and 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.
|
Modifier and Type | Method and 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.
|
public static final char NO_SHORTFLAG
FlaggedOption
,
UnflaggedOption
,
Constant Field Valuespublic static final java.lang.String NO_LONGFLAG
FlaggedOption
,
UnflaggedOption
public static final char DEFAULT_LISTSEPARATOR
FlaggedOption.setListSeparator(char)
public static final java.lang.String DEFAULT_PARAM_HELP_SEPARATOR
public static final boolean REQUIRED
public static final boolean NOT_REQUIRED
public static final boolean LIST
public static final boolean NOT_LIST
public static final boolean MULTIPLEDECLARATIONS
public static final boolean NO_MULTIPLEDECLARATIONS
public static final boolean GREEDY
public static final boolean NOT_GREEDY
public static final java.lang.String NO_DEFAULT
public static final java.lang.String NO_HELP
Parameter.setHelp(String)
public static final BigDecimalStringParser BIGDECIMAL_PARSER
BigDecimalStringParser
.public static final BigIntegerStringParser BIGINTEGER_PARSER
BigIntegerStringParser
.public static final BooleanStringParser BOOLEAN_PARSER
BooleanStringParser
.public static final ByteStringParser BYTE_PARSER
ByteStringParser
.public static final CharacterStringParser CHARACTER_PARSER
CharacterStringParser
.public static final ClassStringParser CLASS_PARSER
ClassStringParser
.public static final ColorStringParser COLOR_PARSER
ColorStringParser
.public static final DoubleStringParser DOUBLE_PARSER
DoubleStringParser
.public static final FloatStringParser FLOAT_PARSER
FloatStringParser
.public static final InetAddressStringParser INETADDRESS_PARSER
InetAddressStringParser
.public static final IntegerStringParser INTEGER_PARSER
IntegerStringParser
.public static final IntSizeStringParser INTSIZE_PARSER
IntSizeStringParser
.public static final LongSizeStringParser LONGSIZE_PARSER
LongSizeStringParser
.public static final LongStringParser LONG_PARSER
LongStringParser
.public static final PackageStringParser PACKAGE_PARSER
PackageStringParser
.public static final ShortStringParser SHORT_PARSER
ShortStringParser
.public static final StringStringParser STRING_PARSER
StringStringParser
.public static final URLStringParser URL_PARSER
URLStringParser
.public static final int DEFAULT_SCREENWIDTH
public JSAP()
public JSAP(java.net.URL jsapXML) throws java.io.IOException, JSAPException
jsapXML
- reference to xml representation of the JSAP configurationjava.io.IOException
- if an I/O error occursJSAPException
- if the configuration is not validpublic JSAP(java.lang.String resourceName) throws java.io.IOException, JSAPException
resourceName
- name of the resource (accessible via this JSAP's classloader)
containing the xml representation of the JSAP configurationjava.io.IOException
- if an I/O error occursJSAPException
- if the configuration is not validpublic void setUsage(java.lang.String usage)
usage
- the manually-set usage string.public void setHelp(java.lang.String help)
help
- the manualy-set help string.public java.lang.String getHelp()
getHelp(int,String)
public java.lang.String getHelp(int screenWidth)
screenWidth
- the screen width for which to format the help.getHelp(int,String)
public java.lang.String getHelp(int screenWidth, java.lang.String paramSeparator)
screenWidth
- the screen width (in characters) for which
the help text will be formatted. If zero, help will not be
line-wrapped.public java.lang.String getUsage()
public java.lang.String toString()
toString
in class java.lang.Object
public IDMap getIDMap()
public Parameter getByID(java.lang.String id)
id
- the ID of the requested Switch, FlaggedOption, or
UnflaggedOption.public Flagged getByLongFlag(java.lang.String longFlag)
longFlag
- the long flag of the requested Switch or FlaggedOption.public Flagged getByShortFlag(java.lang.Character shortFlag)
shortFlag
- the short flag of the requested Switch or FlaggedOption.public Flagged getByShortFlag(char shortFlag)
shortFlag
- the short flag of the requested Switch or FlaggedOption.public java.util.Iterator getUnflaggedOptionsIterator()
Iterator
public void registerDefaultSource(DefaultSource ds)
ds
- the DefaultSource to append to the DefaultSource chain.DefaultSource
public void unregisterDefaultSource(DefaultSource ds)
ds
- the DefaultSource to remove from the DefaultSource chain.public void registerParameter(Parameter param) throws JSAPException
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.
param
- the Parameter to register.JSAPException
- if this Parameter cannot be added. Possible
reasons include:
public void unregisterParameter(Parameter param)
param
- the Parameter to unregister from this JSAP.public JSAPResult parse(java.lang.String[] args)
args
- An array of command line arguments to parse. This array is
typically provided in the application's main class' main() method.public JSAPResult parse(java.lang.String cmdLine)
cmdLine
- An array of command line arguments to parse. This array
is typically provided in the application's main class' main() method.public void finalize()
finalize
in class java.lang.Object
Copyright © 2002-2006, Martian Software, Inc.. All Rights Reserved.
For the latest version and documentation, please visit http://www.martiansoftware.com/jsap