feat: provide fluent builder API (#67)

Signed-off-by: tison <wander4096@gmail.com>

.github/workflows/ci.yml

@@ -57,10 +57,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        # Ensure both MSRV and stable work
-        rust-version:
-          - "1.75.0"
-          - stable
+        rust-version: [ "1.75.0", "stable" ]
     steps:
       - uses: actions/checkout@v4
       - uses: Swatinem/rust-cache@v2

README.md

@@ -31,29 +31,25 @@ cargo add logforth
 
 ... where [log](https://crates.io/crates/log) is the logging facade and [logforth](https://crates.io/crates/logforth) is the logging implementation.
 
-Then, you can use the logger with:
+Then, you can use the logger with the simplest default setup:
 
 ```rust
-use log::LevelFilter;
-use logforth::append;
-use logforth::layout::TextLayout;
-use logforth::Dispatch;
-use logforth::Logger;
+fn main() {
+    logforth::stderr().finish();
+}
+```
 
+Or configure the logger in a more fine-grained way:
+
+```rust
 fn main() {
-    Logger::new().dispatch(
-        Dispatch::new()
-            .filter(LevelFilter::Trace)
-            .append(append::Stdout::default()),
-        )
-        .apply()
-        .unwrap();
-
-    log::error!("Hello error!");
-    log::warn!("Hello warn!");
-    log::info!("Hello info!");
-    log::debug!("Hello debug!");
-    log::trace!("Hello trace!");
+    logforth::builder()
+        .filter(log::LevelFilter::Debug)
+        .append(logforth::append::Stderr::default())
+        .dispatch()
+        .filter(log::LevelFilter::Info)
+        .append(logforth::append::Stdout::default())
+        .finish();
 }
 ```
 

examples/env_filter.rs

@@ -14,18 +14,12 @@
 
 use logforth::append;
 use logforth::filter::EnvFilter;
-use logforth::Dispatch;
-use logforth::Logger;
 
 fn main() {
-    Logger::new()
-        .dispatch(
-            Dispatch::new()
-                .filter(EnvFilter::from_default_env())
-                .append(append::Stdout::default()),
-        )
-        .apply()
-        .unwrap();
+    logforth::builder()
+        .filter(EnvFilter::from_default_env())
+        .append(append::Stdout::default())
+        .finish();
 
     log::error!("Hello error!");
     log::warn!("Hello warn!");

examples/fn_layout_filter.rs

@@ -17,28 +17,22 @@ use logforth::append;
 use logforth::filter::CustomFilter;
 use logforth::filter::FilterResult;
 use logforth::layout::CustomLayout;
-use logforth::Dispatch;
-use logforth::Logger;
 
 fn main() {
-    Logger::new()
-        .dispatch(
-            Dispatch::new()
-                .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())
-                    })),
-                ),
+    logforth::builder()
+        .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()
-        .unwrap();
+        .finish();
 
     log::error!("Hello error!");
     log::warn!("Hello warn!");

examples/json_stdio.rs

@@ -12,21 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use log::LevelFilter;
 use logforth::append;
 use logforth::layout::JsonLayout;
