alox_init.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 {
 
//==================================================================================================
/// 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 #"alib::lox::Lox;Lox" that execute a log operation
/// assign a value of this enum to the <em>Log Statement</em>. Secondly, the overloaded methods
/// #"Lox::SetVerbosity(detail::Logger*)", 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  #"Verbosity::Warning;2" and
/// #"Verbosity::Error" are executed and those with #"Verbosity::Info" and #"VerbosityVerbose" are
/// suppressed.
///
/// If the special value #"%Verbosity::Off" is used with
/// #"Lox::SetVerbosity(detail::Logger*);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. #"Lox::Entry",
/// #"Lox::Once(const NString&, Verbosity, const Box&, const String&, Scope, int);Lox::Once", and
/// #"Lox::If(bool, const NString&, Verbosity, BoxedObjects&& ...);Lox::If"), while others
/// inherently use the right value as their method name suggests (e.g.
/// #"Lox::Error",
/// #"Lox::Warning",
/// #"Lox::Info",
/// #"Lox::Verbose" and
/// #"Lox::Assert").
/// The latter group of methods do not support verbosity value #"%Verbosity::Off".
///
/// If the special value #"%Verbosity::Off" is used with those <em>Log Statements</em> that allow
/// specifying the \e Verbosity as a parameter, the <em>Log Statement</em> is never executed.
/// This is useful if the parameter is determined at runtime, depending on the state of an
/// application.
//==================================================================================================
enum class Verbosity : uint8_t {
    /// Statements with this value associated are never logged (useful if \e Verbosity is
    /// evaluated at runtime). <em>Log Domains</em> with this setting do not execute any
    /// <em>Log Statement</em>.
    Off,
 
    /// A \e Verbosity for error messages.
    /// It is suppressed only if a <em>Log Domain</em>'s setting is #"%Verbosity::Off".
    Error,
 
    /// 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 #"%Verbosity::Warning", #"%Verbosity::Info" or
    /// #"%Verbosity::Verbose".
    Warning,
 
    /// The standard \e Verbosity for normal log output statements.
    /// Logged if a <em>Log Domain</em> is set to #"%Verbosity::Info" or #"%Verbosity::Verbose".
    Info,
 
    /// The 'highest' level of \e Verbosity.
    /// Statements with this value associated are logged only if a <em>Log Domain</em> is set to
    /// #"%Verbosity::Verbose" as well.
    Verbose,
};
 
 
//==================================================================================================
/// 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 #"ArithmeticalTraits;ALib arithmetical enum". However,
/// the addition of values is only allowed with the last element, #"%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 avoided, unless scope information is
///   explicitly enabled.<br>
///   For more information on how to change the defaults, see documentation of preprocessor
///   configuration macros #"ALOX_DBG_LOG_CI" and #"ALOX_REL_LOG_CI".
///
///   For more information on \e Scopes consult the #"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 #"ArithmeticalTraits;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
/// #"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_DLL
    static void ReplaceToReadable( AString& target, integer startIdx );
}; // class ESC
 
 
/// Denotes flags used with methods #"Lox::GetState;*" and #"Lox::State;*" to select
/// different parts of the state receive.
enum class StateInfo {
    NONE                     = 0,       ///< No state
    Basic                    = 1 <<  0, ///< Name and number of log calls
    Version                  = 1 <<  1, ///< Library Version and thread safeness
    Loggers                  = 1 <<  2, ///< Loggers
 
    Domains                  = 1 <<  3, ///< Log domains currently registered
    InternalDomains          = 1 <<  4, ///< Internal domains
    ScopeDomains             = 1 <<  5, ///< Scope domains
    DSR                      = 1 <<  6, ///< Domain substitution rules
    PrefixLogables           = 1 <<  7, ///< Prefix logables
    Once                     = 1 <<  8, ///< Log once counters
    LogData                  = 1 <<  9, ///< Log data objects
    ThreadMappings           = 1 << 10, ///< Named threads
 
    SPTR                     = 1 << 20, ///< Source path trim rules
    CompilationFlags         = 1 << 21, ///< \alib/\alox compilation flags
 
    All                      =     ~0L, ///< All flags set.
};
 
 
} // namespace alib[::lox]
 
 
/// Type alias in namespace #"%alib".
using   Verbosity=        lox::Verbosity;
 
/// Type alias in namespace #"%alib".
using   Scope=            lox::Scope;
 
/// Type alias in namespace #"%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_ENUMS_ASSIGN_RECORD( alib::lox::Verbosity, alib::enumrecords::ERSerializable )
ALIB_ENUMS_ASSIGN_RECORD( alib::lox::Scope    , alib::enumrecords::ERSerializable )
ALIB_ENUMS_MAKE_ARITHMETICAL( alib::lox::Scope     )
 
 
ALIB_ENUMS_ASSIGN_RECORD( alib::lox::StateInfo, alib::enumrecords::ERSerializable )