Description:

Introduction

This data record is used as an alternative (and often preferred) method to declare and optionally already define an ALib Variable. The record contains the following information:

The variables' name,
the variables' type name,
an optional defaultValue, and
optional comments.

The latter may be used by an external configuration file to place human-readable comments next to each configuration entry.

With a Declaration instance in place, constructors Variable(Configuration& cfg, const Declaration* ), as well as methods Declare(const Declaration*), and Try(const Declaration*) can be used.

Nevertheless, as we will see below, a much nicer option exists.

Placeholders: All fields support placeholders "%1", "%2" ... "%N", which are replaced with optional constructors of class Variable, some of its methods Declare and with this classes' static method Get.-

This allows defining a series of variables whose name, description, default value and comments are dependent on run-time information. For example, the text logging types of camp ALox, have an own name. Now this name fills the placeholders within the variable declarations that each logger creates. This way, one resourced declaration is copied to be used by one or more loggers.

String Data Allocation: The nature of this type's contained string data is "static" and "read only". Consequently this classes' members are simple ALib strings, without a own string buffer. The class relies on the fact that the lifecycle of the string data is permanent, just like C++ string literals that you might pass to the constructor, or like externalized resource strings, which is described in the next sections, are.
A little challenge arises when placeholders are used: Here, new string data has to be allocated. For this, the convenience method Configuration::StoreDeclaration is available. The method not only copies the data into the internal MonoAllocator, but it also checks if a corresponding replaced record was previously already stored. In this case no next copy is generated, but the old one is re-used. In the sample of ALox loggers above this means: The repeated creation and deletion of a logger with the same name generates only one declaration.

If a programmer provides self-generated variable names in combination with declarations, it has to be ensured that these variable names survive the lifecycle of the declaration.

Note: This is not true for the variable names of declared variables. They are duly copied, allocated, disposed, and recycled by class Configuration.

Enum Records

This type inherits class enumrecords::ERSerializable and is enabled to be read from (externalized) resource data associated with C++ enumerations. The record associated with an enum element used for construction must be of this type itself. Consequently, equipping enum type MyEnum is performed like this:

 ALIB_ENUMS_ASSIGN_RECORD( MyEnum, alib::variables::Declaration )

(For more information, see ALib Enum Records.)

Resourced Enums

Besides defining the enum record type, a custom enum has to have a specialization of the type traits ResourcedTraits. This is an exception to similar types found across ALib. Usually, a C++ enum type can be equipped with enum records and then optionally be resourced. The reason for this exception 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, which has the following advantages:

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

Note: What was said here does not mean that Declaration instances have to be resourced. The point is that only if declarations are to be associated with C++ enums, which list the available variables, then this second step of resourcing the enums has to be made!

With these prerequisites in place, variables can be declared very conveniently by passing just a C++ enum element of custom enum type to one of the following methods:

Furthermore, a whole set of variables can be declared by passing just the enum type itself to method

Configuration::PreloadVariables.

This is usually done with bootstrap which makes all variables seamlessly available at least with a resourced default value, or overwritten by configuration files, CLI arguments or command lines. Usually the using code does not care and just accesses a variables value through the enumeration.

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

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

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.

This makes it very convenient to have all attributes of a variable, including their name managed independently from the program code and allows localizing variable names to other languages. Of course, this applies to such variables only which become externalized. Therefore, this library likewise allows declaring and use variables without providing an instance of this type.

Reference Documentation

Definition at line 138 of file declaration.inl.

Inheritance diagram for alib::variables::Declaration:

[legend]

Collaboration diagram for alib::variables::Declaration:

[legend]

Public Static Method Index:
template<typename TEnum> requires (EnumRecords<TEnum>::template AreOfType<Declaration>())
static const Declaration *	Get (TEnum element)

Public Method Index:
	Declaration ()=default
	Default constructor.

	Declaration (const String &pName, const String &pTypeName, const String &pDefaultValue, const String &pComments)

const String &	Comments () const

const String &	DefaultValue () const

const String &	Name () const

ALIB_DLL void	Parse ()

const String &	TypeName () const

Public Method Index: inherited from alib::enumrecords::ERSerializable
	ERSerializable () noexcept=default
	Defaulted constructor leaving the record undefined.

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

ALIB_DLL void	Parse ()

