Collaboration diagram for ALox:

Class Description

This is a 100% static class that holds constants and 'global' methods of the ALox Logging Library.

Public Static Fields
static VariableDecl	AUTO_SIZES

static Configuration	Config =null

static AString	ConfigCategory = new AString("ALOX" )

static VariableDecl	CONSOLE_LIGHT_COLORS

static VariableDecl	CONSOLE_TYPE

static VariableDecl	DOMAIN_SUBSTITUTION

static VariableDecl	DUMP_STATE_ON_EXIT

static VariableDecl	FORMAT

static VariableDecl	FORMAT_DATE_TIME

static VariableDecl	FORMAT_MULTILINE

static VariableDecl	FORMAT_TIME_DIFF

static readonly String	InternalDomains ="$/"

static VariableDecl	MAX_ELAPSED_TIME

static VariableDecl	NO_IDE_LOGGER

static VariableDecl	PREFIXES

static VariableDecl	REPLACEMENTS

static readonly int	Revision =0

static VariableDecl	SPTR_GLOBAL

static VariableDecl	SPTR_LOX

static VariableDecl	VERBOSITY

static readonly int	Version =2402

Public Static Methods
static Lox	Get (String name, Create create=Create.Never)

static void	Init (Configuration config)

static void	Init (String[] args=null)

static Verbosity	ReadVerbosity (Substring src)

static void	Register (Lox lox, ContainerOp operation)

static void	Reset ()

static AString	ToString (Scope scope, int pathLevel, AString target)

static AString	ToString (Verbosity verbosity, int priority, AString target)

static AString	ToStringPriority (int priority, AString target)

Private Static Fields
static bool	isInitialized = false

static List< Lox >	loxes = new List<Lox>()

Member Function Documentation

◆ Get()

static Lox Get	(	String	name,
		Create	create = `Create.Never`
	)

inlinestatic

Returns the Lox with the given name. A lox is only found if it was created and registered with ALox using Register. If not found, and parameter create is true (the default), a new Lox is created, registered and returned.

Parameters

name	The name of the Lox to search and optionally to create. Comparison is case insensitive.
create	Denotes whether a Lox that was not found is created. Optional and defaults to Create.Never.

Returns: The Lox found, null in case of failure.

◆ Init() [1/2]

static void Init ( Configuration config )

inlinestatic

Variant of method Init, accepting a configuration. This will be stored in field Config and used for loading and storing ALox variables.

Parameters

config The configuration object to use.

Returns: Returns true if ALox was initialized before, false if not.

◆ Init() [2/2]

static void Init ( String[] args = null )

inlinestatic

This method must be called prior to using ALox, e.g. at the beginning of the main() method of an application. It is OK, to call this method more than once, which allows independent code blocks (e.g. libraries) to bootstrap ALox independently. However, only the first invocation is effective.

The very first invocation should not be interrupted by a parallel invocation of a second thread. Consequently, with more complex applications it is recommended to explicitly invoke this method once when the software is bootstrapped.

Note: This method invokes ALIB.Init and passes the Configuration object created. Hence, no explicit initialization of underlying ALib is needed.
If a different configuration object is to be used with ALib, then ALIB.Init needs to be called explicitly prior to this method.

If command line parameters should be used for configuring ALox, then the very first call to this method has to provide the argc and argv parameters. Subsequent calls to this method with different parameters do not change the setup.

If other, custom configuration data sources should be used already with this method (to read the configuration variables as described in ALIB.Init), use overloaded method ALox.Init(Configuration).

Parameters

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

◆ ReadVerbosity()

static Verbosity ReadVerbosity ( Substring src )

inlinestatic

Interprets given src as a verbosity. A case insensitive comparison of only the first (!) character of the start of the string is performed (against 'v', 'i', 'w' and 'e'). If no match is found, Verbosity.Off is returned.

Parameters

src	The string to 'parse'.

Returns: The verbosity read.

◆ Register()

static void Register	(	Lox	lox,
		ContainerOp	operation
	)

inlinestatic

Registers or un-registers a Lox object statically with ALox. Once registered, any code entity of the same process is enabled to retrieve the Lox using Get.
No two objects with the same name must be registered. If this is done, the latter will not be registered and not be found by Get. In debug-compilations, an ALib error report is written (by default raises 'assert') if a name is registered twice.
Note that name comparison is performed case in-sensitive.

If debug-logging is enabled (depends on compilation symbols) and used, the singleton of type % Lox provided for debug-logging is registered. This uses the name "Log"

