textfilelogger.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_alox of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software 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:
 
        /// Encapsulates the text file stream in a system dependent way.
        StringWriter            writer;
 
        /// 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.
        SystemErrors           LastSystemError                                 = SystemErrors::None;
 
 
    // #############################################################################################
    // 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        notifyLogOp( 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     logSubstring( 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 \b alib.
using     TextFileLogger=           lox::loggers::TextFileLogger;
 
} // namespace [alib]