src/logger/level.rs

Lines

100.00 %

Functions

100.00 %

Regions

100.00 %


//
// File Name:    level.rs
// Directory:    src/logger
// Project Name: flogging
//
// Copyright (C) 2025 Bradley Willcott
//
// SPDX-License-Identifier: GPL-3.0-or-later
//
// This library (crate) is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This library (crate) is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this library (crate).  If not, see <https://www.gnu.org/licenses/>.
//

//!
//! # Log Entry Level
//!
//! This module provides the enum containing the possible log entry levels.
//! The order in which they are listed within the enum, enables logging at that level
//! and at all higher levels.
//!
//! The levels in descending order are:
//!
//! - SEVERE (highest level)
//! - WARNING
//! - INFO
//! - CONFIG
//! - FINE
//! - FINER
//! - FINEST (lowest level)
//!
//! In addition there is a level **OFF** that can be used to turn off logging.

use std::{fmt, str::FromStr};
use strum::{EnumIter, IntoEnumIterator};

///
/// Log entry level setting.
///
/// Default level: INFO.
///
// #[allow(unused)]
#[derive(Debug, Clone, Default, PartialEq, PartialOrd, EnumIter, Copy)]
pub enum Level {
    ///
    /// ALL is a special level that can be used to turn on logging
    /// for all levels.
    ///
    ALL,

    ///
    /// FINEST indicates a highly detailed tracing message.
    ///
    FINEST,

    ///
    /// FINER indicates a fairly detailed tracing message.
    /// Suggest logging calls for entering, returning,
    /// or `Error`s, such as returned via `Result`, are traced at
    /// this level.
    ///
    FINER,

    ///
    /// FINE is a message level providing tracing information.
    ///
    /// All of FINE, FINER, and FINEST are intended for relatively
    /// detailed tracing. The exact meaning of the three levels will
    /// vary between subsystems, but in general, FINEST should be
    /// used for the most voluminous detailed output, FINER for somewhat
    /// less detailed output, and FINE for the lowest volume (and most
    /// important) messages.
    ///
    /// In general the FINE level should be used for information that
    /// will be broadly interesting to developers who do not have a
    /// specialized interest in the specific subsystem.
    ///
    /// FINE messages might include things like minor (recoverable)
    /// failures. Issues indicating potential performance problems are
    /// also worth logging as FINE.
    ///
    FINE,

    ///
    /// CONFIG is a message level for static configuration messages.
    ///
    /// CONFIG messages are intended to provide a variety of static
    /// configuration information, to assist in debugging problems
    /// that may be associated with particular configurations.
    ///
    /// For example, a CONFIG message might include the CPU type, the
    /// graphics depth, the GUI look-and-feel, etc.
    ///
    CONFIG,

    ///
    /// INFO is a message level for informational messages.
    ///
    /// Typically INFO messages will be written to the console or its
    /// equivalent. So the INFO level should only be used for reasonably
    /// significant messages that will make sense to end users and system
    /// administrators.
    ///
    /// \[default level]
    ///
    #[default]
    INFO,

    ///
    /// WARNING is a message level indicating a potential problem.
    ///
    /// In general WARNING messages should describe events that will be
    /// of interest to end users or system managers, or which indicate
    /// potential problems.
    ///
    WARNING,

    ///
    /// SEVERE is a message level indicating a serious failure.
    ///
    /// In general SEVERE messages should describe events that are of
    /// considerable importance and which will prevent normal program
    /// execution. They should be reasonably intelligible to end users
    /// and to system administrators.
    ///
    SEVERE,

    ///
    /// OFF is a special level that can be used to turn off logging.
    ///
    OFF,
}

impl Level {
    ///
    /// Converts a level to its string version.
    ///
    pub const fn as_str(&self) -> &'static str {
        match self {
            Level::ALL => "ALL",
            Level::FINEST => "FINEST",
            Level::FINER => "FINER",
            Level::FINE => "FINE",
            Level::CONFIG => "CONFIG",
            Level::INFO => "INFO",
            Level::WARNING => "WARNING",
            Level::SEVERE => "SEVERE",
            Level::OFF => "OFF",
        }
    }
}

