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(String name, char valueSep, C[] options)`
Constructor with implicit element type.
`MultiChoiceParameter(String name, Class<C> optClazz, char valueSep, C[] options)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`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.
`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(String usage)`
Sets a usage string for this parameter.
`C[]`
`stringToObject(Environment env, 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 Details

### MultiChoiceParameter

public MultiChoiceParameter(String name, 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(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 Details

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