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:</p.

 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:
  • Field Details

  • Constructor Details

    • 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 Details

    • 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

      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

      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:
    • 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:
    • 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.
    • getDefaults

      protected Defaults getDefaults(ExceptionMap exceptionMap)
      Returns a Defaults object representing the merged Defaults of every DefaultSource in the DefaultSource chain and the default values specified in the AbstractParameters themselves.
      Parameters:
      exceptionMap - the ExceptionMap object within which any encountered exceptions will be returned.
      Returns:
      a Defaults object representing the Defaults of the entire JSAP.
      See Also:
    • 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