uk.ac.starlink.ttools.task

Class WordsParameter<W>

java.lang.Object

uk.ac.starlink.task.Parameter<W[]>

uk.ac.starlink.ttools.task.WordsParameter<W>

Type Parameters:

W - parsed type of each word

public class WordsParameter<W>
extends Parameter<W[]>

Parameter which can split its value up into an array of words, each parsed as a parameterised type. Words are generally delimited by whitespace, but can be quoted using single or double quotes as in the shell. You can specify the required number of words.

Since:

1 Sep 2005

Author:

Mark Taylor

Field Summary

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

BY_NAME

Constructor Summary

Constructors

Constructor and Description
WordsParameter(String name, Class<W[]> arrayClazz, WordParser<W> parser) Constructor.

Method Summary

Modifier and Type	Method and Description
static WordsParameter<Boolean>	createBooleanWordsParameter(String name) Returns an instance for which words are parsed as Booleans.
static WordsParameter<Double>	createDoubleWordsParameter(String name) Returns an instance for which words are parsed as Doubles.
static WordsParameter<Integer>	createIntegerWordsParameter(String name) Returns an instance for which words are parsed as Integers.
static WordsParameter<String>	createStringWordsParameter(String name) Returns an instance for which words are simply parsed as strings.
int	getRequiredWordCount() Returns the number of words required from this parameter.
WordParser<W>	getWordParser() Returns the parser which is being used to validate and to parse each word in the supplied value string.
void	setRequiredWordCount(int nWords) Sets the number of words required from this parameter.
void	setWordUsage(String wordUsage) Configures the usage of this parameter from usages for given words.
W[]	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.
W[]	wordsValue(Environment env) Returns the typed value of this parameter.

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

clearValue, getDescription, getName, getPosition, getPreferExplicit, getPrompt, getStringDefault, getUsage, getValueClass, isNullPermitted, objectToString, objectValue, setDescription, setDescription, setName, setNullPermitted, setPosition, setPreferExplicit, setPrompt, setStringDefault, setUsage, 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

WordsParameter

public WordsParameter(String name,
                      Class<W[]> arrayClazz,
                      WordParser<W> parser)

Constructor.

Parameters:

name - parameter name

arrayClazz - array output class of this parameter

parser - converts each input word string to a typed value

Method Detail

setRequiredWordCount

public void setRequiredWordCount(int nWords)

Sets the number of words required from this parameter. If it is -1 (the default), then no restrictions are placed on the number of words. Otherwise, attempting to set the value to the wrong number of words is an error.

Parameters:

nWords - required number of words

getRequiredWordCount

public int getRequiredWordCount()

Returns the number of words required from this parameter. If it is -1 (the default), then no restrictions are placed on the number of words. Otherwise, attempting to set the value to the wrong number of words is an error.

Returns:

required number of words

getWordParser

public WordParser<W> getWordParser()

Returns the parser which is being used to validate and to parse each word in the supplied value string.

Returns:

word parser

setWordUsage

public void setWordUsage(String wordUsage)

Configures the usage of this parameter from usages for given words.

Parameters:

wordUsage - per-word usage

wordsValue

public W[] wordsValue(Environment env)
               throws TaskException

Returns the typed value of this parameter. If the required word count value of this parameter is non-negative, then the return value is guaranteed to contain that number of elements.

This is just an alias for Parameter.objectValue(uk.ac.starlink.task.Environment).

Parameters:

env - execution environment

Returns:

array of words constituting the value of this parameter

Throws:

TaskException

stringToObject

public W[] 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<W[]>

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

createStringWordsParameter

public static WordsParameter<String> createStringWordsParameter(String name)

Returns an instance for which words are simply parsed as strings.

Parameters:

name - parameter name

Returns:

new WordsParameter

createIntegerWordsParameter

public static WordsParameter<Integer> createIntegerWordsParameter(String name)

Returns an instance for which words are parsed as Integers.

Parameters:

name - parameter name

Returns:

new WordsParameter

createDoubleWordsParameter

public static WordsParameter<Double> createDoubleWordsParameter(String name)

Returns an instance for which words are parsed as Doubles.

Parameters:

name - parameter name

Returns:

new WordsParameter

createBooleanWordsParameter

public static WordsParameter<Boolean> createBooleanWordsParameter(String name)

Returns an instance for which words are parsed as Booleans.

Parameters:

name - parameter name

Returns:

new WordsParameter