Rewrite most documentation and examples

README.md

@@ -5,24 +5,25 @@
 [![](https://img.shields.io/badge/docs.rs-spdlog--rs-ff69b4?style=flat-square&logo=rust)](https://docs.rs/spdlog-rs)
 [![](https://img.shields.io/github/actions/workflow/status/SpriteOvO/spdlog-rs/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white)](https://github.com/SpriteOvO/spdlog-rs/actions/workflows/ci.yml)
 
-A fast and combinable Rust logging crate, inspired by the C++ logging library [spdlog].
+Fast, highly configurable Rust logging crate, inspired by the C++ logging library [spdlog].
 
 ## Features
 
  - Very fast (see [Benchmarks]).
- - Various log targets:
-    - Standard streams with optional colors.
-    - Files.
-    - Rotating log files by file size.
-    - Rotating log files hourly.
-    - Rotating log files daily.
-    - ... (more targets are implementing, PRs are welcome)
-    - Extendable with custom log targets.
- - Compatible with [log crate] (optional).
  - Asynchronous support.
- - Configured via environment variable.
- - Custom formatting.
- - Log filtering - log levels can be modified in runtime as well as in compile time.
+ - Compatible with `log` crate.
+ - Custom log formats:
+   - compile-time zero-cost pattern or runtime pattern;
+   - manually implementing for more flexibility.
+ - Various combinable sinks:
+    - standard streams with optional color support;
+    - files (single file, rotating hourly, daily or by file size);
+    - platform-specific (e.g. `journald` for Linux and `OutputDebugStringW` for Windows);
+    - ... and able to implement one yourself.
+ - Configuring via environment variables or TOML[^1].
+ - More readable level filters.
+
+[^1]: TOML deserialization support is working in progress, tracking issue [#25]
 
 ## Getting started
 
@@ -32,11 +33,11 @@ Add this to `Cargo.toml`:
 spdlog-rs = "0.3"
 ```
 
-The documentation of this crate is hosted on [docs.rs], and you can find examples under [./examples] directory.
+The documentation of this crate is hosted on [docs.rs], and you can learn examples under [./examples] directory along with it.
 
-If you have any questions or need help while using this crate, feel free to [open a discussion]. For feature requests or bug reports, please [open an issue].
+If you have any trouble while using this crate, please don't hesitate to [open a discussion] for help. For feature requests or bug reports, please [open an issue].
 
-## Supported Rust Versions
+## Supported Rust versions
 
 <!--
 When updating this, also update:
@@ -55,22 +56,18 @@ The current minimum supported Rust version is 1.56.
 
 Licensed under either of
 
- * Apache License, Version 2.0
-   ([LICENSE-APACHE](/LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license
-   ([LICENSE-MIT](/LICENSE-MIT) or http://opensource.org/licenses/MIT)
+ * Apache License, Version 2.0 ([LICENSE-APACHE](/LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](/LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.
 
 ## Contribution
 
-Unless you explicitly state otherwise, any contribution intentionally submitted
-for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
-dual licensed as above, without any additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
 
 [spdlog]: https://github.com/gabime/spdlog
 [Benchmarks]: https://github.com/SpriteOvO/spdlog-rs/blob/main/spdlog/benches/README.md
-[log crate]: https://crates.io/crates/log
+[#25]: https://github.com/SpriteOvO/spdlog-rs/issues/25
 [./examples]: https://github.com/SpriteOvO/spdlog-rs/tree/main/spdlog/examples
 [docs.rs]: https://docs.rs/spdlog-rs/
 [open a discussion]: https://github.com/SpriteOvO/spdlog-rs/discussions/new

spdlog/Cargo.toml

@@ -147,8 +147,8 @@ name = "ftlog_3_level_off"
 path = "benches/ftlog/3_level_off.rs"
 
 [[example]]
-name = "06_compatible_with_log_crate"
+name = "06_log_crate"
 required-features = ["log"]
 [[example]]
-name = "07_async_pool_sink"
+name = "07_async"
 required-features = ["multi-thread"]

spdlog/examples/01_macro.rs

@@ -0,0 +1,20 @@
+// All log macros and common types are under `spdlog::prelude` module.
+use spdlog::prelude::*;
+
+fn main() {
+    // Writes a log at "info" level with the info level, and this log will be
+    // processed by the global default logger - It will be output to `stdout`.
+    info!("program started");
+
+    let file = "config.json";
+
+    // They will be output to `stderr`.
+    error!("failed to open file: {}", file);
+    warn!("undetermined locale, defaults to `en_US.UTF-8`");
+
+    // Level "trace" and "debug" will be ignored by default, you can modify the
+    // level filter of the global default logger to enable all levels.
+    spdlog::default_logger().set_level_filter(LevelFilter::All);
+
+    trace!("position x: {}, y: {}", 11.4, -5.14);
+}

spdlog/examples/02_file.rs

@@ -0,0 +1,42 @@
+use std::{env, sync::Arc};
+
+use spdlog::{
+    prelude::*,
+    sink::{FileSink, RotatingFileSink, RotationPolicy},
+};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    configure_file_logger()?;
+    configure_rotating_file_logger()?;
+
+    Ok(())
+}
+
+fn configure_file_logger() -> Result<(), Box<dyn std::error::Error>> {
+    let path = env::current_exe()?.with_file_name("file.log");
+
+    let file_sink = Arc::new(FileSink::builder().path(path).build()?);
+    let new_logger = Arc::new(Logger::builder().sink(file_sink).build()?);
+    spdlog::set_default_logger(new_logger);
+
+    info!("this log will be written to the file `all.log`");
+
+    Ok(())
+}
+
+fn configure_rotating_file_logger() -> Result<(), Box<dyn std::error::Error>> {
+    let path = env::current_exe()?.with_file_name("rotating.log");
+
+    let file_sink = Arc::new(
+        RotatingFileSink::builder()
+            .base_path(path)
+            .rotation_policy(RotationPolicy::Daily { hour: 0, minute: 0 })
+            .build()?,
+    );
+    let new_logger = Arc::new(Logger::builder().sink(file_sink).build()?);
+    spdlog::set_default_logger(new_logger);
+
+    info!("this log will be written to the file `rotating.log`, and the file will be rotated daily at 00:00");
+
+    Ok(())
+}

spdlog/examples/03_logger.rs

@@ -0,0 +1,60 @@
+use std::{env, sync::Arc, time::Duration};
+
+use spdlog::{
+    prelude::*,
+    sink::{FileSink, Sink},
+};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // `spdlog-rs` has a global default logger and logs will be processed by it
+    // by default, You can configure it.
+    let default_logger = spdlog::default_logger();
+    default_logger.set_level_filter(LevelFilter::All);
+
+    // Or completely replace it with a new one.
+    let path = env::current_exe()?.with_file_name("all.log");
+    let file_sink = Arc::new(FileSink::builder().path(path).build()?);
+
+    let new_logger = Arc::new(
+        Logger::builder()
+            .level_filter(LevelFilter::All)
+            .flush_level_filter(LevelFilter::MoreSevereEqual(Level::Warn))
+            .sink(file_sink.clone())
+            .build()?,
+    );
+    new_logger.set_flush_period(Some(Duration::from_secs(3)));
+    spdlog::set_default_logger(new_logger);
+
+    info!("this log will be written to the file `all.log`");
+
+    // In addition to having the global default logger, more loggers are allowed to
+    // be configured, stored and used independently.
+    let db = AppDatabase::new(file_sink)?;
+    db.write_i32(114514);
+
+    Ok(())
+}
+
+struct AppDatabase {
+    logger: Logger,
+}
+
+impl AppDatabase {
+    fn new(all_log_sink: Arc<dyn Sink>) -> Result<Self, Box<dyn std::error::Error>> {
+        let path = env::current_exe()?.with_file_name("db.log");
+        let db_file_sink = Arc::new(FileSink::builder().path(path).build()?);
+
+        let logger = Logger::builder()
+            .name("database")
+            .level_filter(LevelFilter::All)
+            .flush_level_filter(LevelFilter::MoreSevereEqual(Level::Warn))
+            .sinks([all_log_sink, db_file_sink])
+            .build()?;
+        Ok(Self { logger })
+    }
+
+    fn write_i32(&self, value: i32) {
+        // This log will be written to both files `all.log` and `db.log`.
+        trace!(logger: self.logger, "writing value {} to the database", value);
+    }
+}