#include <variable.hpp>

Inheritance diagram for Variable:

Collaboration diagram for Variable:

Class Description

This class is used to load and store external configuration data with objects of class Configuration and its plug-ins ConfigurationPlugin.

Note: For general information about external configuration variables, see namespace documentation aworx::lib::config.

Construction/Redeclaration:
While constructors accepting attributes of a variable exist, it is recommended to declare all external configuration variables in a central place, using statically or dynamically allocated objects of type VariableDecl and pass such record to the constructor of a variable.

The class is self-contained in a MonoAllocator and supports is designed to be 'reused'. This is implementation is chosen to avoid repeated allocation/de-allocation of dynamic memory when a larger amount of variables are read or written. After invoking one of the overloaded methods Declare, which share the same signatures as the overloaded constructors, a variable is freshly initialized and its monotonic allocator is reseet.

Values:
A variable can contain zero, one or several values. If zero, then the variable was either not loaded, yet or the load operation failed (no configuration plug-in defined the variable). Method Size reports the currently available values and methods GetString(int), GetInteger(int) and GetFloat(int) return a value. Internally all values are stored as strings. If field Config is set, its field Configuration::NumberFormat is used for floating point conversion.

When storing a variable that contains more than one value, field Delim has to be set. Conversely, when reading a variable that contains multiple values, the delimiter has to be set prior to the load operation.

Note: This is not true when loading/storing a variable directly in a plug-in of type InMemoryPlugin or might also not be true with custom configuration plug-in types which for example might store the values in a database.
However, with the default plug-ins CLIArgs, Environment and IniFile, the delimiter is needed! Therefore, it is best practice to always define a proper delimiter if a variable contains multiple values.

To set the contents of various fields, methods whose name is prefixed with Replace are given. Each of these methods allocates new storage in the internal monotonic allocator, which is freed only with method Reset, which is internally called with each overloaded Declare method. The using software has to ensure that Reset is invoked on a regular basis, to not generate a "memory leak" by increasing the allocated space in the monotonic allocator. In common use-cases of the class, this is not an issue.

Loading and Storing:
There are two ways of loading and storing a variable:

Using the interface of class Configuration which allows to load and store variables from different sources (plug-ins) in a prioritized way.
Using the interface of class ConfigurationPlugin which may be used if the decision about the source or drain of a load/store operation is explicitly made by a code unit - instead of by the configuration.

Storing empty variables (method Size returns 0) deletes a variable from the those configuration plug-ins that are write enabled.

Definition at line 196 of file variable.hpp.

Public Methods
	Variable ()

	Variable (const String &category, const String &name, character delim='\0', const String &comments=nullptr)

	Variable (const Variable &variable)

	Variable (const VariableDecl &declaration, const Box &replacements)

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

template<typename TEnum , typename TEnableIf = void>
	Variable (TEnum declaration, const Box &replacements)

	Variable (Variable &&src) noexcept

ALIB_API void	Add (const String &value)

ALIB_API void	Add (double value)

void	Add (int32_t value)

ALIB_API void	Add (int64_t value)

const String &	Category () const

Variable &	ClearValues (int startIdx=0)

const String &	Comments () const

Configuration *	Config ()

const Configuration *	Config () const

ALIB_API Variable &	Declare (const ComplementString &category, const ComplementString &name, complementChar delim='\0', const ComplementString &comments=nullptr)

ALIB_API Variable &	Declare (const String &category, const String &name, character delim='\0', const String &comments=nullptr)

ALIB_API Variable &	Declare (const Variable &variable)

ALIB_API Variable &	Declare (const VariableDecl &declaration, const Box &replacements)

template<typename TEnum >
Variable &	Declare (TEnum declaration)

const String &	DefaultValue () const

character	Delim () const

FormatHints	FmtHints () const

const String &	FormatAttrAlignment () const

const ALIB_API String &	Fullname ()

