Description:

This class is the container for ALib variables.
The use of this type is documented with the Programmer's Manual of camp ALib Variables.

Beside the interface that this class provides, publicly inherited interfaces of base types StringTree and PluginContainer are available for use.

See also: Note that a general configuration object is provided with ALib Camps. Usually one instance is shared between all ALib Camps. By customizing the bootstrap process, dedicated configuration instances for built-in or custom ALib Camps can be created.

Definition at line 205 of file configuration.inl.

Inheritance diagram for alib::variables::Configuration:

[legend]

Collaboration diagram for alib::variables::Configuration:

[legend]

Inner Type Index:
struct	ListenerRecord
	Record used to manage registered listeners. More...

struct	ValueDescriptorRD
	Helper-struct used for implementing field replacementDeclarations. More...

struct	ValueDescriptorTypes
	Helper-struct used for implementing field types. More...

Public Field Index:
List< MonoAllocator, std::pair< Token, Token >, Recycling::None >	BooleanTokens

StringEscaperStandard	Escaper

alib::NumberFormat	NumberFormat

PoolAllocator	Pool

CString	SubstitutionVariableDelimiters = A_CHAR(" $@,.;:\"\'+-*\\§%&()[]{}<>=?'`~#")

String	SubstitutionVariableEnd = A_CHAR("}")

String	SubstitutionVariableStart = A_CHAR("${")

Public Method Index:
ALIB_DLL	Configuration (MonoAllocator &allocator, lang::CreateDefaults createDefaults=lang::CreateDefaults::Yes)

ALIB_DLL	~Configuration ()
	Destructor.

ALIB_DLL bool	DeletePath (const String &path)

void	MonitorDistinctVariable (lang::ContainerOp insertOrRemove, ConfigurationListener *listener, ConfigurationListener::Event event, const Variable &variable)

void	MonitorPath (lang::ContainerOp insertOrRemove, ConfigurationListener *listener, ConfigurationListener::Event event, const Configuration::Cursor &cursor)

void	MonitorPathPrefix (lang::ContainerOp insertOrRemove, ConfigurationListener *listener, ConfigurationListener::Event event, const String &pathPrefix)

void	MonitorPathSubstring (lang::ContainerOp insertOrRemove, ConfigurationListener *listener, ConfigurationListener::Event event, const String &pathSubstring)

ALIB_DLL int	MonitorStop (ConfigurationListener *listener)

void	MonitorVariablesByName (lang::ContainerOp insertOrRemove, ConfigurationListener *listener, ConfigurationListener::Event event, const String &variableName)

ALIB_DLL std::pair< bool, int8_t >	ParseBooleanToken (const String &src)

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

void	PresetImportString (const String &name, const String &value, Priority priority=Priority::DefaultValues)

void	PresetImportString (const String &name, const String &value, StringEscaper *escaper, Priority priority=Priority::DefaultValues)

template<typename TVMeta>
void	RegisterType ()

ALIB_DLL const Declaration *	StoreDeclaration (const Declaration *orig, const Box &replacements)

ALIB_DLL AString &	WriteBooleanToken (bool value, int8_t index, AString &dest)

Public Method Index: inherited from alib::containers::StringTree< TAllocator, T, TNodeHandler, TRecycling >
	StringTree (AllocatorType &allocator, CharacterType pathSeparator)

	StringTree (AllocatorType &allocator, CharacterType pathSeparator)

	StringTree (CharacterType pathSeparator, TSharedRecycler &pRecycler)

	StringTree (CharacterType pathSeparator, TSharedRecycler &pRecycler)

	~StringTree ()

	~StringTree ()

void	Clear ()

void	Clear ()

void	ConstructRootValue (TArgs &&... args)

void	ConstructRootValue (TArgs &&... args)

void	DbgSetDCSName (const char *name) const

void	DbgSetDCSName (const char *name) const

void	DestructRootValue ()

void	DestructRootValue ()

