ALib C++ Library
Library Version: 2402 R1
Documentation generated by doxygen
No Matches
TextLogger Class Referenceabstract


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

The class uses a helper class to generate the textual representation of the meta information of a log call. This helper can be extended and replaced in MetaInfo to modify the behavior of TextLogger.

The final log message is then passed to the abstract method logText. Hence, custom Logger classes that inherited from this class instead of directly from class 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 MultiLineMsgMode for more information.

Definition at line 436 of file textlogger.hpp.

#include <textlogger.hpp>

Inheritance diagram for TextLogger:
Collaboration diagram for TextLogger:

Public Type Index:

enum class  LightColorUsage { Auto , Never , Foreground , Background }

Public Field Index:

strings::util::AutoSizes AutoSizes
ObjectConverterConverter = nullptr
String16 FmtMsgSuffix
String64 FmtMultiLineMsgHeadline = A_CHAR("ALox: Multi line message follows: ")
String16 FmtMultiLinePrefix = A_CHAR(">> ")
String16 FmtMultiLineSuffix = A_CHAR("")
AString MultiLineDelimiter
String16 MultiLineDelimiterRepl = A_CHAR("\\r")
int MultiLineMsgMode =2
- Public Field Index: inherited from Logger
integer CntLogs =0
time::Ticks TimeOfCreation
time::Ticks TimeOfLastLog
- Public Field Index: inherited from ThreadLock
NCString DbgOwnerFile =nullptr
NCString DbgOwnerFunc =nullptr
int DbgOwnerLine
uint16_t DbgRecursionWarningThreshold =10
integer DbgWarningAfterWaitTimeInMillis =2000L

Public Method Index:

virtual ALIB_API ~TextLogger () override
virtual ALIB_API void AcknowledgeLox (LoxImpl *lox, lang::ContainerOp op) override
virtual ALIB_API void ClearReplacements ()
virtual ALIB_API void Log (Domain &domain, Verbosity verbosity, Boxes &logables, 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 ()
const NStringGetName () const
const NStringGetTypeName () const
- Public Method Index: inherited from SmartLock
 SmartLock ()
void Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)
ALIB_API int AddAcquirer (ThreadLock *newAcquirer)
ALIB_API int CntAcquirers ()
ALIB_API void Release ()
ALIB_API int RemoveAcquirer (ThreadLock *acquirer)
- Public Method Index: inherited from ThreadLock
ALIB_API ThreadLock (lang::Safeness safeness=lang::Safeness::Safe)
ALIB_API ~ThreadLock ()
ALIB_API void Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)
int CountAcquirements () const
ThreadGetOwner () const
lang::Safeness GetSafeness () const
bool IsOwnedByCurrentThread () const
ALIB_API void Release ()
ALIB_API void SetSafeness (lang::Safeness safeness)
bool WillRelease () const

Additional Inherited Members

- Public Static Field Index: inherited from SmartLock
static ALIB_API SmartLock StdOutputStreams

Enumeration Details:

◆ LightColorUsage

enum class LightColorUsage

Denotes the use of light vs dark colors. Used with descendant classes only.




Never use light colors.


Use light colors for foreground.


Use light colors for background.

Definition at line 468 of file textlogger.hpp.

Field Details:

◆ AutoSizes

Holds a list of values 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.

This field will be read from configuration variable ALOX_LOGGERNAME_AUTO_SIZES when this TextLogger is attached to a Lox and written back on removal.

Definition at line 523 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 491 of file textlogger.hpp.

◆ FmtMsgSuffix

String16 FmtMsgSuffix

Characters written after each Log Statement. This may be used for example to reset colors and styles. Note, that with multi-line Log Statements, the contents of this field is not written at the end of each line, but only at the end of the last line. To define characters that are written after each line of a multi-line Log Statement, field FmtMultiLineSuffix.

Defaults to empty string.

Definition at line 510 of file textlogger.hpp.

◆ FmtMultiLineMsgHeadline

String64 FmtMultiLineMsgHeadline = A_CHAR("ALox: Multi line message follows: ")

Headline for multi line messages (depending on MultiLineMsgMode) . Defaults to "ALox: Multi line message follows: "

Definition at line 566 of file textlogger.hpp.

◆ FmtMultiLinePrefix

String16 FmtMultiLinePrefix = A_CHAR(">> ")

Prefix for multi line messages. This is also used if multi line messages logging is switched off (MultiLineMsgMode == 0) but replacing of a set MultiLineDelimiter takes place. Defaults to ">> ".

Definition at line 574 of file textlogger.hpp.

◆ FmtMultiLineSuffix

String16 FmtMultiLineSuffix = A_CHAR("")