-use logforth::Dispatch;
-use logforth::Logger;
 
 fn main() {
-    Logger::new()
-        .dispatch(
-            Dispatch::new()
-                .filter(LevelFilter::Trace)
-                .append(append::Stdout::default().with_layout(JsonLayout::default())),
-        )
-        .apply()
-        .unwrap();
+    logforth::builder()
+        .append(append::Stdout::default().with_layout(JsonLayout::default()))
+        .finish();
 
     log::error!("Hello error!");
     log::warn!("Hello warn!");

examples/rolling_file.rs

@@ -18,8 +18,6 @@ use logforth::append::rolling_file::RollingFileWriter;
 use logforth::append::rolling_file::Rotation;
 use logforth::append::Stdout;
 use logforth::layout::JsonLayout;
-use logforth::Dispatch;
-use logforth::Logger;
 
 fn main() {
     let rolling = RollingFileWriter::builder()
@@ -32,15 +30,13 @@ fn main() {
         .unwrap();
     let (writer, _guard) = NonBlockingBuilder::default().finish(rolling);
 
-    Logger::new()
-        .dispatch(
-            Dispatch::new()
-                .filter("trace")
-                .append(RollingFile::new(writer).with_layout(JsonLayout::default()))
-                .append(Stdout::default()),
-        )
-        .apply()
-        .unwrap();
+    logforth::builder()
+        .filter("trace")
+        .append(RollingFile::new(writer).with_layout(JsonLayout::default()))
+        .dispatch()
+        .filter("info")
+        .append(Stdout::default())
+        .finish();
 
     let repeat = 1;
 

examples/simple_stdio.rs

@@ -14,19 +14,13 @@
 
 use log::LevelFilter;
 use logforth::append;
-use logforth::Dispatch;
-use logforth::Logger;
 
 fn main() {
-    Logger::new()
-        .dispatch(
-            Dispatch::new()
-                .filter(LevelFilter::Trace)
-                .append(append::Stdout::default())
-                .append(append::Stderr::default()),
-        )
-        .apply()
-        .unwrap();
+    logforth::builder()
+        .filter(LevelFilter::Trace)
+        .append(append::Stdout::default())
+        .append(append::Stderr::default())
+        .finish();
 
     log::error!("Hello error!");
     log::warn!("Hello warn!");

src/append/opentelemetry.rs

@@ -195,7 +195,7 @@ impl Append for OpentelemetryLog {
             record: &'a mut LogRecord,
         }
 
-        impl<'a, 'kvs> log::kv::Visitor<'kvs> for KvExtractor<'a> {
+        impl<'kvs> log::kv::Visitor<'kvs> for KvExtractor<'_> {
             fn visit_pair(
                 &mut self,
                 key: log::kv::Key<'kvs>,

src/layout/json.rs

@@ -47,7 +47,7 @@ struct KvCollector<'a> {
     kvs: &'a mut Map<String, Value>,
 }
 
-impl<'a, 'kvs> log::kv::Visitor<'kvs> for KvCollector<'a> {
+impl<'kvs> log::kv::Visitor<'kvs> for KvCollector<'_> {
     fn visit_pair(
         &mut self,
         key: log::kv::Key<'kvs>,

src/layout/kv.rs

@@ -37,7 +37,7 @@ struct KvWriter<'a, 'kvs> {
     writer: &'kvs mut std::fmt::Formatter<'a>,
 }
 
-impl<'a, 'kvs> log::kv::Visitor<'kvs> for KvWriter<'a, 'kvs> {
+impl<'kvs> log::kv::Visitor<'kvs> for KvWriter<'_, 'kvs> {
     fn visit_pair(
         &mut self,
         key: log::kv::Key<'kvs>,

src/lib.rs

@@ -12,55 +12,50 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! # A versatile and extensible logging implementation
-//!
-//! ## Usage
-//!
-//! Add the dependencies to your `Cargo.toml` with:
-//!
-//! ```shell
-//! cargo add log
-//! cargo add logforth
-//! ```
-//!
-//! Here, [`log`] is the logging facade and `logforth` is the logging implementation.
-//!
-//! Then, you can use the logger with:
-//!
-//! ```rust
-//! use log::LevelFilter;
-//! use logforth::append;
-//! use logforth::layout::TextLayout;
-//! use logforth::Dispatch;
-//! use logforth::Logger;
-//!
-//! Logger::new()
-//!     .dispatch(
-//!         Dispatch::new()
-//!             .filter(LevelFilter::Trace)
-//!             .append(append::Stdout::default()),
-//!     )
-//!     .apply()
-//!     .unwrap();
-//!
-//! log::error!("Hello error!");
-//! log::warn!("Hello warn!");
-//! log::info!("Hello info!");
-//! log::debug!("Hello debug!");
-//! log::trace!("Hello trace!");
-//! ```
-//!
-//! Read more demos under the [examples](https://github.com/fast/logforth/tree/main/examples) directory.
+/*!
+# A versatile and extensible logging implementation
+
+## Usage
+
+Add the dependencies to your `Cargo.toml` with:
+
+```shell
+cargo add log
+cargo add logforth
+```
+
+[`log`] is the logging facade and `logforth` is the logging implementation.
+
+Then, you can use the logger with the simplest default setup:
+
+```rust
+logforth::stderr().finish();
+```
+
+Or configure the logger in a more fine-grained way:
+
+```rust
+logforth::builder()
+    .filter(log::LevelFilter::Debug)
+    .append(logforth::append::Stderr::default())
+    .dispatch()
+    .filter(log::LevelFilter::Info)
+    .append(logforth::append::Stdout::default())
+    .finish();
+```
+
+Read more demos under the [examples](https://github.com/fast/logforth/tree/main/examples) directory.
+*/
 
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 pub mod append;
 pub mod filter;
 pub mod layout;
-mod logger;
 
 pub use append::Append;
 pub use filter::Filter;
 pub use layout::Layout;
-pub use logger::Dispatch;
-pub use logger::Logger;
+
+mod logger;
+pub use logger::*;