Description:

This is a pure static type used for parsing enum records from strings. The static fields are initialized with each method of type EnumRecords and therefore implementations of EnumRecordPrototype::Parse can rely on finding these fields properly set.

This concept makes use of the restriction, that the setup of ALib Enum Records must exclusively be done during bootstrapping of a software process, where no multi-threading is active, yet.

If parse errors occur, a std::runtime_error is thrown.

Note: This is the only occasion where any ALib module throws an exception of type std. If (in presence of module ALib BaseCamp) an Exception was thrown, this had to be resourced likewise. The rationale for this design decision is that enum records usually are defined by potentially externalized resources. The maintenance of such resources must not lead to corrupted exceptions that are thrown when parsing those resources. Consequently, the exception messages are using english language and are not externalized. An end user will not be faced with these exception unless an errorneous "roll-out" of a software using malicious externalized resources was performed.

The methods of this type perform strict checks about unnecessary whitespaces, '+'-signs, etc, which also raise an exception. The rationale for this design decision (to not allow unnecessary, but maybe unharmful characters in resources) besides saving memory is, that the occurrence of unnecessary characters, indicates an errorneous maintenance of externalized resources, and such should be detected as soon as possible.

The main interface into this class is given with the overloaded Get methods. Enum Records are usually rather simple structs, consisting of strings, characters, integers and floating point values. If so, a simple list of invocations of Get for each field of the struct has to be placed in implementations of method EnumRecordPrototype::Parse. For the last field, optional parameter isLastField has to be given as true4. As an example, the following code shows the implementation of Declaration::Parse:

void Declaration::Parse()
{
    enums::EnumRecordParser::Get( ERSerializable::EnumElementName  );           // field from parent class
                                  ERSerializable::MinimumRecognitionLength= 0;  // omit reading, but fix to zero
    enums::EnumRecordParser::Get( typeName                            , true ); // last field!
}

This parse method omits reading the value for inherited field ERSerializable::MinimumRecognitionLength, and sets it to fixed 0 instead. This is often an option when custom enumeration record types are derived from ERSerializable but are not supposed to be deserialized or de-serialization forcing the whole string to read is acceptable. Note that it is still is possible to deserialize elements, but not with abbreviated names.

An implementation for a custom record type might perform more complex parsing operations. For this, some helper methods are publicly provided and finally, the direct use of the substring Input is likewise allowed.

Definition at line 69 of file recordparser.hpp.

#include <recordparser.hpp>

Collaboration diagram for EnumRecordParser:

[legend]

Public Static Field Index:
static ALIB_API character	InnerDelimChar
	The delimiter of fields of a record.

static ALIB_API Substring	Input
	The remaining input string.

static ALIB_API String	OriginalInput
	A backup of the originally given string to parse.

static ALIB_API character	OuterDelimChar
	The delimiter of records.

static ALIB_API NString	ResourceCategory
	The resource category (if a resourced string was parsed).

static ALIB_API NString	ResourceName
	The resource name (if a resourced string was parsed).

Public Static Method Index:
static ALIB_API void	assertChar (character specificChar, const NCString &where)

static ALIB_API void	assertEndOfInput ()
	Asserts that the Input is empty.

static ALIB_API void	assertEndOfRecord ()
	Asserts that either Input is empty, or an OuterDelimChar follows.

static ALIB_API void	assertNoTrailingWhitespaces (String &token)

static ALIB_API void	assertNoUnnecessary (character specificChar, const NCString &where)

static ALIB_API void	assertNoWhitespaces (const NCString &where)

static ALIB_API void	Delim ()

static ALIB_API void	error (const NCString &what)

static ALIB_API void	Get (character &result, bool isLastField=false)

static ALIB_API void	Get (double &result, bool isLastField=false)

static ALIB_API void	Get (String &result, bool isLastField=false)

template<typename TEnum >
static void	Get (TEnum &result, bool isLastField=false)

template<typename TIntegral >
static void	Get (TIntegral &result, bool isLastField=false)

static ALIB_API integer	getInteger (bool isLastField)

static ALIB_API void	Initialize (const String &input, character innerDelim, character outerDelim, const NString &resourceCategory, const NString &resourceName)

static ALIB_API void	OuterDelim ()

Field Details:

◆ InnerDelimChar

ALIB_API character InnerDelimChar

static

The delimiter of fields of a record.

Definition at line 75 of file recordparser.hpp.

◆ Input

ALIB_API Substring Input

static

The remaining input string.

Definition at line 72 of file recordparser.hpp.

◆ OriginalInput

ALIB_API String OriginalInput

static

A backup of the originally given string to parse.

Definition at line 81 of file recordparser.hpp.

◆ OuterDelimChar

ALIB_API character OuterDelimChar

static

The delimiter of records.

Definition at line 78 of file recordparser.hpp.

◆ ResourceCategory

ALIB_API NString ResourceCategory

static

The resource category (if a resourced string was parsed).

Definition at line 84 of file recordparser.hpp.

◆ ResourceName

ALIB_API NString ResourceName

static

The resource name (if a resourced string was parsed).

Definition at line 87 of file recordparser.hpp.

Method Details:

◆ assertChar()

