Inheritance diagram for Lox:

Collaboration diagram for Lox:

Class Description

This class acts as a container for Loggers and provides a convenient interface to logging. Fore information how to use this class, checkout the ALox tutorials and the ALox User Manual.

Public Types
enum	StateInfo { Basic = 1 << 0, Version = 1 << 1, Loggers = 1 << 2, Domains = 1 << 3, InternalDomains = 1 << 4, ScopeDomains = 1 << 5, DSR = 1 << 6, PrefixLogables = 1 << 7, Once = 1 << 8, LogData = 1 << 9, ThreadMappings = 1 << 10, SPTR = 1 << 20, All = ~0 }

Inner Classes
class	DomainSubstitutionRule

Public Fields
int	CntLogCalls =0

Public Fields inherited from ThreadLock
int	RecursionWarningThreshold =10

int	waitWarningTimeLimitInMillis =1000

Public Static Methods
static TextLogger	CreateConsoleLogger (String name=null)

Public Methods
	Lox (String name, bool doRegister=true)

override void	Acquire (int cln, String csf, String cmn)

void	Assert (bool condition, Object logableOrDomain, Object optLog2=null, Object optLog3=null, Object optLog4=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	ClearSourcePathTrimRules (Reach reach=Reach.Global, bool allowAutoRule=true, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Entry (String domain, Verbosity verbosity, Object[] logables, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	EntryDetectDomain (Verbosity verbosity, Object logableOrDomain, Object optLog2=null, Object optLog3=null, Object optLog4=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Error (Object logableOrDomain, Object optLog2=null, Object optLog3=null, Object optLog4=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

Logger	GetLogger (String loggerName, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

String	GetName ()

void	GetState (AString buf, Lox.StateInfo flags, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	If (bool condition, String domain, Verbosity verbosity, Object firstLog, Object optLog2=null, Object optLog3=null, Object optLog4=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	If (bool condition, Verbosity verbosity, Object firstLog, Object optLog2=null, Object optLog3=null, Object optLog4=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Info (Object logableOrDomain, Object optLog2=null, Object optLog3=null, Object optLog4=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

bool	IsRegistered ()

void	MapThreadName (String threadName, int id=-1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Object logables, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Object logables, Scope scope, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Object logables, String group, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Object logables, String group, Scope scope, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (String domain, Verbosity verbosity, Object logables, Scope scope=Scope.Global, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (String domain, Verbosity verbosity, Object logables, String group, Scope scope=Scope.Global, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (String domain, Verbosity verbosity, String logable, Scope scope=Scope.Global, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (String domain, Verbosity verbosity, String logable, String group, Scope scope=Scope.Global, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (String logable, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (String logable, Scope scope, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (String logable, String group, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (String logable, String group, Scope scope, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Verbosity verbosity, Object logables, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Verbosity verbosity, Object logables, Scope scope, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Verbosity verbosity, Object logables, String group, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Verbosity verbosity, Object logables, String group, Scope scope, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Verbosity verbosity, String logable, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Verbosity verbosity, String logable, Scope scope, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Verbosity verbosity, String logable, String group, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Once (Verbosity verbosity, String logable, String group, Scope scope, int quantity=1, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

override void	Release ()

void	RemoveLogger (Logger logger, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	RemoveLogger (Logger logger, ref bool wasFound, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	RemoveLogger (String loggerName, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	RemoveLogger (String loggerName, ref Logger logger, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	RemoveThreadDomain (String scopeDomain, Scope scope, Thread thread=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

Object	Retrieve (Scope scope=Scope.Global, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

Object	Retrieve (String key, Scope scope=Scope.Global, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetDomain (String scopeDomain, Scope scope, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetDomain (String scopeDomain, Scope scope, Thread thread, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetDomainSubstitutionRule (String domainPath, String replacement, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetPrefix (Object logable, Scope scope, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetPrefix (Object logable, Scope scope, Thread thread, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetPrefix (Object prefix, String domain=null, Inclusion otherPLs=Inclusion.Include, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetSourcePathTrimRule (String path, Inclusion includeString=Inclusion.Exclude, int trimOffset=0, Case sensitivity=Case.Ignore, String trimReplacement=null, Reach reach=Reach.Global, int priority=Configuration.PrioDefaultValues, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetStartTime (DateTime? startTime=null, String loggerName=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetVerbosity (Logger logger, Verbosity verbosity, String domain="/", int priority=Configuration.PrioDefaultValues, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	SetVerbosity (String loggerName, Verbosity verbosity, String domain="/", int priority=Configuration.PrioDefaultValues, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	State (String domain, Verbosity verbosity, String headLine, StateInfo flags, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Store (Object data, Scope scope=Scope.Global, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Store (Object data, String key, Scope scope=Scope.Global, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Verbose (Object logableOrDomain, Object optLog2=null, Object optLog3=null, Object optLog4=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

void	Warning (Object logableOrDomain, Object optLog2=null, Object optLog3=null, Object optLog4=null, [CallerLineNumber] int cln=0,[CallerFilePath] String csf="",[CallerMemberName] String cmn="")

Public Methods inherited from ThreadLock
	ThreadLock (LockMode lockMode=LockMode.Recursive, Safeness safeness=Safeness.Safe)

int	DbgCountAcquirements (Thread thread=null)

LockMode	GetMode ()

Safeness	GetSafeness ()

void	SetSafeness (Safeness safeness)

override String	ToString ()

bool	WillRelease ()

Protected Fields
Domain	domains

List< DomainSubstitutionRule >	domainSubstitutions =new List<DomainSubstitutionRule>()

Domain	internalDomains

AString	intMsg = new AString( 256 )

List< List< Object > >	logableLists = new List<List<Object>>()

bool	loggerAddedSinceLastDebugState =false

int	maxDomainPathLength = 0

int	maxLoggerNameLength = 0

readonly String	noKeyHashKey = "$"

bool	oneTimeWarningCircularDS =false

AString	resDomain = new AString( 32 )

AString	resDomainInternal = new AString( 32 )

ScopeStore< AString >	scopeDomains

ScopeInfo	scopeInfo

ScopeStore< Dictionary< AString, Object > >	scopeLogData

ScopeStore< Dictionary< AString, int[]> >	scopeLogOnce

ScopeStore< Object >	scopePrefixes

AString	tmpAS = new AString( 64 )

AString	tmpComments = new AString( 128 )

AString	tmpSubstitutionPath =new AString(64)

AString	tmpSubstitutionPathInternalDomains =new AString(64)

Protected Fields inherited from ThreadLock
int	cntAcquirements

LockMode	lockMode

Object	mutex

Thread	owner

Ticks	waitTime =new Ticks()

Protected Methods
int	checkScopeInformation (ref Scope scope, String internalDomain)

void	dumpStateOnLoggerRemoval ()

Domain	evaluateResultDomain (String domainPath)

void	getAllVerbosities (Logger logger, Domain dom, Variable cfgResult)

void	getDomainPrefixFromConfig (Domain dom)

void	getVerbosityFromConfig (Logger logger, Domain dom, Variable variable)

void	insertLogables (List< Object > list, Object logable)

bool	isThreadRelatedScope (Scope scope, int cln, String csf, String cmn)

void	log (Domain dom, Verbosity verbosity, Object[] logables, Inclusion prefixes)

void	logInternal (Verbosity verbosity, String subDomain, AString logable)

void	logStateCollectPrefixes (Domain domain, int indentSpaces, AString target)

void	logStateDomainRecursive (Domain domain, AString buf)

void	logStateDomainsWithDiffVerb (Domain domain, int loggerNo, List< Domain > results)

void	once (String domain, Verbosity verbosity, Object logable, String group, Scope scope, int quantity, int cln, String csf, String cmn)

void	setDomainImpl (String scopeDomain, Scope scope, bool removeNTRSD, Thread thread, int cln, String csf, String cmn)

void	setPrefixImpl (Object logable, Scope scope, Thread thread, int cln, String csf, String cmn)

void	verbositySettingToVariable (Domain domain, int loggerNo, Variable variable)

void	writeVerbositiesOnLoggerRemoval (Logger logger)

Private Methods
Domain	findDomain (Domain domainSystem, AString domainPath)

Member Enumeration Documentation

◆ StateInfo

enum StateInfo

strong

Denotes flags used with methods GetState and State to select different parts of the state receive.

Enumerator
Basic	Name 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.

Constructor & Destructor Documentation

◆ Lox()

Lox	(	String	name,
		bool	doRegister = `true`
	)

inline

Constructs a new, empty Lox with the given name. The name is immutable and all Lox objects registered with ALox must be unique. The name "Log" is reserved for the internal default singleton used for debug-logging. In addition, name "GLOBAL" is not allowed.

If parameter register is true (the default), static method ALox.Register is invoked and the object will be retrievable with static method ALox.Get. In some situations, such 'registration' may not be wanted.

Parameters

name	The name of the Lox. Will be converted to upper case.
doRegister	If `true`, this object is registered with static class ALox. Optional and defaults to `true`.

Member Function Documentation

◆ Acquire()

override void Acquire	(	int	cln,
		String	csf,
		String	cmn
	)

inlinevirtual

Acquires the lock and stores scope information

Parameters

cln	Caller info, compiler generated and passed to here.
csf	Caller info, compiler generated and passed to here.
cmn	Caller info, compiler generated and passed to here.

Reimplemented from ThreadLock.

◆ Assert()

void Assert	(	bool	condition,
		Object	logableOrDomain,
		Object	optLog2 = `null`,
		Object	optLog3 = `null`,
		Object	optLog4 = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs given logables only if the parameter condition is not true. If executed, Verbosity.Error is used.

The first object provided may be a domain name. All values are passed to EntryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

condition	If `false`, the Log Statement is executed.
logableOrDomain	The first logable or the domain path.
optLog2	Optional logable (or the first logable if logableOrDomain was the domain).
optLog3	Optional logable.
optLog4	Optional logable.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ checkScopeInformation()

int checkScopeInformation	(	ref Scope	scope,
		String	internalDomain
	)

inlineprotected

Checks if given scope needs information that is not available. In addition, the in/out parameter scope is changed to Scope.Path, in case a level was added. That level is returned.

Parameters

[in,out]	scope	The scope that is to be checked.
	internalDomain	The internal sub-domain to log any error/warning into.

Returns: A posititve value providing the path level deducted from scope if all is fine, -1 else.

◆ ClearSourcePathTrimRules()

void ClearSourcePathTrimRules	(	Reach	reach = `Reach.Global`,
		bool	allowAutoRule = `true`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Removes all local trimming rules set with SetSourcePathTrimRule. If parameter global is set to Inclusion.Include, the global rules are cleared in addition.

Setting parameter allowAutoRule to false, allows to suppress the creation of an automatic rule based on the executables path.

See also: ALox User Manual for more information.

Parameters

reach	Denotes whether only local rules are cleared or also global ones. Defaults to Reach.Global.
allowAutoRule	Determines if an auto rule should be tried to be detected next no appropriate rule is found.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ CreateConsoleLogger()

static TextLogger CreateConsoleLogger ( String name = null )

inlinestatic

This static method creates a console logger. To decide which logger type to choose, configuration variable ALOX_CONSOLE_TYPE is checked. If this variable is not set, then the decision is made as follows:

On GNU/Linux OS, a AnsiConsoleLogger is chosen.
On Windows OS, if a console window is attached, type ColorConsoleLogger is chosen. If no console is attached to the process, instead a ConsoleLogger is returned.

Parameters

name	(Optional) The name of the Logger. Defaults to null, which implies standard logger names defined in the Logger sub-classes.

Returns: The TextLogger chosen.

◆ dumpStateOnLoggerRemoval()

void dumpStateOnLoggerRemoval ( )

inlineprotected

Implements functionality for configuration variable LOXNAME_DUMP_STATE_ON_EXIT. Is called when a logger is removed.

◆ Entry()

void Entry	(	String	domain,
		Verbosity	verbosity,
		Object[]	logables,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs a Logable with the given Verbosity.

This method is usually not used directly. Instead, methods Info, Verbose, Warning and Error provide simpler interfaces which take a single logables that are collected in an array and then passed to this methods.
Note that the other methods accept an "external" list of boxes as a parameter as well. This means that also with these methods it is allowed to collect the logables in an user-specific Object[] first and later pass them to the methods.

Hence, the use of this method is recommended only if the verbosity of a log statement is is evaluated only at runtime.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The verbosity.
logables	The objects to log.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ EntryDetectDomain()

void EntryDetectDomain	(	Verbosity	verbosity,
		Object	logableOrDomain,
		Object	optLog2 = `null`,
		Object	optLog3 = `null`,
		Object	optLog4 = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs a list of optional Logables with the given Verbosity.

If more than one Logable is given and the first one is of string type and comprises a valid domain name, then this first argument is interpreted as a the domain name! Valid domain names are strings that consists only of characters of the following set:

upper case letters,
numbers,
hyphen ('-') and
underscore ('_').

If a first Logable could be misinterpreted as being a domain name, an empty string (the "neutral" domain) has to be added as a first argument. Alternatively, a character which is illegal in respect to domain names could be added to the first argument, for example a simple space at the end of an output string.

Note: This method allows a consistent interface of overloaded methods Info, Error, etc, without introducing a separate version which excepts a then mandatory domain parameter. The little drawback of the auto detection is the possibility of ambiguous invocations.

In the C# Version of ALox, the number of logables that might be directly passed to this method (respectively to methods Info, Verbose, etc.) is limited to four. The reason is of technical nature: In the C# we can not work with variadic argument lists, as the end of the argument list, the "hidden" parameters that collect caller information and which are provided by the compiler have to follow. This disallows the use of the elipse "..." pattern.
If more than those four objects should be logged, then these objects need to be embedded in an object array when invoking the method. The following sample demonstrates this:

Log.Info( "MYDOM", new Object[] {"The result of {} + {} is ", 10, 5, 10 + 5 } );

This way, an arbitrary amount of objects may be passed. Each parameter that represents a logable is allowed to be of type Object[].

Parameters

verbosity	The verbosity.
logableOrDomain	The first logable or the domain path.
optLog2	Optional logable (or the first logable if logableOrDomain was the domain).
optLog3	Optional logable.
optLog4	Optional logable.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Error()

void Error	(	Object	logableOrDomain,
		Object	optLog2 = `null`,
		Object	optLog3 = `null`,
		Object	optLog4 = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs the given Logables using Verbosity.Error.

The first object provided may be a domain name. All values are passed to EntryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

logableOrDomain	The first logable or the domain path.
optLog2	Optional logable (or the first logable if logableOrDomain was the domain).
optLog3	Optional logable.
optLog4	Optional logable.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ evaluateResultDomain()

Domain evaluateResultDomain ( String domainPath )

inlineprotected

Assembles the resulting domain from the given domainPath and the Scope Domain paths (see SetDomain) according to the scope identified by scopeInfo. The resulting full domain string is assembled from inner to outer scope. If domainPath, respectively as soon as any of the scope levels' Scope Domain paths starts with the character defined in Domain.Separator, the evaluation is stopped (the path is interpreted as absolute).

Parameters

domainPath The domain path. If starting with the character defined in Domain.Separator, no Scope Domains are applied.

Returns: The resulting Domain.

◆ findDomain()

Domain findDomain	(	Domain	domainSystem,
		AString	domainPath
	)

inlineprivate

Invokes Find on the given domain and logs internal message when the domain was not known before.

Parameters

domainSystem	The domain system. Either the standard or the internal one.
domainPath	The domain path.

Returns: The resulting Domain.

◆ getAllVerbosities()

void getAllVerbosities	(	Logger	logger,
		Domain	dom,
		Variable	cfgResult
	)

inlineprotected

Reads the verbosity for the given logger and domain from the ALib configuration system. This internal method is used when a new logger is added. Walks recursively for all existing domains.

Parameters

logger	The logger to set the verbosity for.
dom	The domain to set the verbosity for.
cfgResult	The result of the search for the variable to set verbosities from.

◆ getDomainPrefixFromConfig()

void getDomainPrefixFromConfig ( Domain dom )

inlineprotected

Reads a prefix string from the ALib configuration system. This internal method is used when a new domain is created,

Parameters

dom	The domain to set the verbosity for.

◆ GetLogger()

Logger GetLogger	(	String	loggerName,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Retrieves an instance of a Logger by its name. This might be useful when access to a Logger is needed to change its configuration.

Parameters

loggerName	The name of the Logger to search for (case insensitive).
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

Returns: The logger, null if not found.

◆ GetName()

String GetName ( )

inline

Returns the name of this Lox. The name user defined, provided in the constructor, converted to upper case and otherwise immutable.

Returns: The name of this Lox.

◆ GetState()

void GetState	(	AString	buf,
		Lox.StateInfo	flags,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

This method collects state information about this lox.

Parameters

buf	The target string.
flags	Flag bits that define which state information is collected.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ getVerbosityFromConfig()

void getVerbosityFromConfig	(	Logger	logger,
		Domain	dom,
		Variable	variable
	)

inlineprotected

Reads the verbosity for the given logger and domain from the ALib configuration system. This internal method is used in two occasions:

when a new logger is added: recursively for all existing domains (configStr is given)
when a new domain is created on the fly(configStr is not given)

Parameters

logger	The logger to set the verbosity for.
dom	The domain to set the verbosity for.
variable	The (already read) variable to set verbosities from.

◆ If() [1/2]

void If	(	bool	condition,
		String	domain,
		Verbosity	verbosity,
		Object	firstLog,
		Object	optLog2 = `null`,
		Object	optLog3 = `null`,
		Object	optLog4 = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs a list of Logables only if the parameter condition is true.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

See also: Method Assert.

Parameters

condition	If `false`, the Log Statement is executed.
domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The verbosity.
firstLog	The first logable.
optLog2	Optional logable.
optLog3	Optional logable.
optLog4	Optional logable.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ If() [2/2]

void If	(	bool	condition,
		Verbosity	verbosity,
		Object	firstLog,
		Object	optLog2 = `null`,
		Object	optLog3 = `null`,
		Object	optLog4 = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs a list of Logables only if the parameter condition is true.
This overloaded version omits parameter domain.

The first logable provided may be a domain name. All values are passed to EntryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

See also: Method Assert.

Parameters

condition	If `false`, the Log Statement is executed.
verbosity	The verbosity.
firstLog	The first logable or the domain path.
optLog2	Optional logable
optLog3	Optional logable.
optLog4	Optional logable.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Info()

void Info	(	Object	logableOrDomain,
		Object	optLog2 = `null`,
		Object	optLog3 = `null`,
		Object	optLog4 = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs the given Logables using Verbosity.Info.

The first object provided may be a domain name. All values are passed to EntryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

logableOrDomain	The first logable or the domain path.
optLog2	Optional logable (or the first logable if logableOrDomain was the domain).
optLog3	Optional logable.
optLog4	Optional logable.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ insertLogables()

void insertLogables	(	List< Object >	list,
		Object	logable
	)

inlineprotected

Simple helper method that inserts a logable at the front of given list. If the logable is an object array, each object will be inserted.

Parameters

list	The logable list
logable	The logable or array of logables.

◆ IsRegistered()

bool IsRegistered ( )

inline

Status of registration with ALox. To keep a Lox "private" using parameter doRegister of the constructor, allows to suppress registration. Registered instances of this class can be statically received (by their name) using ALox.Get.

Returns: true if this instance was registered with ALox, false if not.

◆ isThreadRelatedScope()

bool isThreadRelatedScope	(	Scope	scope,
		int	cln,
		String	csf,
		String	cmn
	)

inlineprotected

Checks if given scope is thread-related.

Parameters

scope	The scope that is to be checked.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

Returns: true if scope is thread-related, false else.

◆ log()

void log	(	Domain	dom,
		Verbosity	verbosity,
		Object[]	logables,
		Inclusion	prefixes
	)

inlineprotected

This method is looping over the Loggers, checking their verbosity against the given one, and, if they match, invoke the log method of the Logger. With the first logger identified to be active, the Prefix Objects get collected from the scope store.

Parameters

dom	The domain to log on
verbosity	The verbosity.
logables	The objects to log.
prefixes	Denotes if prefixes should be included or not.

◆ logInternal()

void logInternal	(	Verbosity	verbosity,
		String	subDomain,
		AString	logable
	)

inlineprotected

Logs an internal error message using the internal domain tree as defined in ALox.InternalDomains.

Parameters

verbosity	The verbosity.
subDomain	The sub-domain of the internal domain to log into.
logable	The message.

◆ logStateCollectPrefixes()

void logStateCollectPrefixes	(	Domain	domain,
		int	indentSpaces,
		AString	target
	)

inlineprotected

Internal method used by State() to recursively (DFS) log Prefix Logables bound to Log Domains

Parameters

domain	The actual domain to check.
indentSpaces	The number of spaces to write before each line.
target	The target string.

◆ logStateDomainRecursive()

void logStateDomainRecursive	(	Domain	domain,
		AString	buf
	)

inlineprotected

Internal method used by State() to recursively log Domain instances.

Parameters

domain	The Domain instance to log out.
buf	The buffer to log to.

◆ logStateDomainsWithDiffVerb()

void logStateDomainsWithDiffVerb	(	Domain	domain,
		int	loggerNo,
		List< Domain >	results
	)

inlineprotected

Internal method used by State() to recursively (DFS) collect Domains of Logger that have a different verbosity than their parent.

Parameters

domain	The actual domain to check.
loggerNo	The logger to collect domains for.
results	The result list.

◆ MapThreadName()

void MapThreadName	(	String	threadName,
		int	id = `-1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

This method sets a human readable name to the given thread ID (or current thread) which is optionally included in each log line.

Parameters

threadName	The name of the thread as it should be displayed in the logs
id	(Optional) Parameter providing the thread ID. If omitted, the current thread's ID is used.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [1/20]

void Once	(	Object	logables,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [2/20]

void Once	(	Object	logables,
		Scope	scope,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [3/20]

void Once	(	Object	logables,
		String	group,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [4/20]

void Once	(	Object	logables,
		String	group,
		Scope	scope,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ once()

void once	(	String	domain,
		Verbosity	verbosity,
		Object	logable,
		String	group,
		Scope	scope,
		int	quantity,
		int	cln,
		String	csf,
		String	cmn
	)

inlineprotected

Internal implementation of Once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logable	The string to log.
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [5/20]

void Once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		Scope	scope = `Scope.Global`,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [6/20]

void Once	(	String	domain,
		Verbosity	verbosity,
		Object	logables,
		String	group,
		Scope	scope = `Scope.Global`,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs given logables once, up to quantity times or every n-th time. In its simplest overloaded version, the counter is bound to the source code line, hence, only the first execution of this exact Log Statement is executed.

Using parameter group, a set of Log Statements that share the same group key, can be grouped and of such set, only the one which is first executed actually logs.
Alternatively, when key is omitted (or null or empty), but a Scope is given with parameter scope, then the counter is associated with the scope.
Finally, parameters key and scope can also be used in combination. The key is then unique in respect to the Scope provided.

Using, none, one or both of the parameters group and scope, among others, the following use cases can be achieved.

Log a specific statement up to n-times.
Log only the first n of a group of statements.
Log only the first n statements within a method.
Log only the first n statements belonging to the same group and method .
Log only the first n statements within any method of
- a source file
- a directory of source files
- a parent directory of source files and all sources recursively
Log only the first n statements which belong to the same group and are placed within any method of
- a source file
- a directory of source files
- a parent directory of source files and all sources recursively
Log a Log Statement n-times per new thread.
Log only the first n statements of a group of statements executed by a specific thread.

When parameter quantity is a negative value, the log statement is executed every n-th time instead n-times. E.g, if quantity is -5, the first statement is executed and afterwards every fifth invocation.

Note: Unlike other methods of this class which accept more than one logable, this method and its overloaded variants accept only one object. To supply several objects at once, an Object[] may be passed with parameter logables, like in the following sample:
Log.Once( new Object[] {"One - {} - {}!", "two", 3} );

Note: C# autoboxes parameter values of type 'int', which leads to ambiguous statements. This is why all Once methods are doubled with a String-type parameter logable to avoid ambiguities when a simple string is to be logged. Unfortunately, this leads to a large amount of overloaded versions.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`. If negative, the first and every "-quantity-th" statement is executed.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [7/20]

void Once	(	String	domain,
		Verbosity	verbosity,
		String	logable,
		Scope	scope = `Scope.Global`,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logable	The string message to log.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [8/20]

void Once	(	String	domain,
		Verbosity	verbosity,
		String	logable,
		String	group,
		Scope	scope = `Scope.Global`,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The Verbosity of the Log Statement (if performed).
logable	The string message to log.
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [9/20]

void Once	(	String	logable,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

logable	The string message to log.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [10/20]

void Once	(	String	logable,
		Scope	scope,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

logable	The string message to log.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [11/20]

void Once	(	String	logable,
		String	group,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

logable	The string message to log.
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [12/20]

void Once	(	String	logable,
		String	group,
		Scope	scope,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

logable	The string message to log.
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [13/20]

void Once	(	Verbosity	verbosity,
		Object	logables,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [14/20]

void Once	(	Verbosity	verbosity,
		Object	logables,
		Scope	scope,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [15/20]

void Once	(	Verbosity	verbosity,
		Object	logables,
		String	group,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [16/20]

void Once	(	Verbosity	verbosity,
		Object	logables,
		String	group,
		Scope	scope,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

verbosity	The Verbosity of the Log Statement (if performed).
logables	The object(s) to log. (Multiple objects may be provided as an Object[].)
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [17/20]

void Once	(	Verbosity	verbosity,
		String	logable,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

verbosity	The Verbosity of the Log Statement (if performed).
logable	The string message to log.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [18/20]

void Once	(	Verbosity	verbosity,
		String	logable,
		Scope	scope,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

verbosity	The Verbosity of the Log Statement (if performed).
logable	The string message to log.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [19/20]

void Once	(	Verbosity	verbosity,
		String	logable,
		String	group,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

verbosity	The Verbosity of the Log Statement (if performed).
logable	The string message to log.
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Once() [20/20]

void Once	(	Verbosity	verbosity,
		String	logable,
		String	group,
		Scope	scope,
		int	quantity = `1`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Once.

Parameters

verbosity	The Verbosity of the Log Statement (if performed).
logable	The string message to log.
group	The optional name of the statement group . If used, all statements that share the same group name are working on the same counter (according to the scope.) If omitted (or empty or null), the counter is is bound to the Scope provided. If omitted and scope is Scope.Global, then the counter is associated exclusively with the single Log Statement itself.
scope	The Scope that the group or counter is bound to.
quantity	The number of logs to be performed. As the name of the method indicates, this defaults to `1`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Release()

override void Release ( )

inlinevirtual

Releases latest scope information and the lock

Reimplemented from ThreadLock.

◆ RemoveLogger() [1/4]

void RemoveLogger	(	Logger	logger,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Removes a logger from this container.

Note: To (temporarily) disable a logger without removing it, a call to SetVerbosity( logger, Verbosity.Off ) can be used.

Parameters

logger	The logger to be removed.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ RemoveLogger() [2/4]

void RemoveLogger	(	Logger	logger,
		ref bool	wasFound,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Removes a logger from this container.

Note: To (temporarily) disable a logger without removing it, a call to SetVerbosity( logger, Verbosity.Off ) can be used.

Parameters

	logger	The logger to be removed.
[out]	wasFound	Output parameter that is set to `true`, if the Logger was found and removed, to `false` otherwise.
	cln	(Optional) Caller info, compiler generated. Please omit.
	csf	(Optional) Caller info, compiler generated. Please omit.
	cmn	(Optional) Caller info, compiler generated. Please omit.

◆ RemoveLogger() [3/4]

void RemoveLogger	(	String	loggerName,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Removes logger named loggerName from this container.

Note: To (temporarily) disable a logger without removing it, a call to SetVerbosity( logger, Verbosity.Off ) can be used.

Parameters

loggerName	The name of the Logger to be removed (case insensitive).
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ RemoveLogger() [4/4]

void RemoveLogger	(	String	loggerName,
		ref Logger	logger,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Removes logger named loggerName from this container.

Note: To (temporarily) disable a logger without removing it, a call to SetVerbosity( logger, Verbosity.Off ) can be used.

Parameters

	loggerName	The name of the Logger to be removed (case insensitive).
[out]	logger	Output parameter that returns the Logger that was removed, to null if not found.
	cln	(Optional) Caller info, compiler generated. Please omit.
	csf	(Optional) Caller info, compiler generated. Please omit.
	cmn	(Optional) Caller info, compiler generated. Please omit.

◆ RemoveThreadDomain()

void RemoveThreadDomain	(	String	scopeDomain,
		Scope	scope,
		Thread	thread = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

This method is used to remove an explicitly given domain path from the list of domain paths set for Scope.ThreadOuter or Scope.ThreadInner.

To remove the most recently added domain path from such thread-related Scope, use one of the overloaded methods SetDomain and provide an empty or nulled value for parameter scopeDomain (the same as how domain paths of other Scopes are removed).

Note: The long name of the method already indicates that this method is a little special. Only seldom, more than one Scope Domain is needed to be added. And if this is needed, then such Scope Domains usually get removed in reverse order of their definition, with is performed using the standard interface that allows 'removing' any other Scope Domain. (Passing an empty or nulled domain path to method SetDomain.)

Parameters

scopeDomain	The domain path to register.
scope	Either Scope.ThreadOuter or Scope.ThreadInner. With other values, an internal error is logged.
thread	The thread to set/unset a thread-related Scope Domains for. Defaults to the current thread.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Retrieve() [1/2]

Object Retrieve	(	Scope	scope = `Scope.Global`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Retrieve which omits parameter key.

Note: Log Data is a feature provided by ALox to support debug-logging. It is not advised to use Log Data to implement application logic.

Parameters

scope	The Scope that the data is bound to.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

Returns: The Object object, null if nothing was found.

◆ Retrieve() [2/2]

Object Retrieve	(	String	key,
		Scope	scope = `Scope.Global`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Retrieves an object which was previously stored with method Store. Optional parameters key and scope offer various possibilities to reference such objects.

Note: If no Log Data object is found, an empty object is stored and returned.

Note: Log Data is a feature provided by ALox to support debug-logging. It is not advised to use Log Data to implement application logic.

Parameters

key	The optional key to the data. If omitted (or empty or null), the data is bound to the Scope provided. If omitted and scope is Scope.Global, then the data is unique to the Lox.
scope	The Scope that the data is bound to.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

Returns: The Object object, null if nothing was found.

◆ SetDomain() [1/2]

void SetDomain	(	String	scopeDomain,
		Scope	scope,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

The given scopeDomain becomes the default domain path for given scope. This means, that any subsequent log invocations (from within this same scope) can omit the domain parameter, or if they provide one, this Scope Domain path is prepended. If subsequent log calls specify a domain name with a leading '/' character, then the Scope Domain of the scope is ignored.
Furthermore, if the given scope is an inner scope, outer scopes are prepended to the given scopeDomain when the resulting domain of a log invocation is evaluated. Again, this behavior can be overruled by prepending a leading '/' character to scopeDomain.

To remove a previously set Scope Domain a nulled or empty string has to be passed with parameter scopeDomain.

For Scope.ThreadOuter and Scope.ThreadInner, passing an empty or nulled string removes the most recently added domain path. For removing an explicitly named domain path of Scope.ThreadOuter and Scope.ThreadInner use method RemoveThreadDomain.

Parameters

scopeDomain	The domain path to register.
scope	The scope that should the given domain be registered for. Available Scope definitions are platform/language dependent.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetDomain() [2/2]

void SetDomain	(	String	scopeDomain,
		Scope	scope,
		Thread	thread,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

This overloaded version of SetDomain is applicable only for Scope.ThreadOuter and Scope.ThreadInner and allows to specify the thread that the setting should be associated with.

If scopeDomain is null or empty, the most recently added domain path is removed. For removing an explicitly named domain associated with a thread use method RemoveThreadDomain.

Parameters

scopeDomain	The domain path to register.
scope	Either Scope.ThreadOuter or Scope.ThreadInner. With other values, an internal error is logged.
thread	The thread to set/unset a thread-related Scope Domains for.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ setDomainImpl()

void setDomainImpl	(	String	scopeDomain,
		Scope	scope,
		bool	removeNTRSD,
		Thread	thread,
		int	cln,
		String	csf,
		String	cmn
	)

inlineprotected

Implementation of the interface method fetching all possible parameters.

Parameters

scopeDomain	The domain path to register.
scope	The scope that the given domain should be registered for. Available Scope definitions are platform/language dependent.
removeNTRSD	Used to remove thread-related Scope Domains (and is true only when invoked by interface method RemoveThreadDomain.
thread	The thread to set/unset a thread-related Scope Domain for.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetDomainSubstitutionRule()

void SetDomainSubstitutionRule	(	String	domainPath,
		String	replacement,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Adds a Domain Substitution Rule. Domain Substitution is performed as a last step when evaluating the domain path of a Log Statement, taking Scope Domains and the optional parameter domain of the statement into account.

Wildcards
Parameter domainPath supports 'wildcard' character '*' at its beginning and at its end (or both). This allows to have four types of rules:

Exact match
Prefix match (* at the end of domainPath)
Suffix match (* at the start of domainPath)
Substring match (* at both, start and the end of domainPath)

Only minimal checks are performed, e.g. if an exact match is requested, but domainPath does not start with character '/'. In this and some other cases, the rule is not stored and an internal warning is logged. Further checks, for example for illegal domain path characters are not performed (those will be eliminated when the resulting domain path is to be created internally).

Circular Dependencies
If the given rules have circular dependencies, only a limited number (ten) replacements are performed. If this number of replacements for one Log Statement is exceeded, an internal warning message is logged. This is done only once over the life-time of a Logger.

Application of Rules
Rules are applied in the order of their definition. After all rules have been applied this is repeated as long as at least one rule matched (up to ten times).

Deletion of Rules To delete a rule, invoke the method with same parameter domainPath and a 'nulled' or empty string for parameter replacement. To delete all rules, invoke the method with parameter domainPath 'nulled' or empty.

Final remarks Domain substitution is useful to permanently change ('redirect') domain paths of 3rd party code (e.g. libraries using ALox) or log statements that must not be changed for other reasons. It is advised to not 'overuse' this feature, as side effects are inherent to the concept of Domain Substitution. For example, an unwanted side effect might be that Prefix Logables are not applicable to the substituted domain, while other Prefix Logables are bound to the resulting domain.

For Lox objects that should be protected of external manipulation, it is advisable, to remove all Domain Substitution Rules right after the Lox was created by invoking this method with a nulled value for parameter domainPath. The reason is, that otherwise, through configuration files or command line parameters, domains of the Lox can be substituted and then the resulting domains Verbosities be overwritten using further configuration variables. Any prioritized 'internal' setting of Verbosities this way could be circumvented!

For more information consult the ALox User Manual.

Parameters

domainPath	The path to search. Has to start with either `'/'` or `'*'`.
replacement	The replacement path.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetPrefix() [1/3]

void SetPrefix	(	Object	logable,
		Scope	scope,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

The given prefix becomes a Prefix Logable provided to loggers with each log statement executed within the given scope. The list of objects received by a logger is sorted from outer scope to inner scope. The logable of the Log Statement itself, is the last in the list, except one or more Prefix Logables of Scope.ThreadInner are set. Those are (similar to how this Scope is used with Scope Domains) appended to the end of the list.

To remove a previously set Prefix Logable, null has to be passed with parameter logable. For Scope.ThreadOuter and Scope.ThreadInner, passing null removes the most recently added Prefix Logable.

Note: Unlike other methods of this class which accept more than one logable, this method and its overloaded variants accept only one (the prefix). To supply several objects to be prefix logables at once, those may be passed as an Object[] like shown in the following sample:
Log.SetPrefix( new Object[] {"One, ", "two, ", 3 }, Scope.Global );; The word 'prefix' in this methods' name and in the name of ALox feature Prefix Logables is chosen for the fact that with text loggers (which is the most widely applied use case for ALox) such objects are prefixes to the log message. Of-course, with using Scope.ThreadInner, this turns into a suffix!
When using ALox to process objects instead of log messages, the concept of Prefix Logables is very useful. Just the name does not fit so well anymore. Think of 'SetContext' and Context Objects instead.

Parameters

logable	The Prefix Logable to set.
scope	The scope that should the given logable be registered for. Available Scope definitions are platform/language dependent.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetPrefix() [2/3]

void SetPrefix	(	Object	logable,
		Scope	scope,
		Thread	thread,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

This overloaded version of SetPrefix is applicable only for Scope.ThreadOuter and Scope.ThreadInner and allows to specify the thread that the setting should be associated with.

If logable is null, the most recently added Prefix Logable is removed.

Parameters

logable	The Prefix Logable to set.
scope	Either Scope.ThreadOuter or Scope.ThreadInner. With other values, an internal error is logged.
thread	The thread to set/unset a thread-related Prefix Logable for.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetPrefix() [3/3]

void SetPrefix	(	Object	prefix,
		String	domain = `null`,
		Inclusion	otherPLs = `Inclusion.Include`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

The given logable becomes a Prefix Logable associated to the given Log Domain. Prefix Logables associated with the Log Domain are added to the list of Logables right before the main Logable of the Log Statement itself. Multiple Prefix Logables can be added per Log Domain.

To remove the most recently added Prefix Logable associated with a Log Domain, null has to be passed with parameter logable.

Attention: The same as with most interface methods of this class, the given domain parameter is combined with Scope Domains set for the callers' Scope. To suppress this, an absolute domain path can be used. (Still any Scope Domain of Scope.Thread.Inner will be applied). The default value of parameter domain is "" which addresses the domain evaluated for the current scope.

Parameters

prefix	The Prefix Logable to set.
domain	The domain path. Defaults to `null`, resulting in evaluated Scope Domain path.
otherPLs	If set to `Inclusion.Exclude`, scope-related Prefix Logables are ignored and only domain-related Prefix Logables are passed to the Loggers. Defaults to `Inclusion.Include`.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ setPrefixImpl()

void setPrefixImpl	(	Object	logable,
		Scope	scope,
		Thread	thread,
		int	cln,
		String	csf,
		String	cmn
	)

inlineprotected

Implementation of the interface method fetching all possible parameters.

Parameters

logable	The Prefix Logable to set.
scope	The scope that the given logable should be registered for. Available Scope definitions are platform/language dependent.
thread	The thread to set/unset a thread-related Prefix Logable for.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetSourcePathTrimRule()

void SetSourcePathTrimRule	(	String	path,
		Inclusion	includeString = `Inclusion.Exclude`,
		int	trimOffset = `0`,
		Case	sensitivity = `Case.Ignore`,
		String	trimReplacement = `null`,
		Reach	reach = `Reach.Global`,
		int	priority = `Configuration.PrioDefaultValues`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Adds path to an internal list of substrings that are used to trim the path of a source file name. Trimmed paths are used for Scope mechanisms and can be logged (e.g. with meta information of class TextLogger.

By default such setting affects all instances of class Lox, not only this instance. This can be altered using parameter global. one other The given trim information can either

If given path starts with character '*', the rest of the string is searched within source paths. Otherwise, it is checked if a source path starts with the given path.

Parameter includeString determines if the searched substring should be included in the resulting source path or not. In addition, parameter trimOffset, which can be negative or positive, is added to the position of trimming. This can be used to increase the length of the search path, and then cut only a portion of what was searched for.

Parameter trimReplacement optionally provides a replacement string for the trimmed path. This can be used for example to provide the right absolute path for an IDE to find source files of a library.

Finally, parameter sensitivity determines whether the match is performed case sensitive or not. It defaults to non-sensitive, for convenience and for the fact that for example Microsoft C++ compilers' preprocessor passes lower case path-strings!

Note: If the platform (compiler) specific path separator is '/', then characters '\' found in parameters path and trimReplacement are replaced by '\' and vice versa. This allows to specify paths and substrings thereof in a platform independent way.

Attention: Setting global rules (when parameter global equals Inclusion.Include) is not protected by a mutex against concurrent access. Therefore, global rules have to be either at bootstrap of a process, before threads are created, or such creation has to 'manually' be protected by locking all existing instances of this class!

Parameters

path	The path to search for. If not starting with `'*'`, a prefix is searched.
includeString	Determines if path should be included in the trimmed path or not. Optional and defaults to Inclusion.Exclude.
trimOffset	Adjusts the portion of path that is trimmed. Optional and defaults to `0`.
sensitivity	Determines if the comparison of path with a source files' path is performed case sensitive or not. Optional and defaults to Case.Ignore.
trimReplacement	Replacement string for trimmed portion of the path. Optional and defaults to NullString.
reach	Denotes whether the rule is applied locally (to this Lox only) or applies to all instances of class Lox. Defaults to Reach.Global.
priority	The priority of the setting. Defaults to Configuration.PrioDefaultValues, which is a lower priority than standard plug-ins of external configuration have.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetStartTime()

void SetStartTime	(	DateTime?	startTime = `null`,
		String	loggerName = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

This method is used reset (or to explicitly set) the start time of the Logger(s). The only impact is the output of time differences in the log lines. Hence, it is useful to see some absolute time values when doing basic performance tests using the Logger.

Note: This affects loggers that are registered for at least one standard domain. In other words, loggers that are exclusively attached to the internal domain, will not be affected.

Parameters

startTime	Optional parameter with the new start time. Defaults to current time if omitted.
loggerName	The name of the Logger(s) whose start time is to be set (case insensitive). Defaults to empty string, which indicates that all loggers are to be affected.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetVerbosity() [1/2]

void SetVerbosity	(	Logger	logger,
		Verbosity	verbosity,
		String	domain = `"/"`,
		int	priority = `Configuration.PrioDefaultValues`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Sets the Verbosity of the Log Domain which is evaluated from parameter domain and applicable Scope Domains. The verbosity given, is set recursively for all sub-domains.

With the first invocation of this method for a distinct logger, this Logger is registered with this Lox. In this case, prior to setting the given Verbosity for the evaluated sub-domain, the Verbosity for all domains is set to Verbosity.Off.

To deregister a Logger with a Lox, use method RemoveLogger. To 'disable' a Logger, invoke this method with parameters verbosity equaling to Verbosity.Off and domain to "/".

Optional parameter priority defaults to Configuration.PrioDefaultValues, which is a lower priority than those of the standard plug-ins of external configuration data. Therefore, external configuration by default 'overwrite' settings made from 'within the source code', which simply means by invoking this method.
The parameter can be provided for two main reasons:

To 'lock' a verbosity setting against external manipulation.
to 'break' the standard mechanism that an invocation of this method sets all sub-domains recursively. If a sub-domain was set with a higher priority (e.g. Configuration.PrioDefaultValues + 1, then this sub-domain will not be affected by future invocations of this method with standard-priority given.

Attention: The same as with most interface methods of this class, the given domain parameter is combined with Scope Domains set for the callers' Scope. In standard use cases of ALox, the Verbosity of a Domain is set using absolute domain path addressing. Therefore, it is recommended to have any domain path passed to this method starting with '/', which suppresses the concatenation of Scope Domains.
This is why this parameter with this method defaults to '/', while with other methods of this class, it defaults to an empty string.; Even when using an absolute domain path, Scope Domains of Scope.ThreadInner, will still apply. This means that from within a thread that has such Scope Domain set, this method is (almost) not usable! This all aligns with the concept (advice), that Loggers and their Verbosity are generally set outside of such scopes, hence in configuration sections of a process.; Consequently, this method may be (mis-) used to modify the 'actual' (default) scope when explicitly giving an empty string with parameter domain. This is useful, to temporarily adjust a scope. But remember: ALox was designed to avoid temporary code lines...

Parameters

logger	The logger to be to be affected (case insensitive).
verbosity	The 'level of verboseness' to be set.
domain	The parent (start) domain to be set. The use of absolute paths starting with `'/'` are recommended. Defaults to root domain "/".
priority	The priority of the setting. Defaults to Configuration.PrioDefaultValues.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ SetVerbosity() [2/2]

void SetVerbosity	(	String	loggerName,
		Verbosity	verbosity,
		String	domain = `"/"`,
		int	priority = `Configuration.PrioDefaultValues`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Same as SetVerbosity but addressing the Logger to manipulate by its name.
This method may only be used after a Logger was once 'registered' with this Lox using SetVerbosity.

Parameters

loggerName	The logger to be to be affected, identified by its name (case insensitive).
verbosity	The 'level of verboseness' to be set.
domain	The parent (start) domain to be set. The use of absolute paths starting with `'/'` are recommended. Defaults to root domain "/".
priority	The priority of the setting. Defaults to Configuration.PrioDefaultValues.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ State()

void State	(	String	domain,
		Verbosity	verbosity,
		String	headLine,
		StateInfo	flags,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

This method logs the current configuration of this Lox and its encapsulated objects. It uses method GetState to assemble the logable string.

Note: As an alternative to (temporarily) adding an invocation of Lox.State to your code, ALox provides configuration variable ALOX_LOXNAME_DUMP_STATE_ON_EXIT. This allows to enable an automatic invocation of this method using external configuration data like command line parameters, environment variables or INI files.

Parameters

domain	Optional Log Domain which is combined with Scope Domains set for the Scope of invocation.
verbosity	The verbosity.
headLine	If given, a separated headline will be logged at first place.
flags	Flag bits that define which state information is logged.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Store() [1/2]

void Store	(	Object	data,
		Scope	scope = `Scope.Global`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Overloaded version of Store(Object,const String,Scope, int,String,String) "Store" which omits parameter key.

Parameters

data	The data object to store. If `null`, currently stored data will be removed.
scope	The Scope that the data is bound to.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Store() [2/2]

void Store	(	Object	data,
		String	key,
		Scope	scope = `Scope.Global`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Stores an object which can afterwards be retrieved by invoking Retrieve. Optional parameters key and scope offer various possibilities to reference this data later.

To remove data from the store, pass null with parameter data.

Attention: When data objects are 'overwritten', previous objects will be deleted internally. Hence, only pointers to heap-allocated objects (created with new) may be passed!
For more information, consult the ALox User Manual.

Note: Log Data is a feature provided by ALox to support debug-logging. It is not advised to use Log Data to implement application logic.

Parameters

data	The data object to store. If `null`, currently stored data will be removed.
key	The optional key to the data. If omitted (or empty or null), the data is bound to the Scope provided. If omitted and scope is Scope.Global, then the data is unique to the Lox.
scope	The Scope that the data is bound to.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ Verbose()

void Verbose	(	Object	logableOrDomain,
		Object	optLog2 = `null`,
		Object	optLog3 = `null`,
		Object	optLog4 = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs the given Logables using Verbosity.Verbose.

The first object provided may be a domain name. All values are passed to EntryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

logableOrDomain	The first logable or the domain path.
optLog2	Optional logable (or the first logable if logableOrDomain was the domain).
optLog3	Optional logable.
optLog4	Optional logable.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ verbositySettingToVariable()

void verbositySettingToVariable	(	Domain	domain,
		int	loggerNo,
		Variable	variable
	)

inlineprotected

Helper method of dumpStateOnLoggerRemoval to recursively collect domain settings.

Parameters

domain	The actual domain.
loggerNo	The number of the logger
variable	The AString to collect the information.

◆ Warning()

void Warning	(	Object	logableOrDomain,
		Object	optLog2 = `null`,
		Object	optLog3 = `null`,
		Object	optLog4 = `null`,
		[CallerLineNumber] int	cln = `0`,
		[CallerFilePath] String	csf = `""`,
		[CallerMemberName] String	cmn = `""`
	)

inline

Logs the given Logables using Verbosity.Warning.

The first object provided may be a domain name. All values are passed to EntryDetectDomain. See documentation of this method for information on how to avoid ambiguities in respect to domain names.

If one of the arguments (or a single argument given) is of type Object[], then the contents of this list is inserted into the list of logables. This allows to collect logables prior to invoking the method. In the C# version, where flexibility of parameter passing is limited due to the use of compiler-inserted parameters, parameters of type Object[] can also be used to provide more than four logables.

Parameters

logableOrDomain	The first logable or the domain path.
optLog2	Optional logable (or the first logable if logableOrDomain was the domain).
optLog3	Optional logable.
optLog4	Optional logable.
cln	(Optional) Caller info, compiler generated. Please omit.
csf	(Optional) Caller info, compiler generated. Please omit.
cmn	(Optional) Caller info, compiler generated. Please omit.

◆ writeVerbositiesOnLoggerRemoval()

void writeVerbositiesOnLoggerRemoval ( Logger logger )

inlineprotected

Implements functionality for configuration variable LOXNAME_LOGGERNAME_VERBOSITY. Is called when a logger is removed.

Parameters

logger The logger to write the verbosity for.

Member Data Documentation

◆ CntLogCalls

int CntLogCalls =0

A counter for the quantity of calls. The count includes logs that were suppressed by disabled Log Domain and those suppressed by the optional log condition parameter.

◆ domains

Domain domains

protected

The root domain "/". All registered domains become a sub domain of this root. If a Sub-Log Domains' Verbosity is not explicitly set, such sub domain inherits the Verbosity of its parent.

◆ domainSubstitutions

List<DomainSubstitutionRule> domainSubstitutions =new List<DomainSubstitutionRule>()

protected

The list of domain substitution rules.

◆ internalDomains

Domain internalDomains

protected

The root domain for internal Log Domains.

◆ intMsg

AString intMsg = new AString( 256 )

protected

A temporary AString, following the "create once and reuse" design pattern.

◆ logableLists

List<List<Object> > logableLists = new List<List<Object>>()

protected

A list of lists of objects. The list is passed to the Loggers. For each recursive call, one list is created.

◆ loggerAddedSinceLastDebugState

bool loggerAddedSinceLastDebugState =false

protected

Flag used with configuration variable LOXNAME_DUMP_STATE_ON_EXIT.

◆ maxDomainPathLength

int maxDomainPathLength = 0

protected

Used for tabular output of logger lists

◆ maxLoggerNameLength

int maxLoggerNameLength = 0

protected

Used for tabular output of logger lists

◆ noKeyHashKey

readonly String noKeyHashKey = "$"

protected

A key value used in stores if no key is given (global object).

◆ oneTimeWarningCircularDS

bool oneTimeWarningCircularDS =false

protected

Flag if a warning on circular rule detection was logged.

◆ resDomain

AString resDomain = new AString( 32 )

protected

The resulting domain name.

◆ resDomainInternal

AString resDomainInternal = new AString( 32 )

protected

The resulting domain name for internal logs.

◆ scopeDomains

ScopeStore<AString> scopeDomains

protected

Scope Domains .

◆ scopeInfo

ScopeInfo scopeInfo

protected

Information about the source code, method, thread, etc. invoking a log call

◆ scopeLogData

ScopeStore<Dictionary<AString, Object> > scopeLogData

protected

Log Data

◆ scopeLogOnce

ScopeStore<Dictionary<AString, int[]> > scopeLogOnce

protected

Log once counters

◆ scopePrefixes

ScopeStore<Object> scopePrefixes

protected

Prefix logables store

◆ tmpAS

AString tmpAS = new AString( 64 )

protected

A temporary AString

◆ tmpComments

AString tmpComments = new AString( 128 )

protected

A temporary AString

◆ tmpSubstitutionPath

AString tmpSubstitutionPath =new AString(64)

protected

Temporary string used with domain substitutions.

◆ tmpSubstitutionPathInternalDomains

AString tmpSubstitutionPathInternalDomains =new AString(64)

protected

Temporary string used with domain substitutions.

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

Lox.cs

Class Description

Public Types

Inner Classes

Public Fields

Public Static Methods

Public Methods

Protected Fields

Protected Methods

Private Methods

Member Enumeration Documentation

◆ StateInfo

Constructor & Destructor Documentation

◆ Lox()

Member Function Documentation

◆ Acquire()

◆ Assert()

◆ checkScopeInformation()

◆ ClearSourcePathTrimRules()

◆ CreateConsoleLogger()

◆ dumpStateOnLoggerRemoval()

◆ Entry()

◆ EntryDetectDomain()

◆ Error()

◆ evaluateResultDomain()

◆ findDomain()

◆ getAllVerbosities()

◆ getDomainPrefixFromConfig()

◆ GetLogger()

◆ GetName()

◆ GetState()

◆ getVerbosityFromConfig()

◆ If() [1/2]

◆ If() [2/2]

◆ Info()

◆ insertLogables()

◆ IsRegistered()

◆ isThreadRelatedScope()

◆ log()

◆ logInternal()

◆ logStateCollectPrefixes()

◆ logStateDomainRecursive()

◆ logStateDomainsWithDiffVerb()

◆ MapThreadName()

◆ Once() [1/20]

◆ Once() [2/20]

◆ Once() [3/20]

◆ Once() [4/20]

◆ once()

◆ Once() [5/20]

◆ Once() [6/20]

◆ Once() [7/20]

◆ Once() [8/20]

◆ Once() [9/20]

◆ Once() [10/20]

◆ Once() [11/20]

◆ Once() [12/20]

◆ Once() [13/20]

◆ Once() [14/20]

◆ Once() [15/20]

◆ Once() [16/20]

◆ Once() [17/20]

◆ Once() [18/20]

◆ Once() [19/20]

◆ Once() [20/20]

◆ Release()

◆ RemoveLogger() [1/4]

◆ RemoveLogger() [2/4]

◆ RemoveLogger() [3/4]

◆ RemoveLogger() [4/4]

◆ RemoveThreadDomain()

◆ Retrieve() [1/2]

◆ Retrieve() [2/2]

◆ SetDomain() [1/2]

◆ SetDomain() [2/2]

◆ setDomainImpl()

◆ SetDomainSubstitutionRule()

◆ SetPrefix() [1/3]

◆ SetPrefix() [2/3]

◆ SetPrefix() [3/3]

◆ setPrefixImpl()