|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.martiansoftware.jsap.JSAP
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");
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
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 |
public static final char NO_SHORTFLAG
FlaggedOption
,
UnflaggedOption
,
Constant Field Valuespublic static final String NO_LONGFLAG
FlaggedOption
,
UnflaggedOption
public static final char DEFAULT_LISTSEPARATOR
FlaggedOption.setListSeparator(char)
public static final String DEFAULT_PARAM_HELP_SEPARATOR
public static final boolean REQUIRED
FlaggedOption.setRequired(boolean)
,
Constant Field Valuespublic static final boolean NOT_REQUIRED
FlaggedOption.setRequired(boolean)
,
Constant Field Valuespublic static final boolean LIST
FlaggedOption.setList(boolean)
,
Constant Field Valuespublic static final boolean NOT_LIST
FlaggedOption.setList(boolean)
,
Constant Field Valuespublic static final boolean MULTIPLEDECLARATIONS
FlaggedOption.setAllowMultipleDeclarations(boolean)
,
Constant Field Valuespublic static final boolean NO_MULTIPLEDECLARATIONS
FlaggedOption.setAllowMultipleDeclarations(boolean)
,
Constant Field Valuespublic static final boolean GREEDY
UnflaggedOption.setGreedy(boolean)
,
Constant Field Valuespublic static final boolean NOT_GREEDY
UnflaggedOption.setGreedy(boolean)
,
Constant Field Valuespublic static final String NO_DEFAULT
public static final 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
Constructor Detail |
public JSAP()
public JSAP(URL jsapXML) throws IOException, JSAPException
jsapXML
- reference to xml representation of the JSAP configuration
IOException
- if an I/O error occurs
JSAPException
- if the configuration is not validpublic JSAP(String resourceName) throws IOException, JSAPException
resourceName
- name of the resource (accessible via this JSAP's classloader)
containing the xml representation of the JSAP configuration
IOException
- if an I/O error occurs
JSAPException
- if the configuration is not validMethod Detail |
public void setUsage(String usage)
usage
- the manually-set usage string.public void setHelp(String help)
help
- the manualy-set help string.public String getHelp()
getHelp(int,String)
public String getHelp(int screenWidth)
screenWidth
- the screen width for which to format the help.
getHelp(int,String)
public String getHelp(int screenWidth, 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 String getUsage()
public String toString()
public IDMap getIDMap()
public Parameter getByID(String id)
id
- the ID of the requested Switch, FlaggedOption, or
UnflaggedOption.
public Flagged getByLongFlag(String longFlag)
longFlag
- the long flag of the requested Switch or FlaggedOption.
public Flagged getByShortFlag(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 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(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(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()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |