A Parser interprets the characters of a Sliding_String as a sequence of Parameter Value Language (PVL) syntax statements. More...

#include <Parser.hh>

Inheritance diagram for Parser:

[legend]

Collaboration diagram for Parser:

[legend]

List of all members.

Public Types
typedef idaeim::Strings::String_Filter	Filter
	String_Filters applied to the Sliding_String.
typedef std::vector< Exception * >	Warnings_List
	Vector of warning Exception pointers.
Public Member Functions
Aggregate &	add_parameters (Aggregate &aggregate)
	Adds to an Aggregate all Parameters found from the input source.
Value &	add_values (Array &array)
	Adds to an Array the next Values found from the input source.
void	clear_warnings ()
	Clears all warnings.
Parser &	commented_lines (bool allow)
	Enable or disable recognition of single commented lines.
bool	commented_lines ()
	Tests if commented lines will be recognized.
std::string	get_comment ()
	Gets the next sequence of comments from the source of PVL statements as a single comment string.
Value *	get_datum ()
	Gets a datum from the source of PVL statements.
Parameter *	get_parameter (bool Assignment_only=false)
	Gets a Parameter from the source of PVL statements.
Parameter *	get_parameters ()
	Gets as many Parameters as possible.
std::string	get_quoted_string ()
	Gets a quoted string from the source of PVL statements.
std::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.
Parser &	operator= (const Parser &parser)
	Parser (const Parser &parser)
	Parser ()
	Creates a Parser with no source of PVL statements.
	Parser (std::istream &reader, Location limit=Sliding_String::NO_LIMIT)
	Creates a Parser using an istream as the source of PVL statements, and sets a limit on the amount to read.
	Parser (const std::string &string_source)
	Creates a Parser using a String as the source of PVL statements.
Location	skip_whitespace_and_comments (Location location)
	Gets the next Location in the PVL source stream following any sequence of whitespace and/or comments.
bool	strict ()
	Tests if the Parser will enforce strict PVL syntax rules.
Parser &	strict (bool strict)
	Enables or disables strict PVL syntax rules in the Parser.
bool	string_continuation ()
	Tests if the string continuation delimiter will be recognized.
Parser &	string_continuation (bool enable)
	Enable or disable recognition of the string continuation delimiter.
Parser &	verbatim_strings (bool verbatim)
	Enable or disable verbatim quoted strings.
bool	verbatim_strings ()
	Tests if the Parser will handle quoted strings verbatim.
Warnings_List *	warnings ()
	Gets the current vector of warning conditions.
virtual	~Parser ()
Static Public Attributes
static const char *const	COMMENT_END_DELIMITERS
	Marks the end of a comment string.
static const char	COMMENT_LINE_DELIMITER
	Begins a comment that extends to the end of the line.
static const char *const	COMMENT_START_DELIMITERS
	Marks the start of a comment string.
static const char *const	CONTAINER_NAME
	The default name of the Aggregate to contain all Parameters when get_parameters() finds more than one Parameter or the source is an istream.
static const char *const	DATE_TIME_DELIMITERS
	Set of characters that suggests a DATE_TIME type of STRING Value.
static const char *const	ID
	Class identification.
static const char *const	LINE_BREAK
	Character sequence that separates PVL statement lines.
static const char	NUMBER_BASE_DELIMITER
	Encloses the datum of a Value in radix base notation.
static const char	PARAMETER_NAME_DELIMITER
	Delimits a Parameter name from its Value.
static const char	PARAMETER_VALUE_DELIMITER
	Delimits elements of an ARRAY Value.
static const char *const	RESERVED_CHARACTERS
	Characters reserved by the PVL syntax.
static const char	SEQUENCE_END_DELIMITER
	Marks the end of a SEQUENCE ARRAY Value.
static const char	SEQUENCE_START_DELIMITER
	Marks the start of a SEQUENCE ARRAY Value.
static const char	SET_END_DELIMITER
	Marks the end of a SET ARRAY Value.
