1 // Copyright 2017 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 #ifndef ABSL_BASE_LOG_SEVERITY_H_
16 #define ABSL_BASE_LOG_SEVERITY_H_
17
18 #include <array>
19 #include <ostream>
20
21 #include "absl/base/attributes.h"
22 #include "absl/base/config.h"
23
24 namespace absl {
25 ABSL_NAMESPACE_BEGIN
26
27 // absl::LogSeverity
28 //
29 // Four severity levels are defined. Logging APIs should terminate the program
30 // when a message is logged at severity `kFatal`; the other levels have no
31 // special semantics.
32 //
33 // Values other than the four defined levels (e.g. produced by `static_cast`)
34 // are valid, but their semantics when passed to a function, macro, or flag
35 // depend on the function, macro, or flag. The usual behavior is to normalize
36 // such values to a defined severity level, however in some cases values other
37 // than the defined levels are useful for comparison.
38 //
39 // Example:
40 //
41 // // Effectively disables all logging:
42 // SetMinLogLevel(static_cast<absl::LogSeverity>(100));
43 //
44 // Abseil flags may be defined with type `LogSeverity`. Dependency layering
45 // constraints require that the `AbslParseFlag()` overload be declared and
46 // defined in the flags library itself rather than here. The `AbslUnparseFlag()`
47 // overload is defined there as well for consistency.
48 //
49 // absl::LogSeverity Flag String Representation
50 //
51 // An `absl::LogSeverity` has a string representation used for parsing
52 // command-line flags based on the enumerator name (e.g. `kFatal`) or
53 // its unprefixed name (without the `k`) in any case-insensitive form. (E.g.
54 // "FATAL", "fatal" or "Fatal" are all valid.) Unparsing such flags produces an
55 // unprefixed string representation in all caps (e.g. "FATAL") or an integer.
56 //
57 // Additionally, the parser accepts arbitrary integers (as if the type were
58 // `int`).
59 //
60 // Examples:
61 //
62 // --my_log_level=kInfo
63 // --my_log_level=INFO
64 // --my_log_level=info
65 // --my_log_level=0
66 //
67 // `DFATAL` and `kLogDebugFatal` are similarly accepted.
68 //
69 // Unparsing a flag produces the same result as `absl::LogSeverityName()` for
70 // the standard levels and a base-ten integer otherwise.
71 enum class LogSeverity : int {
72 kInfo = 0,
73 kWarning = 1,
74 kError = 2,
75 kFatal = 3,
76 };
77
78 // LogSeverities()
79 //
80 // Returns an iterable of all standard `absl::LogSeverity` values, ordered from
81 // least to most severe.
LogSeverities()82 constexpr std::array<absl::LogSeverity, 4> LogSeverities() {
83 return {{absl::LogSeverity::kInfo, absl::LogSeverity::kWarning,
84 absl::LogSeverity::kError, absl::LogSeverity::kFatal}};
85 }
86
87 // `absl::kLogDebugFatal` equals `absl::LogSeverity::kFatal` in debug builds
88 // (i.e. when `NDEBUG` is not defined) and `absl::LogSeverity::kError`
89 // otherwise. Avoid ODR-using this variable as it has internal linkage and thus
90 // distinct storage in different TUs.
91 #ifdef NDEBUG
92 static constexpr absl::LogSeverity kLogDebugFatal = absl::LogSeverity::kError;
93 #else
94 static constexpr absl::LogSeverity kLogDebugFatal = absl::LogSeverity::kFatal;
95 #endif
96
97 // LogSeverityName()
98 //
99 // Returns the all-caps string representation (e.g. "INFO") of the specified
100 // severity level if it is one of the standard levels and "UNKNOWN" otherwise.
LogSeverityName(absl::LogSeverity s)101 constexpr const char* LogSeverityName(absl::LogSeverity s) {
102 return s == absl::LogSeverity::kInfo
103 ? "INFO"
104 : s == absl::LogSeverity::kWarning
105 ? "WARNING"
106 : s == absl::LogSeverity::kError
107 ? "ERROR"
108 : s == absl::LogSeverity::kFatal ? "FATAL" : "UNKNOWN";
109 }
110
111 // NormalizeLogSeverity()
112 //
113 // Values less than `kInfo` normalize to `kInfo`; values greater than `kFatal`
114 // normalize to `kError` (**NOT** `kFatal`).
NormalizeLogSeverity(absl::LogSeverity s)115 constexpr absl::LogSeverity NormalizeLogSeverity(absl::LogSeverity s) {
116 return s < absl::LogSeverity::kInfo
117 ? absl::LogSeverity::kInfo
118 : s > absl::LogSeverity::kFatal ? absl::LogSeverity::kError : s;
119 }
NormalizeLogSeverity(int s)120 constexpr absl::LogSeverity NormalizeLogSeverity(int s) {
121 return absl::NormalizeLogSeverity(static_cast<absl::LogSeverity>(s));
122 }
123
124 // operator<<
125 //
126 // The exact representation of a streamed `absl::LogSeverity` is deliberately
127 // unspecified; do not rely on it.
128 std::ostream& operator<<(std::ostream& os, absl::LogSeverity s);
129
130 // Enums representing a lower bound for LogSeverity. APIs that only operate on
131 // messages of at least a certain level (for example, `SetMinLogLevel()`) use
132 // this type to specify that level. absl::LogSeverityAtLeast::kInfinity is
133 // a level above all threshold levels and therefore no log message will
134 // ever meet this threshold.
135 enum class LogSeverityAtLeast : int {
136 kInfo = static_cast<int>(absl::LogSeverity::kInfo),
137 kWarning = static_cast<int>(absl::LogSeverity::kWarning),
138 kError = static_cast<int>(absl::LogSeverity::kError),
139 kFatal = static_cast<int>(absl::LogSeverity::kFatal),
140 kInfinity = 1000,
141 };
142
143 std::ostream& operator<<(std::ostream& os, absl::LogSeverityAtLeast s);
144
145 // Enums representing an upper bound for LogSeverity. APIs that only operate on
146 // messages of at most a certain level (for example, buffer all messages at or
147 // below a certain level) use this type to specify that level.
148 // absl::LogSeverityAtMost::kNegativeInfinity is a level below all threshold
149 // levels and therefore will exclude all log messages.
150 enum class LogSeverityAtMost : int {
151 kNegativeInfinity = -1000,
152 kInfo = static_cast<int>(absl::LogSeverity::kInfo),
153 kWarning = static_cast<int>(absl::LogSeverity::kWarning),
154 kError = static_cast<int>(absl::LogSeverity::kError),
155 kFatal = static_cast<int>(absl::LogSeverity::kFatal),
156 };
157
158 std::ostream& operator<<(std::ostream& os, absl::LogSeverityAtMost s);
159
160 #define COMPOP(op1, op2, T) \
161 constexpr bool operator op1(absl::T lhs, absl::LogSeverity rhs) { \
162 return static_cast<absl::LogSeverity>(lhs) op1 rhs; \
163 } \
164 constexpr bool operator op2(absl::LogSeverity lhs, absl::T rhs) { \
165 return lhs op2 static_cast<absl::LogSeverity>(rhs); \
166 }
167
168 // Comparisons between `LogSeverity` and `LogSeverityAtLeast`/
169 // `LogSeverityAtMost` are only supported in one direction.
170 // Valid checks are:
171 // LogSeverity >= LogSeverityAtLeast
172 // LogSeverity < LogSeverityAtLeast
173 // LogSeverity <= LogSeverityAtMost
174 // LogSeverity > LogSeverityAtMost
175 COMPOP(>, <, LogSeverityAtLeast)
176 COMPOP(<=, >=, LogSeverityAtLeast)
177 COMPOP(<, >, LogSeverityAtMost)
178 COMPOP(>=, <=, LogSeverityAtMost)
179 #undef COMPOP
180
181 ABSL_NAMESPACE_END
182 } // namespace absl
183
184 #endif // ABSL_BASE_LOG_SEVERITY_H_
185