Description:

A data record used to declare an ALib Configuration Variable .

All fields (except Delim) support placeholders "%1", "%2" ... "%N", which are replaced with the constructor of class Variable and method Variable::Declare. This allows to define a series of variables whose category, name, description and value is dependent on run-time information.

Objects of class Variable can be constructed and existing objects can be reused by invoking Variable::Declare. Both, construction and re-declaration of variables, use objects of this type.

While variables can also be declared by setting their attributes "manually", it is recommended to declare all external configuration variables in a central place, this type.

In this C++ implementation of ALib , this class can be created from elements of enum types. For this, the concept of ALib Enum Records is used. The record associated with an enum element used for construction must be of this type itself! Consequently, equipping enum type MyType is performed like this:

 ALIB_ENUMS_ASSIGN_RECORD( MyEnum, alib::config::VariableDecl )

Besides defining the enum record type, a custom enum has to have a specialization of type T_Resourced . The reason for this is that enum records of this type do load fields DefaultValue and Comments indirectly from resources by adding postfixes _D, respectively _C to the variable's resource name along with the variable's underlying enumeration element's integral value. This way, both values are loaded from separated resource strings, what has the following advantages:

The values may contain the separation character used.
The values can be manipulated within the (externalized) resources more easily.

With this - and the corresponding resource data! - in place, elements of custom enum type can be used to declare configuration variables by passing them to one of following constructors and methods:

The resource data has to provide six values in the following order:

The custom integral enum value (this is mandatory with every resourced enum record).
Field Category.
Base class's field ERSerializable::EnumElementName .
Note
Field ERSerializable::MinimumRecognitionLength is not read from the string, but set to fixed value 0.
Field Delim.
Field FormatAttrAlignment.
Field FmtHints.

As already noted above, fields DefaultValue and Comments can be defined in two separate resource strings named like the variable's resource itself with concatenated postfixes _D, respectively _C and the variable's underlying enumeration element's integral value. Both resources are optional and not mandatory to be existent.

A sample of variable resources is given with the documentation of class PropertyFormatter.

Definition at line 109 of file variabledecl.hpp.

#include <variabledecl.hpp>

Inheritance diagram for VariableDecl:

[legend]

Collaboration diagram for VariableDecl:

[legend]

Public Field Index:
String	Category

String	Comments

String	DefaultValue

character	Delim

FormatHints	FmtHints

String	FormatAttrAlignment

Public Field Index: inherited from ERSerializable
String	EnumElementName

int	MinimumRecognitionLength

Public Method Index:
	VariableDecl () noexcept=default

	VariableDecl (const String &category, const String &name, const String &defaultValue, character delim, const String &formatAttrAlignment, FormatHints formatHints, const String &comments)

template<typename TEnum , typename TEnableIf = void>
	VariableDecl (TEnum declaration)

ALIB_API void	Parse ()

Public Method Index: inherited from ERSerializable
	ERSerializable () noexcept=default

	ERSerializable (const String &name, int minLength=0) noexcept

ALIB_API void	Parse ()

Field Details:

◆ Category

String Category

The value for field Variable::Category .

Definition at line 115 of file variabledecl.hpp.

◆ Comments

String Comments

The value for field Variable::Comments .

Note: If TMP struct T_Resourced is specialized for an enumeration, this field is interpreted as a resource name to load the description from.

Definition at line 136 of file variabledecl.hpp.

◆ DefaultValue

String DefaultValue

The value for field Variable::DefaultValue .

Note: If TMP struct T_Resourced is specialized for an enumeration, this field is interpreted as a resource name to load the description from.

Definition at line 121 of file variabledecl.hpp.

◆ Delim

character Delim

The value for field Variable::Delim .

Definition at line 124 of file variabledecl.hpp.

◆ FmtHints

FormatHints FmtHints

The value for field Variable::FmtHints .

Definition at line 130 of file variabledecl.hpp.

◆ FormatAttrAlignment

String FormatAttrAlignment

The value for field Variable::FormatAttrAlignment .

Definition at line 127 of file variabledecl.hpp.

Constructor(s) / Destructor Details::

◆ VariableDecl() [1/3]

VariableDecl ( )

defaultnoexcept

Defaulted constructor leaving the declaration undefined.

◆ VariableDecl() [2/3]

VariableDecl	(	const String &	category,
		const String &	name,
		const String &	defaultValue,
		character	delim,
		const String &	formatAttrAlignment,
		FormatHints	formatHints,
		const String &	comments )

inline

Constructor usually used with static variable declarations (declarations that are not using enumeration types associated with ALib Enum Records of this type).

If used however to define an enum record during bootstrap of a software (by user code that omits the preferred option of parsing resourced strings to create such records), then each parameter of type String passed, has to be of "static nature". This means, that string buffers and their contents are deemed to survive the life-cycle of an application. Usually, C++ string literals are passed in such situation.

Parameters

category	Value for field Variable::Category .
name	Value for field Variable::Name .
defaultValue	Value for field Variable::DefaultValue .
delim	Value for field Variable::Delim .
formatAttrAlignment	Value for field Variable::FormatAttrAlignment .
formatHints	Value for field Variable::FmtHints .
comments	Value for field Variable::Comments .

Definition at line 157 of file variabledecl.hpp.

◆ VariableDecl() [3/3]

template<typename TEnum , typename TEnableIf = void>

VariableDecl ( TEnum declaration )

Constructor that accepts an element of a C++ enum type equipped with ALib Enum Records of this type (VariableDecl ). that contains the declaration data. A copy of the enum record is created.

In the case that a specialization of type T_Resourced exists for the given enumeration type, fields DefaultValue and Comments are interpreted as a resource name and are loaded from the resource pool specified.

Template Parameters

TEnum	The type of parameter declaration
TEnableIf	Not to be specified. Used by the compiler to select this constructor only for associated custom C++ enum types.

Parameters

declaration Element of an enum class that is representing configuration variables.

Method Details:

◆ Parse()

void Parse ( )

Implementation of EnumRecordPrototype::Parse .

Note: Field ERSerializable::MinimumRecognitionLength is not read from the string, but set to fixed value 0.

Definition at line 285 of file variable.cpp.

Here is the call graph for this function:

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