src/logger/mod.rs

Lines

100.00 %

Functions

100.00 %

Regions

100.00 %


//
// File Name:    mod.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/>.
//

//!
//! # Logger
//!
//! `Logger` is the work-horse of the crate.
//!
//! It contains the primary methods to both create a logger instance, and has
//! the methods to add log messages at various log levels.
//!

#![allow(clippy::needless_doctest_main)]

mod builder;
mod level;
mod log_entry;

use anyhow::{Context, Error, Result};
use std::cell::{LazyCell, RefCell};
use std::collections::hash_map::IterMut;
use std::collections::{HashMap, HashSet};
use std::f32::consts;
use std::fs::{File, exists};
use std::io::Write;
use std::marker::PhantomData;
use std::module_path;
use std::ops::DerefMut;
use std::path::Path;
use std::sync::mpsc::Sender;
use std::sync::{Arc, MutexGuard, PoisonError, mpsc};
use std::thread;
use std::{fmt, fs};

pub use builder::*;
pub use level::Level;
pub use log_entry::LogEntry;

use crate::*;

///
/// This is the work-horse, providing the primary methods of the crate.
///
pub struct Logger {
    ///
    /// Identify the source of log messages passed to this logger.
    ///
    /// This would ideally be the **mod** path.
    ///
    mod_path: String,

    ///
    /// The name of the function/method inside which the log message
    /// is generated.
    ///
    fn_name: String,

    ///
    /// Default level used by `log(msg)`.
    ///
    level: Level,

    ///
    /// Holds the handlers associated with this logger.
    ///
    handlers: RefCell<HashMap<Handler, Box<dyn HandlerTrait>>>,
}

impl Logger {
    ///
    /// Create a new Logger instance.
    ///
    /// Logging level is set to it's default setting (INFO).
    ///
    /// No `handlers` are set. Use the various methods of
    /// [`LoggerBuilder`] to configure the new `Logger`.
    ///
    /// ## Parameters
    /// - `mod_path` - The module path. Can be set with: [`module_path!()`]
    ///
    /// Returns a `LoggerBuilder` for further configuring.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_console_handler()
    ///     .build();
    /// ```
    ///
    pub fn builder(mod_path: &str) -> LoggerBuilder {
        LoggerBuilder::create(mod_path.to_string())
    }

    ///
    /// Log a CONFIG message.
    ///
    /// If the logger is currently enabled for the CONFIG message level
    /// then the given message is forwarded to all the registered output
    /// Handler objects.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_level(Level::CONFIG);
    /// log.config("Some text to store.");
    /// ```
    ///
    pub fn config(&mut self, msg: &str) {
        self.log(Level::CONFIG, &self.fn_name(), msg);
    }

    ///
    /// Create new Logger instance, with a `ConsoleHandler`, output
    /// set to: [`std::io::stdout`].
    ///
    /// Logging level is set to it's default setting (INFO).
    ///
    /// ## Parameters
    /// - `mod_path`- The module path. Suggest using [`module_path!()`].
    ///
    /// Returns a configured `Logger`.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_fn_name("main");
    ///
    /// log.warning("Don't over do it.");
    /// ```
    /// Output to stdout:
    /// ```text
    /// flogging->main [WARNING] Don't over do it.
    /// ```
    ///
    pub fn console_logger(mod_path: &str) -> Logger {
        Logger::builder(mod_path).add_console_handler().build()
    }

    ///
    /// Create new Logger instance, with a custom handler.
    ///
    /// ## Parameters
    /// - `mod_path`- The module path. Suggest using [`module_path!()`].
    /// - `label` - Unique label for this custom handler.
    /// - `custom` - The boxed custom handler.
    ///
    /// Returns a configured `Logger`.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::custom_logger(
    ///     module_path!(),
    ///     "MockHandler",
    ///     Box::new(MockHandler::create("Some text").unwrap()),
    /// );
    /// log.set_fn_name("main");
    ///
    /// log.warning("Don't over do it.");
    /// ```
    /// [`MockHandler`] doesn't publish anything, as [`publish()`][MockHandler::publish()] is a **NoOp** method.
    /// It is used here to make the example work.
    ///
    /// However, it is expected that _your_ custom handler will do a little more.
    ///
    pub fn custom_logger(mod_path: &str, label: &str, custom: Box<dyn HandlerTrait>) -> Logger {
        Logger::builder(mod_path)
            .add_custom_handler(label, custom)
            .build()
    }

