log.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 {
 
// forward declarations
class Lox;
#if !ALIB_C20_MODULES
namespace detail        { class Logger;    }
namespace textlogger    { class TextLogger; }
#endif
 
// The debug lox singleton
#if ALOX_DBG_LOG
    /// The debug-lox instance. This object will be created in method
    /// #"ALoxCamp::Bootstrap;*" and deleted with #"ALoxCamp::Shutdown;*".
    extern ALIB_DLL Lox*     DEBUG_LOX;
#endif
#if ALIB_DEBUG
    /// The domain-prefix used with plug-in function #"ALoxAssertionPlugin".
    /// The given assertion domain will be appended to this name, separated by the domain
    /// separation character <c>'/'</c>.<br>
    /// Defaults to <c>"ALIB"</c>.
    ALIB_DLL extern std::string_view  const ALOX_ASSERTION_PLUGIN_DOMAIN_PREFIX;
#endif
 
//==================================================================================================
/// Holds static objects used for standard debug logging and provides an interface to
/// create such objects. If the configuration macro #"ALOX_DBG_LOG" is set to \c 0, this class will be empty.
//==================================================================================================
class Log {
  public:
  #if ALOX_DBG_LOG
    /// The debug logger created by AddDebugLogger.
    ALIB_DLL static textlogger::TextLogger*   DEBUG_LOGGER;
 
    /// An (additional) IDE specific logger, that might be created by AddDebugLogger.
    ALIB_DLL static textlogger::TextLogger*   IDE_LOGGER;
 
    /// Returns the default singleton of class #"%Lox" used for debug logging.
    /// @return The debug-logging Lox of \alox
    static Lox*     Get()                                                      { return DEBUG_LOX; }
 
    /// This method creates an adequate/default debug logger.
    /// It is used by macro #"Log_AddDebugLogger" also automatically invoked
    /// when debug logging is used without the explicit creation and registration of
    /// any other logger.
    ///
    /// Of course, alternatively to using this method (resp. the macro), a suitable (set of)
    /// debug logger(s) can be created manually. Also, before or after using this method
    /// additional debug loggers may be created.
    ///
    /// In the current version of \alox (future changes are likely), this method does:
    /// - use
    ///   #"alib::lox::Lox::CreateConsoleLogger;Lox::CreateConsoleLogger"
    ///   to create the best compatible console logger for the
    ///   running platform
    /// - this logger will be added to the debug Lox object with specifying
    ///   \c Verbosity::Error for internal domains.
    /// - If under windows, a Visual Studio debug session is running, adds a
    ///   #"alib::lox::loggers::VStudioLogger;VStudioLogger"
    ///   in addition to the standard console logger. This can be suppressed using
    ///   configuration variable #"alxcvALOX_NO_IDE_LOGGER".
    ///
    /// The name of the \e Logger created is \c "DEBUG_LOGGER". It will be registered with
    /// the standard #"%Lox" used for debug-logging, by setting \e Verbosities
    /// - Verbosity::Verbose for the root domain <c> '/'</c> and
    /// - Verbosity::Warning for internal domains.
    ///
    /// An optionally created second, IDE-specific \e Logger will be named \c "IDE_LOGGER"
    /// and will be registered with the standard #"%Lox" used for debug-logging with the same
    /// \e Verbosities as \c "DEBUG_LOGGER" is.
    ///
    /// Finally, this method also invokes #"SetALibAssertionPlugin".
    ///
    /// @param lox  The lox to add the debug logger(s) to.
    ALIB_DLL static void      AddDebugLogger( Lox* lox );
 
    /// Removes the \e Logger(s) and which was (were) created by #"AddDebugLogger".
    /// This method also invokes #"SetALibAssertionPlugin", passing \c nullptr to unregister
    /// the plug-in.
    /// @param lox The lox to remove the debug logger(s) from.
    ALIB_DLL static void      RemoveDebugLogger( Lox* lox );
 
    #if ALIB_DEBUG
    /// Sets the global pointer #"assert::PLUGIN" to function
    /// #"ALoxAssertionPlugin" which then redirects the output of
    /// #"alib::assert::Raise;ALib assertions" to the given #"Lox".
    ///
    /// \note
    ///   This method is effective only with debug-builds. Usually it is invoked indirectly by
    ///   using the method #"AddDebugLogger".
    ///   Applications that do not use that method (e.g., because they are using release
    ///   logging exclusively) should invoke this method on bootstrap providing their
    ///   (release) lox.
    ///   In this case, the \e Verbosity of the internal domain used by function
    ///   #"ALoxAssertionPlugin" has to be set for the logger(s) in the given
    ///   \p{lox} in question.
    ///
    /// @param lox  The lox that the #"ALoxAssertionPlugin" will be using.
    ///             If \c nullptr is given, the plug-in will be removed.
    ALIB_DLL static void      SetALibAssertionPlugin( Lox* lox );
    #else
                 static void      SetALibAssertionPlugin( Lox*     )                              {}
    #endif
 
  #endif // ALOX_DBG_LOG
}; // class Log
 
} // namespace alib[::lox]
 
/// Type alias in namespace #"%alib".
using     Log=           lox::Log;
 
}  // namespace [alib]