PIRL.PVL

## Class Lister

- java.lang.Object
- - PIRL.PVL.Lister

    public class Lister
    extends Object

A Lister writes PVL syxtax.

A Lister complements a Parser in that the latter interprets Parameter Value Language (PVL) syntax from a Reader into Parameter and Value objects, while the former generates PVL syntax to a Writer.

See Also:
  `Parser`, `Parameter`, `Value`

### Field Summary

Fields
`static boolean` `First_Warning_Default` The default for returning the `first warning` (or `last warning`).
`static String` `ID` Class name and version identification.
`static String` `INDENT` The indent character(s).
`static boolean` `Indent_Arrays_Default` The default for applying `array indenting`.
`static int` `Indent_Level_Default` The default `statement base indent level` (none if negative).
`static String` `NEW_LINE` The platform's native line separator (newline) String.
`static boolean` `Strict_Default` The default for enforcing `strict` PVL syntax rules.
`static boolean` `Verbatim_Strings_Default` `Verbatim strings` default.

### Constructor Summary

Constructors
Constructor and Description
`Lister()` Creates a Lister with the default (System.out) destination for PVL statements.
`Lister(File file)` Creates a Lister using a File as the destination for PVL statements.
`Lister(OutputStream output_stream)` Creates a Lister using an OutputStream as the destination for PVL statements.
`Lister(Writer writer)` Creates a Lister using a Writer as the destination for PVL statements.

### Method Summary

Methods
`PVL_Exception` `First_Warning()` Returns the first warning since the last `Reset_Warning`.
`Lister` `First_Warning(boolean first)` Enables or disables returning the first warning that occurs as the current warning status.
`Writer` `Get_Writer()` Gets the current destination for Lister characters.
`boolean` `Indent_Arrays()` Tests if Array Values will be indented.
`Lister` `Indent_Arrays(boolean indent)` Enables or disables indenting of Array Value listings.
`int` `Indent_Level()` Gets the current base indent level.
`Lister` `Indent_Level(int level)` Sets the base indenting level when listing PVL statements.
`Lister` `Indent(boolean indent)` Enables or disables indenting of PVL statement listings.
`PVL_Exception` `Last_Warning()` Returns the last warning since a `Reset_Warning`.
`Lister` `Last_Warning(boolean last)` Enables or disables returning the last warning that occurs as the current warning status.
`Lister` `Reset_Warning()` Clears any warning status so that the `Warning` method will return null until the next warning condition occurs.
`Lister` `Set_Writer(File file)` Sets the Writer where the Lister will send characters by constructing a FileWriter from the specified File and wrapping this in a BufferedWriter for efficiency.
`Lister` `Set_Writer(OutputStream output_stream)` Sets the Writer where the Lister will send characters by constructing an OutputStreamWriter from the specified OutputStream and wrapping this in a BufferedWriter for efficiency.
`Lister` `Set_Writer(Writer writer)` Sets the Writer where the Lister will send characters.
`boolean` `Strict()` Tests if the Lister will enforce strict PVL syntax rules.
`Lister` `Strict(boolean strict)` Enables or disables strict PVL syntax rules in the Lister.
`static String_Buffer` `translate_to_escape_sequences(String_Buffer string)` Translates special characters in a String_Buffer to their corresponding escape sequences.
`boolean` `Verbatim_Strings()` Tests if verbatim strings mode is enabled.
`Lister` `Verbatim_Strings(boolean verbatim)` Enable or disable verbatim quoted strings.
`PVL_Exception` `Warning()` Gets the current warning status.
`int` `Write_Comments(String comments)` Writes a PVL comments sequence at the current indent level.
`int` `Write_Comments(String comments, int level)` Writes a PVL comments sequence.
`int` `Write(Parameter parameter)` Writes the Parameter in PVL syntax.
`int` `Write(Value value)` Writes the Value in PVL syntax.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### ID

    public static final String ID

Class name and version identification.

See Also:
  Constant Field Values

#### Strict_Default

    public static boolean Strict_Default

The default for enforcing `strict` PVL syntax rules.

#### Verbatim_Strings_Default

    public static boolean Verbatim_Strings_Default

`Verbatim strings` default.

#### Indent_Level_Default

    public static int Indent_Level_Default

The default `statement base indent level` (none if negative).

#### Indent_Arrays_Default

    public static boolean Indent_Arrays_Default

The default for applying `array indenting`.

#### INDENT

    public static String INDENT

The indent character(s).

This String is written once for each `indent level`. The default value is the tab character. A suitable alternative could be four space characters.

#### NEW_LINE

    public static String NEW_LINE

