PIRL.PVL
Class Parser

java.lang.Object
  PIRL.Strings.String_Buffer
      PIRL.Strings.String_Buffer_Reader
          PIRL.PVL.Parser

public class Parser
extends String_Buffer_Reader

The Parser extends the String_Buffer_Reader to interpret the characters as a sequence of Parameter Value Language (PVL) syntax statements.

This Parser implements the syntax of the PVL used by the Planetary Data System (PDS) as specified by the Consultative Committee for Space Data Systems in the Blue Book "Parameter Value Language Specification (CCSDS0006,8)", June 2000 [CCSDS 641.0-B-2] and Green Book "Parameter Value Language - A Tutorial", May 1992 [CCSDS 641.0-G-1] documents. PVL has been accepted by the International Standards Organization (ISO), as a Draft Standard (ISO/CD 14961:1997). The PVL syntax defines a Parameter with this basic format:

[Comments]
Name [= Value][;]

The optional Comments are enclosed in C-style delimiters, or optionally preceeded by a crosshatch ('#') character on each line. The PVL syntax for a Value follows this format:

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

The purpose of a Parser object is to assemble Parameter and Value objects using the PVL statements obtained from the associated String_Buffer_Reader.

The class methods that perform the parsing of the character source are organized into a hierarchy:

• Get
• Add_To
  • Get_Parameter
    • Get_Comments
    • Get_Value
      • Get_Datum
        • Get_Quoted_String
      • Get_Units

Higher level methods utilize lower level methods to assemble their constituent parts. At the top level an aggregate of all Parameters that can be interpreted from the input will be collected by getting as many Parameters as possible; a Parameter is produced from the input stream by getting any comments, a name String, and a Value; a Value includes as many datum and optional units descriptions that can be sequentially found in the input stream; and a datum is composed from primitive syntactic elements, including integer or real number representations or character strings which may be quoted (a Parameter name may also be a quoted string). Typically applications will only use the top method(s). Applications needing finer grained control over input stream parsing may, of course, use the lower level methods directly, however it is much easier to just get all of the Parameters from an input source and then manipulate the Parameter-Value object hierarchy.

Each method that parses the input stream interprets the contents of the logical String_Buffer_Reader which presents the entire virtual contents of the stream from the current location onwards. Except for the top level which does not interpret the character source directly, these methods first seek forward from the current location to the beginning of a potentially relevant syntactic character sequence. If the sequence is recognized as suitable for the item the method is responsible for interpreting then the appropriate end of the sequence is found and the characters it contains are translated into the corresponding internal form of object class variable. If the translation is successful then the logical Next_Location of the String_Buffer_Reader is moved forward to the end of the sequence before the iterative interpretation of the stream continues. If, however, the beginning of a recognizable syntactic sequence is not found, or the translation of a sequence fails, then the method returns empty handed, and without having advanced the logical String_Buffer_Reader, to the invoking method which may invoke a different method in an attempt to get a different item or itself discontinue its efforts to assemble an item. Thus each parsing method either gets its item and advances the current location in the character stream, or does not get its item nor advance the stream; i.e. the PVL statements encountered in the character source are sequentially translated at the same time that the input stream is incrementally moved forward.

Version:

1.35

Author:

Bradford Castalia, UA/PIRL

See Also:

String_Buffer_Reader, Parameter, Value

Field Summary

static boolean	All_Values_Strings_Default The default for treating all values as strings.
static String	CHARACTER_ENCODING The PVL character encoding: "US-ASCII".
static String	COMMENT_END_DELIMITERS Marks the end of a comment string: '*' and '/'.
static String	COMMENT_START_DELIMITERS Marks the start of a comment string: '/' and '*'.
static String	CONTAINER_NAME The default name of the aggregate Parameter to contain all Parameters when a Parser Get finds more than one Parameter: "The Container".
static char	CROSSHATCH Begins a "crosshatch comment" that extends to the end of the line: '#'.
static boolean	Crosshatch_Comments_Default The default for allowing crosshatched-to-EOL comments.
static String	DATE_TIME_DELIMITERS Set of characters that suggests a DATE_TIME type of STRING Value: "-:".
static String	ID Class name and version identification.
static String	LINE_BREAK Character sequence that separates PVL statement lines: "\r\n" (CR-NL).
static char	NUMBER_BASE_DELIMITER Encloses the datum of a Value in radix base notation: '#'.
static char	PARAMETER_NAME_DELIMITER Delimits a Parameter name from its Value: '='.
static char	PARAMETER_VALUE_DELIMITER Delimits elements of an ARRAY Value: ','.
static String	RESERVED_CHARACTERS Characters reserved by the PVL syntax.
static char	SEQUENCE_END_DELIMITER Marks the end of a SEQUENCE ARRAY Value: ')'
static char	SEQUENCE_START_DELIMITER Marks the start of a SEQUENCE ARRAY Value: '('.
static char	SET_END_DELIMITER Marks the end of a SET ARRAY Value: '}'.
static char	SET_START_DELIMITER Marks the start of a SET ARRAY Value: '{'.
static char	STATEMENT_CONTINUATION_DELIMITER Indicates that the statement continues in the next record: '&'.
static char	STATEMENT_END_DELIMITER Marks the end of a PVL statement: ';'.
static boolean	Strict_Default The default for enforcing strict PVL syntax rules.
static boolean	String_Continuation_Default String continuation default.
static char	STRING_CONTINUATION_DELIMITER Indicates that the quoted string continues unbroken in the next record: '-'.
static char	SYMBOL_DELIMITER Encloses a SYMBOL STRING Value: '\''.
static char	TEXT_DELIMITER Encloses a TEXT STRING Value: '"'.
static char	UNITS_END_DELIMITER Marks the end of a Value units description: '>'.
static char	UNITS_START_DELIMITER Marks the start of a Value units description: '<'.
static String	VERBATIM_STRING_DELIMITERS Encloses a verbatim (uninterpreted) string: "\\v".
static boolean	Verbatim_Strings_Default Verbatim strings default.
static String	WHITESPACE Set of "whitespace" characters between PVL tokens: " \t\r\n\f\013" (SP, HT, CR, NL, FF, and VT).

