textlogger.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_alox of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace lox {
 
//==================================================================================================
/// This namespaces defines class #"%TextLogger" and its helpers.
//==================================================================================================
namespace textlogger {
 
//==================================================================================================
/// This abstract class represents a plug-in for the TextLogger class which converts the list
/// of logables into a textual representation.
/// \see StandardConverter for further information.
//==================================================================================================
class ObjectConverter {
  public:
    /// Destructs an object of this class.
    virtual            ~ObjectConverter()                                                         {}
 
    /// The conversion method.
    /// @param target     An AString that takes the result.
    /// @param logables   The objects to convert.
    virtual void        ConvertObjects( AString& target, BoxesMA& logables )                     =0;
 
    /// If this converter uses an #"util::AutoSizes" object, this method passes
    /// an external object to use.
    /// @param autoSizes   The instance to use.
    ALIB_DLL
    virtual void        SetAutoSizes( AutoSizes* autoSizes )                                     =0;
 
    /// If this converter uses an #"util::AutoSizes" object, this method returns
    /// such object.
    /// @return The auto sizes used, \c nullptr if not applicable.
    virtual AutoSizes*  GetAutoSizes()                                                           =0;
 
    /// If this converter uses an #"util::AutoSizes" object, values of this field
    /// are reset.
    virtual void        ResetAutoSizes()                                                         =0;
};
 
//==================================================================================================
/// Implements the interface
/// #"alib::lox::textlogger::ObjectConverter;ObjectConverter". Class
/// #"alib::lox::textlogger::TextLogger;TextLogger" creates an instance of this type at
/// the moment no other (custom) type was set before the first log statement.
///
/// This implementation uses two specializations of class #"format::Formatter" to format the
/// given logables to a textual representation. The formatters (and their sequence!) are:
///
/// 1. #"FormatterPythonStyle"
/// 2. #"FormatterJavaStyle"
///
/// This way, standard text logging supports format strings in Python-style as well as in
/// Java-style.
//==================================================================================================
class StandardConverter : public ObjectConverter {
  public:
    /// A list of formatters used to "convert" logables to strings.
    /// By default, each entry contains a concatenated pair of formatters of types
    /// #"FormatterPythonStyle" and
    /// #"FormatterJavaStyle" are added in the
    /// constructor of this class.
    ///
    /// A vector of formatters is needed to support recursive log calls.
    /// If recursion occurs during logging (aka the conversion of a logable triggers another
    /// logging operation), the necessary formatters are created on the fly, respectively re-used
    /// from previous recursions.
    /// Their settings are cloned to those of the main formatters
    /// using #"Formatter::CloneSettings;*".
    ///
    /// To use different formatters, it is recommended to implement a different converter
    /// type, instead of "patching" the linked and recursive formatters found in this vector.
    std::vector<Formatter*>             Formatters;
 
  protected:
    /// A counter to detect recursive calls.
    int                                 cntRecursion;
 
  public:
 
    /// Constructor.
    ALIB_DLL            StandardConverter();
 
    /// Virtual destructor.
    ALIB_DLL
    virtual            ~StandardConverter()                                                override;
 
    /// The conversion method.
    /// Passes \p{target} and \p{logables} to the #"Formatters".
    /// @param target     An AString that takes the result.
    /// @param logables   The objects to convert.
    ALIB_DLL
    virtual void        ConvertObjects( AString& target, BoxesMA& logables )               override;
 
    /// Checks if the first formatter in #"Formatters" is of type
    /// #"FormatterPythonStyle". If so, its #"%AutoSizes" member is set to
    /// the given external instance. Otherwise the call is ignored.
    /// @param autoSizes The instance to use.
    ALIB_DLL
    virtual void        SetAutoSizes( AutoSizes* autoSizes )                               override;
 
    /// Checks if the first formatter in #"Formatters" is of type
    /// #"FormatterPythonStyle". If so, its #"%AutoSizes" member is returned.
    /// If not, the method returns \c nullptr.
    /// @return The auto sizes object of the main formatter.
    ALIB_DLL
    virtual AutoSizes*  GetAutoSizes()                                                     override;
 
    /// Resets automatically widened tab stops and field widths of this converter.
    ALIB_DLL
    virtual void        ResetAutoSizes()                                                   override;
}; //class StandardConverter
 
 
//==================================================================================================
/// 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 #"textlogger::FormatMultiLine" for more
/// information.
//==================================================================================================
class TextLogger : public Logger {
 
  //################################################################################################
  // Internal fields
  //################################################################################################
  protected:
 
    /// The internal log Buffer.
    AString     logBuf;
 
    /// The buffer for converting the logables.
    AString     msgBuf;
 
    /// Variable of type #"textlogger::FormatMetaInfo" residing in the
    /// #"Configuration" of camp \alib_alox.
    Variable    varFormatMetaInfo;
 
    /// Variable of type #"textlogger::FormatDateTime" residing in the
    /// #"Configuration" of camp \alib_alox.
    Variable    varFormatDateTime;
 
    /// Variable of type #"textlogger::FormatTimeDiff" residing in the
    /// #"Configuration" of camp \alib_alox.
    Variable    varFormatTimeDiff;
 
    /// Variable of type #"textlogger::FormatMultiLine" residing in the
    /// #"Configuration" of camp \alib_alox.
    Variable    varFormatMultiLine;
 
    /// Variable of type #"textlogger::FormatOther" residing in the
    /// #"Configuration" of camp \alib_alox.
    Variable    varFormatOther;
 
    /// Variable of type #"textlogger::FormatAutoSizes", which inherits class
    /// #"util::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 #"alxcvALOX_LOGGERNAME_AUTO_SIZES"
    Variable    varFormatAutoSizes;
 
    /// 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.
    Variable    varReplacements;
 
 
    /// A singleton calendar time object shared between different format variables during one
    /// invocation.
    strings::util::CalendarDateTime callerDateTime;
 
 
  //################################################################################################
  // Public fields
  //################################################################################################
  public:
    /// 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
    /// #"textlogger::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".
    ObjectConverter*            Converter                                                 = nullptr;
 
    /// This field is used to convert the steady and monotonic clock values provided with
    /// #"ScopeInfo::GetTimeStamp;2" into human-readable, calendrical values in the case
    /// that field #".varFormatMetaInfo" contains tokens <c>%%TD</c> and/or <c>%%TT</c>.
    ///
    /// 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;2".
    TickConverter               DateConverter;
 
    /// If \c 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 \c true to omit further
    /// warnings.
    bool                        FormatWarningOnce                                            =false;
 
    /// Provides access to the value of the internal configuration variable #".varFormatMetaInfo".<br>
    /// This variable is declared only after the logger was added to a #"%Lox".
    /// @return The struct containing formatting information.
    FormatMetaInfo&  GetFormatMetaInfo()         { return varFormatMetaInfo.Get<FormatMetaInfo>(); }
 
    /// Provides access to the value of the internal configuration variable #".varFormatDateTime".<br>
    /// This variable is declared only after the logger was added to a #"%Lox".
    /// @return The struct containing formatting information.
    FormatDateTime&  GetFormatDate()             { return varFormatDateTime.Get<FormatDateTime>(); }
 
    /// Provides access to the value of the internal configuration variable #".varFormatTimeDiff".<br>
    /// This variable is declared only after the logger was added to a #"%Lox".
    /// @return The struct containing formatting information.
    FormatTimeDiff&  GetFormatTimeDiff()         { return varFormatTimeDiff.Get<FormatTimeDiff>(); }
 
    /// Provides access to the value of the internal configuration variable #".varFormatMultiLine".<br>
    /// This variable is declared only after the logger was added to a #"%Lox".
    /// @return The struct containing formatting information.
    FormatMultiLine& GetFormatMultiLine()      { return varFormatMultiLine.Get<FormatMultiLine>(); }
 
    /// Provides access to the value of the internal configuration variable #".varFormatOther".<br>
    /// This variable is declared only after the logger was added to a #"%Lox".
    /// @return The struct containing formatting information.
    FormatOther&     GetFormatOther()                  { return varFormatOther.Get<FormatOther>(); }
 
    /// Provides access to the value of the internal configuration variable #".varFormatAutoSizes".<br>
    /// This variable is declared only after the logger was added to a #"%Lox".
    /// @return The struct containing the #"util::AutoSizes" instances for the
    ///        meta-information of the log message and for the log message itself.
    FormatAutoSizes& GetAutoSizes()            { return varFormatAutoSizes.Get<FormatAutoSizes>(); }
 
    /// Provides access to the value of the internal configuration variable #".varReplacements".<br>
    /// This variable is declared only after the logger was added to a #"%Lox".
    /// @return The #"textlogger::Replacements" instance for the logger in question.
    Replacements&    GetReplacements()               { return varReplacements.Get<Replacements>(); }
 
 
  //################################################################################################
  // protected Constructor/ public destructor
  //################################################################################################
  protected:
    /// Constructs a TextLogger.
    /// @param pName            The name of the \e Logger.
    /// @param typeName         The type of the \e Logger.
    ALIB_DLL explicit TextLogger( const NString& pName, const NString& typeName );
 
  //################################################################################################
  // protected methods
  //################################################################################################
    /// Parses the format string in the field #".varFormatMetaInfo" and logs meta-information into
    /// the log buffer.
    /// For each variable found, the 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.
    /// @param buffer    The buffer to write meta-information into.
    /// @param domain    The <em>Log Domain</em>.
    /// @param verbosity The verbosity.
    /// @param scope     Information about the scope of the <em>Log Statement</em>..
    ALIB_DLL
    virtual void writeMetaInfo( AString&           buffer,
                                detail::Domain&    domain,
                                Verbosity          verbosity,
                                detail::ScopeInfo& scope     );
 
    /// 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.
    ///
    /// @param domainPath   The <em>Log Domain</em> full path.
    /// @param 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.
    /// @param scope        Information about the scope of the <em>Log Statement</em>..
    /// @param dest         The buffer to write meta-information into.
    /// @param variable     The variable to read (may have more characters appended)
    ALIB_DLL
    virtual void processVariable( const NString&     domainPath,
                                  Verbosity          verbosity,
                                  detail::ScopeInfo& scope,
                                  AString&           dest,
                                  Substring&         variable      );
 
    /// Helper function that logs a time given difference into the given buffer in a human-readable
    /// format. Works from nanoseconds seconds to days.
    ///
    /// @param buffer       The buffer to write the time difference representation into.
    /// @param diffNanos    The time difference to write in nanoseconds.
    ALIB_DLL
    virtual void writeTimeDiff  ( AString& buffer, int64_t diffNanos );
 
 
  public:
    /// Destructs a TextLogger.
    ALIB_DLL virtual ~TextLogger()                                                         override;
 
  //################################################################################################
  // Overriding parent's virtual, empty method AcknowledgeLox()
  //################################################################################################
 
    /// Configuration variables are read within this method and created with
    /// default values, in the case they do not exist, yet. The variables read are:
    /// - \b alxcvALOX_LOGGERNAME_AUTO_SIZES
    /// - \b alxcvALOX_LOGGERNAME_FORMAT
    /// - \b alxcvALOX_LOGGERNAME_FORMAT_DATE_TIME
    /// - \b alxcvALOX_LOGGERNAME_FORMAT_TIME_DIFF
    /// - \b alxcvALOX_LOGGERNAME_FORMAT_MULTILINE
    /// - \b alxcvALOX_LOGGERNAME_FORMAT_OTHER
    /// - \b alxcvALOX_LOGGERNAME_REPLACEMENTS
    ///
    /// Configuration variables are #"alib_alox_cfgvars;documented here".
    ///
    /// @param lox     The #"%Lox" to acknowledge insertion or removal
    /// @param op      The operation. Either #"%ContainerOp::Insert" or #"%ContainerOp::Remove".
    ALIB_DLL
    virtual void AcknowledgeLox( detail::LoxImpl* lox, lang::ContainerOp op )              override;
 
 
  //################################################################################################
  // Abstract methods introduced
  //################################################################################################
  protected:
    /// 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 #"%Logger::Log;2". This class TextLogger is
    /// responsible for generating meta-information, doing text replacements, handling multi-line
    /// messages, etc. and provides the textual representation of the whole log contents
    /// to descendants using this method.
    ///
    /// @param domain      The <em>Log Domain</em>.
    /// @param 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.
    /// @param msg         The log message.
    /// @param scope       Information about the scope of the <em>Log Statement</em>.
    /// @param lineNumber  The line number of a multi-line message, starting with 0.
    ///                    For single line messages this is -1.
    /// @param isRecursion If \c true, a recursive logging operation was detected. A logger might
    ///                    use this information, for example, to prevent recursive acquisitions
    ///                    of resources.
    virtual void logText(  detail::Domain&     domain,
                           Verbosity           verbosity,
                           AString&            msg,
                           detail::ScopeInfo&  scope,
                           int                 lineNumber,
                           bool                isRecursion )                                     =0;
 
    /// 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.<br>
    /// This is useful if the writing of text includes the acquisition of system resources
    /// (e.g., opening a file).
    ///
    /// @param phase  Indicates the beginning or end of a multi-line operation.
    virtual void notifyMultiLineOp( lang::Phase phase )                                          =0;
 
  //################################################################################################
  // Abstract method implementations
  //################################################################################################
  public:
    /// This is the implementation of the abstract method inherited from class Logger
    /// that executes a log.<br>
    /// 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.
    ///
    /// @param domain    The <em>Log Domain</em>.
    /// @param verbosity The verbosity.
    /// @param logables  The list of objects to log.
    /// @param scope     Information about the scope of the <em>Log Statement</em>..
    ALIB_DLL
    virtual void Log( detail::Domain& domain, Verbosity verbosity, BoxesMA& logables,
                      detail::ScopeInfo& scope)                                            override;
 
  //################################################################################################
  // Public interface
  //################################################################################################
  public:
    /// Adds the given pair of replacement strings. If searched string already exists, the
    /// current replacement string gets replaced. If the replacement string is \c nullptr,
    /// nothing is set and a previously set replacement definition becomes unset.
    /// @param searched    The string to be searched.
    /// @param replacement The replacement string. If this equals 'nullptr' a previously set
    ///                    replacement will be unset.
    ALIB_DLL
    virtual void  SetReplacement( const String& searched, const String& replacement );
 
    /// Removes all pairs of searched strings and their replacement value.
    ALIB_DLL
    virtual void  ClearReplacements();
 
    /// Resets automatically widened tab stops and field widths of this logger by calling
    /// #"StandardConverter;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" accessible through the field
    ///       #".varFormatAutoSizes".
    ALIB_DLL
    virtual void    ResetAutoSizes();
}; // class TextLogger
 
}} // namespace alib[::lox::textlogger]
 
/// Type alias in namespace #"%alib".
using     TextLogger=       lox::textlogger::TextLogger;
 
}  // namespace [alib]