uk.ac.starlink.task

## Class LineEnvironment

- java.lang.Object
- - uk.ac.starlink.task.LineEnvironment

- All Implemented Interfaces:
    Environment

      public class LineEnvironment
      extends java.lang.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 and Description
    --- | ---
    `static char` | `INDIRECTION_CHAR`
    `static int` | `NUM_TRIES`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LineEnvironment()` Constructs a LineEnvironment without any additional initialisation.
    `LineEnvironment(java.lang.String[] args, Parameter[] params)` Constructs a new LineEnvironment, initialising it with a set of command line arguments.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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.
    `java.lang.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.
    `java.io.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.
    `java.lang.String[]` | `getNames()` Returns an array of parameter names which have been specified.
    `java.io.PrintStream` | `getOutputStream()` Returns an output stream into which text output from a task can be written.
    `java.lang.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.
    `java.lang.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(java.lang.String envName, Parameter param)` Indicates whether a parameter name supplied from the environment is a reference to a given parameter.
    `void` | `setErrorStream(java.io.PrintStream err)` Sets the destination stream for standard error.
    `void` | `setInteractive(boolean interactive)` Sets whether we are running interactively or not.
    `void` | `setOutputStream(java.io.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 Detail

    - #### INDIRECTION_CHAR

          public static final char INDIRECTION_CHAR

      See Also:
        Constant Field Values

    - #### NUM_TRIES

          public static final int NUM_TRIES

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### 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(java.lang.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 Detail

    - #### setWords

          public void setWords(LineWord[] words)

      Sets the words supplying the parameter values for this environment.
      Parameters:
        `words` - list of words

    - #### getParamHelp

          public java.lang.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 java.lang.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(java.io.PrintStream out)

      Sets the destination stream for standard out.
      Parameters:
        `out` - output stream

    - #### setErrorStream

          public void setErrorStream(java.io.PrintStream err)

      Sets the destination stream for standard error.
      Parameters:
        `err` - error stream

    - #### getOutputStream

          public java.io.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 java.io.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 java.lang.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 java.lang.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(java.lang.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`

Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.