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/// ```
77pub fn basic_builder() -> Builder {
78    let mut builder = Builder::new();
79    builder.format(formatter(format::DefaultCologStyle));
80    builder
81}
82
83/// Opinionated builder, with [`colog`](crate) defaults.
84///
85/// This function returns a builder that:
86///  - Uses [`colog`](crate) formatting
87///  - Presents messages at severity [`LevelFilter::Info`] and up
88///  - Optionally uses `RUST_LOG` environment settings
89///
90/// ```rust
91/// let mut builder = colog::default_builder();
92/// /* further builder setup here.. */
93/// builder.init();
94/// log::info!("logging is ready");
95/// ```
96pub fn default_builder() -> Builder {
97    let mut builder = basic_builder();
98    builder.filter(None, LevelFilter::Info);
99    if let Ok(rust_log) = env::var("RUST_LOG") {
100        builder.parse_filters(&rust_log);
101    }
102    builder
103}
104
105/// Deprecated. Use [`default_builder`] instead (see also [`basic_builder`])
106#[deprecated(note = "Use `default_builder` instead")]
107pub fn builder() -> Builder {
108    default_builder()
109}
110
111/// Convenience function to initialize logging.
112///
113/// This function constructs the default builder [`default_builder`] and
114/// initializes it, without any custom options.
115///
116/// If more flexibility is needed, see [`default_builder`] or [`basic_builder`]
117pub fn init() {
118    default_builder().init()
119}
120
121/// Convenience function to create binding formatter closure
122///
123/// This functions creates a `move` closure, which is useful when setting up
124/// logging with a custom styling. So instead of this:
125///
126/// ```rust
127/// # use env_logger::Builder;
128/// # use colog::format::CologStyle;
129/// # struct CustomStyle;
130/// # impl CologStyle for CustomStyle {}
131/// let mut builder = Builder::new();
132/// builder.format(|buf, rec| CustomStyle.format(buf, rec));
133/// /* ... */
134/// ```
135///
136/// One can write this:
137///
138/// ```rust
139/// # use env_logger::Builder;
140/// # use colog::format::CologStyle;
141/// # struct CustomStyle;
142/// # impl CologStyle for CustomStyle {}
143/// let mut builder = Builder::new();
144/// builder.format(colog::formatter(CustomStyle));
145/// /* ... */
146/// ```
147pub fn formatter(
148    fmt: impl CologStyle + Sync + Send,
149) -> impl Fn(&mut Formatter, &Record<'_>) -> Result<(), Error> + Sync + Send {
150    move |buf, rec| fmt.format(buf, rec)
151}
colog/lib.rs

colog/
lib.rs
