BDE 4.14.0 Production release
Loading...
Searching...
No Matches
ball_severity.h
Go to the documentation of this file.
1/// @file ball_severity.h
2///
3/// The content of this file has been pre-processed for Doxygen.
4///
5
6
7// ball_severity.h -*-C++-*-
8#ifndef INCLUDED_BALL_SEVERITY
9#define INCLUDED_BALL_SEVERITY
10
11#include <bsls_ident.h>
12BSLS_IDENT("$Id: $")
13
14/// @defgroup ball_severity ball_severity
15/// @brief Enumerate a set of logging severity levels.
16/// @addtogroup bal
17/// @{
18/// @addtogroup ball
19/// @{
20/// @addtogroup ball_severity
21/// @{
22///
23/// <h1> Outline </h1>
24/// * <a href="#ball_severity-purpose"> Purpose</a>
25/// * <a href="#ball_severity-classes"> Classes </a>
26/// * <a href="#ball_severity-description"> Description </a>
27/// * <a href="#ball_severity-usage"> Usage </a>
28/// * <a href="#ball_severity-example-1-syntax"> Example 1: Syntax </a>
29/// * <a href="#ball_severity-example-2-logging"> Example 2: Logging </a>
30///
31/// # Purpose {#ball_severity-purpose}
32/// Enumerate a set of logging severity levels.
33///
34/// # Classes {#ball_severity-classes}
35///
36/// - ball::Severity: namespace for enumerating logging severity levels
37///
38/// # Description {#ball_severity-description}
39/// This component provides a namespace, `ball::Severity`, for the
40/// `enum` type `ball::Severity::Level`. `Level` enumerates a list of severity
41/// levels that can be attached to a logging event. In addition, this component
42/// supports functions that convert the `Level` enumerators to a well-defined
43/// ASCII representation.
44///
45/// ## Usage {#ball_severity-usage}
46///
47///
48/// This section illustrates intended use of this component.
49///
50/// ### Example 1: Syntax {#ball_severity-example-1-syntax}
51///
52///
53/// The following snippets of code provide a simple illustration of ordinary
54/// `ball::Severity` operation. (The next example discusses a more elaborate
55/// usage scenario.)
56///
57/// First create a variable `level` of type `ball::Severity::Level` and
58/// initialize it to the value `ball::Severity::e_ERROR`.
59/// @code
60/// ball::Severity::Level level = ball::Severity::e_ERROR;
61/// @endcode
62/// Next, store a pointer to its ASCII representation in a variable `asciiLevel`
63/// of type `const char *`.
64/// @code
65/// const char *asciiLevel = ball::Severity::toAscii(level);
66/// assert(0 == strcmp(asciiLevel, "ERROR"));
67/// @endcode
68/// Finally, print the value of `level` to `bsl::cout`.
69/// @code
70/// bsl::cout << level << bsl::endl;
71/// @endcode
72/// This statement produces the following output on `stdout`:
73/// @code
74/// ERROR
75/// @endcode
76///
77/// ### Example 2: Logging {#ball_severity-example-2-logging}
78///
79///
80/// Consider a general-purpose logging facility that provides two interfaces:
81/// one for developers to use when logging from subroutines and another to be
82/// used by the owner of the main program to administer how much information is
83/// to be published to a log file. Messages logged with numeric values at or
84/// below the globally-administered threshold level are published to the log,
85/// while those logged with higher (less severe) levels are not. Being
86/// general-purpose, we envision that additional levels may be useful in some
87/// applications. Hence, the numeric values supplied in this component might be
88/// augmented with additional severity levels. For example:
89/// @code
90/// enum {
91/// MAJOR_ERROR = 48
92/// MINOR_ERROR = 80,
93/// DEBUG2 = 162
94/// };
95/// @endcode
96/// Given that library modules using augmented logging schemes may coexist in a
97/// single program, we would choose not to have the core logging facility depend
98/// on this enumeration, but instead accept integer log levels in the range
99/// [0 .. 255]. Hence, those that choose to limit their logging levels to the
100/// seven defined in `ball::Severity` can do so, and still coexist on the same
101/// logging facility along side routines that log with more finely-graduated
102/// levels of severity.
103///
104/// To facilitate administration, the following enumerated values, in addition
105/// to any level values supplied to programmers, should be available to the
106/// owner of the main program to control output:
107/// @code
108/// enum {
109/// ALL = 255, // publish all log messages
110/// OFF = -1 // disable logging
111/// };
112/// @endcode
113/// Setting the global threshold to `ALL` causes all messages to be published;
114/// setting it to `OFF` disables logging.
115/// @}
116/** @} */
117/** @} */
118
119/** @addtogroup bal
120 * @{
121 */
122/** @addtogroup ball
123 * @{
124 */
125/** @addtogroup ball_severity
126 * @{
127 */
128
129#include <balscm_version.h>
130
131#include <bsls_platform.h>
132
133#include <bsl_iosfwd.h>
134
135#ifndef BDE_OMIT_INTERNAL_DEPRECATED
136#if BSLS_PLATFORM_HAS_MACRO_PUSH_POP
137
138#pragma push_macro("OFF")
139#undef OFF
140#pragma push_macro("FATAL")
141#undef FATAL
142#pragma push_macro("ERROR")
143#undef ERROR
144#pragma push_macro("WARN")
145#undef WARN
146#pragma push_macro("INFO")
147#undef INFO
148#pragma push_macro("DEBUG")
149#undef DEBUG
150#pragma push_macro("TRACE")
151#undef TRACE
152
153#endif
154#endif // BDE_OMIT_INTERNAL_DEPRECATED
155
156
157namespace ball {
158
159 // ===============
160 // struct Severity
161 // ===============
162
163/// This struct provides a namespace for enumerating severity levels.
164struct Severity {
165
166 public:
167 enum Level {
168 e_OFF = 0, // disable generation of corresponding message
169 e_FATAL = 32, // a condition that will (likely) cause a *crash*
170 e_ERROR = 64, // a condition that *will* cause incorrect behavior
171 e_WARN = 96, // a *potentially* problematic condition
172 e_INFO = 128, // data about the running process
173 e_DEBUG = 160, // information useful while debugging
174 e_TRACE = 192 // execution trace data
175
176#ifndef BDE_OMIT_INTERNAL_DEPRECATED
184
185#ifndef OFF
187#endif
188#ifndef FATAL
190#endif
191#ifndef ERROR
193#endif
194#ifndef WARN
196#endif
197#ifndef INFO
199#endif
200#ifndef DEBUG
202#endif
203#ifndef TRACE
205#endif
206
207#endif // BDE_OMIT_INTERNAL_DEPRECATED
208 };
209
210 /// Define `e_LENGTH` to be the number of enumerators in the `Level`
211 /// enumeration.
212 enum {
213 e_LENGTH = 7
214 };
215
216 private:
217 // PRIVATE CLASS METHODS
218
219 /// Write to the specified `stream` the string representation of the
220 /// specified enumeration `value`.
221 static void print(bsl::ostream& stream, Severity::Level value);
222
223 public:
224 // CLASS METHODS
225
226 /// Load into the specified `level` the severity matching the specified
227 /// case-insensitive `string` of the specified `stringLength`. Return 0
228 /// on success, and a non-zero value with no effect on `level`
229 /// otherwise (i.e., `string` does not match any `Level` enumerator).
230 static int fromAscii(Severity::Level *level,
231 const char *string,
232 int stringLength);
233
234 /// Return the string representation exactly matching the enumerator name
235 /// corresponding to the specified enumeration `value`.
236 static const char *toAscii(Severity::Level value);
237
238 /// Format the specified `value` to the specified output `stream` and
239 /// return a reference to the modifiable `stream`.
240 static bsl::ostream& streamOut(bsl::ostream& stream,
241 Severity::Level value);
242};
243
244// FREE OPERATORS
245
246/// Format the specified `rhs` to the specified output `stream` and return a
247/// reference to the modifiable `stream`.
248bsl::ostream& operator<<(bsl::ostream& stream, Severity::Level rhs);
249
250// ============================================================================
251// INLINE DEFINITIONS
252// ============================================================================
253
254 // ---------------
255 // struct Severity
256 // ---------------
257
258// CLASS METHODS
259inline
260bsl::ostream& Severity::streamOut(bsl::ostream& stream, Severity::Level value)
261{
262 print(stream, value);
263 return stream;
264}
265
266} // close package namespace
267
268// FREE OPERATORS
269inline
270bsl::ostream& ball::operator<<(bsl::ostream& stream, Severity::Level rhs)
271{
272 return Severity::streamOut(stream, rhs);
273}
274
275
276
277#ifndef BDE_OMIT_INTERNAL_DEPRECATED
278#if BSLS_PLATFORM_HAS_MACRO_PUSH_POP
279
280#pragma pop_macro("OFF")
281#pragma pop_macro("FATAL")
282#pragma pop_macro("ERROR")
283#pragma pop_macro("WARN")
284#pragma pop_macro("INFO")
285#pragma pop_macro("DEBUG")
286#pragma pop_macro("TRACE")
287
288#endif
289#endif
290
291#endif
292
293// ----------------------------------------------------------------------------
294// Copyright 2015 Bloomberg Finance L.P.
295//
296// Licensed under the Apache License, Version 2.0 (the "License");
297// you may not use this file except in compliance with the License.
298// You may obtain a copy of the License at
299//
300// http://www.apache.org/licenses/LICENSE-2.0
301//
302// Unless required by applicable law or agreed to in writing, software
303// distributed under the License is distributed on an "AS IS" BASIS,
304// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
305// See the License for the specific language governing permissions and
306// limitations under the License.
307// ----------------------------- END-OF-FILE ----------------------------------
308
309/** @} */
310/** @} */
311/** @} */
#define BSLS_IDENT(str)
Definition bsls_ident.h:195
Definition ball_administration.h:214
bsl::ostream & operator<<(bsl::ostream &output, const Attribute &attribute)
This struct provides a namespace for enumerating severity levels.
Definition ball_severity.h:164
static const char * toAscii(Severity::Level value)
static bsl::ostream & streamOut(bsl::ostream &stream, Severity::Level value)
Definition ball_severity.h:260
@ e_LENGTH
Definition ball_severity.h:213
static int fromAscii(Severity::Level *level, const char *string, int stringLength)
Level
Definition ball_severity.h:167
@ ERROR
Definition ball_severity.h:192
@ BAEL_TRACE
Definition ball_severity.h:183
@ BAEL_WARN
Definition ball_severity.h:180
@ DEBUG
Definition ball_severity.h:201
@ e_TRACE
Definition ball_severity.h:174
@ e_ERROR
Definition ball_severity.h:170
@ FATAL
Definition ball_severity.h:189
@ e_FATAL
Definition ball_severity.h:169
@ e_OFF
Definition ball_severity.h:168
@ WARN
Definition ball_severity.h:195
@ e_DEBUG
Definition ball_severity.h:173
@ e_INFO
Definition ball_severity.h:172
@ BAEL_DEBUG
Definition ball_severity.h:182
@ e_WARN
Definition ball_severity.h:171
@ INFO
Definition ball_severity.h:198
@ BAEL_FATAL
Definition ball_severity.h:178
@ BAEL_ERROR
Definition ball_severity.h:179
@ BAEL_OFF
Definition ball_severity.h:177
@ OFF
Definition ball_severity.h:186
@ TRACE
Definition ball_severity.h:204
@ BAEL_INFO
Definition ball_severity.h:181