textfilelogger.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 { namespace loggers {
 
//==================================================================================================
/// This is a very simple file logger for textual log outputs. The file name string provided
/// in the constructor is not verified.
/// The fileName may be changed by simply setting the public member #".FileName".
///
/// In alignment with \alox principles (\alox does not throw!), the logger does not throw i/o
/// exceptions. In debug-compilations, \alib warnings are issued.
/// Recent system io/ errors are stored in public field# LastSystemError.
/// The constructor tries to open/close the file with write permissions.
/// For many applications, it should be enough to check this field after construction and
/// take according actions on failure. Otherwise, errors may periodically be checked by an
/// application (e.g., no space left on device, etc.).
//==================================================================================================
class TextFileLogger : public alib::lox::textlogger::PlainTextLogger {
  //################################################################################################
  // Internal fields
  //################################################################################################
  protected:
    /// Allocator used for the #"std::OStreamWriter".
    MonoAllocator       ma;
 
    /// The #"%OStreamWriter" encapsulated in a placeholder. The instance is constructed
    /// and destructed with #"notifyPlainTextLogOp". With that, synchronized output is
    /// guaranteed.
    lang::Placeholder<OStreamWriter<nchar, MonoAllocator, true>>  writer;
 
    /// Encapsulates the text file stream in a system-dependent way.
    std::ofstream*          ofs                                                            =nullptr;
 
    /// Flag to prevent file open/close operations when multi-line text logging is performed.
    bool                    currentlyInMultiLineOp                                           =false;
 
 
  //################################################################################################
  // Public fields
  //################################################################################################
  public:
    /// The path and fileName to the log file.
    alib::AString          FileName;
 
    /// Errors that usually indicate i/o problems. With construction of the logger,
    /// the file is tried to be opened and closed, which might indicate major problems
    /// (permissions, path, etc) with this public field very early.
    std::errc              LastSystemError                                            =std::errc(0);
 
 
  //################################################################################################
  // Constructor/destructor
  //################################################################################################
  public:
    /// Creates a TextFileLogger.
    /// @param fileName    The filename (potentially including a path) of the output log file.
    /// @param loggerName  The name of the \e Logger. Defaults to "TEXTFILE".
    ALIB_DLL
    explicit            TextFileLogger( const alib::String& fileName,
                                        const alib::NString& loggerName    =nullptr );
 
    /// Destructs a TextFileLogger
    virtual            ~TextFileLogger()                                                 override {}
 
  //################################################################################################
  // Protected methods
  //################################################################################################
  protected:
    /// Opens the file.
    ALIB_DLL
    void                openFile();
 
    /// Closes the file.
    ALIB_DLL
    void                closeFile();
 
  //################################################################################################
  // Abstract method implementations
  //################################################################################################
  protected:
    /// Starts/ends log line. Appends a new-line character sequence to previously logged lines.
    ///
    /// @param phase  Indicates the beginning or end of a log line.
    /// @return Always returns true.
    ALIB_DLL
    virtual bool        notifyPlainTextLogOp( lang::Phase phase )                          override;
 
    /// Writes the given region of the given string to the console.
    ///
    /// @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.
    ALIB_DLL
    virtual integer     logPlainTextPart( const String& buffer,
                                          integer       start,    integer length )         override;
 
 
    /// Empty implementation, not needed for this class
    /// @param phase  Indicates the beginning or end of a multi-line operation.
    ALIB_DLL
    virtual void        notifyMultiLineOp ( lang::Phase phase )                            override;
 
}; // class TextFileLogger
 
 
}} // namespace alib[::lox::loggers]
 
/// Type alias in namespace #"%alib".
using     TextFileLogger=           lox::loggers::TextFileLogger;
 
} // namespace [alib]