Description:

This is the central interface type into ALib Configuration Data. The class is a very lightweight (size of two times sizeof(void*)) object, because it rather is a pointer to a variable instead of an implementation of its data structures. The types' true nature is inherited from class StringTree::Cursor which is the base of this class. The inheritance is defined protected and this class received its own dedicated interface reflecting the domain of configuration variables. Nevertheless, the protected base type is accessible with the explicit cast method AsCursor. While a reader might think this is a contradiction, this was made by design: Casting to a StringTree::Cursor is only necessary for implementing ConfigurationPlugin or similar extraordinary things. For the common use, the dedicated interface is all that is needed.

See also

For a quick tutorial about using ALib configuration variables, consult the tutorial-style Programmer's Manual of camp ALib Configuration.
For this class, a pretty printer for the GNU debugger is provided.

Definition at line 698 of file configuration.hpp.

#include <configuration.hpp>

Inheritance diagram for Variable:

[legend]

Collaboration diagram for Variable:

[legend]

Public Method Index:
	Variable ()=default

	Variable (Configuration &cfg)

	Variable (Configuration &cfg, const Declaration *decl)

	Variable (Configuration &cfg, const String &name, const String &typeName, const String &defaultValue=NULL_STRING)

template<typename TEnum >
	Variable (Configuration &cfg, TEnum Enum)

template<typename TEnum >
	Variable (Configuration &cfg, TEnum Enum, const Box replacements)

	Variable (const Cursor &cursor)

	Variable (const Cursor &cursor, const String &typeName, const String &defaultValue=NULL_STRING)

	Variable (const String &name, const String &typeName, const String &defaultValue=NULL_STRING)

	Variable (lang::Camp &camp)

	Variable (lang::Camp &camp, const Declaration *decl)

	Variable (lang::Camp &camp, const String &name, const String &typeName, const String &defaultValue=NULL_STRING)

template<typename TEnum >
	Variable (lang::Camp &camp, TEnum Enum)

template<typename TEnum >
	Variable (lang::Camp &camp, TEnum Enum, const Box replacements)

Cursor &	AsCursor ()

const Cursor &	AsCursor () const

ALIB_API Variable &	Declare (const Declaration *declaration)

ALIB_API Variable &	Declare (const String &name, const String &typeName, const String &defaultValue=NULL_STRING)

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

template<typename TEnum >
Variable &	Declare (TEnum Enum, const Box &replacements)

ALIB_API bool	Define (Priority requestedPriority=Priority::Standard)

ALIB_API void	Delete ()

AString &	Export (AString &dest, const StringEscaper *escaper=nullptr) const

template<typename T >
T &	Get ()

template<typename T >
const T &	Get () const

bool	GetBool ()

Box &	GetBox ()

Configuration &	GetConfiguration () const

const Declaration *	GetDeclaration () const

double	GetDouble ()

float	GetFloat ()

integer	GetInt ()

bool	GetOrSetDefault (bool value, Priority priority=Priority::DefaultValues)

String &	GetOrSetDefault (const String &value, Priority priority=Priority::DefaultValues)

bool	GetOrSetDefault (integer value, Priority priority=Priority::DefaultValues)

Priority	GetPriority () const

AStringPA &	GetString ()

String &	GetString (int idx)

StringVectorPA &	GetStrings ()

ALIB_API void	Import (const String &src, Priority priority, const StringEscaper *escaper=nullptr)

bool	IsDeclared () const

bool	IsDefined () const

bool	IsDefinedExternally () const

bool	IsNotDefined () const

AString &	Name (AString &target) const

	operator bool ()

	operator const String & ()

	operator const Substring ()

	operator double ()

	operator float ()

	operator integer ()

bool	operator= (bool val)
	Calls Get<Bool>() and assigns val.

const String &	operator= (const String &val)
	Calls Get<AStringPA>() and resets the string to val.

double	operator= (double val)
	Calls Get<double>() and assigns val.

float	operator= (float val)
	Calls Get<double>() and assigns val.

integer	operator= (integer val)
	Calls Get<integer>() and assigns val.

int	Size ()

ALIB_API bool	Try (const Declaration *decl)

bool	Try (const String &name)

ALIB_API bool	Try (const String &name, const String &typeName)

Protected Method Index:
void	create (const String &typeName, const String &defaultValue)

VMeta *	getMeta () const

const String &	substitute (const String &importString, AString &buf, const StringEscaper *escaper)

