colog/
lib.rs

1//! # Colog: Simple colored logger for rust
2//!
3//! The `colog` library is a simple formatter backend for the standard
4//! rust logging system (in the `log` crate).
5//!
6//! For convenience, [`colog`](crate) provides utility functions to help
7//! initialize logging, while using some reasonable defaults.
8//!
9//! All these defaults can be controlled, using a few more lines of code.
10//!
11//! Example code:
12//!  - `examples/simple.rs` (minimal example)
13//!  - `examples/levels.rs` (custom log levels)
14//!
15//! ## Minimal example
16//!
17//! ```rust
18//! use log::{error, warn, info, debug, trace};
19//!
20//! // Quick start: use default initialization
21//! colog::init();
22//!
23//! error!("error message");
24//! error!("error with fmt: {}", 42);
25//! warn!("warn message");
26//! info!("info message");
27//! debug!("debug message"); // not printed (LogLevel::Info is the default level)
28//! trace!("trace message"); // not printed (LogLevel::Info is the default level)
29//!
30//! // notice how multi-line comments are handled gracefully
31//! info!("multi line demonstration\nhere");
32//! info!("more\nmulti\nline\nhere\nhere");
33//! ```
34//!
35//! This results in the following terminal output:
36//!
37//! ![demo screenshot from terminal](https://raw.githubusercontent.com/chrivers/rust-colog/master/screenshot.png)
38//!
39//! ## Custom styling ##
40//!
41//! All the styling of [`colog`](crate) can be overriden.
42//!
43//! The styling is provided by the trait [`CologStyle`], which provides default
44//!  implementations for all methods, resulting in the default colog style.
45//!
46//! Example code:
47//!   - `examples/custom-level-colors.rs`
48//!   - `examples/custom-level-tokens.rs`
49//!   - `examples/custom-level-prefix.rs`
50
51use std::env;
52use std::io::Error;
53
54use env_logger::{fmt::Formatter, Builder};
55use log::{LevelFilter, Record};
56
57pub mod format;
58
59use format::CologStyle;
60
61/// Returns a [`env_logger::Builder`] that is configured to use [`crate`]
62/// formatting for its output.
63///
64/// This can be used as a building block to integrate into existing
65/// [`env_logger`] applications.
66///
67/// If desired, these steps can be performed manually, like so:
68///
69/// ```rust
70/// use colog::format::CologStyle;
71/// let mut builder = env_logger::Builder::new();
72/// builder.format(colog::formatter(colog::format::DefaultCologStyle));
73/// /* further builder setup here.. */
74/// builder.init();
75/// log::info!("logging is ready");
76/// ```
77#[must_use]
78pub fn basic_builder() -> Builder {
79    let mut builder = Builder::new();
80    builder.format(formatter(format::DefaultCologStyle));
81    builder
82}
83
84/// Opinionated builder, with [`colog`](crate) defaults.
85///
86/// This function returns a builder that:
87///  - Uses [`colog`](crate) formatting
88///  - Presents messages at severity [`LevelFilter::Info`] and up
89///  - Optionally uses `RUST_LOG` environment settings
90///
91/// ```rust
92/// let mut builder = colog::default_builder();
93/// /* further builder setup here.. */
94/// builder.init();
95/// log::info!("logging is ready");
96/// ```
97#[must_use]
98pub fn default_builder() -> Builder {
99    let mut builder = basic_builder();
100    builder.filter(None, LevelFilter::Info);
101    if let Ok(rust_log) = env::var("RUST_LOG") {
102        builder.parse_filters(&rust_log);
103    }
104    builder
105}
106
107/// Deprecated. Use [`default_builder`] instead (see also [`basic_builder`])
108#[deprecated(note = "Use `default_builder` instead")]
109#[must_use]
110pub fn builder() -> Builder {
111    default_builder()
112}
113
114/// Convenience function to initialize logging.
115///
116/// This function constructs the default builder [`default_builder`] and
117/// initializes it, without any custom options.
118///
119/// If more flexibility is needed, see [`default_builder`] or [`basic_builder`]
120pub fn init() {
121    default_builder().init();
122}
123
124/// Convenience function to create binding formatter closure
125///
126/// This functions creates a `move` closure, which is useful when setting up
127/// logging with a custom styling. So instead of this:
128///
129/// ```rust
130/// # use env_logger::Builder;
131/// # use colog::format::CologStyle;
132/// # struct CustomStyle;
133/// # impl CologStyle for CustomStyle {}
134/// let mut builder = Builder::new();
135/// builder.format(|buf, rec| CustomStyle.format(buf, rec));
136/// /* ... */
137/// ```
138///
139/// One can write this:
140///
141/// ```rust
142/// # use env_logger::Builder;
143/// # use colog::format::CologStyle;
144/// # struct CustomStyle;
145/// # impl CologStyle for CustomStyle {}
146/// let mut builder = Builder::new();
147/// builder.format(colog::formatter(CustomStyle));
148/// /* ... */
149/// ```
150pub fn formatter(
151    fmt: impl CologStyle + Sync + Send,
152) -> impl Fn(&mut Formatter, &Record<'_>) -> Result<(), Error> + Sync + Send {
153    move |buf, rec| fmt.format(buf, rec)
154}
colog/lib.rs

colog/
lib.rs