The platform's native line separator (newline) String.

This String is obtained from System.getProperty ("line.separator"), or "\n" is used if the System property can't be obtained.

#### First_Warning_Default

    public static boolean First_Warning_Default

The default for returning the `first warning` (or `last warning`).

### Constructor Detail

#### Lister

    public Lister(Writer writer)

Creates a Lister using a Writer as the destination for PVL statements.

Parameters:
  `writer` - The Writer destination for characters.
See Also:
  `Set_Writer(Writer)`

#### Lister

    public Lister(OutputStream output_stream)
           throws PVL_Exception

Creates a Lister using an OutputStream as the destination for PVL statements.

Parameters:
  `output_stream` - The OutputStream destination for characters.
Throws:
  `PVL_Exception` - From `Set_Writer`
See Also:
  `Set_Writer(OutputStream)`

#### Lister

    public Lister(File file)
           throws PVL_Exception

Creates a Lister using a File as the destination for PVL statements.

Parameters:
  `file` - The File destination for characters.
Throws:
  `PVL_Exception` - From `Set_Writer`
See Also:
  `Set_Writer(File)`

#### Lister

    public Lister()

Creates a Lister with the default (System.out) destination for PVL statements.

### Method Detail

#### Set_Writer

    public Lister Set_Writer(Writer writer)

Sets the Writer where the Lister will send characters.

N.B.: The US-ASCII character encoding is used.

Parameters:
  `writer` - The Writer destination for Lister output. If null, then a BufferedWriter constructed from an OutputStreamWriter using System.out is provided.
Returns:
  This Lister.
Throws:
  `IllegalStateException` - If the `Parser.CHARACTER_ENCODING` (US-ASCII) is not supported.

#### Get_Writer

    public Writer Get_Writer()

Gets the current destination for Lister characters.

Returns:
  The current Writer for the Lister.
See Also:
  `Set_Writer(Writer)`

#### Set_Writer

    public Lister Set_Writer(OutputStream output_stream)

Sets the Writer where the Lister will send characters by constructing an OutputStreamWriter from the specified OutputStream and wrapping this in a BufferedWriter for efficiency.

N.B.: The US-ASCII character encoding is used.

Parameters:
  `output_stream` - The OutputStream destination for Lister output. If null, System.out is used.
Returns:
  This Lister.
Throws:
  `IllegalStateException` - If the `Parser.CHARACTER_ENCODING` (US-ASCII) is not supported.

#### Set_Writer

    public Lister Set_Writer(File file)
                      throws PVL_Exception

Sets the Writer where the Lister will send characters by constructing a FileWriter from the specified File and wrapping this in a BufferedWriter for efficiency.

Parameters:
  `file` - The File destination for Lister output.
Returns:
  This Lister.
Throws:
  `PVL_Exception` - A FILE_IO error condition will occur if the File refers to a directory or a file for which write permission is not provided. Any other IOException that occurs while constructing the FileWriter will also be converted into a PVL_Exception.FILE_IO exception.

#### Strict

    public Lister Strict(boolean strict)

Enables or disables strict PVL syntax rules in the Lister.

The default is controlled by the `Strict_Default` value.

Parameters:
  `strict` - true if strict rules are applied; false otherwise.
Returns:
  This Lister.

#### Strict

    public boolean Strict()

Tests if the Lister will enforce strict PVL syntax rules.

Returns:
  true if the Lister will enforce strict syntax rules; false otherwise.

#### Verbatim_Strings

    public Lister Verbatim_Strings(boolean verbatim)

Enable or disable verbatim quoted strings.

Verbatim strings are listed exactly as they occur.

With verbatim strings disabled Parameter names, `STRING` Values, and units description strings will have special characters translated to escape sequences. However, in this case those sections of these strings that are bracketed by ``VERBATIM_STRING_DELIMITERS`` will not be translated, though the `VERBATIM_STRING_DELIMITERS` will be removed.

The default is controlled by the `Verbatim_Strings_Default` value.

Parameters:
  `verbatim` - true if strings are to be written verbatim; false if special character translation is to be applied.
Returns:
  This Lister.
See Also:
  `translate_to_escape_sequences(String_Buffer)`

#### Verbatim_Strings

    public boolean Verbatim_Strings()

Tests if verbatim strings mode is enabled.

Returns:
  true if verbatim strings mode is enabled; false otherwise.
See Also:
  `Verbatim_Strings(boolean)`

#### Indent_Level

    public Lister Indent_Level(int level)

Sets the base indenting level when listing PVL statements.