ALIB_API bool	GetAttribute (const String &attrName, Substring &result, character attrDelim=A_CHAR('='))

ALIB_API double	GetFloat (int idx=0)

ALIB_API integer	GetInteger (int idx=0)

const String &	GetString (int idx=0)

ALIB_API bool	IsTrue (int idx=0)

const String &	Name () const

Priorities	Priority () const

void	ReplaceCategory (const String &newValue)

void	ReplaceComments (const String &newValue)

void	ReplaceDefaultValue (const String &newValue)

void	ReplaceFormatAttrAlignment (const String &newValue)

void	ReplaceName (const String &newValue)

ALIB_API void	ReplaceValue (int idx, const String &replacement)

ALIB_API void	ReplaceValue (int idx, Variable &replVariable)

ALIB_API Variable &	Reset (CurrentData nameAndCategory=CurrentData::Clear)

void	SetConfig (Configuration *config)

void	SetDelim (character delim)

void	SetFmtHints (FormatHints hints)

void	SetPriority (Priorities priority)

integer	Size () const

Additional Inherited Members
Protected Fields inherited from SelfContained< detail::VariableFields >
Fields *	fields

Protected Methods inherited from SelfContained< detail::VariableFields >
	SelfContained ()=delete

	SelfContained (SelfContained &&move) noexcept

	SelfContained (SelfContained &)=delete

	SelfContained (size_t initialChunkSize, unsigned int chunkGrowthInPercent, TArgs &&... args)

	~SelfContained ()

MonoAllocator &	Allocator ()

const MonoAllocator &	Allocator () const

SelfContained &	operator= (SelfContained &&src)

SelfContained &	operator= (SelfContained &)=delete

void	Reset (TArgs &&... args)

detail::VariableFields &	Self ()

const detail::VariableFields &	Self () const

void	TakeSnapshot ()

Constructor & Destructor Documentation

◆ Variable() [1/7]

Variable ( Variable && src )

inlinenoexcept

Move constructor moves the entries and deletes them in source object.

Parameters

src	The object to move.

Definition at line 206 of file variable.hpp.

◆ Variable() [2/7]

Variable ( )

inline

Constructs an undefined Variable. Prior to using this, Declare has to be invoked.

Definition at line 213 of file variable.hpp.

Here is the call graph for this function:

◆ Variable() [3/7]

Variable	(	const VariableDecl &	declaration,
		const Box &	replacements
	)

inline

Constructs a variable from a declaration. Strings named "%1", "%2" ... "%N" found in the fields Category, Name, Comments and DefaultValue are replaced with given replacement values found in boxed argument (list) replacements.

Parameters

declaration	The declaration data of the variable.
replacements	List of replacement values. Must be of boxed types that are appendable to class AString. To provide more than one object, pass an object of class Boxes or a boxed array.

Definition at line 235 of file variable.hpp.

Here is the call graph for this function:

◆ Variable() [4/7]

Variable ( const Variable & variable )

inline

Constructs a variable using the declaration of another variable. The values are not copied.

Parameters

variable A variable to copy the declaration (which is comprised with fields Category, Name, Fullname, Delim, Comments and DefaultValue) from.

Definition at line 251 of file variable.hpp.

Here is the call graph for this function:

◆ Variable() [5/7]

Variable	(	const String &	category,
		const String &	name,
		character	delim = `'\0'`,
		const String &	comments = `nullptr`
	)

inline

Constructs a variable from the given values

Parameters

category	The category of the variable.
name	The name of the variable
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files).
comments	Comment lines that might be added in the configuration storage (plug-in implementation dependent).

Definition at line 270 of file variable.hpp.

Here is the call graph for this function:

◆ Variable() [6/7]

Variable ( TEnum declaration )

inline

Constructs a variable from an enum element equipped with ALib Enum Records of type VariableDecl.

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.

◆ Variable() [7/7]

Variable	(	TEnum	declaration,
		const Box &	replacements
	)

