Description:

This class is a still abstract implementation of class Logger which is used as a base for all textual Logger implementations within ALox, e.g., ConsoleLogger.

One main purpose of the class is to generate the textual representation of the meta-information of a log call. The final log message is then passed to the abstract method logText. Hence, types that inherited from this class instead of directly from class detail::Logger, need to implement logText instead of implementing Log.

Class TextLogger supports multi line log outputs. Such multi line log outputs can be configured to be logged in different ways. See struct FormatMultiLine for more information.

Definition at line 179 of file textlogger.hpp.

#include <textlogger.hpp>

Inheritance diagram for TextLogger:

[legend]

Collaboration diagram for TextLogger:

[legend]

Public Field Index:
ObjectConverter *	Converter = nullptr

TickConverter	DateConverter

bool	FormatWarningOnce = false

Public Field Index: inherited from Logger
integer	CntLogs =0

time::Ticks	TimeOfCreation
	The creation time of the Logger.

time::Ticks	TimeOfLastLog
	Timestamp of the last log operation.

Public Field Index: inherited from RecursiveLock
DbgLockAsserter	Dbg
	The debug tool instance.

Public Method Index:
virtual ALIB_API	~TextLogger () override
	Destructs a TextLogger.

virtual ALIB_API void	AcknowledgeLox (detail::LoxImpl *lox, lang::ContainerOp op) override

virtual ALIB_API void	ClearReplacements ()
	Removes all pairs of searched strings and their replacement value.

FormatAutoSizes &	GetAutoSizes ()

FormatDateTime &	GetFormatDate ()

FormatMetaInfo &	GetFormatMetaInfo ()

FormatMultiLine &	GetFormatMultiLine ()

FormatOther &	GetFormatOther ()

FormatTimeDiff &	GetFormatTimeDiff ()

Replacements &	GetReplacements ()

virtual ALIB_API void	Log (detail::Domain &domain, Verbosity verbosity, BoxesMA &logables, detail::ScopeInfo &scope) override

virtual ALIB_API void	ResetAutoSizes ()

virtual ALIB_API void	SetReplacement (const String &searched, const String &replacement)

Public Method Index: inherited from Logger
virtual	~Logger () override
	Destructs a logger.

const NString &	GetName () const

const NString &	GetTypeName () const

Public Method Index: inherited from RecursiveLock
	~RecursiveLock () override
	Destructor. With debug-compilations, asserts that this lock is not acquired.

ALIB_API void	AcquireRecursive (ALIB_DBG_TAKE_CI)

virtual ALIB_API bool	DCSIsAcquired () const override

virtual ALIB_API bool	DCSIsSharedAcquired () const override

ALIB_API void	ReleaseRecursive (ALIB_DBG_TAKE_CI)

ALIB_API bool	TryAcquire (ALIB_DBG_TAKE_CI)

Public Method Index: inherited from DbgCriticalSections::AssociatedLock
virtual	~AssociatedLock ()
	Virtual Destructor.

Protected Field Index:
lang::system::CalendarDateTime	callerDateTime

AString	logBuf
	The internal log Buffer.

AString	msgBuf
	The buffers for converting the logables.

bool	usesStdStreams

Variable	varFormatAutoSizes

Variable	varFormatDateTime

Variable	varFormatMetaInfo

Variable	varFormatMultiLine

Variable	varFormatOther

Variable	varFormatTimeDiff

Variable	varReplacements

Protected Field Index: inherited from Logger
NString32	Name

NString32	TypeName

Protected Field Index: inherited from RecursiveLock
std::recursive_mutex	mutex

Protected Method Index:
ALIB_API	TextLogger (const NString &pName, const NString &typeName, bool pUsesStdStreams)

virtual void	logText (detail::Domain &domain, Verbosity verbosity, AString &msg, detail::ScopeInfo &scope, int lineNumber)=0

virtual void	notifyMultiLineOp (lang::Phase phase)=0

virtual ALIB_API void	processVariable (const NString &domainPath, Verbosity verbosity, detail::ScopeInfo &scope, AString &dest, Substring &variable)

virtual ALIB_API void	writeMetaInfo (AString &buffer, detail::Domain &domain, Verbosity verbosity, detail::ScopeInfo &scope)

virtual ALIB_API void	writeTimeDiff (AString &buffer, int64_t diffNanos)

Protected Method Index: inherited from Logger
	Logger (const NString &name, const NString &typeName)

Field Details:

◆ callerDateTime

lang::system::CalendarDateTime callerDateTime

protected

A singleton calendar time object shared between different format variables during one invocation.

Definition at line 238 of file textlogger.hpp.

◆ Converter

ObjectConverter* Converter = nullptr