AllocatorType &	GetAllocator () noexcept

AllocatorType &	GetAllocator () noexcept

ConstCursor	ImportCursor (ConstCursorHandle handle)

ConstCursor	ImportCursor (ConstCursorHandle handle)

Cursor	ImportCursor (CursorHandle handle)

Cursor	ImportCursor (CursorHandle handle)

bool	IsEmpty () const

bool	IsEmpty () const

auto &	NodeTable ()

auto &	NodeTable ()

const auto &	NodeTable () const

const auto &	NodeTable () const

integer	RecyclablesCount () const

integer	RecyclablesCount () const

void	ReserveRecyclables (integer qty, lang::ValueReference reference)

void	ReserveRecyclables (integer qty, lang::ValueReference reference)

void	Reset ()

void	Reset ()

Cursor	Root ()

Cursor	Root ()

const ConstCursor	Root () const

const ConstCursor	Root () const

constexpr CharacterType	Separator () const noexcept

constexpr CharacterType	Separator () const noexcept

integer	Size () const

integer	Size () const

Public Method Index: inherited from alib::lang::PluginContainer< ConfigurationPlugin, Priority >
	~PluginContainer ()

integer	CountPlugins ()

ConfigurationPlugin *	GetPlugin (integer number)

ConfigurationPlugin *	GetPlugin (Priority priority)

TPluginType *	GetPluginTypeSafe ()

TPluginType *	GetPluginTypeSafe (Priority priority)

Priority	GetPriority (integer number)

bool	HasPlugins ()

void	InsertPlugin (ConfigurationPlugin *plugin, lang::Responsibility responsibility=lang::Responsibility::KeepWithSender)

bool	RemovePlugin (ConfigurationPlugin *plugIn)

void	RemovePlugin (integer idx)

ConfigurationPlugin *	RemovePlugin (Priority priority)

Protected Type Index:
using	RDHashTable

using	TypesHashTable
	A hashtable for the registered types. Key is the type name, value is the VMeta singleton.

Protected Type Index: inherited from alib::containers::detail::StringTreeBase< TAllocator, T, TNodeHandler, TRecycling >
using	CharacterType = typename TNodeHandler::CharacterType

using	ConstCursorBase = TCursorBase<true>
	The constant version of type StringTreeBase::TCursorBase<TConst>.

using	CursorBase = TCursorBase<false>
	The mutable version of type StringTreeBase::TCursorBase<TConst>.

using	NameStorageType = typename TNodeHandler::NameStringType

using	NameType = const strings::TString<CharacterType>
	The string-type of node names and paths if provided externally for comparison.

using	NodeList = lang::BidiListHook<NodeBase>
	Alias shortcut for a bidirectional list of Node elements.

using	SharedRecyclerType = typename decltype(nodeTable)::SharedRecyclerType

using	SubstringType = typename strings::TSubstring<CharacterType>

Protected Field Index:
ConfigurationPlugin *	cliPlugin
	A default plugin created and inserted with construction.

ConfigurationPlugin *	environmentPlugin
	A default plugin created and inserted with construction.

List< MonoAllocator, ListenerRecord >	listeners
	The list of registered listeners.

RDHashTable	replacementDeclarations

TypesHashTable	types
	A hashtable for the registered types. Key is the type name, value is the VMeta singleton.

Protected Field Index: inherited from alib::containers::detail::StringTreeBase< TAllocator, T, TNodeHandler, TRecycling >
int	dbgRootDataSet = 0

HashTable< TAllocator, typename NodeKey::ValueDescriptor, typename NodeKey::Hash, typename NodeKey::EqualTo, lang::Caching::Enabled, TRecycling >	nodeTable

RootNodeSpacer	root
	The root node.

CharacterType	separator

Protected Field Index: inherited from alib::lang::PluginContainer< ConfigurationPlugin, Priority >
PluginList	plugins
	The plug-ins we have attached in descending priority order.