Fields inherited from class PIRL.Strings.String_Buffer_Reader

DEFAULT_READ_LIMIT, DEFAULT_SIZE_INCREMENT, INVALID_CHARACTER, NO_READ_LIMIT

Fields inherited from class PIRL.Strings.String_Buffer

QUESTIONABLE_CHARACTER

Constructor Summary

Parser()
Creates a Parser with no source of PVL statements.

Parser(char[] char_array)
Creates a Parser using a character array as the source of PVL statements.

Parser(char[] char_array, int offset, int length)
Creates a Parser using a characer array subset as the source of PVL statements.

Parser(File file)
Creates a Parser using a File to create a new Reader as the source of PVL statements, with no limit on the amount to read.

Parser(File file, long read_limit)
Creates a Parser using a File to create a new Reader as the source of PVL statements, and sets a limit on the amount to read.

Parser(InputStream input_stream)
Creates a Parser using an InputStream to create a new Reader as the source of PVL statements, with no limit on the amount to read.

Parser(InputStream input_stream, long read_limit)
Creates a Parser using an InputStream to create a new Reader as the source of PVL statements, and sets a limit on the amount to read.

Parser(Reader reader)
Creates a Parser using a Reader as the source of PVL statements, with no limit on the amount to read.

Parser(Reader reader, long read_limit)
Creates a Parser using a Reader as the source of PVL statements, and sets a limit on the amount to read.

Parser(String string)
Creates a Parser using a String as the source of PVL statements.

Method Summary

Parameter	Add_To(Parameter The_Aggregate) Adds to a Parameter all Parameters found from the input source.
boolean	All_Values_Strings() Tests if the Parser will treat all values as strings.
Parser	All_Values_Strings(boolean all_values_strings) Enable or disable treating all values as strings.
static int	Bad_Character(String string) Checks a String for any bad character.
boolean	Crosshatch_Comments() Tests if crosshatch comments will be recognized.
Parser	Crosshatch_Comments(boolean crosshatch_comments) Enable or disable recognition of crosshatch comments.
PVL_Exception	First_Warning() Returns the first warning since the last Reset_Warning.
Parser	First_Warning(boolean first) Enables or disables returning the first warning that occurs as the current warning status.
String	Get_Comments() Gets the next sequence of comments from the source of PVL statements as a single comment String.
Value	Get_Datum(Value The_Value) Gets a datum from the source of PVL statements.
Parameter	Get_Parameter() Gets a Parameter from the source of PVL statements.
String	Get_Quoted_String() Gets a quoted String from the source of PVL statements.
String	Get_Units() Gets a units description String from the source of PVL statements.
Value	Get_Value() Gets a Value from the source of PVL statements.
Parameter	Get() Gets as many Parameters as possible.
static boolean	isprint(char character) Tests if a character is printable: in the ASCII range from the space character (' ') to the tilde character ('~') inclusive.
PVL_Exception	Last_Warning() Returns the last warning since a Reset_Warning.
Parser	Last_Warning(boolean last) Enables or disables returning the last warning that occurs as the current warning status.
Parser	Reset_Warning() Clears any warning status so that the Warning method will return null until the next warning condition occurs.
Parser	Set_Reader(File file, long read_limit) Sets the Reader where the Parser will obtain characters by constructing a FileInputStream from the specified File and passing this to the Set_Reader (InputStream, long) method.
Parser	Set_Reader(InputStream input_stream, long read_limit) Sets the Reader where the Parser will obtain characters by constructing an InputStreamReader from the specified InputStream and wrapping this in a BufferedReader, the same size as the Size_Increment of the String_Buffer_Reader, for efficiency.
Parser	Set_Reader(Reader reader, long read_limit) Sets the Reader where the Parser will obtain characters.
long	skip_whitespace_and_comments(long location) Gets the next location in the PVL source stream following any sequence of whitespace and/or comments.
static int	Special_Classification(String name) Gets the Parameter classification code corresponding to the specified special Parameter name String.
static String	Special_Name(int classification) Gets the special Parameter name String for the specified Parameter classification code.
boolean	Strict() Tests if the Parser will enforce strict PVL syntax rules.
Parser	Strict(boolean strict) Enables or disables strict PVL syntax rules in the Parser.
boolean	String_Continuation() Tests if the Parser will recognize multi-line string continuation.
Parser	String_Continuation(boolean continuation) Enable or disable string continuation.
static String_Buffer	translate_from_escape_sequences(String_Buffer string) Translates escape sequences in a String_Buffer to their corresponding special characters.
boolean	Verbatim_Strings() Tests if the Parser will handle quoted strings verbatim.
Parser	Verbatim_Strings(boolean verbatim) Enable or disable verbatim quoted strings.
PVL_Exception	Warning() Gets the current warning status.

Methods inherited from class PIRL.Strings.String_Buffer_Reader

Buffer_Location, Char_At, End_Index, End_Location, Ended, Equals, Extend, Filter_Input, Filter_Input, Filter_Input, Get_Reader, Index, Is_Empty, Is_End, Is_Text, Location_Of, Location_Of, Location, Next_Index, Next_Index, Next_Location, Next_Location, No_Read_Limit, Non_Text_Limit, Non_Text_Limit, Read_Limit, Read_Limit, Reader_Source, Record_Size, Record_Size, Reset_Location, Reset, Set_Reader, Size_Increment, Size_Increment, Skip_Over, Skip_Until, String_Source, Substring, Total_Read

Methods inherited from class PIRL.Strings.String_Buffer