Registration is not mandatory but done by default by the constructor of class Lox. Therefore, to keep a Lox private, an optional parameter is available.

Parameters

lox	The Lox to register.
operation	If ContainerOp.Remove, the given Lox is deregistered. Defaults to ContainerOp.Insert.

◆ Reset()

static void Reset ( )

inlinestatic

Resets this object. Concretely the following steps are performed:

All Lox objects are removed.
If the debug lox singleton exists, it is deleted.

Attention: This method was introduced to support resetting ALox in the unit tests. In real applications, this method should NOT be used. Side effects might appear using this method and it is not tested otherwise than used in tests!

◆ ToString() [1/2]

static AString ToString	(	Scope	scope,
		int	pathLevel,
		AString	target
	)

inlinestatic

Provides a string representation of the Scope enums.

Parameters

scope	The enum value to retrieve a string representation for.
pathLevel	The path level.
target	The target string.

Returns: A string representation of the provided Scope value.

◆ ToString() [2/2]

static AString ToString	(	Verbosity	verbosity,
		int	priority,
		AString	target
	)

inlinestatic

Writes a string representation of the Verbosity and priority into the given AString.

Parameters

verbosity	The enum value to retrieve a string representation for.
priority	The priority of the verbosity setting.
target	The target to write into.

Returns: target to allow concatenated calls.

◆ ToStringPriority()

static AString ToStringPriority	(	int	priority,
		AString	target
	)

inlinestatic

Writes a string representation of the priority value into the given AString.

Parameters

priority	The priority of the verbosity setting.
target	The target to write into.

Returns: target to allow concatenated calls.

Member Data Documentation

◆ AUTO_SIZES

VariableDecl AUTO_SIZES

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_AUTO_SIZES",
            null,
            '\0', null, Variable.FormatHint.None,
            "Auto size values of last run of Logger '%1' (generated and temporary values)."
        )

Attributes of corresponding configuration variable used by TextLogger.

◆ Config

Configuration Config =null

static

The configuration used by ALox. This is received or created with overloaded Init methods. It might be shared with other libraries or can be an instance explicitly dedicated to the ALox library.
The option to use an exclusive one may be used to store ALox configuration variables in different configuration files, e.g. to reduce "clutter" of an applications' then "main" configuration file.
Changes should only be made at very initial, single threaded bootstrap code, with the invocation of the according method Init(Configuration).

See also: Field ConfigCategory.

◆ ConfigCategory

AString ConfigCategory = new AString("ALOX" )

static

The name of the configuration category of configuration variables used by ALox.
Defaults to "ALOX".
This value can be changed to avoid conflicts between applications (especially in respect to environment variable settings). Changes should be placed at very initial bootstrap code, before the invocation of Init.
See also ALIB.ConfigCategory.

◆ CONSOLE_LIGHT_COLORS

VariableDecl CONSOLE_LIGHT_COLORS

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "CONSOLE_LIGHT_COLORS",
            "",
            '\0', null, Variable.FormatHint.None,
            "Evaluated by colorful loggers that dispose about light and dark colors. Those may\n"        +
            "adjust their foreground and background color accordingly. If not given, under Windows OS\n" +
            "the right value is detected. Otherwise the value defaults to \"foreground\". In some\n"     +
            "occasions, the (detected or set) runtime environment might also indicate a different\n"     +
            "default value. Possible values are 'foreground', 'background' and 'never'."
        )

Attributes of corresponding configuration variable used by colorful specializations of class TextLogger.

◆ CONSOLE_TYPE

VariableDecl CONSOLE_TYPE

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,             "CONSOLE_TYPE",
            "default",
            '\0', null, Variable.FormatHint.None,
            "Influences the type of console logger to be created by method\n"         +
            "Lox.CreateConsoleLogger which is also used by Log.AddDebugLogger\n"    +
            "Possible values are: default, plain, ansi, windows, noqtcreator"
            )

Attributes of corresponding configuration variable used by Lox.CreateConsoleLogger.

◆ DOMAIN_SUBSTITUTION

VariableDecl DOMAIN_SUBSTITUTION

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_DOMAIN_SUBSTITUTION",
            null,
            ';', "->", Variable.FormatHint.MultLine,
            ""
        )

Attributes of corresponding configuration variable used by Lox.

◆ DUMP_STATE_ON_EXIT