Protected Method Index:
ALIB_DLL void	notifyListeners (int event, const Variable &variable, const String &variablePath, Priority previousPriority)

ALIB_DLL void	presetImportString (const String &name, const String &value, const StringEscaper *escaper, Priority priority)

ALIB_DLL void	registerListener (ConfigurationListener listener, lang::ContainerOp insertOrRemove, int event, const Variable variable, const StringTree::Cursor *subTree, const String &variableName, const String &pathPrefix, const String &pathSubstring)

template<typename TVMeta>
void	registerType ()

Protected Method Index: inherited from alib::containers::StringTree< TAllocator, T, TNodeHandler, TRecycling >
Cursor	createCursor (baseNode &node)

Cursor	createCursor (baseNode &node)

Protected Method Index: inherited from alib::containers::detail::StringTreeBase< TAllocator, T, TNodeHandler, TRecycling >
	StringTreeBase (TAllocator &allocator, CharacterType pathSeparator)

template<typename TSharedRecycler = SharedRecyclerType> requires ( !std::same_as<TSharedRecycler , void> )
	StringTreeBase (TAllocator &allocator, TSharedRecycler &pRecycler, CharacterType pathSeparator)

template<typename TSharedRecycler = SharedRecyclerType> requires (!std::same_as<TSharedRecycler, void>)
	StringTreeBase (TSharedRecycler &pRecycler, CharacterType pathSeparator)

bool	checkChildName (const NameType &name) const

TAllocator &	GetAllocator () noexcept

Private Type Index:
using	base = StringTree<MonoAllocator,detail::Entry, detail::ConfigNodeHandler>
	Alias to the StringTree-parent.

Additional Inherited Members
Public Type Index: inherited from alib::containers::StringTree< TAllocator, T, TNodeHandler, TRecycling >
using	AllocatorType
	Type definition publishing template parameter TAllocator.

using	CharacterType

using	ConstCursor
	The constant version of type TCursor<TConst>.

using	ConstRecursiveIterator
	The constant version of type TRecursiveIterator.

using	Cursor
	The mutable version of type TCursor<TConst>.

using	HandlerType
	Type definition publishing template parameter TNodeHandler.

using	NameType

using	RecursiveIterator
	The mutable version of type TRecursiveIterator.

using	SharedRecyclerType

using	SubstringType

Public Type Index: inherited from alib::lang::PluginContainer< ConfigurationPlugin, Priority >
using	PluginList
	The list that stores the plugins.

using	PluginType
	This exposes the template parameter pTPlugin to the outer world.

using	PrioritiesType
	This exposes the template parameter pTPlugin to the outer world.

Friends And Related Entity Details:

◆ detail::ConfigNodeHandler

friend struct detail::ConfigNodeHandler

friend

Definition at line 214 of file configuration.inl.

◆ detail::Entry

friend class detail::Entry

friend

Definition at line 213 of file configuration.inl.

◆ Variable

friend class Variable

friend

Type alias in namespace alib.

Definition at line 212 of file configuration.inl.

Type Definition Details:

◆ base

using alib::variables::Configuration::base = StringTree<MonoAllocator,detail::Entry, detail::ConfigNodeHandler>

private

Alias to the StringTree-parent.

Definition at line 209 of file configuration.inl.

◆ RDHashTable

using alib::variables::Configuration::RDHashTable

protected

Initial value:

 HashTable< MonoAllocator  ,   
                       ValueDescriptorRD         ,   
                       std::hash    <String>     ,   
                       std::equal_to<String>     ,   
                       lang::Caching::Disabled   ,   
                       Recycling::None           >

Type definition of the container that stores declarations allocated with method Configuration::StoreDeclaration.

Definition at line 279 of file configuration.inl.

◆ TypesHashTable

using alib::variables::Configuration::TypesHashTable

protected

