spdlog-rs 0.5.3

Fast, highly configurable Rust logging crate, inspired by the C++ logging library spdlog
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! Provides formatters for sink formatting log records.
//!
//! # 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
//! [`SinkPropAccess::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 enough for you, take a look at [`FullFormatter::builder`] which allows
//! you to opt-out fields, or implement [`Formatter`] trait for your own
//! formatter struct for better flexibility. See the implementation of
//! [./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},
//!     prelude::*,
//! };
//! # use spdlog::sink::{Sink, WriteSink};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // This pattern is built at compile-time, the template accepts only a literal string.
//! let pattern = pattern!("[{date} {time}.{millisecond}] [{level}] {payload}{eol}");
//!
//! #[cfg(feature = "runtime-pattern")]
//! {
//!     use spdlog::formatter::runtime_pattern;
//!
//!     // This pattern is built at runtime, the template accepts a runtime string.
//!     let input = "[{date} {time}.{millisecond}] [{level}] {payload}{eol}";
//!     let pattern = runtime_pattern!(input)?;
//! }
//!
//! // Use the compile-time or runtime pattern.
//! # let your_sink = WriteSink::builder().target(vec![]).build()?;
//! your_sink.set_formatter(Box::new(PatternFormatter::new(pattern)));
//! # Ok(()) }
//! ```
//!
//! [`SinkPropAccess::set_formatter`]: crate::sink::SinkPropAccess::set_formatter
//! [./examples]: https://github.com/SpriteOvO/spdlog-rs/tree/main/spdlog/examples

mod full_formatter;
#[cfg(feature = "serde_json")]
mod json_formatter;
mod local_time_cacher;
mod pattern_formatter;
mod unreachable_formatter;

use std::ops::Range;

use dyn_clone::*;
pub use full_formatter::*;
#[cfg(feature = "serde_json")]
pub use json_formatter::*;
pub(crate) use local_time_cacher::*;
pub use pattern_formatter::*;
pub(crate) use unreachable_formatter::*;

use crate::{Record, Result, StringBuf};

/// Represents a formatter that can be used for formatting logs.
///
/// # Examples
///
/// See the implementation of [`FullFormatter`] and [./examples] directory.
///
/// [./examples]: https://github.com/SpriteOvO/spdlog-rs/tree/main/spdlog/examples
pub trait Formatter: Send + Sync + DynClone {
    /// Formats a log record.
    fn format(
        &self,
        record: &Record,
        dest: &mut StringBuf,
        ctx: &mut FormatterContext,
    ) -> Result<()>;
}
clone_trait_object!(Formatter);

/// Provides context for formatters.
#[derive(Debug, Default)]
pub struct FormatterContext<'a> {
    style_range: Option<Range<usize>>,
    // Set to `Some` if the cached date time is locked in the upper caller.
    locked_time_date: Option<TimeDateLazyLocked<'a>>,
}

impl FormatterContext<'_> {
    /// Constructs a `FormatterContext`.
    #[must_use]
    pub fn new() -> Self {
        Self {
            style_range: None,
            locked_time_date: None,
        }
    }

    /// Sets style range (in bytes) of the formatted text.
    ///
    /// Users must ensure that indexes are correctly UTF-8 boundary.
    pub fn set_style_range(&mut self, range: Option<Range<usize>>) {
        self.style_range = range;
    }

    /// A style range (in bytes) of the formatted text.
    ///
    /// If style is available in the sink, the text in the range will be
    /// rendered in the style corresponding to that log message level, otherwise
    /// it will be ignored.
    ///
    /// Its indexes are guaranteed by the setter to be the correct UTF-8
    /// boundary.
    #[must_use]
    pub fn style_range(&self) -> Option<Range<usize>> {
        self.style_range.clone() // This clone is cheap
    }
}