# Class ChoiceParameter<T>

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

public class ChoiceParameter<T> extends AbstractChoiceParameter<T,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 Parameter

`BY_NAME`

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`String`
`getUsage()`
Returns a usage message.
`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(String usage)`
Sets a usage string for this parameter.
`T`
`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 AbstractChoiceParameter

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

### Methods inherited from class 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 Object

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

## Constructor Details

### ChoiceParameter

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

### stringToObject

public T 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<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 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

### getUsage

public String getUsage()
Returns a usage message. Unless it has been overriden by an earlier call to `setUsage(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(String)`

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