A Lister is used to manage the listing of PVL objects. More...

#include <Lister.hh>

Collaboration diagram for Lister:

Classes
struct	Which_Mode
	Mode set selector. More...
Public Types
enum	MODE { Begin_Aggregates, Uppercase_Aggregates, Name_End_Aggregates, Assign_Align, Array_Indenting, Use_Statement_Delimiter, Single_Line_Comments, Verbatim_Strings, TOTAL_MODES }
	Mode selectors. More...
Public Member Functions
Lister &	array_indenting (const bool enabled, const Which_Mode which=LOCAL_MODE_SET)
	Enable or disable indenting of Assignment Array Values.
bool	array_indenting (const Which_Mode &which=LOCAL_MODE_SET) const
	Test if indenting of Array Values is enabled.
Lister &	assign_align (const bool enabled, const Which_Mode which=LOCAL_MODE_SET)
	Enable or disable Assignment alignment.
bool	assign_align (const Which_Mode &which=LOCAL_MODE_SET) const
	Test if Assignment alignment is enabled.
bool	begin_aggregates (const Which_Mode &which=LOCAL_MODE_SET) const
	Test if the BEGIN annotation for Aggregates is enabled.
Lister &	begin_aggregates (const bool enabled, const Which_Mode &which=LOCAL_MODE_SET)
	Enable or disable the BEGIN annotation for Aggregates.
void	clear ()
	Clears the pending characters buffer.
unsigned int	flush (int wrap_depth=0)
	Flushes any pending characters to the output stream of this Lister.
Lister &	indent (int depth)
	Writes indenting characters.
unsigned int	indent_depth (int level) const
	Calculates the character depth of an indent level.
Lister &	indent_width (const int width, const Which_Mode &which=LOCAL_MODE_SET)
	Sets the indenting width.
int	indent_width (const Which_Mode &which=LOCAL_MODE_SET) const
	Gets the indenting width.
bool	indenting () const
	Tests if indenting is enabled.
Lister &	informal_NL (const char *new_line_characters, const Which_Mode &which=LOCAL_MODE_SET)
	Sets the informal (strict = false) new-line character sequence.
const char *	informal_NL (const Which_Mode &which=LOCAL_MODE_SET) const
	Gets the informal (strict = false) new-line character sequence.
	Lister (const Lister &lister)
	Copy constructor.
	Lister (std::ostream &out=std::cout)
	Default constructor.
bool	mode (const MODE selection, const Which_Mode &which=LOCAL_MODE_SET) const
	Gets the state of a mode.
Lister &	mode (const MODE selection, const bool enabled, const Which_Mode &which=LOCAL_MODE_SET)
	Sets the state of a mode.
const bool *	modes (const Which_Mode &which=LOCAL_MODE_SET) const
	Gets the array of syntax mode states.
Lister &	modes (const bool *mode_set, const Which_Mode &which=LOCAL_MODE_SET)
	Sets the state of all syntax modes.
Lister &	name_end_aggregates (const bool enabled, const Which_Mode which=LOCAL_MODE_SET)
	Enable or disable the use of the Aggregate name in its end identifier.
bool	name_end_aggregates (const Which_Mode which=LOCAL_MODE_SET) const
	Test if the use of the Aggregate name in its end identifier is enabled.
Lister &	new_line (int wrap_depth=0)
	Adds an end-of-line marker to the characters pending output, which results in them being flushed to the output stream.
Lister &	NL (const char *new_line_characters, const Which_Mode &which=LOCAL_MODE_SET)
	Sets the new-line (end-of-line) character sequence.
const char *	NL (const Which_Mode &which=LOCAL_MODE_SET) const
	Gets the new-line (end-of-line) character sequence.
std::ostream &	operator<< (const Parameter &parameter)
	Writes a Parameter.
std::ostream &	operator<< (const Value &value)
	Writes a Value.
Lister &	output_stream (std::ostream &out)
	Sets the output stream.
std::ostream &	output_stream () const
	Gets the output stream.
int	page_width (const Which_Mode &which=LOCAL_MODE_SET) const
	Gets the page width.
Lister &	page_width (const int width, const Which_Mode &which=LOCAL_MODE_SET)
	Sets the page width.
int	parameter_name (const std::string &name, bool verbatim=false)
	Writes a Parameter name.
unsigned int	pending () const
	Gets the number of buffered characters pending output.
std::string	pending_characters () const
	Gets the characters pending output.
Lister &	reset_total ()
	Resets the count of total characters output to zero.
Lister &	single_line_comments (const bool enabled, const Which_Mode &which=LOCAL_MODE_SET)
	Enable or disable single line comments.
bool	single_line_comments (const Which_Mode &which=LOCAL_MODE_SET) const
	Test if single line comments will be used.
Lister &	strict (const bool enabled, const Which_Mode &which=LOCAL_MODE_SET)
	Enables or disables strict PVL syntax rules.
bool	strict (const Which_Mode &which=LOCAL_MODE_SET) const
	Test if strict PVL syntax rules will be enforced.
const char *	strict_NL (const Which_Mode &which=LOCAL_MODE_SET) const
	Gets the strict (strict = true) new-line character sequence.
