Description:

This class is a container for objects of type ConfigurationPlugin, and provides a single user interface to query configuration data from those.

By default, all category and variable names are case insensitive. This is at least true for the default plug-ins delivered with ALib .

Variables by default can contain other variables, which are recursively substituted by this method. For more information about the (adjustable) syntax, see Variable Substitution.

See documentation of namespace alib::config for more information on ALib external configuration variables.

Definition at line 62 of file configuration.hpp.

#include <configuration.hpp>

Inheritance diagram for Configuration:

[legend]

Collaboration diagram for Configuration:

[legend]

Inner Type Index:
class	Iterator

Public Field Index:
alib::NumberFormat	NumberFormat

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

String	SubstitutionVariableEnd = nullptr

String	SubstitutionVariableStart = A_CHAR("$")

Variable	tempVar

std::vector< String >	TrueValues

Public Method Index:
ALIB_API	Configuration (lang::CreateDefaults addPlugins)

ALIB_API int	FetchFromDefault (ConfigurationPlugin &dest, const String &section=NullString())

ALIB_API Iterator *	GetIterator (const String &sectionName)

ALIB_API bool	IsTrue (const String &value)

ALIB_API Priorities	Load (Variable &variable)

ALIB_API integer	LoadFromString (Variable &variable, const String &externalizedValue)

template<typename TEnum >
void	PreloadVariables ()

ALIB_API Priorities	Protect (Variable &variable, const String &externalizedValue=nullptr)

void	SetCommandLineArgs (int argc, const wchar_t **argv)

void	SetCommandLineArgs (int argc=0, const nchar **argv=nullptr)

ALIB_API Priorities	Store (Variable &variable, const String &externalizedValue=nullptr)

ALIB_API Priorities	StoreDefault (Variable &variable, const String &externalizedValue=nullptr)

Public Method Index: inherited from PluginContainer< ConfigurationPlugin, Priorities >
	~PluginContainer ()

integer	CountPlugins ()

TPlugin *	GetPlugin (integer number)

TPlugin *	GetPlugin (TPriorities priority)

TPluginType *	GetPluginTypeSafe ()

TPluginType *	GetPluginTypeSafe (TPriorities priority)

bool	HasPlugins ()

void	InsertPlugin (TPlugin *plugin, TPriorities priority, lang::Responsibility responsibility=lang::Responsibility::KeepWithSender)

void	RemovePlugin (integer idx)

bool	RemovePlugin (TPlugin *plugIn)

TPlugin *	RemovePlugin (TPriorities priority)

Additional Inherited Members
Public Type Index: inherited from PluginContainer< ConfigurationPlugin, Priorities >
using	TPlugin

using	TPriorities

Field Details:

◆ NumberFormat

alib::NumberFormat NumberFormat

Number format definition used to read and write int and float values.

Definition at line 84 of file configuration.hpp.

◆ SubstitutionVariableDelimiters

CString 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 107 of file configuration.hpp.

◆ SubstitutionVariableEnd

String SubstitutionVariableEnd = nullptr

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 99 of file configuration.hpp.

◆ SubstitutionVariableStart

String 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 91 of file configuration.hpp.

◆ tempVar

Variable tempVar

A temporary variable to be reused (allocate once pattern).

Definition at line 110 of file configuration.hpp.

◆ TrueValues

std::vector<String> TrueValues

Values considered to indicate "true". Defaults to { "1", "true", "t", "yes", "y", "on", "ok" }. See methods IsTrue.

Application specific values (e.g. localization languages) might be added by publicly accessing this field and adding new values (or removing existing).

Definition at line 81 of file configuration.hpp.

Constructor(s) / Destructor Details::

◆ Configuration()

Configuration ( lang::CreateDefaults addPlugins )

Constructs a Configuration. If addDefaultPlugins is true, registers the initial plug-ins as follows

Priority	Plug-in Type
Priorities::ProtectedValues	InMemoryPlugin
Priorities::Environment	Environment
Priorities::CLI	CLIArgs
Priorities::DefaultValues	InMemoryPlugin

Parameters

addPlugins If Yes the default plugins are added.

Definition at line 49 of file configuration.cpp.

Here is the call graph for this function:

Method Details:

◆ FetchFromDefault()

int FetchFromDefault	(	ConfigurationPlugin &	dest,
		const String &	section = NullString() )

This method fetches all values from a plug-in of priority Priorities::DefaultValues , which are not present in the given plug-in dest and stores them in that. This is useful to collect all generated default values and store them in a user's configuration file. This way, the user can identify configurable options easily.

Note: Applications might want to copy only a portion of the default values (of a section) to not blow up a user's configuration. To achieve this, a custom method to fetch selected values has to be implemented. In this respect, this method is a very simple default and its source might be used as a jump start.