Protected Method Index: inherited from StringTree< TAllocator, T, TNodeHandler, TRecycling >::TCursor< TConst >
	TCursor (cmTree pTree, cmNode pNode) noexcept

void	dbgCheckTree () const

void	dbgCheckTreeAndNode () const

	TCursor () noexcept=default

	TCursor (const TCursor &src) noexcept

	TCursor (TCursor &&src) noexcept

	~TCursor () noexcept=default
	Trivial default destructor.

strings::TAString< typename cmTree::CharacterType, lang::HeapAllocator > &	AssemblePath (strings::TAString< typename cmTree::CharacterType, lang::HeapAllocator > &targetString, const TCursor< true > &parent, lang::CurrentData targetData=lang::CurrentData::Clear) const

strings::TAString< typename cmTree::CharacterType, lang::HeapAllocator > &	AssemblePath (strings::TAString< typename cmTree::CharacterType, lang::HeapAllocator > &targetString, lang::CurrentData targetData=lang::CurrentData::Clear) const

TCursor	Child (const NameType &name) const

uinteger	CountChildren () const

template<typename TCheck = CHK, typename... TArgs>
TCursor	CreateChild (const NameType &childName, TArgs &&... args) const

template<typename... TArgs>
std::pair< TCursor, bool >	CreateChildIfNotExistent (const NameType &name, TArgs &&... args)

template<typename... TArgs>
std::pair< TCursor, integer >	CreatePathIfNotExistent (const NameType &path, TArgs &&... args)

uinteger	Delete ()

bool	DeleteChild (const NameType &childName) const

void	DeleteChild (TCursor &child) const

uinteger	DeleteChildren () const

int	Depth () const

int	Distance (const TCursor< true > &other) const

CursorHandle	Export ()

ConstCursorHandle	Export () const

TCursor	FirstChild () const

SubstringType	GoTo (const NameType &path)

bool	GoToChild (const NameType &name)

template<typename... TArgs>
bool	GoToCreateChildIfNotExistent (const NameType &name, TArgs &&... args)

template<typename... TArgs>
integer	GoToCreatedPathIfNotExistent (const NameType &path, TArgs &&... args)

bool	GoToFirstChild ()

bool	GoToLastChild ()

bool	GoToNextSibling ()

TCursor &	GoToParent ()

bool	GoToPreviousSibling ()

TCursor &	GoToRoot ()

bool	HasChildren () const

bool	HasNextSibling () const

bool	HasPreviousSibling () const

bool	IsInvalid () const

bool	IsRoot () const

bool	IsValid () const

TCursor	LastChild () const

const NameType &	Name () const

TCursor	NextSibling () const

	operator TCursor<!TConst > ()

bool	operator!= (const TCursor &other) const

std::pair< TCursor, SubstringType >	operator() (const NameType &path) const

T &	operator* ()

const T &	operator* () const

T *	operator-> ()

const T *	operator-> () const

TCursor &	operator= (const TCursor &) noexcept=default

TCursor &	operator= (TCursor &&) noexcept=default

bool	operator== (const TCursor &other) const

TCursor	Parent () const

TCursor	PreviousSibling () const

TCursor	Root () const

template<typename TParent = StringTree>
const TParent &	Tree ()

T &	Value ()

const T &	Value () const

Private Type Index:
using	Cursor = Configuration::Cursor

Additional Inherited Members
Protected Type Index: inherited from StringTree< TAllocator, T, TNodeHandler, TRecycling >::TCursor< TConst >
using	cmCursor = ATMP_IF_T_F(!TConst, baseCursor, baseConstCursor)

using	cmNode = ATMP_IF_T_F(!TConst, baseNode, const baseNode)

using	cmTree = ATMP_IF_T_F(!TConst, basetree, const basetree)

using	TStringTree = ATMP_IF_T_F(!TConst, StringTree, const StringTree)

Friends And Related Entity Details:

◆ alib::config::Configuration

friend class alib::config::Configuration

friend

Definition at line 700 of file configuration.hpp.

Type Definition Details:

◆ Cursor

using Cursor = Configuration::Cursor

private

The base cursor type of the internal StringTree. This type is used to perform cursor operations on Configuration instances.

Definition at line 704 of file configuration.hpp.

Constructor(s) / Destructor Details:

◆ Variable() [1/14]

Variable ( )

default

Default constructor.

Note

A variable that was default-constructed cannot be used later, without assigning a configuration with declaration. If for example a field member of type variable cannot be constructed with the provision of a corresponding Configuration, one of the following options has to be taken:

The variable value gets a newly constructed instance assigned at a later stage when the configuration is known, or
the configuration is provided with one of the overloaded Declare methods that accept a configuration.

◆ Variable() [2/14]

Variable ( const Cursor & cursor )

inline

Constructs an instance of this type from its base type. This constructor is for advanced use when direct operations with class StringTree and its cursor and iterator types are performed.
Note that the variable has to be declared already, when this constructor is used.

Parameters

cursor The StringTree cursor.

Definition at line 750 of file configuration.hpp.

◆ Variable() [3/14]

Variable	(	const Cursor &	cursor,
		const String &	typeName,
		const String &	defaultValue = NULL_STRING )

inline

Constructs an instance of this type from its base type. This constructor is for advanced use when direct operations with class StringTree and its cursor and iterator types are performed.
Note that the previous variable declaratin will be destroyed, in case a variable had been declared at this cursor already.

Parameters

cursor	The StringTree cursor.
typeName	The type name.
defaultValue	A default value, if available. Defaults to nulled string.

Definition at line 761 of file configuration.hpp.

Here is the call graph for this function:

◆ Variable() [4/14]

Variable ( Configuration & cfg )

inlineexplicit

Constructs an undeclared variable "cursor" associated with the given configuration object.

Note: The internal alib::containers,StringTree::Cursor "containers,StringTree::Cursor" equals the root cursor received with alib::containers,StringTree::Root "containers,StringTree::Root" after this construction.

Parameters

cfg	The configuration to use.

Definition at line 769 of file configuration.hpp.

◆ Variable() [5/14]

Variable ( lang::Camp & camp )

inlineexplicit

Same as Variable(Configuration&), but takes the configuration from an ALib Camp.

Parameters

camp	An ALib Camp singleton wich supplies the Configuration instance.

Definition at line 774 of file configuration.hpp.

◆ Variable() [6/14]

Variable	(	Configuration &	cfg,
		const String &	name,
		const String &	typeName,
		const String &	defaultValue = NULL_STRING )

inline

Constructs and declares this variable, without using or allocating a declaration struct.

Parameters

cfg	The configuration to use.
name	The name of the variable.
typeName	The type of the variable.
defaultValue	An optional default value. Defaults to nulled string.

Definition at line 783 of file configuration.hpp.

◆ Variable() [7/14]

Variable	(	lang::Camp &	camp,
		const String &	name,
		const String &	typeName,
		const String &	defaultValue = NULL_STRING )

inline

Constructs and declares this variable, without using or allocating a declaration struct.

Parameters

camp	An ALib Camp An ALib Camp singleton which supplies the Configuration instance.
name	The name of the variable.
typeName	The type of the variable.
defaultValue	An optional default value. Defaults to nulled string.

Definition at line 795 of file configuration.hpp.

◆ Variable() [8/14]

Variable	(	const String &	name,
		const String &	typeName,
		const String &	defaultValue = NULL_STRING )

inline

Constructs and declares this variable, without using or allocating a declaration struct. This overload omits a parameter that specifies a configuration and uses the configuration object of the ALib Camp singleton alib::BASECAMP.

Parameters

name	The name of the variable.
typeName	The type of the variable.
defaultValue	An optional default value. Defaults to nulled string.

Definition at line 807 of file configuration.hpp.

◆ Variable() [9/14]

Variable	(	Configuration &	cfg,
		const Declaration *	decl )

inline

Constructs and declares this variable.

Parameters

cfg	The configuration to use.
decl	The declaration to use.

Definition at line 814 of file configuration.hpp.

◆ Variable() [10/14]

Variable	(	lang::Camp &	camp,
		const Declaration *	decl )

inline

Constructs and declares this variable.

Parameters

camp	An ALib Camp singleton which supplies the Configuration instance.
decl	The declaration to use.

Definition at line 820 of file configuration.hpp.

◆ Variable() [11/14]

template<typename TEnum >

Variable	(	Configuration &	cfg,
		TEnum	Enum )

inline

Constructs and declares this variable.

Template Parameters

TEnum The type of parameter Enum

Parameters

cfg	The configuration to use.
Enum	Element of an enum type that represents resourced configuration variables.

Definition at line 829 of file configuration.hpp.

Here is the call graph for this function:

◆ Variable() [12/14]

template<typename TEnum >

Variable	(	lang::Camp &	camp,
		TEnum	Enum )

