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.

Version:

1.20

Author:

Bradford Castalia, UA/PIRL

See Also:

Parser, Parameter, Value

Field Summary

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

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

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