Protected Field Index:
String	comments

String	defaultValue

String	typeName

Additional Inherited Members
Public Field Index: inherited from alib::enumrecords::ERSerializable
String	EnumElementName
	The name of the enum element.

int	MinimumRecognitionLength

Friends And Related Entity Details:

◆ alib::variables::Configuration

friend class alib::variables::Configuration

friend

Definition at line 140 of file declaration.inl.

◆ alib::variables::Variable

friend class alib::variables::Variable

friend

Definition at line 141 of file declaration.inl.

Field Details:

◆ comments

String alib::variables::Declaration::comments

protected

The configuration variable's comments.

Note: If the type trait ResourcedTraits is specialized for an enumeration, this field is interpreted as a resource name to load the description/comments from.

Definition at line 161 of file declaration.inl.

◆ defaultValue

String alib::variables::Declaration::defaultValue

protected

The default value provided as an C++ string that may have to be parsed when imported into a variable definition. If set, the variable becomes automatically defined with Priority::DefaultValues when declared passing this instance.

See also: Method DefaultValue.

Definition at line 154 of file declaration.inl.

◆ typeName

String alib::variables::Declaration::typeName

protected

The type of the variable. Corresponds to what is defined with macros ALIB_VARIABLES_DEFINE_TYPE and ALIB_VARIABLES_REGISTER_TYPE.
Built-in types are listed with chapter 5.1 Built-In Variable Types of the Programmer's Manual.

Definition at line 148 of file declaration.inl.

Constructor(s) / Destructor Details:

◆ Declaration()

alib::variables::Declaration::Declaration	(	const String &	pName,
		const String &	pTypeName,
		const String &	pDefaultValue,
		const String &	pComments )

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

pName	Value for field ERSerializable::EnumElementName.
pTypeName	Value for field typeName.
pDefaultValue	Value for field defaultValue.
pComments	Value for field comments.

Definition at line 183 of file declaration.inl.

Here is the call graph for this function:

Method Details:

◆ Comments()

const String & alib::variables::Declaration::Comments ( ) const

inline

Returns this configuration variable's comments.

Returns: The comments of this variable.

Definition at line 255 of file declaration.inl.

◆ DefaultValue()

const String & alib::variables::Declaration::DefaultValue ( ) const

inline

The default value provided as a C++ string (not escaped). If provided, the variable becomes automatically defined with Priority::DefaultValues.

Returns: The contents of field defaultValue.

Definition at line 251 of file declaration.inl.

◆ Get()

template<typename TEnum>
requires (EnumRecords<TEnum>::template AreOfType<Declaration>())

const Declaration * alib::variables::Declaration::Get ( TEnum element )

inlinestatic

Static method that accepts an element of a C++ enum type equipped with ALib Enum Records of this type, that contains the declaration data.

In the case that a specialization of type trait ResourcedTraits exists for the enumeration, DefaultValue and Comments are interpreted as a resource name and are loaded with this method - separately from the resource pool.

Template Parameters

TEnum The custom enum type that is associated with variable declarations.

Parameters

element The desired variable (aka element of type TEnum.

Returns: The resourced declaration associated with the given enumeration element of type TEnum.

Definition at line 212 of file declaration.inl.

Here is the call graph for this function:

◆ Name()

const String & alib::variables::Declaration::Name ( ) const

inline

Returns this configuration variable's name.

Returns: The name of this variable.

Definition at line 244 of file declaration.inl.

◆ Parse()

void alib::variables::Declaration::Parse ( )

Implementation of EnumRecordPrototype::Parse.

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

Definition at line 29 of file vmeta.cpp.

Here is the call graph for this function:

◆ TypeName()

const String & alib::variables::Declaration::TypeName ( ) const

inline

Returns this configuration variable's type.

Returns: The name of this variable.

Definition at line 240 of file declaration.inl.

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

Description:

Public Static Method Index:

Public Method Index:

Protected Field Index:

Additional Inherited Members

Friends And Related Entity Details:

◆ alib::variables::Configuration

◆ alib::variables::Variable

Field Details:

◆ comments

◆ defaultValue

◆ typeName

Constructor(s) / Destructor Details:

◆ Declaration()

Method Details:

◆ Comments()

◆ DefaultValue()

◆ Get()

◆ Name()

◆ Parse()

◆ TypeName()