static const char	SET_START_DELIMITER
	Marks the start of a SET ARRAY Value.
static const char	STATEMENT_CONTINUATION_DELIMITER
	Indicates that the statement continues in the next record.
static const char	STATEMENT_END_DELIMITER
	Marks the end of a PVL statement.
static const char	STRING_CONTINUATION_DELIMITER
	Indicates that the quoted string continues unbroken in the next record.
static const char	SYMBOL_DELIMITER
	Encloses a SYMBOL STRING Value.
static const char	TEXT_DELIMITER
	Encloses a TEXT STRING Value.
static const char	UNITS_END_DELIMITER
	Marks the end of a Value units description.
static const char	UNITS_START_DELIMITER
	Marks the start of a Value units description.
static const char *const	VERBATIM_STRING_DELIMITERS
	Encloses a verbatim (uninterpreted) string.
static const char *const	WHITESPACE
	Set of "whitespace" characters between PVL tokens.
Protected Member Functions
Parameter::Type	ingest_parameters (Aggregate &aggregate)
	Ingests from the input source all Parameters found, putting them in the aggregate.
std::string	line_position (bool before, Location location) const
Location	skip_commented_line (Location location)
void	WARNING (Exception *exception)

Detailed Description

A Parser interprets the characters of a Sliding_String 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 (CCSD0006,8)", June 2000 [CCSDS 641.0-B-2] and Green Book "Parameter Value Language - A Tutorial", June 2000 [CCSDS 641.0-G-1] documents. PVL has been accepted by the International Standards Organization (ISO), as a Final Draft International Standard (ISO 14961:2002) keyword value type language for naming and expressing data values.

The PVL syntax defines a Parameter with this basic format:

[Comment]
Name [= Value][;]

The optional Comment is enclosed in C-style delimiters.

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 Sliding_String. The Parser inserts a VMS_Records_Filter into the Sliding_String to automatically handle the special binary record size values if this (now obsolete) data source is encountered. A set of syntax modes are provided to control how strictly the PVL syntax will be applied. Normally the Parser is very tolerant with the goal of providing parameters if at all possible, and when what might be a syntax violation is encountered but can be elided the exception that would have been thrown is saved in a stack of warnings for possible consideration.

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

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 comment, 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. 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 Sliding_String 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 parsed to construct the corresponding object class variable. If the parsing of the element is successful then the logical next_location of the Sliding_String is moved forward to the end of the sequence, thus consuming the character sequence. If, however, the beginning of a recognizable syntactic sequence is not found, or the parsing of a sequence fails, then the method returns empty handed, and without having advanced the logical Sliding_String, 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 parsed at the same time that the input stream is incrementally moved forward.

See also:: Sliding_String; Parameter; Value

Author:: Bradford Castalia

Version:: 1.28

Member Typedef Documentation

typedef std::vector<Exception*> Warnings_List

Vector of warning Exception pointers.

typedef idaeim::Strings::String_Filter Filter

String_Filters applied to the Sliding_String.

Constructor & Destructor Documentation

Parser ( ) [inline]

Creates a Parser with no source of PVL statements.

Parser	(	std::istream &	reader,
		Location	limit = `Sliding_String::NO_LIMIT`
	)

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

Parameters:

reader	The istream to use as the source of characters.
limit	The maximum amount to read.

See also:: Sliding_String::Sliding_String(const istream&, Location)

Parser ( const std::string & string_source )

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

Parameters:

string_source The string to use as the source of characters.

See also:: Sliding_String::Sliding_String(const String&)

Parser ( const Parser & parser ) [inline]

virtual ~Parser ( ) [virtual]

Member Function Documentation

Parser& operator= ( const Parser & parser )

Parser& strict ( bool strict ) [inline]

Enables or disables strict PVL syntax rules in the Parser.

Normally the Parser is tolerant.

Parameters:

strict true if strict rules are applied; false otherwise.

Returns:: This Parser.

References Parser::strict().

