Package uk.ac.starlink.task

Class LineEnvironment

java.lang.Object
uk.ac.starlink.task.LineEnvironment
All Implemented Interfaces:
Environment
public class LineEnvironment extends Object implements 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
    Modifier and Type
    Field
    Description
    static final char
    INDIRECTION_CHAR
     
    static final int
    NUM_TRIES
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    LineEnvironment()
    Constructs 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 Type
    Method
    Description
    void
    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[]
    getAssignments()
    Returns an array of strings, one for each parameter assignment which was actually used (via acquireValue(uk.ac.starlink.task.Parameter<?>)) for this environment.
    PrintStream
    getErrorStream()
    Returns an output stream into which error or logging output from a task can be written.
    boolean
    getInteractive()
    Determines whether we are running interactively.
    String[]
    getNames()
    Returns an array of parameter names which have been specified.
    PrintStream
    getOutputStream()
    Returns an output stream into which text output from a task can be written.
    String
    getParamHelp(Parameter<?> param)
    Returns the help string for a given parameter.
    boolean
    getPromptAll()
    Determines whether all parameters which haven't received explicit values on the command line should be prompted for.
    String[]
    getUnused()
    Returns a string containing any words of the input argument list which were never queried by the application to find their value.
    boolean
    isHidden(Parameter<?> param)
    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
    setErrorStream(PrintStream err)
    Sets the destination stream for standard error.
    void
    setInteractive(boolean interactive)
    Sets whether we are running interactively or not.
    void
    setOutputStream(PrintStream out)
    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
    setWords(LineWord[] words)
    Sets the words supplying the parameter values for this environment.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • LineEnvironment

      public LineEnvironment()
      Constructs a LineEnvironment without any additional initialisation. A subsequent call of setWords(uk.ac.starlink.task.LineWord[]) must be made before it is interrogated for values.

    • LineEnvironment

      public LineEnvironment(String[] args, Parameter<?>[] params) throws UsageException
      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 form name=value, or just value for positional arguments. If any of these refer to parameters not in the params list, an exception will be thrown.
      Parameters:
      args - command-line arguments
      params - parameters that args provide values for
      Throws:
      UsageException

  • Method Details

    • setWords

      public void setWords(LineWord[] words)
      Sets the words supplying the parameter values for this environment.
      Parameters:
      words - list of words

    • getParamHelp

      public String getParamHelp(Parameter<?> param)
      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

      public boolean isHidden(Parameter<?> param)
      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

      public void checkParameters(Parameter<?>[] params) throws UsageException
      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

      public String[] 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 interface Environment
      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

      public void clearValue(Parameter<?> par)
      Description copied from interface: Environment
      Clears a value for a given parameter.
      Specified by:
      clearValue in interface Environment
      Parameters:
      par - the Parameter whose value is to be cleared

    • setOutputStream

      public void setOutputStream(PrintStream out)
      Sets the destination stream for standard out.
      Parameters:
      out - output stream

    • setErrorStream

      public void setErrorStream(PrintStream err)
      Sets the destination stream for standard error.
      Parameters:
      err - error stream

    • getOutputStream

      public PrintStream 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 interface Environment
      Returns:
      a stream for text output

    • getErrorStream

      public PrintStream 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 interface Environment
      Returns:
      a stream for error output

    • acquireValue

      public void acquireValue(Parameter<?> param) throws TaskException
      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 interface Environment
      Parameters:
      param - the Parameter whose value is to be obtained and set
      Throws:
      TaskException

    • getUnused

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

      public String[] getAssignments()
      Returns an array of strings, one for each parameter assignment which was actually used (via acquireValue(uk.ac.starlink.task.Parameter<?>)) for this environment.
      Returns:
      array of parameter assignment strings

    • paramNameMatches

      public boolean paramNameMatches(String envName, Parameter<?> param)
      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 the param.getName(). This behaviour may be overridden by subclasses to change the environment's behaviour.

      Parameters:
      envName - parameter name from environment
      param - parameter
      Returns:
      true iff envName is considered to name param