Variable Class Reference

Collaboration diagram for Variable:

Class Description

---

This class is used to load and store external configuration data with objects of class Configuration and its plug-ins ConfigurationPlugin.

Note

For general information about external configuration variables, see namespace documentation com.aworx.lib.config.

Construction/Redeclaration:
While constructors accepting attributes of a variable exist, it is recommended to declare all external configuration variables in a central place, using statically or dynamically allocated objects of type VariableDecl and pass such record to the constructor of a variable.

The class is designed to be 'reused' to avoid repeated allocation/de-allocation of memory. After invoking one of the overloaded methods Declare, which share the same signatures as the overloaded constructors, a variable is freshly initialized. Internally, the memory allocated for values remains allocated.

Values:
A variable can contain zero, one or several values. If zero, then the variable was either not loaded, yet or the load operation failed (no configuration plug-in defined the variable). Method Size reports the currently available values and methods GetString(int), GetInteger(int) and GetFloat(int) return a value. Internally all values are stored as strings. If field Config is set, its field Configuration.NumberFormat is used for floating point conversion.

When storing a variable that contains more than one value, field Delim has to be set. Conversely, when reading a variable that contains multiple values, the delimiter has to be set prior to the load operation.

Note

This is not true when loading/storing a variable directly in a plug-in of type InMemoryPlugin or might also not be true with custom configuration plug-in types which for example might store the values in a database.
However, with the default plug-ins CLIArgs, Environment and IniFile the delimiter is needed! Therefore, it is best practice to always define a proper delimiter if a variable is multi-valued.

Loading and Storing:
There are two ways of loading and storing a variable:

• Using the interface of class Configuration which allows to load and store variables from different sources (plug-ins) in a prioritized way.
• Using the interface of class ConfigurationPlugin which may be used if the decision about the source or drain of a load/store operation is explicitly made by a code unit.

Storing empty variables (method Size returns 0) deletes a variable from the those configuration plug-ins that are write enabled.

Public Types
enum	FormatHint { None = 0, MultLine = 1 << 0, NoDelimSpaces = 1 << 1, Custom = 1 << 16 }

Public Fields
AString	Category = new AString()
AString	Comments = new AString()
Configuration	Config
AString	DefaultValue = new AString()
char	Delim = '\0'
String	FormatAttrAlignment
FormatHint	FormatHints
AString	Fullname = new AString()
AString	Name = new AString()
int	Priority = 0

Public Methods
	Variable ()
	Variable (Object category, Object name, char delim='\0', Object comments=null)
	Variable (Variable variable)
	Variable (VariableDecl declaration, params Object[] replacements)
AString	Add ()
AString	Add (bool value)
AString	Add (Object value)
Variable	ClearValues (int startIdx=0)
Variable	Declare (Object category, Object name, char delim='\0', Object comments=null)
Variable	Declare (Variable variable)
Variable	Declare (VariableDecl declaration, params Object[] replacements)
bool	GetAttribute (String attrName, Substring result, char attrDelim='=')
double	GetFloat (int idx=0)
long	GetInteger (int idx=0)
AString	GetString (int idx=0)
bool	IsTrue (int idx=0)
void	ReplaceValue (int idx, Variable replVariable)
int	Size ()

Protected Fields
int	qtyValues = 0
List< AString >	values = new List<AString>()

Protected Methods
void	clear ()

Member Enumeration Documentation

FormatHint

enum FormatHint

strong

Denotes hints for formatting variables when storing in external configuration files

Enumerator
None	No hints
MultLine	Write each argument in a new line
NoDelimSpaces	Suppress spaces around the delimiter (only used in single line mode)
Custom	This and upward bits are reserved for custom plug-ins

Constructor & Destructor Documentation

Variable() [1/4]

Variable ( )

inline

---

Constructs an undefined Variable. Prior to using this, Declare has to be invoked.

Variable() [2/4]

Variable ( VariableDecl  declaration, params Object[]  replacements  )

inline

---

Constructs a variable from a declaration. Strings named "%1", "%2" ... "%N" found in the fields Category, Name, Comments and DefaultValue are replaced with given replacement strings found in vector replacements.

Parameters

declaration	The declaration data of the variable.
replacements	List of objects that will be converted to strings using AString._(Object).

Variable() [3/4]

Variable ( Variable  variable )

inline

---

Constructs a variable using the declaration of another variable. The values are not copied.

Parameters

variable

A variable to copy the declaration (which is comprised with fields Category, Name, Fullname, Delim, Comments and DefaultValue) from.

Variable() [4/4]

Variable ( Object  category, Object  name, char  delim = '\0', Object  comments = null  )

inline

---

Constructs a variable from the given values

Parameters

category	The category of the variable.
name	The name of the variable
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files).
comments	Comment lines that might be added in the configuration storage (plug-in implementation dependent).

Member Function Documentation

Add() [1/3]

AString Add ( )

inline

---

Adds a value to the end of the list of values.

Returns

A reference to the string which can be manipulated to set the value.

Add() [2/3]

AString Add ( bool  value )

inline

---

Adds the given boolean value to the end of the list of values. For true values string "true" is set, otherwise "false".

Note

Other, depending on the variable semantics, more user friendly values may be set using the string interface Add. String values recognized for boolean variables are defined in Configuration.TrueValues.

Parameters

value

The value to set.

Returns

A reference to the string representing the boolean value.

Add() [3/3]

AString Add ( Object  value )

inline

---

Adds the given string value to the end of the list of values.

Parameters

value

The value to set.

Returns

A reference to the string which can be further manipulated to set the value.

clear()

void clear ( )

inlineprotected

---

Clears all values.

ClearValues()

Variable ClearValues ( int  startIdx = 0 )

inline

---

