ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
variables.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_alox of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
9
10//==================================================================================================
11/// Definition of the main log-line format string for class \alib{lox;textlogger::TextLogger}
12/// and its derivates.
13/// This struct is used to define an external \ref alib_mod_variables "configuration variable"
14/// named \ref alxcvALOX_LOGGERNAME_FORMAT.
15/// This variable can be accessed programatically
16/// with \alib{lox::textlogger;TextLogger::GetFormatMetaInfo} or by accessing the variable's value
17/// through the configuration object found in camp singleton #alib::ALOX.
18//==================================================================================================
20{
21 /// The line format specifies the (automated) log output that is prepended to each log line before
22 /// the log message itself. This format string can be changed after the creation
23 /// of a \ref TextLogger.
24 ///
25 /// The string supports replacement variables that begin with a <c>\%</c> character:
26 /// - \%SP: The full path of the source file
27 /// - \%Sp: The trimmed path of the source file
28 /// - \%SF: The caller's source file name
29 /// - \%Sf: The caller's source file name without extension
30 /// - \%SL: The line number in the source file
31 /// - \%SM: The method name
32 ///
33 /// - \%TD: The date the log call was invoked
34 /// - \%TT: Time of day the log call was invoked
35 /// - \%TC: Time elapsed since the Logger was created or its timer was reset
36 /// - \%TL: Time elapsed since the last log call
37 ///
38 /// - \%tN: Thread name
39 /// - \%tI: Thread ID
40 /// - \%V: The verbosity. This is replaced by the corresponding strings found in fields
41 /// #VerbosityError, #VerbosityWarning, #VerbosityInfo and #VerbosityVerbose.
42 /// - \%D: Log domain
43 /// - \%#: The log call counter (like a line counter, but counting multi lines as one)
44 /// - \%An: An auto-adjusted tabulator. This grows whenever it needs, but never shrinks. The
45 /// optional integer number n specifies how much extra space is added when tab is adjusted.
46 /// Setting this to a higher value avoids too many adjustments at the beginning of a log session.
47 /// - \%LG: The name of the \e Logger. This might be useful if multiple loggers write to the same
48 /// output stream (e.g., Console).
49 /// - \%LX: The name of the \e Lox.
50 /// - \%P: The name of the process / application.
51 ///
52 /// Resourced default is
53 /// \code "%Sp/%SF(%SL):%A5%SM() %A5[%TC +%TL][%tN]%V[%D]%A1(%#): " \endcode
54 ///
55 /// If debug logging as well as release logging has scope information disabled
56 /// (see \ref ALOX_DBG_LOG_CI and \ref ALOX_REL_LOG_CI), then it defaults to:
57 /// <c>"[%TC +%TL][%tN]%V[%D]%A1(%#): "</c>
58 ///
59 /// \note
60 /// The use of <c>%%TD</c> and <c>%%TT</c> may become problematic and ambiguous if the
61 /// system clock is changed during software run. Especially for long-running background
62 /// software (daemons, servers, etc.), the software that uses \alox needs to provide
63 /// a strategy of synchronizing the clock with field
64 /// \alib{lox::textlogger;TextLogger::DateConverter}.<br>
65 /// For some explanation of the problem see details of namespace #alib::time.
67
68 /// The replacement for variable \c %%V in field #Format if \e Verbosity is \c Error.
69 /// Resourced as '[ERR]'.
71
72 /// The replacement for variable \c %%V in field #Format if \e Verbosity is \c Warning.
73 /// Resourced as '[WRN]'.
75
76 /// The replacement for variable \c %%V in field #Format if \e Verbosity is \c Info.
77 /// Resourced as ' '.
79
80 /// The replacement for variable \c %%V in field #Format if \e Verbosity is \c Verbose.
81 /// Resourced as to '[***]'.
83
84 /// Characters written after each <em>Log Statement</em>.
85 /// This may be used for example to reset colors and styles.
86 /// Note, that with multi-line <em>Log Statements</em>, the contents of this field is \b not
87 /// written at the end of each line, but only at the end of the last line.
88 /// To define characters that are written after each line of a multi-line
89 /// <em>Log Statement</em>, set field #MsgSuffix.
90 ///
91 /// Defaults to empty string.
93
94
95 /// Constructor taking an object pool which is passed to each string member.
96 /// @param pool The pool object of the \alib{variables;Configuration}.
98 : Format (pool)
99 , VerbosityError (pool)
100 , VerbosityWarning (pool)
101 , VerbosityInfo (pool)
102 , VerbosityVerbose (pool)
103 , MsgSuffix (pool) {}
104}; // struct FormatMetaInfo
105
106//==================================================================================================
107/// Definition of date and time formats for class \alib{lox;textlogger::TextLogger}
108/// and its derivates.
109/// This struct is used to define an external \ref alib_mod_variables "configuration variable"
110/// named \ref alxcvALOX_LOGGERNAME_FORMAT_DATE_TIME.
111/// This variable can be accessed programatically
112/// with \alib{lox::textlogger;TextLogger::GetFormatDate} or by accessing the variable's value
113/// through the configuration object found in camp singleton #alib::ALOX.
114//==================================================================================================
116{
117 /// Format string for the output of the log date. For more information, see
118 /// "Standard Date and Time Format Strings" in .NET StringBuilder.AppendFormat().
120
121 /// Format string for the output of the time of day. For more information, see
122 /// "Standard Date and Time Format Strings" in .NET StringBuilder.AppendFormat().
124
125 /// The word "Days" the out put of time elapsed (if longer than a day).
127
128 /// Constructor taking an object pool which is passed to each string member.
129 /// @param pool The pool object of the \alib{variables;Configuration}.
131 : Date (pool)
132 , TimeOfDay (pool)
133 , ElapsedDays(pool) {}
134}; // struct DateFormat
135
136//==================================================================================================
137/// Definition of the formats of time differences for class
138/// \alib{lox;textlogger::TextLogger} and its derivates.
139/// This struct is used to define an external \ref alib_mod_variables "configuration variable"
140/// named \ref alxcvALOX_LOGGERNAME_FORMAT_TIME_DIFF.
141/// This variable can be accessed programatically
142/// with \alib{lox::textlogger;TextLogger::GetFormatTimeDiff} or by accessing the variable's value
143/// through the configuration object found in camp singleton #alib::ALOX.
144//==================================================================================================
146{
147 /// Minimum time difference to log in nanoseconds. Below that #None is written.
148 int64_t Minimum;
149
150 /// Output for time difference if below reasonable (measurable) minimum defined in #Minimum.
152
153 /// Entity nanoseconds for time difference outputs below 1000 microsecond.
155
156 /// Entity microseconds for time difference outputs below 1000 microseconds.
158
159 /// Entity milliseconds for time difference outputs below 1000 milliseconds.
161
162 /// Format for time difference outputs between 10s and 99.9s.
164
165 /// Format for time difference outputs between 100s and 60 min.
167
168 /// Format for time difference outputs between 1h and 24h.
170
171 /// Format for time difference outputs of more than a day.
173
174 /// Constructor taking an object pool which is passed to each string member.
175 /// @param pool The pool object of the \alib{variables;Configuration}.
177 : None (pool)
178 , Nanos (pool)
179 , Micros(pool)
180 , Millis(pool)
181 , Secs (pool)
182 , Mins (pool)
183 , Hours (pool)
184 , Days (pool) {}
185};
186
187//==================================================================================================
188/// Definition of the multi-line message mode for class \alib{lox;textlogger::TextLogger}
189/// and its derivates.
190/// This struct is used to define an external \ref alib_mod_variables "configuration variable"
191/// named \ref alxcvALOX_LOGGERNAME_FORMAT_MULTILINE.
192/// This variable can be accessed programatically
193/// with \alib{lox::textlogger;TextLogger::GetFormatMultiLine} or by accessing the variable's value
194/// through the configuration object found in camp singleton #alib::ALOX.
195//==================================================================================================
197{
198 /// Determines if multi line messages should be split into different log lines. Possible
199 /// values are:
200 ///
201 /// - 0: No line split is performed, delimiters can be replaced by readable delimiters
202 /// (depending on setting of #Delimiter and #DelimiterReplacement).
203 ///
204 /// - 1: Each log line contains all meta-information
205 ///
206 /// - 2: Starting with second log line, meta-information is replaced by blanks (default)
207 ///
208 /// - 3: The headline #Headline is logged and all lines of the multi line
209 /// text are logged at position zero (without further meta-information)
210 ///
211 /// - 4: Just the multi line text is logged, starting at column zero (no meta-information
212 /// is logged)
213 ///
214 /// \note In modes 3 and 4, no ESC::EOMETA is included at the beginning of the message.
215 /// Loggers that need such info, have to implement method
216 /// \alib{lox::textlogger;TextLogger::notifyMultiLineOp}.
217 int Mode;
218
219 /// This is the string interpreted as line delimiter within log messages. If \e nulled, then
220 /// <c>'\\n'</c>, <c>'\\r'</c> or <c>'\\r\\n'</c> is recognized.<br>
221 /// Important: Can be set to an empty string, to stop any multi line processing of
222 /// \b %TextLogger, even the replacements of the delimiter character.
224
225 /// Headline for multi line messages (depending on #Mode) .
226 /// Defaults to "ALox: Multi line message follows: "
228
229 /// Prefix for multi line messages. This is also used if multi line messages logging is
230 /// switched off (MultiLineMsgMode == 0) but replacing of a set MultiLineDelimiter takes
231 /// place.
232 /// Defaults to ">> ".
234
235 /// Suffix for multi line messages. This is also used if multi line messages logging is
236 /// switched off (MultiLineMsgMode == 0) and replacing of a set #Delimiter
237 /// takes place.<br>
238 /// Note that at the end of the last line, in addition #Suffix is added.<br>
239 /// Defaults to "".
241
242 /// This is the readable (!) separator string, for logging out multi line messages into a
243 /// single line (#Mode==0).
244 /// Defaults to "\\r".
246
247 /// Constructor taking an object pool which is passed to each string member.
248 /// @param pool The pool object of the \alib{variables;Configuration}.
250 : Delimiter (pool)
251 , Headline (pool)
252 , Prefix (pool)
253 , Suffix (pool)
254 , DelimiterReplacement(pool) {}
255
256};
257
258//==================================================================================================
259/// Definition of further format options for class \alib{lox;textlogger::TextLogger}
260/// and its derivates.
261/// This struct is used to define an external \ref alib_mod_variables "configuration variable"
262/// named \ref alxcvALOX_LOGGERNAME_FORMAT_OTHER.
263/// This variable can be accessed programatically
264/// with \alib{lox::textlogger;TextLogger::GetFormatOther} or by accessing the variable's value
265/// through the configuration object found in camp singleton #alib::ALOX.
266//==================================================================================================
268{
269 /// Replacement string if no source info is available.
271
272 /// Replacement string if no source info is available.
274
275 /// The minimum digits to write for the log number (if used in format string).
277
278 /// Constructor taking an object pool which is passed to each string member.
279 /// @param pool The pool object of the \alib{variables;Configuration}.
281 : NoSourceFileInfo(pool)
282 , NoMethodInfo (pool) {}
283}; // struct FormatOther
284
285
286//==================================================================================================
287/// Automatically detected field width and tab-stop positions for the meta-information part
288/// as well as the log message part, collected during the run of software.
289/// This struct is used to define an external \ref alib_mod_variables "configuration variable"
290/// named \ref alxcvALOX_LOGGERNAME_AUTO_SIZES.
291///
292/// This variable can be accessed programatically either with method
293/// \alib{lox::textlogger;TextLogger::GetAutoSizes} or by accessing the variable's value
294/// through the configuration object found in camp singleton #alib::ALOX.
295///
296/// For almost all use cases, field #Main will work as expected, because the meta-information
297/// of log lines usually do not change. In other words, if they get changed, it is a good idea
298/// to invoke \alib{strings::util;AutoSizes::Reset} on that field.
299///
300/// Field #LogMessage with built-in text loggers, is passed to field
301/// \alib{format;FormatterPythonStyle::Sizes} and thus is used to organize tab-stops and
302/// field widths of the log messages itself.<br>
303/// The field may be reset manually after (or before) a coherent set of log messages have
304/// been (respectively are to be) written. Such "coherent set" is for example the output of
305/// tabular data. If this is not done, a next table containing different data, would not be
306/// printed with correct field sizes in case the automatic tab-stops.
307///
308/// Also, it might be reasonable to invoke \alib{strings::util::AutoSizes;Consolidate} one both
309/// objects from time to time, or in certain situations.
310///
311/// @see %Variable \ref alxcvALOX_LOGGERNAME_AUTO_SIZES.
312//==================================================================================================
314{
315 /// The instance used with the meta info format string.
317
318 /// An \b AutoSizes object which is used to format the log message itself.
319 /// \note With the use of class \alib{lox::textlogger;StandardConverter}, this
320 /// instance is passed to the internal instance(s) of the
321 /// \alib{format;FormatterPythonStyle} used.
323}; // struct FormatAutoSizes
324
325//==================================================================================================
326/// A simple list of pairs of strings to search in log messages and their replacement value.
327/// This variable can be accessed programatically with
328/// \alib{lox::textlogger;TextLogger::GetReplacements} or by accessing the variable's value
329/// through the configuration object found in camp singleton #alib::ALOX.
330//==================================================================================================
332{
333 /// The list of pairs of replacement strings
334 std::vector<AStringPA, lang::StdContainerAllocator<AStringPA, PoolAllocator>> Pairs;
335
336 /// Constructor taking an object pool which is passed to the string vector.
337 /// @param pool The pool object of the \alib{variables;Configuration}.
339 : Pairs(pool) {}
340};
341
342/// Parameters specific to colorful loggers. As of today, this simply has one attribute.
344{
345 /// Denotes the use of light vs dark colors. Used with colorful descendants of class
346 /// \alib{lox::textlogger;TextLogger}.
348 {
349 Auto, ///< Automatic
350 Never, ///< Never use light colors
351 Foreground, ///< Use light colors for foreground
352 Background ///< Use light colors for background
353 };
354
355 LightColorUsage LCU= LightColorUsage::Auto; ///< Denotes use of light or dark colors.
356 ///< Defaults to \e Auto.
357};
358
359
360} // namespace [alib::lox::textlogger]
361
362DOX_MARKER([DOX_VARIABLES_DEFINETYPE1])
364DOX_MARKER([DOX_VARIABLES_DEFINETYPE1])
369ALIB_VARIABLES_DEFINE_TYPE ( alib::lox::textlogger::, FormatAutoSizes ,A_CHAR("ALOXAS" ) )
371ALIB_VARIABLES_DEFINE_TYPE ( alib::lox::textlogger::, ColorfulLoggerParameters ,A_CHAR("ALOXCLP") )
372
373
374ALIB_ENUMS_ASSIGN_RECORD( alib::lox::textlogger::ColorfulLoggerParameters::LightColorUsage, alib::enumrecords::ERSerializable )
375
#define A_CHAR(STR)
#define ALIB_ENUMS_ASSIGN_RECORD(TEnum, TRecord)
#define ALIB_VARIABLES_DEFINE_TYPE_WITH_POOL_CONSTRUCTOR(Namespace, CPPName, CfgTypeString)
#define ALIB_EXPORT
Definition alib.inl:488
#define ALIB_VARIABLES_DEFINE_TYPE(Namespace, CPPName, CfgTypeString)
This namespaces defines class TextLogger and its helpers.
Definition loxpimpl.inl:13
monomem::TPoolAllocator< MonoAllocator > PoolAllocator
strings::util::AutoSizes AutoSizes
Type alias in namespace alib.
strings::TAString< nchar, PoolAllocator > NAStringPA
Type alias in namespace alib.
strings::TAString< character, PoolAllocator > AStringPA
Type alias in namespace alib.
Parameters specific to colorful loggers. As of today, this simply has one attribute.
AutoSizes Main
The instance used with the meta info format string.
AStringPA ElapsedDays
The word "Days" the out put of time elapsed (if longer than a day).
FormatMetaInfo(PoolAllocator &pool)
Definition variables.inl:97
NAStringPA NoMethodInfo
Replacement string if no source info is available.
FormatOther(PoolAllocator &pool)
NAStringPA NoSourceFileInfo
Replacement string if no source info is available.
int LogNumberMinDigits
The minimum digits to write for the log number (if used in format string).
AStringPA Nanos
Entity nanoseconds for time difference outputs below 1000 microsecond.
AStringPA None
Output for time difference if below reasonable (measurable) minimum defined in Minimum.
AStringPA Mins
Format for time difference outputs between 100s and 60 min.
AStringPA Millis
Entity milliseconds for time difference outputs below 1000 milliseconds.
int64_t Minimum
Minimum time difference to log in nanoseconds. Below that None is written.
AStringPA Days
Format for time difference outputs of more than a day.
AStringPA Secs
Format for time difference outputs between 10s and 99.9s.
AStringPA Hours
Format for time difference outputs between 1h and 24h.
AStringPA Micros
Entity microseconds for time difference outputs below 1000 microseconds.
Replacements(PoolAllocator &pool)
std::vector< AStringPA, lang::StdContainerAllocator< AStringPA, PoolAllocator > > Pairs
The list of pairs of replacement strings.