|
ALib C++ Library
|
by |  |
|
Loading...
Searching...
No Matches
|
ALib C++ Library
|
by | |
|
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 .
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. |
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:
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.
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] (https://msdn.microsoft.com/EN-US/library/windows/desktop/dd317756%28v=vs.85%29.aspx).
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.
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.
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".
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:
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 (").
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:
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:
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.
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.
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.
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.
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:
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 )