src/logger/builder.rs

Lines

100.00 %

Functions

100.00 %

Regions

99.36 %


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

//!
//! # LoggerBuilder
//!

use crate::*;
use std::{cell::RefCell, collections::HashMap, fs};

///
/// Used by [`Logger`] to provide more flexibility in the configuration of the
/// final logger.
///
pub struct LoggerBuilder {
    mod_path: String,
    fn_name: String,
    level: Level,
    handlers: RefCell<HashMap<Handler, Box<dyn HandlerTrait>>>,
}

impl LoggerBuilder {
    pub(super) fn create(mod_path: String) -> Self {
        LoggerBuilder {
            mod_path,
            fn_name: String::new(),
            level: Level::default(),
            handlers: RefCell::new(HashMap::new()),
        }
    }

    ///
    /// Adds a [`ConsoleHandler`] with the default formatter,
    /// with output according to: [`ConsoleType::StdOut`].
    ///
    /// ## Examples
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_console_handler()
    ///     .build();
    /// ```
    ///
    pub fn add_console_handler(self) -> Self {
        self.add_handler_with(Handler::Console, None, None, None, None)
    }

    ///
    /// Adds a [`ConsoleHandler`] with the required formatter,
    /// with output according to: [`ConsoleType::StdOut`].
    ///
    /// ## Parameters
    /// - `format_type` - The format type used to produce the required formatter.
    /// - `custom_formatter` - The optional boxed custom formatter.
    ///   Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
    ///
    /// ## Examples
    /// First, using a provided formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_console_handler_with(FormatType::Iso8601, None)
    ///     .build();
    /// ```
    /// Now using a custom formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_console_handler_with(
    ///         FormatType::Custom,
    ///         Some(Box::new(MockFormatter::new())),
    ///     )
    ///     .build();
    /// ```
    ///
    pub fn add_console_handler_with(
        self,
        format_type: FormatType,
        custom_formatter: Option<Box<dyn FormatTrait>>,
    ) -> Self {
        self.add_handler_with(
            Handler::Console,
            None,
            None,
            Some(format_type),
            custom_formatter,
        )
    }

    ///
    /// Adds a [`ConsoleHandler`] with the default formatter,
    /// with output according to: [`ConsoleType::StdErr`].
    ///
    /// ## Examples
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_econsole_handler()
    ///     .build();
    /// ```
    ///
    pub fn add_econsole_handler(self) -> Self {
        self.add_handler_with(Handler::EConsole, None, None, None, None)
    }

    ///
    /// Adds a [`ConsoleHandler`] with the required formatter,
    /// with output according to: [`ConsoleType::StdErr`].
    ///
    /// ## Parameters
    /// - `format_type` - The format type used to produce the required formatter.
    /// - `custom_formatter` - The optional boxed custom formatter.
    ///   Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
    ///
    /// ## Examples
    /// First, using a provided formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_econsole_handler_with(FormatType::Iso8601, None)
    ///     .build();
    /// ```
    /// Now using a custom formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_econsole_handler_with(
    ///         FormatType::Custom,
    ///         Some(Box::new(MockFormatter::new())),
    ///     )
    ///     .build();
    /// ```
    ///
    pub fn add_econsole_handler_with(
        self,
        format_type: FormatType,
        custom_formatter: Option<Box<dyn FormatTrait>>,
    ) -> Self {
        self.add_handler_with(
            Handler::EConsole,
            None,
            None,
            Some(format_type),
            custom_formatter,
        )
    }

    ///
    /// Adds a custom handler with the default formatter.
    ///
    /// ## Parameters
    /// - `label` - Unique identifier for this custom handler. Used when attempting to
    ///   retrieve this handler: [`has_handler()`][Logger::has_handler], [`get_handler()`][Logger::get_handler]
    /// - `custom_handler` - The boxed custom handler.
    ///
    /// ## Examples
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_custom_handler(
    ///         "MockHandler",
    ///         Box::new(MockHandler::create("What ever you need").unwrap()),
    ///     )
    ///     .build();
    /// ```
    ///
    pub fn add_custom_handler(self, label: &str, custom_handler: Box<dyn HandlerTrait>) -> Self {
        self.add_handler_with(
            Handler::Custom(label.to_string()),
            Some(custom_handler),
            None,
            None,
            None,
        )
    }

    ///
    /// Adds a custom handler with the required formatter.
    ///
    /// ## Parameters
    /// - `label` - Unique identifier for this custom handler. Used when attempting to
    ///   retrieve this handler: [`has_handler()`][Logger::has_handler], [`get_handler()`][Logger::get_handler]
    /// - `custom_handler` - The boxed custom handler.
    /// - `format_type` - The format type used to produce the required formatter.
    /// - `custom_formatter` - The optional boxed custom formatter.
    ///   Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
    ///
    /// ## Examples
    /// First, using a provided formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_custom_handler_with(
    ///         "MockHandler",
    ///         Box::new(MockHandler::create("What ever you need").unwrap()),
    ///         FormatType::Simple,
    ///         None,
    ///     )
    ///     .build();
    /// ```
    /// Now using a custom formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_custom_handler_with(
    ///         "MockHandler",
    ///         Box::new(MockHandler::create("What ever you need").unwrap()),
    ///         FormatType::Custom,
    ///         Some(Box::new(MockFormatter::new())),
    ///     )
    ///     .build();
    /// ```
    ///
    pub fn add_custom_handler_with(
        self,
        label: &str,
        custom_handler: Box<dyn HandlerTrait>,
        format_type: FormatType,
        custom_formatter: Option<Box<dyn FormatTrait>>,
    ) -> Self {
        self.add_handler_with(
            Handler::Custom(label.to_string()),
            Some(custom_handler),
            None,
            Some(format_type),
            custom_formatter,
        )
    }

    ///
    /// Adds a [`FileHandler`] with the default formatter.
    ///
    /// ## Parameters
    ///
    /// - `filename` - The name of the output log file. Must include any relevant
    ///   path (relative or absolute).
    ///
    /// ## Examples
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_file_handler("test_logs/builder.log")
    ///     .build();
    /// ```
    ///
    pub fn add_file_handler(self, filename: &str) -> Self {
        self.add_handler_with(Handler::File, None, Some(filename), None, None)
    }

    ///
    /// Adds a [`FileHandler`] with the required formatter.
    ///
    /// ## Parameters
    /// - `filename` - The name of the output log file. Must include any relevant
    ///   path (relative or absolute).
    /// - `format_type` - The format type used to produce the required formatter.
    /// - `custom_formatter` - The optional boxed custom formatter.
    ///   Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
    ///
    /// ## Examples
    /// First, using a provided formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_file_handler_with("test_logs/builder.log", FormatType::Iso8601, None)
    ///     .build();
    /// ```
    /// Now using a custom formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_file_handler_with(
    ///         "test_logs/builder.log",
    ///         FormatType::Custom,
    ///         Some(Box::new(MockFormatter::new())),
    ///     )
    ///     .build();
    /// ```
    ///
    pub fn add_file_handler_with(
        self,
        filename: &str,
        format_type: FormatType,
        custom_formatter: Option<Box<dyn FormatTrait>>,
    ) -> Self {
        self.add_handler_with(
            Handler::File,
            None,
            Some(filename),
            Some(format_type),
            custom_formatter,
        )
    }

    fn add_handler_with(
        mut self,
        handler: Handler,
        custom_handler: Option<Box<dyn HandlerTrait>>,
        filename: Option<&str>,
        format_type: Option<FormatType>,
        custom_formatter: Option<Box<dyn FormatTrait>>,
    ) -> Self {
        let name = filename.unwrap_or(&self.mod_path);
        let mut h: Box<dyn HandlerTrait> = match handler {
            Handler::Console => {
                Box::new(ConsoleHandler::create(ConsoleType::StdOut.as_str()).unwrap())
            }
            Handler::EConsole => {
                Box::new(ConsoleHandler::create(ConsoleType::StdErr.as_str()).unwrap())
            }
            Handler::File => Box::new(FileHandler::create(name).unwrap()),
            Handler::PConsole => {
                Box::new(ConsoleHandler::create(ConsoleType::Production.as_str()).unwrap())
            }
            Handler::String => Box::new(StringHandler::create(name).unwrap()),
            Handler::Custom(_) => custom_handler.unwrap(),
        };

        if let Some(f) = format_type {
            h.set_formatter(match f {
                FormatType::Iso8601 => f.create(None),
                FormatType::Simple => f.create(None),
                FormatType::UnixTimestamp => f.create(None),
                FormatType::Custom => f.create(custom_formatter),
            });
        }

        let map = self.handlers.get_mut();
        map.insert(handler, h);

        self
    }

    ///
    /// Adds a [`ConsoleHandler`] with the default formatter,
    /// with output according to: [`ConsoleType::Production`].
    ///
    /// ## Examples
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_pconsole_handler()
    ///     .build();
    /// ```
    ///
    pub fn add_pconsole_handler(self) -> Self {
        self.add_handler_with(Handler::PConsole, None, None, None, None)
    }

    ///
    /// Adds a [`ConsoleHandler`] with the required formatter,
    /// with output according to: [`ConsoleType::Production`].
    ///
    /// ## Parameters
    /// - `format_type` - The format type used to produce the required formatter.
    /// - `custom_formatter` - The optional boxed custom formatter.
    ///   Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
    ///
    /// ## Examples
    /// First, using a provided formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_pconsole_handler_with(FormatType::Iso8601, None)
    ///     .build();
    /// ```
    /// Now using a custom formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_pconsole_handler_with(
    ///         FormatType::Custom,
    ///         Some(Box::new(MockFormatter::new())),
    ///     )
    ///     .build();
    /// ```
    ///
    pub fn add_pconsole_handler_with(
        self,
        format_type: FormatType,
        custom_formatter: Option<Box<dyn FormatTrait>>,
    ) -> Self {
        self.add_handler_with(
            Handler::PConsole,
            None,
            None,
            Some(format_type),
            custom_formatter,
        )
    }

    ///
    /// Adds a [`StringHandler`] with the default formatter.
    ///
    /// ## Examples
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_string_handler()
    ///     .build();
    /// ```
    ///
    pub fn add_string_handler(self) -> Self {
        self.add_handler_with(Handler::String, None, None, None, None)
    }

    ///
    /// Adds a [`StringHandler`] with the required formatter.
    ///
    /// ## Parameters
    /// - `format_type` - The format type used to produce the required formatter.
    /// - `custom_formatter` - The optional boxed custom formatter.
    ///   Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
    ///
    /// ## Examples
    /// First, using a provided formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_string_handler_with(FormatType::Iso8601, None)
    ///     .build();
    /// ```
    /// Now using a custom formatter:
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_string_handler_with(
    ///         FormatType::Custom,
    ///         Some(Box::new(MockFormatter::new())),
    ///     )
    ///     .build();
    /// ```
    ///
    pub fn add_string_handler_with(
        self,
        format_type: FormatType,
        custom_formatter: Option<Box<dyn FormatTrait>>,
    ) -> Self {
        self.add_handler_with(
            Handler::String,
            None,
            None,
            Some(format_type),
            custom_formatter,
        )
    }

    ///
    /// Complete the build process and produce the final [`Logger`] instance.
    ///
    /// ## Examples
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_console_handler()
    ///     .build();
    /// ```
    ///
    pub fn build(self) -> Logger {
        Logger {
            mod_path: self.mod_path.clone(),
            fn_name: self.fn_name.clone(),
            level: self.level,
            handlers: self.handlers,
        }
    }

    ///
    /// 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
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .remove_file("test_logs/builder.log")
    ///     .add_file_handler("test_logs/builder.log")
    ///     .build();
    /// ```
    ///
    pub fn remove_file(self, filename: &str) -> Self {
        let _ = fs::remove_file(filename).is_err();
        self
    }

    ///
    /// 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) -> Self {
        self.fn_name = fn_name.to_string();
        self
    }

    ///
    /// Set the logging level for the [`Logger`] instance being configured.
    ///
    /// ## Parameters
    /// - `level` - The new level to set.
    ///
    /// ## Examples
    /// ```
    /// extern crate flogging;
    /// use flogging::*;
    ///
    /// let mut log = Logger::builder(module_path!())
    ///     .add_console_handler()
    ///     .set_level(Level::ALL)
    ///     .build();
    /// ```
    ///
    pub fn set_level(mut self, level: Level) -> Self {
        self.level = level;
        self
    }
}

#[cfg(test)]
mod tests {
    use crate::*;
    use regex::Regex;
    use std::io::{Result, Stdout, Write, stdout};

