alib::variables Namespace Reference

Description:

This is the namespace ofALib Module, which implements access, evaluation and writing of configuration variables. Variable data can be load from different sources, for example configuration files, command line parameters, environment variables, or any custom storage type.

Please consult ALib Module Config - Programmer's Manual for further information.

Type Index:
struct	Bool
class	CLIVariablesPlugin
class	ConfigResourcePool
class	Configuration
struct	ConfigurationListener
class	ConfigurationPlugin
class	Declaration
class	EnvironmentVariablesPlugin
struct	ERPriority
	ALib Enum Record associated with enumeration Priority. More...
class	IniFile
class	IniFileFeeder
class	TSharedConfiguration
class	Variable
struct	VMeta

Type Definition Index:
using	StringVectorComma = alib::StringVectorPA
using	StringVectorSemicolon = alib::StringVectorPA

Enumeration Index:
enum class	Exceptions { ErrorOpeningFile = 1 , ErrorWritingFile = 2 }
enum class	Priority : uint16_t {   NONE = 0 , AutoDetected = 1000 , DefaultValues = 2000 , Standard = 4000 ,   ConfigFile = 6000 , Environment = 8000 , SessionFile = 10000 , CLI = 12000 ,   Session = 14000 , Protected = (std::numeric_limits<uint16_t>::max)() }

Function Index:
variables::Variable	CampVariable (camp::Camp &camp)
variables::Variable	CampVariable (camp::Camp &camp, const Declaration *decl)
variables::Variable	CampVariable (camp::Camp &camp, const String &name, const String &typeName, const String &defaultValue=NULL_STRING)
template<typename TEnum>
variables::Variable	CampVariable (camp::Camp &camp, TEnum Enum)
template<typename TEnum> requires std::is_enum_v<TEnum>
variables::Variable	CampVariable (camp::Camp &camp, TEnum Enum, const Box replacements)

Type Definition Details:

StringVectorComma

using alib::variables::StringVectorComma = alib::StringVectorPA

Type definition used with configuration variables of type "SV,", which stores a string array, imported by parsing a comma-separated string list.

Attention

When exported, NEW_LINE codes are added after each comma. This allows external configuration systems to smoothly format longer lists of values. However, the new line codes usually have to be detected with writing and eliminated on import. Built-in type IniFile processes such codes correctly.

Definition at line 210 of file vmeta.inl.

StringVectorSemicolon

using alib::variables::StringVectorSemicolon = alib::StringVectorPA

Type definition used with configuration variables of type "SV;", which stores a string array, imported by parsing a string list separated by character ';'.

Attention

When exported, NEW_LINE codes are added after each semicolon. This allows external configuration systems to smoothly format longer lists of values. However, the new line codes usually have to be detected with writing and eliminated on import. Built-in type IniFile processes such codes correctly.

Definition at line 220 of file vmeta.inl.

Enumeration Details:

Exceptions

enum class alib::variables::Exceptions

strong

Exception codes of namespace alib::variables.

Availability

This enum type is only available if the module ALib Camp is included in the ALib Build.

Enumerator
ErrorOpeningFile	File not found when reading.
ErrorWritingFile	An error occurred writing the file .

Definition at line 385 of file inifile.inl.

Priority

enum class alib::variables::Priority : uint16_t

strong

Arithmetical enumeration used to control write access to configuration variables, depending on the source of assignable values.

See also

Chapter 4.1 Variables and Priorities of the Programmer's Manual of camp ALib Variables.