    ///
    /// Create new Logger instance, with a `ConsoleHandler`, output
    /// set to: [`std::io::stderr`].
    ///
    /// Logging level is set to it's default setting (INFO).
    ///
    /// ## Parameters
    /// - `mod_path`- The module path. Suggest using [`module_path!()`].
    ///
    /// Returns a configured `Logger`.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::econsole_logger(module_path!());
    /// log.set_fn_name("main");
    ///
    /// log.warning("Don't over do it.");
    /// ```
    /// Output to stderr:
    /// ```text
    /// flogging->main [WARNING] Don't over do it.
    /// ```
    ///
    pub fn econsole_logger(mod_path: &str) -> Logger {
        Logger::builder(mod_path).add_econsole_handler().build()
    }

    ///
    /// Log a method entry.
    ///
    /// This is a convenience method that can be used to log entry to a method.
    /// A `LogEntry` with message "Entry" and log level FINER, is logged.
    ///
    /// ## Examples
    /// ```
    /// mod my_mod {
    ///     extern crate flogging;
    ///     use flogging::*;
    ///     use std::cell::{LazyCell, RefCell};
    ///
    ///     // Setting up the module level logger.
    ///     const LOGGER: LazyCell<RefCell<Logger>> = LazyCell::new(|| {
    ///         RefCell::new({
    ///             Logger::builder(module_path!())
    ///                 .add_console_handler()
    ///                 .set_level(Level::FINEST)
    ///                 .build()
    ///         })
    ///     });
    ///
    ///     pub fn my_func(data: &str) {
    ///         let binding = LOGGER;
    ///         let mut log = binding.borrow_mut();
    ///         log.set_fn_name("my_func");
    ///
    ///         log.entering();
    ///     }
    /// }
    ///
    /// fn main() {
    ///     let data = "Some data";
    ///     my_mod::my_func(data);
    /// }
    /// ```
    /// Output:
    /// ```text
    /// flogging::my_mod->my_func [FINER  ] Entry
    /// ```
    ///
    pub fn entering(&mut self) {
        self.log(Level::FINER, &self.fn_name(), "Entry");
    }

    ///
    /// Log a method entry.
    ///
    /// This is a convenience method that can be used to log entry to a method.
    /// A `LogEntry` with message "Entry" and log level FINER, is logged.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// mod my_mod {
    ///     extern crate flogging;
    ///     use flogging::*;
    ///     use std::cell::{LazyCell, RefCell};
    ///
    ///     // Setting up the module level logger.
    ///     const LOGGER: LazyCell<RefCell<Logger>> = LazyCell::new(|| {
    ///         RefCell::new({
    ///             Logger::builder(module_path!())
    ///                 .add_console_handler()
    ///                 .set_level(Level::FINEST)
    ///                 .build()
    ///         })
    ///     });
    ///
    ///     pub fn my_func(data: &str) {
    ///         let binding = LOGGER;
    ///         let mut log = binding.borrow_mut();
    ///         log.set_fn_name("my_func");
    ///
    ///         log.entering_with(&format!("data: \"{data}\""));
    ///     }
    /// }
    ///
    /// fn main() {
    ///     let data = "Some data";
    ///     my_mod::my_func(data);
    /// }
    /// ```
    /// Output:
    /// ```text
    /// flogging::my_mod->my_func [FINER  ] Entry: (data: "Some data")
    /// ```
    ///
    pub fn entering_with(&mut self, msg: &str) {
        self.log(
            Level::FINER,
            &self.fn_name(),
            &("Entry: (".to_string() + msg + ")"),
        );
    }

    ///
    /// Log a method return.
    ///
    /// This is a convenience method that can be used to log returning from a method.
    /// A `LogEntry` with message "Return" and log level FINER, is logged.
    ///
    /// ## Examples
    /// ```
    /// mod my_mod {
    ///     extern crate flogging;
    ///     use flogging::*;
    ///     use std::cell::{LazyCell, RefCell};
    ///
    ///     // Setting up the module level logger.
    ///     const LOGGER: LazyCell<RefCell<Logger>> = LazyCell::new(|| {
    ///         RefCell::new({
    ///             Logger::builder(module_path!())
    ///                 .add_console_handler()
    ///                 .set_level(Level::FINEST)
    ///                 .build()
    ///         })
    ///     });
    ///
    ///     pub fn my_func(data: &str) {
    ///         let binding = LOGGER;
    ///         let mut log = binding.borrow_mut();
    ///         log.set_fn_name("my_func");
    ///
    ///         log.exiting();
    ///     }
    /// }
    ///
    /// fn main() {
    ///     let data = "Some data";
    ///     my_mod::my_func(data);
    /// }
    /// ```
    /// Output:
    /// ```text
    /// flogging::my_mod->my_func [FINER  ] Return
    /// ```
    ///
    pub fn exiting(&mut self) {
        self.log(Level::FINER, &self.fn_name(), "Return");
    }

