alox/alox.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header file is part of module \alib_alox of the \aliblong.
///
/// \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#ifndef HPP_ALIB_ALOX
#define HPP_ALIB_ALOX 1
#pragma once
#if !defined(DOXYGEN)
#   include "alib/alib.hpp"
#endif
 
ALIB_ASSERT_MODULE(ALOX)
 
#include "alib/config/priority.hpp"
 
namespace alib {  namespace lox {
 
class Lox;
 
//==================================================================================================
/// This enum is used in \alox to control the "verbosity" or "verboseness" of the log output.
/// The values herein - apart from special value 'Off' - are sorted in the following order
/// - Verbose (highest level)
/// - Info
/// - Warning
/// - Error (lowest level).
///
/// A value of this set is provided to \alox in two different ways:
/// First, all methods of class \ref alib::lox::Lox "Lox" that execute a log operation
/// assign a value of this enum to the <em>Log Statement</em>. Secondly, methods
/// \ref alib::lox::Lox::SetVerbosity "Lox::SetVerbosity", are defining the 'accepted'
/// <em>minimal Verbosity</em> for a pair of <em><Logger/%Log Domain></em>.
///
/// \alox, when executing a statement, checks both values against each other.
/// A <em>Log Statement</em> is executed, when the <em><Logger/%Log Domain></em> setting is set
/// to the same or a 'higher level'.  For example if a <em><Logger/%Log Domain></em> setting is
/// \b %Warning, then <em>Log Statements</em> with associated \e %Verbosity \b %Warning and
/// \b %Error are executed and those with \b %Info and \b %Verbose are suppressed.
///
/// If special value \b %Off is used with \alib{lox;Lox::SetVerbosity}, all logging is switched off
/// for this pair of <em><Logger/%Log Domain></em>.
///
/// Some of the <em>Log Statements</em> accept the parameter directly (e.g.
/// \ref alib::lox::Lox::Entry "Lox::Entry",
/// \ref alib::lox::Lox::Once  "Lox::Once" and
/// \ref alib::lox::Lox::If "Lox::If"), others inherently use the right value as their method
/// name suggests (e.g.
/// \ref alib::lox::Lox::Error      "Lox::Error",
/// \ref alib::lox::Lox::Warning    "Lox::Warning",
/// \ref alib::lox::Lox::Info       "Lox::Info",
/// \ref alib::lox::Lox::Verbose    "Lox::Verbose" and
/// \ref alib::lox::Lox::Assert     "Lox::Assert"). The latter group of methods do not support
/// parameter \b %Off.
///
/// If special value \b %Off is used with those <em>Log Statements</em>, that allow to specify the
/// \e %Verbosity as a parameter, the <em>Log Statement</em> is never executed This is useful if the
/// parameter is determined at run-time, depending on the state of an application.
//==================================================================================================
enum class Verbosity : uint8_t
{
    /// The 'highest' level of \e %Verbosity.
    /// Statements with this value associated are logged only if a <em>%Log Domain</em> is set to
    /// \b %Verbose as well.
    Verbose,
 
    /// The standard \e Verbosity for normal log output statements.
    /// Logged if a <em>%Log Domain</em> is set to \b %Info or \b %Verbose.
    Info,
 
    /// A \e Verbosity for warning messages, hence things that might lead to errors or are not
    /// welcome for other reasons, but maybe are not errors.<br>
    /// Logged if a <em>%Log Domain</em> is set to \b %Warning, \b %Info or \b %Verbose.
    Warning,
 
    /// A \e Verbosity for error messages.
    /// It is suppressed only if a <em>%Log Domain</em>'s setting is \b %Off.
    Error,
 