Clears the value, respectively the list of values set. After invoking this method, Size will return startIdx and GetString will return null for any index greater or equal to startIdx.

Parameters

startIdx

The index of the first value to be cleared. Defaults to 0.

Returns

this to allow concatenated operations.

Declare() [1/3]

Variable Declare ( Object  category, Object  name, char  delim = '\0', Object  comments = null  )

inline

---

Clears the variable resets its declaration.

Parameters

category	The category of the variable.
name	The name of the variable
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files). Defaults to '\0'.
comments	Comment lines that might be added in the configuration storage (plug-in implementation dependent). Defaults to null.

Returns

this to allow concatenated operations.

Declare() [2/3]

Variable Declare ( Variable  variable )

inline

---

Constructs a variable using the declaration of another variable. The values are not copied.

Parameters

variable

A variable to copy the declaration (which is comprised with fields Category, Name, Fullname, Delim, Comments and DefaultValue) from.

Returns

this to allow concatenated operations.

Declare() [3/3]

Variable Declare ( VariableDecl  declaration, params Object[]  replacements  )

inline

---

Re-initializes a variable from a declaration. Strings named "%1", "%2" ... "%N" found in the fields Category, Name, Comments and DefaultValue are replaced with given replacement string arguments in vector replacements.

Parameters

declaration	The declaration data of the variable.
replacements	List of objects that will be converted to strings using AString._(Object).

Returns

this to allow concatenated operations.

GetAttribute()

bool GetAttribute ( String  attrName, Substring  result, char  attrDelim = '='  )

inline

---

Searches in the values of this variable for the pattern attrName = result and sets parameter result to the string following this pattern.

Parameters

	attrName	The name of the attribute searched.
[out]	result	A substring with the result.
	attrDelim	The delimiter to search for. Defaults to '='.

Returns

true if the attribute was found, false otherwise.

GetFloat()

double GetFloat ( int  idx = 0 )

inline

---

Returns the value at idx interpreted as a double value. If the index is invalid, 0.0 is returned. Parsing is done using field NumberFormat of field Config, respectively, if this is not set, the static singleton NumberFormat.Global.

Parameters

idx	The index of the value to be retrieved. Defaults to 0.

Returns

The value at idx interpreted as a double value.

GetInteger()

long GetInteger ( int  idx = 0 )

inline

---

Returns the value at idx interpreted as an integer. If the index is invalid, 0 is returned.

Parameters

idx	The index of the value to be retrieved. Defaults to 0.

Returns

The value at idx interpreted as an integer value.

GetString()

AString GetString ( int  idx = 0 )

inline

---

Returns the value with the given index. Valid values for parameter idx are between 0 and Size - 1. If no value is set for the given index, null is returned.

Note

It is explicitly allowed to change the contents of the AString object returned, e.g. for a subsequent store operation.

Parameters

idx	The index of the value to be retrieved. Defaults to 0.

Returns

The value at idx.

IsTrue()

bool IsTrue ( int  idx = 0 )

inline

---

Returns true if the first value represents a boolean 'true'. Evaluation is done using field Config, respectively if this is not set, the static singleton ALIB.Config.

Parameters

idx	The index of the value to be retrieved. Defaults to 0.

Returns

The value at idx interpreted as a boolean value.

ReplaceValue()

void ReplaceValue ( int  idx, Variable  replVariable  )

inline

---

Replaces the value at idx with the values of the given other variable.

Parameters

idx	The index of the value to replace.
replVariable	The variable providing the replacement values.

Size()

int Size ( )

inline

---

Returns the number of values set in this object.

Returns

The number of values set.

Member Data Documentation

Category

AString Category = new AString()

The configuration variable category.

Comments

AString Comments = new AString()

The configuration variable comments with placeholders replaced

Config

Configuration Config

The Configuration that was recently used to request or store the value.

DefaultValue

AString DefaultValue = new AString()

The default value provided as an externalized string.

The only occasion that this value is used is with method Configuration.Load. If no plug-in has this variable defined and this field is not nulled, then the value is written into plug-in of priority Configuration.PrioDefaultValues, respectively - if this default plug-in was replaced by the user - into a plug-in found at or below this priority.

In this case, the value is parsed using method XTernalizer.LoadFromString of field ConfigurationPlugin.StringConverter of the plug-in writing the value.

Note

The field is ignored when using the plug-in interface ConfigurationPlugin.Load directly. To store this value 'manually' directly to a plug-in, invoke ConfigurationPlugin.Store with providing value explicitly.

Delim

char Delim = '\0'

The delimiter used for parsing and storing values by simple textual plug-ins which use the default version of XTernalizer for in- and externalizing variables.

FormatAttrAlignment

String FormatAttrAlignment

If set, attributes written in multi-lines are vertically aligned by this character or string. Use cases are "=", ":" or "->".
Used by IniFile and potentially by custom plug-ins.

FormatHints

FormatHint FormatHints

Hints for formatting textual configuration files. (Used by class IniFile and potentially by custom plug-ins.

Fullname

AString Fullname = new AString()

The configuration variable category and name concatenated with an underscore character '_'. This is useful e.g. for naming variables in log messages.

Name

AString Name = new AString()

The configuration variable name.

Priority

int Priority = 0

A value related to the priority of a configuration plug-in. The following values apply:

• 0 after creation or declaration (reuse).
• The priority of the plug-in that loaded the value (after calling Configuration.Load).
• The priority of the plug-in that stored the value (after calling Configuration.Store).
• 0, if the last load or store operation failed. In addition prior to storing a variable, the value might be manually set. See documentation of Configuration.Store) for details.

qtyValues

int qtyValues = 0

protected

The number of values currently stored. This may be less than items found in values as those are reused objects.

values

List<AString> values = new List<AString>()

protected

The values

---

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

• Variable.cs