 |
ALib C++ Library
|
|
|
ALib C++ Library
|
|
Trough the use of class Configuration defined in module ALib Configuration of the ALib C++ Library, external configuration variables can be comfortably defined and accessed.
While this is a reference appendix chapter, for general information, please refer to:
A few further configuration variables that ALib internally uses are defined by module ALib BaseCamp. The variables defined with this module are documented here.
Default Behavior:
ALox and the ALib C++ Library are designed to run fine without setting configuration variables. Therefore, these variables provide an additional way to tweak ALox and change its default behavior.
Boolean Variables:
This documentation uses the term boolean variables for those variables that are evaluated using method Configuration::IsTrue.
Declaration:
The variables listed here are resourced with camp ALox and declared with enum class lox::Variables.
Variables | |
| Configuration Variable | ALOX_CODE_PAGE |
| Configuration Variable | ALOX_CONSOLE_LIGHT_COLORS |
| Configuration Variable | ALOX_CONSOLE_TYPE |
| Configuration Variable | ALOX_GLOBAL_SOURCE_PATH_TRIM_RULES |
| Configuration Variable | ALOX_LOGGERNAME_AUTO_SIZES |
| Configuration Variable | ALOX_LOGGERNAME_FORMAT |
| Configuration Variable | ALOX_LOGGERNAME_FORMAT_DATE_TIME |
| Configuration Variable | ALOX_LOGGERNAME_FORMAT_MULTILINE |
| Configuration Variable | ALOX_LOGGERNAME_FORMAT_TIME_DIFF |
| Configuration Variable | ALOX_LOGGERNAME_MAX_ELAPSED_TIME |
| Configuration Variable | ALOX_LOGGERNAME_REPLACEMENTS |
| Configuration Variable | ALOX_LOXNAME_DOMAIN_SUBSTITUTION |
| Configuration Variable | ALOX_LOXNAME_DUMP_STATE_ON_EXIT |
| Configuration Variable | ALOX_LOXNAME_LOGGERNAME_VERBOSITY |
| Configuration Variable | ALOX_LOXNAME_PREFIXES |
| Configuration Variable | ALOX_LOXNAME_SOURCE_PATH_TRIM_RULES |
| Configuration Variable | ALOX_NO_IDE_LOGGER |
| ALOX_CODE_PAGE |
Default Value: 65001
Availability: On target platform WindowsOS only.
Evaluated once in the constructor of class WindowsConsoleLogger. Overwrites the default value of field CodePage. For possible values refer to Microsoft documentation.
Definition at line 13 of file alib_ref_alox_config_variables.dox.
| ALOX_CONSOLE_LIGHT_COLORS |
Default Value: "" (empty string)
Evaluated by colorful loggers that dispose about light and dark colors to adjust their foreground color accordingly. E.g. for instances of class AnsiLogger, field UseLightColors is set.
If not given, under Windows OS the right value is detected (here, the color of a terminal is detectable). Otherwise the value defaults to be an empty string, which chooses a programatically evaluated (internal) default value. In some occasions the (detected or set) runtime environment might influence such default value.
Value options are:
Definition at line 15 of file alib_ref_alox_config_variables.dox.
| ALOX_CONSOLE_TYPE |
Default Value: "default"
Influences the type of console logger that will be created by method Lox::CreateConsoleLogger, which is also used by Log::AddDebugLogger.
Possible values are:
| Default | No influence, same as if variable was not set (An OS-specific, colorful logger is chosen). |
| Plain | Plain text Logger of type ConsoleLogger is created. |
| Ansi | A Logger of type AnsiLogger is created. |
| Windows | A Logger of type WindowsConsoleLogger is created. |
Definition at line 14 of file alib_ref_alox_config_variables.dox.
| ALOX_GLOBAL_SOURCE_PATH_TRIM_RULES |
Default Value: "" (empty string).
This variable is used to define global Source Path Trim Rules.
Format: ALOX_GLOBAL_SOURCE_PATH_TRIM_RULES = [*]sourcepath [, inclusion, trimoffset, sensitivity, replacement] [ ; … ]
Details are described in External Configuration of Trim Rules.
Definition at line 16 of file alib_ref_alox_config_variables.dox.
| ALOX_LOGGERNAME_AUTO_SIZES |
Default Value: none.
This variable is used by Loggers derived from abstract type TextLogger. It is read when a TextLogger is registered with a Lox and written back when it is removed.
This mechanism maintains automatically adjusted tabulator positions in the generated meta information across different runs of a software. TextLogger::AutoSizes for more information.
Note that the portion 'LOGGERNAME' in the variable name is replaced by ALox with the value of Logger::GetName. This allows to have different sizes for different Loggers.
There is no need to manually edit the values found in this variable and their values are not documented here. Consider this variable a 'cookie' that ALox uses to store tabulator width across sessions. The information is only stored (and successfully read back with the next run of a process) when a write-enabled configuration plug-in (e.g. an INI file) is available.
Definition at line 17 of file alib_ref_alox_config_variables.dox.
| ALOX_LOGGERNAME_FORMAT |
Default Value: Set to the default values of the class members (fields).
This variable is used by Loggers of type textlogger::TextLogger.
It is read when a Logger of that type is added to a Lox and if found, fields
are (optionally) set according to the variables' content. The contents of the variable is specified as follows:
Format: ALOX_<LOGGERNAME>_FORMAT = ["]Format["] [, ["]Error["] [, ["]Warning["] [, ["]Info["] [, ["]Verbose["] ] [, ["]MsgSuffix["] ]]]]]
Values that start or end with whitespace characters or which contain comma characters (,) , need to be enclosed by quotation marks (").
Note that the portion 'LOGGERNAME' in the variable name is replaced by ALox as follows:
This allows to configure either a single Logger or a whole class of Loggers.
As a sample, configuration variable ALOX_ANSI_CONSOLE_LOGGER_FORMAT, affects all loggers of type AnsiConsoleLogger as long as no specific name is set when such Logger is constructed and no separate configuration for that name is set.
Note that the default debug Logger which is automatically created if no Logger is attached to the debug Lox singleton, is named "DEBUG_LOGGER". Therefore, by setting variable ALOX_DEBUG_LOGGER_FORMAT, this Logger is affected. Furthermore, whith debugging, a second debug-Logger for the IDE might be created. Its' name is "IDE_LOGGER".
Definition at line 18 of file alib_ref_alox_config_variables.dox.
| ALOX_LOGGERNAME_FORMAT_DATE_TIME |
Default Value: Set to the default values of the class members (fields).
This variable is used and applied in the same way as ALOX_LOGGERNAME_FORMAT, but defines the following fields:
Definition at line 19 of file alib_ref_alox_config_variables.dox.
| ALOX_LOGGERNAME_FORMAT_MULTILINE |
Default Value: Set to the default values of the class members (fields).
This variable is used and applied in the same way as ALOX_LOGGERNAME_FORMAT, but defines the following fields:
Definition at line 21 of file alib_ref_alox_config_variables.dox.
| ALOX_LOGGERNAME_FORMAT_TIME_DIFF |
Default Value: Set to the default values of the class members (fields).
This variable is used and applied in the same way as ALOX_LOGGERNAME_FORMAT, but defines the following fields:
Definition at line 20 of file alib_ref_alox_config_variables.dox.
| ALOX_LOGGERNAME_MAX_ELAPSED_TIME |
Default Value: "0, limit=59"
Format: ALOX_<LOGGERNAME>_MAX_ELAPSED_TIME = maximum [, limit= limitValue]
This variable is used by Loggers of type textlogger::TextLogger. It is read when a TextLogger is registered with a Lox and written back when it is removed.
The value stores the maximum elapsed time span of any Log Statement executed, measured in seconds. Those maximum values are preserved across different sessions of an application. If a subsequent run of a process takes more time than any previous, then this new time span is stored as the new maximum of all sessions.
The value is used to determine the number of 'digits' displayed in the meta information output of utility class MetaInfo for format parameter "%TC".
Consequently, the width of the log output (in respect to meta info "%TC") automatically adjusts to a reasonable value, depending on the execution time of the software.
The variable optionally supports a second attribute 'limit' which restricts the maximum value when a new session starts.
Note that the portion 'LOGGERNAME' in the variable name is replaced by ALox with the value of Logger::GetName. This allows to have different values for different Loggers.
Definition at line 22 of file alib_ref_alox_config_variables.dox.
| ALOX_LOGGERNAME_REPLACEMENTS |
Format: ALOX_<LOGGERNAME>_REPLACEMENTSFORMAT = ["]search["] , ["]replace["] [,...]
Note that the portion 'LOGGERNAME' in the variable name is replaced as documented in ALOX_LOGGERNAME_FORMAT.
The variable allows to set pairs of search and replace strings for a text logger. Pairs found here, are set using method TextLogger::SetReplacement.
Values that start or end with whitespace characters or which contain comma characters (,) , need to be enclosed by quotation marks (").
Definition at line 23 of file alib_ref_alox_config_variables.dox.
| ALOX_LOXNAME_DOMAIN_SUBSTITUTION |
Default Value: none.
This variable is used to define Domain Substitution Rules for a Lox. The portion 'LOXNAME' of the variable name has to be replaced by the name of the instance of class Lox in question.
Format: ALOX_<LOXNAME>_DOMAIN_SUBSTITUTION = [*]domainpath[*] -> replacement [ ; … ]
Details are described in Substitution Rules and External Configuration.
Definition at line 24 of file alib_ref_alox_config_variables.dox.
| ALOX_LOXNAME_DUMP_STATE_ON_EXIT |
Default Value: "none, verbosity=info, domain=/ALOX" (empty string).
Used for debugging or for investigation into ALox enabled 3rd party libraries or applications.
Format: ALOX_<LOXNAME>_DUMP_STATE_ON_EXIT = arg1 [, arg2][, … ]
The portion 'LOXNAME' of the variable name has to be replaced by the name of the instance of class Lox in question.
If this variable is defined, class Lox will automatically invoke method Lox::State in the moment a first Logger is removed. In most cases this would be the at the end of the process. (The other cases are: If after a removal of a Logger, the same or another Logger is added, then the next removal of a Logger will again invoke the method.)
There are two types of arguments possible which can appear in arbitrary order. All argument identifiers are letter case agnostic.
1. State Information Flags:
See reference documentation of Lox::State for more information. The identifiers expected in this variables' arguments are: ww
None | Selects nothing. This identifier overrules all others. If found, nothing is done. |
All | Selects everything |
Basic | Name of the Lox and number of log calls |
Version | Library version and thread safeness |
Loggers | Loggers |
Domains | Log domains currently registered |
Internaldomains | Internal domains |
Scopedomains | Scope domains |
DSR | Domain substitution rules |
PrefixLogables | Prefix logables |
Once | Log once counters |
Logdata | Log data objects |
Threadmappings | Named threads |
SPTR | Source path trim rules (C++ and C# only) |
Compilationflags | ALib compilation flags (C++ only) |
2. Attributes:
Two attributes that are affecting the invocation of Lox::State can be provided as arguments:
domain = DOMAIN_PATH | Sets a domain path for the Log.State invocation (defaults to ""). |
verbosity = VERBOSITY | Sets a verbosity for the Log.State invocation (defaults to "Info"). |
As a sample, take the following external variable:
ALOX_LOG_DUMP_STATE_ON_EXIT= domain=/DEBUG, verbosity = info, logdata, scopedomains
When the process terminates (precisely the first Logger is removed from the standard debug Lox instance), then method Lox::State is invoked, with
Verbosity.Info for parameter verbosity and( LogData & ScopeDomains ) Definition at line 26 of file alib_ref_alox_config_variables.dox.
| ALOX_LOXNAME_LOGGERNAME_VERBOSITY |
Default Value: "writeback" (empty string).
This variable is used to set Verbosities for a Logger attached to an instance of class Lox. The portions 'LOXNAME' and 'LOGGERNAME' of the variable name have to be replaced by the names of the instances of Lox and Logger in question.
Format: ALOX_<LOXNAME>_<LOGGERNAME>_VERBOSITY = [ writeback [ VAR_NAME ] ; ] [*]domainpath[*] = verbosity [ ; … ]
Details are described in External Verbosity Configuration.
Definition at line 25 of file alib_ref_alox_config_variables.dox.
| ALOX_LOXNAME_PREFIXES |
Default Value: "" (empty string).
This variable is used to define Lox and Log Domain specific Prefix Logables (strings only). The portion 'LOXNAME' of the variable name has to be replaced by the name of the instance of class Lox in question.
Format: ALOX_<LOXNAME>_PREFIXES = [*]domainpath[*] = prefixstring [, inclusion] [ ; … ]
The variable value may contain more than one definition, separated by semicolons ';'. Each definition contains of the following parameters:
Definition at line 27 of file alib_ref_alox_config_variables.dox.
| ALOX_LOXNAME_SOURCE_PATH_TRIM_RULES |
Default Value: "" (empty string).
This variable is used to define Lox-specific Source Path Trim Rules. The portion 'LOXNAME' of the variable name has to be replaced by the name of the instance of class Lox in question.
Format: ALOX_<LOXNAME>_SOURCE_PATH_TRIM_RULES = [*]sourcepath [, inclusion, trimoffset, sensitivity, replacement] [ ; … ]
Details are described in External Configuration of Trim Rules.
Definition at line 28 of file alib_ref_alox_config_variables.dox.
| ALOX_NO_IDE_LOGGER |
Default Value: "false"
Boolean variable that is evaluated in method Log::AddDebugLogger. If not set, when debugging, an additional Logger supporting the log output of the IDE is created. The only logger currently available (needed) is with WindowsOS / VisualStudio, class VStudioLogger.
This variable can be used to suppress this.
Definition at line 29 of file alib_ref_alox_config_variables.dox.