Lister &	strict_NL (const char *new_line_characters, const Which_Mode &which=LOCAL_MODE_SET)
	Sets the strict (strict = true) new-line character sequence.
unsigned int	total () const
	Gets the total number of characters written.
Lister &	uppercase_aggregates (const bool enabled, const Which_Mode &which=LOCAL_MODE_SET)
	Enable or disable uppercase of Aggregate identifiers.
bool	uppercase_aggregates (const Which_Mode &which=LOCAL_MODE_SET) const
	Test if the uppercase of Aggregate identifiers is enabled.
Lister &	use_statement_delimiter (const bool enabled, const Which_Mode &which=LOCAL_MODE_SET)
	Enable or disable the use of the statement end delimiter.
bool	use_statement_delimiter (const Which_Mode &which=LOCAL_MODE_SET) const
	Test if the statement end delimiter character will be used.
Lister &	value_units (const std::string &units)
	Writes a Value units string.
Lister &	value_units (const Value &value)
	Writes a units string for a Value.
bool	verbatim_strings (const Which_Mode &which=LOCAL_MODE_SET) const
	Test if quoted strings will be written verbatim.
Lister &	verbatim_strings (const bool enabled, const Which_Mode &which=LOCAL_MODE_SET)
	Enable or disable verbatim quoted strings.
Lister &	write (const String &text, int wrap_depth=0)
	Writes a String Value.
Lister &	write (const Integer &integer, int wrap_depth=0)
	Writes an Integer Value.
unsigned int	write (int wrap_to=0, const std::string &leading="", const std::string &trailing="")
	Writes any pending characters on the output stream of this Lister.
Lister &	write (const Array &array, int wrap_depth=0)
	Writes an Array Value.
Lister &	write (const std::string &characters, int wrap_depth=0)
	Writes characters.
Lister &	write (const Real &real, int wrap_depth=0)
	Writes a Real Value.
Lister &	write (const Assignment &assignment, int wrap_depth=0)
	Writes an Assignment.
Lister &	write (const char character, int wrap_depth=0)
	Writes a character.
Lister &	write (const Value &value, int wrap_depth=0)
	Writes a Value.
Lister &	write (const Parameter &parameter, int wrap_depth=0)
	Writes a Parameter.
Lister &	write (const Aggregate &aggregate, int wrap_depth=0)
	Writes an Aggregate.
Lister &	write_comment (const std::string &comment, int depth=0)
	Writes a comment.
Static Public Member Functions
static void	default_array_indenting (const bool enabled)
	Convenience function for static setting of default modes.
static bool	default_array_indenting ()
	Convenience function for static testing of default modes.
static void	default_assign_align (const bool enabled)
	Convenience function for static setting of default modes.
static bool	default_assign_align ()
	Convenience function for static testing of default modes.
static bool	default_begin_aggregates ()
	Convenience function for static testing of default modes.
static void	default_begin_aggregates (const bool enabled)
	Convenience function for static setting of default modes.
static void	default_indent_width (const int width)
	Convenience function for static setting of default modes.
static int	default_indent_width ()
	Convenience function for static getting of default values.
static bool	default_mode (const MODE selection)
	Convenience function for static testing of default modes.
static void	default_mode (const MODE selection, const bool enabled)
	Convenience function for static setting of default modes.
static bool	default_name_end_aggregates ()
	Convenience function for static testing of default modes.
static void	default_name_end_aggregates (const bool enabled)
	Convenience function for static setting of default modes.
static void	default_NL (const char *new_line_characters)
	Convenience function for static setting of default modes.
static const char *	default_NL ()
	Convenience function for static getting of default values.
static int	default_page_width ()
	Convenience function for static getting of default values.
static void	default_page_width (const int width)
	Convenience function for static setting of default modes.
static bool	default_single_line_comments ()
	Convenience function for static testing of default modes.
static void	default_single_line_comments (const bool enabled)
	Convenience function for static setting of default modes.
static void	default_strict (const bool enabled)
	Convenience function for static setting of default modes.
static bool	default_strict ()
	Convenience function for static testing of default modes.
static void	default_uppercase_aggregates (const bool enabled)
	Convenience function for static setting of default modes.
static bool	default_uppercase_aggregates ()
	Convenience function for static testing of default modes.
static void	default_use_statement_delimiter (const bool enabled)
	Convenience function for static setting of default modes.
static bool	default_use_statement_delimiter ()
	Convenience function for static testing of default modes.
static bool	default_verbatim_strings ()
	Convenience function for static testing of default modes.
static void	default_verbatim_strings (const bool enabled)
	Convenience function for static setting of default modes.
Static Public Attributes
static int	Default_Indent_Width
static const char *	Default_Informal_NL_Characters
static const Which_Mode	DEFAULT_MODE_SET
	The syntax mode which argument for selecting default modes.
static int	Default_Page_Width
static const char *	Default_Strict_NL_Characters
static const char *const	ID
	Class identification name with source code version and date.
static const Which_Mode	LOCAL_MODE_SET
	The syntax mode which argument for selecting local modes.