    ///
    /// Log a method return.
    ///
    /// This is a convenience method that can be used to log returning from a method.
    /// A `LogEntry` with message "Return" and log level FINER, is logged.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// mod my_mod {
    ///     extern crate flogging;
    ///     use flogging::*;
    ///     use std::cell::{LazyCell, RefCell};
    ///
    ///     // Setting up the module level logger.
    ///     const LOGGER: LazyCell<RefCell<Logger>> = LazyCell::new(|| {
    ///         RefCell::new({
    ///             Logger::builder(module_path!())
    ///                 .add_console_handler()
    ///                 .set_level(Level::FINEST)
    ///                 .build()
    ///         })
    ///     });
    ///
    ///     pub fn my_func(data: &str) -> bool {
    ///         let binding = LOGGER;
    ///         let mut log = binding.borrow_mut();
    ///         log.set_fn_name("my_func");
    ///
    ///         let rtn = true;
    ///         log.exiting_with(&format!("rtn: {rtn}"));
    ///         rtn
    ///     }
    /// }
    ///
    /// fn main() {
    ///     let data = "Some data";
    ///     my_mod::my_func(data);
    /// }
    /// ```
    /// Output:
    /// ```text
    /// flogging::my_mod->my_func [FINER  ] Return: (rtn: true)
    /// ```
    ///
    pub fn exiting_with(&mut self, msg: &str) {
        self.log(
            Level::FINER,
            &self.fn_name(),
            &("Return: (".to_string() + msg + ")"),
        );
    }

    ///
    /// Create new Logger instance, with a `FileHandler`.
    ///
    /// Logging level is set to it's default setting (INFO).
    ///
    /// ## Parameters
    /// - `mod_path`- The module path. Suggest using [`std::module_path`][mp].
    /// - `filename` - The name of the log file to use. Will be created
    ///   if it doesn't exist.
    ///
    /// Returns a configured `Logger`.
    ///
    /// ## Examples
    /// ```
    /// use flogging::Logger;
    ///
    /// let mut log = Logger::file_logger(module_path!(), "test_logs/logger.log");
    /// log.set_fn_name("main");
    ///
    /// log.info("Some text to store.");
    /// ```
    /// Output:
    /// ```text
    /// 2025-07-18T12:14:47.322720683+08:00 flogging->main [INFO   ] Some text to store.
    /// ```
    ///
    /// [mp]: https://doc.rust-lang.org/std/macro.module_path.html
    pub fn file_logger(mod_path: &str, filename: &str) -> Logger {
        Logger::builder(mod_path).add_file_handler(filename).build()
    }

    ///
    /// Log a FINE message.
    ///
    /// If the logger is currently enabled for the FINE message level
    /// then the given message is forwarded to all the registered output
    /// Handler objects.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_level(Level::FINEST);
    /// log.set_fn_name("main");
    ///
    /// log.fine("Some text to store.");
    /// ```
    /// Output:
    /// ```text
    /// flogging->main [FINE   ] Some text to store.
    /// ```
    ///
    pub fn fine(&mut self, msg: &str) {
        self.log(Level::FINE, &self.fn_name(), msg);
    }

    ///
    /// Log a FINER message.
    ///
    /// If the logger is currently enabled for the FINER message level
    /// then the given message is forwarded to all the registered output
    /// Handler objects.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_level(Level::FINEST);
    /// log.set_fn_name("main");
    ///
    /// log.finer("Some text to store.");
    /// ```
    /// Output:
    /// ```text
    /// flogging->main [FINER  ] Some text to store.
    /// ```
    ///
    pub fn finer(&mut self, msg: &str) {
        self.log(Level::FINER, &self.fn_name(), msg);
    }

    ///
    /// Log a FINEST message.
    ///
    /// If the logger is currently enabled for the FINEST message level
    /// then the given message is forwarded to all the registered output
    /// Handler objects.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_level(Level::FINEST);
    /// log.set_fn_name("main");
    ///
    /// log.finest("Some text to store.");
    /// ```
    /// Output:
    /// ```text
    /// flogging->main [FINEST ] Some text to store.
    /// ```
    ///
    pub fn finest(&mut self, msg: &str) {
        self.log(Level::FINEST, &self.fn_name(), msg);
    }

    ///
    /// Get the current function/method name.
    ///
    pub fn fn_name(&self) -> String {
        self.fn_name.clone()
    }

    ///
    /// Get required `Handler`.
    ///
    /// ## Parameters
    /// - `handler` - The enum of the required handler.
    ///
    /// Returns Some boxed handler, or None.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::string_logger(module_path!());
    /// log.set_fn_name("get_handler");
    ///
    /// log.info("Some text to store.");
    ///
    /// let h = log.get_handler(Handler::String).unwrap();
    /// println!("{h}");
    /// ```
    pub fn get_handler(&mut self, handler: Handler) -> Option<Box<&mut dyn HandlerTrait>> {
        match self.handlers.get_mut().get_mut(&handler) {
            Some(val) => Some(Box::new(&mut **val)),
            None => None,
        }
    }