Referenced by Parser::strict().

bool strict ( ) [inline]

Tests if the Parser will enforce strict PVL syntax rules.

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

Parser& verbatim_strings ( bool verbatim ) [inline]

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

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(); get_comment(); get_datum(); get_units()

bool verbatim_strings ( ) [inline]

Tests if the Parser will handle quoted strings verbatim.

Returns:: true if quoted strings are taken verbatim; false otherwise.

See also:: Verbatim_Strings(boolean)

Parser& commented_lines ( bool allow ) [inline]

Enable or disable recognition of single commented lines.

A commented line begins with the COMMENT_LINE_DELIMITER character and extends to the end of the current line (marked by a LINE_BREAK character). Commented lines are never recognized in strict mode.

N.B.: Commented lines 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 commented lines are not recognized.

Parameters:

allow true if crosshatch comments are to be recognized.

Returns:: This Parser.

See also:: get_quoted_string()

bool commented_lines ( ) [inline]

Tests if commented lines will be recognized.

Regardless of this test, commented lines are never recognized in strict mode.

Returns:: true if commented lines will be recognized; false otherwise.

See also:: commented_lines(bool)

Parser& string_continuation ( bool enable ) [inline]

Enable or disable recognition of the string continuation delimiter.

Normally, unless verbatim strings is enabled, when a quoted string continues across multiple lines the end of line sequence and all surrounding white space are collapsed to a single space character (' '). 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 a 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. However, if the string continuation delimiter is preceeded by a space character, or the delimiter is the first character of the string, the delimiter is retained but the normal collapsing of whitespace around the line wrap to a single space is still done.

By default string continuation is enabled.

Parameters:

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

Returns:: This Parser.

See also:: get_quoted_string(); verbatim_strings(bool)

bool string_continuation ( ) [inline]

Tests if the string continuation delimiter will be recognized.

Returns:: true if the continuation delimiter will be recognized; false otherwise.

See also:: string_continuation(bool)

Warnings_List* warnings ( ) [inline]

Gets the current vector of warning conditions.

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 pointer to an Exception that was not thrown. Each new warning is appended to the vector of Warnings maintained for the Parser.

N.B.: The warnings are pointers to Exception objects created with new. DO NOT delete the Warnings_List; use clear_warnings() instead.

Returns:: A pointer to the current list of warning pointers.

See also:: clear_warnings()

void clear_warnings ( )

Clears all warnings.

Each warning pointer in the list first has its Exception object deleted, then all of the now invalid warning pointers are deleted. This leaves a clean, empty warnings list.

See also:: warnings()

Parameter* get_parameters ( )

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 Parameter is found; otherwise the single Parameter found is returned. If nothing is found then NULL is returned.

Returns:: A Parameter containing everything found from the input source, or NULL if nothing was found.

Exceptions:

Invalid_Syntax If an unrecoverable problem occurred while parsing the input source.

See also:: add_parameters(Aggregate&)

Aggregate& add_parameters ( Aggregate & aggregate )

Adds to an Aggregate all Parameters found from the input source.

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. N.B.: Parameters having the END Parameter::Type 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 Parameter is encountered no more Parameters will be added regardless of the recursion level.

Parameters:

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

Returns:: The original aggregate Parameter.

Exceptions:

Aggregate_Closure_Mismatch In strict mode, when an END Aggregate Parameter does not match the specific Parameter::Type containing the aggregate list. This is only added to the warnings list when strict mode is not enabled.

See also:: get_parameter()

Parameter* get_parameter ( bool Assignment_only = false )

Gets a Parameter from the source of PVL statements.

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

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 reserved characters 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_type, then the Parameter is given that Parameter::Type; otherwise it is tentatively set 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 Parameter::Type, then the Type is upgraded to ASSIGNMENT. If, however, the Parameter had been given an AGGREGATE Type 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.

Exceptions:

Invalid_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.
Invalid_Aggregate_Value	The Value obtained for an Aggregate Parameter is not a STRING type.

