Package uk.ac.starlink.task

## Class MultiChoiceParameter<C>

- java.lang.Object
- - uk.ac.starlink.task.Parameter<T>
  - - uk.ac.starlink.task.AbstractChoiceParameter<C[],​C>
    - - uk.ac.starlink.task.MultiChoiceParameter<C>

- Type Parameters:
    `C` - type for single element of parameter output array
  All Implemented Interfaces:
    `MultiParameter`

      public class MultiChoiceParameter<C>
      extends AbstractChoiceParameter<C[],​C>
      implements MultiParameter

  MultiParameter that returns an array of values from a given typed list of options. Matching is case-insensitive against the stringified value of the option.
  Since:
    17 Dec 2021
  Author:
    Mark Taylor

- - ### Field Summary

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

      `BY_NAME`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MultiChoiceParameter​(java.lang.String name, char valueSep, C[] options)` | Constructor with implicit element type.
    `MultiChoiceParameter​(java.lang.String name, java.lang.Class<C> optClazz, char valueSep, C[] options)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `getUsage()` | Returns the usage string for this parameter.
    `char` | `getValueSeparator()` | Returns a character which is to be used as the separator between values found in adjacent occurrences of the parameter in the execution environment.
    `java.lang.String` | `objectToString​(Environment env, C[] objVal)` | Takes a typed value of this parameter and formats it as a string which may be used for presentation to the user.
    `void` | `setDefaultOptions​(C[] options)` | Sets the default value for this parameter to an array containing previously added options.
    `void` | `setUsage​(java.lang.String usage)` | Sets a usage string for this parameter.
    `C[]` | `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.AbstractChoiceParameter

      `addOption, addOption, choiceToString, clearOptions, getName, getOption, getOptionNames, getOptions, getOptionValueList, stringifyOption, stringToChoice`

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

    - #### MultiChoiceParameter

          public MultiChoiceParameter​(java.lang.String name,
                                      java.lang.Class<C> optClazz,
                                      char valueSep,
                                      C[] options)

      Constructor.
      Parameters:
        `name` - parameter name
        `optClazz` - type for element value of this parameter
        `valueSep` - separator character for multiple values in a string
        `options` - initial array of legal element values for this parameter

    - #### MultiChoiceParameter

          public MultiChoiceParameter​(java.lang.String name,
                                      char valueSep,
                                      C[] options)

      Constructor with implicit element type.
      Parameters:
        `name` - parameter name
        `valueSep` - separator character for multiple values in a string
        `options` - initial array of legal element values for this parameter

  - ### Method Detail

    - #### getValueSeparator

          public char getValueSeparator()

      Description copied from interface: `MultiParameter`
      Returns a character which is to be used as the separator between values found in adjacent occurrences of the parameter in the execution environment.
      Specified by:
        `getValueSeparator` in interface `MultiParameter`

    - #### stringToObject

          public C[] 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<C[]>`
      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,
                                                 C[] 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<C[]>`
      Parameters:
        `env` - execution environment
        `objVal` - typed parameter value
      Returns:
        string value for presentation

    - #### 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<C[]>`
      Parameters:
        `usage` - usage string

    - #### getUsage

          public java.lang.String getUsage()

      Description copied from class: `Parameter`
      Returns the usage string for this parameter.
      Overrides:
        `getUsage` in class `Parameter<C[]>`
      Returns:
        usage string
      See Also:
        `Parameter.setUsage(java.lang.String)`

    - #### setDefaultOptions

          public void setDefaultOptions​(C[] options)

      Sets the default value for this parameter to an array containing previously added options.
      Parameters:
        `options` - default parameter value