Suffix for multi line messages. This is also used if multi line messages logging is switched off (MultiLineMsgMode == 0) and replacing of a set MultiLineDelimiter takes place.
Note that at the end of the last line, in addition FmtMsgSuffix is added.
Defaults to "".

Definition at line 583 of file textlogger.hpp.

◆ logBuf

AString logBuf

The internal log Buffer.

Definition at line 445 of file textlogger.hpp.

◆ MetaInfo

A helper object to format log objects into textual representations. This class incorporates a format string that defines the meta information in the log output. Furthermore, to extend TextLogger, this object can be replaced by custom implementations of it.

Definition at line 498 of file textlogger.hpp.

◆ msgBuf

AString msgBuf

The buffers for converting the logables.

Definition at line 448 of file textlogger.hpp.

◆ MultiLineDelimiter

AString MultiLineDelimiter

This is the string interpreted as line delimiter within log messages. If nulled, then '\n', '\r' or '\r\n' is recognized.
Important: Can be set to an empty string, to stop any multi line processing of TextLogger, even the replacements of the delimiter character.

Definition at line 553 of file textlogger.hpp.

◆ MultiLineDelimiterRepl

String16 MultiLineDelimiterRepl = A_CHAR("\\r")

This is the readable (!) separator string, for logging out multi line messages into a single line (MultiLineMsgMode==0). Defaults to "\\r".

Definition at line 560 of file textlogger.hpp.

◆ MultiLineMsgMode

int MultiLineMsgMode =2

Determines if multi line messages should be split into different log lines. Possible values are:

  • 0: No line split is performed, delimiters can be replaced by readable delimiters (depending on setting of MultiLineDelimiter and # MultiLineDelimiterRepl).
  • 1: Each log line contains all meta information
  • 2: Starting with second log line, meta information is replaced by blanks (default)
  • 3: The headline FmtMultiLineMsgHeadline is logged and all lines of the multi line text are logged at position zero (without further meta information)
  • 4: Just the multi line text is logged, starting at column zero (no meta information is logged)
In modes 3 and 4, no ESC::EOMETA is included at the beginning of the message. Loggers that need such info, have to implement method notifyMultiLineOp.

Definition at line 545 of file textlogger.hpp.

◆ replacements

std::vector<AString> replacements

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 464 of file textlogger.hpp.

◆ stdStreamLockRegistrationCounter

int stdStreamLockRegistrationCounter =0

Used to avoid repeated registration with ALib standard output stream lockers when attached to multiple instances of class Lox.

Definition at line 457 of file textlogger.hpp.

◆ usesStdStreams

bool usesStdStreams

Denotes whether this logger writes to the standard output streams. If so, SmartLock::StdOutputStreams is acquired on logging.

Definition at line 452 of file textlogger.hpp.

Constructor(s) / Destructor Details::

◆ TextLogger()

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

Constructs a TextLogger. Reads the format variable for the meta information from the configuration. The variable name is created from the Logger name and the suffix '_FORMAT'

pNameThe name of the Logger.
typeNameThe type of the Logger.
pUsesStdStreamsDenotes whether this logger writes to the standard output streams.

Definition at line 571 of file textlogger.cpp.

◆ ~TextLogger()

~TextLogger ( )

Destructs a TextLogger.

Definition at line 580 of file textlogger.cpp.

Method Details:

◆ AcknowledgeLox()

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

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

  • ALox::FORMAT

Configuration variables are documented here.

Furthermore, invokes grand-parent's method SmartLock::AddAcquirer , respectively SmartLock::RemoveAcquirer and in addition, if field usesStdStreams is set, registers with SmartLock::StdOutputStreams .

loxThe Lox to acknowledge insertion or removal
opThe operation. Either ContainerOp::Insert or ContainerOp::Remove.

Reimplemented from Logger.

Definition at line 588 of file textlogger.cpp.

Here is the call graph for this function:

◆ ClearReplacements()

void ClearReplacements ( )

Removes all pairs of searched strings and their replacement value.

Definition at line 854 of file textlogger.cpp.

◆ Log()

void Log ( Domain & domain,
Verbosity verbosity,
Boxes & logables,
ScopeInfo & scope )

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.

domainThe Log Domain.
verbosityThe verbosity.
logablesThe list of objects to log.
scopeInformation about the scope of the Log Statement..

Implements Logger.

Definition at line 865 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.

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

Implemented in WindowsConsoleLogger, PlainTextLogger, and AnsiLogger.

◆ 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).

phaseIndicates the beginning or end of a multi-line operation.

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

◆ ResetAutoSizes()

void ResetAutoSizes ( )

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

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 859 of file textlogger.cpp.

◆ SetReplacement()

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

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.

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

Definition at line 828 of file textlogger.cpp.

Here is the call graph for this function:

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