The default base level is 0. However, the default is controlled by the `Indent_Level_Default` value. Aggregate Parameter contents and subarrays of array Values are idented an additional level from their containing statement listing. If the base level is negative, indenting is disabled.

The default base level is 0. However, the default is controlled by the `Indent_Level_Default` value.

Parameters:
  `level` - The base indenting level.
Returns:
  This Lister.
See Also:
  `Indent(boolean)`, `Indent_Arrays(boolean)`

#### Indent_Level

    public int Indent_Level()

Gets the current base indent level.

Returns:
  The current base indent level.
See Also:
  `Indent_Level(int)`

#### Indent

    public Lister Indent(boolean indent)

Enables or disables indenting of PVL statement listings.

When enabling indenting, if indenting was previously disabled the default (0) base level is set. However, if indenting was previously enabled the current level remains unchanged.

Parameters:
  `indent` - true to enable indenting; false to disable it.
Returns:
  This Lister.
See Also:
  `Indent_Level(int)`

#### Indent_Arrays

    public Lister Indent_Arrays(boolean indent)

Enables or disables indenting of Array Value listings.

Normally indenting of Array Values is controlled by the indent level of PVL statement listings; with the listing of the Array, and each Array Value within the Array, starting on the next line at the next indent level. If indenting for PVL statements (i.e. Aggregate Parameters) is disabled, Arrays will be indented from level 0. However, Array indenting may be disabled even though PVL statement indenting remains enabled, in which case all Values of an Array will be written on one line.

The default is controlled by the `Indent_Arrays_Default` value.

Parameters:
  `indent` - true to enable Array indenting; false to disable it.
Returns:
  This Lister.
See Also:
  `Indent(boolean)`, `Indent_Level(int)`

#### Indent_Arrays

    public boolean Indent_Arrays()

Tests if Array Values will be indented.

Returns:
  true if Arrays Values will be indented; false otherwise.
See Also:
  `Indent_Arrays(boolean)`

#### Warning

    public PVL_Exception Warning()

Gets the current warning status.

When conditions are encountered that are unusual enough to warrant attention, but not an error condition that would prevent successful processing which would cause an exception to be thrown, a warning condition is registered. The warning is in the form of a PVL_Exception that was not thrown. The current warning status is either the ``First_Warning`` or the ``Last_Warning`` since a ``Reset_Warning``.

Returns:
  The current warning status as a PVL_Exception object, or null if no warning condition is registered.
See Also:
  `PVL_Exception`, `First_Warning(boolean)`, `Last_Warning(boolean)`, `Reset_Warning()`

#### Reset_Warning

    public Lister Reset_Warning()

Clears any warning status so that the `Warning` method will return null until the next warning condition occurs.

Returns:
  This Lister.
See Also:
  `Warning()`

#### First_Warning

    public Lister First_Warning(boolean first)

Enables or disables returning the first warning that occurs as the current warning status.

The first warning is one that occurs when the current warning status is null. If the use of the first warning is disabled the last warning that occurred will be returned instead. The default is to use the first warning. However, the default is controlled by the `First_Warning_Default` value.

N.B.: Enabling the return of the first warning is the same as disabling the `return of the last warning`.

Parameters:
  `first` - true to enable returning the first warning status; false to return the last warning that occurred as the current warning status.
Returns:
  This Lister.
See Also:
  `Last_Warning(boolean)`, `Warning()`, `First_Warning()`, `Reset_Warning()`

#### First_Warning

    public PVL_Exception First_Warning()

Returns the first warning since the last `Reset_Warning`.

Returns:
  The first warning status as a PVL_Exception object, or null if no warning condition is registered.
See Also:
  `PVL_Exception`, `Warning()`, `First_Warning(boolean)`, `Reset_Warning()`

#### Last_Warning

    public Lister Last_Warning(boolean last)

Enables or disables returning the last warning that occurs as the current warning status.

The last warning is the most recent one that ocurred, regardless of any previous warning conditions that may have occured, without an intervening `Reset_Warning`.

N.B.: Enabling the return of the last warning is the same as disabling the `return of the first warning`.

Parameters:
  `last` - true to enable returning the last warning status; false to return the first warning condition that occurred as the current warning status.
Returns:
  This Lister.
See Also:
  `First_Warning(boolean)`, `Warning()`, `Last_Warning()`, `Reset_Warning()`

#### Last_Warning

    public PVL_Exception Last_Warning()

Returns the last warning since a `Reset_Warning`.

Returns:
  The last warning status as a PVL_Exception object, or null if no warning condition is registered.
See Also:
  `PVL_Exception`, `Warning()`, `Last_Warning(boolean)`, `Reset_Warning()`