Parameters

dest	The destination plug-in.
section	Optional string denoting a section to fetch. Defaults to NullString().

Returns: The number of variables fetched.

Definition at line 63 of file configuration.cpp.

Here is the call graph for this function:

◆ GetIterator()

ALIB_API Iterator * GetIterator ( const String & sectionName )

Creates an iterator object to return all variables within a section.

The iterator object returned, needs to be deleted by the caller.

Parameters

sectionName The name of the section to iterate.

Returns: The result of Variable::Size after parsing.

◆ IsTrue()

bool IsTrue ( const String & value )

Utility method that checks if a given value represents boolean true. Uses field TrueValues. Comparisons are made case insensitive.

Parameters

value The value to check

Returns: Returns true, if the value represents 'true', false if not.

Definition at line 90 of file configuration.cpp.

Here is the call graph for this function:

◆ Load()

Priorities Load ( Variable & variable )

Receives and optionally creates configuration variable.

If the variable was not found and Variable::DefaultValue in variable is set, the method adds the value to a plug-in of priority Priorities::DefaultValues , (respectively to the plug-in found at or below DefaultValues). For the conversion of the value, field ConfigurationPlugin::StringConverter of field a plug-in of priority DefaultValues, is used.

If no plug-in at or below priority DefaultValues is found, then the declared default value is added to the variable using the default implementation of XTernalizer::LoadFromString .

Parameters

variable The variable to receive.

Returns: The priority of the configuration plug-in that provided the result. 0 if not found.

Definition at line 104 of file configuration.cpp.

Here is the call graph for this function:

◆ LoadFromString()

integer LoadFromString	(	Variable &	variable,
		const String &	externalizedValue )

Convenience method to set values in variable according to the provided string. For the conversion of the "externalized" string, method XTernalizer::LoadFromString of field ConfigurationPlugin::StringConverter of a plug-in of priority Priorities::DefaultValues , is used.

Parameters

variable	The variable object.
externalizedValue	The new value to write.

Returns: The result of Variable::Size after parsing.

Definition at line 217 of file configuration.cpp.

Here is the call graph for this function:

◆ loadImpl()

Priorities loadImpl	(	Variable &	variable,
		bool	substitute )

protected

Implementation of method Load.

Parameters

variable	The variable to get.
substitute	If `false`, automatic variable substitutions are suppressed.

Returns: Zero if the variable was not found. Otherwise it returns the priority of the (first) plug-in that contained the variable.

Definition at line 230 of file configuration.cpp.

Here is the call graph for this function:

◆ PreloadVariables()

template<typename TEnum >

void PreloadVariables ( )

inline

This method loads all variables of the given enum type in case no placeholders are contained in their name and a default value is given with the declaraition.

With that they become stored in this configuration's default plug-in and a later invocation of FetchFromDefault may be used to move those to a plug-in that persitently stores them, for example an INI-file.

The goal of this approach is to have all (most) variables presented in an external configuration file that is automatically created on a software's first run - regardless if that first run used the variables or not.

Template Parameters

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

◆ Protect()

Priorities Protect	(	Variable &	variable,
		const String &	externalizedValue = nullptr )

Convenience method that stores the variable with priority Priorities::ProtectedValues .

The variable value is determined as follows:

If optional parameter externalizedValue is provided and not nulled, the values are loaded from that string.
Otherwise, if the variable has no values set but Variable::DefaultValue is not nulled then values are loaded from this field.
If all is unset (the variable values, parameter externalizedValue and field Variable::DefaultValue ), then the unset variable is stored, which results in removing an existing protection value from the configuration.

Parameters

variable	The variable object.
externalizedValue	Optional externalized value string. If given, the variable is set prior to writing.

Returns: The result of Configuration::Store .

Definition at line 200 of file configuration.cpp.

Here is the call graph for this function:

◆ SetCommandLineArgs() [1/2]

void SetCommandLineArgs	(	int	argc,
		const wchar_t **	argv )

inline

Variant of method SetCommandLineArgs, accepting command line arguments of type wchar.

Parameters

argc	Parameter usually taken from standard C `main()` method (the number of arguments in argv ).
argv	The command line arguments as a zero-terminated list of pointers to zero-terminated `wchar_c` strings.

Definition at line 171 of file configuration.hpp.

Here is the call graph for this function:

◆ SetCommandLineArgs() [2/2]

void SetCommandLineArgs	(	int	argc = 0,
		const nchar **	argv = nullptr )

inline

Sets the command line arguments for default plug-in CLIArgs . This method should be called for instances of this class after construction.

