Class Parameter

  • Direct Known Subclasses:
    Option, Switch

    public abstract class Parameter
    extends java.lang.Object

    Top-level abstraction of a parameter. A parameter consists of one or more arguments (command line tokens) that have a special meaning when taken together. For example, a command-line switch "-v" is a parameter consisting of a single argument, whereas a command-line option "--file somefile.txt" is a parameter consisting of two arguments. Some parameters can be quite large, such as an option for a file compression utility that allows you to specify any number of files to comporess.

    This is an abstract class. See its subclasses Switch, FlaggedOption, and UnflaggedOption for details on the various types of parameters. Functionality common to all three types of Parameters is described below.

    Each parameter has a unique ID assigned in its constructor. This ID is used to retrieve values from the parser after the command line is parsed. You can set the ID to any String value you wish, although in general you'll want them to be brief and descriptive to provide a degree of documentation. A "-h" switch, for example, might have the ID "help". The calling program can then determine if the user specified the -h switch on the command line with the simple call getBoolean("help") against the JSAPResult object produced by JSAP.parse().

    Author:
    Marty Lamb
    See Also:
    Switch, FlaggedOption, UnflaggedOption, JSAPResult.getBoolean(String), JSAP.parse(String[])
    • Constructor Summary

      Constructors 
      Constructor Description
      Parameter​(java.lang.String id)
      Creates a new Parameter.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected void _setDefault​(java.lang.String defaultValue)
      Sets a default value for this parameter.
      protected void _setDefault​(java.lang.String[] defaultValues)
      Sets one or more default values for this parameter.
      protected void _setUsageName​(java.lang.String usageName)
      Sets the name of this AbstractParameter for the purposes of usage information.
      void addDefault​(java.lang.String defaultValue)
      Adds a single default value to any currently defined for this parameter.
      protected void enforceParameterLock()
      Helper method that can be called by any methods that modify this parameter (or its subclasses).
      java.lang.String[] getDefault()
      Returns an array of default values for this parameter, or null if no default values have been defined.
      java.lang.String getHelp()
      Returns a description of the option's usage.
      java.lang.String getID()
      Returns this parameter's unique ID.
      abstract java.lang.String getSyntax()
      A convenience method for automatically generating syntax information based upon a JSAP configuration.
      java.lang.String getUsage()
      Deprecated.
      use getSyntax() instead
      java.lang.String getUsageName()
      Returns the name of this AbstractParameter for the purposes of usage information.
      protected boolean locked()
      Returns a boolean indicating whether this parameter is locked.
      protected abstract java.util.List parse​(java.lang.String arg)
      Returns an ArrayList of values resulting from the parsing of the specified argument.
      Parameter setHelp​(java.lang.String help)
      Sets the help text for this parameter.
      protected void setLocked​(boolean locked)
      Locks or unlocks this parameter.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Parameter

        public Parameter​(java.lang.String id)
        Creates a new Parameter. Subclasses should call this constructor.
        Parameters:
        id - The ID for this argument. All arguments MUST have a unique ID.
    • Method Detail

      • getID

        public java.lang.String getID()
        Returns this parameter's unique ID.
        Returns:
        this parameter's unique ID.
      • setLocked

        protected final void setLocked​(boolean locked)
        Locks or unlocks this parameter. Locked parameters cannot be modified. This is necessary because the JSAP object with which parameters are registered performs certain validation routines at the time of registration. See JSAP.registerParameter(Parameter) for more information.
        Parameters:
        locked - if TRUE, locks this parameter. if FALSE, unlocks it.
        See Also:
        JSAP.registerParameter(Parameter)
      • locked

        protected final boolean locked()
        Returns a boolean indicating whether this parameter is locked.
        Returns:
        a boolean indicating whether this parameter is currently locked.
      • enforceParameterLock

        protected final void enforceParameterLock()
        Helper method that can be called by any methods that modify this parameter (or its subclasses). If the parameter is currently locked, an IllegalStateException is thrown.
      • _setDefault

        protected final void _setDefault​(java.lang.String defaultValue)
        Sets a default value for this parameter. The default is specified as a String, and is parsed as a single value specified on the command line. In other words, default values for "list" parameters or parameters allowing multiple declarations should be set using setDefault(String[]), as JSAP would otherwise treat the entire list of values as a single value.
        Parameters:
        defaultValue - the default value for this parameter.
      • _setDefault

        protected final void _setDefault​(java.lang.String[] defaultValues)
        Sets one or more default values for this parameter. This method should be used whenever a parameter has more than one default value.
        Parameters:
        defaultValues - the default values for this parameter.
      • addDefault

        public final void addDefault​(java.lang.String defaultValue)
        Adds a single default value to any currently defined for this parameter.
        Parameters:
        defaultValue - the default value to add to this parameter.
      • _setUsageName

        protected final void _setUsageName​(java.lang.String usageName)
        Sets the name of this AbstractParameter for the purposes of usage information. If null, the id will be used.
        Parameters:
        usageName - the usage name for this AbstractParameter
      • getUsageName

        public final java.lang.String getUsageName()
        Returns the name of this AbstractParameter for the purposes of usage information. The returned value is by default the id of this parameter, but can be overridden via setUsageName(String).
        Returns:
        the name of this AbstractParameter for the purposes of usage information.
      • getDefault

        public final java.lang.String[] getDefault()
        Returns an array of default values for this parameter, or null if no default values have been defined.
        Returns:
        an array of default values for this parameter, or null if no default values have been defined.
      • parse

        protected abstract java.util.List parse​(java.lang.String arg)
                                         throws ParseException
        Returns an ArrayList of values resulting from the parsing of the specified argument. Multiple values may be returned if the arg is a list (such as a PATH or CLASSPATH variable), or if the semantics of the parameter type otherwise represent multiple values.
        Parameters:
        arg - the argument to parse.
        Returns:
        a List of values resulting from the parse.
        Throws:
        ParseException - if the specified argument cannot be parsed.
      • getSyntax

        public abstract java.lang.String getSyntax()
        A convenience method for automatically generating syntax information based upon a JSAP configuration. A call to JSAP.getSyntax() returns a String built by calling getSyntax() on every parameter registered to a JSAP in the order in which they were registered. This method does not provide a help description (see getHelp()), but rather the syntax for this parameter.
        Returns:
        usage information for this parameter.
      • getUsage

        public final java.lang.String getUsage()
        Deprecated.
        use getSyntax() instead
        Deprecated - use getSyntax()
        Returns:
        deprecated - use getSyntax()
      • getHelp

        public final java.lang.String getHelp()
        Returns a description of the option's usage.
        Returns:
        a textual description of this option's usage
      • setHelp

        public final Parameter setHelp​(java.lang.String help)
        Sets the help text for this parameter.
        Parameters:
        help - the help text for this parameter.