refactor: improve api

.github/workflows/ci.yml

@@ -71,10 +71,10 @@ jobs:
         run: cargo test --all-features -- --nocapture
       - name: Run examples
         run: |
-          cargo run --example simple_stdio
-          cargo run --example fn_layout_filter
-          cargo run --example default_filter_respect_env
-          cargo run --features="no-color" --example simple_stdio
+          cargo run --example text_stdio
+          cargo run --example custom_layout_filter
+          cargo run --example env_filter
+          cargo run --features="no-color" --example text_stdio
           cargo run --features="json" --example json_stdio
           cargo run --features="json,rolling_file" --example rolling_file
 

Cargo.toml

@@ -96,8 +96,8 @@ version = "0.26"
 
 ## Examples
 [[example]]
-name = "simple_stdio"
-path = "examples/simple_stdio.rs"
+name = "text_stdio"
+path = "examples/text_stdio.rs"
 
 [[example]]
 name = "json_stdio"
@@ -110,9 +110,9 @@ path = "examples/rolling_file.rs"
 required-features = ["rolling_file", "json"]
 
 [[example]]
-name = "fn_layout_filter"
-path = "examples/fn_layout_filter.rs"
+name = "custom_layout_filter"
+path = "examples/custom_layout_filter.rs"
 
 [[example]]
-name = "default_filter_respect_env"
-path = "examples/default_filter_respect_env.rs"
+name = "env_filter"
+path = "examples/env_filter.rs"

README.md

@@ -46,8 +46,9 @@ use log::LevelFilter;
 use logforth::append;
 
 fn main() {
-    logforth::dispatch(|b| b.filter(LevelFilter::Debug).append(append::Stderr::default()))
-        .and_dispatch(|b| b.filter(LevelFilter::Info).append(append::Stdout::default()))
+    logforth::builder()
+        .dispatch(|d| d.filter(LevelFilter::Debug).append(append::Stderr::default()))
+        .dispatch(|d| d.filter(LevelFilter::Info).append(append::Stdout::default()))
         .apply();
 }
 ```

examples/fn_layout_filter.rs → examples/custom_layout_filter.rs

@@ -19,21 +19,22 @@ use logforth::filter::FilterResult;
 use logforth::layout::CustomLayout;
 
 fn main() {
-    logforth::dispatch(|b| {
-        b.filter(CustomFilter::new(|metadata: &log::Metadata| {
-            if metadata.level() > LevelFilter::Info {
-                FilterResult::Accept
-            } else {
-                FilterResult::Reject
-            }
-        }))
-        .append(
-            append::Stdout::default().with_layout(CustomLayout::new(|record| {
-                Ok(format!("[system alert] {}", record.args()).into_bytes())
-            })),
-        )
-    })
-    .apply();
+    logforth::builder()
+        .dispatch(|d| {
+            d.filter(CustomFilter::new(|metadata: &log::Metadata| {
+                if metadata.level() > LevelFilter::Info {
+                    FilterResult::Accept
+                } else {
+                    FilterResult::Reject
+                }
+            }))
+            .append(
+                append::Stdout::default().with_layout(CustomLayout::new(|record| {
+                    Ok(format!("[system alert] {}", record.args()).into_bytes())
+                })),
+            )
+        })
+        .apply();
 
     log::error!("Hello error!");
     log::warn!("Hello warn!");

examples/json_stdio.rs

@@ -16,7 +16,8 @@ use logforth::append;
 use logforth::layout::JsonLayout;
 
 fn main() {
-    logforth::dispatch(|b| b.append(append::Stdout::default().with_layout(JsonLayout::default())))
+    logforth::builder()
+        .dispatch(|d| d.append(append::Stdout::default().with_layout(JsonLayout::default())))
         .apply();
 
     log::error!("Hello error!");

examples/rolling_file.rs

@@ -30,12 +30,13 @@ fn main() {
         .unwrap();
     let (writer, _guard) = NonBlockingBuilder::default().finish(rolling);
 
-    logforth::dispatch(|b| {
-        b.filter("trace")
-            .append(RollingFile::new(writer).with_layout(JsonLayout::default()))
-    })
-    .and_dispatch(|b| b.filter("info").append(Stdout::default()))
-    .apply();
+    logforth::builder()
+        .dispatch(|d| {
+            d.filter("trace")
+                .append(RollingFile::new(writer).with_layout(JsonLayout::default()))
+        })
+        .dispatch(|d| d.filter("info").append(Stdout::default()))
+        .apply();
 
     let repeat = 1;
 

examples/simple_stdio.rs → examples/text_stdio.rs

@@ -16,12 +16,13 @@ use log::LevelFilter;
 use logforth::append;
 
 fn main() {
-    logforth::dispatch(|b| {
-        b.filter(LevelFilter::Trace)
-            .append(append::Stdout::default())
-            .append(append::Stderr::default())
-    })
-    .apply();
+    logforth::builder()
+        .dispatch(|d| {
+            d.filter(LevelFilter::Trace)
+                .append(append::Stdout::default())
+                .append(append::Stderr::default())
+        })
+        .apply();
 
     log::error!("Hello error!");
     log::warn!("Hello warn!");

src/filter/mod.rs

@@ -19,10 +19,10 @@ use std::str::FromStr;
 use log::LevelFilter;
 
 pub use self::custom::CustomFilter;
-pub use self::env::EnvFilter;
+pub use self::env_filter::EnvFilter;
 
 mod custom;
-pub mod env;
+pub mod env_filter;
 
 /// The result of a filter may return.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]

src/lib.rs

@@ -38,8 +38,9 @@ Or configure the logger in a more fine-grained way:
 use log::LevelFilter;
 use logforth::append;
 
-logforth::dispatch(|b| b.filter(LevelFilter::Debug).append(append::Stderr::default()))
-    .and_dispatch(|b| b.filter(LevelFilter::Info).append(append::Stdout::default()))
+logforth::builder()
+    .dispatch(|d| d.filter(LevelFilter::Debug).append(append::Stderr::default()))
+    .dispatch(|d| d.filter(LevelFilter::Info).append(append::Stdout::default()))
     .apply();
 ```
 

