ChoiceParameter (Starjava Task API)

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

Class ChoiceParameter<T>

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Constructor Detail

ChoiceParameter

ChoiceParameter

ChoiceParameter

Method Detail

stringToObject

objectToString

addOption

addOption

clearOptions

getUsage

setUsage

setDefaultOption

getOptionNames

getOptions

getOptionValueList

getName

stringifyOption

getOption