Constructs a variable from an enum element equipped with ALib Enum Records of type VariableDecl.

Strings named "%1", "%2" ... "%N" found in the fields Category, Name, Comments and DefaultValue are replaced with given replacement values found in boxed argument (list) replacements.

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.
replacements	List of replacement values. Must be of boxed types that are appendable to class AString. To provide more than one object, pass an object of class Boxes or a boxed array of boxes.

Member Function Documentation

◆ Add() [1/4]

void Add ( const String & value )

Adds a value to the end of the list of values.

Parameters

value The string value to add.

Definition at line 223 of file variable.cpp.

Here is the call graph for this function:

◆ Add() [2/4]

void Add ( double value )

Adds a floating point value to the end of the list of values.

Parameters

value The value to add.

Definition at line 235 of file variable.cpp.

Here is the call graph for this function:

◆ Add() [3/4]

void Add ( int32_t value )

inline

Adds an integral value to the end of the list of values.

Parameters

value The value to add.

Definition at line 748 of file variable.hpp.

Here is the call graph for this function:

◆ Add() [4/4]

void Add ( int64_t value )

Adds an integral value to the end of the list of values.

Parameters

value The value to add.

Definition at line 229 of file variable.cpp.

Here is the call graph for this function:

◆ Category()

const String& Category ( ) const

inline

Returns this configuration variable's category.

Returns: The category of this variable.

Definition at line 487 of file variable.hpp.

Here is the call graph for this function:

◆ ClearValues()

Variable& ClearValues ( int startIdx = 0 )

inline

Clears the value, respectively the list of values set. After invoking this method, Size will return startIdx and GetString will return nullptr for any index greater or equal to startIdx.

Parameters

startIdx The index of the first value to be cleared. Defaults to 0.

Returns: *this to allow concatenated operations.

Definition at line 721 of file variable.hpp.

Here is the call graph for this function:

◆ Comments()

const String& Comments ( ) const

inline

Returns this configuration variable's comments.

Returns: The comments of this variable.

Definition at line 558 of file variable.hpp.

Here is the call graph for this function:

◆ Config() [1/2]

Configuration* Config ( )

inline

The Configuration that was recently used to request or store the value.

Returns: The associated configuration object or nullptr if no configuration is assigned.

Definition at line 468 of file variable.hpp.

Here is the call graph for this function:

◆ Config() [2/2]

const Configuration* Config ( ) const

inline

The Configuration that was recently used to request or store the value.

Returns: The associated configuration object or nullptr if no configuration is assigned.

Definition at line 458 of file variable.hpp.

Here is the call graph for this function:

◆ Declare() [1/5]

Variable & Declare	(	const ComplementString &	category,
		const ComplementString &	name,
		complementChar	delim = `'\0'`,
		const ComplementString &	comments = `nullptr`
	)

Re-initializes the variable using the specific values given. This overload accepts complementary string character types for each argument.

Parameters

category	The category of the variable.
name	The name of the variable
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files). Defaults to `'\0'`.
comments	Comment lines that might be added in the configuration storage (plug-in implementation dependent). Defaults to `nullptr`.

Returns: *this to allow concatenated operations.

Definition at line 167 of file variable.cpp.

Here is the call graph for this function:

◆ Declare() [2/5]

Variable & Declare	(	const String &	category,
		const String &	name,
		character	delim = `'\0'`,
		const String &	comments = `nullptr`
	)

Re-initializes the variable using the specific values given.

Parameters

category	The category of the variable.
name	The name of the variable
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files). Defaults to `'\0'`.
comments	Comment lines that might be added in the configuration storage (plug-in implementation dependent). Defaults to `nullptr`.

Returns: *this to allow concatenated operations.

Definition at line 151 of file variable.cpp.

Here is the call graph for this function:

◆ Declare() [3/5]

Variable & Declare ( const Variable & variable )

Declares a variable using the declaration of another variable. The values are not copied.

