Package uk.ac.starlink.task

## Class ChoiceParameter<T>

- java.lang.Object
- - uk.ac.starlink.task.Parameter<T>
  - - uk.ac.starlink.task.ChoiceParameter<T>

-     public class ChoiceParameter<T>
      extends Parameter<T>

  Parameter whose legal value must be one of a disjunction of given values. Matching is case-insensitive against the stringified value of the option.
  Since:
    15 Aug 2005
  Author:
    Mark Taylor

- - ### Field Summary

    - ### Fields inherited from class uk.ac.starlink.task.Parameter

      `BY_NAME`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ChoiceParameter​(java.lang.String name, java.lang.Class<T> clazz)` | Constructs a choice parameter with no initially set options.
    `ChoiceParameter​(java.lang.String name, java.lang.Class<T> clazz, T[] options)` | Constructor.
    `ChoiceParameter​(java.lang.String name, T[] options)` | Constructs a choice parameter with an initial option set.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addOption​(T option)` | Adds an option value to this parameter.
    `void` | `addOption​(T option, java.lang.String name)` | Adds an option value to this parameter with a given name.
    `void` | `clearOptions()` | Clears the list of known options.
    `java.lang.String` | `getName​(T option)` | Converts an option value object to a string which is used to identify it as a string value of this parameter.
    `T` | `getOption​(java.lang.String name)` | Returns the option value associated with a given string by this parameter.
    `java.lang.String[]` | `getOptionNames()` | Returns an array of the string values of options accepted by this parameter.
    `T[]` | `getOptions()` | Returns an array of the option objects which may form the values of this parameter.
    `java.util.Collection<T>` | `getOptionValueList()` | Returns a collection of the option objects which may form the values of this parameter.
    `java.lang.String` | `getUsage()` | Returns a usage message.
    `java.lang.String` | `objectToString​(Environment env, T objVal)` | Takes a typed value of this parameter and formats it as a string which may be used for presentation to the user.
    `void` | `setDefaultOption​(T option)` | Sets the default value for this parameter to one of the previously added options.
    `void` | `setUsage​(java.lang.String usage)` | Sets a usage string for this parameter.
    `java.lang.String` | `stringifyOption​(T option)` | Determines how an option will be represented as a string value of this parameter if no name has explicitly been supplied.
    `T` | `stringToObject​(Environment env, java.lang.String sval)` | Takes a non-blank string, as supplied by the execution environment, and turns it into a typed value for this parameter.

    - ### Methods inherited from class uk.ac.starlink.task.Parameter

      `clearValue, getDescription, getName, getPosition, getPreferExplicit, getPrompt, getStringDefault, getValueClass, isNullPermitted, objectValue, setDescription, setDescription, setName, setNullPermitted, setPosition, setPreferExplicit, setPrompt, setStringDefault, setValue, setValueFromObject, setValueFromString, stringValue, toArray, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ChoiceParameter

          public ChoiceParameter​(java.lang.String name,
                                 java.lang.Class<T> clazz,
                                 T[] options)

      Constructor.
      Parameters:
        `name` - parameter name
        `clazz` - type for values of this parameter
        `options` - initial array of legal values of this parameter

    - #### ChoiceParameter

          public ChoiceParameter​(java.lang.String name,
                                 java.lang.Class<T> clazz)

      Constructs a choice parameter with no initially set options.
      Parameters:
        `name` - parameter name
        `clazz` - type for values of this parameter

    - #### ChoiceParameter

          public ChoiceParameter​(java.lang.String name,
                                 T[] options)

      Constructs a choice parameter with an initial option set. The data type is taken from the supplied array type.
      Parameters:
        `name` - parameter name
        `options` - initial array of legal values of this parameter

  - ### Method Detail

    - #### stringToObject

          public T stringToObject​(Environment env,
                                  java.lang.String sval)
                           throws TaskException

      Description copied from class: `Parameter`
      Takes a non-blank string, as supplied by the execution environment, and turns it into a typed value for this parameter. This method also performs validation, so if the string value is unacceptable in any way, a ParameterValueException should be thrown.

      It is an error to supply a null or empty string value.

      If this method fails (throws a ParameterValueException) and if `allowClassnameValue` is set, then a subsequent attempt will be made to interpret the `stringVal` as the classname of a suitable class with a no-arg constructor.

      Specified by:
        `stringToObject` in class `Parameter<T>`
      Parameters:
        `env` - execution environment; in most cases this is not required but for some purposes environment-specific characteristics may influence the result
        `sval` - non-null, non-empty string value
      Returns:
        typed value
      Throws:
        `TaskException`

    - #### objectToString

          public java.lang.String objectToString​(Environment env,
                                                 T objVal)

      Description copied from class: `Parameter`
      Takes a typed value of this parameter and formats it as a string which may be used for presentation to the user. Ideally, round-tripping between this method and `stringToObject` should be possible, but that is not in general required/guaranteed.

      The default implementation uses the value's toString method, but subclasses can override this for smarter behaviour.

      Overrides:
        `objectToString` in class `Parameter<T>`
      Parameters:
        `env` - execution environment
        `objVal` - typed parameter value
      Returns:
        string value for presentation

    - #### addOption

          public void addOption​(T option,
                                java.lang.String name)

      Adds an option value to this parameter with a given name. The name is the parameter value string used to identify this option.
      Parameters:
        `option` - option object
        `name` - label for option

    - #### addOption

          public void addOption​(T option)

      Adds an option value to this parameter. The option's name will be determined by this object's `stringifyOption(T)` method.
      Parameters:
        `option` - option object

    - #### clearOptions

          public void clearOptions()

      Clears the list of known options.

    - #### getUsage

          public java.lang.String getUsage()

      Returns a usage message. Unless it has been overriden by an earlier call to `setUsage(java.lang.String)`, this will return a usage message based on the list of known options.
      Overrides:
        `getUsage` in class `Parameter<T>`
      Returns:
        usage message
      See Also:
        `Parameter.setUsage(java.lang.String)`

    - #### setUsage

          public void setUsage​(java.lang.String usage)

      Description copied from class: `Parameter`
      Sets a usage string for this parameter. This should be terse (in particular no newline characters) and conform to the following rules:
      - the parameter name is not included in the message
      - placeholders are enclosed in angle brackets (<>)
      - literals are not enclosed in angle brackets
      - a disjunction is represented using the "|" character
      The `Parameter` class uses the string "<value>" as the default usage string.
      Overrides:
        `setUsage` in class `Parameter<T>`
      Parameters:
        `usage` - usage string

    - #### setDefaultOption

          public void setDefaultOption​(T option)

      Sets the default value for this parameter to one of the previously added options.
      Parameters:
        `option` - default option

    - #### getOptionNames

          public java.lang.String[] getOptionNames()

      Returns an array of the string values of options accepted by this parameter.
      Returns:
        permitted options, stringified

    - #### getOptions

          public T[] getOptions()

      Returns an array of the option objects which may form the values of this parameter.
      Returns:
        permitted options

    - #### getOptionValueList

          public java.util.Collection<T> getOptionValueList()

      Returns a collection of the option objects which may form the values of this parameter.
      Returns:
        permitted options

    - #### getName

          public java.lang.String getName​(T option)

      Converts an option value object to a string which is used to identify it as a string value of this parameter.
      Parameters:
        `option` - option value
      Returns:
        string representation

    - #### stringifyOption

          public java.lang.String stringifyOption​(T option)

      Determines how an option will be represented as a string value of this parameter if no name has explicitly been supplied. The default implementation is `String.valueOf(option)`, but this may be overrridden.
      Parameters:
        `option` - option value
      Returns:
        string representation of option

    - #### getOption

          public T getOption​(java.lang.String name)

      Returns the option value associated with a given string by this parameter. Null is returned if none of the options added so far has a name as supplied. Name matching is case-insensitive.
      Parameters:
        `name` - name of option which has been added
      Returns:
        correspondig option object