append, append, append, append, append, append, append, append, append, append, append, append, append, capacity, charAt, clean, clear, delete, deleteCharAt, ensureCapacity, equals_ignore_case, equals, equalsIgnoreCase, escape_to_special, escape_to_special, from_character_references, from_character_references, getChars, index_of, index_of, indexOf, indexOf, insert, insert, insert, insert, insert, insert, insert, insert, insert, insert, length, replace_span, replace, replace, replaceSpan, reverse, setCharAt, setLength, skip_back_over, skip_back_until, skip_over, skip_until, skipBackOver, skipBackUntil, skipOver, skipUntil, special_to_escape, special_to_escape, substring, substring, to_character_references, to_character_references, to_printable_ASCII, to_printable_ASCII, toString, trim_all, trim_beginning, trim_end, trim, trim, trim

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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.

String_Continuation_Default

public static boolean String_Continuation_Default

String continuation default.

Crosshatch_Comments_Default

public static boolean Crosshatch_Comments_Default

The default for allowing crosshatched-to-EOL comments.

All_Values_Strings_Default

public static boolean All_Values_Strings_Default

The default for treating all values as strings.

CROSSHATCH

public static final char CROSSHATCH

Begins a "crosshatch comment" that extends to the end of the line: '#'.

See Also:

Constant Field Values

CHARACTER_ENCODING

public static final String CHARACTER_ENCODING

The PVL character encoding: "US-ASCII".

See Also:

Constant Field Values

RESERVED_CHARACTERS

public static final String RESERVED_CHARACTERS

Characters reserved by the PVL syntax.

{}()[]<>&\"',=;#%~|+! \t\r\n\f\013

Some of these characters have special meanings in specific contexts as delimiters of PVL items.

See Also:

Constant Field Values

PARAMETER_NAME_DELIMITER

public static final char PARAMETER_NAME_DELIMITER

Delimits a Parameter name from its Value: '='.

See Also:

Constant Field Values

PARAMETER_VALUE_DELIMITER

public static final char PARAMETER_VALUE_DELIMITER

Delimits elements of an ARRAY Value: ','.

See Also:

Constant Field Values

TEXT_DELIMITER

public static final char TEXT_DELIMITER

Encloses a TEXT STRING Value: '"'.

See Also:

Constant Field Values

SYMBOL_DELIMITER

public static final char SYMBOL_DELIMITER

Encloses a SYMBOL STRING Value: '\''.

See Also:

Constant Field Values

SET_START_DELIMITER

public static final char SET_START_DELIMITER

Marks the start of a SET ARRAY Value: '{'.

See Also:

Constant Field Values

SET_END_DELIMITER

public static final char SET_END_DELIMITER

Marks the end of a SET ARRAY Value: '}'.

See Also:

Constant Field Values

SEQUENCE_START_DELIMITER

public static final char SEQUENCE_START_DELIMITER

Marks the start of a SEQUENCE ARRAY Value: '('.

See Also:

Constant Field Values

SEQUENCE_END_DELIMITER

public static final char SEQUENCE_END_DELIMITER

Marks the end of a SEQUENCE ARRAY Value: ')'

See Also:

Constant Field Values

UNITS_START_DELIMITER

public static final char UNITS_START_DELIMITER

Marks the start of a Value units description: '<'.

See Also:

Constant Field Values

UNITS_END_DELIMITER

public static final char UNITS_END_DELIMITER

Marks the end of a Value units description: '>'.

See Also:

Constant Field Values

NUMBER_BASE_DELIMITER

public static final char NUMBER_BASE_DELIMITER

Encloses the datum of a Value in radix base notation: '#'.

See Also:

Constant Field Values

STATEMENT_END_DELIMITER

public static final char STATEMENT_END_DELIMITER

Marks the end of a PVL statement: ';'.

See Also:

Constant Field Values

STATEMENT_CONTINUATION_DELIMITER

public static final char STATEMENT_CONTINUATION_DELIMITER

Indicates that the statement continues in the next record: '&'.

See Also:

Constant Field Values

STRING_CONTINUATION_DELIMITER

public static final char STRING_CONTINUATION_DELIMITER

Indicates that the quoted string continues unbroken in the next record: '-'.

See Also:

Constant Field Values

LINE_BREAK

public static final String LINE_BREAK

Character sequence that separates PVL statement lines: "\r\n" (CR-NL).

See Also:

Constant Field Values

WHITESPACE

public static final String WHITESPACE

Set of "whitespace" characters between PVL tokens: " \t\r\n\f\013" (SP, HT, CR, NL, FF, and VT).

See Also:

Constant Field Values

COMMENT_START_DELIMITERS

public static final String COMMENT_START_DELIMITERS

Marks the start of a comment string: '/' and '*'.

See Also:

Constant Field Values

COMMENT_END_DELIMITERS

public static final String COMMENT_END_DELIMITERS

Marks the end of a comment string: '*' and '/'.

See Also:

Constant Field Values

DATE_TIME_DELIMITERS

public static final String DATE_TIME_DELIMITERS

Set of characters that suggests a DATE_TIME type of STRING Value: "-:".

See Also:

Constant Field Values

VERBATIM_STRING_DELIMITERS

public static final String VERBATIM_STRING_DELIMITERS

Encloses a verbatim (uninterpreted) string: "\\v".

See Also:

Constant Field Values

CONTAINER_NAME

public static final String CONTAINER_NAME

The default name of the aggregate Parameter to contain all Parameters when a Parser Get finds more than one Parameter: "The Container".

See Also:

Constant Field Values

Constructor Detail

Parser

public Parser(Reader reader,
              long read_limit)
       throws PVL_Exception

Creates a Parser using a Reader as the source of PVL statements, and sets a limit on the amount to read.

Parameters:

reader - The Reader to use as the source of characters.

read_limit - The maximum amount to read.

