uk.ac.starlink.ttools.task

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 and Description
CommandFormatter(CredibleString invocation, boolean includeDflts, LineEnder lineEnder, int levelIndent, int cwidth, boolean addSuggestions) Constructor.

Method Summary

Modifier and Type	Method and Description
static StyledDocument	createBasicDocument(String txt) Utility method returning a StyledDocument instance with some supplied plain text.
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(Task task, String[] words) Remove words from the list of unused words that are harmless.

Methods inherited from class java.lang.Object

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

Constructor Detail

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 Detail

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 Executable createExecutable(StiltsCommand command)
                            throws 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:

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