Class CommandFormatter

java.lang.Object
uk.ac.starlink.ttools.task.CommandFormatter
Direct Known Subclasses:
PlotCommandFormatter

public class CommandFormatter extends Object
Handles export of StiltsCommand objects to external serialization formats.
Since:
27 Sep 2024
Author:
Mark Taylor
  • Constructor Details

    • CommandFormatter

      public CommandFormatter(CredibleString invocation, boolean includeDflts, LineEnder lineEnder, int levelIndent, int cwidth, boolean addSuggestions)
      Constructor.
      Parameters:
      invocation - display text to introduce the STILTS command
      includeDflts - if true, all parameters are included; if false, only those with non-default values
      lineEnder - line end presentation policy
      levelIndent - number of spaces per indentation level
      cwidth - nominal formatting width in characters; this affects line wrapping, but actual wrapping may depend on other factors too
      addSuggestions - if true, some parameters that might be useful but are not necessary may be added
  • Method Details

    • getInvocation

      public CredibleString getInvocation()
      Returns the invocation used to introduce the STILTS command.
      Returns:
      STILTS invocation string
    • setForceError

      public void setForceError(boolean forceError)
      Sets whether the generated stilts commands will be made to produce a gratuitous error. This is only useful for debugging purposes.
      Parameters:
      forceError - true to force an error from generated commands
    • createExecutable

      public uk.ac.starlink.task.Executable createExecutable(StiltsCommand command) throws uk.ac.starlink.task.TaskException
      Creates a task Executable based on the state of this formatter. Various exceptions may be thrown if there is some error. Such errors are quite possible.

      If this method returns without error there is a fair chance that the serializations predicted from this object will represent legal STILTS commands.

      Parameters:
      command - command specification
      Returns:
      executable
      Throws:
      uk.ac.starlink.task.TaskException - if there is some other error in setting up the executable; probably incorrect parameter assignments of some kind
    • createShellDocument

      public StyledDocument createShellDocument(StiltsCommand command)
      Returns a Document, suitable for use with a JTextPane, formatting the given plot specification. This may include coloured highlighting etc. depending on configuration.
      Parameters:
      command - command specification
    • stripExpectedUnused

      protected String[] stripExpectedUnused(uk.ac.starlink.task.Task task, String[] words)
      Remove words from the list of unused words that are harmless.

      This is a hook for a hack. Some of the parameter settings can be unused when object values for other parameter settings are used. If that happens, it looks like there is a problem because settings have not been used. This routine can pull them out so the warning goes away.

      Parameters:
      task - task
      words - input command word list
      Returns:
      list apart from any words that shouldn't be there
    • populateEnvironment

      public void populateEnvironment(StiltsCommand command, MapEnvironment env)
      Adds entries to a supplied execution environment corresponding to the STILTS parameters defined by this specification.
      Parameters:
      command - command specification
      env - execution environment to populate; should probably be empty on entry
    • createBasicDocument

      public static StyledDocument createBasicDocument(String txt)
      Utility method returning a StyledDocument instance with some supplied plain text.
      Parameters:
      txt - text content
      Returns:
      document