Skip to content

Commit

Permalink
Merge pull request #310 from epage/docs
Browse files Browse the repository at this point in the history
docs: Talk abotu new styling API
  • Loading branch information
epage authored Feb 13, 2024
2 parents 8c94cd5 + c67579c commit 522ce17
Show file tree
Hide file tree
Showing 7 changed files with 37 additions and 31 deletions.
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,21 @@ and this project adheres to [Semantic Versioning](http://semver.org/).

## [0.11.0] - 2024-01-19

### Migration Guide

**env_logger::fmt::Style:**
The bespoke styling API, behind `color`, was removed, in favor of accepting any
ANSI styled string and adapting it to the target stream's capabilities.

Possible styling libraries include:
- [anstyle](https://docs.rs/anstyle) is a minimal, runtime string styling API and is re-exported as `env_logger::fmt::style`
- [owo-colors](https://docs.rs/owo-colors) is a feature rich runtime string styling API
- [color-print](https://docs.rs/color-print) for feature-rich compile-time styling API

[custom_format.rs](https://docs.rs/env_logger/latest/src/custom_format/custom_format.rs.html)
uses `anstyle` via
[`Formatter::default_level_style`](https://docs.rs/env_logger/latest/env_logger/fmt/struct.Formatter.html#method.default_level_style)

### Breaking Change

- Removed bespoke styling API
Expand Down
4 changes: 2 additions & 2 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ log = { version = "0.4.8", features = ["std"] }
env_filter = { version = "0.1.0", path = "crates/env_filter", default-features = false }
humantime = { version = "2.0.0", optional = true }
anstream = { version = "0.6.11", default-features = false, features = ["wincon"], optional = true }
anstyle = { version = "1.0.4", optional = true }
anstyle = { version = "1.0.6", optional = true }

[[test]]
name = "regexp_filter"
Expand Down
4 changes: 1 addition & 3 deletions examples/custom_format.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,11 @@ fn main() {
// We are reusing `anstyle` but there are `anstyle-*` crates to adapt it to your
// preferred styling crate.
let warn_style = buf.default_level_style(log::Level::Warn);
let reset = warn_style.render_reset();
let warn_style = warn_style.render();
let timestamp = buf.timestamp();

writeln!(
buf,
"My formatted log ({timestamp}): {warn_style}{}{reset}",
"My formatted log ({timestamp}): {warn_style}{}{warn_style:#}",
record.args()
)
})
Expand Down
5 changes: 1 addition & 4 deletions src/fmt/humantime.rs
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,6 @@ impl Formatter {
/// writeln!(buf, "{}: {}: {}", ts, record.level(), record.args())
/// });
/// ```
///
/// [`Timestamp`]: struct.Timestamp.html
pub fn timestamp(&self) -> Timestamp {
Timestamp {
time: SystemTime::now(),
Expand Down Expand Up @@ -76,8 +74,7 @@ impl Formatter {
/// The timestamp implements [`Display`] and can be written to a [`Formatter`].
///
/// [RFC3339]: https://www.ietf.org/rfc/rfc3339.txt
/// [`Display`]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
/// [`Formatter`]: struct.Formatter.html
/// [`Display`]: std::fmt::Display
pub struct Timestamp {
time: SystemTime,
precision: TimestampPrecision,
Expand Down
34 changes: 17 additions & 17 deletions src/fmt/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,14 @@
//!
//! The format used to print log records can be customised using the [`Builder::format`]
//! method.
//! Custom formats can apply different color and weight to printed values using
//! [`Style`] builders.
//!
//! Terminal styling is done through ANSI escape codes and will be adapted to the capabilities of
//! the target stream.
//! For example, you could use one of:
//! - [anstyle](https://docs.rs/anstyle) is a minimal, runtime string styling API and is re-exported as [`style`]
//! - [owo-colors](https://docs.rs/owo-colors) is a feature rich runtime string styling API
//! - [color-print](https://docs.rs/color-print) for feature-rich compile-time styling API
//! See also [`Formatter::default_level_style`]
//!
//! ```
//! use std::io::Write;
Expand All @@ -24,10 +30,8 @@
//! });
//! ```
//!
//! [`Formatter`]: struct.Formatter.html
//! [`Style`]: struct.Style.html
//! [`Builder::format`]: ../struct.Builder.html#method.format
//! [`Write`]: https://doc.rust-lang.org/stable/std/io/trait.Write.html
//! [`Builder::format`]: crate::Builder::format
//! [`Write`]: std::io::Write

use std::cell::RefCell;
use std::fmt::Display;
Expand Down Expand Up @@ -80,7 +84,7 @@ impl Default for TimestampPrecision {
/// A formatter to write logs into.
///
/// `Formatter` implements the standard [`Write`] trait for writing log records.
/// It also supports terminal colors, through the [`style`] method.
/// It also supports terminal styling using ANSI escape codes.
///
/// # Examples
///
Expand All @@ -95,9 +99,8 @@ impl Default for TimestampPrecision {
/// builder.format(|buf, record| writeln!(buf, "{}: {}", record.level(), record.args()));
/// ```
///
/// [`Write`]: https://doc.rust-lang.org/stable/std/io/trait.Write.html
/// [`writeln`]: https://doc.rust-lang.org/stable/std/macro.writeln.html
/// [`style`]: #method.style
/// [`Write`]: std::io::Write
/// [`writeln`]: std::writeln
pub struct Formatter {
buf: Rc<RefCell<Buffer>>,
write_style: WriteStyle,
Expand Down Expand Up @@ -129,6 +132,8 @@ impl Formatter {
/// Get the default [`style::Style`] for the given level.
///
/// The style can be used to print other values besides the level.
///
/// See [`style`] for how to adapt it to the styling crate of your choice
pub fn default_level_style(&self, level: Level) -> style::Style {
if self.write_style == WriteStyle::Never {
style::Style::new()
Expand Down Expand Up @@ -238,10 +243,6 @@ type SubtleStyle = StyledValue<&'static str>;
type SubtleStyle = &'static str;

/// A value that can be printed using the given styles.
///
/// It is the result of calling [`Style::value`].
///
/// [`Style::value`]: struct.Style.html#method.value
#[cfg(feature = "color")]
struct StyledValue<T> {
style: style::Style,
Expand All @@ -251,14 +252,13 @@ struct StyledValue<T> {
#[cfg(feature = "color")]
impl<T: std::fmt::Display> std::fmt::Display for StyledValue<T> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let style = self.style.render();
let reset = self.style.render_reset();
let style = self.style;

// We need to make sure `f`s settings don't get passed onto the styling but do get passed
// to the value
write!(f, "{style}")?;
self.value.fmt(f)?;
write!(f, "{reset}")?;
write!(f, "{style:#}")?;
Ok(())
}
}
Expand Down
4 changes: 0 additions & 4 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -259,10 +259,6 @@
//! [gh-repo-examples]: https://github.com/rust-cli/env_logger/tree/main/examples
//! [level-enum]: https://docs.rs/log/latest/log/enum.Level.html
//! [log-crate-url]: https://docs.rs/log
//! [`Builder`]: struct.Builder.html
//! [`Builder::is_test`]: struct.Builder.html#method.is_test
//! [`Env`]: struct.Env.html
//! [`fmt`]: fmt/index.html

#![doc(
html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
Expand Down

0 comments on commit 522ce17

Please sign in to comment.