Parameters

variable A variable to copy the declaration (which is comprised with fields Category, Name, Fullname, Delim, Comments and DefaultValue) from.

Returns: *this to allow concatenated operations.

Definition at line 61 of file variable.cpp.

Here is the call graph for this function:

◆ Declare() [4/5]

Variable & Declare	(	const VariableDecl &	declaration,
		const Box &	replacements
	)

Re-initializes this variable from a given declaration. Placeholders "%1", "%2" ... "%N" found in fields Category, Name, Comments and DefaultValue are replaced with the replacement values given with boxed argument (list) replacements.

Parameters

declaration	The declaration data of the variable.
replacements	List of replacement values. Must be of boxed types that are appendable to class AString. To provide more than one object, pass an object of class Boxes or a boxed array.

Returns: *this to allow concatenated operations.

Definition at line 77 of file variable.cpp.

Here is the call graph for this function:

◆ Declare() [5/5]

Variable& Declare ( TEnum declaration )

Re-initializes this variable and resets its declaration. Internally uses an instance of class VariableDecl constructed with enum element declaration.

Parameters

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

Template Parameters

TEnum The type of parameter declaration

Returns: *this to allow concatenated operations.

◆ DefaultValue()

const String& DefaultValue ( ) const

inline

The default value provided as an externalized string.

The only occasion that this value is used is with method Configuration::Load. If no plug-in has this variable defined and this field is not nulled, then the value is written into plug-in of priority Priorities::DefaultValues, respectively - if this default plug-in was replaced by the user - into a plug-in found at or below this priority.

In this case, the value is parsed using method XTernalizer::LoadFromString of field ConfigurationPlugin::StringConverter of the plug-in writing the value.

Note: The field is ignored when using the plug-in interface ConfigurationPlugin::Load directly. To store this value 'manually' directly to a plug-in, invoke ConfigurationPlugin::Store with providing value explicitly.

Returns: The default value of this variagble.

Definition at line 597 of file variable.hpp.

Here is the call graph for this function:

◆ Delim()

character Delim ( ) const

inline

The delimiter used for parsing and storing values by simple textual plug-ins which use the default version of XTernalizer for in- and externalizing variables.

Returns: The delimiter character of this variable.

Definition at line 506 of file variable.hpp.

Here is the call graph for this function:

◆ FmtHints()

FormatHints FmtHints ( ) const

inline

