ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
alox_init.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of the \aliblong.
4/// With supporting legacy or module builds, .mpp-files are either recognized by the build-system
5/// as C++20 Module interface files, or are included by the
6/// \ref alib_manual_modules_impludes "import/include headers".
7///
8/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
9/// Published under \ref mainpage_license "Boost Software License".
10//==================================================================================================
11ALIB_EXPORT namespace alib { namespace lox {
12
13//==================================================================================================
14/// This enum is used in \alox to control the "verbosity" or "verboseness" of the log output.
15/// The values herein - apart from special value 'Off' - are sorted in the following order
16/// - Verbose (highest level)
17/// - Info
18/// - Warning
19/// - Error (lowest level).
20///
21/// A value of this set is provided to \alox in two different ways:
22/// First, all methods of class \ref alib::lox::Lox "Lox" that execute a log operation
23/// assign a value of this enum to the <em>Log Statement</em>. Secondly, methods
24/// \ref alib::lox::Lox::SetVerbosity "Lox::SetVerbosity", are defining the 'accepted'
25/// <em>minimal Verbosity</em> for a pair of <em><Logger/%Log Domain></em>.
26///
27/// \alox, when executing a statement, checks both values against each other.
28/// A <em>Log Statement</em> is executed, when the <em><Logger/%Log Domain></em> setting is set
29/// to the same or a 'higher level'. For example if a <em><Logger/%Log Domain></em> setting is
30/// \b %Warning, then <em>Log Statements</em> with associated \e %Verbosity \b %Warning and
31/// \b %Error are executed and those with \b %Info and \b %Verbose are suppressed.
32///
33/// If special value \b %Off is used with \alib{lox;Lox::SetVerbosity}, all logging is switched off
34/// for this pair of <em><Logger/%Log Domain></em>.
35///
36/// Some of the <em>Log Statements</em> accept the parameter directly (e.g.
37/// \ref alib::lox::Lox::Entry "Lox::Entry",
38/// \ref alib::lox::Lox::Once "Lox::Once" and
39/// \ref alib::lox::Lox::If "Lox::If"), others inherently use the right value as their method
40/// name suggests (e.g.
41/// \ref alib::lox::Lox::Error "Lox::Error",
42/// \ref alib::lox::Lox::Warning "Lox::Warning",
43/// \ref alib::lox::Lox::Info "Lox::Info",
44/// \ref alib::lox::Lox::Verbose "Lox::Verbose" and
45/// \ref alib::lox::Lox::Assert "Lox::Assert"). The latter group of methods do not support
46/// parameter \b %Off.
47///
48/// If special value \b %Off is used with those <em>Log Statements</em>, that allow to specify the
49/// \e %Verbosity as a parameter, the <em>Log Statement</em> is never executed This is useful if the
50/// parameter is determined at run-time, depending on the state of an application.
51//==================================================================================================
52enum class Verbosity : uint8_t
53{
54 /// The 'highest' level of \e %Verbosity.
55 /// Statements with this value associated are logged only if a <em>%Log Domain</em> is set to
56 /// \b %Verbose as well.
58
59 /// The standard \e Verbosity for normal log output statements.
60 /// Logged if a <em>%Log Domain</em> is set to \b %Info or \b %Verbose.
62
63 /// A \e Verbosity for warning messages, hence things that might lead to errors or are not
64 /// welcome for other reasons, but maybe are not errors.<br>
65 /// Logged if a <em>%Log Domain</em> is set to \b %Warning, \b %Info or \b %Verbose.
67
68 /// A \e Verbosity for error messages.
69 /// It is suppressed only if a <em>%Log Domain</em>'s setting is \b %Off.
71
72 /// Statements with this value associated are never logged (useful if \e %Verbosity is
73 /// evaluated at run-time). <em>%Log Domains</em> with this setting do not execute any
74 /// <em>Log Statement</em>.
76};
77
78
79//==================================================================================================
80/// These are definitions that are used as a parameter to certain \alox methods to denote
81/// the \e Scope of a setting. \e Scopes are dependent of the programming language
82/// and hence differ slightly from each other in the different versions of \alox.
83///
84/// This enumeration is an \alib{enumops;ArithmeticalTraits;ALib arithmetical enum}. However,
85/// the addition of values is only allowed with the last element, \b Path. By adding integer
86/// values, the Nth parent directory of a source file's location are addressed. As an example,
87/// invocations like this are used to select the source directory two levels above the source
88/// code file for a prefix scope:
89///
90/// lox->SetPrefix( "#> ", Scope::Path + 2 );
91///
92/// \note
93/// \alox for C++ implements scope mechanisms using scope information generated by the
94/// preprocessor.
95/// By default, debug logging supports such 'caller information', while release logging
96/// does not.<br>
97/// Therefore, in release-logging, the use of \e Scopes 'Path', 'Filename' and
98/// 'Method' will just default to an empty scope and therefore the all reflect the same,
99/// shared scope, which is not very helpful. Therefore, for standard release logging,
100/// the use of the scope mechanisms should be be avoided, unless scope information is
101/// explicitly enabled.<br>
102/// For more information on how to change the defaults, see documentation of preprocessor
103/// symbols \ref ALOX_DBG_LOG_CI and \ref ALOX_REL_LOG_CI.
104///
105/// For more information on \e Scopes consult the \ref alib_mod_alox.
106//==================================================================================================
107enum class Scope
108{
109 /// Denotes the global (singleton) scope.
111
112 /// Denotes the actual thread as the scope. When used with <em>Scope Domains</em>,
113 /// 'inner' scopes can be defined optionally by multiple definitions.
115
116 /// Denotes the actual source file as the scope.
118
119 /// Denotes the actual method as the scope.
121
122 /// Denotes the actual thread as the scope. When used with <em>Scope Domains</em>,
123 /// 'inner' scopes can be defined optionally by multiple definitions.
125
126 /// Denotes the actual source path as the scope. By adding positive integral values
127 /// to this element (the enum type is an \alib{enumops;ArithmeticalTraits;ALib arithmetical enum}),
128 /// 'outer' \e Scopes of this scope level itself can be defined using parent directories
129 /// of the path.
131};
132
133//==================================================================================================
134/// This class defines "escape sequences" that influence the formatting of log output.
135/// Specific implementations of class
136/// \ref alib::lox::detail::Logger "Logger"
137/// have to convert or interpret this classes definitions of escape sequences
138/// when processing log data. If no formatting of the output is supported by a specific Logger
139/// implementation, such logger should filter and discard escape sequences defined here.
140///
141/// The sequences are similar to ANSI Escape sequences and logger classes that
142/// log to 'VT100' compatible terminals will simply convert them.
143///
144/// The name of the class was intentionally chosen to be short, because the escape codes
145/// defined with this class will be concatenated to log strings like that:
146///
147/// \snippet "ut_alox_dox.cpp" DOX_ALOX_ESC
148///
149/// \note
150/// With the introduction of own, \alox specific escape codes, software that uses ALox becomes
151/// independent of any underlying, platform-specific sequences. For example, \alox is not relying
152/// on ANSI color codes, which are not supported by colorful Windows consoles. Instead, on each
153/// platform, dedicated Loggers will perform the translation of \alox codes to platform-specific
154/// ones.
155//==================================================================================================
156class ESC
157{
158 public:
159 static constexpr character RED [4]{ A_CHAR("\033c0") }; ///< Select red color for foreground.
160 static constexpr character GREEN [4]{ A_CHAR("\033c1") }; ///< Select green color for foreground.
161 static constexpr character YELLOW [4]{ A_CHAR("\033c2") }; ///< Select yellow color for foreground.
162 static constexpr character BLUE [4]{ A_CHAR("\033c3") }; ///< Select blue color for foreground.
163 static constexpr character MAGENTA [4]{ A_CHAR("\033c4") }; ///< Select magenta color for foreground.
164 static constexpr character CYAN [4]{ A_CHAR("\033c5") }; ///< Select cyan color for foreground.
165 static constexpr character BLACK [4]{ A_CHAR("\033c6") }; ///< Select black color for foreground.
166 static constexpr character WHITE [4]{ A_CHAR("\033c7") }; ///< Select white color for foreground.
167 static constexpr character GRAY [4]{ A_CHAR("\033c8") }; ///< Select gray color for foreground.
168 static constexpr character FG_RESET [4]{ A_CHAR("\033c9") }; ///< Select std color for foreground.
169
170 static constexpr character BG_RED [4]{ A_CHAR("\033C0") }; ///< Select red color for background.
171 static constexpr character BG_GREEN [4]{ A_CHAR("\033C1") }; ///< Select green color for background.
172 static constexpr character BG_YELLOW [4]{ A_CHAR("\033C2") }; ///< Select yellow color for background.
173 static constexpr character BG_BLUE [4]{ A_CHAR("\033C3") }; ///< Select blue color for background.
174 static constexpr character BG_MAGENTA [4]{ A_CHAR("\033C4") }; ///< Select blue color for background.
175 static constexpr character BG_CYAN [4]{ A_CHAR("\033C5") }; ///< Select blue color for background.
176 static constexpr character BG_BLACK [4]{ A_CHAR("\033C6") }; ///< Select red color for background.
177 static constexpr character BG_WHITE [4]{ A_CHAR("\033C7") }; ///< Select blue color for background.
178 static constexpr character BG_GRAY [4]{ A_CHAR("\033C8") }; ///< Select gray color for background.
179 static constexpr character BG_RESET [4]{ A_CHAR("\033C9") }; ///< Select std color for background.
180
181 static constexpr character BOLD [4]{ A_CHAR("\033sB") }; ///< Select bold font style.
182 static constexpr character ITALICS [4]{ A_CHAR("\033sI") }; ///< Select italics font style.
183 static constexpr character STYLE_RESET[4]{ A_CHAR("\033sr") }; ///< Select standard font style.
184 static constexpr character RESET [4]{ A_CHAR("\033sa") }; ///< Reset color and style.
185
186 static constexpr character URL_START [4]{ A_CHAR("\033lS") }; ///< Mark the start of an URL.
187 static constexpr character URL_END [4]{ A_CHAR("\033lE") }; ///< Mark the end of an URL.
188 static constexpr character TAB [4]{ A_CHAR("\033t0") }; ///< Go to next tab. Usually, text loggers will increase the tab position automatically.
189
190 static constexpr character EOMETA [4]{ A_CHAR("\033A0") }; ///< End of meta-information in log string
191
192 //==============================================================================================
193 /// Replaces ESC codes in a string reversely to "ESC::XXX".
194 /// @param target The string to replace in.
195 /// @param startIdx The index to start searching for ESC codes.
196 //==============================================================================================
198 static void ReplaceToReadable( AString& target, integer startIdx );
199}; // class ESC
200
201
202/// Denotes flags used with methods \alib{lox;Lox::GetState} and \alib{lox;Lox::State} to select
203/// different parts of the state receive.
204enum class StateInfo
205{
206 NONE = 0, ///< No state
207 Basic = 1 << 0, ///< Name and number of log calls
208 Version = 1 << 1, ///< Library Version and thread safeness
209 Loggers = 1 << 2, ///< Loggers
210
211 Domains = 1 << 3, ///< Log domains currently registered
212 InternalDomains = 1 << 4, ///< Internal domains
213 ScopeDomains = 1 << 5, ///< Scope domains
214 DSR = 1 << 6, ///< Domain substitution rules
215 PrefixLogables = 1 << 7, ///< Prefix logables
216 Once = 1 << 8, ///< Log once counters
217 LogData = 1 << 9, ///< Log data objects
218 ThreadMappings = 1 << 10, ///< Named threads
219
220 SPTR = 1 << 20, ///< Source path trim rules
221 CompilationFlags = 1 << 21, ///< \alib/\alox compilation flags
222
223 All = ~0L, ///< All flags set.
224};
225
226
227} // namespace alib[::lox]
228
229
230/// Type alias in namespace \b alib.
232
233/// Type alias in namespace \b alib.
235
236/// Type alias in namespace \b alib.
238
239} // namespace [alib]
240
241
244
245
249
250
252
253
static constexpr character BG_GRAY[4]
Select gray color for background.
static constexpr character BOLD[4]
Select bold font style.
static constexpr character BG_WHITE[4]
Select blue color for background.
static constexpr character BG_RESET[4]
Select std color for background.
static constexpr character GREEN[4]
Select green color for foreground.
static constexpr character TAB[4]
Go to next tab. Usually, text loggers will increase the tab position automatically.
static constexpr character EOMETA[4]
End of meta-information in log string.
static constexpr character BG_MAGENTA[4]
Select blue color for background.
static constexpr character URL_START[4]
Mark the start of an URL.
static constexpr character BG_BLUE[4]
Select blue color for background.
static ALIB_DLL void ReplaceToReadable(AString &target, integer startIdx)
Definition aloxinit.cpp:48
static constexpr character GRAY[4]
Select gray color for foreground.
static constexpr character STYLE_RESET[4]
Select standard font style.
static constexpr character MAGENTA[4]
Select magenta color for foreground.
static constexpr character ITALICS[4]
Select italics font style.
static constexpr character CYAN[4]
Select cyan color for foreground.
static constexpr character FG_RESET[4]
Select std color for foreground.
static constexpr character BG_RED[4]
Select red color for background.
static constexpr character BG_BLACK[4]
Select red color for background.
static constexpr character URL_END[4]
Mark the end of an URL.
static constexpr character RESET[4]
Reset color and style.
static constexpr character BG_YELLOW[4]
Select yellow color for background.
static constexpr character BLACK[4]
Select black color for foreground.
static constexpr character BG_GREEN[4]
Select green color for background.
static constexpr character BG_CYAN[4]
Select blue color for background.
static constexpr character YELLOW[4]
Select yellow color for foreground.
static constexpr character WHITE[4]
Select white color for foreground.
static constexpr character RED[4]
Select red color for foreground.
static constexpr character BLUE[4]
Select blue color for foreground.
#define ALIB_DLL
Definition alib.inl:496
#define A_CHAR(STR)
#define ALIB_ENUMS_ASSIGN_RECORD(TEnum, TRecord)
#define ALIB_BOXING_VTABLE_DECLARE(TMapped, Identifier)
#define ALIB_ENUMS_MAKE_ARITHMETICAL(TEnum)
#define ALIB_EXPORT
Definition alib.inl:488
@ Filename
Denotes the actual source file as the scope.
@ Method
Denotes the actual method as the scope.
@ Global
Denotes the global (singleton) scope.
@ ScopeDomains
Scope domains.
@ CompilationFlags
ALib/ALox compilation flags
@ DSR
Domain substitution rules.
@ InternalDomains
Internal domains.
@ Version
Library Version and thread safeness.
@ PrefixLogables
Prefix logables.
@ Domains
Log domains currently registered.
@ LogData
Log data objects.
@ Basic
Name and number of log calls.
@ All
All flags set.
@ SPTR
Source path trim rules.
@ Once
Log once counters.
@ ThreadMappings
Named threads.
strings::TAString< character, lang::HeapAllocator > AString
Type alias in namespace alib.
lox::Scope Scope
Type alias in namespace alib.
lang::integer integer
Type alias in namespace alib.
Definition integers.inl:149
lox::ESC ESC
Type alias in namespace alib.
lox::Verbosity Verbosity
Type alias in namespace alib.
characters::character character
Type alias in namespace alib.