Enumerator
NONE	This priority value denotes that a variable is undefined and has no value set. The underlying integral value is 0.
AutoDetected	Constant providing a priority which is even lower than default. A use-case for this priority are for third party libraries that may preset variables in cases where values are estimated or detected instead of defaulted. A using code of such library may then overwrite the auto-detection estimates, by setting a default value in the configuration. This priority is not used internally (by any ALib camp) today. The underlying integral value is 1,000.
DefaultValues	Used to store default values, either from (resourced) declarations, hard-coded values, or values provided with method Configuration::PresetImportString. The underlying integral value is 2,000.
Standard	This is the default priority when a variable is defined for setting a 'hard-coded' value. The underlying integral value is 4,000. Hard-coded values have a higher priority than default values, but are deemed to get overwritten by any other configuration source.
ConfigFile	External application configuration sources use this element to define variables found. This element is also used with built-in class IniFileFeeder. The underlying integral value is 6,000.
Environment	Used with plug-in EnvironmentVariablesPlugin. The underlying integral value is 8,000.
SessionFile	Used to store temporary session information. Those are higher than Environment but lower than CLI. This session priority is only a proposal. Implementations might use a different value, even for different variables, for example Environment - 1 or CLI + 1 . It depends on the use case. The underlying integral value is 10,000.
CLI	Used with plug-in CLIVariablesPlugin. The underlying integral value is 12,000.
Session	Used to store generate temporary session information. While usually changes made in source code has a low priority, session information is overwritten by running software, no matter from which external source an existing values came. If software wants to disallow the change of session information imposed by a library or a different software part, still a value can be set to protected. The underlying integral value is 14,000.
Protected	Used to define variables with protected values. If all code entities apply to the contract that this camp imposes in respect to variable definitions and priorities, a value set with this priority cannot be manipulated from "outside", hence by config files, command line arguments or any custom configuration source or plug-in. The underlying integral value is std::numeric_limits<int>::max().

Definition at line 30 of file variables.prepro.hpp.

Function Details:

CampVariable() [1/5]

variables::Variable alib::variables::CampVariable ( camp::Camp & camp )

inline

Creates an undeclared configuration variable attached to an ALib Camp.

Note

While all other overloads of this shortcut-function lock the configuration instance of the given camp, with this method it this is not needed and thus not done.

Parameters

camp	An singleton which supplies the Configuration instance.

Returns

A variable using the Configuration of the given camp.

Definition at line 349 of file camp.inl.

CampVariable() [2/5]

variables::Variable alib::variables::CampVariable ( camp::Camp & camp, const Declaration * decl )

inline

Constructs and declares a variable.

Note

This shortcut-function locks the configuration instance of the given camp for declaring the variable. Thus, it must not be locked before the call.

Parameters

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

Returns

The variable created.

Definition at line 379 of file camp.inl.

Here is the call graph for this function:

CampVariable() [3/5]

variables::Variable alib::variables::CampVariable ( camp::Camp & camp, const String & name, const String & typeName, const String & defaultValue = NULL_STRING )

inline

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

Note

This shortcut-function locks the configuration instance of the given camp for declaring the variable. Thus, it must not be locked before the call.

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.

Returns

The variable created.

Definition at line 363 of file camp.inl.

Here is the call graph for this function:

CampVariable() [4/5]

template<typename TEnum>

variables::Variable alib::variables::CampVariable	(	camp::Camp &	camp,
		TEnum	Enum )

Constructs and declares a variable.

Note

This shortcut-function locks the configuration instance of the given camp for declaring the variable. Thus, it must not be locked before the call.

Template Parameters

TEnum

The type of parameter Enum

Parameters

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

Returns

The variable created.

Definition at line 394 of file camp.inl.

Here is the call graph for this function:

CampVariable() [5/5]

template<typename TEnum>
requires std::is_enum_v<TEnum>

variables::Variable alib::variables::CampVariable	(	camp::Camp &	camp,
		TEnum	Enum,
		const Box	replacements )

Constructs and declares a variable.

Note

This shortcut-function locks the configuration instance of the given camp for declaring the variable. Thus, it must not be locked before the call.

Attention

This function might allocate 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 which supplies the Configuration instance.
Enum	Element of an enum type that represents resourced configuration variables.
replacements	Replacement values.

Returns

The variable created.

Definition at line 416 of file camp.inl.

Here is the call graph for this function: