-/// [2022-11-02 09:23:12.263] [info] hello, world! +/// [2022-11-02 09:23:12.263] [info] hello, world! ////// /// - If the logger has a name: /// ///
-/// [2022-11-02 09:23:12.263] [logger-name] [info] hello, world! +/// [2022-11-02 09:23:12.263] [logger-name] [info] hello, world! ////// /// - If crate feature `source-location` is enabled: /// ///
-/// [2022-11-02 09:23:12.263] [info] [mod::path, src/main.rs:4] hello, world! +/// [2022-11-02 09:23:12.263] [logger-name] [info] [mod::path, src/main.rs:4] hello, world! ///#[derive(Clone)] pub struct FullFormatter { diff --git a/spdlog/src/formatter/mod.rs b/spdlog/src/formatter/mod.rs index 878812d..d87a26e 100644 --- a/spdlog/src/formatter/mod.rs +++ b/spdlog/src/formatter/mod.rs @@ -1,8 +1,52 @@ //! Provides formatters for sink formatting log records. //! -//! Usually use [`Sink::set_formatter`] to set the formatter of a sink. +//! # Formatter +//! +//! Each normal Sink owns a Formatter, which is used to format each log. +//! +//! The default formatter for most sinks is [`FullFormatter`], you can call +//! [`Sink::set_formatter`] to replace it with another formatter. +//! +//! The easiest way to make a custom formatter is to build a pattern, see +//! [Compile-time and runtime pattern +//! formatter](#compile-time-and-runtime-pattern-formatter) below. If pattern +//! isn't flexible enough for you, you need to implement [`Formatter`] trait for +//! your own formatter struct. See the implementation of [`FullFormatter`] and +//! [./examples] directory for examples. +//! +//! # Compile-time and runtime pattern formatter +//! +//! spdlog-rs supports formatting your log records according to a pattern +//! string. There are 2 ways to construct a pattern: +//! +//! - Macro [`pattern!`]: Builds a pattern at compile-time. +//! - Macro [`runtime_pattern!`]: Builds a pattern at runtime. +//! +//! ``` +//! use spdlog::formatter::{pattern, PatternFormatter}; +//! # use spdlog::sink::{Sink, WriteSink}; +//! +//! # fn main() -> Result<(), Box
{
pattern: P,
@@ -392,20 +392,22 @@ where
}
}
-/// Provide context for patterns.
+/// Provides context for patterns.
+///
+/// There is nothing to set up here at the moment, reserved for future use.
#[derive(Clone, Debug)]
pub struct PatternContext {
fmt_info_builder: FmtExtraInfoBuilder,
}
impl PatternContext {
- /// Create a new `PatternContext` object.
+ /// Creates a new `PatternContext` object.
#[must_use]
fn new(fmt_info_builder: FmtExtraInfoBuilder) -> Self {
Self { fmt_info_builder }
}
- /// Set the style range of the log message written by the patterns.
+ /// Sets the style range of the log message written by the patterns.
///
/// This function is reserved for use by the style range pattern. Other
/// built-in patterns should not use this function. User-defined
@@ -416,26 +418,24 @@ impl PatternContext {
}
}
-/// A pattern.
+/// Represents a pattern for replacing a placeholder in templates.
///
-/// A pattern is like a formatter, except that multiple patterns can be combined
-/// in various ways to create a new pattern. The [`PatternFormatter`] struct
-/// provides a [`Formatter`] that formats log records according to a given
-/// pattern.
+/// A pattern will be used to replace placeholders that appear in a template
+/// string. Multiple patterns can form a new pattern. The [`PatternFormatter`]
+/// formats logs according to a given pattern.
///
/// # Built-in Patterns
///
-/// `spdlog` provides a rich set of built-in patterns. See the [`pattern`]
+/// `spdlog-rs` provides a rich set of built-in patterns. See the [`pattern`]
/// macro.
///
/// # Custom Patterns
///
/// There are 3 approaches to create your own pattern:
-/// - Define a new type and implements this trait;
-/// - Use the [`pattern`] macro to create a pattern from a literal template
+/// - Define a new type and implement this trait;
+/// - Use [`pattern`] macro to create a pattern from a literal template string.
+/// - Use [`runtime_pattern`] macro to create a pattern from a runtime template
/// string.
-/// - Use the [`runtime_pattern`] macro to create a pattern from a runtime
-/// template string.
pub trait Pattern: Send + Sync + DynClone {
/// Format this pattern against the given log record and write the formatted
/// message into the output buffer.
diff --git a/spdlog/src/formatter/pattern_formatter/runtime.rs b/spdlog/src/formatter/pattern_formatter/runtime.rs
index ef768e7..8d643a2 100644
--- a/spdlog/src/formatter/pattern_formatter/runtime.rs
+++ b/spdlog/src/formatter/pattern_formatter/runtime.rs
@@ -17,7 +17,7 @@ type PatternCreator = Box
-//! [2022-11-02 09:23:12.263] [info] hello, world!
-//! [2022-11-02 09:23:12.263] [warn] 3 + 2 = 5
-//! [2022-11-02 09:23:12.263] [error] oops!
+//! [2022-11-02 09:23:12.263] [info] hello, world!
+//! [2022-11-02 09:23:12.263] [error] oops!
+//! [2022-11-02 09:23:12.263] [debug] 3 + 2 = 5
//!
//!
-//! If you want to learn more advanced features such as *asynchronous sink*,
-//! *compile-time pattern formatter*, etc., please see [./examples]
-//! directory.
+//! The basic use is through these logging macros: [`trace!`], [`debug!`],
+//! [`info!`], [`warn!`], [`error!`], [`critical!`], where `critical!`
+//! represents the most severe logs and `trace!` the most verbose. Each of these
+//! macros accept format strings similarly to [`println!`]. All log macros
+//! and common types are already under [`prelude`] module.
//!
-//! ## Help
+//! ## Sink
//!
-//! 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].
+//! Many real programs want more than just displaying logs to the terminal.
//!
-//! # Overview of features
+//! [`Sink`]s are the objects that actually write logs to their targets. If you
+//! want logs to be written to files as well, [`FileSink`] is what you need.
//!
-//! - [Compatible with log crate](#compatible-with-log-crate)
-//! - [Asynchronous support](#asynchronous-support)
-//! - [Configured via environment
-//! variable](#configured-via-environment-variable)
-//! - [Compile-time and runtime pattern
-//! formatter](#compile-time-and-runtime-pattern-formatter)
-//! - [Compile-time filters](#compile-time-filters)
-//!
-//! # Compatible with log crate
-//!
-//! This is optional and is controlled by crate feature `log`.
+//! ```
+//! # use std::sync::Arc;
+//! use spdlog::{prelude::*, sink::FileSink};
+//!
+//! # fn main() -> spdlog::Result<()> {
+//! let path = "path/to/somewhere.log";
+//!
+//! # let path = concat!(env!("OUT_DIR"), "/doctest-out/crate-1.txt");
+//! let new_logger = spdlog::default_logger().fork_with(|new| {
+//! let file_sink = Arc::new(FileSink::builder().path(path).build()?);
+//! new.sinks_mut().push(file_sink);
+//! Ok(())
+//! })?;
+//! # let backup = spdlog::default_logger();
+//! spdlog::set_default_logger(new_logger);
+//!
+//! info!("from now on, logs will be written to both stdout/stderr and the file");
+//! # spdlog::set_default_logger(backup);
+//! # Ok(()) }
+//! ```
//!
-//! The compatibility with [log crate] is mainly through a proxy layer
-//! [`LogCrateProxy`]. Call [`init_log_crate_proxy`] function to enable the
-//! proxy layer, and all logs from [log crate] will be handled by it. You can
-//! use it to output [log crate] logs of upstream dependencies or to quickly
-//! migrate from [log crate] for your projects.
+//! Take a look at [`sink`] module for more interesting sinks, such as
+//! [`RotatingFileSink`] that automatically rotates files by time point or file
+//! size, and [`AsyncPoolSink`] that outputs logs asynchronously.
//!
-//! [`LogCrateProxy`] forwards all logs from [log crate] to [`default_logger`]
-//! by default, you can call [`log_crate_proxy()`] to get a reference to this
-//! proxy to configure it.
+//! ## Logger
//!
-//! See [./examples] directory for examples.
+//! A complex program may consist of many separated components.
//!
-//! # Asynchronous support
+//! [`Logger`] manages, controls and invokes multiple sinks within it. In
+//! addition to having the global [`default_logger`], more loggers are allowed
+//! to be configured, stored and used independently.
//!
-//! See [Asynchronous combined sink].
+//! Logging macros provide an optional parameter `logger`. If it is specified,
+//! logs will be processed by the specified logger instead of the global default
+//! logger.
//!
-//! # Configured via environment variable
+//! And benefiting from the fact that a logger uses `Arc` to store sinks, a sink
+//! can be set and used by more than one logger, and you can combine them as you
+//! like.
//!
-//! Users can optionally configure the level filter of loggers via the
-//! environment variable `SPDLOG_RS_LEVEL`.
+//! ```
+//! use spdlog::prelude::*;
+//! # use spdlog::Result;
//!
-//! For more details, see the documentation of [`init_env_level`].
+//! struct AppDatabase {
+//! logger: Logger,
+//! // Database info...
+//! }
//!
-//! # Compile-time and runtime pattern formatter
+//! impl AppDatabase {
+//! fn new() -> Result