A helper object to get textual representation of logable objects. If no converter is set when this logger is attached to a lox, a converter of type StandardConverter is created and used. Custom loggers might create their own, custom converter objects here. In the destructor of this class, the current object converter will be deleted.

To extend class TextLogger to support logging custom objects, custom converters can set. The preferred alternative is however, to make custom types be formattable by formatter classes used with StandardConverter.

Definition at line 254 of file textlogger.hpp.

◆ DateConverter

TickConverter DateConverter

This field is used to convert the steady and monotonic clock values provided with ScopeInfo::GetTimeStamp into human-readable, calendrical values in the moment, field Format contains tokens %TD and/or %TT.

This may become problematic and ambiguous if the system clock is changed during a software run. Especially for long-running background software (daemons, servers, etc.), the software that uses ALox needs to provide a strategy of synchronizing this converter with the system clock.

A simple strategy is to just periodically invoke TickConverter::SyncClocks, for example once a second.

For some explanation of the problem see details of namespace alib::time.

Definition at line 269 of file textlogger.hpp.

◆ FormatWarningOnce

bool FormatWarningOnce = false

If false, an one-time warning (using ALIB_WARNING) will be issued if the format string is illegal. With each warning, the flag is set to true to omit further warnings.

Definition at line 274 of file textlogger.hpp.

◆ logBuf

AString logBuf

protected

The internal log Buffer.

Definition at line 188 of file textlogger.hpp.

◆ msgBuf

AString msgBuf

protected

The buffers for converting the logables.

Definition at line 191 of file textlogger.hpp.

◆ usesStdStreams

bool usesStdStreams

protected

Denotes whether this logger writes to the standard output streams. If so, STD_IOSTREAMS_LOCK is acquired with writing.

Definition at line 195 of file textlogger.hpp.

◆ varFormatAutoSizes

Variable varFormatAutoSizes

protected

Variable of type FormatAutoSizes, which inherits class AutoSizes.The sizes are used for auto tab positions and field sizes. For each requested value, a corresponding array field is created on the fly. If the format string get's changed and different (new) auto values should be used, then this field should be reset after setting the new format string. The other way round, it is also possible to preset set minimum values for tabs and field sizes and hence avoid the columns growing during the lifetime of the Logger.

The second member of type AutoSizes is attached to field Converter when this TextLogger is attached to a Lox.

This field will be read from configuration variable ALOX/LOGGERNAME/AUTO_SIZES

Definition at line 229 of file textlogger.hpp.

◆ varFormatDateTime

Variable varFormatDateTime

protected

Variable of type FormatDateTime residing in the Configuration of camp ALox.

Definition at line 203 of file textlogger.hpp.

◆ varFormatMetaInfo

Variable varFormatMetaInfo

protected

Variable of type FormatMetaInfo residing in the Configuration of camp ALox.

Definition at line 199 of file textlogger.hpp.

◆ varFormatMultiLine

Variable varFormatMultiLine

protected

Variable of type FormatMultiLine residing in the Configuration of camp ALox.

Definition at line 211 of file textlogger.hpp.

◆ varFormatOther

Variable varFormatOther

protected

Variable of type FormatOther residing in the Configuration of camp ALox.

Definition at line 215 of file textlogger.hpp.

◆ varFormatTimeDiff

Variable varFormatTimeDiff

protected

Variable of type FormatTimeDiff residing in the Configuration of camp ALox.

Definition at line 207 of file textlogger.hpp.

◆ varReplacements

Variable varReplacements

protected

A list of pairs of strings. Within each log message, the first string of a pair is searched and replaced by the second string. Very simple, but useful in some cases.

Definition at line 233 of file textlogger.hpp.

Constructor(s) / Destructor Details:

◆ TextLogger()

TextLogger	(	const NString &	pName,
		const NString &	typeName,
		bool	pUsesStdStreams )

explicitprotected

Constructs a TextLogger.

Parameters

pName	The name of the Logger.
typeName	The type of the Logger.
pUsesStdStreams	Denotes whether this logger writes to the standard output streams.

Definition at line 570 of file textlogger.cpp.

◆ ~TextLogger()

~TextLogger ( )

overridevirtual

Destructs a TextLogger.

Definition at line 585 of file textlogger.cpp.

Method Details:

◆ AcknowledgeLox()

void AcknowledgeLox	(	detail::LoxImpl *	lox,
		lang::ContainerOp	op )

overridevirtual

Configuration variables are read within this method and created with default values, in the case they do not exist, yet. The variables read are:

