# 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 Summary

Constructors
Constructor
Description
`CommandFormatter(CredibleString invocation, boolean includeDflts, LineEnder lineEnder, int levelIndent, int cwidth, boolean addSuggestions)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`static StyledDocument`
`createBasicDocument(String txt)`
Utility method returning a StyledDocument instance with some supplied plain text.
`uk.ac.starlink.task.Executable`
`createExecutable(StiltsCommand command)`
Creates a task Executable based on the state of this formatter.
`StyledDocument`
`createShellDocument(StiltsCommand command)`
Returns a Document, suitable for use with a JTextPane, formatting the given plot specification.
`CredibleString`
`getInvocation()`
Returns the invocation used to introduce the STILTS command.
`void`
`populateEnvironment(StiltsCommand command, MapEnvironment env)`
Adds entries to a supplied execution environment corresponding to the STILTS parameters defined by this specification.
`void`
`setForceError(boolean forceError)`
Sets whether the generated stilts commands will be made to produce a gratuitous error.
`protected String[]`
`stripExpectedUnused(uk.ac.starlink.task.Task task, String[] words)`
Remove words from the list of unused words that are harmless.

### Methods inherited from class Object

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

## 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