VariableDecl DUMP_STATE_ON_EXIT

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_DUMP_STATE_ON_EXIT",
            "none, verbosity=info, domain=/ALOX",
            ',', null, Variable.FormatHint.None,
            "Log information about lox \"%1\" on exit. Comma separated list of arguments define\n"    +
            "verbosity, domain and content of output. Possible values content arguments are:\n"       +
            "  All, Basic, Version, SPTR, Loggers, Domains, InternalDomains\n"   +
            "  ScopeDomains, DSR, PrefixLogablesOnce, LogData, ThreadMappings,\n"   +
            "  CompilationFlags. If NONE is given nothing is dumped."
        )

Attributes of corresponding configuration variable used by Lox.

◆ FORMAT

VariableDecl FORMAT

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_FORMAT",
 
            null,
 
            ',', null, Variable.FormatHint.MultLine,
            "Meta info format of text logger \"%1\", including signatures for verbosity strings and\n"   +
            "an optional string added to the end of each log statement.\n"                               +
            "   Format: metaInfoFormat [, Error [, Warning [, Info [, Verbose [, MsgSuffix ]]]]]"
        )

Attributes of corresponding configuration variable used by TextLogger.

◆ FORMAT_DATE_TIME

VariableDecl FORMAT_DATE_TIME

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_FORMAT_DATE_TIME",
 
            null,
 
            ',', null, Variable.FormatHint.None,
             "Meta info date and time format of text logger \"%1\".\n"              +
             "   Format: DateFormat [, TimeOfDayFormat [, TimeElapsedDays ]]]"
        )

Attributes of corresponding configuration variable used by TextLogger.

◆ FORMAT_MULTILINE

VariableDecl FORMAT_MULTILINE

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_FORMAT_MULTILINE",
 
            null,
 
            ',', null, Variable.FormatHint.None,
             "Multi-line format of text logger \"%1\".\n"                                                           +
             "   Format: MultiLineMsgMode [, FmtMultiLineMsgHeadline [, FmtMultiLinePrefix [, FmtMultiLineSuffix\n" +
             "           [, MultiLineDelimiter [, MultiLineDelimiterRepl ]]]]]"
        )

Attributes of corresponding configuration variable used by TextLogger.

◆ FORMAT_TIME_DIFF

VariableDecl FORMAT_TIME_DIFF

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_FORMAT_TIME_DIFF",
 
            null,
 
            ',', null, Variable.FormatHint.None,
             "Meta info time difference entities of text logger \"%1\".\n"                                        +
             "   Format: TimeDiffMinimum [, TimeDiffNone [, TimeDiffNanos [, TimeDiffMicros [, TimeDiffMillis \n" +
             "           [, TimeDiffSecs [, TimeDiffMins [, TimeDiffHours [,  TimeDiffDays  ]]]]]]]]"
        )

Attributes of corresponding configuration variable used by TextLogger.

◆ InternalDomains

readonly String InternalDomains ="$/"

static

This is the path for logging to the internal domain. By manipulating this Log Domain's Verbosity, the verbosity of ALox itself can be controlled. For example, with Verbosity.INFO, the 'on the fly' creation of Log Domains are logged, which can be helpful to determine the Log Domains that are created by libraries and larger projects.

The following sub-domains are used by ALox:

Sub-Domain	Description
LGR	Used when Loggers are registered, retrieved or removed from a Lox and when the Verbosity of a Log Domain for a Logger is changed. In addition used with method Lox.SetStartTime.
DMN	Used when Log Domains are registered (on first use), when Scope Domains are set or removed and when Domain Substitution Rules are set.
PFX	Used when Prefix Logables are set or removed.
THR	Used with method Lox.MapThreadName.
LGD	Used with storing and retrieving Log Data objects.

In addition, class ALoxReportWriter logs into sub-domain 'REPORT'.

Note: For internal logging an separated domain tree is used. This means, that setting the root domain of a Lox to a certain Verbosity does not affect the internal domains. In other words, the Verbosity of the internal domain (or one of its sub-domains) has to be set explicitly.

◆ isInitialized

bool isInitialized = false

staticprivate

State of initialization, used to avoid double initialization.

◆ loxes

List<Lox> loxes = new List<Lox>()

staticprivate

The Lox objects registered with us.

◆ MAX_ELAPSED_TIME

VariableDecl MAX_ELAPSED_TIME

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_MAX_ELAPSED_TIME",
            "0, limit=59",
            ',', null, Variable.FormatHint.None,
            "Maximum elapsed time of all runs of Logger '%1'. To reset elapsed time display\n" +
            "width, set this to 0 manually. Generated and temporary value.)"
        )