Hints for formatting textual configuration files. (Used by class IniFile and potentially by custom plug-ins.

Returns: The format hints.

Definition at line 527 of file variable.hpp.

Here is the call graph for this function:

◆ FormatAttrAlignment()

const String& FormatAttrAlignment ( ) const

inline

If set, attributes written in multi-lines are vertically aligned by this character or string. Use cases are "=", ":" or "->".
Used by IniFile and potentially by custom plug-ins.

Returns: The alignment of attributes.

Definition at line 549 of file variable.hpp.

Here is the call graph for this function:

◆ Fullname()

const String & Fullname ( )

The configuration variable category and name concatenated with an underscore character '_'. This is useful e.g. for naming variables in log messages.

Note: This method is not declared const, as the full name might be assembled with the invocation of this method.

Returns: The name and category of this variable separated by '_'.

Definition at line 266 of file variable.cpp.

Here is the call graph for this function:

◆ GetAttribute()

bool GetAttribute	(	const String &	attrName,
		Substring &	result,
		character	attrDelim = `A_CHAR('=')`
	)

Searches in the values of this variable for the pattern attrName = result and sets parameter result to the string following this pattern.

Parameters

	attrName	The name of the attribute searched.
[out]	result	A sub-string with the result.
	attrDelim	The delimiter to search for. Defaults to '='.

Returns: true if the attribute was found, false otherwise. In the latter case, output argument result will be a nulled string.

Definition at line 250 of file variable.cpp.

Here is the call graph for this function:

◆ GetFloat()

double GetFloat ( int idx = 0 )

Returns the value at idx interpreted as a double value. If the index is invalid, 0.0 is returned. Parsing is done using field NumberFormat of field Config, respectively, if this is not set, the static singleton NumberFormat::Global.

Parameters

idx	The index of the value to be retrieved. Defaults to `0`.

Returns: The value at idx interpreted as a double value.

Definition at line 246 of file variable.cpp.

Here is the call graph for this function:

◆ GetInteger()

integer GetInteger ( int idx = 0 )

Returns the value at idx interpreted as an integer. If the index is invalid, 0 is returned.

Parameters

idx	The index of the value to be retrieved. Defaults to `0`.

Returns: The value at idx interpreted as an integral value.

Definition at line 244 of file variable.cpp.

Here is the call graph for this function:

◆ GetString()

const String& GetString ( int idx = 0 )

inline

Returns the stored value with the given index. Valid values for parameter idx are between 0 and Size - 1.
In debug-compilations an error is raised if the given idx is out of range.

Parameters

idx	The index of the value to be retrieved. Defaults to `0`.

Returns: The value at idx.

Definition at line 780 of file variable.hpp.

Here is the call graph for this function:

◆ IsTrue()

bool IsTrue ( int idx = 0 )

Returns true if the first value represents a boolean 'true'. Evaluation is done using field Config, respectively if this is not set, the static singleton NumberFormat::Global.

Parameters

idx	The index of the value to be retrieved. Defaults to `0`.

Returns: The value at idx interpreted as a boolean value.

Definition at line 242 of file variable.cpp.

Here is the call graph for this function:

◆ Name()

const String& Name ( ) const

inline

Returns this configuration variable's name.

Returns: The name of this variable.

Definition at line 496 of file variable.hpp.

Here is the call graph for this function:

◆ Priority()

Priorities Priority ( ) const

inline

A value related to the priority of a configuration plug-in. The following values apply:

Priorities::NONE after creation or declaration (reuse).
The priority of the plug-in that loaded the value (after calling Configuration::Load).
The priority of the plug-in that stored the value (after calling Configuration::Store).
0, if the last load or store operation failed. In addition prior to storing a variable, the value might be manually set. See documentation of Configuration::Store) for details.

Returns: The priority setting for this variable.

Definition at line 617 of file variable.hpp.

Here is the call graph for this function:

◆ ReplaceCategory()

void ReplaceCategory ( const String & newValue )

inline

Sets the value received by Category.

Note: This method allocates a new string object in the internal MonoAllocator which will only be released with resetting this variable instance.

Parameters

newValue The new category to set.

Definition at line 642 of file variable.hpp.

Here is the call graph for this function:

◆ ReplaceComments()

void ReplaceComments ( const String & newValue )

inline

Sets the value received by Comments.

Note: This method allocates a new string object in the internal MonoAllocator which will only be released with resetting this variable instance.

Parameters

newValue The new comments to set.

Definition at line 668 of file variable.hpp.

Here is the call graph for this function:

◆ ReplaceDefaultValue()

void ReplaceDefaultValue ( const String & newValue )

inline

Sets the value received by DefaultValue.

Note: This method allocates a new string object in the internal MonoAllocator which will only be released with resetting this variable instance.

Parameters

newValue The new default value to set.

Definition at line 681 of file variable.hpp.

Here is the call graph for this function:

◆ ReplaceFormatAttrAlignment()

void ReplaceFormatAttrAlignment ( const String & newValue )

inline

Sets the value received by FormatAttrAlignment.

Note: This method allocates a new string object in the internal MonoAllocator which will only be released with resetting this variable instance.

Parameters

newValue The new alignment to set.

Definition at line 694 of file variable.hpp.

Here is the call graph for this function:

◆ ReplaceName()

void ReplaceName ( const String & newValue )

inline

Sets the value received by Name.

Note: This method allocates a new string object in the internal MonoAllocator which will only be released with resetting this variable instance.

