plaintextlogger.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::lox::textlogger {
 
//==================================================================================================
/// A text logger that either removes or ignores (just writes through) \alox ESC sequences.
/// Implements abstract method #"logText" and introduces two new abstract methods
/// #"logPlainTextPart" and #"notifyPlainTextLogOp".
//==================================================================================================
class PlainTextLogger : public TextLogger {
  //################################################################################################
  // public fields
  //################################################################################################
  public:
    /// If this field is set to \c true (the default), all #"alib::lox::ESC;ESC" color and
    /// style codes get removed when logging into this Logger. \c ESC::TAB is processed.
    ///
    /// It might be useful to set this to false, e.g., in the case, the contents of the
    /// Logger are (later) written into a different logger (e.g., as a multi-line message)
    /// which is capable of interpreting the escape sequences of class ESC.
    bool                        PruneESCSequences                                             =true;
 
  //################################################################################################
  // Constructor/destructor
  //################################################################################################
  protected:
    /// Creates a PlainTextLogger
    /// @param name            The name of the \e Logger. If empty, it defaults to the type name.
    /// @param typeName        The type of the \e Logger.
    explicit  PlainTextLogger( const NString& name, const NString& typeName)
              : TextLogger( name, typeName )                                                      {}
 
    /// Destructs a MemoryLogger
    virtual  ~PlainTextLogger()                                                          override {}
 
  //################################################################################################
  // Abstract methods introduced
  //################################################################################################
  protected:
    /// Abstract method to be implemented by descendants. This method is called when a new
    /// log message is started. It is called exactly once before a series of #"logPlainTextPart"
    /// calls and exactly once after such series. If either the start or one of the calls
    /// to #".logPlainTextPart" returns a negative number, the second invocation that would
    /// indicate the end of a log message is omitted.
    ///
    /// Implementing this method allows the acquisition of system resources
    /// (e.g., opening a file).
    ///
    /// @param phase  Indicates the beginning or end of a log line.
    /// @return If \c false is returned, the log line is aborted without an invocation of
    ///         #"notifyPlainTextLogOp;notifyPlainTextLogOp(Phase::End)".
    virtual bool    notifyPlainTextLogOp( lang::Phase phase )                                    =0;
 
    /// Abstract method to be implemented by descendants. Has to write the given region of
    /// the given string to the destination.
    /// Has to return the number of characters written, which might be different from the
    /// region length requested, e.g., in case of character set conversions.
    ///
    /// If an error occurs, \c -1 can be returned to indicate that the current log should be
    /// aborted. In this case, no invocation of
    /// #"notifyPlainTextLogOp;notifyPlainTextLogOp(Phase::End)" will be performed.
    ///
    /// @param buffer   The string to write a portion of.
    /// @param start    The start of the portion in \p{buffer} to write out.
    /// @param length   The length of the portion in \p{buffer} to write out.
    /// @return The number of characters written, -1 on error.
    virtual integer logPlainTextPart( const String& buffer, integer start, integer length )      =0;
 
 
  //################################################################################################
  // Abstract method implementations
  //################################################################################################
  protected:
    /// The implementation of the abstract method of parent class TextLogger.
    /// Loops over the log text, removes or ignores ESC sequences (all but ESC.TAB) and invokes
    /// abstract methods of descendants as follows:
    /// - #"notifyPlainTextLogOp;notifyPlainTextLogOp(true)"
    /// -   #".logPlainTextPart"
    /// -   ...
    /// - #"notifyPlainTextLogOp;notifyPlainTextLogOp(Phase::End)"
    ///
    /// @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.
    ALIB_DLL
    virtual void    logText( detail::Domain&     domain,
                             Verbosity           verbosity,
                             AString&            msg,
                             detail::ScopeInfo&  scope,
                             int                 lineNumber,
                             bool                isRecursion    )                          override;
}; // class PlainTextLogger
 
} // namespace [alib::lox::textlogger]