    ///
    /// Check if the required `Handler` has been added to this `Logger`.
    ///
    /// ## Parameters
    /// - `handler` - The enum of the required handler.
    ///
    /// Returns `true` if it exists, `false` otherwise.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::string_logger(module_path!());
    /// log.info("Some text to store.");
    ///
    /// println!("This logger has a 'StringHandler': {}", log.has_handler(Handler::String));
    /// ```
    pub fn has_handler(&self, handler: Handler) -> bool {
        self.handlers.borrow().contains_key(&handler)
    }
    ///
    /// Log a INFO message.
    ///
    /// If the logger is currently enabled for the INFO message level
    /// then the given message is forwarded to all the registered output
    /// Handler objects.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_level(Level::FINEST);
    /// log.set_fn_name("main");
    ///
    /// log.info("Some text to store.");
    /// ```
    /// Output:
    /// ```text
    /// flogging->main [INFO   ] Some text to store.
    /// ```
    ///
    pub fn info(&mut self, msg: &str) {
        self.log(Level::INFO, &self.fn_name(), msg);
    }

    ///
    /// Check if a message of the given level would actually be logged by this logger.
    ///
    /// ## Parameters
    /// - `level` - The level to compare with.
    ///
    /// Returns `true` if it is loggable, `false` if not.
    ///
    fn is_loggable(&self, level: &Level) -> bool {
        *level >= self.level
    }

    ///
    /// Checks whether or not this logger is processing log requests.
    ///
    /// Returns `true` if it is, `false` if not.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_level(Level::OFF);
    /// log.set_fn_name("main");
    ///
    /// let msg = "The program might become unstable.";
    /// log.warning(msg);
    ///
    /// if !log.is_logging() {
    ///     eprintln!{"{msg}"};
    /// }
    /// ```
    /// Output to [`std::io::stderr`]:
    /// ```text
    /// The program might become unstable.
    /// ```
    ///
    pub fn is_logging(&self) -> bool {
        self.level() != &Level::OFF
    }

    ///
    /// Obtain the current logging level for this Log instance.
    ///
    pub fn level(&self) -> &Level {
        &self.level
    }

    ///
    /// Log a `LogEntry`.
    ///
    /// All the other logging methods in this class call through this method to actually
    /// perform any logging.
    ///
    /// ## Parameters
    /// - `entry` - The `LogEntry` to be published.
    ///
    fn _log(&mut self, entry: &mut LogEntry) {
        entry.set_mod_path(self.mod_path.clone());

        for handler in self.handlers.get_mut() {
            handler.1.publish(entry);
        }
    }

    ///
    /// Log a message, with no arguments.
    ///
    /// If the logger is currently enabled for the given message level then the given
    /// message is forwarded to all the registered output `Handler` objects.
    ///
    /// ## Parameters
    /// - `level` - One of the message level identifiers, e.g., SEVERE.
    /// - `fn_name` - The name of the function/method from-which this method
    ///   was called.
    /// - `msg` - The string message.
    ///
    fn log(&mut self, level: Level, fn_name: &str, msg: &str) {
        if !self.is_loggable(&level) {
            return;
        }

        // build LogEntry
        let mut log_entry = LogEntry::create(level, fn_name.to_string(), msg.to_string());
        // Send LogEntry
        self._log(&mut log_entry);
    }

    ///
    /// Create new Logger instance, with a `ConsoleHandler`, output
    /// set to: [`std::io::stdout`].
    ///
    /// Logging level is set to it's default setting (INFO).
    ///
    /// All `INFO` level log entries are output without any formatting.
    /// All other levels are processed through the formatter, first.
    ///
    /// ## Parameters
    /// - `mod_path`- The module path. Suggest using [`module_path!()`].
    ///
    /// Returns a configured `Logger`.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::pconsole_logger(module_path!());
    /// log.set_fn_name("main");
    ///
    /// log.warning("Don't over do it.");
    /// ```
    /// Output to stderr:
    /// ```text
    /// flogging->main [WARNING] Don't over do it.
    /// ```
    ///
    pub fn pconsole_logger(mod_path: &str) -> Logger {
        Logger::builder(mod_path).add_pconsole_handler().build()
    }

