Collaboration diagram for Configuration:

Class Description

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

Interface methods are implemented synchronized.

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 cs.aworx.lib.config for more information on ALib external configuration variables.

Inner Classes
class	PluginAndPrio

Public Static Fields
const int	PrioAutodetect = 500

const int	PrioCLIArgs = 40000

const int	PrioDefaultValues = 10000

const int	PrioEnvironment = 30000

const int	PrioProtectedValues = int.MaxValue

const int	PrioStandard = 20000

Public Fields
NumberFormat	NumberFormat = new NumberFormat()

char[]	SubstitutionVariableDelimiters

AString	SubstitutionVariableEnd = new AString()

AString	SubstitutionVariableStart = new AString("$")

List< AString >	TrueValues

Public Methods
	Configuration (bool addDefaultPlugins=true)

int	FetchFromDefault (ConfigurationPlugin dest, String sectionName=null)

ConfigurationPlugin	GetPlugin (int priority)

TPluginType	GetPluginTypeSafe< TPluginType > ()

TPluginType	GetPluginTypeSafe< TPluginType > (int priority)

bool	HasPlugins ()

void	InsertPlugin (ConfigurationPlugin plugin, int priority)

bool	IsTrue (AString value)

int	Load (Variable variable)

int	LoadFromString (Variable variable, Object externalizedValue)

int	loadImpl (Variable variable, bool substitute)

int	Protect (Variable variable, Object externalizedValue=null)

bool	RemovePlugin (ConfigurationPlugin plugin)

void	SetCommandLineArgs (String[] args=null)

int	Store (Variable variable, Object externalizedValue=null)

int	StoreDefault (Variable variable, Object externalizedValue=null)

Protected Fields
List< PluginAndPrio >	plugins = new List<PluginAndPrio>()

AString	tmpConversion = new AString()

Substring	tmpReplVarAll = new Substring()

Substring	tmpReplVarCategory = new Substring()

Substring	tmpReplVarName = new Substring()

Constructor & Destructor Documentation

◆ Configuration()

Configuration ( bool addDefaultPlugins = true )

inline

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

Priority	Plug-in Type
Configuration.PrioDefaultValues	InMemoryPlugin
Configuration.PrioEnvironment	Environment
Configuration.PrioCLIArgs	CLIArgs
Configuration.PrioProtectedValues	InMemoryPlugin

Parameters

addDefaultPlugins If true, the default plugins are added. Defaults to true.

Member Function Documentation

◆ FetchFromDefault()

int FetchFromDefault	(	ConfigurationPlugin	dest,
		String	sectionName = `null`
	)

inline

This method fetches all values from a plug-in of priority PrioDefaultValues, 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 users' 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 users' 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.
sectionName	Optional string denoting a section to fetch. Defaults to `null`.

Returns: The number of variables fetched.

◆ GetPlugin()

ConfigurationPlugin GetPlugin ( int priority )

inline

Returns the plug-in with the given priority. If the plug-in does not exist, null is returned.

Note: The method is not thread-safe. At least, the returned plugin may become invalid after the method returned. For thread-safe operations, this object needs to be acquired and released explicitly.

Usually this method is used in the termination section of a software, when no parallel threads are active.

It may be used for example to fetch default variables into a configuration file.

Parameters

priority The priority of the plug-in to return.

Returns: The plug-in requested or null if not available.

◆ GetPluginTypeSafe< TPluginType >() [1/2]

TPluginType GetPluginTypeSafe< TPluginType > ( )

inline

Searches all plug-ins for the first found with type TPluginType.

Template Parameters

TPluginType The type of the plugin to search.

Returns: The plug-in of requested type. null if not available.

Type Constraints

TPluginType

:

ConfigurationPlugin

◆ GetPluginTypeSafe< TPluginType >() [2/2]

TPluginType GetPluginTypeSafe< TPluginType > ( int priority )

inline

Same as GetPlugin, but converts the plug-in found to the template type. A type-check is performed. If the plugin has a different type, null is returned.

Parameters

priority The priority of the plug-in to return.

Template Parameters

TPluginType The type of the plugin to search.

Returns: The plug-in of requested type and priority. null if not available.

Type Constraints

TPluginType

:

ConfigurationPlugin

◆ HasPlugins()

bool HasPlugins ( )

inline

Checks if any plug-in is attached. This is useful if optional configuration objects are used. In case no plug-in was attached (by a third party), the effort to declare and search a variable can be omitted.

Returns: true if this object has any plugin set, false otherwise.

◆ InsertPlugin()

void InsertPlugin	(	ConfigurationPlugin	plugin,
		int	priority
	)

inline

Adds the given plug-in to the list of plug-ins used to query configuration values. Higher numbers for parameter priority, prioritize this plug-in against those with lower values. Default values are provided with static constant fields PrioCLIArgs, PrioEnvironment and PrioStandard.

Parameters

plugin	The plug-in to insert.
priority	The priority of the plug-in.

◆ IsTrue()

bool IsTrue ( AString value )

inline

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.

◆ Load()

int Load ( Variable variable )

inline

Receives and optionally creates configuration variable.

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

Parameters

variable The variable to receive.

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

◆ LoadFromString()

int LoadFromString	(	Variable	variable,
		Object	externalizedValue
	)

inline

Convenience method to set values 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 PrioDefaultValues, is used.

Parameters

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

Returns: The size of the variable after parsing.

◆ loadImpl()