alxcvALOX_LOGGERNAME_AUTO_SIZES
alxcvALOX_LOGGERNAME_FORMAT
alxcvALOX_LOGGERNAME_FORMAT_DATE_TIME
alxcvALOX_LOGGERNAME_FORMAT_TIME_DIFF
alxcvALOX_LOGGERNAME_FORMAT_MULTILINE
alxcvALOX_LOGGERNAME_FORMAT_OTHER
alxcvALOX_LOGGERNAME_REPLACEMENTS

Configuration variables are documented here.

Parameters

lox	The Lox to acknowledge insertion or removal
op	The operation. Either ContainerOp::Insert or ContainerOp::Remove.

Reimplemented from Logger.

Reimplemented in AnsiLogger, VStudioLogger, and WindowsConsoleLogger.

Definition at line 592 of file textlogger.cpp.

Here is the call graph for this function:

◆ ClearReplacements()

void ClearReplacements ( )

virtual

Removes all pairs of searched strings and their replacement value.

Definition at line 727 of file textlogger.cpp.

Here is the call graph for this function:

◆ GetAutoSizes()

FormatAutoSizes & GetAutoSizes ( )

inline

Provides access to the value of the internal configuration variable varFormatAutoSizes.
This variable is declared only after the logger was added to a Lox.

Returns: The struct containing the AutoSizes instances for the meta-information of the log message and for the log message itself.

Definition at line 305 of file textlogger.hpp.

Here is the call graph for this function:

◆ GetFormatDate()

FormatDateTime & GetFormatDate ( )

inline

Provides access to the value of the internal configuration variable varFormatDateTime.
This variable is declared only after the logger was added to a Lox.

Returns: The struct containing formatting information.

Definition at line 284 of file textlogger.hpp.

Here is the call graph for this function:

◆ GetFormatMetaInfo()

FormatMetaInfo & GetFormatMetaInfo ( )

inline

Provides access to the value of the internal configuration variable varFormatMetaInfo.
This variable is declared only after the logger was added to a Lox.

Returns: The struct containing formatting information.

Definition at line 279 of file textlogger.hpp.

Here is the call graph for this function:

◆ GetFormatMultiLine()

FormatMultiLine & GetFormatMultiLine ( )

inline

Provides access to the value of the internal configuration variable varFormatMultiLine.
This variable is declared only after the logger was added to a Lox.

Returns: The struct containing formatting information.

Definition at line 294 of file textlogger.hpp.

Here is the call graph for this function:

◆ GetFormatOther()

FormatOther & GetFormatOther ( )

inline

Provides access to the value of the internal configuration variable varFormatOther.
This variable is declared only after the logger was added to a Lox.

Returns: The struct containing formatting information.

Definition at line 299 of file textlogger.hpp.

Here is the call graph for this function:

◆ GetFormatTimeDiff()

FormatTimeDiff & GetFormatTimeDiff ( )

inline

Provides access to the value of the internal configuration variable varFormatTimeDiff.
This variable is declared only after the logger was added to a Lox.

Returns: The struct containing formatting information.

Definition at line 289 of file textlogger.hpp.

Here is the call graph for this function:

◆ GetReplacements()

Replacements & GetReplacements ( )

inline

Provides access to the value of the internal configuration variable varReplacements.
This variable is declared only after the logger was added to a Lox.

Returns: The Replacements instance for the logger in question.

Definition at line 310 of file textlogger.hpp.

Here is the call graph for this function:

◆ Log()

void Log	(	detail::Domain &	domain,
		Verbosity	verbosity,
		BoxesMA &	logables,
		detail::ScopeInfo &	scope )

overridevirtual

This is the implementation of the abstract method inherited from class Logger that executes a log.
This class implements this method and but exposes the new abstract method logText. This mechanism allows this class to do various things that are standard to Loggers of type TextLogger. For example, meta-information of the log invocation is formatted and string replacements are performed. This way, descendants of this class will consume a ready to use log buffer with all meta-information and contents of all objects to be included and their primary obligation is to copy the content into a corresponding output stream.

Parameters

domain	The Log Domain.
verbosity	The verbosity.
logables	The list of objects to log.
scope	Information about the scope of the Log Statement..

Implements Logger.

Definition at line 738 of file textlogger.cpp.

Here is the call graph for this function:

◆ logText()

virtual void logText	(	detail::Domain &	domain,
		Verbosity	verbosity,
		AString &	msg,
		detail::ScopeInfo &	scope,
		int	lineNumber )

protectedpure virtual

This abstract method introduced by this class "replaces" the abstract method Log of parent class Logger which this class implements. In other words, descendants of this class need to override this method instead of Log. This class TextLogger is responsible for generating meta-information, doing text replacements, handle multi-line messages, etc. and provides the textual representation of the whole log contents to descendants using this method.

Parameters