static const int	NO_INDENT
	The indent level value for no indenting.
Protected Attributes
int	Assign_Align_Depth
	The Assign_Align depth.
int	Indent_Width
	The width of an indent level.
const char *	Informal_NL_Characters
bool	Modes [TOTAL_MODES]
	Local (object) mode states.
const char *	New_Line
	The New_Line sequence is an aspect of Strict mode.
int	Page_Width
	The maximum width of a listing.
const char *	Strict_NL_Characters
Static Protected Attributes
static bool	Default_Modes [TOTAL_MODES]
	Default (static) mode states.
static const char *	Default_New_Line
static const bool	STRICT_MODES [TOTAL_MODES]
	Strict mode states.

Detailed Description

A Lister is used to manage the listing of PVL objects.

A Lister controls the modes for writing PVL syntax text for Parameter and Value objects. These control the use of strict Parameter Value Language syntax such as multiple or single line comments, the use of formatting escape sequences, the PVL statement end marker, and the end-of-line character sequence. In addition, line indenting and wrapping to a maximum page width are also managed.

The Lister provides both global defaults and lister specific mode settings. These settings apply to each Parameter and Value listed. They supplement the Parameter specific syntax modes.

See also:: Parameter; Value; Parser

Author:: Bradford Castalia

Version:: 1.27

Member Enumeration Documentation

enum MODE

Mode selectors.

Enumerator:

Begin_Aggregates
Uppercase_Aggregates
Name_End_Aggregates
Assign_Align
Array_Indenting
Use_Statement_Delimiter
Single_Line_Comments
Verbatim_Strings
TOTAL_MODES

Constructor & Destructor Documentation

Lister ( std::ostream & out = std::cout ) [explicit]

Default constructor.

All local data members are initialized from their static default counterparts.

Parameters:

out	The ostream for listing output.

Lister ( const Lister & lister )

Copy constructor.

Parameters:

lister The Lister to be copied.

Member Function Documentation