Attributes of corresponding configuration variable used by TextLogger.

◆ NO_IDE_LOGGER

VariableDecl NO_IDE_LOGGER

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "NO_IDE_LOGGER",
 
            "false",
            '\0', null, Variable.FormatHint.None,
             "If true, the creation of an additional, ide-specific debug logger is suppressed." +
             "(In particular suppresses CLRDebugLogger (C#) and VStudioLogger (C++))"
        )

Attributes of corresponding configuration variable used by Log.AddDebugLogger.

◆ PREFIXES

VariableDecl PREFIXES

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_PREFIXES",
            "",
            ';', "=", Variable.FormatHint.MultLine,
            "Prefix strings for log domains of lox \"%1\".\n"                           +
            "   Format: [*]domainpath[*] = prefixstring [, inclusion] [ ; … ] "
        )

Attributes of corresponding configuration variable used by Lox.

◆ REPLACEMENTS

VariableDecl REPLACEMENTS

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_REPLACEMENTS",
 
            null,
 
            ',', null, Variable.FormatHint.None,
            "Pairs of search and replacement strings for text logger \"%1\".\n"  +
            "   Format: search, replacement [, search, replacement] [,...]"
        )

Attributes of corresponding configuration variable used by TextLogger.

◆ Revision

readonly int Revision =0

static

The revision number of this release. Each ALox Version is initially released as revision 0. Pure maintenance releases that do not change the interface of ALox are holding the same Version but an increased number in this field.

◆ SPTR_GLOBAL

VariableDecl SPTR_GLOBAL

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "GLOBAL_SOURCE_PATH_TRIM_RULES",
            "",
            ';', "=", Variable.FormatHint.MultLine,
             "Defines global source path trim rules (applicable for all Lox instances).\n"   +
             "   Format: [*]sourcepath [, inclusion, trimoffset, sensitivity, replacement] [ ; … ]"
        )

Attributes of corresponding configuration variable ALOX_GLOBAL_SOURCE_PATH_TRIM_RULES.

◆ SPTR_LOX

VariableDecl SPTR_LOX

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_SOURCE_PATH_TRIM_RULES",
 
            "",
 
            ';', "=", Variable.FormatHint.MultLine,
             "Defines source path trim rules for Lox \"%1\".\n"           +
             "   Format: [*]sourcepath [, inclusion, trimoffset, sensitivity, replacement] [ ; … ]"
        )

Attributes of corresponding configuration variable used by Lox.

◆ VERBOSITY

VariableDecl VERBOSITY

static

Initial value:

= new VariableDecl(
            ConfigCategory,   null,     "%1_%2_VERBOSITY",
            "writeback;",
            ';', "=", Variable.FormatHint.MultLine,
            "The verbosities of logger \"%2\" in lox \"%1\". Use 'writeback [VAR_NAME] ;'\n" +
            "to enable automatic writing on application exit."
        )

Attributes of corresponding configuration variable ALOX_LOXNAME_LOGGERNAME_VERBOSITY.

◆ Version

readonly int Version =2402

static

The version of ALox. The version number follows the scheme YYMM (2-digit year, 2-digit month) of the initial release date. Besides this version number, field Revision indicates if this is a revised version of a former release.

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

ALox.cs

Class Description

Public Static Fields

Public Static Methods

Private Static Fields

Member Function Documentation

◆ Get()

◆ Init() [1/2]

◆ Init() [2/2]

◆ ReadVerbosity()

◆ Register()

◆ Reset()

◆ ToString() [1/2]

◆ ToString() [2/2]

◆ ToStringPriority()

Member Data Documentation

◆ AUTO_SIZES

◆ Config

◆ ConfigCategory

◆ CONSOLE_LIGHT_COLORS

◆ CONSOLE_TYPE

◆ DOMAIN_SUBSTITUTION

◆ DUMP_STATE_ON_EXIT

◆ FORMAT

◆ FORMAT_DATE_TIME

◆ FORMAT_MULTILINE

◆ FORMAT_TIME_DIFF

◆ InternalDomains

◆ isInitialized

◆ loxes

◆ MAX_ELAPSED_TIME

◆ NO_IDE_LOGGER

◆ PREFIXES

◆ REPLACEMENTS

◆ Revision

◆ SPTR_GLOBAL

◆ SPTR_LOX

◆ VERBOSITY

◆ Version