Throws:

PVL_Exception - From Set_Reader.

See Also:

Set_Reader(Reader, long)

Parser

public Parser(Reader reader)
       throws PVL_Exception

Creates a Parser using a Reader as the source of PVL statements, with no limit on the amount to read.

Parameters:

reader - The Reader to use as the source of characters.

Throws:

PVL_Exception - From Set_Reader.

See Also:

Set_Reader(Reader, long)

Parser

public Parser(File file,
              long read_limit)
       throws PVL_Exception

Creates a Parser using a File to create a new Reader as the source of PVL statements, and sets a limit on the amount to read.

Parameters:

file - The File to be the basis for a new Reader.

read_limit - The maximum amount to read.

Throws:

PVL_Exception - From Set_Reader.

See Also:

Set_Reader(File, long)

Parser

public Parser(File file)
       throws PVL_Exception

Creates a Parser using a File to create a new Reader as the source of PVL statements, with no limit on the amount to read.

Parameters:

file - The File to be the basis for a new Reader.

Throws:

PVL_Exception - From Set_Reader.

See Also:

Set_Reader(File, long)

Parser

public Parser(InputStream input_stream,
              long read_limit)
       throws PVL_Exception

Creates a Parser using an InputStream to create a new Reader as the source of PVL statements, and sets a limit on the amount to read.

Parameters:

input_stream - The InputStream to be the basis for a new Reader.

read_limit - The maximum amount to read.

Throws:

PVL_Exception - From Set_Reader.

See Also:

Set_Reader(InputStream, long)

Parser

public Parser(InputStream input_stream)
       throws PVL_Exception

Creates a Parser using an InputStream to create a new Reader as the source of PVL statements, with no limit on the amount to read.

Parameters:

input_stream - The InputStream to be the basis for a new Reader.

Throws:

PVL_Exception - From Set_Reader.

See Also:

Set_Reader(InputStream, long)

Parser

public Parser()

Creates a Parser with no source of PVL statements.

Parser

public Parser(String string)

Creates a Parser using a String as the source of PVL statements.

Parameters:

string - The String to use as the source of characters.

Parser

public Parser(char[] char_array)

Creates a Parser using a character array as the source of PVL statements.

Parameters:

char_array - The source of characters.

Parser

public Parser(char[] char_array,
              int offset,
              int length)

Creates a Parser using a characer array subset as the source of PVL statements.

Parameters:

char_array - The source of characters.

offset - The array index where the character source starts.

length - The number of characters to source.

Method Detail

Set_Reader

public Parser Set_Reader(Reader reader,
                         long read_limit)
                  throws PVL_Exception

Sets the Reader where the Parser will obtain characters.

If Filter_Input is true, then a SIZED_RECORDS Warning is registered.

N.B.: When Filter_Input is used it will read the first two characters from the reader to test them for non-printable values, unless the test has already been done on the reader or input filtering has been disabled. If no characters are yet available from the reader - e.g. if the reader is backed by a pipe or network socket - then the read will block until two characters become available (or an IOException occurs). The base String_Buffer_Reader does its own Filter_Input test every time its internal buffer content is extended. Therefore, to prevent the Filter_Input() test from blocking when the reader is set defer setting the reader until blocking is acceptable, it is known that the required input will be available or filtering has been disabled. For example:

Parser parser = new Parser ();
// The reader is certain not to need filtering.
parser.Filter_Input (false);
// Any of the Set_Reader methods may be used.
parser.Set_Reader (reader, read_limit);

Parameters:

reader - The Reader source for Parser input. If null, then there is no PVL source and thus nothing to be parsed.

Returns:

This Parser.

Throws:

PVL_Exception - From Set_Reader. A FILE_IO form is thrown if there is an IOException from Filter_Input.

See Also:

String_Buffer_Reader.Set_Reader(Reader), String_Buffer_Reader.Filter_Input(), String_Buffer_Reader.Read_Limit(long)

Set_Reader

public Parser Set_Reader(InputStream input_stream,
                         long read_limit)
                  throws PVL_Exception

Sets the Reader where the Parser will obtain characters by constructing an InputStreamReader from the specified InputStream and wrapping this in a BufferedReader, the same size as the Size_Increment of the String_Buffer_Reader, for efficiency. The Parser's CHARACTER_ENCODING is used.

Parameters:

input_stream - The InputStream source for Parser input. If null then there is nothing to read.

Returns:

This Parser.

Throws:

PVL_Exception - From Set_Reader. A FILE_IO form is thrown if there is an UnsupportedEncodingException when constructing the InputStreamReader.

See Also:

String_Buffer_Reader.Size_Increment(int)

Set_Reader

public Parser Set_Reader(File file,
                         long read_limit)
                  throws PVL_Exception

Sets the Reader where the Parser will obtain characters by constructing a FileInputStream from the specified File and passing this to the Set_Reader (InputStream, long) method.

Parameters:

file - The File source for Parser input. If null, there is nothing to read.

Returns:

This Parser.

Throws:

PVL_Exception - A FILE_IO error condition will occur if the File refers to a directory or a file for which read permission is not provided. Any other IOException that occurs while constructing the FileInputStream will also be converted into a PVL_Exception.FILE_IO exception.

See Also:

Set_Reader(InputStream, long)

Strict

public Parser Strict(boolean strict)

Enables or disables strict PVL syntax rules in the Parser.

Normally the Parser is tolerant. However, the default is controlled by the Strict_Default value.

N.B.: Enabling strict syntax rules will prevent treating all Values as Strings.

Parameters:

strict - true if strict rules are applied; false otherwise.

Returns:

This Parser.

Strict

public boolean Strict()

Tests if the Parser will enforce strict PVL syntax rules.

Returns:

true if the Parser will enforce strict syntax rules; false otherwise.

Verbatim_Strings

