JSAP (JSAP: the Java Simple Argument Parser)
Keywords: com.martiansoftware.jsap.JSAP class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.martiansoftware.jsap
Class JSAP

    java.lang.Object
      com.martiansoftware.jsap.JSAP

Direct Known Subclasses:
  SimpleJSAP

    public class JSAP

extends 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
`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

### 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 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 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.

  See Also:
    `FlaggedOption.setRequired(boolean)`, Constant Field Values

### NOT_REQUIRED

    public static final boolean NOT_REQUIRED

  The parameter is not required.

  See Also:
    `FlaggedOption.setRequired(boolean)`, Constant Field Values

### LIST

    public static final boolean LIST

  The parameter is a list.

  See Also:
    `FlaggedOption.setList(boolean)`, Constant Field Values

### NOT_LIST

    public static final boolean NOT_LIST

  The parameter is not a list.

  See Also:
    `FlaggedOption.setList(boolean)`, Constant Field Values

### MULTIPLEDECLARATIONS

    public static final boolean MULTIPLEDECLARATIONS

  The parameter allows multiple declarations.

  See Also:
    `FlaggedOption.setAllowMultipleDeclarations(boolean)`, Constant Field Values

### NO_MULTIPLEDECLARATIONS

    public static final boolean NO_MULTIPLEDECLARATIONS

  The parameter does not allow multiple declarations.

  See Also:
    `FlaggedOption.setAllowMultipleDeclarations(boolean)`, Constant Field Values

### GREEDY

    public static final boolean GREEDY

  The parameter consumes the command line.

  See Also:
    `UnflaggedOption.setGreedy(boolean)`, Constant Field Values

### NOT_GREEDY

    public static final boolean NOT_GREEDY

  The parameter does not consume the command line.

  See Also:
    `UnflaggedOption.setGreedy(boolean)`, Constant Field Values

### NO_DEFAULT

    public static final String NO_DEFAULT

  The parameter has no default value.

### NO_HELP

    public static final 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 a `BigDecimalStringParser`.

### BIGINTEGER_PARSER

    public static final BigIntegerStringParser BIGINTEGER_PARSER

  The only instance of a `BigIntegerStringParser`.

### BOOLEAN_PARSER

    public static final BooleanStringParser BOOLEAN_PARSER

  The only instance of a `BooleanStringParser`.

### BYTE_PARSER

    public static final ByteStringParser BYTE_PARSER

  The only instance of a `ByteStringParser`.

### CHARACTER_PARSER

    public static final CharacterStringParser CHARACTER_PARSER

  The only instance of a `CharacterStringParser`.

### CLASS_PARSER

    public static final ClassStringParser CLASS_PARSER

  The only instance of a `ClassStringParser`.

### COLOR_PARSER

    public static final ColorStringParser COLOR_PARSER

  The only instance of a `ColorStringParser`.

### DOUBLE_PARSER

    public static final DoubleStringParser DOUBLE_PARSER

  The only instance of a `DoubleStringParser`.

### FLOAT_PARSER

    public static final FloatStringParser FLOAT_PARSER

  The only instance of a `FloatStringParser`.

### INETADDRESS_PARSER

    public static final InetAddressStringParser INETADDRESS_PARSER

  The only instance of a `InetAddressStringParser`.

### INTEGER_PARSER

    public static final IntegerStringParser INTEGER_PARSER

  The only instance of a `IntegerStringParser`.

### INTSIZE_PARSER

    public static final IntSizeStringParser INTSIZE_PARSER

  The only instance of a `IntSizeStringParser`.

### LONGSIZE_PARSER

    public static final LongSizeStringParser LONGSIZE_PARSER

  The only instance of a `LongSizeStringParser`.

### LONG_PARSER

    public static final LongStringParser LONG_PARSER

  The only instance of a `LongStringParser`.

### PACKAGE_PARSER

    public static final PackageStringParser PACKAGE_PARSER

  The only instance of a `PackageStringParser`.

### SHORT_PARSER

    public static final ShortStringParser SHORT_PARSER

  The only instance of a `ShortStringParser`.

### STRING_PARSER

    public static final StringStringParser STRING_PARSER

  The only instance of a `StringStringParser`.

### URL_PARSER

    public static final URLStringParser URL_PARSER

  The only instance of a `URLStringParser`.

### 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(URL jsapXML)
         throws IOException,
                JSAPException

  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 occurs
    `JSAPException` - if the configuration is not valid

### JSAP

    public JSAP(String resourceName)
         throws 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:
    `IOException` - if an I/O error occurs
    `JSAPException` - if the configuration is not valid

Method Detail

### setUsage

    public void setUsage(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(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 String getHelp()

  A shortcut method for calling getHelp(80, "\n").

  Returns:
    the same as gethelp(80, "\n")
  See Also:
    `getHelp(int,String)`

### getHelp

    public 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 String getHelp(int screenWidth,
                          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 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 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 class `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(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(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(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 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(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(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.

  Overrides:
    `finalize` in class `Object`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2005, Martian Software, Inc.. All Rights Reserved.
For the latest version and documentation, please visit http://www.martiansoftware.com/jsap