int loadImpl	(	Variable	variable,
		bool	substitute
	)

inline

Implementation of get method. No locking is performed (has to be done before invoking this method)

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.

◆ Protect()

int Protect	(	Variable	variable,
		Object	externalizedValue = `null`
	)

inline

Convenience method that stores the variable with priority Configuration.PrioProtectedValues.

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 field 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.Default.Store(this).

◆ RemovePlugin()

bool RemovePlugin ( ConfigurationPlugin plugin )

inline

Remove the given plug-in from the list of plug-ins. Responsibility for deletion of removed plug-ins moves to the remover. Active (inserted) plug-ins get deleted by class' destructor.

Parameters

plugin The plug-in to be deleted.

Returns: true if the plug-in was removed, else false.

◆ SetCommandLineArgs()

void SetCommandLineArgs ( String[] args = null )

inline

Sets the command line arguments for default plug-in CLIArgs.

Note: This method should be called for instances of this class after construction.
In standard application scenarios, this method is invoked by method ALIB.Init for the static singleton found in ALIB.Config.

Parameters

args	Parameters taken from standard C# method `main()` (the list of command line arguments). Defaults to null.

◆ Store()

int Store	(	Variable	variable,
		Object	externalizedValue = `null`
	)

inline

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 (0), 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, PrioDefaultValues 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 PrioProtectedValues, 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 PrioDefaultValues, the value becomes just a default and does not overwrite externally specified values.
Leaving the field to its uninitialized state (0), 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 PrioProtectedValues allows to protect the variable value in respect to external manipulation.
Setting the field to PrioProtectedValues - 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 0 (no priority) 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 PrioDefaultValues (but greater than 0),
the detected priority was PrioProtectedValues. (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 users' 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 variables' 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.

◆ StoreDefault()

int StoreDefault	(	Variable	variable,
		Object	externalizedValue = `null`
	)

inline

Convenience method that stores the variable with priority Configuration.PrioDefaultValues.

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 field 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.Default.Store(this).

Member Data Documentation

◆ NumberFormat

NumberFormat NumberFormat = new NumberFormat()

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

◆ plugins

List<PluginAndPrio> plugins = new List<PluginAndPrio>()

protected

The plug-ins we have in our portfolio

◆ PrioAutodetect

const int PrioAutodetect = 500

static

Constant providing a priority which is even lower than default. This priority is not used by any standard plug-ins and currently not even anywhere in core ALib. The rational to provide it is for third party libraries that may use this value in cases where values are estimated or detected - instead of defaulted. A user of the library may then overwrite such auto-detection by setting a default value in the configuration.

◆ PrioCLIArgs

const int PrioCLIArgs = 40000

static

Constant providing default priority for IniFile (or similar) external plug-ins.

◆ PrioDefaultValues

const int PrioDefaultValues = 10000

static

Constant providing a low priority. This is used with PrioDefaultValues

◆ PrioEnvironment

const int PrioEnvironment = 30000

static

Constant providing default priority for environment variables plug-in.

◆ PrioProtectedValues

const int PrioProtectedValues = int.MaxValue

static

Constant providing the highest possible priority. This is used with PrioProtectedValues

◆ PrioStandard

const int PrioStandard = 20000

static

Constant providing default priority for command-line parameters plug-in.

◆ SubstitutionVariableDelimiters

char [] SubstitutionVariableDelimiters

Initial value:

= { ' ','$','@',',','.',';',':','\"','\'','+','-','*','/','\\',

'§','%','&','(',')','[',']','{','}','<','>','=','?','\'','`','~','#' }

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.

◆ SubstitutionVariableEnd

AString SubstitutionVariableEnd = new AString()

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

◆ SubstitutionVariableStart

AString SubstitutionVariableStart = new AString("$")

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. "}"

◆ tmpConversion

AString tmpConversion = new AString()

protected

A temporary object used for conversion

◆ tmpReplVarAll

Substring tmpReplVarAll = new Substring()

protected

A temporary object used with variable substitution

◆ tmpReplVarCategory

Substring tmpReplVarCategory = new Substring()

protected

A temporary object used with variable substitution

◆ tmpReplVarName

Substring tmpReplVarName = new Substring()

protected

A temporary object used with variable substitution

◆ TrueValues

List<AString> 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).

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

Configuration.cs

Class Description

Inner Classes

Public Static Fields

Public Fields

Public Methods

Protected Fields

Constructor & Destructor Documentation

◆ Configuration()

Member Function Documentation

◆ FetchFromDefault()

◆ GetPlugin()

◆ GetPluginTypeSafe< TPluginType >() [1/2]

◆ GetPluginTypeSafe< TPluginType >() [2/2]

◆ HasPlugins()

◆ InsertPlugin()

◆ IsTrue()

◆ Load()

◆ LoadFromString()

◆ loadImpl()

◆ Protect()

◆ RemovePlugin()

◆ SetCommandLineArgs()

◆ Store()

◆ StoreDefault()

Member Data Documentation

◆ NumberFormat

◆ plugins

◆ PrioAutodetect

◆ PrioCLIArgs

◆ PrioDefaultValues

◆ PrioEnvironment

◆ PrioProtectedValues

◆ PrioStandard

◆ SubstitutionVariableDelimiters

◆ SubstitutionVariableEnd

◆ SubstitutionVariableStart

◆ tmpConversion

◆ tmpReplVarAll

◆ tmpReplVarCategory

◆ tmpReplVarName

◆ TrueValues