Package uk.ac.starlink.task
Class LineEnvironment
java.lang.Object
uk.ac.starlink.task.LineEnvironment
- All Implemented Interfaces:
Environment
Execution environment for use from the command line.
Arguments are supplied as
LineWord
objects.- Since:
- 27 Nov 2006
- Author:
- Mark Taylor
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a LineEnvironment without any additional initialisation.LineEnvironment
(String[] args, Parameter<?>[] params) Constructs a new LineEnvironment, initialising it with a set of command line arguments. -
Method Summary
Modifier and TypeMethodDescriptionvoid
acquireValue
(Parameter<?> param) Obtains a legal value for a given parameter from the environment and sets the parameter's value accordingly.void
checkParameters
(Parameter<?>[] params) Checks that this environment's values are compatible with the given list of parameters.void
clearValue
(Parameter<?> par) Clears a value for a given parameter.String[]
Returns an array of strings, one for each parameter assignment which was actually used (viaacquireValue(uk.ac.starlink.task.Parameter<?>)
) for this environment.Returns an output stream into which error or logging output from a task can be written.boolean
Determines whether we are running interactively.String[]
getNames()
Returns an array of parameter names which have been specified.Returns an output stream into which text output from a task can be written.getParamHelp
(Parameter<?> param) Returns the help string for a given parameter.boolean
Determines whether all parameters which haven't received explicit values on the command line should be prompted for.String[]
Returns a string containing any words of the input argument list which were never queried by the application to find their value.boolean
Determines whether a parameter is "hidden", that is its value should not be revealed to prying eyes.boolean
paramNameMatches
(String envName, Parameter<?> param) Indicates whether a parameter name supplied from the environment is a reference to a given parameter.void
Sets the destination stream for standard error.void
setInteractive
(boolean interactive) Sets whether we are running interactively or not.void
Sets the destination stream for standard out.void
setPromptAll
(boolean prompt) Sets whether all parameters which haven't received explicit values on the command line should be prompted for.void
Sets the words supplying the parameter values for this environment.
-
Field Details
-
INDIRECTION_CHAR
public static final char INDIRECTION_CHAR- See Also:
-
NUM_TRIES
public static final int NUM_TRIES- See Also:
-
-
Constructor Details
-
LineEnvironment
public LineEnvironment()Constructs a LineEnvironment without any additional initialisation. A subsequent call ofsetWords(uk.ac.starlink.task.LineWord[])
must be made before it is interrogated for values. -
LineEnvironment
Constructs a new LineEnvironment, initialising it with a set of command line arguments. These are checked against a set of parameters. The arguments must be of the formname=value
, or justvalue
for positional arguments. If any of these refer to parameters not in theparams
list, an exception will be thrown.- Parameters:
args
- command-line argumentsparams
- parameters thatargs
provide values for- Throws:
UsageException
-
-
Method Details
-
setWords
Sets the words supplying the parameter values for this environment.- Parameters:
words
- list of words
-
getParamHelp
Returns the help string for a given parameter. This should be supplied in ready-to-use form, that is formatted for a suitable screen width etc.- Parameters:
param
- parameter- Returns:
- formatted documentation for
param
-
isHidden
Determines whether a parameter is "hidden", that is its value should not be revealed to prying eyes. The default implementation returns false.- Parameters:
param
- param- Returns:
- true if param is hidden type
-
checkParameters
Checks that this environment's values are compatible with the given list of parameters. If any of the values does not appear to be a spcecification of one of the listed parameters a UsageException will be thrown.- Parameters:
params
- parameter list- Throws:
UsageException
-
getNames
Description copied from interface:Environment
Returns an array of parameter names which have been specified. The result is not necessarily an exhaustive list of all parameters whose values can be retrieved from this environment, since an interactive environment may be able to prompt the user for values, but it can give a list of values provided explicitly or without interactive prompts.- Specified by:
getNames
in interfaceEnvironment
- Returns:
- array of names of known supplied parameters
-
setInteractive
public void setInteractive(boolean interactive) Sets whether we are running interactively or not. Only if this attribute is true will any attempt be made to prompt the user for responses etc. Default is true.- Parameters:
interactive
- whether we are running interactively
-
getInteractive
public boolean getInteractive()Determines whether we are running interactively. Only if this attribute is true will any attempt be made to prompt the user for responses etc. Default is true.- Returns:
- whether we are running interactively
-
setPromptAll
public void setPromptAll(boolean prompt) Sets whether all parameters which haven't received explicit values on the command line should be prompted for. Default is false. Only makes sense if we're running interatively.- Parameters:
prompt
- whether to prompt for everything
-
getPromptAll
public boolean getPromptAll()Determines whether all parameters which haven't received explicit values on the command line should be prompted for. Default is false.- Returns:
- whether to prompt for everything
-
clearValue
Description copied from interface:Environment
Clears a value for a given parameter.- Specified by:
clearValue
in interfaceEnvironment
- Parameters:
par
- the Parameter whose value is to be cleared
-
setOutputStream
Sets the destination stream for standard out.- Parameters:
out
- output stream
-
setErrorStream
Sets the destination stream for standard error.- Parameters:
err
- error stream
-
getOutputStream
Description copied from interface:Environment
Returns an output stream into which text output from a task can be written. This would correspond to standard output for a terminal-based application.- Specified by:
getOutputStream
in interfaceEnvironment
- Returns:
- a stream for text output
-
getErrorStream
Description copied from interface:Environment
Returns an output stream into which error or logging output from a task can be written. This would correspodnd to standard error for a terminal-based application.- Specified by:
getErrorStream
in interfaceEnvironment
- Returns:
- a stream for error output
-
acquireValue
Description copied from interface:Environment
Obtains a legal value for a given parameter from the environment and sets the parameter's value accordingly.This environment should obtain a value for the parameter par in whatever way it sees fit, and must then call par's
Parameter.setValueFromString(uk.ac.starlink.task.Environment, java.lang.String)
method so that the parameter knows what its new value is. If the setValueFromString call throws a ParameterValueException the environment may try to get another value (for instance by re-prompting the user) or may give up and re-throw the exception.- Specified by:
acquireValue
in interfaceEnvironment
- Parameters:
param
- the Parameter whose value is to be obtained and set- Throws:
TaskException
-
getUnused
Returns a string containing any words of the input argument list which were never queried by the application to find their value. Such unused words probably merit a warning, since they may for instance be misspelled versions of real parameters.- Returns:
- array of unused words
-
getAssignments
Returns an array of strings, one for each parameter assignment which was actually used (viaacquireValue(uk.ac.starlink.task.Parameter<?>)
) for this environment.- Returns:
- array of parameter assignment strings
-
paramNameMatches
Indicates whether a parameter name supplied from the environment is a reference to a given parameter.The implementation in the
LineEnvironment
class performs case-insensitive matching against theparam.getName()
. This behaviour may be overridden by subclasses to change the environment's behaviour.- Parameters:
envName
- parameter name from environmentparam
- parameter- Returns:
- true iff
envName
is considered to nameparam
-