impl fmt::Display for Level {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.as_str().fmt(f)
    }
}

#[allow(dead_code)]
#[derive(Debug)]
pub struct LevelError {
    msg: String,
}

impl FromStr for Level {
    type Err = LevelError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "ALL" => Ok(Level::ALL),
            "FINEST" => Ok(Level::FINEST),
            "FINER" => Ok(Level::FINER),
            "FINE" => Ok(Level::FINE),
            "CONFIG" => Ok(Level::CONFIG),
            "INFO" => Ok(Level::INFO),
            "WARNING" => Ok(Level::WARNING),
            "SEVERE" => Ok(Level::SEVERE),
            "OFF" => Ok(Level::OFF),
            _ => Err(LevelError {
                msg: format!("Unknown Level: {s}"),
            }),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn compare_levels() {
        let log_level = Level::default();
        let b = Level::FINE;

        println!("\n|{log_level}|\n");

        assert!(b < log_level);
    }

    #[test]
    fn check_conversions() {
        for level in Level::iter() {
            let lstr = level.as_str();
            let l = Level::from_str(lstr).unwrap();
            assert_eq!(level, l);
        }

        assert!(Level::from_str("DEBUG").is_err());
    }
}

Line	Count	Source (jump to first uncovered line)
1		//
2		// File Name: level.rs
3		// Directory: src/logger
4		// Project Name: flogging
5		//
6		// Copyright (C) 2025 Bradley Willcott
7		//
8		// SPDX-License-Identifier: GPL-3.0-or-later
9		//
10		// This library (crate) is free software: you can redistribute it and/or modify
11		// it under the terms of the GNU General Public License as published by
12		// the Free Software Foundation, either version 3 of the License, or
13		// (at your option) any later version.
14		//
15		// This library (crate) is distributed in the hope that it will be useful,
16		// but WITHOUT ANY WARRANTY; without even the implied warranty of
17		// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18		// GNU General Public License for more details.
19		//
20		// You should have received a copy of the GNU General Public License
21		// along with this library (crate). If not, see <https://www.gnu.org/licenses/>.
22		//
23
24		//!
25		//! # Log Entry Level
26		//!
27		//! This module provides the enum containing the possible log entry levels.
28		//! The order in which they are listed within the enum, enables logging at that level
29		//! and at all higher levels.
30		//!
31		//! The levels in descending order are:
32		//!
33		//! - SEVERE (highest level)
34		//! - WARNING
35		//! - INFO
36		//! - CONFIG
37		//! - FINE
38		//! - FINER
39		//! - FINEST (lowest level)
40		//!
41		//! In addition there is a level OFF that can be used to turn off logging.
42
43		use std::{fmt, str::FromStr};
44		use strum::{EnumIter, IntoEnumIterator};
45
46		///
47		/// Log entry level setting.
48		///
49		/// Default level: INFO.
50		///
51		// #[allow(unused)]
52		#[derive(Debug, Clone, Default, PartialEq, PartialOrd, EnumIter, Copy)]
53		pub enum Level {
54		///
55		/// ALL is a special level that can be used to turn on logging
56		/// for all levels.
57		///
58		ALL,
59
60		///
61		/// FINEST indicates a highly detailed tracing message.
62		///
63		FINEST,
64
65		///
66		/// FINER indicates a fairly detailed tracing message.
67		/// Suggest logging calls for entering, returning,
68		/// or `Error`s, such as returned via `Result`, are traced at
69		/// this level.
70		///
71		FINER,
72
73		///
74		/// FINE is a message level providing tracing information.
75		///
76		/// All of FINE, FINER, and FINEST are intended for relatively
77		/// detailed tracing. The exact meaning of the three levels will
78		/// vary between subsystems, but in general, FINEST should be
79		/// used for the most voluminous detailed output, FINER for somewhat
80		/// less detailed output, and FINE for the lowest volume (and most
81		/// important) messages.
82		///
83		/// In general the FINE level should be used for information that
84		/// will be broadly interesting to developers who do not have a
85		/// specialized interest in the specific subsystem.
86		///
87		/// FINE messages might include things like minor (recoverable)
88		/// failures. Issues indicating potential performance problems are
89		/// also worth logging as FINE.
90		///
91		FINE,
92
93		///
94		/// CONFIG is a message level for static configuration messages.
95		///
96		/// CONFIG messages are intended to provide a variety of static
97		/// configuration information, to assist in debugging problems
98		/// that may be associated with particular configurations.
99		///
100		/// For example, a CONFIG message might include the CPU type, the
101		/// graphics depth, the GUI look-and-feel, etc.
102		///
103		CONFIG,
104
105		///
106		/// INFO is a message level for informational messages.
107		///
108		/// Typically INFO messages will be written to the console or its
109		/// equivalent. So the INFO level should only be used for reasonably
110		/// significant messages that will make sense to end users and system
111		/// administrators.
112		///
113		/// \[default level]
114		///
115		#[default]
116		INFO,
117
118		///
119		/// WARNING is a message level indicating a potential problem.
120		///
121		/// In general WARNING messages should describe events that will be
122		/// of interest to end users or system managers, or which indicate
123		/// potential problems.
124		///
125		WARNING,
126
127		///
128		/// SEVERE is a message level indicating a serious failure.
129		///
130		/// In general SEVERE messages should describe events that are of
131		/// considerable importance and which will prevent normal program
132		/// execution. They should be reasonably intelligible to end users
133		/// and to system administrators.
134		///
135		SEVERE,
136
137		///
138		/// OFF is a special level that can be used to turn off logging.
139		///
140		OFF,
141		}
142
143		impl Level {
144		///
145		/// Converts a level to its string version.
146		///
147	168	pub const fn as_str(&self) -> &'static str {
148	168	match self {
149	1	Level::ALL => "ALL",
150	7	Level::FINEST => "FINEST",
151	33	Level::FINER => "FINER",
152	13	Level::FINE => "FINE",
153	24	Level::CONFIG => "CONFIG",
154	44	Level::INFO => "INFO",
155	35	Level::WARNING => "WARNING",
156	10	Level::SEVERE => "SEVERE",
157	1	Level::OFF => "OFF",
158		}
159	168	}
160		}
161
162		impl fmt::Display for Level {
163	5	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
164	5	self.as_str().fmt(f)
165	5	}
166		}
167
168		#[allow(dead_code)]
169		#[derive(Debug)]
170		pub struct LevelError {
171		msg: String,
172		}
173
174		impl FromStr for Level {
175		type Err = LevelError;
176
177	10	fn from_str(s: &str) -> Result<Self, Self::Err> {
178	10	match s {
179	1	"ALL" => Ok(Level::ALL),
180	1	"FINEST" => Ok(Level::FINEST),
181	1	"FINER" => Ok(Level::FINER),
182	1	"FINE" => Ok(Level::FINE),
183	1	"CONFIG" => Ok(Level::CONFIG),
184	1	"INFO" => Ok(Level::INFO),
185	1	"WARNING" => Ok(Level::WARNING),
186	1	"SEVERE" => Ok(Level::SEVERE),
187	1	"OFF" => Ok(Level::OFF),
188	1	_ => Err(LevelError {
189	1	msg: format!("Unknown Level: {s}"),
190	1	}),
191		}
192	10	}
193		}
194
195		#[cfg(test)]
196		mod tests {
197		use super::*;
198
199		#[test]
200	1	fn compare_levels() {
201	1	let log_level = Level::default();
202	1	let b = Level::FINE;
203
204	1	println!("\n\|{log_level}\|\n");
205
206	1	assert!(b < log_level);
207	1	}
208
209		#[test]
210	1	fn check_conversions() {
211	1	for level in Level::iter() {
212	9	let lstr = level.as_str();
213	9	let l = Level::from_str(lstr).unwrap();
214	9	assert_eq!(level, l);
215		}
216
217	1	assert!(Level::from_str("DEBUG").is_err());
218	1	}
219		}