#### Write

    public int Write(Parameter parameter)
              throws PVL_Exception,
                     IOException

Writes the Parameter in PVL syntax.

The PVL syntax that is written follows this pattern:

> Comments
> Name = Value

The comments string, if there is one, is written by the `Write_Comments` method.

The Parameter's name is written next beginning on a new line. If indenting is enabled, the name will be preceeded by the current indent count number of horizontal tab characters. The name String itself is usually provided by the Parameter's `Name` method. However, if the Parser's `Special_Name` method determines that the Parameter's classification is associated with a special name (as it is for all aggregate and `END` Parameters), then that will be written instead. Unless ``Verbatim_Strings`` are enabled, escape sequences are substituted for special (format control) characters and ``Parser.TEXT_DELIMITER``, ``Parser.SYMBOL_DELIMITER`` and backslash ('\') characters are escaped (with a preceding backslash character). If the name contains `whitespace` or `reserved` characters or is empty then it will be quoted (with ``Parser.TEXT_DELIMITER`` characters). Note: When `Strict` PVL has been specified, Parameter's that begin an aggregate list will have the special name `BEGIN_GROUP` or `BEGIN_OBJECT`, otherwise the `BEGIN_` portion will not be included.

The Parameter's value is written next, if the Parameter is not a token or classified as `UNKNOWN`. It is preceeded by the `equals` character surrounded by space characters. For an assignment, the `Write Value)` method completes the output of a parameter, including any line termination, and the method returns. If there is no Value, an empty quoted String is written by default. For aggregates, the name of the Parameter is its value; i.e. in this case the special name for the specific classification substitutes for the usual name, and the usual name appears as the value (yes, this seems strange, but take it up with the committee that wrote the specification for the PVL syntax).

The Parameter line is completed by writing a new-line character. However, if `Strict` PVL has been specified, then the ``Parser.STATEMENT_END_DELIMITER`` character followed by the ``Parser.LINE_BREAK`` sequence is written instead.

When the Parameter being written is an aggregate, the indent level (if indenting is enabled) is incremented and then each Parameter in the aggregate list is recursively written. At the end of the list the indent level is decremented (if indenting is enabled) and an `END_GROUP` or `END_OBJECT` Parameter, corresponding to the classification of the aggregate containing the list, is written. If an `END` Parameter is encountered in the aggregate list, then the list is terminated at that point. If an `END_PVL` Parameter is encountered, then the current list is terminated as well as the lists of all containing aggregates; i.e. all Parameter lists end at that point.

As a special case, when the Parameter being written is an aggregate with the name ``Parser.CONTAINER_NAME`` this "container" Parameter is not written, but the Parameters in it's aggregate list are written normally. This special case only applies to the first Parameter inspected by the `Write (Parameter)` method, not aggregate list entries; i.e. only the top of the hierarchy is considered as a potential special case.

Normally the special `END_PVL` Parameter is not written at the end of the listing. This is so that several Parameters can be written to a file before the application provides the `END_PVL` Parameter formally expected at the end of a PVL sequence. However, when the Parameter being written is the top of the output hierarchy and has the special `Parser.CONTAINER_NAME`, then the `END_PVL` Parameter is automatically provided to reflect the end of the container's parameters; i.e. what is written should be logically the equivalent to what was read by the Parser.

Parameters:
  `parameter` - The Parameter to write.
Returns:
  The total number of bytes written.
Throws:
  `PVL_Exception` -
  `BAD_ARGUMENT`
    If an element in an aggregate list is not a Parameter.
  `IOException` - From the Writer's `write` method.
See Also:
  `Write_Comments(String, int)`, `Parameter.Name()`, `Parser.Special_Name(int)`, `translate_to_escape_sequences(String_Buffer)`, `Write(Value)`

#### Write_Comments

    public int Write_Comments(String comments,
                     int level)
                       throws IOException

Writes a PVL comments sequence.

Normally comments are attached to a Parameter with the `Comments` method and they are written as part of the Parameter. Comments may be inserted virtually anywhere in a PVL listing, and this method is provided for such ad hoc commenting.

Comments are delimited by `Parser.COMMENT_START_DELIMITERS` and `Parser.COMMENT_END_DELIMITERS` (C-style) sequences. When `Strict` PVL syntax is specified each line of the comments String (a line being delmited by a new-line character) is separated into individual single line comments. Otherwise the comments String is simply output between the start and end sequences as-is.

If indenting is enabled each comment start sequence will be preceeded by the current indent count number of horizontal tab characters. Unless `Strict` syntax has been specified, the comment end sequence is preceeded by a new-line character and any indenting. If indenting is enabled the end of the comments sequence is completed by writing a new-line character, or the ``Parser.LINE_BREAK`` sequence for `Strict` PVL.

Parameters:
  `comments` - The String to be written in a comments sequence. If comments is null, nothing is written.
  `level` - The indent level to use.
Returns:
  The total number of bytes written.
Throws:
  `IOException` - From the OutputStream `write` method.

#### Write_Comments

    public int Write_Comments(String comments)
                       throws IOException

Writes a PVL comments sequence at the current indent level.

Parameters:
  `comments` - The String to be written in a comments sequence. If comments is null, nothing is written.
Returns:
  The total number of bytes written.
Throws:
  `IOException` - From the Writer's `write` method.
See Also:
  `Write_Comments(String, int)`

#### Write

    public int Write(Value value)
              throws PVL_Exception,
                     IOException

Writes the Value in PVL syntax.

The PVL syntax that is written follows this pattern:

> [ ( | { ] Datum [ < Units > ] [ , Datum [...] ] [ ) | } [ < Units > ] ]

The Value datum is always written. If the Value is the `UNKNOWN` type then an empty `SYMBOL` type is provided by default. If the datum is a `STRING` type and ``Verbatim_Strings`` are disabled, escape sequences are substituted for special (format control) characters and ``Parser.TEXT_DELIMITER``, ``Parser.SYMBOL_DELIMITER`` and backslash ('\') characters are escaped (with a preceding backslash character). If the string contains `whitespace` or `reserved` characters or is empty then it will be quoted (with ``Parser.TEXT_DELIMITER`` characters).

If the Value is an `ARRAY` type then the appropriate enclosure start character (``Parser.SET_START_DELIMITER`` or ``Parser.SEQUENCE_START_DELIMITER``) is written before each Value in the array Vector is recursively written by this method with a space and ``Parser.PARAMETER_VALUE_DELIMITER`` separation. After all the array Vector Values have been written the appropriate enclosure end character (``Parser.SET_END_DELIMITER`` or ``Parser.SEQUENCE_END_DELIMITER``) is written.

After each Value is written, whether a single datum or an array, it is followed by any units description String (preceeded by a space character and enclosed in PVL syntax characters (``Parser.UNITS_START_DELIMITER`` and ``Parser.UNITS_END_DELIMITER``).

Array indenting may be enabled. In this mode each nested array is written on separate lines indented by tab characters to its nesting level. Each subarray starts a new line and increments the nesting level. The end of a subarray is followed by a new-line and the nesting level is decremented before continuing a previous array level (but not if there is no previous array level or the previous level has no more Values). The start of an array at level 0 is not given indent treatment.

In `Strict` mode new-line sequences are the ``Parser.LINE_BREAK`` characters; normally the native new-line (the line.separator System property) is used. Also, `Strict` mode results in the ``Parser.STATEMENT_END_DELIMITER`` character preceeding the usual new-line that completes the Value output.

If an unenclosed `STRING` type datum contains any of the ``Parser.RESERVED_CHARACTERS`` then a warning status is set (and thrown in `Strict` mode). These characters have special meaning in the PVL syntax so writing values containing them could confuse a PVL parser that reads them. Unless strict mode is in effect, the string is enclosed in ``Parser.TEXT_DELIMITER`` characters to protect them from inappropriate interpretation.

Parameters:
  `value` - The Value to write.
Returns:
  The total number of bytes written.
Throws:
  `PVL_Exception` -
  `BAD_ARGUMENT`
    If an element in an array is not a Value.
  `ILLEGAL_SYNTAX`
    If a PVL reserved character was found in an unenclosed `STRING` datum during `Strict` writing.
  `IOException` - From the OutputStream `write` method.
See Also:
  `translate_to_escape_sequences(String_Buffer)`

#### translate_to_escape_sequences

    public static String_Buffer translate_to_escape_sequences(String_Buffer string)

Translates special characters in a String_Buffer to their corresponding escape sequences.

In addition to the special characters translated by the ``special_to_escape`` method, the ``TEXT_DELIMITER`` and ``SYMBOL_DELIMITER`` characters are also escaped. The occurance of ``VERBATIM_STRING_DELIMITERS`` starts a sequence of characters that are taken verbatim (they are not translated) up to and including the next `VERBATIM_STRING_DELIMITERS` or the end of the string.

Parameters:
  `string` - The String_Buffer to be translated.
Returns:
  The translated String_Buffer.
See Also:
  `String_Buffer.special_to_escape()`