    /// Statements with this value associated are never logged (useful if \e %Verbosity is
    /// evaluated at run-time). <em>%Log Domains</em> with this setting do not execute any
    /// <em>Log Statement</em>.
    Off
};
 
 
//==================================================================================================
/// These are definitions that are used as a parameter to certain \alox methods to denote
/// the \e Scope of a setting. \e Scopes are dependent of the programming language
/// and hence differ slightly from each other in the different versions of \alox.
///
/// This enumeration is an \alib{enums;T_EnumIsArithmetical;ALib arithmetical enum}. However,
/// the addition of values is only allowed with the last element, \b Path. By adding integer
/// values, the Nth parent directory of a source file's location are addressed. As an example,
/// invocations like this are used to select the source directory two levels above the source
/// code file for a prefix scope:
///
///      lox->SetPrefix( "#> ", Scope::Path + 2 );
///
/// \note
///   \alox for C++ implements scope mechanisms using scope information generated by the
///   preprocessor.
///   By default, debug logging supports such 'caller information', while release logging
///   does not.<br>
///   Therefore, in release-logging, the use of \e Scopes 'Path', 'Filename' and
///   'Method' will just default to an empty scope and therefore the all reflect the same,
///   shared scope, which is not very helpful. Therefore, for standard release logging,
///   the use of the scope mechanisms should be be avoided, unless scope information is
///   explicitly enabled.<br>
///   For more information on how to change the defaults, see documentation of preprocessor
///   symbols \ref ALOX_DBG_LOG_CI and \ref ALOX_REL_LOG_CI.
///
///   For more information on \e Scopes consult the \ref alib_mod_alox.
//==================================================================================================
enum class Scope
{
    /// Denotes the global (singleton) scope.
    Global,
 
    /// Denotes the actual thread as the scope. When used with <em>Scope Domains</em>,
    /// 'inner' scopes can be defined optionally by multiple definitions.
    ThreadOuter,
 
    /// Denotes the actual source file as the scope.
    Filename,
 
    /// Denotes the actual method as the scope.
    Method,
 
    /// Denotes the actual thread as the scope. When used with <em>Scope Domains</em>,
    ///  'inner' scopes can be defined optionally by multiple definitions.
    ThreadInner,
 
    /// Denotes the actual source path as the scope. By adding positive integral values
    /// to this element (the enum type is an \alib{enums;T_EnumIsArithmetical;ALib arithmetical enum}),
    /// 'outer' \e Scopes of this scope level itself can be defined using parent directories
    /// of the path.
    Path
};
 
//==================================================================================================
/// This class defines "escape sequences" that influence the formatting of log output.
/// Specific implementations of class
/// \ref alib::lox::detail::Logger "Logger"
/// have to convert or interpret this classes definitions of escape sequences
/// when processing log data. If no formatting of the output is supported by a specific Logger
/// implementation, such logger should filter and discard escape sequences defined here.
///
/// The sequences are similar to ANSI Escape sequences and logger classes that
/// log to 'VT100' compatible terminals will simply convert them.
///
/// The name of the class was intentionally chosen to be short, because the escape codes
/// defined with this class will be concatenated to log strings like that:
///
/// \snippet "ut_alox_dox.cpp"     DOX_ALOX_ESC
///
/// \note
///   With the introduction of own, \alox specific escape codes, software that uses ALox becomes
///   independent of any underlying, platform-specific sequences. For example, \alox is not relying
///   on ANSI color codes, which are not supported by colorful Windows consoles. Instead, on each
///   platform, dedicated Loggers will perform the translation of \alox codes to platform-specific
///   ones.
//==================================================================================================
class ESC
{
    public:
    static constexpr    character  RED        [4]{ A_CHAR("\033c0") }; ///< Select red color for foreground.
    static constexpr    character  GREEN      [4]{ A_CHAR("\033c1") }; ///< Select green color for foreground.
    static constexpr    character  YELLOW     [4]{ A_CHAR("\033c2") }; ///< Select yellow color for foreground.
    static constexpr    character  BLUE       [4]{ A_CHAR("\033c3") }; ///< Select blue color for foreground.
    static constexpr    character  MAGENTA    [4]{ A_CHAR("\033c4") }; ///< Select magenta color for foreground.
    static constexpr    character  CYAN       [4]{ A_CHAR("\033c5") }; ///< Select cyan color for foreground.
    static constexpr    character  BLACK      [4]{ A_CHAR("\033c6") }; ///< Select black color for foreground.
    static constexpr    character  WHITE      [4]{ A_CHAR("\033c7") }; ///< Select white color for foreground.
    static constexpr    character  GRAY       [4]{ A_CHAR("\033c8") }; ///< Select gray color for foreground.
    static constexpr    character  FG_RESET   [4]{ A_CHAR("\033c9") }; ///< Select std color for foreground.
 