Initial value:

 HashTable<MonoAllocator            ,
                                    ValueDescriptorTypes     ,
                                    std::hash<String>        ,
                                    std::equal_to<String>    ,
                                    lang::Caching::Enabled   ,
                                    Recycling::None          >

A hashtable for the registered types. Key is the type name, value is the VMeta singleton.

Definition at line 257 of file configuration.inl.

Field Details:

◆ BooleanTokens

List<MonoAllocator, std::pair<Token,Token>, Recycling::None> alib::variables::Configuration::BooleanTokens

This is a list that holds pairs of type strings::util::Token which is used by the built-in boolean variable type (type name "B"). The list defines how extern string data (for example, from command line args, environment variables, or INI-files) is converted to boolean values.

When parsed from outside, the index of the pair that had the match is stored and in the case of writing back (e.g., to the INI-file), the corresponding representation of this pair will be written out. (For example, if a user used "On" in the configuration file, and the software switched it to false, the word "Off" is to be written.

During bootstrap, this list might be modified, but before any variable was read. Otherwise the indices would become invalid. However, the preferred way of changing the accepted tokens is to modify the resources. This allows having localization of terms, in case this should be needed some day.

If even with modification of the predefined list, some other needs or flexibility is wanted, then the definition of an alternative boolean configuration variable type is the way to go.

The list of resourced predefined tokens after construction of a configuration is:

Index	True Token	False Token
0	`false I 1`	`true I 1`
1	`0 I 1`	`1 I 1`
2	`no I 1`	`yes I 1`
3	`off I 3`	`on I 2`
4	`— I 1`	`OK I 2`

See also: Methods ParseBooleanToken and WriteBooleanToken.

Definition at line 400 of file configuration.inl.

◆ cliPlugin

ConfigurationPlugin* alib::variables::Configuration::cliPlugin

protected

A default plugin created and inserted with construction.

Definition at line 241 of file configuration.inl.

◆ environmentPlugin

ConfigurationPlugin* alib::variables::Configuration::environmentPlugin

protected

A default plugin created and inserted with construction.

Definition at line 244 of file configuration.inl.

◆ Escaper

StringEscaperStandard alib::variables::Configuration::Escaper

A standard string escaper that can be used to set preset values received from external escaped strings.

Definition at line 351 of file configuration.inl.

◆ listeners

List<MonoAllocator, ListenerRecord> alib::variables::Configuration::listeners

protected

The list of registered listeners.

Definition at line 292 of file configuration.inl.

◆ NumberFormat

alib::NumberFormat alib::variables::Configuration::NumberFormat

Number format definition used to read and write int and float values. Can be tweaked to change the way external information is parsed.

Definition at line 347 of file configuration.inl.

◆ Pool

PoolAllocator alib::variables::Configuration::Pool

An object pool for recycling variable values as well as the hashtable entries. It is chained to the allocator provided with construction.

The pool may be used in accordance with the general rules imposed by camp ALib Monomem. If so, in multithreaded environments, this configuration has to be locked (in addition to all other custom locks when interfacing this type), when using this pool from custom code.

Definition at line 224 of file configuration.inl.

◆ replacementDeclarations

RDHashTable alib::variables::Configuration::replacementDeclarations

protected

A hashtable for declarations allocated with method Configuration::StoreDeclaration.

Definition at line 289 of file configuration.inl.

◆ SubstitutionVariableDelimiters

CString alib::variables::Configuration::SubstitutionVariableDelimiters = A_CHAR(" $@,.;:\"\'+-*\\§%&()[]{}<>=?'`~#")

The delimiters used to identify the end of a substitutable variable. If field SubstitutionVariableEnd is not empty, this field is ignored. Otherwise, all characters defined in this string are used to identify the end of a substitution variable.

Definition at line 368 of file configuration.inl.

◆ SubstitutionVariableEnd

String alib::variables::Configuration::SubstitutionVariableEnd = A_CHAR("}")

The end of a substitution variables. If this field is set, then field SubstitutionVariableDelimiters is ignored. If this field is nullptr (the default) or empty, it is ignored and characters in field SubstitutionVariableDelimiters are used to identify the end of the variable.

Definition at line 362 of file configuration.inl.

◆ SubstitutionVariableStart

String alib::variables::Configuration::SubstitutionVariableStart = A_CHAR("${")

The start string to identify substitution variables. Defaults to single character '$'. If a string is set, i.e., "${", then field SubstitutionVariableEnd may be set accordingly, i.e., "}"

Definition at line 356 of file configuration.inl.

◆ types

TypesHashTable alib::variables::Configuration::types

protected

A hashtable for the registered types. Key is the type name, value is the VMeta singleton.

Definition at line 265 of file configuration.inl.

Constructor(s) / Destructor Details:

◆ Configuration()

alib::variables::Configuration::Configuration	(	MonoAllocator &	allocator,
		lang::CreateDefaults	createDefaults = lang::CreateDefaults::Yes )

Constructs a Configuration.

If addDefaultPlugins is true, registers the initial plug-ins as follows:

Priority	Plug-in Type
Priority::Environment	EnvironmentVariablesPlugin
Priority::CLI	CLIVariablesPlugin

Furthermore all built-in variable types are registered.

Modifications (in respect to plug-ins and registered types) should be performed during bootstrap, right after construction of this type (when no parallel threads are active) or with prior locking the Configuration instance.

Parameters

allocator	The allocator to use.
createDefaults	Determines if default plug-ins are to be created. Defaults to `Yes`.

Definition at line 85 of file configuration.cpp.

Here is the call graph for this function:

◆ ~Configuration()

alib::variables::Configuration::~Configuration ( )

Destructor.

Definition at line 127 of file configuration.cpp.

Here is the call graph for this function:

Method Details:

◆ DeletePath()

bool alib::variables::Configuration::DeletePath ( const String & path )

Deletes the given variable path, respectively all variables under the given path as well as the path node itself.

This is a convenience method. Full access to the underlying StringTree is provided by public inheritance, which offers many other ways of manipulating variable data. As an example, consider the implementation of this method:

// get root node of the tree
Cursor cs= Root();
 
// try to walk the givedn path. If a remainder of the string exits, exit.
if( cs.GoTo(path).IsNotEmpty() )
    return false;
 
// now delete the subtree, including the node the cursor represents
cs.Delete();
 
// that's it
return true;

Parameters

path	The path in the variable tree.

Returns: true on success, false, if the given path was not found.

Definition at line 430 of file configuration.cpp.

Here is the call graph for this function:

◆ MonitorDistinctVariable()

void alib::variables::Configuration::MonitorDistinctVariable	(	lang::ContainerOp	insertOrRemove,
		ConfigurationListener *	listener,
		ConfigurationListener::Event	event,
		const Variable &	variable )

inline

Inserts or removes a listener to a specific variable. Note that this version of the method cannot be used to fetch declaration events, because the given variable obviously is already declared and created.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
variable	The variable to listen to.

See also: Chapter 9. Monitoring Changes of Variables of the Programmer's Manual of camp ALib Variables.

Definition at line 591 of file configuration.inl.

Here is the call graph for this function:

◆ MonitorPath()

void alib::variables::Configuration::MonitorPath	(	lang::ContainerOp	insertOrRemove,
		ConfigurationListener *	listener,
		ConfigurationListener::Event	event,
		const Configuration::Cursor &	cursor )

inline

Inserts or removes a listener for all variables below subtree specified by the given cursor.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
cursor	The parent node in the configuration variable tree of the variables to monitor.

See also: Chapter 9. Monitoring Changes of Variables of the Programmer's Manual of camp ALib Variables.

Definition at line 634 of file configuration.inl.

Here is the call graph for this function:

◆ MonitorPathPrefix()

void alib::variables::Configuration::MonitorPathPrefix	(	lang::ContainerOp	insertOrRemove,
		ConfigurationListener *	listener,
		ConfigurationListener::Event	event,
		const String &	pathPrefix )

inline

Inserts or removes a listener for all variables below the subtree specified by the given startPath.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
pathPrefix	The path prefix of the subtree of variables to monitor. Note that a missing leading separator character `'/'` will be added.

See also: Chapter 9. Monitoring Changes of Variables of the Programmer's Manual of camp ALib Variables.

Definition at line 658 of file configuration.inl.

Here is the call graph for this function:

◆ MonitorPathSubstring()

void alib::variables::Configuration::MonitorPathSubstring	(	lang::ContainerOp	insertOrRemove,
		ConfigurationListener *	listener,
		ConfigurationListener::Event	event,
		const String &	pathSubstring )

inline

Inserts or removes a listener for all variables below the subtree specified by the given startPath.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
pathSubstring	The substring to match in the path (including the variable name) of the variables to monitor.

See also: Chapter 9. Monitoring Changes of Variables of the Programmer's Manual of camp ALib Variables.

Definition at line 681 of file configuration.inl.

Here is the call graph for this function:

◆ MonitorStop()

int alib::variables::Configuration::MonitorStop ( ConfigurationListener * listener )

Removes all registrations of the given listener.

Parameters

listener The listener to remove.

Returns: The number of registrations that have been removed.

See also: Chapter 9. Monitoring Changes of Variables of the Programmer's Manual of camp ALib Variables.

Definition at line 194 of file configuration.cpp.

◆ MonitorVariablesByName()

void alib::variables::Configuration::MonitorVariablesByName	(	lang::ContainerOp	insertOrRemove,
		ConfigurationListener *	listener,
		ConfigurationListener::Event	event,
		const String &	variableName )

inline

Inserts or removes a listener for all variables that share the given variableName.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
variableName	The name of one or more variables to listen to.

See also: Chapter 9. Monitoring Changes of Variables of the Programmer's Manual of camp ALib Variables.

Definition at line 613 of file configuration.inl.

Here is the call graph for this function:

◆ notifyListeners()

void alib::variables::Configuration::notifyListeners	(	int	event,
		const Variable &	variable,
		const String &	variablePath,
		Priority	previousPriority )

protected

Notifies registered listeners on events.

Parameters

event	The event that occurred.
variable	The variable.
variablePath	The full path of the variable. Might be nulled if not available, yet.
previousPriority	The priority of the variable before the event.

Definition at line 213 of file configuration.cpp.

Here is the call graph for this function:

◆ ParseBooleanToken()

std::pair< bool, int8_t > alib::variables::Configuration::ParseBooleanToken ( const String & src )

Utility method that checks if a given value represents boolean true.

See also: Field BooleanTokens, which is used by this function and sibling method WriteBooleanToken

Parameters

src	The input string to check.

Returns: Returns the value found and the index of the pair of tokens that matched. If no token matched (false,-1) is returned.

Definition at line 396 of file configuration.cpp.

Here is the call graph for this function:

◆ PreloadVariables()

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

void alib::variables::Configuration::PreloadVariables ( )

Declares and defines all variables of the given enum type which do not contain placeholders are contained in the variable's name.

The purpose of this method is to fill the configuration system with variables (usually during or right after bootstrap) regardless of their later use, which depends on the concrete execution path of a run of software. The rationale to do this is is twofold:

To allow external configuaration plug-ins to set all variable's values, which is not possible if a variable is not declared, yet, and thus its type is not known. In that case, an external source can only use method Configuration::PresetImportString, which in the end leads to correctly setting a variable's external value, but which creates a little overhead in respect to execution time and memory consumption.
To give external configuaration plug-ins the possibiltiy to "populate" their files with all known variables, including their default values and comments, again independently from a concrete excution path of a run of the software, which might not declare certain variables and thus those would not be "known" to the external source. Populating external configuration files (with the first run of software), tremendously supports an end-user in learning about configuration options.
For example, built-in class IniFileFeeder supports such "population" of for INI-fles through its Export methods.

Altogether, the use of this method does not not impose much of an overhead, because:

as explained above, the need of method Configuration::PresetImportString is avoided for all variables that do not contain placeholders, and because
most variables would anyhow be declared later during the run of software and thus, this declaration is just performed earlier and the variable are already in place when software later uses them.

See also: Chapter 7.3 Built-in Class IniFileFeeder of the Programmer's Manual of camp ALib Variables.

Template Parameters

TEnum Enumeration type equipped with ALib Enum Records of type Declaration.

◆ PresetImportString() [1/2]

void alib::variables::Configuration::PresetImportString	(	const String &	name,
		const String &	value,
		Priority	priority = Priority::DefaultValues )

inline

Same as overloaded version PresetImportString(const String&, const String&,StringEscaper*, Priority), but does not accept an StringEscaper and thus expects the value is in C++ internal string format (aka 'not escaped').

Parameters

name	The name of the variable.
value	The value to import.
priority	The priority to set for the value. Defaults to Default.

Definition at line 534 of file configuration.inl.

Here is the call graph for this function:

◆ PresetImportString() [2/2]

void alib::variables::Configuration::PresetImportString	(	const String &	name,
		const String &	value,
		StringEscaper *	escaper,
		Priority	priority = Priority::DefaultValues )

inline

Stores the given information as a default value, which will be assigned to a variable as soon as it is declared. If a variable is deleted and later again declared, the given value is again imported. In other words, a preset will not be removed with a first declaration and use.
To delete a previously set import string, a nulled string is to be passed with for parameter value.

This method is to be used in cases when a declaration of a variable is not possible, i.e., when a variable's type is not known, which often is the case when external configuration values are to be set.

See also

Overloaded public methods PresetImportString.
Chapter 7.3 Built-in Class IniFileFeeder of the Programmer's Manual of camp ALib Variables.

Parameters

name	The name of the variable.
value	The value to import. Will be 'unescaped' using escaper.
escaper	The escaper to use for importing. Has to be still valid at the time(s) the value read. A pointer to field Escaper might be passed here.
priority	The priority to set for the value. Defaults to Default.

Definition at line 522 of file configuration.inl.

Here is the call graph for this function:

◆ presetImportString()

void alib::variables::Configuration::presetImportString	(	const String &	name,
		const String &	value,
		const StringEscaper *	escaper,
		Priority	priority )

protected

Stores the given information as a default value, which is imported to a variable as soon as it becomes declared.

See also: Overloaded public methods Configuration::PresetImportString.

Parameters

name	The name of the variable.
value	The value to import.
escaper	The escaper to use for importing.
priority	The priority to set for the value.

Definition at line 248 of file configuration.cpp.

Here is the call graph for this function:

◆ registerListener()

void alib::variables::Configuration::registerListener	(	ConfigurationListener *	listener,
		lang::ContainerOp	insertOrRemove,
		int	event,
		const Variable *	variable,
		const StringTree::Cursor *	subTree,
		const String &	variableName,
		const String &	pathPrefix,
		const String &	pathSubstring )

protected

Implements the various overloaded listener registration methods.

Parameters

listener	The listener to register or dispose.
insertOrRemove	Denotes registration or disposal of a listener.
event	The event to listen to.
variable	If given, the exported value of the variable to listen to.
subTree	If given, the exported value of the subtree of variables to listen to.
variableName	If given, the variable's name to listen to.
pathPrefix	If given, the start string of the path of the variables to monitor.
pathSubstring	If given, the substring to match in the path (including the variable name) of the variables to monitor.

Definition at line 137 of file configuration.cpp.

Here is the call graph for this function:

◆ RegisterType()

template<typename TVMeta>

void alib::variables::Configuration::RegisterType ( )

inline

Registers a variable type with this configuration. The only parameter is the template parameter TVMeta. The function will create the singleton of this type and store it in a hash table of types. When a variable associated with this configuration object is declared, this variable type is used as the key to this hash table. Then this singleton object of the given type is responsible for construction, destruction and import/export of variables of this type.

Template Parameters

TVMeta The meta-information type of the type to register.

Definition at line 438 of file configuration.inl.

Here is the call graph for this function:

◆ registerType()

template<typename TVMeta>

void alib::variables::Configuration::registerType ( )

inlineprotected

Implementation of Configuration::RegisterType.

Template Parameters

TVMeta The meta-information type of the type to register.

Definition at line 298 of file configuration.inl.

Here is the call graph for this function:

◆ StoreDeclaration()

const Declaration * alib::variables::Configuration::StoreDeclaration	(	const Declaration *	orig,
		const Box &	replacements )

Creates and stores a declaration. Placeholders "%1", "%2" ... "%N" found in the fields (except typeName) are replaced with the replacement values given with boxed argument (list) replacements.

Attention: This method creates a copy a new declaration instance within the monotonic allocator of this Configuration object. This imposes a potential memory drain (leak). To mitigate the problem and widen the use cases, this method uses a hashtable to cache the resulting declarations. This means, that only for combinations of parameters that result to a different variable name, a declaration is created.

See also: Chapter 2.4 Placeholders in Variable Names of the Programmer's Manual of camp ALib Variables.

Parameters

orig	The original, typically resourced declaration with placeholders.
replacements	A list of replacement values. Must be of boxed types that are alib::strings,AppendableTraits,appendable "strings,AppendableTraits,appendable" to class AString. To provide more than one object, pass an object of class alib::boxing,Boxes "boxing,Boxes" or a boxed array.

Returns: The allocated (or cached) copy of orig.

Definition at line 311 of file configuration.cpp.

Here is the call graph for this function:

◆ WriteBooleanToken()

AString & alib::variables::Configuration::WriteBooleanToken	(	bool	value,
		int8_t	index,
		AString &	dest )

Utility method that writes the given boolean value as specified with the token found at index in BooleanTokens.
This method is used internally by the meta-information handler of variable type "B"/bool.

See also: Sibling method ParseBooleanToken.

Parameters

value	The boolean value to write.
index	The token to use. If negative, this is corrected to `0`.
dest	The destination string.

Returns: dest to allow concatenated operations.

Definition at line 412 of file configuration.cpp.

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

Description:

Inner Type Index:

Public Field Index:

Public Method Index:

Protected Type Index:

Protected Field Index:

Protected Method Index:

Private Type Index:

Additional Inherited Members

Friends And Related Entity Details:

◆ detail::ConfigNodeHandler

◆ detail::Entry

◆ Variable

Type Definition Details:

◆ base

◆ RDHashTable

◆ TypesHashTable

Field Details:

◆ BooleanTokens

◆ cliPlugin

◆ environmentPlugin

◆ Escaper

◆ listeners

◆ NumberFormat

◆ Pool

◆ replacementDeclarations

◆ SubstitutionVariableDelimiters

◆ SubstitutionVariableEnd

◆ SubstitutionVariableStart

◆ types

Constructor(s) / Destructor Details:

◆ Configuration()

◆ ~Configuration()

Method Details:

◆ DeletePath()

◆ MonitorDistinctVariable()

◆ MonitorPath()

◆ MonitorPathPrefix()

◆ MonitorPathSubstring()

◆ MonitorStop()

◆ MonitorVariablesByName()

◆ notifyListeners()

◆ ParseBooleanToken()

◆ PreloadVariables()

◆ PresetImportString() [1/2]

◆ PresetImportString() [2/2]

◆ presetImportString()

◆ registerListener()

◆ RegisterType()

◆ registerType()

◆ StoreDeclaration()

◆ WriteBooleanToken()