    #[test]
    fn temp() -> Result<()> {
        let msg = "arguments";
        let mut w = stdout();
        writeln!(&mut w)?;
        writeln!(&mut w, "test")?;
        writeln!(&mut w, "formatted {}", msg)?;

        // assert_eq!(&w[..], "\ntest\nformatted arguments\n".as_bytes());
        Ok(())
    }
    #[test]
    fn add_console_handler() {
        let expected = "flogging::logger::builder::tests->add_console_handler [INFO   ] We begin!
flogging::logger::builder::tests->add_console_handler [WARNING] Need more tests.
"
        .to_string();

        let mut log = Logger::builder(module_path!())
            .add_console_handler()
            .set_fn_name("add_console_handler")
            .build();

        let h = log.get_handler(crate::Handler::Console).unwrap();
        h.set_test_mode(true);

        log.info("We begin!");
        log.warning("Need more tests.");

        let h = log.get_handler(crate::Handler::Console).unwrap();
        let buf = h.get_log();
        assert_eq!(expected, buf);
    }

    #[test]
    fn add_console_handler_with() {
        let re_str =
"^(?:\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{9}\\+\\d{2}:\\d{2}) flogging::logger::builder::tests->add_console_handler_with \\[INFO   ] We begin!
(?:\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{9}\\+\\d{2}:\\d{2}) flogging::logger::builder::tests->add_console_handler_with \\[WARNING] Need more tests.
$";

        let re = Regex::new(re_str).unwrap();

        let mut log = Logger::builder(module_path!())
            .add_console_handler_with(FormatType::Iso8601, None)
            .set_fn_name("add_console_handler_with")
            .build();

        let h = log.get_handler(crate::Handler::Console).unwrap();
        h.set_test_mode(true);

        log.info("We begin!");
        log.warning("Need more tests.");

        let h = log.get_handler(crate::Handler::Console).unwrap();
        let result = h.get_log();
        println!("{result}");

        assert!(re.is_match(&result));
    }