    ///
    /// Remove an existing log file.
    ///
    /// The purpose of this, is to allow resetting of the log file, each time
    /// a test run is done.
    ///
    /// ## Note
    ///
    /// This **must** be called _before_ adding the corresponding file handler
    /// that is going to open this file.
    ///
    /// ## Parameters
    ///
    /// - `filename` - The name of the output log file. Must include any relevant
    ///   path (relative or absolute).
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// Logger::remove_file("test_logs/logger.log");
    /// let mut log = Logger::file_logger(module_path!(), "test_logs/logger.log");
    /// log.set_fn_name("main");
    /// log.info("Something to log.");
    /// ```
    ///
    pub fn remove_file(filename: &str) {
        let _ = fs::remove_file(filename).is_err();
    }

    ///
    /// Set the current function/method name.
    ///
    /// ## Parameters
    /// - `fn_name` - The name of the function/method in which you are
    ///   logging.
    ///
    /// Returns itself for chaining purposes.
    ///
    pub fn set_fn_name(&mut self, fn_name: &str) -> &mut Self {
        self.fn_name = fn_name.to_string();
        self
    }

    ///
    /// Set logging level for this Log instance.
    ///
    /// ## Parameters
    /// - `level` - The new logging level to set.
    ///
    /// Returns itself for chaining purposes.
    ///
    pub fn set_level(&mut self, level: Level) -> &mut Self {
        self.level = level;
        self
    }

    ///
    /// Log a SEVERE message.
    ///
    /// If the logger is currently enabled for the SEVERE message level
    /// then the given message is forwarded to all the registered output
    /// Handler objects.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_level(Level::FINEST);
    /// log.set_fn_name("main");
    ///
    /// log.severe("Some text to store.");
    /// ```
    /// Output:
    /// ```text
    /// flogging->main [SEVERE ] Some text to store.
    /// ```
    ///
    pub fn severe(&mut self, msg: &str) {
        self.log(Level::SEVERE, &self.fn_name(), msg);
    }

    ///
    /// Create new Logger instance, with a `ConsoleHandler`.
    ///
    /// Logging level is set to it's default setting (INFO).
    ///
    /// I expect this will be primarily used during unit testing of
    /// the logging output. Though, any requirement to pass-on the log entry,
    /// perhaps for further processing, would also be a valid use case.
    ///
    /// ## Parameters
    /// - `mod_path`- The module path. Suggest using [`module_path!()`].
    ///
    /// Returns a configured `Logger`.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::string_logger(module_path!());
    /// log.set_fn_name("main");
    ///
    /// log.warning("Don't over do it.");
    ///
    /// let log_str = log.get_handler(Handler::String).unwrap().get_log();
    ///
    /// println!("{log_str}");
    /// ```
    /// Output:
    /// ```text
    /// flogging->main [WARNING] Don't over do it.
    /// ```
    ///
    pub fn string_logger(mod_path: &str) -> Logger {
        Logger::builder(mod_path).add_string_handler().build()
    }

    ///
    /// Log a WARNING message.
    ///
    /// If the logger is currently enabled for the WARNING message level
    /// then the given message is forwarded to all the registered output
    /// Handler objects.
    ///
    /// ## Parameters
    /// - `msg` - The string message.
    ///
    /// ## Examples
    /// ```
    /// use flogging::*;
    ///
    /// let mut log = Logger::console_logger(module_path!());
    /// log.set_level(Level::FINEST);
    /// log.set_fn_name("main");
    ///
    /// log.warning("Some text to store.");
    /// ```
    /// Output:
    /// ```text
    /// flogging->main [WARNING] Some text to store.
    /// ```
    ///
    pub fn warning(&mut self, msg: &str) {
        self.log(Level::WARNING, &self.fn_name(), msg);
    }
}

impl fmt::Display for Logger {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut buf = String::new();

        for elem in self.handlers.borrow().iter() {
            let s = format!("{}: {}\n", elem.0, elem.1);
            buf.push_str(&s);
        }

        writeln!(
            f,
            "{}::{} - [{}]\n\n{}",
            self.mod_path, self.fn_name, self.level, buf
        )
    }
}

#[cfg(test)]
mod tests;