public Parser Verbatim_Strings(boolean verbatim)

Enable or disable verbatim quoted strings.

With format control (Verbatim_Strings disabled) multi-line quoted strings in PVL statements have white space surrounding the line breaks compressed to a single space character - except when String_Continuation is enabled and the last non-white space character on the line is a dash ("-"), in which case no space is included. This is because output formatting is expected to be controlled by embedded format characters which are processed by the Write method:

\n - line break.
\t - horizontal tab.
\f - form feed (page break).
\ \ - backslash character.
\v - verbatim (no formatting) till the next \v.

Without format control (Verbatim_Strings enabled) all STRING Values are taken as-is.

By default verbatim strings are disabled. However, the default is controlled by the Verbatim_Strings_Default value.

Parameters:

verbatim - true if quoted strings in PVL statements are to be taken verbatim, without format control.

Returns:

This Parser.

See Also:

Get_Parameter(), Get_Quoted_String(), String_Continuation(boolean), Get_Comments(), Get_Datum(Value), Get_Units()

Verbatim_Strings

public boolean Verbatim_Strings()

Tests if the Parser will handle quoted strings verbatim.

Returns:

true if quoted strings are taken verbatim; false otherwise.

See Also:

Verbatim_Strings(boolean)

String_Continuation

public Parser String_Continuation(boolean continuation)

Enable or disable string continuation.

When string continuation is enabled (the default) and verbatim strings is disabled (the default) the occurrance in a quoted string of a STRING_CONTINUATION_DELIMITER as the last character before the new line sequence causes the string continuation delimiter and all characters up to the next non-whitespace character to be removed from the string; i.e. the string continues on the next line after any whitespace.

By default string continuation is enabled. However, the default is controlled by the String_Continuation_Default value.

Parameters:

continuation - true if string continuation is to be enabled; false otherwise.

Returns:

This Parser.

See Also:

Get_Quoted_String(), Verbatim_Strings(boolean)

String_Continuation

public boolean String_Continuation()

Tests if the Parser will recognize multi-line string continuation.

Returns:

true if quoted string conintuation will be recognized; false otherwise.

See Also:

String_Continuation(boolean)

Crosshatch_Comments

public Parser Crosshatch_Comments(boolean crosshatch_comments)

Enable or disable recognition of crosshatch comments. A Crosshatch comment begins with the CROSSHATCH character and extends to the end of the current line (marked by a LINE_BREAK character). Crosshatch comments are never recognized in Strict mode.

Note: Crosshatch comments are not recognized in the PVL syntax specification. Because of their common use in configuration files, this special extension is provided to accommodate such applications. Be default crosshatch comments are not recognized.

By default crosshatch comments are enabled. However, the default is controlled by the Crosshatch_Comments_Default value.

Parameters:

crosshatch_comments - true if crosshatch comments are to be recognized; false otherwise.

Returns:

This Parser.

Crosshatch_Comments

public boolean Crosshatch_Comments()

Tests if crosshatch comments will be recognized.

Regardless of this test, crosshatch comments are never recognized in Strict mode.

Returns:

true if crosshatch comments will be recognized; false otherwise.

See Also:

Crosshatch_Comments(boolean)

All_Values_Strings

public Parser All_Values_Strings(boolean all_values_strings)

Enable or disable treating all values as strings.

When enabled, and strict syntax rules are not enabled, all PVL parameter values will be parsed as Strings; no other Value Type will be generated. This may be useful in cases where, for example, a numeric Type Value would be generated from a PVL value representation that can not be converted to a binary value with sufficient precision, or where unquoted PVL value representations that would otherwise be expected to be identifiers happen to contain all numeric digit characters.

By default treating all values as strings is disabled. However the default is controlled by the All_Values_Strings_Default value.

Parameters:

all_values_strings - true if all Values are to be generated as Value.STRING Types; false otherwise.

Returns:

This Parser.

All_Values_Strings

public boolean All_Values_Strings()

Tests if the Parser will treat all values as strings.

Regardless of this test, treating all values as strings will not be enforced if Strict mode is enabled.

Returns:

true if the Parser will treat all values as strings; false otherwise.

See Also:

All_Values_Strings(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 Parser Reset_Warning()

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

Returns:

This Parser.

See Also:

Warning()

First_Warning

public Parser 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.

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 Parser.

See Also:

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 Parser 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 regarless of any previous warning conditions that may have occured without an intervening Reset_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 Parser.

See Also:

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

Get

public Parameter Get()
              throws PVL_Exception

Gets as many Parameters as possible.

When the source of PVL statements is a Reader, then an aggregate Parameter named CONTAINER_NAME will be provided to contain all the Parameters found (zero or more). If this Parser was created with a String as the source of PVL statements, then a container Parameter will only be provided if more than one Paramter is found: the single Parameter found, or an empty UNKNOWN Parameter if nothing is found.

Returns:

A Parameter containing everything found from the input source.

Throws:

PVL_Exception - If an unrecoverable problem occurred while parsing the input source.

See Also:

Add_To(Parameter), String_Buffer_Reader.String_Source()

Add_To

public Parameter Add_To(Parameter The_Aggregate)
                 throws PVL_Exception

Adds to a Parameter all Parameters found from the input source. Any Paramter added that is itself an AGGREGATE classification will recursively invoke this method on the new aggregate Parameter.

While the source of PVL statements is not empty and Get_Parameter can assemble a Parameter from the source, each new Parameter is Added to the specified Parameter's aggregate list. Note: Parameters having END classifications are not added, instead they stop the addition of Parameters to the current aggregate list; additions will continue with the parent of the current aggregate on returning from recursive method invocations. However, if an END_PVL Parameter is encountered no more Parameters will be added regardless of the recursion level.

Parameters:

The_Aggregate - The aggregate Parameter to which to add new Parameters from the input source.

Returns:

The_Aggregate Parameter.

Throws:

PVL_Exception -

BAD_ARGUMENT

The_Aggregate Parameter is actually an ASSIGNMENT with a non-null Value.

AGGREGATE_CLOSURE_MISMATCH

In Strict mode, when an END_AGGREGATE Parameter does not match the specific classification of the Parameter containing the aggregate list. This is only a Warning when Strict mode is not enabled.

Others are possible during parsing.

See Also:

Parameter.AGGREGATE, String_Buffer_Reader.Is_Empty(), Get_Parameter(), Parameter.Add(Parameter), Parameter.END, Parameter.END_AGGREGATE, Parameter.END_PVL

Get_Parameter

public Parameter Get_Parameter()
                        throws PVL_Exception

Gets a Parameter from the source of PVL statements.

First, Get_Comments is used to to collect any and all comment sequences preceeding the parameter proper as the Parameter's Comments.

The next sequence of non-WHITESPACE characters is taken to be the Parameter's Name. If the sequence is quoted (i.e. starts with a TEXT_DELIMITER or SYMBOL_DELIMITER), then the name is all characters within the quotes. Otherwise it is all characters up to but not including the next PARAMETER_NAME_DELIMITER, STATEMENT_END_DELIMITER, whitespace character, or comment sequence. The name is checked for any Bad_Character and a Warning will be registered (exception thrown in Strict mode) if one is found. If Verbatim_Strings is not enabled, then all character escape sequences in the name are replaced with their corresponding special characters.

If the name is associated with a Special_Classification, then the Parameter is given that classification; otherwise it is tentatively classified as a TOKEN.

If, after any whitespace or comments following the Parameter name, a PARAMETER_NAME_DELIMITER is found, then the Get_Value method is used to obtain the expected Parameter Value. If the Parameter had been given the TOKEN classification, then the classification is upgraded to ASSIGNMENT. If, however, the Parameter had been given an AGGREGATE classification as a result of its special name, and the Value obtained is a STRING type, then the Parameter's name is changed to the Value String; if, in this case, the Value found is not a STRING type a Warning will be registered (exception thrown in Strict mode).

Having assembled a valid Parameter, the Next_Location in the input stream is moved forward past any whitespace or STATEMENT_END_DELIMITER.

Returns:

The next Parameter assembled from the input stream, or null if no Parameter can be assembled because the input stream is empty.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX

Strict mode is enabled and the Parameter name was quoted.

RESERVED_CHARACTER

The Parameter name contained a bad character and Strict mode is enabled.

GROUP_VALUE

The Value obtained for an AGGREGATE Parameter is not a STRING type.

FILE_IO

If an IOException occurred in the String_Buffer_Reader.

See Also:

Get_Comments(), Parameter.Comments(), Parameter.Name(), translate_from_escape_sequences(String_Buffer), Special_Classification(String), Get_Value()

Get_Comments

public String Get_Comments()
                    throws PVL_Exception

Gets the next sequence of comments from the source of PVL statements as a single comment String. After skipping over any whitespace, the next characters must start a comment sequence or nothing (null) is returned.

A PVL comment uses C-style conventions: It starts after the COMMENT_START_DELIMITERS and ends before the COMMENT_END_DELIMITERS. A comment without the closing COMMENT_END_DELIMITERS will result in a MISSING_COMMENT_END exception in Strict mode; otherwise a Warning is registered and the next line break, STATEMENT_END_DELIMITER, or the end of the input stream is taken as the end of the comment. Note: Though an effort is made to recover from encountering an unending comment, this will only be effective when no other normally closed comment occurs in the input stream (if a normally closed comment does occur after an unclosed comment, the latter will be taken as the end of the former), and in this case the input stream will have been read into memory until it is empty.

Sequential comments, with nothing but white space intervening, are accumulated with a single new-line ('\n') chararacter separating them in the resulting String that is returned. In Strict mode comments that wrap across line breaks cause an exception. When Verbatim_Strings are not enabled whitespace is trimmed from the end of each comment (but not the beginning), and escape sequences are translated into their corresponding special characters.

If any comments are found the Next_Location of the input stream is moved to the position immediately following the last comment.

Returns:

A String containing the sequence of comments found, or null if no comment occurs before the next PVL item or the end of input.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX

Strict mode is enabled and a comment continues on more than one line.

MISSING_COMMENT_END

A comment does not have COMMENT_END_DELIMITERS and Strict mode is enabled. If Strict is not enabled and a line or statement delimiter can not be found, then the exception is thrown.

FILE_IO

If an IOException occurred in the String_Buffer_Reader.

See Also:

Verbatim_Strings(boolean)

Get_Value

public Value Get_Value()
                throws PVL_Exception

Gets a Value from the source of PVL statements.

If the next character, after skipping any whitespace and comments, is a SET_START_DELIMITER or SEQUENCE_START_DELIMITER the Value being assembled is typed as a SET or SEQUENCE, respectively, and the Next_Location in the input stream is moved over the character; otherwise the Value is tentatively typed as a SET, and the Next_Location is not moved.

Now a cycle is entered to obtain as many sequential datum values as are available. The first step is to skip any whitespace and comments and test the character that is found. If the character is a SET_END_DELIMITER or SEQUENCE_END_DELIMITER, then the Next_Location in the input stream is moved over the character and Get_Units is used to set the ARRAY Value's units description before ending the datum cycle. If the character is a STATEMENT_END_DELIMITER the datum cycle ends. A reserved PARAMETER_NAME_DELIMITER, PARAMETER_VALUE_DELIMITER, UNITS_START_DELIMITER, UNITS_END_DELIMITER, or NUMBER_BASE_DELIMITER character here is an ILLEGAL_SYNTAX exception. For any other character the Next_Location is moved forward to its position as a possible datum.

When the character at this location is a SET_START_DELIMITER or SEQUENCE_START_DELIMITER this method is called recursively to get a subarray as the datum. Otherwise the Get_Datum method is used to get a basic value followed by the Get_Units method to get any units description for the new datum. If no datum is obtained the datum cycle ends, otherwise the new datum is added to the Vector of Value's being accumulated for this new Value.

After skipping any whitespace and comments the next character is checked. A reserved PARAMETER_NAME_DELIMITER, UNITS_START_DELIMITER, UNITS_END_DELIMITER, or NUMBER_BASE_DELIMITER character here is an ILLEGAL_SYNTAX exception. A SET_START_DELIMITER or SEQUENCE_START_DELIMITER character will also generate an ILLEGAL_SYNTAX exception, but if Strict mode is not enabled this will just be registered as a Warning and the Next_Location will be moved to the character's position before continuing the datum cycle from the beginning. If the character is a PARAMETER_VALUE_DELIMITER the Next_Location is moved over the character and the datum cycle returns to the beginning. For a SET_END_DELIMITER or SEQUENCE_END_DELIMITER, if the character does not correspond to the delimiter that began the array an ARRAY_CLOSURE_MISMATCH Warning is registered (this exception is thrown in Strict mode). Then the Next_Location is moved over the character and the Get_Units method is used to set this Value's units description before ending the datum cycle. Any other character also causes the datum cycle to end.

After the datum cycle has collected as many Values as possible, if this new Value was not begun with a SET_START_DELIMITER or SEQUENCE_START_DELIMITER and the accumulated Values Vector containins less than two Values then the initial tentative SET type does not apply. In this case an empty accumlated Values Vector results in this new Value being an UNNOWN type (i.e. it is empty). When only one Value was collected it is the new Value that is returned. When two or more Values were collected the Vector containing them is set as the data of this ARRAY Value.

Returns:

The next Value assembled from the input stream, or null if no Value can be assembled because the input stream is empty.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX

A misplaced reserved character was found.

ARRAY_CLOSURE_MISMATCH

The delimiter character ending an array of Values does not correspond to the one that began the array.

FILE_IO

If an IOException occurred in the String_Buffer_Reader.

See Also:

Value.set_type(int), Value.Units(String), Get_Datum(Value)

Get_Datum

public Value Get_Datum(Value The_Value)
                throws PVL_Exception

Gets a datum from the source of PVL statements.

After skipping any whitespace or comments, the next character is checked to determine the type of datum to parse. For a STATEMENT_END_DELIMITER nothing happens. A reserved PARAMETER_NAME_DELIMITER, PARAMETER_VALUE_DELIMITER, SET_START_DELIMITER, SET_END_DELIMITER, SEQUENCE_START_DELIMITER, SEQUENCE_END_DELIMITER, UNITS_START_DELIMITER, UNITS_END_DELIMITER, or NUMBER_BASE_DELIMITER character here is an ILLEGAL_SYNTAX exception. For a TEXT_DELIMITER or SYMBOL_DELIMITER the Get_Quoted_String method is used to set the datum of the Value and its type is set to TEXT or SYMBOL respectively.

For any ordinary character the substring up to, but not including, the next WHITESPACE, PARAMETER_VALUE_DELIMITER, STATEMENT_END_DELIMITER, COMMENT_START_DELIMITERS, any of the SET/SEQUENCE/UNITS START/END delimiters, or the end of the input stream is used for parsing a datum. If Verbatim_Strings is not enabled, then all escape sequences in the substring are converted to their special character equivalents.

The datum substring is first assumed to represent a number. If the substring contains a NUMBER_BASE_DELIMITER ('#') the number is presumed to be in radix base notation:

[sign]base#value#

In this case the initial base integer is obtained using the Integer.parseInt method and becomes the Value's Base, and the value number is obtained using the Long.parseLong method with the base argument specified and becomes the Value's datum. The sign is applied to the value number. The Value becomes type INTEGER. Without the NUMBER_BASE_DELIMITER the datum substring is taken to be in decimal notation. If this number conversion fails, then the Double.valueOf method is tried on the datum substring to produce a type REAL Value.

N.B.: If treating all values as strings has been enabled, and Strict mode is not enabled, then the value is not assumed to be a number; it is always taken as string.

If parsing the datum substring as a number fails, then the Value is a STRING and its datum is the substring. If the substring contains one of the DATE_TIME_DELIMITERS the Value is given the DATE_TIME type. Otherwise it is the IDENTIFIER type. The datum substring is also checked for a Bad_Character with a Warning being registered (exception thrown in Strict mode) if one is found.

Once a datum has been given to the Value the Next_Location in the input stream is moved to the position immediately following the datum substring.

Parameters:

The_Value - The Value to which the next datum is to be applied.

Returns:

The_Value, or null if the input stream is empty.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX

A misplaced reserved character was found.

RESERVED_CHARACTER

A STRING Value contains a reserved character.

FILE_IO

If an IOException occurred in the String_Buffer_Reader.

See Also:

Integer.parseInt(String), Long.parseLong(String, int), Double.valueOf(String), Value.set_data(Object), Value.Base(int), Value.set_type(int), translate_from_escape_sequences(String_Buffer)

Get_Units

public String Get_Units()
                 throws PVL_Exception

Gets a units description String from the source of PVL statements.

After skipping over any whitespace, the next character must start a units description sequence or nothing (null) is returned. A units description sequence starts after a UNITS_START_DELIMITER and ends before a UNITS_END_DELIMITER. A units description sequence without the closing UNITS_END_DELIMITER will result in a MISSING_UNITS_END exception in Strict mode; otherwise a Warning is registered and the next PARAMETER_VALUE_DELIMITER, any of the SET/SEQUENCE/UNITS START/END delimiters, STATEMENT_END_DELIMITER, or the end of the input stream is taken as the end of the units description. Note: Though an effort is made to recover from encountering an unending units description, this will only be effective when no other normally closed units descripiton occurs in the input stream (if a normally closed units descripiton does occur after an unclosed units description, the latter will be taken as the end of the former), and in this case the input stream will have been read into memory until it is empty.

Sequential comments, with nothing but white space intervening, are accumulated with a single new-line ('\n') chararacter separating them in the resulting String that is returned. In Strict mode comments that wrap across line breaks cause an exception. When Verbatim_Strings are not enabled whitespace is trimmed from the end of each comment (but not the beginning), and escape sequences are translated into their corresponding special characters.

If a units descripiton is found the Next_Location of the input stream is moved to the position immediately following it. The units description is trimmed of leading and trailing whitespace. If Verbatim_Strings is not enabled, then all comment sequences are removed from the units description String, all whitespace sequences are collapsed to a single space (' ') character, and escape sequences are substituted for their corresponding special characters.

Returns:

A units description String, or null if no units description occurs before the next PVL item or the end of input.

Throws:

PVL_Exception -

MISSING_UNITS_END

A units description does not have a UNITS_END_DELIMITER.

FILE_IO

If an IOException occurred in the String_Buffer_Reader.

See Also:

Verbatim_Strings(boolean), translate_from_escape_sequences(String_Buffer)

Get_Quoted_String

public String Get_Quoted_String()
                         throws PVL_Exception

Gets a quoted String from the source of PVL statements.

The next non-whitespace character is taken to be the "quote" character. The characters following the first quote character up to but not including the next, non-escaped (not preceeded by a backslash, '\') quote character are the quoted string. If the closing quote character can not be found, then a MISSING_QUOTE_END Warning will be registered (the exception will be thrown in Strict mode) and the quoted string will end at the end of the input stream. Note: The lack of a closing quote character will cause the entire input stream to be read into memory until it is emtpy. The Next_Location is moved to the position immediately following the last quote character.

If Verbatim_Strings is not enabled then line break sequences (one or more sequential line breaks) and any surrounding whitespace (whitespace ending the last line and beginning the next line) are replaced with a single space (' ') character. If, however, String_Continuation is enabled and the last non-whitespace character before the line break sequence is a STRING_CONTINUATION_DELIMITER then no space remains (i.e. the string ending with the last non-whitespace character on the last line is continued with the first non-whitspace character on the next line). In addition, escape sequences are translated to their corresponding special characters. Sequences of characters bracketed by VERBATIM_STRING_DELIMITERS are taken verbatim; they are subject to neither end of line treatment nor escape sequence translation.

Returns:

A String, or null if no non-whitespace character occurs before the end of input.

Throws:

PVL_Exception -

MISSING_QUOTE_END

A closing quote was not found in the input stream.

FILE_IO

If an IOException occurred in the String_Buffer_Reader.

See Also:

Verbatim_Strings(boolean), String_Continuation(boolean), String_Buffer.escape_to_special()

skip_whitespace_and_comments

public long skip_whitespace_and_comments(long location)
                                  throws PVL_Exception

Gets the next location in the PVL source stream following any sequence of whitespace and/or comments. A STATEMENT_CONTINUATION_DELIMITER and any Crosshatch_Comments (if enabled) are included in the whitespace category. Note: As with the Get_Comments method, a comment without a closing sequence is taken to end and the next line break, STATEMENT_END_DELIMITER, or the end of the input stream; but this condition will cause the entire input stream to be read into memory.

Parameters:

location - The starting location from which to skip over whitespace and comments.

Returns:

The location of the next character after any whitespace or comments.

Throws:

PVL_Exception -

MISSING_COMMENT_END

A comment does not have COMMENT_END_DELIMITERS and Strict mode is enabled.

FILE_IO

If an IOException occurred in the String_Buffer_Reader.

translate_from_escape_sequences

public static String_Buffer translate_from_escape_sequences(String_Buffer string)

Translates escape sequences in a String_Buffer to their corresponding special characters. The escape_to_special method is used to translate escape sequences to special characters. However the occurance of VERBATIM_STRING_DELIMITERS starts a sequence of characters that are taken verbatim (they are not translated) up to the next VERBATIM_STRING_DELIMITERS or the end of the string (the VERBATIM_STRING_DELIMITERS are dropped).

Parameters:

string - The String_Buffer to be translated.

Returns:

The translated String_Buffer.

See Also:

String_Buffer.escape_to_special()

Bad_Character

public static int Bad_Character(String string)

Checks a String for any bad character. A bad character is one of the RESERVED_CHARACTERS or a non-printable character.

Parameters:

string - The String to check.

Returns:

The index of the first bad character found in the string, or -1 if no bad characters were found.

isprint

public static boolean isprint(char character)

Tests if a character is printable: in the ASCII range from the space character (' ') to the tilde character ('~') inclusive.

Parameters:

character - The char to test.

Returns:

true if the character is printable; false otherwise.

Special_Classification

public static int Special_Classification(String name)

Gets the Parameter classification code corresponding to the specified special Parameter name String. The special Parameter names and their classification codes are:

Begin_Object or BeginObject - BEGIN_OBJECT
Object - OBJECT
End_Object or EndObject - END_OBJECT
Begin_Group or BeginGroup - BEGIN_GROUP
Group - GROUP
End_Group or EndGroup - END_GROUP
End - END_PVL

The names are not case sensitive.

Parameters:

name - A String that may be a special Parameter name.

Returns:

the Parameter classification code associated with the special Parameter name; or -1 if the name is not a special Parameter name.

See Also:

Parameter

Special_Name

public static String Special_Name(int classification)

Gets the special Parameter name String for the specified Parameter classification code.

Parameters:

classification - A Parameter classification code int.

Returns:

The special Parameter name String associated with the classification code; or null if the classification code is not associated with a special Parameter name.

See Also:

Special_Classification(String)