inline

Constructs and declares this variable.

Template Parameters

TEnum The type of parameter Enum

Parameters

camp	An ALib Camp singleton wich supplies the Configuration instance.
Enum	Element of an enum type that represents resourced configuration variables.

Definition at line 838 of file configuration.hpp.

Here is the call graph for this function:

◆ Variable() [13/14]

template<typename TEnum >

Variable	(	Configuration &	cfg,
		TEnum	Enum,
		const Box	replacements )

inline

Constructs and declares this variable.

Attention: This constructor might allocated a new record in the mono allocator of cfg. To avoid memory drain, consult the documentation of method Configuration::StoreDeclaration.,

Template Parameters

TEnum The type of parameter Enum

Parameters

cfg	The configuration to use.
Enum	Element of an enum type that represents resourced configuration variables.
replacements	Replacement values.

◆ Variable() [14/14]

template<typename TEnum >

Variable	(	lang::Camp &	camp,
		TEnum	Enum,
		const Box	replacements )

inline

Constructs and declares this variable.

Attention: This constructor might allocated a new record in the mono allocator of cfg. To avoid memory drain, consult the documentation of method Configuration::StoreDeclaration.,

Template Parameters

TEnum The type of parameter Enum

Parameters

camp	An ALib Camp singleton wich supplies the Configuration instance.
Enum	Element of an enum type that represents resourced configuration variables.
replacements	Replacement values.

Method Details:

◆ AsCursor() [1/2]

Cursor & AsCursor ( )

inline

This is an explicit cast operator to the protected base class.

Note: C++, for good reasons, does not allow implicit cast operators to protected base classes, as this would undermine the protected nature of the inheritance. Now, we undermine this explicitly. Why is this still good software design? Well, class Variable restricts and changes the interface of class Cursor in a way that it seems to be a very different entity. And this is right in the vast majority of use cases. In the remaining cases such access to the cursor features is needed. For example, when implementing a custom ConfigurationPlugin.
By the same token, this class has explicit constructors that accept a Cursor.

Returns: This instance cast 'down' to its protected base class.

Definition at line 890 of file configuration.hpp.

◆ AsCursor() [2/2]

const Cursor & AsCursor ( ) const

inline

const version of the cast operator to the protected base class.

See also: For details, see the mutable version of this operator.

Returns: This instance cast 'down' to its protected base class.

Definition at line 895 of file configuration.hpp.

◆ create()

void create	(	const String &	typeName,
		const String &	defaultValue )

protected

Called by declaration methods. Creates necessary internal data structs, searches configuration plug-ins for data, and, in case not found, optionally applies the given defaultValue

Parameters

typeName	The type name.
defaultValue	A default value, if available.

Definition at line 110 of file variable.cpp.

Here is the call graph for this function:

◆ Declare() [1/4]

Variable & Declare ( const Declaration * declaration )

Moves this variable cursor (aka StringTree::Cursor) to represent the variable of the given declaration. If the variable does not exist, yet it is created. If the variable exists, the given decl is ignored. In debug compilations, an assertion is raised in case the variable existed but has a different declaration attached.

If the variable is created and the declaration contains a default value, such value is imported from the string. In this case, DefaultValues is returned.

Parameters

declaration The declaration singleton.

Returns: *this to allow concatenated operations.

Definition at line 233 of file variable.cpp.

Here is the call graph for this function:

◆ Declare() [2/4]

Variable & Declare	(	const String &	name,
		const String &	typeName,
		const String &	defaultValue = NULL_STRING )

Declares this variable, without using or allocating a declaration struct.

Parameters

name	The name of the variable.
typeName	The type of the variable.
defaultValue	An optional default value. Defaults to nulled string.

Returns: *this to allow concatenated operations.

Definition at line 193 of file variable.cpp.

Here is the call graph for this function:

◆ Declare() [3/4]

template<typename TEnum >

Variable & Declare ( TEnum Enum )

inline

Declares this variable.

Template Parameters

TEnum The type of parameter Enum

Parameters

Enum	Element of an enum type that represents resourced configuration variables.

Returns: The priority of the variable's data.

Definition at line 932 of file configuration.hpp.

Here is the call graph for this function:

◆ Declare() [4/4]

template<typename TEnum >

Variable & Declare	(	TEnum	Enum,
		const Box &	replacements )

inline

Declares this variable.

Attention: This constructor might allocated a new record in the mono allocator of cfg. To avoid memory drain, consult the documentation of method Configuration::StoreDeclaration.,

