refactor: move format/with_format from builder to formatter

Author: djugei

examples/custom_format.rs

@@ -19,17 +19,17 @@ If you want to control the logging output completely, see the `custom_logger` ex
 
 #[cfg(all(feature = "color", feature = "humantime"))]
 fn main() {
-    use env_logger::{Builder, Env};
+    use env_logger::{fmt::Formatter, Env, Logger};
+    use log::Record;
 
     use std::io::Write;
 
     fn init_logger() {
         let env = Env::default()
             .filter("MY_LOG_LEVEL")
             .write_style("MY_LOG_STYLE");
-
-        Builder::from_env(env)
-            .format(|buf, record| {
+        Logger::from_env(env)
+            .with_format(Box::new(|buf: &mut Formatter, record: &Record<'_>| {
                 // We are reusing `anstyle` but there are `anstyle-*` crates to adapt it to your
                 // preferred styling crate.
                 let warn_style = buf.default_level_style(log::Level::Warn);
@@ -40,8 +40,9 @@ fn main() {
                     "My formatted log ({timestamp}): {warn_style}{}{warn_style:#}",
                     record.args()
                 )
-            })
-            .init();
+            }))
+            .try_init()
+            .unwrap();
     }
 
     init_logger();

examples/syslog_friendly_format.rs

@@ -1,9 +1,12 @@
 use std::io::Write;
 
+use env_logger::fmt::Formatter;
+use log::Record;
+
 fn main() {
     match std::env::var("RUST_LOG_STYLE") {
-        Ok(s) if s == "SYSTEMD" => env_logger::builder()
-            .format(|buf, record| {
+        Ok(s) if s == "SYSTEMD" => env_logger::Logger::from_default_env()
+            .with_format(Box::new(|buf: &mut Formatter, record: &Record<'_>| {
                 writeln!(
                     buf,
                     "<{}>{}: {}",
@@ -17,8 +20,9 @@ fn main() {
                     record.target(),
                     record.args()
                 )
-            })
-            .init(),
+            }))
+            .try_init()
+            .unwrap(),
         _ => env_logger::init(),
     };
 }

src/fmt/mod.rs

@@ -7,7 +7,7 @@
 //!
 //! # Formatting log records
 //!
-//! The format used to print log records can be customised using the [`Builder::format`]
+//! The format used to print log records can be customised using the [`crate::Logger::with_format`]
 //! method.
 //!
 //! Terminal styling is done through ANSI escape codes and will be adapted to the capabilities of
@@ -53,7 +53,7 @@
 //!
 //! See <https://docs.rs/log/latest/log/#structured-logging>.
 //!
-//! [`Builder::format`]: crate::Builder::format
+//! [`Logger::with_fmt`]: crate::Logger::with_fmt
 //! [`Write`]: std::io::Write
 //! [`Builder::format_key_values`]: crate::Builder::format_key_values
 
@@ -200,7 +200,7 @@ impl fmt::Debug for Formatter {
     }
 }
 
-pub(crate) trait RecordFormat {
+pub trait RecordFormat {
     fn format(&self, formatter: &mut Formatter, record: &Record<'_>) -> io::Result<()>;
 }
 
@@ -217,8 +217,7 @@ pub(crate) type FormatFn = Box<dyn RecordFormat + Sync + Send>;
 
 #[derive(Default)]
 pub(crate) struct Builder {
-    pub(crate) default_format: ConfigurableFormat,
-    pub(crate) custom_format: Option<FormatFn>,
+    pub(crate) format: ConfigurableFormat,
     built: bool,
 }
 
@@ -239,11 +238,7 @@ impl Builder {
             },
         );
 
-        if let Some(fmt) = built.custom_format {
-            fmt
-        } else {
-            Box::new(built.default_format)
-        }
+        Box::new(built.format)
     }
 }
 
