|
||||||||||
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 char |
DEFAULT_LISTSEPARATOR
The default separator for list parameters (equivalent to java.io.File.pathSeparatorChar) |
static boolean |
GREEDY
The parameter consumes the command line. |
static boolean |
LIST
The parameter is a list. |
static boolean |
MULTIPLEDECLARATIONS
The parameter allows multiple declarations. |
static String |
NO_DEFAULT
The parameter has no default value. |
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 boolean |
REQUIRED
The parameter is required. |
Constructor Summary | |
JSAP()
Creates a new JSAP with an empty configuration. |
Method Summary | |
void |
finalize()
Unregisters all registered AbstractParameters, allowing them to perform their cleanup. |
AbstractParameter |
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). |
String |
getHelp(int screenWidth)
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(AbstractParameter param)
Registers the specified AbstractParameter (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(AbstractParameter param)
Unregisters the specified AbstractParameter (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
com.martiansoftware.jsap.Option#setListSeparator(char)
public static final boolean REQUIRED
com.martiansoftware.jsap.Option#setRequired(boolean)
,
Constant Field Valuespublic static final boolean NOT_REQUIRED
com.martiansoftware.jsap.Option#setRequired(boolean)
,
Constant Field Valuespublic static final boolean LIST
com.martiansoftware.jsap.Option#setIsList(boolean)
,
Constant Field Valuespublic static final boolean NOT_LIST
com.martiansoftware.jsap.Option#setIsList(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
com.martiansoftware.jsap.AbstractParameter#setDefault(String)
Constructor Detail |
public JSAP()
Method 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)
public String getHelp(int screenWidth)
screenWidth
- the screen width (in characters) for which
the help text will be formatted.
public String getUsage()
public String toString()
public IDMap getIDMap()
public AbstractParameter 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(AbstractParameter param) throws JSAPException
Registering an AbstractParameter locks the parameter. Attempting to change its properties (ID, flags, etc.) while it is locked will result in a JSAPException. To unlock an AbstractParameter, it must be unregistered from the JSAP.
param
- the AbstractParameter to register.
JSAPException
- if this AbstractParameter cannot be added. Possible
reasons include:
public void unregisterParameter(AbstractParameter param)
param
- the AbstractParameter 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 |