domain	The Log Domain.
verbosity	The verbosity. This has been checked to be active already on this stage and is provided to be able to be logged out only.
msg	The log message.
scope	Information about the scope of the Log Statement.
lineNumber	The line number of a multi-line message, starting with 0. For single line messages this is -1.

Implemented in AnsiLogger, WindowsConsoleLogger, and PlainTextLogger.

◆ notifyMultiLineOp()

virtual void notifyMultiLineOp ( lang::Phase phase )

protectedpure virtual

Abstract method to be implemented by descendants. This message is called only when multi-line messages are logged. It is called exactly once before a series of logText calls of a multi-line message and exactly once after such series.
This is useful if the writing of text includes the acquisition of system resources (e.g., opening a file).

Parameters

phase Indicates the beginning or end of a multi-line operation.

Implemented in AnsiLogger, ConsoleLogger, MemoryLogger, TextFileLogger, VStudioLogger, and WindowsConsoleLogger.

◆ processVariable()

void processVariable	(	const NString &	domainPath,
		Verbosity	verbosity,
		detail::ScopeInfo &	scope,
		AString &	dest,
		Substring &	variable )

protectedvirtual

Processes the next command found in the format string, by writing formatted information into the given buffer. The given Substring holds the next command. When the method returns, the command is cut from the front.

Parameters

domainPath	The Log Domain full path.
verbosity	The verbosity. This has been checked to be active already on this stage and is provided to be able to be logged out only.
scope	Information about the scope of the Log Statement..
dest	The buffer to write meta-information into.
variable	The variable to read (may have more characters appended)

Definition at line 140 of file textlogger.cpp.

◆ ResetAutoSizes()

void ResetAutoSizes ( )

virtual

Resets automatically widened tab stops and field widths of this logger by calling ResetAutoSizes on field Converter.

Note: The sizes affected are the ones used to format the custom log output, not the ones uses for the meta-information. To reset the auto-sizes of the meta information, invoke AutoSizes::Reset on field AutoSizes.

Definition at line 732 of file textlogger.cpp.

Here is the call graph for this function:

◆ SetReplacement()

void SetReplacement	(	const String &	searched,
		const String &	replacement )

virtual

Adds the given pair of replacement strings. If searched string already exists, the current replacement string gets replaced. If the replacement string is nullptr, nothing is set and a previously set replacement definition becomes unset.

Parameters

searched	The string to be searched.
replacement	The replacement string. If this equals 'nullptr' a previously set replacement will be unset.

Definition at line 698 of file textlogger.cpp.

Here is the call graph for this function:

◆ writeMetaInfo()

void writeMetaInfo	(	AString &	buffer,
		detail::Domain &	domain,
		Verbosity	verbosity,
		detail::ScopeInfo &	scope )

protectedvirtual

Parses the Format string and logs meta-information into the log buffer. For each variable found, method processVariable is invoked. Hence, to add new variables, the latter method can be overwritten by descendants. Overwriting this method is recommended for formatter classes that do not rely on format strings.

Parameters

buffer	The buffer to write meta-information into.
domain	The Log Domain.
verbosity	The verbosity.
scope	Information about the scope of the Log Statement..

Definition at line 111 of file textlogger.cpp.

◆ writeTimeDiff()

void writeTimeDiff	(	AString &	buffer,
		int64_t	diffNanos )

protectedvirtual

Helper function that logs a time given difference into the given buffer in a human-readable format. Works from nanoseconds seconds to days.

Parameters

buffer	The buffer to write the time difference representation into.
diffNanos	The time difference to write in nanoseconds.

Definition at line 413 of file textlogger.cpp.

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

Description:

Public Field Index:

Public Method Index:

Protected Field Index:

Protected Method Index:

Field Details:

◆ callerDateTime

◆ Converter

◆ DateConverter

◆ FormatWarningOnce

◆ logBuf

◆ msgBuf

◆ usesStdStreams

◆ varFormatAutoSizes

◆ varFormatDateTime

◆ varFormatMetaInfo

◆ varFormatMultiLine

◆ varFormatOther

◆ varFormatTimeDiff

◆ varReplacements

Constructor(s) / Destructor Details:

◆ TextLogger()

◆ ~TextLogger()

Method Details:

◆ AcknowledgeLox()

◆ ClearReplacements()

◆ GetAutoSizes()

◆ GetFormatDate()

◆ GetFormatMetaInfo()

◆ GetFormatMultiLine()

◆ GetFormatOther()

◆ GetFormatTimeDiff()

◆ GetReplacements()

◆ Log()

◆ logText()

◆ notifyMultiLineOp()

◆ processVariable()

◆ ResetAutoSizes()

◆ SetReplacement()

◆ writeMetaInfo()

◆ writeTimeDiff()