    static constexpr    character  BG_RED     [4]{ A_CHAR("\033C0") }; ///< Select red color for background.
    static constexpr    character  BG_GREEN   [4]{ A_CHAR("\033C1") }; ///< Select green color for background.
    static constexpr    character  BG_YELLOW  [4]{ A_CHAR("\033C2") }; ///< Select yellow color for background.
    static constexpr    character  BG_BLUE    [4]{ A_CHAR("\033C3") }; ///< Select blue color for background.
    static constexpr    character  BG_MAGENTA [4]{ A_CHAR("\033C4") }; ///< Select blue color for background.
    static constexpr    character  BG_CYAN    [4]{ A_CHAR("\033C5") }; ///< Select blue color for background.
    static constexpr    character  BG_BLACK   [4]{ A_CHAR("\033C6") }; ///< Select red color for background.
    static constexpr    character  BG_WHITE   [4]{ A_CHAR("\033C7") }; ///< Select blue color for background.
    static constexpr    character  BG_GRAY    [4]{ A_CHAR("\033C8") }; ///< Select gray color for background.
    static constexpr    character  BG_RESET   [4]{ A_CHAR("\033C9") }; ///< Select std color for background.
 
    static constexpr    character  BOLD       [4]{ A_CHAR("\033sB") }; ///< Select bold font style.
    static constexpr    character  ITALICS    [4]{ A_CHAR("\033sI") }; ///< Select italics font style.
    static constexpr    character  STYLE_RESET[4]{ A_CHAR("\033sr") }; ///< Select standard font style.
    static constexpr    character  RESET      [4]{ A_CHAR("\033sa") }; ///< Reset color and style.
 
    static constexpr    character  URL_START  [4]{ A_CHAR("\033lS") }; ///< Mark the start of an URL.
    static constexpr    character  URL_END    [4]{ A_CHAR("\033lE") }; ///< Mark the end of an URL.
    static constexpr    character  TAB        [4]{ A_CHAR("\033t0") }; ///< Go to next tab. Usually, text loggers will increase the tab position automatically.
 
    static constexpr    character  EOMETA     [4]{ A_CHAR("\033A0") }; ///< End of meta-information in log string
 
    //==============================================================================================
    /// Replaces ESC codes in a string reversely to "ESC::XXX".
    /// @param target   The string to replace in.
    /// @param startIdx The index to start searching for ESC codes.
    //==============================================================================================
    ALIB_API
    static void ReplaceToReadable( AString& target, integer startIdx );
}; // class ESC
 
} // namespace alib[::lox]
 
 
/// Type alias in namespace \b alib.
using   Verbosity=        lox::Verbosity;
 
/// Type alias in namespace \b alib.
using   Scope=            lox::Scope;
 
/// Type alias in namespace \b alib.
using   ESC=              lox::ESC;
 
} // namespace [alib]
 
 
ALIB_BOXING_VTABLE_DECLARE( alib::lox::Verbosity     , vt_lox_verbosity )
ALIB_BOXING_VTABLE_DECLARE( alib::lox::Scope         , vt_lox_scope     )
ALIB_BOXING_VTABLE_DECLARE( std::pair<alib::lox::Verbosity
                            ALIB_COMMA alib::config::Priority> , vt_lox_pair_verby_prio )
 
 
ALIB_ENUMS_ASSIGN_RECORD( alib::lox::Verbosity, alib::enums::ERSerializable )
ALIB_ENUMS_ASSIGN_RECORD( alib::lox::Scope    , alib::enums::ERSerializable )
ALIB_ENUMS_MAKE_ARITHMETICAL( alib::lox::Scope     )
 
 
 
// #################################################################################################
// include Log and Lox classes
// #################################################################################################
#include "alib/alox/macros.inl"
 
#if (ALIB_DEBUG && ALOX_DBG_LOG) || ALOX_REL_LOG
#   include "alib/alox/log.inl"
#   include "alib/alox/lox.inl"
#endif
 
#endif // HPP_ALIB_ALOX