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
-
-
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
-
-
-
-
Constructor Detail
-
ChoiceParameter
public ChoiceParameter(java.lang.String name, java.lang.Class<T> clazz, T[] options)
Constructor.- Parameters:
name
- parameter nameclazz
- type for values of this parameteroptions
- 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 nameclazz
- 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 nameoptions
- 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 thestringVal
as the classname of a suitable class with a no-arg constructor.- Specified by:
stringToObject
in classParameter<T>
- Parameters:
env
- execution environment; in most cases this is not required but for some purposes environment-specific characteristics may influence the resultsval
- 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 andstringToObject
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 classParameter<T>
- Parameters:
env
- execution environmentobjVal
- 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 objectname
- 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'sstringifyOption(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 tosetUsage(java.lang.String)
, this will return a usage message based on the list of known options.- Overrides:
getUsage
in classParameter<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
Parameter
class uses the string "<value>" as the default 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 isString.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
-
-