src/logger/builder.rs

@@ -29,11 +29,12 @@ use crate::Filter;
 /// use log::LevelFilter;
 /// use logforth::append;
 ///
-/// logforth::dispatch(|b| {
-///     b.filter(LevelFilter::Info)
-///         .append(append::Stdout::default())
-/// })
-/// .apply();
+/// logforth::builder()
+///     .dispatch(|d| {
+///         d.filter(LevelFilter::Info)
+///             .append(append::Stdout::default())
+///     })
+///     .apply();
 /// ```
 ///
 /// Multiple dispatches can be added:
@@ -42,21 +43,19 @@ use crate::Filter;
 /// use log::LevelFilter;
 /// use logforth::append;
 ///
-/// logforth::dispatch(|b| {
-///     b.filter(LevelFilter::Info)
-///         .append(append::Stdout::default())
-/// })
-/// .and_dispatch(|b| {
-///     b.filter(LevelFilter::Debug)
-///         .append(append::Stderr::default())
-/// })
-/// .apply();
+/// logforth::builder()
+///     .dispatch(|d| {
+///         d.filter(LevelFilter::Info)
+///             .append(append::Stdout::default())
+///     })
+///     .dispatch(|d| {
+///         d.filter(LevelFilter::Debug)
+///             .append(append::Stderr::default())
+///     })
+///     .apply();
 /// ```
-pub fn dispatch<F>(f: F) -> Builder
-where
-    F: FnOnce(DispatchBuilder<false>) -> DispatchBuilder<true>,
-{
-    Builder::dispatch(f)
+pub fn builder() -> Builder {
+    Builder::new()
 }
 
 /// Create a new [`Builder`] with a default [`Stdout`][append::Stdout] append configured, and
@@ -68,8 +67,8 @@ where
 /// logforth::stdout().apply();
 /// ```
 pub fn stdout() -> Builder {
-    dispatch(|b| {
-        b.filter(EnvFilter::from_default_env())
+    crate::builder().dispatch(|d| {
+        d.filter(EnvFilter::from_default_env())
             .append(append::Stdout::default())
     })
 }
@@ -83,13 +82,13 @@ pub fn stdout() -> Builder {
 /// logforth::stderr().apply();
 /// ```
 pub fn stderr() -> Builder {
-    dispatch(|b| {
-        b.filter(EnvFilter::from_default_env())
+    crate::builder().dispatch(|d| {
+        d.filter(EnvFilter::from_default_env())
             .append(append::Stderr::default())
     })
 }
 
-/// A builder for configuring the logger. Always constructed via [`dispatch`] for a fluent API.
+/// A builder for configuring the logger. Always constructed via [`builder`] for a fluent API.
 ///
 /// ## Examples
 ///
@@ -99,11 +98,12 @@ pub fn stderr() -> Builder {
 /// use log::LevelFilter;
 /// use logforth::append;
 ///
-/// logforth::dispatch(|b| {
-///     b.filter(LevelFilter::Info)
-///         .append(append::Stdout::default())
-/// })
-/// .apply();
+/// logforth::builder()
+///     .dispatch(|d| {
+///         d.filter(LevelFilter::Info)
+///             .append(append::Stdout::default())
+///     })
+///     .apply();
 /// ```
 #[must_use = "call `apply` to set the global logger"]
 #[derive(Debug)]
@@ -116,19 +116,15 @@ pub struct Builder {
 }
 
 impl Builder {
-    /// Create a new logger builder with the first dispatch configured by `f`.
-    fn dispatch<F>(f: F) -> Self
-    where
-        F: FnOnce(DispatchBuilder<false>) -> DispatchBuilder<true>,
-    {
-        Self {
-            dispatches: vec![f(DispatchBuilder::new()).build()],
+    fn new() -> Self {
+        Builder {
+            dispatches: vec![],
             max_level: LevelFilter::Trace,
         }
     }
 
-    /// Stage a new dispatch.
-    pub fn and_dispatch<F>(mut self, f: F) -> Self
+    /// Register a new dispatch.
+    pub fn dispatch<F>(mut self, f: F) -> Self
     where
         F: FnOnce(DispatchBuilder<false>) -> DispatchBuilder<true>,
     {
@@ -138,7 +134,7 @@ impl Builder {
 
     /// Set the global maximum log level.
     ///
-    /// This will be passed to [`log::set_max_level`] on [`Builder::finish`].
+    /// This will be passed to [`log::set_max_level`] on [`Builder::apply`].
     pub fn max_level(mut self, max_level: LevelFilter) -> Self {
         self.max_level = max_level;
         self

tests/recursive_logging.rs

@@ -37,9 +37,10 @@ fn test_meta_logging_in_format_works() {
         })
     };
 
-    logforth::dispatch(|b| b.append(append::Stdout::default().with_layout(layout("out"))))
-        .and_dispatch(|b| b.append(append::Stderr::default().with_layout(layout("err"))))
-        .and_dispatch(|b| b.append(append::RollingFile::new(writer).with_layout(layout("file"))))
+    logforth::builder()
+        .dispatch(|d| d.append(append::Stdout::default().with_layout(layout("out"))))
+        .dispatch(|d| d.append(append::Stderr::default().with_layout(layout("err"))))
+        .dispatch(|d| d.append(append::RollingFile::new(writer).with_layout(layout("file"))))
         .apply();
 
     struct Thing<'a>(&'a str);