See also:: get_comment(); Parameter::comment(); Parameter::name(); reserved_character(const std::string&); translate_from_escape_sequences(String); special_type(String); get_value()

std::string get_comment ( )

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. N.B.: 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 ('
') 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 comment found, or NULL if no comment occurs before the next PVL item or the end of input.

Exceptions:

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

See also:: verbatim_strings(boolean)

Value& add_values ( Array & array )

Adds to an Array the next Values found from the input source.

While the source of PVL statements is not empty and get_value can assemble a Value from the source, each new Value is added to the specified Array's element list.

Parameters:

array The Array to which to add new Values.

Returns:: The original Array.

Value* get_value ( )

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 Invalid_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 Invalid_Syntax exception. A SET_START_DELIMITER or SEQUENCE_START_DELIMITER character will also generate an Invalid_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 a 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.

Exceptions:

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

See also:: Value::type(int); Value::units(string); get_datum(Value)

Value* get_datum ( )

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 Invalid_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 and becomes the Value's numeric base, and the value number is obtained using the base for parsing the representation 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. In addition, unless DECIMAL_NOTATION_ONLY was defined at compile time, a datum substring that begins with "0x" or "0X" is taken to be in hexadecimal notation.

If this number conversion fails, then floating point representation parsing is tried on the datum substring to produce a type REAL Value. If this succeeds the number of decimal precision digits of the Value is determined by finding the location of the decimal point character ('.') in the datum string and the number of decimal digits that follow it. For scientific notation - in which an 'e' or 'E' exponent notation is present - the decimal point is expected to follow one non-zero digit. N.B.: For scientific notation the decimal point is assumed to be the second character in the datum string regardless of its actual location, which ensures that at least the full numeric precision of the value will be represented. The format flags are set to fixed point or scientific notation corresponding to the datum substring representation; the showpoint format flag is always set.

Numeric conversions are checked for validity. For example, overflow conditions result in an invalid condition.

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 any reserved characters 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.

Returns:: The_Value, or NULL if the input stream is empty.

Exceptions:

Reserved_Character	A STRING Value contains a reserved character.
Invalid_Value	A number conversion was found to be invalid.

See also:: reserved_character(const std::string&); translate_from_escape_sequences(String); Value::base(const int); Value::digits(const int); Real::format_flags(std::ios::fmtflags)

std::string get_units ( )

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. N.B.: 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.

Exceptions:

Missing_Units_End A units description does not have a UNITS_END_DELIMITER.

See also:: verbatim_strings(boolean); translate_from_escape_sequences(String)

std::string get_quoted_string ( )

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. N.B.: 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 squence is a STRING_CONTINUATION_DELIMITER that is not preceded by a space character (and the delimiter is not the first character of the string) 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.

Exceptions:

Missing_Quote_End A closing quote was not found in the input stream.

See also:: verbatim_strings(boolean); String::escape_to_special()

Location skip_whitespace_and_comments ( Location location )

Gets the next Location in the PVL source stream following any sequence of whitespace and/or comments.

A STATEMENT_CONTINUATION_DELIMITER and any commented lines (if enabled) are included in the whitespace category. N.B.: As with the get_comment 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 input stream to be read to its limit 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.

Exceptions:

Missing_Comment_End A comment does not have COMMENT_END_DELIMITERS and strict mode is enabled.

Parameter::Type ingest_parameters ( Aggregate & aggregate ) [protected]

Ingests from the input source all Parameters found, putting them in the aggregate.

This method is invoked recursively on each aggregate Parameter ingested.

Parameters:

aggregate The aggregate Parameter to receive new Parameters from the input source.

Returns:: The Parameter::Type last ingested; this will be END when the last Parameter, or an error condition, was encountered.

Exceptions:

Aggregate_Closure_Mismatch In strict mode, when an END Aggregate Parameter does not match the specific Parameter::Type containing the aggregate list. This is only a warning when strict mode is not enabled.