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 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 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 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 errorneous "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 Declaration::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 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 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.

Collaboration diagram for alib::enumrecords::bootstrap::EnumRecordParser:

[legend]

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

static ALIB_DLL Substring	Input
	The remaining input string.

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

static ALIB_DLL character	OuterDelimChar
	The delimiter of records.

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

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

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

static ALIB_DLL void	assertEndOfInput ()

static ALIB_DLL void	assertEndOfRecord ()

static ALIB_DLL void	assertNoTrailingWhitespaces (String &token)

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

static ALIB_DLL void	assertNoWhitespaces (const NCString &where)

static ALIB_DLL void	Delim ()

static ALIB_DLL void	error (const NCString &what)

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

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

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

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

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

static ALIB_DLL integer	getInteger (bool isLastField)

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

static ALIB_DLL void	OuterDelim ()

Field Details:

◆ InnerDelimChar

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

static

The delimiter of fields of a record.

Definition at line 66 of file recordparser.inl.

◆ Input

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

static

The remaining input string.

Definition at line 63 of file recordparser.inl.

◆ OriginalInput

ALIB_DLL 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

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

static

The delimiter of records.

Definition at line 69 of file recordparser.inl.

◆ ResourceCategory

ALIB_DLL 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

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

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

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

static

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

◆ assertEndOfRecord()

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

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

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

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

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

static

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

◆ error()

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

Here is the call graph for this function:

◆ Get() [1/5]

ALIB_DLL 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]

ALIB_DLL 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]

ALIB_DLL 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>
requires std::is_enum_v<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 208 of file recordparser.inl.

Here is the call graph for this function:

◆ Get() [5/5]

template<typename TIntegral>
requires std::integral<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 186 of file recordparser.inl.

Here is the call graph for this function:

◆ getInteger()

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

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

Here is the call graph for this function:

◆ OuterDelim()

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