Parameters

newValue The new name to set.

Definition at line 655 of file variable.hpp.

Here is the call graph for this function:

◆ ReplaceValue() [1/2]

void ReplaceValue	(	int	idx,
		const String &	replacement
	)

Replaces the value at idx with the given string.

Parameters

idx	The index of the value to replace.
replacement	The string value to set.

Definition at line 188 of file variable.cpp.

Here is the call graph for this function:

◆ ReplaceValue() [2/2]

void ReplaceValue	(	int	idx,
		Variable &	replVariable
	)

Replaces the value at idx with the values of the given other variable.

Parameters

idx	The index of the value to replace.
replVariable	The variable providing the replacement values.

Definition at line 200 of file variable.cpp.

Here is the call graph for this function:

◆ Reset()

Variable & Reset ( CurrentData nameAndCategory = CurrentData::Clear )

Clears all fields and resets internal monotonic allocator.

Parameters

nameAndCategory If CurrentData::CurrentData::Keep is given, the name and category of the variable will be restored after the reset.
Defaults to CurrentData::Clear.

Returns: *this to allow concatenated operations.

Definition at line 25 of file variable.cpp.

Here is the call graph for this function:

◆ SetConfig()

void SetConfig ( Configuration * config )

inline

Sets the Configuration to load or store the value.

Parameters

config The configuration to use.

Definition at line 477 of file variable.hpp.

Here is the call graph for this function:

◆ SetDelim()

void SetDelim ( character delim )

inline

Sets the delimiter used for parsing and storing values.

See also: Method Delim for more informaiton.

Parameters

delim The configuration to use.

Definition at line 517 of file variable.hpp.

Here is the call graph for this function:

◆ SetFmtHints()

void SetFmtHints ( FormatHints hints )

inline

Sets the hints for formatting textual configuration files. (Used by class IniFile and potentially by custom plug-ins.

Parameters

hints The hints to be used.

Definition at line 538 of file variable.hpp.

Here is the call graph for this function:

◆ SetPriority()

void SetPriority ( Priorities priority )

inline

Sets the priority.

See also: Method Priority for more information.

Parameters

priority The priority to use.

Definition at line 628 of file variable.hpp.

Here is the call graph for this function:

◆ Size()

integer Size ( ) const

inline

Returns the number of values set in this object.

Returns: The number of values set.

Definition at line 708 of file variable.hpp.

Here is the call graph for this function:

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

Class Description

Public Methods

Additional Inherited Members

Constructor & Destructor Documentation

◆ Variable() [1/7]

◆ Variable() [2/7]

◆ Variable() [3/7]

◆ Variable() [4/7]

◆ Variable() [5/7]

◆ Variable() [6/7]

◆ Variable() [7/7]

Member Function Documentation

◆ Add() [1/4]

◆ Add() [2/4]

◆ Add() [3/4]

◆ Add() [4/4]

◆ Category()

◆ ClearValues()

◆ Comments()

◆ Config() [1/2]

◆ Config() [2/2]

◆ Declare() [1/5]

◆ Declare() [2/5]

◆ Declare() [3/5]

◆ Declare() [4/5]

◆ Declare() [5/5]

◆ DefaultValue()

◆ Delim()

◆ FmtHints()

◆ FormatAttrAlignment()

◆ Fullname()

◆ GetAttribute()

◆ GetFloat()

◆ GetInteger()

◆ GetString()

◆ IsTrue()

◆ Name()

◆ Priority()

◆ ReplaceCategory()

◆ ReplaceComments()

◆ ReplaceDefaultValue()

◆ ReplaceFormatAttrAlignment()

◆ ReplaceName()

◆ ReplaceValue() [1/2]

◆ ReplaceValue() [2/2]

◆ Reset()

◆ SetConfig()

◆ SetDelim()

◆ SetFmtHints()

◆ SetPriority()

◆ Size()