Declaration Class Reference

Description:

Introduction

This data record is used as an alternative (and often preferred) method to declare and optionally already define an ALib Configuration 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 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* ), and Variable(lang::Camp& camp, const Declaration* ), as well as methods Declare(const Declaration*), and Try(const Declaration*) can be used.

Nevertheless, as seen 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 enums::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::config::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 type T_Resourced. 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, what 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 enumerate 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:

• Static method Declaration::Get(TEnum)
• Variable::Variable(Configuration&, TEnum)
• Variable::Variable(Configuration&, TEnum, const Box)
• Variable::Variable(lang::Camp&, TEnum)
• Variable::Variable(lang::Camp&, TEnum, const Box)
• Variable::Declare(TEnum)
• Variable::Declare(TEnum, const Box&)

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:

1. The enum element value (this is mandatory with every resourced enum record).
2. Base class's field ERSerializable::EnumElementName.

   Note

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

3. 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 148 of file declaration.hpp.

#include <declaration.hpp>

Inheritance diagram for Declaration:

Collaboration diagram for Declaration:

Public Static Method Index:
template<typename TEnum , typename TEnableIf = void>
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_API void	Parse ()
const String &	TypeName () const
Public Method Index: inherited from ERSerializable
	ERSerializable () noexcept=default
	Defaulted constructor leaving the record undefined.
	ERSerializable (const String &name, int minLength=0) noexcept
ALIB_API void	Parse ()

Protected Field Index:
String	comments
String	defaultValue
String	typeName

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

Friends And Related Entity Details:

alib::config::Configuration

friend class alib::config::Configuration

friend

Definition at line 150 of file declaration.hpp.

alib::config::Variable

friend class alib::config::Variable

friend

Definition at line 151 of file declaration.hpp.

Field Details:

comments

String comments

protected

The configuration variable's comments.

Note

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

Definition at line 170 of file declaration.hpp.

defaultValue

String 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 164 of file declaration.hpp.

typeName

String typeName

protected

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

Definition at line 158 of file declaration.hpp.

Constructor(s) / Destructor Details:

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

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

Definition at line 192 of file declaration.hpp.

Method Details:

Comments()

const String & Comments ( ) const

inline

Returns this configuration variable's comments.

Returns

The comments of this variable.

Definition at line 270 of file declaration.hpp.

DefaultValue()

const String & 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 266 of file declaration.hpp.

Get()

template<typename TEnum , typename TEnableIf = void>

static const Declaration * Get ( TEnum element )

static

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 T_Resourced exists for the enumeration type, DefaultValue and Comments are interpreted as a resource name given and are loaded with this method separatedly from the resource pool.

Template Parameters

TEnum	The custom enum type that is associated with variable declarations.
TEnableIf	Not to be specified. Used by the compiler to select this method only for associated custom C++ enum types.

Parameters

element

The desired variable (aka element of type TEnum.

Returns

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

Name()

const String & Name ( ) const

inline

Returns this configuration variable's name.

Returns

The name of this variable.

Definition at line 259 of file declaration.hpp.

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 26 of file vmeta.cpp.

Here is the call graph for this function:

TypeName()

const String & TypeName ( ) const

inline

Returns this configuration variable's type.

Returns

The name of this variable.

Definition at line 255 of file declaration.hpp.

---

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

• declaration.hpp
• vmeta.cpp