Note: For the standard configuration objects found in class Camp , this method is automatically invoked by function Bootstrap .; On the Windows platform, the Microsoft compiler provides the global variables __argc and __argv (respectively __wargv for wide character binaries. These variables a can be used if this method is invoked outside of the main() method.

Parameters

argc	Parameter usually taken from standard C `main()` method (the number of arguments in argv ). Defaults to 0.
argv	Parameter usually taken from standard C `main()` method (pointer to a zero-terminated list of zero-terminated strings comprising the command line arguments). Defaults to nullptr.

Definition at line 152 of file configuration.hpp.

Here is the call graph for this function:

◆ Store()

Priorities Store	(	Variable &	variable,
		const String &	externalizedValue = nullptr )

Writes the variable into one of the plug-ins registered with this configuration object. The plug-ins are looped in descending order of priority, until a first plug-in confirms the variable to be written.

The first (most highly prioritized) plug-in to start the loop with, is defined by field Variable::Priority of the given variable .

If this is unset (Priorities::NONE ), which is the default value of the field for freshly declared variable objects, the starting priority value of the loop is detected.

Detection is made by searching the variable in the plug-ins prior to storing it. The search order is likewise by priority, starting with the highest. If the variable was not found, Priorities::DefaultValues is chosen. Usually the writing loop then will also already end there, because standard configuration sets have a write-enabled in-memory plug-in at that priority.

If the variable was found in the plug-in of priority Priorities::ProtectedValues , the method stops without storing anything.

This approach of storing variables, supports various use cases very nicely. Some of the frequent ones shall be named here:

By setting the field to Priorities::DefaultValues , the value becomes just a default and does not overwrite externally specified values.
Leaving the field to its uninitialized state Priorities::NONE , allows to store the variable in the plug-in that it was originally read from, or - if not stored already - in default values.
Setting the field to Priorities::ProtectedValues allows to protect the variable value in respect to external manipulation.
Setting the field to Priorities::ProtectedValues - 1, allows to store the variable just in the plug-in with highest possible priority.
Finally, an application specific reason might motivate a caller of this method to preset a distinct priority value prior to invoking this method. For example, a variable might be related to a second one. If the priority of the second one is known, that priority might be set prior to invoking this message, to have both variables potentially stored in the same plug-in.

The method returns the priority of the configuration plug-in that the value was written to. This value is as well stored in field Variable::Priority of the given object.

A result of Priorities::NONE indicates that the variable was not written. This might only happen if

the default plug-in of this configuration is not configured or does not support writing variables,
field Priority of the variable was set below Priorities::DefaultValues (but greater than Priorities::NONE ),
the detected priority was Priorities::ProtectedValues . (In this case, obviously the application does not want to allow changes and writing the variable into a different plug-in has no effect. This way, such variables also do not appear in a user's configuration in the case that on program termination, new default values are copied there.)

Optional parameter externalizedValue allows to provide a string that is parsed by the storing plug-in to reset the variable's values prior to writing.

See also: Default variables are often to be stored with the termination of a process. For this, see method FetchFromDefault.

Parameters

variable	The variable object.
externalizedValue	Optional externalized value string. If given, the variable is set prior to writing.

Returns: The priority of the configuration plug-in that the value was written to.

Definition at line 123 of file configuration.cpp.

Here is the call graph for this function:

◆ StoreDefault()

Priorities StoreDefault	(	Variable &	variable,
		const String &	externalizedValue = nullptr )

Convenience method that stores the variable with priority Priorities::DefaultValues .

The variable value is determined as follows:

If optional parameter externalizedValue is provided and not nulled, the values are loaded from that string.
Otherwise, if the variable has no values set but Variable::DefaultValue is not nulled then values are loaded from this field.
If all is unset (the variable values, parameter externalizedValue and field Variable::DefaultValue ), then the unset variable is stored, which results in removing an existing default value from the configuration.

Parameters

variable	The variable object.
externalizedValue	Optional externalized value string. If given, the variable is set prior to writing.

Returns: The result of Configuration::Store .

Definition at line 184 of file configuration.cpp.

Here is the call graph for this function:

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

Description:

Inner Type Index:

Public Field Index:

Public Method Index:

Additional Inherited Members

Field Details:

◆ NumberFormat

◆ SubstitutionVariableDelimiters

◆ SubstitutionVariableEnd

◆ SubstitutionVariableStart

◆ tempVar

◆ TrueValues

Constructor(s) / Destructor Details::

◆ Configuration()

Method Details:

◆ FetchFromDefault()

◆ GetIterator()

◆ IsTrue()

◆ Load()

◆ LoadFromString()

◆ loadImpl()

◆ PreloadVariables()

◆ Protect()

◆ SetCommandLineArgs() [1/2]

◆ SetCommandLineArgs() [2/2]

◆ Store()

◆ StoreDefault()