@@ -276,7 +271,7 @@ impl<T: Display> Display for StyledValue<T> {
 #[cfg(not(feature = "color"))]
 type StyledValue<T> = T;
 
-/// A [custom format][crate::Builder::format] with settings for which fields to show
+/// A custom format with settings for which fields to show
 pub struct ConfigurableFormat {
     // This format needs to work with any combination of crate features.
     pub(crate) timestamp: Option<TimestampPrecision>,

src/logger.rs

@@ -1,4 +1,4 @@
-use std::{borrow::Cow, cell::RefCell, env, io};
+use std::{borrow::Cow, cell::RefCell, env};
 
 use log::{LevelFilter, Log, Metadata, Record, SetLoggerError};
 
@@ -211,43 +211,6 @@ impl Builder {
         self.parse_env(Env::default())
     }
 
-    /// Sets the format function for formatting the log output.
-    ///
-    /// This function is called on each record logged and should format the
-    /// log record and output it to the given [`Formatter`].
-    ///
-    /// The format function is expected to output the string directly to the
-    /// `Formatter` so that implementations can use the [`std::fmt`] macros
-    /// to format and output without intermediate heap allocations. The default
-    /// `env_logger` formatter takes advantage of this.
-    ///
-    /// When the `color` feature is enabled, styling via ANSI escape codes is supported and the
-    /// output will automatically respect [`Builder::write_style`].
-    ///
-    /// # Examples
-    ///
-    /// Use a custom format to write only the log message:
-    ///
-    /// ```
-    /// use std::io::Write;
-    /// use env_logger::Builder;
-    ///
-    /// let mut builder = Builder::new();
-    ///
-    /// builder.format(|buf, record| writeln!(buf, "{}", record.args()));
-    /// ```
-    ///
-    /// [`Formatter`]: fmt/struct.Formatter.html
-    /// [`String`]: https://doc.rust-lang.org/stable/std/string/struct.String.html
-    /// [`std::fmt`]: https://doc.rust-lang.org/std/fmt/index.html
-    pub fn format<F>(&mut self, format: F) -> &mut Self
-    where
-        F: Fn(&mut Formatter, &Record<'_>) -> io::Result<()> + Sync + Send + 'static,
-    {
-        self.format.custom_format = Some(Box::new(format));
-        self
-    }
-
     /// Use the default format.
     ///
     /// This method will clear any custom format set on the builder.
@@ -258,21 +221,21 @@ impl Builder {
 
     /// Whether or not to write the level in the default format.
     pub fn format_level(&mut self, write: bool) -> &mut Self {
-        self.format.default_format.level(write);
+        self.format.format.level(write);
         self
     }
 
     /// Whether or not to write the source file path in the default format.
     pub fn format_file(&mut self, write: bool) -> &mut Self {
-        self.format.default_format.file(write);
+        self.format.format.file(write);
         self
     }
 
     /// Whether or not to write the source line number path in the default format.
     ///
     /// Only has effect if `format_file` is also enabled
     pub fn format_line_number(&mut self, write: bool) -> &mut Self {
-        self.format.default_format.line_number(write);
+        self.format.format.line_number(write);
         self
     }
 
@@ -287,26 +250,26 @@ impl Builder {
 
     /// Whether or not to write the module path in the default format.
     pub fn format_module_path(&mut self, write: bool) -> &mut Self {
-        self.format.default_format.module_path(write);
+        self.format.format.module_path(write);
         self
     }
 
     /// Whether or not to write the target in the default format.
     pub fn format_target(&mut self, write: bool) -> &mut Self {
-        self.format.default_format.target(write);
+        self.format.format.target(write);
         self
     }
 
     /// Configures the amount of spaces to use to indent multiline log records.
     /// A value of `None` disables any kind of indentation.
     pub fn format_indent(&mut self, indent: Option<usize>) -> &mut Self {
-        self.format.default_format.indent(indent);
+        self.format.format.indent(indent);
         self
     }
 
     /// Configures if timestamp should be included and in what precision.
     pub fn format_timestamp(&mut self, timestamp: Option<fmt::TimestampPrecision>) -> &mut Self {
-        self.format.default_format.timestamp(timestamp);
+        self.format.format.timestamp(timestamp);
         self
     }
 
@@ -332,7 +295,7 @@ impl Builder {
 
     /// Configures the end of line suffix.
     pub fn format_suffix(&mut self, suffix: &'static str) -> &mut Self {
-        self.format.default_format.suffix(suffix);
+        self.format.format.suffix(suffix);
         self
     }
 
@@ -349,9 +312,9 @@ impl Builder {
     #[cfg(feature = "kv")]
     pub fn format_key_values<F>(&mut self, format: F) -> &mut Self
     where
-        F: Fn(&mut Formatter, &dyn log::kv::Source) -> io::Result<()> + Sync + Send + 'static,
+        F: Fn(&mut Formatter, &dyn log::kv::Source) -> std::io::Result<()> + Sync + Send + 'static,
     {
-        self.format.default_format.key_values(format);
+        self.format.format.key_values(format);
         self
     }
 
@@ -497,15 +460,7 @@ impl Builder {
     /// library has already initialized a global logger.
     pub fn try_init(&mut self) -> Result<(), SetLoggerError> {
         let logger = self.build();
-
-        let max_level = logger.filter();
-        let r = log::set_boxed_logger(Box::new(logger));
-
-        if r.is_ok() {
-            log::set_max_level(max_level);
-        }
-
-        r
+        logger.try_init()
     }
 
     /// Initializes the global logger with the built env logger.
@@ -641,6 +596,51 @@ impl Logger {
     pub fn matches(&self, record: &Record<'_>) -> bool {
         self.filter.matches(record)
     }
+
+    /// Sets the format function for formatting the log output.
+    ///
+    /// This function is called on each record logged and should format the
+    /// log record and output it to the given [`Formatter`].
+    ///
+    /// The format function is expected to output the string directly to the
+    /// `Formatter` so that implementations can use the [`std::fmt`] macros
+    /// to format and output without intermediate heap allocations. The default
+    /// `env_logger` formatter takes advantage of this.
+    ///
+    /// When the `color` feature is enabled, styling via ANSI escape codes is supported and the
+    /// output will automatically respect [`Builder::write_style`].
+    ///
+    /// # Examples
+    ///
+    /// Use a custom format to write only the log message:
+    ///
+    /// ```
+    /// use std::io::Write;
+    /// use env_logger::Builder;
+    ///
+    /// let mut builder = Builder::new();
+    ///
+    /// builder.format(|buf, record| writeln!(buf, "{}", record.args()));
+    /// ```
+    ///
+    /// [`Formatter`]: fmt/struct.Formatter.html
+    /// [`String`]: https://doc.rust-lang.org/stable/std/string/struct.String.html
+    /// [`std::fmt`]: https://doc.rust-lang.org/std/fmt/index.html
+    pub fn with_format(mut self, format: FormatFn) -> Self {
+        self.format = format;
+        self
+    }
+
+    pub fn try_init(self) -> Result<(), SetLoggerError> {
+        let max_level = self.filter();
+        let r = log::set_boxed_logger(Box::new(self));
+
+        if r.is_ok() {
+            log::set_max_level(max_level);
+        }
+
+        r
+    }
 }
 
 impl Log for Logger {