Lister& mode	(	const MODE	selection,
		const bool	enabled,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		`[inline]`

Sets the state of a mode.

Parameters:

selection	The selected MODE.
enabled	The new state of the selected mode.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

References Lister::Default_Modes, Lister::LOCAL_MODE_SET, and Lister::Modes.

Referenced by Lister::array_indenting(), Lister::assign_align(), Lister::begin_aggregates(), Lister::name_end_aggregates(), Lister::single_line_comments(), Lister::uppercase_aggregates(), Lister::use_statement_delimiter(), and Lister::verbatim_strings().

static void default_mode	(	const MODE	selection,
		const bool	enabled
	)		`[inline, static]`

Convenience function for static setting of default modes.

References Lister::Default_Modes.

bool mode	(	const MODE	selection,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		const `[inline]`

Gets the state of a mode.

Parameters:

selection	The selected MODE.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: The state of the selected mode.

References Lister::Default_Modes, Lister::LOCAL_MODE_SET, and Lister::Modes.

static bool default_mode ( const MODE selection ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Default_Modes.

const bool* modes ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Gets the array of syntax mode states.

The mode states is an array of TOTAL_MODES bool values. The mode that each state represents is reflected in the MODE enum list.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: A pointer to the array of mode states. N.B.: The pointer only remains valid for the life of the Lister object from which it is obtained.

References Lister::Default_Modes, Lister::LOCAL_MODE_SET, and Lister::Modes.

Lister& modes	(	const bool *	mode_set,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)

Sets the state of all syntax modes.

Parameters:

mode_set	A pointer to an array of syntax modes. If NULL the modes will all be reset to their defaults.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

Lister& begin_aggregates	(	const bool	enabled,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		`[inline]`

Enable or disable the BEGIN annotation for Aggregates.

When enabled, a "BEGIN_" annotation will be written immediately preceeding the "GROUP" or "OBJECT" type_name that introduces an Aggregate when it is written.

Parameters:

enabled	true if the mode is enabled; false if disabled.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

References Lister::Begin_Aggregates, and Lister::mode().

static void default_begin_aggregates ( const bool enabled ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Begin_Aggregates, and Lister::Default_Modes.

bool begin_aggregates ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Test if the BEGIN annotation for Aggregates is enabled.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if the mode is enabled; false if disabled.

See also:: BEGIN_aggregate(bool, const Which_Mode&)

References Lister::Begin_Aggregates, and Lister::mode().

static bool default_begin_aggregates ( ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Begin_Aggregates, and Lister::Default_Modes.

Lister& uppercase_aggregates	(	const bool	enabled,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		`[inline]`

Enable or disable uppercase of Aggregate identifiers.

When enabled, the "GROUP" or "OBJECT" type_name, and its corresponding "END_GROUP" or "END_OBJECT", identifiers that start and end an Aggregate will be written in uppercase (this applies to the optional "BEGIN" prefix); otherwise they will be inital-capped (e.g. "Begin_Object").

Parameters:

enabled	true if the mode is enabled; false if disabled.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

See also:: BEGIN_aggregates(bool, const Which_Mode&)

References Lister::mode(), and Lister::Uppercase_Aggregates.

static void default_uppercase_aggregates ( const bool enabled ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Default_Modes, and Lister::Uppercase_Aggregates.

bool uppercase_aggregates ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Test if the uppercase of Aggregate identifiers is enabled.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if the mode is enabled; false if disabled.

See also:: Uppercase_aggregates(bool, const Which_Mode&)

References Lister::mode(), and Lister::Uppercase_Aggregates.

static bool default_uppercase_aggregates ( ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Default_Modes, and Lister::Uppercase_Aggregates.

Lister& name_end_aggregates	(	const bool	enabled,
		const Which_Mode	which = `LOCAL_MODE_SET`
	)		`[inline]`

Enable or disable the use of the Aggregate name in its end identifier.

When enabled, an "End_OBJECT" or "END_GROUP" identifier will have the name of the Aggregate written after it separated by a Parser::PARAMETER_NAME_DELIMITER surrounded by space (' ') characters.

Parameters:

enabled	true if the mode is enabled; false if disabled.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

References Lister::mode(), and Lister::Name_End_Aggregates.

static void default_name_end_aggregates ( const bool enabled ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Default_Modes, and Lister::Name_End_Aggregates.

bool name_end_aggregates ( const Which_Mode which = LOCAL_MODE_SET ) const [inline]

Test if the use of the Aggregate name in its end identifier is enabled.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if the mode is enabled; false if disabled.

See also:: BEGIN_aggregate(bool)

References Lister::mode(), and Lister::Name_End_Aggregates.

static bool default_name_end_aggregates ( ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Default_Modes, and Lister::Name_End_Aggregates.

Lister& assign_align	(	const bool	enabled,
		const Which_Mode	which = `LOCAL_MODE_SET`
	)		`[inline]`

Enable or disable Assignment alignment.

When enabled, each Assignment of an Aggregate has its Parser::PARAMETER_NAME_DELIMITER aligned horizontally so they all appear at the same line location. In addition, the Value's wrap_depth is set to the same location plus two (to allow for the following space character).

N.B.: This mode has no effect if indenting is not in effect.

N.B.: The array_indenting mode is effectively disabled (though not reset) when Assignment alignment is enabled.

Parameters:

enabled	true if the mode is enabled; false if disabled.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

See also:: write(const Assignement&, int); indent_width(int, const Which_Mode&)

References Lister::Assign_Align, and Lister::mode().

static void default_assign_align ( const bool enabled ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Assign_Align, and Lister::Default_Modes.

bool assign_align ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Test if Assignment alignment is enabled.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if the mode is enabled; false if disabled.

See also:: BEGIN_aggregate(bool)

References Lister::Assign_Align, and Lister::mode().

static bool default_assign_align ( ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Assign_Align, and Lister::Default_Modes.

Lister& array_indenting	(	const bool	enabled,
		const Which_Mode	which = `LOCAL_MODE_SET`
	)		`[inline]`

Enable or disable indenting of Assignment Array Values.

When enabled, an Assignment with an Array Value begins on a new line with its indent depth incremented by one level, unless indenting in general has been disabled. However, if the Assignment being written has its indenting mode disabled, then no Array indenting will be applied.

Parameters:

enabled	true if the mode is enabled; false if disabled.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

See also:: write(const Assignement&, int); indent_width(int, const Which_Mode&)

References Lister::Array_Indenting, and Lister::mode().

static void default_array_indenting ( const bool enabled ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Array_Indenting, and Lister::Default_Modes.

bool array_indenting ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Test if indenting of Array Values is enabled.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if the mode is enabled; false if disabled.

See also:: BEGIN_aggregate(bool)

References Lister::Array_Indenting, and Lister::mode().

static bool default_array_indenting ( ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Array_Indenting, and Lister::Default_Modes.

Lister& use_statement_delimiter	(	const bool	enabled,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		`[inline]`

Enable or disable the use of the statement end delimiter.

The Parser::STATEMENT_END_DELIMITER will be written as the last character of each PVL statement, immediately preceeding a new-line sequence, when enabled.

Parameters:

enabled	true if the mode is enabled; false if disabled.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

References Lister::mode(), and Lister::Use_Statement_Delimiter.

static void default_use_statement_delimiter ( const bool enabled ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Default_Modes, and Lister::Use_Statement_Delimiter.

bool use_statement_delimiter ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Test if the statement end delimiter character will be used.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if the mode is enabled; false if disabled.

See also:: use_statement_delimiter(bool, const Which_Mode&)

References Lister::mode(), and Lister::Use_Statement_Delimiter.

static bool default_use_statement_delimiter ( ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Default_Modes, and Lister::Use_Statement_Delimiter.

Lister& single_line_comments	(	const bool	enabled,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		`[inline]`

Enable or disable single line comments.

Parameters:

enabled	true if the mode is enabled; false if disabled.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

See also:: write_comment(const std::string&, int)

References Lister::mode(), and Lister::Single_Line_Comments.

static void default_single_line_comments ( const bool enabled ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Default_Modes, and Lister::Single_Line_Comments.

bool single_line_comments ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Test if single line comments will be used.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if the mode is enabled; false if disabled.

See also:: single_line_comments_default(bool)

References Lister::mode(), and Lister::Single_Line_Comments.

static bool default_single_line_comments ( ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Default_Modes, and Lister::Single_Line_Comments.

Lister& verbatim_strings	(	const bool	enabled,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		`[inline]`

Enable or disable verbatim quoted strings.

When disabled (the default initial condition) 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 Parameter's write method:

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

When enabled all string values written as-is.

Parameters:

enabled	true if the mode is enabled; false if disabled.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

References Lister::mode(), and Lister::Verbatim_Strings.

static void default_verbatim_strings ( const bool enabled ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Default_Modes, and Lister::Verbatim_Strings.

bool verbatim_strings ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Test if quoted strings will be written verbatim.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if the mode is enabled; false if disabled.

See also:: verbatim_strings_default(bool, const Which_Mode&)

References Lister::mode(), and Lister::Verbatim_Strings.

static bool default_verbatim_strings ( ) [inline, static]

Convenience function for static testing of default modes.

References Lister::Default_Modes, and Lister::Verbatim_Strings.

Lister& strict	(	const bool	enabled,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)

Enables or disables strict PVL syntax rules.

Strict mode enables all syntax modes, uses the strict_NL characters for the new-line sequence, and uses space characters for indenting.

Informal mode disables all syntax modes and uses the informal_NL characters for the new-line sequence.

Parameters:

enabled	true if strict rules are applied; false otherwise.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

See also:: NL(bool); informal_NL(bool, const Which_Mode&)

static void default_strict ( const bool enabled ) [static]

Convenience function for static setting of default modes.

bool strict ( const Which_Mode & which = LOCAL_MODE_SET ) const

Test if strict PVL syntax rules will be enforced.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: true if strict syntax rules will be enforced; false otherwise.

static bool default_strict ( ) [static]

Convenience function for static testing of default modes.

Lister& NL	(	const char *	new_line_characters,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)

Sets the new-line (end-of-line) character sequence.

If strict is true, the strict_NL characters are reset to the new-line sequence; otherwise the informal_NL characters are set.

Parameters:

new_line_characters	A pointer to the new end-of-line characters.
which	If DEFAULT_MODE_SET, use the Default_Modes; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

See also:: strict_default(bool)

static void default_NL ( const char * new_line_characters ) [static]

Convenience function for static setting of default modes.

const char* NL ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Gets the new-line (end-of-line) character sequence.

Parameters:

which If DEFAULT_MODE_SET, use the Default_New_Line; if LOCAL_MODE_SET use the local Modes.

Returns:: A char pointer to the new-line character sequence. This will be the strict_NL characters unless strict mode is not in effect, in which case it will be the informal_NL sequence.

See also:: strict(bool)

References Lister::Default_New_Line, Lister::LOCAL_MODE_SET, and Lister::New_Line.

static const char* default_NL ( ) [inline, static]

Convenience function for static getting of default values.

References Lister::Default_New_Line.

Lister& informal_NL	(	const char *	new_line_characters,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)

Sets the informal (strict = false) new-line character sequence.

If strict is false, the NL characters are reset to the new sequence.

Parameters:

new_line_characters	A pointer to the new end-of-line characters.
which	If DEFAULT_MODE_SET, use the Default_Informal_NL_Characters; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

See also:: strict(bool)

const char* informal_NL ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Gets the informal (strict = false) new-line character sequence.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Informal_NL_Characters; if LOCAL_MODE_SET use the local Modes.

Returns:: The informal end-of-line characters.

See also:: strict(bool)

References Lister::Default_Informal_NL_Characters, Lister::Informal_NL_Characters, and Lister::LOCAL_MODE_SET.

const char* strict_NL ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Gets the strict (strict = true) new-line character sequence.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Strict_NL_Characters; if LOCAL_MODE_SET use the local Modes.

Returns:: The strict end-of-line characters.

See also:: strict(bool)

References Lister::Default_Strict_NL_Characters, Lister::LOCAL_MODE_SET, and Lister::Strict_NL_Characters.

Lister& strict_NL	(	const char *	new_line_characters,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)

Sets the strict (strict = true) new-line character sequence.

If strict is true, the NL characters are reset to the new sequence.

Parameters:

new_line_characters	A pointer to the new strict end-of-line characters.
which	If DEFAULT_MODE_SET, use the Default_Strict_NL_Characters; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

See also:: strict(bool)

Lister& page_width	(	const int	width,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		`[inline]`

Sets the page width.

Each PVL statement will be wrapped by replacing the Parser::WHITESPACE sequence preceding the page width minus the NL width with the NL character sequence. If there is no whitespace preceding the maximum page width, then the wrap will occur at the next whitespace sequence, if any.

Parameters:

width	The width of the listing in characters. If this value is negative no line wrapping will occur.
which	If DEFAULT_MODE_SET, use the Default_Page_Width; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

References Lister::Default_Page_Width, Lister::LOCAL_MODE_SET, and Lister::Page_Width.

static void default_page_width ( const int width ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Default_Page_Width.

int page_width ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Gets the page width.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Page_Width; if LOCAL_MODE_SET use the local Modes.

Returns:: The width of a page at which line wrapping is to occur.

References Lister::Default_Page_Width, Lister::LOCAL_MODE_SET, and Lister::Page_Width.

static int default_page_width ( ) [inline, static]

Convenience function for static getting of default values.

References Lister::Default_Page_Width.

Lister& indent_width	(	const int	width,
		const Which_Mode &	which = `LOCAL_MODE_SET`
	)		`[inline]`

Sets the indenting width.

N.B.: Use a width of NO_INDENT to disable all indenting.

Parameters:

width	The number of indenting characters per indent level.
which	If DEFAULT_MODE_SET, use the Default_Indent_Width; if LOCAL_MODE_SET use the local Modes.

Returns:: This Lister.

References Lister::Default_Indent_Width, Lister::Indent_Width, and Lister::LOCAL_MODE_SET.

static void default_indent_width ( const int width ) [inline, static]

Convenience function for static setting of default modes.

References Lister::Default_Indent_Width.

int indent_width ( const Which_Mode & which = LOCAL_MODE_SET ) const [inline]

Gets the indenting width.

Parameters:

which If DEFAULT_MODE_SET, use the Default_Indent_Width; if LOCAL_MODE_SET use the local Modes.

Returns:: The number of indent characters per indent level.

References Lister::Default_Indent_Width, Lister::Indent_Width, and Lister::LOCAL_MODE_SET.

static int default_indent_width ( ) [inline, static]

Convenience function for static getting of default values.

References Lister::Default_Indent_Width.

unsigned int indent_depth ( int level ) const

Calculates the character depth of an indent level.

The depth of an indent level is the indent level times the indent_width, but never less than zero. So even if the indent_width has been set to a negative value the indent depth will always be zero regardless of the indent level.

Parameters:

level The indent level.

Returns:: The character depth of the indent level.

bool indenting ( ) const [inline]

Tests if indenting is enabled.

References Lister::Indent_Width, and Lister::NO_INDENT.

Lister& output_stream ( std::ostream & out ) [inline]

Sets the output stream.

Parameters:

out	The ostream where output will be written.

Returns:: This Lister.

std::ostream& output_stream ( ) const [inline]

Gets the output stream.

Returns:: The ostream where output will be written.

Lister& write	(	const std::string &	characters,
		int	wrap_depth = `0`
	)

Writes characters.

Parameters:

characters	A string of characters to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

Referenced by Lister::operator<<().

Lister& write	(	const char	character,
		int	wrap_depth = `0`
	)

Writes a character.

Parameters:

character	A character to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

Lister& indent ( int depth )

Writes indenting characters.

If indenting is disabled, or the depth is not positive, nothing is written.

Parameters:

depth The number of space (' ') characters to write.

Returns:: This Lister.

See also:: indent_depth(int)

Lister& new_line ( int wrap_depth = 0 )

Adds an end-of-line marker to the characters pending output, which results in them being flushed to the output stream.

Parameters:

wrap_depth The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: pending_characters(); flush(); output_stream()

unsigned int total ( ) const [inline]

Gets the total number of characters written.

Returns:: The total number of characters sent to the output stream since this Lister was constructed or the toal was reset. N.B.: Any buffered characters pending output are not counted.

Lister& reset_total ( ) [inline]

Resets the count of total characters output to zero.

Returns:: This Lister.

See also:: total()

unsigned int pending ( ) const [inline]

Gets the number of buffered characters pending output.

Returns:: The number of characters buffered for output.

See also:: pending_characters()

std::string pending_characters ( ) const [inline]

Gets the characters pending output.

Returns:: A string containing a copy of currently buffered characters.

See also:: pending()

Lister& write	(	const Parameter &	parameter,
		int	wrap_depth = `0`
	)

Writes a Parameter.

Parameters:

parameter	The Parameter to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: write(const Assignment&, int); write(const Aggregate&, int)

std::ostream& operator<< ( const Parameter & parameter ) [inline]

Writes a Parameter.

Parameters:

parameter The Parameter to be written.

Returns:: The output stream of this Lister.

See also:: write(const Parameter&, int)

References Lister::write().

Lister& write	(	const Assignment &	assignment,
		int	wrap_depth = `0`
	)

Writes an Assignment.

The PVL syntax that is written follows this pattern:

Comment
Name = Value

The comment string, if there is one, is written by the write_comment method.

The parameter_name is written on the next line indented by the wrap_depth. N.B.: An Assignment indents itself.

The Parameter's Value is written next, if the Parameter is not a TOKEN. It is preceeded by the Parser::PARAMETER_NAME_DELIMITER name delimiter character surrounded by space characters. The Value write method is used to produce its PVL syntax representation.

For Assignments with an Array Value, if the Assignment's indenting, this Lister indenting, and array_indenting are enabled and the wrap_depth is positive then each Array, including elements of the Array that are themselves an Array, will be written on a new line and have their wrap_depth incremented by one indent level. However, if array_indenting is disabled then the top level Array will be written on the same line as the Assignment and any contained Array elements will inherit all the other indenting modes; this includes the Assignment's indenting mode which, if disabled, overrides a positive wrap_depth causing all Array indenting to be disabled.

The Parameter line is completed by writing a new_line sequence. However, if strict PVL has been specified, then the PVL Parser::STATEMENT_END_DELIMITER character preceeds the end of line.

N.B.: A new_line is written last.

Parameters:

assignment	The Assignment to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: write_comment(const std::string&, int); parameter_name(std::string, bool); write(const Value&, int)

Lister& write	(	const Aggregate &	aggregate,
		int	wrap_depth = `0`
	)

Writes an Aggregate.

The PVL syntax that is written follows this pattern:

Comment
Type = Name
Parameter
...

The comment string, if there is one, is written by the write_comment method.

The Aggregate's type_name is written on the next line indented by the wrap_depth. N.B.: An Aggregate indents itself. If begin_aggregates is enabled the type name will be prepended with "Begin_". If uppercase_aggregates is enabled the entire identifier will be written in uppercase.

The Parameter's name is written next after the Parser::PARAMETER_NAME_DELIMITER character surrounded by space characters. 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 Parser::WHITESPACE or Parser::RESERVED_CHARACTERS or is empty then it will be quoted (with Parser::TEXT_DELIMITER characters).

The Aggregate identification line is completed by writing a new_line sequence. However, if use_statement_delimiter is enabled the PVL Parser::STATEMENT_END_DELIMITER character preceeds the end of line.

Note: In the special case of an Aggregate used as a container for all of the Parameters read from a file (or a string defining multiple Parameters), the Aggregate identification is not written because it is only an artifact needed to contain the Parameter collection. This case is identified as an Aggregate named with the special Parser::CONTAINER_NAME.

The Parameter list follows. If indenting is enabled the wrap_depth is incremented by one indent level and then each Parameter in the list is writen. This will recursively write any Aggregates in the Parameter list.

At the end of the Parameter list, after decrementing any indenting, the Aggregate identification line will be repeated but with "End_" always used where "Begin_" would have been used (regardless of whether it was used or not).

For the special Parser::CONTAINER_NAME Aggregate an additional line containing just "END" (and the Parser::STATEMENT_END_DELIMITER when enabled) will be added to mark the end of the entire PVL sequence. Note: to turn a special container Aggregate into a regular Aggregate, just change its name; or vice versa.

Parameters:

aggregate	The Aggregate to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: write_comment(const std::string&, int); parameter_name(const std::string, bool); write (const Value&, int)

Lister& write_comment	(	const std::string &	comment,
		int	depth = `0`
	)

Writes a comment.

A comment is preceeded by a Parser::COMMENT_START_DELIMITERS sequence. A single space character is added if the comment does not start with a space or horizonatal tab character. The comment is followed by aParser::COMMENT_END_DELIMITERS sequence. This is preceded by a single space if the comment does not end with a space or tab charater.

When single_line_comments mode is in effect, each line of the comment string is enclosed in comment delimiters.

Comment lines - sections of the comment string terminated with an end-of-line ('\n') character - are each written on their own line, depth indented. The end of the comment string is implicitly an end-of-line, except if the depth is negative for in-line comments. Empty comment lines produce blank output lines; empty lines at the beginning of the string produce blank lines before the first Parser::COMMENT_START_DELIMITERS. sequence and empty lines at the end of the string produce blank lines after the last Parser::COMMENT_END_DELIMITERS sequence. For example, a single '\n' character at the end of the string will produce one blank line after the end of the comment.

Parameters:

comment	The comment string to be written.
depth	The indent depth for all lines. Use a negative depth for in-line comments.

Returns:: This Lister.

int parameter_name	(	const std::string &	name,
		bool	verbatim = `false`
	)

Writes a Parameter name.

If verbatim_strings is true special characters (such as non-printing characters) are translated to escape sequences.

The name is quoted with Parser::TEXT_DELIMITER characters if it is empty or contains characters otherwise reserved for the PVL syntax.

Parameters:

name	The name string to be written.
verbatim	Flag for verbatim treatment of characters.

Returns:: The length of the name written.

Exceptions:

Invalid_Syntax	If the Parameter name is empty in verbatim mode.
Reserved_Character	If the Parameter name contains any Parser::RESERVED_CHARACTERS in verbatim mode.

See also:: idaeim::PVL::translate_to_escape_sequences(std::string); verbatim_strings(const Which_Mode&)

Lister& write	(	const Value &	value,
		int	wrap_depth = `0`
	)

Writes a Value.

Parameters:

value	The Value to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: write(Integer&, int); write(Real&, int); write(String&, int); write(Array&, int)

std::ostream& operator<< ( const Value & value ) [inline]

Writes a Value.

The Value representation is written and flushed to the output stream of this Lister.

Parameters:

value The Value to be written.

Returns:: The output stream of this Lister.

See also:: write(const Value&, int)

References Lister::flush(), and Lister::write().

Lister& write	(	const Integer &	integer,
		int	wrap_depth = `0`
	)

Writes an Integer Value.

The integer representation is written in its base (radix) notation with at least the number of digits specified for the Value. If the base is not decimal, then the base value in decimal, followed by a Parser::NUMBER_BASE_DELIMITER, will preceed the integer representation, which will then be followed by another Parser::NUMBER_BASE_DELIMITER:

base#integer#

N.B.: If the number of digits for the Value is greater than the number of digits required to represent the integer in its base notation, then the value will be padded with leading zeros.

The units string, if any, will then be written.

Parameters:

integer	The Ingeter to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: Value::base(); Value::units(); value_units(const std::string)

Lister& write	(	const Real &	real,
		int	wrap_depth = `0`
	)

Writes a Real Value.

The real number representation is written using its format flags to control syntax with at least the Value's digits of precision.

The units string, if any, will then be written.

Parameters:

real	The Real to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: Value::units(); value_units(const std::string)

Lister& write	(	const String &	text,
		int	wrap_depth = `0`
	)

Writes a String Value.

If the String is a TEXT or SYMBOL Type then it will be quoted with either Parser::TEXT_DELIMITER or Parser::SYMBOL_DELIMITER characters, respectively.

The units string, if any, will then be written.

Parameters:

text	The String to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: Value::units(); value_units(const std::string)

Lister& write	(	const Array &	array,
		int	wrap_depth = `0`
	)

Writes an Array Value.

Each Value of the Array is written separated by a Parser::PARAMETER_VALUE_DELIMITER and space (' '). Arrays of Type SET are enclosed in a Parser::SET_START_DELIMITER and Parser::SET_END_DELIMITER, while those of Type SEQUENCE SEQUENCE are enclosed in a Parser::SEQUENCE_START_DELIMITER and Parser::SEQUENCE_END_DELIMITER.

When indenting is true and the wrap_depth is positive each element Value that is itself an Array will be started on a new line with its indent depth incremented by one level. When the wrap_depth is negative and not NO_INDENT then indenting of subarrays will not occur, but the effective wrap depth will be set to -wrap_depth - 2; this special value is used when writing an Assignment of an Array when indenting is enabled but the Assignment's indenting has been disabled.

The units string, if any, will be written after the closing Array delimiter.

Parameters:

array	The Array to be written.
wrap_depth	The indent depth for any wrapped lines.

Returns:: This Lister.

See also:: write(const Value&, int); Value::units(); value_units(const std::string)

Lister& value_units ( const Value & value )

Writes a units string for a Value.

The units string of the Value is written. However, if the units string is empty and the Value is a member of an Array, then the value_units of the parent Array will be used. The effect is to write the "nearest" non-empty units string.

Parameters:

value The Value to have its units written.

Returns:: This Lister.

See also:: value_units(const std::string&)

Lister& value_units ( const std::string & units )

Writes a Value units string.

If the units is not empty a space (' ') character followed by the Parser::UNITS_START_DELIMITER character preceeds the string, and a Parser::UNITS_END_DELIMITER character follows it.

Parameters:

units The units string to be written.

Returns:: This Lister.

unsigned int write	(	int	wrap_to = `0`,
		const std::string &	leading = `""`,
		const std::string &	trailing = `""`
	)

Writes any pending characters on the output stream of this Lister.

Each line of the characters - where a line is terminated by a '\n' character (which is replaced with a NL sequence) - is wrapped to the page_width into multiple output lines. A line longer than the maximum page width minus the width of the trailing string plus NL sequence - the wrap point - is broken into multiple lines by replacing the last sequence of Parser::WHITESPACE characters preceeding the wrap point with the trailing string and then NL sequence. This line is written to the output stream.

N.B.: When a string continuation delimiter character ('-') falls at the end of a line, immediately preceding a NL, in a quoted PVL string the Parser will remove the delimiter character and all surrounding whitespace from the string (unless string continutation mode is disabled). Since the delimiter is contained in the string being listed it is clearly not the intention that the character be removed by a subsequent parsing of the PVL. To elide this gotcha the first whitespace character (forced to be a space character) following a string delimiter character that would fall at the end of a line is retained.

If the whitespace preceeding the wrap point starts at the beginning of the line, then all the leading whitespace is removed and the line wrap is tried again; this effectively wraps a line beginning with a word that is at or beyond the wrap point to the beginning of the line. If whitespace can not be found before the wrap point then the break will occur at the first whitespace that occurs in the line.

Each wrapped line section - not the first section of a line - is preceeded by wrap_to space (' ') characters and then the leading string. Each wrapped line section is itself wrapped.

N.B.: If the characters string does not end with a '\n' none will be provided, but this unterminated line will still be output.

Parameters:

wrap_to	The number of spaces to preceed wrapped lines.
leading	A string to preceed each wrapped line (after any wrap_to spaces).
trailing	A string to follow each wrapped line.

Returns:: The number of characters written.

See also:: pending_characters(); output_stream()

unsigned int flush ( int wrap_depth = 0 )

Flushes any pending characters to the output stream of this Lister.

WARNING: All characters, including those not terminated by an end-of-line, so that subsequent write operations may result in apparently improper line wrapping.

Parameters:

wrap_depth The indent depth for any wrapped lines.