static ALIB_API void assertChar	(	character	specificChar,
		const NCString &	where )

static

Asserts that either specificChar follows. The character will also be consumed.

Parameters

specificChar	The character to consume next.
where	Textual description about what is currently done.

◆ assertNoTrailingWhitespaces()

static ALIB_API void assertNoTrailingWhitespaces ( String & token )

static

Asserts that no trailing whitespaces are in token.

Parameters

token The string to test for trailing whitespaces.

◆ assertNoUnnecessary()

static ALIB_API void assertNoUnnecessary	(	character	specificChar,
		const NCString &	where )

static

Asserts that a specific redundant character is not given, for example a leading '+' sign for an integral value.

Parameters

specificChar	The character to check.
where	Textual description about what is currently done.

◆ assertNoWhitespaces()

static ALIB_API void assertNoWhitespaces ( const NCString & where )

static

Asserts that no whitespaces follow in input.

Parameters

where Textual description about what is currently done.

◆ Delim()

static ALIB_API void Delim ( )

static

Removes an InnerDelimChar. The Input is checked for not containing whitespaces before or after the delimiter.

◆ error()

static ALIB_API void error ( const NCString & what )

static

Raises an error.

Parameters

what	Textual description about what has been tried to do.

◆ Get() [1/5]

static ALIB_API void Get	(	character &	result,
		bool	isLastField = false )

static

Parses a field of character type.

Parameters

result	A reference to the record's field to be read.
isLastField	Has to be given as `true`, if this is the last field to parse. Defaults to `false`.

◆ Get() [2/5]

static ALIB_API void Get	(	double &	result,
		bool	isLastField = false )

static

Parses the next floating point field of a record. Accepts '-' signs, while '+' is considered an unnecessary token. Furthermore asserts that at least one digit was parsed.

Parameters

result	A reference to the record's field to be read.
isLastField	Has to be given as `true`, if this is the last field to parse. Defaults to `false`.

◆ Get() [3/5]

static ALIB_API void Get	(	String &	result,
		bool	isLastField = false )

static

Parses a field of string-type. Parsing ends with an InnerDelimChar. The string is checked for not containing leading or trailing whitespaces.

Parameters

result	A reference to the record's field to be read.
isLastField	Has to be given as `true`, if this is the last field to parse. Defaults to `false`.

◆ Get() [4/5]

template<typename TEnum >

static void Get	(	TEnum &	result,
		bool	isLastField = false )

inlinestatic

Parses an enumeration element value, which has to be given in the source string by its underlying integral value. (It is not possible to parse "named" enumerations in bootstrapping, yet.)

Note: This method uses Get(TIntegral&, bool) to read the value and thus special values min, max and ^N are allowed

Template Parameters

TEnum The enum type to parse an element from.

Parameters

result	A reference to the integer variable to parse.
isLastField	Has to be given as `true`, if this is the last field to parse. Defaults to `false`.

◆ Get() [5/5]

template<typename TIntegral >

static void Get	(	TIntegral &	result,
		bool	isLastField = false )

inlinestatic

Parses an integral field of a record. Accepts '-' signs, while '+' is considered an unnecessary token. Furthermore asserts that at least one digit was parsed.

Allows special values min, max and ^N. The latter provides the power of two.

Template Parameters

TIntegral The integer type to parse. Must be statically castable from uint64_t. Deduced by the compiler.

Parameters

result	A reference to the record's field to be read.
isLastField	Has to be given as `true`, if this is the last field to parse. Defaults to `false`.

◆ getInteger()

static ALIB_API integer getInteger ( bool isLastField )

static

Used by Get(TIntegral&, bool). Reads special values min, max and ^N. The latter provides the power of two.

Parameters

isLastField Has to be given as true, if this is the last field to parse, otherwise false.

Returns: The value parsed.

◆ Initialize()

static ALIB_API void Initialize	(	const String &	input,
		character	innerDelim,
		character	outerDelim,
		const NString &	resourceCategory,
		const NString &	resourceName )

inlinestatic

Initializes this parser. This is done once before reading a resource (or static) string with enum record definitions.

Parameters

input	The input string.
innerDelim	The delimiter of fields of a record.
outerDelim	The delimiter of records.
resourceCategory	The delimiter of records.
resourceName	The delimiter of records.

Definition at line 97 of file recordparser.hpp.

Here is the call graph for this function:

◆ OuterDelim()

static ALIB_API void OuterDelim ( )

static

Removes an OuterDelimChar. The Input is checked for not containing whitespaces before or after the delimiter.

The documentation for this struct was generated from the following file:

recordparser.hpp

Description:

Public Static Field Index:

Public Static Method Index:

Field Details:

◆ InnerDelimChar

◆ Input

◆ OriginalInput

◆ OuterDelimChar

◆ ResourceCategory

◆ ResourceName

Method Details:

◆ assertChar()

◆ assertNoTrailingWhitespaces()

◆ assertNoUnnecessary()

◆ assertNoWhitespaces()

◆ Delim()

◆ error()

◆ Get() [1/5]

◆ Get() [2/5]

◆ Get() [3/5]

◆ Get() [4/5]

◆ Get() [5/5]

◆ getInteger()

◆ Initialize()

◆ OuterDelim()