Template Parameters

TEnum The type of parameter Enum

Parameters

Enum	Element of an enum type that represents resourced configuration variables.
replacements	Replacement values.

Returns: The priority of the variable's data.

◆ Define()

bool Define ( Priority requestedPriority = Priority::Standard )

nodiscard

Increases the reported priority of this variable to the value given. If the current value is higher than the given one, it is not increased and false is returned. In this case, a program should not write the variable's value.

Note: A programmer can easily ignore the result of this method. However, the suggested usage is a contract to make the ALib configuration system secure. For this reason, this method is attributed [[nodiscard]].; If the return value is to be ignored for good reason (for example if Priority::Protected is passed, add a simple (void) before the call.

See also

Chapter 4. Variable Definition of the Programmer's Manual for more information.
Chapter 9. Monitoring Changes of Variables to learn about how to monitor changes of variables.

Parameters

requestedPriority The new, higher priority to set.

Returns: true, if the current priority was lower or equal to the given one, false otherwise.

Definition at line 272 of file variable.cpp.

Here is the call graph for this function:

◆ Delete()

void Delete ( )

Deletes a variable. After this method is executed, the internal cursor will be invalid and further operations on this variable instance can only be made after a next declaration.

Definition at line 285 of file variable.cpp.

Here is the call graph for this function:

◆ Export()

AString & Export	(	AString &	dest,
		const StringEscaper *	escaper = nullptr ) const

inline

Exports the contents of this variable to the given buffer. This is done by calling VMeta::exPort on the virtual meta object associated with this variable's type.

Parameters

dest	The destination string. Must not be reset prior writing, but appended.
escaper	The StringEscaper to use for exporting a C++ string to a (probably) escaped string format. Defaults to `nullptr` which indicates that no conversion (aka 'escaping') has to be performed. Usually, if a ConfigurationPlugin invokes this method to write-back the contents of a variable, it would pass its own suitable implementation here.

Returns: dest to allow concatenated operations.

Definition at line 1172 of file configuration.hpp.

Here is the call graph for this function:

◆ Get() [1/2]

template<typename T >

T & Get ( )

inline

Returns a reference to the variable's value. To receive a value the variable has to be defined, which is either done, by

A provision of a default value with declaration,
A configuration plug-in like CLIVariablesPlugin or EnvironmentVariablesPlugin,
Some bootstrap or other code entities like reading external configuration data from 3rd party sources,
or finally "hard coded" with method Define.

If this is not done, in debug-compilations an assertion is raised. In release-builds, it is defined (!) behavior: A default constructed value of T is returned. Hence, the whole concept of defining a variable and methods IsDefined, etc. is rather a contract than a necessity. This is explained in section 4. Variable Definition of the Programmer's Manual of this ALib Camp.

Template parameter T has to be specified in alignment with the declaration of the variable. It is the users responsibility to specify the right type, as internally a reinterpret_cast has to be performed. In other words, providing a wrong type is undefined behavior.

In debug-compilations, an assertion is raised if the type does not match the declaration.

Template Parameters

T	The type to receive.

Returns: A reference to the value of the variable.

Definition at line 1205 of file configuration.hpp.

Here is the call graph for this function:

◆ Get() [2/2]

template<typename T >

const T & Get ( ) const

inline

const-version of overloaded method.

Template Parameters

T	The type to receive.

Returns: A reference to the value of the variable.

Definition at line 1225 of file configuration.hpp.

Here is the call graph for this function:

◆ GetBool()

bool GetBool ( )

inline

Returns: Calls and returns Get<Bool>().

Definition at line 1248 of file configuration.hpp.

◆ GetBox()

Box & GetBox ( )

inline

Returns: Calls and returns Get<AStringPA>().

Definition at line 1252 of file configuration.hpp.

◆ GetConfiguration()

Configuration & GetConfiguration ( ) const

inline

Returns a reference to the configuration this variable resides in.

Returns: The associated configuration instance.

Definition at line 1095 of file configuration.hpp.

◆ GetDeclaration()

const Declaration * GetDeclaration ( ) const

inline

Returns the declaration struct of this variable, in case it was constructed or declared with an overloaded constructor or method Declare, which accepts such struct. Otherwise, a nullptr is returned.

Note: If a variable is doubly declared by two or more code entities (which is the usual case), a first declaration given is stored and returned from now on. If a second, different declaration struct is passed for the same variable, an assertion is raised in debug compilation. Hence, once a declaration is given, it is always available for inspection.

Returns: nullptr, if no declaration struct was given. Otherwise, the singleton declaration object provided.

Definition at line 1091 of file configuration.hpp.

Here is the call graph for this function:

◆ GetDouble()

double GetDouble ( )

inline

Returns: Calls and returns Get<double>().

Definition at line 1251 of file configuration.hpp.

◆ GetFloat()

float GetFloat ( )

inline

Returns: Calls and returns Get<double>() cast to float.

Definition at line 1250 of file configuration.hpp.

◆ GetInt()

integer GetInt ( )

inline

Returns: Calls and returns Get<integer>().

Definition at line 1249 of file configuration.hpp.

◆ getMeta()

VMeta * getMeta ( ) const

inlineprotected

Returns the meta-information object.

Returns: The virtual meta handler.

Definition at line 726 of file configuration.hpp.

Here is the call graph for this function:

◆ GetOrSetDefault() [1/3]

bool GetOrSetDefault	(	bool	value,
		Priority	priority = Priority::DefaultValues )

inline

Convenience method. If IsDefined returns true, the value of this variable is returned. Otherwise the variable gets defined with the given priority and value is imported.

Parameters

value	The value to import in case the variable is not defined.
priority	The priority to set on import in case the variable is not defined. Defaults to DefaultValues.

Returns: false if data of any priority is available in this variable, true if not.

Definition at line 1289 of file configuration.hpp.

◆ GetOrSetDefault() [2/3]

String & GetOrSetDefault	(	const String &	value,
		Priority	priority = Priority::DefaultValues )

inline

Convenience method. If IsDefined returns true, the value of this variable is returned. Otherwise the variable gets defined with the given priority and value is imported.

Parameters

value	The value to import in case the variable is not defined.
priority	The priority to set on import in case the variable is not defined. Defaults to DefaultValues.

Returns: false if data of any priority is available in this variable, true if not.

Definition at line 1273 of file configuration.hpp.

Here is the call graph for this function:

◆ GetOrSetDefault() [3/3]

bool GetOrSetDefault	(	integer	value,
		Priority	priority = Priority::DefaultValues )

inline

Convenience method. If IsDefined returns true, the value of this variable is returned. Otherwise the variable gets defined with the given priority and value is imported.

Parameters

value	The value to import in case the variable is not defined.
priority	The priority to set on import in case the variable is not defined. Defaults to DefaultValues.

Returns: false if data of any priority is available in this variable, true if not.

Definition at line 1305 of file configuration.hpp.

◆ GetPriority()

Priority GetPriority ( ) const

inline

The priority of a variable indicates "who" or "what" defined the variable and provided the current value. It may be defaulted values, values coming from external configuration files, from command line arguments, environment variables or from common code entities ('hard-coded' values). Besides the elements in enumeration Priority, also any value in between may be given. Doing so, allows fine-tuning which entity exacly is allowed to write values. For example, if a variable's priority is set in code to Environment, then environment variables and CLI arguments may still overwrite a value. If set to Environment + 1, then environment variables would not overwrite, but still CLI arguments could.

A priority of Protected disallows any code entity to make further changes, but those that again use this priority.

Returns: The priority setting for this variable, given with the last successful call to Define.

Definition at line 1112 of file configuration.hpp.

Here is the call graph for this function:

◆ GetString() [1/2]

AStringPA & GetString ( )

inline

Returns: Calls and returns Get<AStringPA>().

Definition at line 1253 of file configuration.hpp.

◆ GetString() [2/2]

String & GetString ( int idx )

inline

Parameters

idx	The index of the requested string.

Returns: Calls and returns Get<StringVectorPA>().Lines.at(idx).

Definition at line 1255 of file configuration.hpp.

◆ GetStrings()

StringVectorPA & GetStrings ( )

inline

Returns: Calls and returns Get<StringVectorPA>().

Definition at line 1254 of file configuration.hpp.

◆ Import()

void Import	(	const String &	src,
		Priority	priority,
		const StringEscaper *	escaper = nullptr )

Imports a variable value from a serialized string representation. Internally, this is performed by calling VMeta::imPort on the virtual meta object associated with this variable's type.

Parameters

src	The source string.
priority	The priority of the import. If the variable is already defined in a higher priority, nothing is done.
escaper	The StringEscaper to use for importing an escaped string. Defaults to `nullptr` which indicates that a programmatically defined C++ string is to be parsed. Usually, if a ConfigurationPlugin invokes this method it would pass its own suitable implementation here.

Definition at line 349 of file variable.cpp.

Here is the call graph for this function:

◆ IsDeclared()

bool IsDeclared ( ) const

inline

Returns true if this variable is declared. If false is returned, this the is just a path node inside the StringTree of the Configuration.

false will be returned only if:

An instance of a variable was created with the constructor that only accepts a Configuration instance (an undeclared variable).
An instance of a variable was created with the constructor that accepts a cursor object of a Configuration and this cursor does not point to a declared variable.
Method Try was called on an instance of this type, and the given variable name did not represent a declared variable.

Returns: true if the underlying StringTree::Cursor of the Configuration that this variable is associated with, points to a declared variable. Otherwise false is returned.

Definition at line 979 of file configuration.hpp.

Here is the call graph for this function:

◆ IsDefined()

bool IsDefined ( ) const

inline

This is a shortcut to Priority() != Priority::NONE and thus, this method checks whether any data is defined.
Variables which are declared using a alib::config,Declaration "config,Declaration" that contains a default value, will have this default value parsed and contain a data set of priority DefaultValues.

Returns: true if data of any priority is available in this variable, false if not.

Definition at line 1122 of file configuration.hpp.

Here is the call graph for this function:

◆ IsDefinedExternally()

bool IsDefinedExternally ( ) const

inline

This is a shortcut to Priority() > Priority::Standard and thus, this method checks whether an explicit definition with a priority higher than Standard was performed, which - by contract - is done only when external data sources are read, for example configuration files, environment variables, or command line parameters.

Returns: true if data contained has a higher priority than Standard, false if not.

Definition at line 1142 of file configuration.hpp.

◆ IsNotDefined()

bool IsNotDefined ( ) const

inline

This is the negation of method IsDefined.

Returns: false if data of any priority is available in this variable, true if not.

Definition at line 1132 of file configuration.hpp.

◆ Name()

AString & Name ( AString & target ) const

inline

Assembles the variable's name from its path within the internal StringTree.

Parameters

target The string buffer to append this variable's name to.

Returns: The given AString to allow concatenated operations.

Definition at line 1043 of file configuration.hpp.

Here is the call graph for this function:

◆ operator bool()

operator bool ( )

inline

Returns: Calls and returns Get<Bool>().

Definition at line 1241 of file configuration.hpp.

◆ operator const String &()

operator const String & ( )

inline

Returns: Calls and returns Get<AStringPA>().

Definition at line 1245 of file configuration.hpp.

◆ operator const Substring()

operator const Substring ( )

inline

Returns: Calls and returns Get<AStringPA>().

Definition at line 1246 of file configuration.hpp.

◆ operator double()

operator double ( )

inline

Returns: Calls and returns Get<double>().

Definition at line 1244 of file configuration.hpp.

◆ operator float()

operator float ( )

inline

Returns: Calls and returns Get<double>() cast to float.

Definition at line 1243 of file configuration.hpp.

◆ operator integer()

operator integer ( )

inline

Returns: Calls and returns Get<integer>().

Definition at line 1242 of file configuration.hpp.

◆ operator=() [1/5]

bool operator= ( bool val )

inline

Calls Get<Bool>() and assigns val.

Parameters

val	The value to assign.

Returns: The val given.

Definition at line 1258 of file configuration.hpp.

◆ operator=() [2/5]

const String & operator= ( const String & val )

inline

Calls Get<AStringPA>() and resets the string to val.

Parameters

val	The value to assign.

Returns: The val given.

Definition at line 1262 of file configuration.hpp.

◆ operator=() [3/5]

double operator= ( double val )

inline

Calls Get<double>() and assigns val.

Parameters

val	The value to assign.

Returns: The val given.

Definition at line 1261 of file configuration.hpp.

◆ operator=() [4/5]

float operator= ( float val )

inline

Calls Get<double>() and assigns val.

Parameters

val	The value to assign.

Returns: The val given.

Definition at line 1260 of file configuration.hpp.

◆ operator=() [5/5]

integer operator= ( integer val )

inline

Calls Get<integer>() and assigns val.

Parameters

val	The value to assign.

Returns: The val given.

Definition at line 1259 of file configuration.hpp.

◆ Size()

int Size ( )

inline

Returns: Calls and returns Get<StringVectorPA>().Lines.size().

Definition at line 1256 of file configuration.hpp.

◆ substitute()

const String & substitute	(	const String &	importString,
		AString &	buf,
		const StringEscaper *	escaper )

protected

Performs variable substitution. This method is called before any call to VMeta::imPort.

Parameters

importString	The import string.
buf	The substitution buffer.
escaper	The escaper used to externalize substitution values.

Returns: Either the original import string, or a reference to the given buffer containing the substituted copy.

Definition at line 18 of file variable.cpp.

Here is the call graph for this function:

◆ Try() [1/3]

bool Try ( const Declaration * decl )

Tries to move the underlying StringTree::Cursor of the Configuration that this variable is associated with, to the variable name found with given declaration. If this succeeds, it is checked if the variable has no declaration record set, and if not, the one given is stored with the variable.

Note: This method automatically declares and defines variables, for which an preset value is set.

Parameters

decl	The declaration of the variable to use.

Returns: true if the variable name specified with the given declaration existed and was declared, or if a preset value existed. Otherwise false is returned and the variable's value is not allowed to be accessed.

Definition at line 330 of file variable.cpp.

Here is the call graph for this function:

◆ Try() [2/3]

bool Try ( const String & name )

inline

Tries to move the underlying StringTree::Cursor of the Configuration that this variable is associated with, to the given path (aka variable name). If this succeeds, the result of IsDeclared() is returned. Otherwise false.

Note that this method still returns false if a preset value exists for the variable, because preset values can only be imported if a variable's type is known, hence when a variable is declared. But this method explicitly avoids declarations.

See also: Overloaded versions, which declare and define a variable if a preset exists.

Parameters

name	The name of the variable to try.

Returns: true if the variable name specified with the given declaration existed and was declared. Otherwise false is returned and the variable's value is not allowed to be accessed.

Definition at line 996 of file configuration.hpp.

Here is the call graph for this function:

◆ Try() [3/3]

bool Try	(	const String &	name,
		const String &	typeName )

Tries to move the underlying StringTree::Cursor of the Configuration that this variable is associated with, to the given path (aka variable name).

Note: This method automatically declares and defines variables, for which an preset value is set.

Parameters

name	The name of the variable.
typeName	The type of the variable.

Returns: true if the variable name specified with the given declaration existed and was declared. Otherwise false is returned and the variable's value is not allowed to be accessed.

Definition at line 295 of file variable.cpp.

Here is the call graph for this function:

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

Description:

Public Method Index:

Protected Method Index:

Private Type Index:

Additional Inherited Members

Friends And Related Entity Details:

◆ alib::config::Configuration

Type Definition Details:

◆ Cursor

Constructor(s) / Destructor Details:

◆ Variable() [1/14]

◆ Variable() [2/14]

◆ Variable() [3/14]

◆ Variable() [4/14]

◆ Variable() [5/14]

◆ Variable() [6/14]

◆ Variable() [7/14]

◆ Variable() [8/14]

◆ Variable() [9/14]

◆ Variable() [10/14]

◆ Variable() [11/14]

◆ Variable() [12/14]

◆ Variable() [13/14]

◆ Variable() [14/14]

Method Details:

◆ AsCursor() [1/2]

◆ AsCursor() [2/2]

◆ create()

◆ Declare() [1/4]

◆ Declare() [2/4]

◆ Declare() [3/4]

◆ Declare() [4/4]

◆ Define()

◆ Delete()

◆ Export()

◆ Get() [1/2]

◆ Get() [2/2]

◆ GetBool()

◆ GetBox()

◆ GetConfiguration()

◆ GetDeclaration()

◆ GetDouble()

◆ GetFloat()

◆ GetInt()

◆ getMeta()

◆ GetOrSetDefault() [1/3]

◆ GetOrSetDefault() [2/3]

◆ GetOrSetDefault() [3/3]

◆ GetPriority()

◆ GetString() [1/2]

◆ GetString() [2/2]

◆ GetStrings()

◆ Import()

◆ IsDeclared()

◆ IsDefined()

◆ IsDefinedExternally()

◆ IsNotDefined()

◆ Name()

◆ operator bool()

◆ operator const String &()

◆ operator const Substring()

◆ operator double()

◆ operator float()

◆ operator integer()

◆ operator=() [1/5]

◆ operator=() [2/5]

◆ operator=() [3/5]

◆ operator=() [4/5]

◆ operator=() [5/5]

◆ Size()

◆ substitute()

◆ Try() [1/3]

◆ Try() [2/3]

◆ Try() [3/3]