    #[test]
    fn add_econsole_handler() {
        let mut log = Logger::builder(module_path!())
            .add_econsole_handler()
            .set_fn_name("add_econsole_handler")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_econsole_handler_with() {
        let mut log = Logger::builder(module_path!())
            .add_econsole_handler_with(FormatType::Iso8601, None)
            .set_fn_name("add_econsole_handler_with")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_custom_handler() {
        let mut log = Logger::builder(module_path!())
            .add_custom_handler(
                "Console",
                Box::new(ConsoleHandler::create(ConsoleType::StdOut.as_str()).unwrap()),
            )
            .set_fn_name("add_custom_handler")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_custom_handler_with() {
        let mut log = Logger::builder(module_path!())
            .add_custom_handler_with(
                "Console",
                Box::new(ConsoleHandler::create(ConsoleType::StdOut.as_str()).unwrap()),
                FormatType::Custom,
                Some(Box::new(MockFormatter::new())),
            )
            .set_fn_name("add_custom_handler_with")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_file_handler() {
        let mut log = Logger::builder(module_path!())
            .add_file_handler("test_logs/add_file_handler.log")
            .set_fn_name("add_file_handler")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_file_handler_with() {
        let mut log = Logger::builder(module_path!())
            .add_file_handler_with(
                "test_logs/add_file_handler_with.log",
                crate::FormatType::UnixTimestamp,
                None,
            )
            .set_fn_name("add_file_handler_with")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_pconsole_handler() {
        let mut log = Logger::builder(module_path!())
            .add_pconsole_handler()
            .set_fn_name("add_pconsole_handler")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_pconsole_handler_with() {
        let mut log = Logger::builder(module_path!())
            .add_pconsole_handler_with(FormatType::Iso8601, None)
            .set_fn_name("add_pconsole_handler_with")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_string_handler() {
        let mut log = Logger::builder(module_path!())
            .add_string_handler()
            .set_fn_name("add_string_handler")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn add_string_handler_with() {
        let mut log = Logger::builder(module_path!())
            .add_string_handler_with(crate::FormatType::Simple, None)
            .set_fn_name("add_string_handler_with")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }

    #[test]
    fn remove_file() {
        let mut log = Logger::builder(module_path!())
            .remove_file("test_logs/remove_file.log")
            .add_file_handler("test_logs/remove_file.log")
            .set_fn_name("add_file_handler")
            .build();

        log.info("We begin!");
        log.warning("Need more tests.");
    }
}

Line	Count	Source (jump to first uncovered line)
1		//
2		// File Name: builder.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		//! # LoggerBuilder
26		//!
27
28		use crate::*;
29		use std::{cell::RefCell, collections::HashMap, fs};
30
31		///
32		/// Used by [`Logger`] to provide more flexibility in the configuration of the
33		/// final logger.
34		///
35		pub struct LoggerBuilder {
36		mod_path: String,
37		fn_name: String,
38		level: Level,
39		handlers: RefCell<HashMap<Handler, Box<dyn HandlerTrait>>>,
40		}
41
42		impl LoggerBuilder {
43	46	pub(super) fn create(mod_path: String) -> Self {
44	46	LoggerBuilder {
45	46	mod_path,
46	46	fn_name: String::new(),
47	46	level: Level::default(),
48	46	handlers: RefCell::new(HashMap::new()),
49	46	}
50	46	}
51
52		///
53		/// Adds a [`ConsoleHandler`] with the default formatter,
54		/// with output according to: [`ConsoleType::StdOut`].
55		///
56		/// ## Examples
57		/// ```
58		/// extern crate flogging;
59		/// use flogging::*;
60		///
61		/// let mut log = Logger::builder(module_path!())
62		/// .add_console_handler()
63		/// .build();
64		/// ```
65		///
66	16	pub fn add_console_handler(self) -> Self {
67	16	self.add_handler_with(Handler::Console, None, None, None, None)
68	16	}
69
70		///
71		/// Adds a [`ConsoleHandler`] with the required formatter,
72		/// with output according to: [`ConsoleType::StdOut`].
73		///
74		/// ## Parameters
75		/// - `format_type` - The format type used to produce the required formatter.
76		/// - `custom_formatter` - The optional boxed custom formatter.
77		/// Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
78		///
79		/// ## Examples
80		/// First, using a provided formatter:
81		/// ```
82		/// extern crate flogging;
83		/// use flogging::*;
84		///
85		/// let mut log = Logger::builder(module_path!())
86		/// .add_console_handler_with(FormatType::Iso8601, None)
87		/// .build();
88		/// ```
89		/// Now using a custom formatter:
90		/// ```
91		/// extern crate flogging;
92		/// use flogging::*;
93		///
94		/// let mut log = Logger::builder(module_path!())
95		/// .add_console_handler_with(
96		/// FormatType::Custom,
97		/// Some(Box::new(MockFormatter::new())),
98		/// )
99		/// .build();
100		/// ```
101		///
102	2	pub fn add_console_handler_with(
103	2	self,
104	2	format_type: FormatType,
105	2	custom_formatter: Option<Box<dyn FormatTrait>>,
106	2	) -> Self {
107	2	self.add_handler_with(
108	2	Handler::Console,
109	2	None,
110	2	None,
111	2	Some(format_type),
112	2	custom_formatter,
113		)
114	2	}
115
116		///
117		/// Adds a [`ConsoleHandler`] with the default formatter,
118		/// with output according to: [`ConsoleType::StdErr`].
119		///
120		/// ## Examples
121		/// ```
122		/// extern crate flogging;
123		/// use flogging::*;
124		///
125		/// let mut log = Logger::builder(module_path!())
126		/// .add_econsole_handler()
127		/// .build();
128		/// ```
129		///
130	4	pub fn add_econsole_handler(self) -> Self {
131	4	self.add_handler_with(Handler::EConsole, None, None, None, None)
132	4	}
133
134		///
135		/// Adds a [`ConsoleHandler`] with the required formatter,
136		/// with output according to: [`ConsoleType::StdErr`].
137		///
138		/// ## Parameters
139		/// - `format_type` - The format type used to produce the required formatter.
140		/// - `custom_formatter` - The optional boxed custom formatter.
141		/// Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
142		///
143		/// ## Examples
144		/// First, using a provided formatter:
145		/// ```
146		/// extern crate flogging;
147		/// use flogging::*;
148		///
149		/// let mut log = Logger::builder(module_path!())
150		/// .add_econsole_handler_with(FormatType::Iso8601, None)
151		/// .build();
152		/// ```
153		/// Now using a custom formatter:
154		/// ```
155		/// extern crate flogging;
156		/// use flogging::*;
157		///
158		/// let mut log = Logger::builder(module_path!())
159		/// .add_econsole_handler_with(
160		/// FormatType::Custom,
161		/// Some(Box::new(MockFormatter::new())),
162		/// )
163		/// .build();
164		/// ```
165		///
166	2	pub fn add_econsole_handler_with(
167	2	self,
168	2	format_type: FormatType,
169	2	custom_formatter: Option<Box<dyn FormatTrait>>,
170	2	) -> Self {
171	2	self.add_handler_with(
172	2	Handler::EConsole,
173	2	None,
174	2	None,
175	2	Some(format_type),
176	2	custom_formatter,
177		)
178	2	}
179
180		///
181		/// Adds a custom handler with the default formatter.
182		///
183		/// ## Parameters
184		/// - `label` - Unique identifier for this custom handler. Used when attempting to
185		/// retrieve this handler: [`has_handler()`][Logger::has_handler], [`get_handler()`][Logger::get_handler]
186		/// - `custom_handler` - The boxed custom handler.
187		///
188		/// ## Examples
189		/// ```
190		/// extern crate flogging;
191		/// use flogging::*;
192		///
193		/// let mut log = Logger::builder(module_path!())
194		/// .add_custom_handler(
195		/// "MockHandler",
196		/// Box::new(MockHandler::create("What ever you need").unwrap()),
197		/// )
198		/// .build();
199		/// ```
200		///
201	3	pub fn add_custom_handler(self, label: &str, custom_handler: Box<dyn HandlerTrait>) -> Self {
202	3	self.add_handler_with(
203	3	Handler::Custom(label.to_string()),
204	3	Some(custom_handler),
205	3	None,
206	3	None,
207	3	None,
208		)
209	3	}
210
211		///
212		/// Adds a custom handler with the required formatter.
213		///
214		/// ## Parameters
215		/// - `label` - Unique identifier for this custom handler. Used when attempting to
216		/// retrieve this handler: [`has_handler()`][Logger::has_handler], [`get_handler()`][Logger::get_handler]
217		/// - `custom_handler` - The boxed custom handler.
218		/// - `format_type` - The format type used to produce the required formatter.
219		/// - `custom_formatter` - The optional boxed custom formatter.
220		/// Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
221		///
222		/// ## Examples
223		/// First, using a provided formatter:
224		/// ```
225		/// extern crate flogging;
226		/// use flogging::*;
227		///
228		/// let mut log = Logger::builder(module_path!())
229		/// .add_custom_handler_with(
230		/// "MockHandler",
231		/// Box::new(MockHandler::create("What ever you need").unwrap()),
232		/// FormatType::Simple,
233		/// None,
234		/// )
235		/// .build();
236		/// ```
237		/// Now using a custom formatter:
238		/// ```
239		/// extern crate flogging;
240		/// use flogging::*;
241		///
242		/// let mut log = Logger::builder(module_path!())
243		/// .add_custom_handler_with(
244		/// "MockHandler",
245		/// Box::new(MockHandler::create("What ever you need").unwrap()),
246		/// FormatType::Custom,
247		/// Some(Box::new(MockFormatter::new())),
248		/// )
249		/// .build();
250		/// ```
251		///
252	2	pub fn add_custom_handler_with(
253	2	self,
254	2	label: &str,
255	2	custom_handler: Box<dyn HandlerTrait>,
256	2	format_type: FormatType,
257	2	custom_formatter: Option<Box<dyn FormatTrait>>,
258	2	) -> Self {
259	2	self.add_handler_with(
260	2	Handler::Custom(label.to_string()),
261	2	Some(custom_handler),
262	2	None,
263	2	Some(format_type),
264	2	custom_formatter,
265		)
266	2	}
267
268		///
269		/// Adds a [`FileHandler`] with the default formatter.
270		///
271		/// ## Parameters
272		///
273		/// - `filename` - The name of the output log file. Must include any relevant
274		/// path (relative or absolute).
275		///
276		/// ## Examples
277		/// ```
278		/// extern crate flogging;
279		/// use flogging::*;
280		///
281		/// let mut log = Logger::builder(module_path!())
282		/// .add_file_handler("test_logs/builder.log")
283		/// .build();
284		/// ```
285		///
286	17	pub fn add_file_handler(self, filename: &str) -> Self {
287	17	self.add_handler_with(Handler::File, None, Some(filename), None, None)
288	17	}
289
290		///
291		/// Adds a [`FileHandler`] with the required formatter.
292		///
293		/// ## Parameters
294		/// - `filename` - The name of the output log file. Must include any relevant
295		/// path (relative or absolute).
296		/// - `format_type` - The format type used to produce the required formatter.
297		/// - `custom_formatter` - The optional boxed custom formatter.
298		/// Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
299		///
300		/// ## Examples
301		/// First, using a provided formatter:
302		/// ```
303		/// extern crate flogging;
304		/// use flogging::*;
305		///
306		/// let mut log = Logger::builder(module_path!())
307		/// .add_file_handler_with("test_logs/builder.log", FormatType::Iso8601, None)
308		/// .build();
309		/// ```
310		/// Now using a custom formatter:
311		/// ```
312		/// extern crate flogging;
313		/// use flogging::*;
314		///
315		/// let mut log = Logger::builder(module_path!())
316		/// .add_file_handler_with(
317		/// "test_logs/builder.log",
318		/// FormatType::Custom,
319		/// Some(Box::new(MockFormatter::new())),
320		/// )
321		/// .build();
322		/// ```
323		///
324	3	pub fn add_file_handler_with(
325	3	self,
326	3	filename: &str,
327	3	format_type: FormatType,
328	3	custom_formatter: Option<Box<dyn FormatTrait>>,
329	3	) -> Self {
330	3	self.add_handler_with(
331	3	Handler::File,
332	3	None,
333	3	Some(filename),
334	3	Some(format_type),
335	3	custom_formatter,
336		)
337	3	}
338
339	65	fn add_handler_with(
340	65	mut self,
341	65	handler: Handler,
342	65	custom_handler: Option<Box<dyn HandlerTrait>>,
343	65	filename: Option<&str>,
344	65	format_type: Option<FormatType>,
345	65	custom_formatter: Option<Box<dyn FormatTrait>>,
346	65	) -> Self {
347	65	let name = filename.unwrap_or(&self.mod_path);
348	65	let mut h: Box<dyn HandlerTrait> = match handler {
349		Handler::Console => {
350	18	Box::new(ConsoleHandler::create(ConsoleType::StdOut.as_str()).unwrap())
351		}
352		Handler::EConsole => {
353	6	Box::new(ConsoleHandler::create(ConsoleType::StdErr.as_str()).unwrap())
354		}
355	20	Handler::File => Box::new(FileHandler::create(name).unwrap()),
356		Handler::PConsole => {
357	4	Box::new(ConsoleHandler::create(ConsoleType::Production.as_str()).unwrap())
358		}
359	12	Handler::String => Box::new(StringHandler::create(name).unwrap()),
360	5	Handler::Custom(_) => custom_handler.unwrap(),
361		};
362
363	65	if let Some(f) = format_type {
364	12	h.set_formatter(match f {
365	5	FormatType::Iso8601 => f.create(None),
366	3	FormatType::Simple => f.create(None),
367	1	FormatType::UnixTimestamp => f.create(None),
368	3	FormatType::Custom => f.create(custom_formatter),
369		});
370	53	}
371
372	65	let map = self.handlers.get_mut();
373	65	map.insert(handler, h);
374
375	65	self
376	65	}
377
378		///
379		/// Adds a [`ConsoleHandler`] with the default formatter,
380		/// with output according to: [`ConsoleType::Production`].
381		///
382		/// ## Examples
383		/// ```
384		/// extern crate flogging;
385		/// use flogging::*;
386		///
387		/// let mut log = Logger::builder(module_path!())
388		/// .add_pconsole_handler()
389		/// .build();
390		/// ```
391		///
392	3	pub fn add_pconsole_handler(self) -> Self {
393	3	self.add_handler_with(Handler::PConsole, None, None, None, None)
394	3	}
395
396		///
397		/// Adds a [`ConsoleHandler`] with the required formatter,
398		/// with output according to: [`ConsoleType::Production`].
399		///
400		/// ## Parameters
401		/// - `format_type` - The format type used to produce the required formatter.
402		/// - `custom_formatter` - The optional boxed custom formatter.
403		/// Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
404		///
405		/// ## Examples
406		/// First, using a provided formatter:
407		/// ```
408		/// extern crate flogging;
409		/// use flogging::*;
410		///
411		/// let mut log = Logger::builder(module_path!())
412		/// .add_pconsole_handler_with(FormatType::Iso8601, None)
413		/// .build();
414		/// ```
415		/// Now using a custom formatter:
416		/// ```
417		/// extern crate flogging;
418		/// use flogging::*;
419		///
420		/// let mut log = Logger::builder(module_path!())
421		/// .add_pconsole_handler_with(
422		/// FormatType::Custom,
423		/// Some(Box::new(MockFormatter::new())),
424		/// )
425		/// .build();
426		/// ```
427		///
428	1	pub fn add_pconsole_handler_with(
429	1	self,
430	1	format_type: FormatType,
431	1	custom_formatter: Option<Box<dyn FormatTrait>>,
432	1	) -> Self {
433	1	self.add_handler_with(
434	1	Handler::PConsole,
435	1	None,
436	1	None,
437	1	Some(format_type),
438	1	custom_formatter,
439		)
440	1	}
441
442		///
443		/// Adds a [`StringHandler`] with the default formatter.
444		///
445		/// ## Examples
446		/// ```
447		/// extern crate flogging;
448		/// use flogging::*;
449		///
450		/// let mut log = Logger::builder(module_path!())
451		/// .add_string_handler()
452		/// .build();
453		/// ```
454		///
455	11	pub fn add_string_handler(self) -> Self {
456	11	self.add_handler_with(Handler::String, None, None, None, None)
457	11	}
458
459		///
460		/// Adds a [`StringHandler`] with the required formatter.
461		///
462		/// ## Parameters
463		/// - `format_type` - The format type used to produce the required formatter.
464		/// - `custom_formatter` - The optional boxed custom formatter.
465		/// Used by the [`FormatType::Custom`] to produce a [`Formatter::Custom`].
466		///
467		/// ## Examples
468		/// First, using a provided formatter:
469		/// ```
470		/// extern crate flogging;
471		/// use flogging::*;
472		///
473		/// let mut log = Logger::builder(module_path!())
474		/// .add_string_handler_with(FormatType::Iso8601, None)
475		/// .build();
476		/// ```
477		/// Now using a custom formatter:
478		/// ```
479		/// extern crate flogging;
480		/// use flogging::*;
481		///
482		/// let mut log = Logger::builder(module_path!())
483		/// .add_string_handler_with(
484		/// FormatType::Custom,
485		/// Some(Box::new(MockFormatter::new())),
486		/// )
487		/// .build();
488		/// ```
489		///
490	1	pub fn add_string_handler_with(
491	1	self,
492	1	format_type: FormatType,
493	1	custom_formatter: Option<Box<dyn FormatTrait>>,
494	1	) -> Self {
495	1	self.add_handler_with(
496	1	Handler::String,
497	1	None,
498	1	None,
499	1	Some(format_type),
500	1	custom_formatter,