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
24namespace absl {
25ABSL_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// Unparsing a flag produces the same result as `absl::LogSeverityName()` for
68// the standard levels and a base-ten integer otherwise.
69enum class LogSeverity : int {
70 kInfo = 0,
71 kWarning = 1,
72 kError = 2,
73 kFatal = 3,
74};
75
76// LogSeverities()
77//
78// Returns an iterable of all standard `absl::LogSeverity` values, ordered from
79// least to most severe.
80constexpr std::array<absl::LogSeverity, 4> LogSeverities() {
81 return {._M_elems: {absl::LogSeverity::kInfo, absl::LogSeverity::kWarning,
82 absl::LogSeverity::kError, absl::LogSeverity::kFatal}};
83}
84
85// LogSeverityName()
86//
87// Returns the all-caps string representation (e.g. "INFO") of the specified
88// severity level if it is one of the standard levels and "UNKNOWN" otherwise.
89constexpr const char* LogSeverityName(absl::LogSeverity s) {
90 return s == absl::LogSeverity::kInfo
91 ? "INFO"
92 : s == absl::LogSeverity::kWarning
93 ? "WARNING"
94 : s == absl::LogSeverity::kError
95 ? "ERROR"
96 : s == absl::LogSeverity::kFatal ? "FATAL" : "UNKNOWN";
97}
98
99// NormalizeLogSeverity()
100//
101// Values less than `kInfo` normalize to `kInfo`; values greater than `kFatal`
102// normalize to `kError` (**NOT** `kFatal`).
103constexpr absl::LogSeverity NormalizeLogSeverity(absl::LogSeverity s) {
104 return s < absl::LogSeverity::kInfo
105 ? absl::LogSeverity::kInfo
106 : s > absl::LogSeverity::kFatal ? absl::LogSeverity::kError : s;
107}
108constexpr absl::LogSeverity NormalizeLogSeverity(int s) {
109 return absl::NormalizeLogSeverity(s: static_cast<absl::LogSeverity>(s));
110}
111
112// operator<<
113//
114// The exact representation of a streamed `absl::LogSeverity` is deliberately
115// unspecified; do not rely on it.
116std::ostream& operator<<(std::ostream& os, absl::LogSeverity s);
117
118// Enums representing a lower bound for LogSeverity. APIs that only operate on
119// messages of at least a certain level (for example, `SetMinLogLevel()`) use
120// this type to specify that level. absl::LogSeverityAtLeast::kInfinity is
121// a level above all threshold levels and therefore no log message will
122// ever meet this threshold.
123enum class LogSeverityAtLeast : int {
124 kInfo = static_cast<int>(absl::LogSeverity::kInfo),
125 kWarning = static_cast<int>(absl::LogSeverity::kWarning),
126 kError = static_cast<int>(absl::LogSeverity::kError),
127 kFatal = static_cast<int>(absl::LogSeverity::kFatal),
128 kInfinity = 1000,
129};
130
131std::ostream& operator<<(std::ostream& os, absl::LogSeverityAtLeast s);
132
133// Enums representing an upper bound for LogSeverity. APIs that only operate on
134// messages of at most a certain level (for example, buffer all messages at or
135// below a certain level) use this type to specify that level.
136// absl::LogSeverityAtMost::kNegativeInfinity is a level below all threshold
137// levels and therefore will exclude all log messages.
138enum class LogSeverityAtMost : int {
139 kNegativeInfinity = -1000,
140 kInfo = static_cast<int>(absl::LogSeverity::kInfo),
141 kWarning = static_cast<int>(absl::LogSeverity::kWarning),
142 kError = static_cast<int>(absl::LogSeverity::kError),
143 kFatal = static_cast<int>(absl::LogSeverity::kFatal),
144};
145
146std::ostream& operator<<(std::ostream& os, absl::LogSeverityAtMost s);
147
148#define COMPOP(op1, op2, T) \
149 constexpr bool operator op1(absl::T lhs, absl::LogSeverity rhs) { \
150 return static_cast<absl::LogSeverity>(lhs) op1 rhs; \
151 } \
152 constexpr bool operator op2(absl::LogSeverity lhs, absl::T rhs) { \
153 return lhs op2 static_cast<absl::LogSeverity>(rhs); \
154 }
155
156// Comparisons between `LogSeverity` and `LogSeverityAtLeast`/
157// `LogSeverityAtMost` are only supported in one direction.
158// Valid checks are:
159// LogSeverity >= LogSeverityAtLeast
160// LogSeverity < LogSeverityAtLeast
161// LogSeverity <= LogSeverityAtMost
162// LogSeverity > LogSeverityAtMost
163COMPOP(>, <, LogSeverityAtLeast)
164COMPOP(<=, >=, LogSeverityAtLeast)
165COMPOP(<, >, LogSeverityAtMost)
166COMPOP(>=, <=, LogSeverityAtMost)
167#undef COMPOP
168
169ABSL_NAMESPACE_END
170} // namespace absl
171
172#endif // ABSL_BASE_LOG_SEVERITY_H_
173

source code of include/absl/base/log_severity.h