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 void 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 software process, where no multi-threading is active, yet.

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

ALib

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 erroneous maintenance of externalized resources, and such should be detected as soon as possible.

The main interface into this class is given with the overloaded methods Get. 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 the method

Note: This is the only occasion where any ALib module throws an exception of type std. If (in presence of the module ALib Exceptions) 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 the English language and are not externalized. An end user will not be faced with these exceptions unless an erroneous "roll-out" of software using malicious externalized resources was performed.{enumrecords;EnumRecordPrototype::Parse}. For the last field, the optional parameter isLastField has to be given as true4. As an example, the following code shows the implementation of void Parse() :
void Declaration::Parse() {

enumrecords::bootstrap::EnumRecordParser::Get( ERSerializable::EnumElementName ); // field from parent class

ERSerializable::MinimumRecognitionLength= 0; // omit reading, but fix to zero

enumrecords::bootstrap::EnumRecordParser::Get( typeName , true ); // last field!

}

This parse method omits reading the value for inherited field int 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 deserialization forcing the whole string to read is acceptable. Note that it is still 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 60 of file recordparser.inl.

Public Static Field Index:
static character	InnerDelimChar
	The delimiter of fields of a record.
static Substring	Input
	The remaining input string.
static String	OriginalInput
	A backup of the originally given string to parse.
static character	OuterDelimChar
	The delimiter of records.
static NString	ResourceCategory
	The resource category (if a resourced string was parsed).
static NString	ResourceName
	The resource name (if a resourced string was parsed).

Public Static Method Index:
static void	assertChar (character specificChar, const NCString &where)
static void	assertEndOfInput ()
static void	assertEndOfRecord ()
static void	assertNoTrailingWhitespaces (String &token)
static void	assertNoUnnecessary (character specificChar, const NCString &where)
static void	assertNoWhitespaces (const NCString &where)
static void	Delim ()
static void	error (const NCString &what)
static void	Get (character &result, bool isLastField=false)
static void	Get (double &result, bool isLastField=false)
static 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 integer	getInteger (bool isLastField)
static void	Initialize (const String &input, character innerDelim, character outerDelim, const NString &resourceCategory, const NString &resourceName)
static void	OuterDelim ()

Field Details:

◆ InnerDelimChar

character alib::enumrecords::bootstrap::EnumRecordParser::InnerDelimChar

static

The delimiter of fields of a record.

Definition at line 66 of file recordparser.inl.

◆ Input

Substring alib::enumrecords::bootstrap::EnumRecordParser::Input

static

The remaining input string.

Definition at line 63 of file recordparser.inl.

◆ OriginalInput

String alib::enumrecords::bootstrap::EnumRecordParser::OriginalInput

static

A backup of the originally given string to parse.

Definition at line 72 of file recordparser.inl.

◆ OuterDelimChar

character alib::enumrecords::bootstrap::EnumRecordParser::OuterDelimChar

static

The delimiter of records.

Definition at line 69 of file recordparser.inl.

◆ ResourceCategory

NString alib::enumrecords::bootstrap::EnumRecordParser::ResourceCategory

static

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

Definition at line 75 of file recordparser.inl.

◆ ResourceName

NString alib::enumrecords::bootstrap::EnumRecordParser::ResourceName

static

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

Definition at line 78 of file recordparser.inl.

Method Details:

◆ assertChar()

void alib::enumrecords::bootstrap::EnumRecordParser::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.

◆ assertEndOfInput()

void alib::enumrecords::bootstrap::EnumRecordParser::assertEndOfInput ( )

static

Asserts that the Input is empty. Throws a std::runtime_error in case.

◆ assertEndOfRecord()

void alib::enumrecords::bootstrap::EnumRecordParser::assertEndOfRecord ( )

static

Asserts that either Input is empty, or an OuterDelimChar follows. Throws a std::runtime_error in case.

◆ assertNoTrailingWhitespaces()

void alib::enumrecords::bootstrap::EnumRecordParser::assertNoTrailingWhitespaces ( String & token )

static

Asserts that no trailing whitespaces are in token. Throws a std::runtime_error in case.

Parameters

token The string to test for trailing whitespaces.

◆ assertNoUnnecessary()

void alib::enumrecords::bootstrap::EnumRecordParser::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. Throws a std::runtime_error in case.

Parameters

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

◆ assertNoWhitespaces()

void alib::enumrecords::bootstrap::EnumRecordParser::assertNoWhitespaces ( const NCString & where )

static

Asserts that no whitespaces follow in input. Throws a std::runtime_error in case.

Parameters

where Textual description about what is currently done.

◆ Delim()

void alib::enumrecords::bootstrap::EnumRecordParser::Delim ( )

static

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

◆ error()

void alib::enumrecords::bootstrap::EnumRecordParser::error ( const NCString & what )

static

Throws a std::runtime_error.

Parameters

what	Textual description about what has been tried to do.

◆ Get() [1/5]

void alib::enumrecords::bootstrap::EnumRecordParser::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]

void alib::enumrecords::bootstrap::EnumRecordParser::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]

void alib::enumrecords::bootstrap::EnumRecordParser::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>

void alib::enumrecords::bootstrap::EnumRecordParser::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`.

Definition at line 204 of file recordparser.inl.

◆ Get() [5/5]

template<typename TIntegral>

void alib::enumrecords::bootstrap::EnumRecordParser::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`.

Definition at line 183 of file recordparser.inl.

◆ getInteger()

integer alib::enumrecords::bootstrap::EnumRecordParser::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()

void alib::enumrecords::bootstrap::EnumRecordParser::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 88 of file recordparser.inl.

◆ OuterDelim()

void alib::enumrecords::bootstrap::EnumRecordParser::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.inl

Description:

Public Static Field Index:

Public Static Method Index:

Field Details:

◆ InnerDelimChar

◆ Input

◆ OriginalInput

◆ OuterDelimChar

◆ ResourceCategory

◆ ResourceName

Method Details:

◆ assertChar()

◆ assertEndOfInput()

◆ assertEndOfRecord()

◆ assertNoTrailingWhitespaces()

◆ assertNoUnnecessary()

◆ assertNoWhitespaces()

◆ Delim()

◆ error()

◆ Get() [1/5]

◆ Get() [2/5]

◆ Get() [3/5]

◆ Get() [4/5]

◆ Get() [5/5]

◆ getInteger()

◆ Initialize()

◆ OuterDelim()