Package com.martiansoftware.jsap

Class 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

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