Line	Count	Source (jump to first uncovered line)
1		//
2		// File Name: mod.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		//! # Logger
26		//!
27		//! `Logger` is the work-horse of the crate.
28		//!
29		//! It contains the primary methods to both create a logger instance, and has
30		//! the methods to add log messages at various log levels.
31		//!
32
33		#![allow(clippy::needless_doctest_main)]
34
35		mod builder;
36		mod level;
37		mod log_entry;
38
39		use anyhow::{Context, Error, Result};
40		use std::cell::{LazyCell, RefCell};
41		use std::collections::hash_map::IterMut;
42		use std::collections::{HashMap, HashSet};
43		use std::f32::consts;
44		use std::fs::{File, exists};
45		use std::io::Write;
46		use std::marker::PhantomData;
47		use std::module_path;
48		use std::ops::DerefMut;
49		use std::path::Path;
50		use std::sync::mpsc::Sender;
51		use std::sync::{Arc, MutexGuard, PoisonError, mpsc};
52		use std::thread;
53		use std::{fmt, fs};
54
55		pub use builder::*;
56		pub use level::Level;
57		pub use log_entry::LogEntry;
58
59		use crate::*;
60
61		///
62		/// This is the work-horse, providing the primary methods of the crate.
63		///
64		pub struct Logger {
65		///
66		/// Identify the source of log messages passed to this logger.
67		///
68		/// This would ideally be the mod path.
69		///
70		mod_path: String,
71
72		///
73		/// The name of the function/method inside which the log message
74		/// is generated.
75		///
76		fn_name: String,
77
78		///
79		/// Default level used by `log(msg)`.
80		///
81		level: Level,
82
83		///
84		/// Holds the handlers associated with this logger.
85		///
86		handlers: RefCell<HashMap<Handler, Box<dyn HandlerTrait>>>,
87		}
88
89		impl Logger {
90		///
91		/// Create a new Logger instance.
92		///
93		/// Logging level is set to it's default setting (INFO).
94		///
95		/// No `handlers` are set. Use the various methods of
96		/// [`LoggerBuilder`] to configure the new `Logger`.
97		///
98		/// ## Parameters
99		/// - `mod_path` - The module path. Can be set with: [`module_path!()`]
100		///
101		/// Returns a `LoggerBuilder` for further configuring.
102		///
103		/// ## Examples
104		/// ```
105		/// use flogging::*;
106		///
107		/// let mut log = Logger::builder(module_path!())
108		/// .add_console_handler()
109		/// .build();
110		/// ```
111		///
112	46	pub fn builder(mod_path: &str) -> LoggerBuilder {
113	46	LoggerBuilder::create(mod_path.to_string())
114	46	}
115
116		///
117		/// Log a CONFIG message.
118		///
119		/// If the logger is currently enabled for the CONFIG message level
120		/// then the given message is forwarded to all the registered output
121		/// Handler objects.
122		///
123		/// ## Parameters
124		/// - `msg` - The string message.
125		///
126		/// ## Examples
127		/// ```
128		/// use flogging::*;
129		///
130		/// let mut log = Logger::console_logger(module_path!());
131		/// log.set_level(Level::CONFIG);
132		/// log.config("Some text to store.");
133		/// ```
134		///
135	9	pub fn config(&mut self, msg: &str) {
136	9	self.log(Level::CONFIG, &self.fn_name(), msg);
137	9	}
138
139		///
140		/// Create new Logger instance, with a `ConsoleHandler`, output
141		/// set to: [`std::io::stdout`].
142		///
143		/// Logging level is set to it's default setting (INFO).
144		///
145		/// ## Parameters
146		/// - `mod_path`- The module path. Suggest using [`module_path!()`].
147		///
148		/// Returns a configured `Logger`.
149		///
150		/// ## Examples
151		/// ```
152		/// use flogging::*;
153		///
154		/// let mut log = Logger::console_logger(module_path!());
155		/// log.set_fn_name("main");
156		///
157		/// log.warning("Don't over do it.");
158		/// ```
159		/// Output to stdout:
160		/// ```text
161		/// flogging->main [WARNING] Don't over do it.
162		/// ```
163		///
164	3	pub fn console_logger(mod_path: &str) -> Logger {
165	3	Logger::builder(mod_path).add_console_handler().build()
166	3	}
167
168		///
169		/// Create new Logger instance, with a custom handler.
170		///
171		/// ## Parameters
172		/// - `mod_path`- The module path. Suggest using [`module_path!()`].
173		/// - `label` - Unique label for this custom handler.
174		/// - `custom` - The boxed custom handler.
175		///
176		/// Returns a configured `Logger`.
177		///
178		/// ## Examples
179		/// ```
180		/// use flogging::*;
181		///
182		/// let mut log = Logger::custom_logger(
183		/// module_path!(),
184		/// "MockHandler",
185		/// Box::new(MockHandler::create("Some text").unwrap()),
186		/// );
187		/// log.set_fn_name("main");
188		///
189		/// log.warning("Don't over do it.");
190		/// ```
191		/// [`MockHandler`] doesn't publish anything, as [`publish()`][MockHandler::publish()] is a NoOp method.
192		/// It is used here to make the example work.
193		///
194		/// However, it is expected that _your_ custom handler will do a little more.
195		///
196	2	pub fn custom_logger(mod_path: &str, label: &str, custom: Box<dyn HandlerTrait>) -> Logger {
197	2	Logger::builder(mod_path)
198	2	.add_custom_handler(label, custom)
199	2	.build()
200	2	}
201
202		///
203		/// Create new Logger instance, with a `ConsoleHandler`, output
204		/// set to: [`std::io::stderr`].
205		///
206		/// Logging level is set to it's default setting (INFO).
207		///
208		/// ## Parameters
209		/// - `mod_path`- The module path. Suggest using [`module_path!()`].
210		///
211		/// Returns a configured `Logger`.
212		///
213		/// ## Examples
214		/// ```
215		/// use flogging::*;
216		///
217		/// let mut log = Logger::econsole_logger(module_path!());
218		/// log.set_fn_name("main");
219		///
220		/// log.warning("Don't over do it.");
221		/// ```
222		/// Output to stderr:
223		/// ```text
224		/// flogging->main [WARNING] Don't over do it.
225		/// ```
226		///
227	2	pub fn econsole_logger(mod_path: &str) -> Logger {
228	2	Logger::builder(mod_path).add_econsole_handler().build()
229	2	}
230
231		///
232		/// Log a method entry.
233		///
234		/// This is a convenience method that can be used to log entry to a method.
235		/// A `LogEntry` with message "Entry" and log level FINER, is logged.
236		///
237		/// ## Examples
238		/// ```
239		/// mod my_mod {
240		/// extern crate flogging;
241		/// use flogging::*;
242		/// use std::cell::{LazyCell, RefCell};
243		///
244		/// // Setting up the module level logger.
245		/// const LOGGER: LazyCell<RefCell<Logger>> = LazyCell::new(\|\| {
246		/// RefCell::new({
247		/// Logger::builder(module_path!())
248		/// .add_console_handler()
249		/// .set_level(Level::FINEST)
250		/// .build()
251		/// })
252		/// });
253		///
254		/// pub fn my_func(data: &str) {
255		/// let binding = LOGGER;
256		/// let mut log = binding.borrow_mut();
257		/// log.set_fn_name("my_func");
258		///
259		/// log.entering();
260		/// }
261		/// }
262		///
263		/// fn main() {
264		/// let data = "Some data";
265		/// my_mod::my_func(data);
266		/// }
267		/// ```
268		/// Output:
269		/// ```text
270		/// flogging::my_mod->my_func [FINER ] Entry
271		/// ```
272		///
273	6	pub fn entering(&mut self) {
274	6	self.log(Level::FINER, &self.fn_name(), "Entry");
275	6	}
276
277		///
278		/// Log a method entry.
279		///
280		/// This is a convenience method that can be used to log entry to a method.
281		/// A `LogEntry` with message "Entry" and log level FINER, is logged.
282		///
283		/// ## Parameters
284		/// - `msg` - The string message.
285		///
286		/// ## Examples
287		/// ```
288		/// mod my_mod {
289		/// extern crate flogging;
290		/// use flogging::*;
291		/// use std::cell::{LazyCell, RefCell};
292		///
293		/// // Setting up the module level logger.
294		/// const LOGGER: LazyCell<RefCell<Logger>> = LazyCell::new(\|\| {
295		/// RefCell::new({
296		/// Logger::builder(module_path!())
297		/// .add_console_handler()
298		/// .set_level(Level::FINEST)
299		/// .build()
300		/// })
301		/// });
302		///
303		/// pub fn my_func(data: &str) {
304		/// let binding = LOGGER;
305		/// let mut log = binding.borrow_mut();
306		/// log.set_fn_name("my_func");
307		///
308		/// log.entering_with(&format!("data: \"{data}\""));
309		/// }
310		/// }
311		///
312		/// fn main() {
313		/// let data = "Some data";
314		/// my_mod::my_func(data);
315		/// }
316		/// ```
317		/// Output:
318		/// ```text
319		/// flogging::my_mod->my_func [FINER ] Entry: (data: "Some data")
320		/// ```
321		///
322	3	pub fn entering_with(&mut self, msg: &str) {
323	3	self.log(
324	3	Level::FINER,
325	3	&self.fn_name(),
326	3	&("Entry: (".to_string() + msg + ")"),
327		);
328	3	}
329
330		///
331		/// Log a method return.
332		///
333		/// This is a convenience method that can be used to log returning from a method.
334		/// A `LogEntry` with message "Return" and log level FINER, is logged.
335		///
336		/// ## Examples
337		/// ```
338		/// mod my_mod {
339		/// extern crate flogging;
340		/// use flogging::*;
341		/// use std::cell::{LazyCell, RefCell};
342		///
343		/// // Setting up the module level logger.
344		/// const LOGGER: LazyCell<RefCell<Logger>> = LazyCell::new(\|\| {
345		/// RefCell::new({
346		/// Logger::builder(module_path!())
347		/// .add_console_handler()
348		/// .set_level(Level::FINEST)
349		/// .build()
350		/// })
351		/// });
352		///
353		/// pub fn my_func(data: &str) {
354		/// let binding = LOGGER;
355		/// let mut log = binding.borrow_mut();
356		/// log.set_fn_name("my_func");
357		///
358		/// log.exiting();
359		/// }
360		/// }
361		///
362		/// fn main() {
363		/// let data = "Some data";
364		/// my_mod::my_func(data);
365		/// }
366		/// ```
367		/// Output:
368		/// ```text
369		/// flogging::my_mod->my_func [FINER ] Return
370		/// ```
371		///
372	6	pub fn exiting(&mut self) {
373	6	self.log(Level::FINER, &self.fn_name(), "Return");
374	6	}
375
376		///
377		/// Log a method return.
378		///
379		/// This is a convenience method that can be used to log returning from a method.
380		/// A `LogEntry` with message "Return" and log level FINER, is logged.
381		///
382		/// ## Parameters
383		/// - `msg` - The string message.
384		///
385		/// ## Examples
386		/// ```
387		/// mod my_mod {
388		/// extern crate flogging;
389		/// use flogging::*;
390		/// use std::cell::{LazyCell, RefCell};
391		///
392		/// // Setting up the module level logger.
393		/// const LOGGER: LazyCell<RefCell<Logger>> = LazyCell::new(\|\| {
394		/// RefCell::new({
395		/// Logger::builder(module_path!())
396		/// .add_console_handler()
397		/// .set_level(Level::FINEST)
398		/// .build()
399		/// })
400		/// });
401		///
402		/// pub fn my_func(data: &str) -> bool {
403		/// let binding = LOGGER;
404		/// let mut log = binding.borrow_mut();
405		/// log.set_fn_name("my_func");
406		///
407		/// let rtn = true;
408		/// log.exiting_with(&format!("rtn: {rtn}"));
409		/// rtn
410		/// }
411		/// }
412		///
413		/// fn main() {
414		/// let data = "Some data";
415		/// my_mod::my_func(data);
416		/// }
417		/// ```
418		/// Output:
419		/// ```text
420		/// flogging::my_mod->my_func [FINER ] Return: (rtn: true)
421		/// ```
422		///
423	3	pub fn exiting_with(&mut self, msg: &str) {
424	3	self.log(
425	3	Level::FINER,
426	3	&self.fn_name(),
427	3	&("Return: (".to_string() + msg + ")"),
428		);
429	3	}
430
431		///
432		/// Create new Logger instance, with a `FileHandler`.
433		///
434		/// Logging level is set to it's default setting (INFO).
435		///
436		/// ## Parameters
437		/// - `mod_path`- The module path. Suggest using [`std::module_path`][mp].
438		/// - `filename` - The name of the log file to use. Will be created
439		/// if it doesn't exist.
440		///
441		/// Returns a configured `Logger`.
442		///
443		/// ## Examples
444		/// ```
445		/// use flogging::Logger;
446		///
447		/// let mut log = Logger::file_logger(module_path!(), "test_logs/logger.log");
448		/// log.set_fn_name("main");
449		///
450		/// log.info("Some text to store.");
451		/// ```
452		/// Output:
453		/// ```text
454		/// 2025-07-18T12:14:47.322720683+08:00 flogging->main [INFO ] Some text to store.
455		/// ```
456		///
457		/// [mp]: https://doc.rust-lang.org/std/macro.module_path.html
458	2	pub fn file_logger(mod_path: &str, filename: &str) -> Logger {
459	2	Logger::builder(mod_path).add_file_handler(filename).build()
460	2	}
461
462		///
463		/// Log a FINE message.
464		///
465		/// If the logger is currently enabled for the FINE message level
466		/// then the given message is forwarded to all the registered output
467		/// Handler objects.
468		///
469		/// ## Parameters
470		/// - `msg` - The string message.
471		///
472		/// ## Examples
473		/// ```
474		/// use flogging::*;
475		///
476		/// let mut log = Logger::console_logger(module_path!());
477		/// log.set_level(Level::FINEST);
478		/// log.set_fn_name("main");
479		///
480		/// log.fine("Some text to store.");
481		/// ```
482		/// Output:
483		/// ```text
484		/// flogging->main [FINE ] Some text to store.
485		/// ```
486		///
487	6	pub fn fine(&mut self, msg: &str) {
488	6	self.log(Level::FINE, &self.fn_name(), msg);
489	6	}
490
491		///
492		/// Log a FINER message.
493		///
494		/// If the logger is currently enabled for the FINER message level
495		/// then the given message is forwarded to all the registered output
496		/// Handler objects.
497		///
498		/// ## Parameters
499		/// - `msg` - The string message.
500		///