From 6562f9abeb3f3684b5ca25e665c25e4bd30233da Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Feb 2024 14:44:53 -0600 Subject: [PATCH 1/6] docs(changelog): Add migration guide --- CHANGELOG.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c6b4ef7..b519076 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 From 5e0566ec4e88422b997a55c89dd8bc512f61e1aa Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Feb 2024 14:45:16 -0600 Subject: [PATCH 2/6] chore: Update anstyle --- Cargo.lock | 4 ++-- Cargo.toml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index bb0de81..ef7ec2b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -27,9 +27,9 @@ dependencies = [ [[package]] name = "anstyle" -version = "1.0.4" +version = "1.0.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7079075b41f533b8c61d2a4d073c4676e1f8b249ff94a393b0595db304e0dd87" +checksum = "8901269c6307e8d93993578286ac0edf7f195079ffff5ebdeea6a59ffb7e36bc" [[package]] name = "anstyle-parse" diff --git a/Cargo.toml b/Cargo.toml index 97ffdd6..6582377 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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" From 8bf7499956114f52668fa60c6c179036e85afee2 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Feb 2024 14:47:37 -0600 Subject: [PATCH 3/6] refactor(fmt): Use simplified anstyle formatting --- examples/custom_format.rs | 4 +--- src/fmt/mod.rs | 5 ++--- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/examples/custom_format.rs b/examples/custom_format.rs index 8f575fd..80b9aaa 100644 --- a/examples/custom_format.rs +++ b/examples/custom_format.rs @@ -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() ) }) diff --git a/src/fmt/mod.rs b/src/fmt/mod.rs index faee69b..b7aa4ac 100644 --- a/src/fmt/mod.rs +++ b/src/fmt/mod.rs @@ -251,14 +251,13 @@ struct StyledValue { #[cfg(feature = "color")] impl std::fmt::Display for StyledValue { 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(()) } } From 1b0f4dd9a084cdc1a6244cbb0041bdba4769b4a4 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Feb 2024 14:48:59 -0600 Subject: [PATCH 4/6] docs(fmt): Point people to anstyle adapters --- src/fmt/mod.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/fmt/mod.rs b/src/fmt/mod.rs index b7aa4ac..f0340e4 100644 --- a/src/fmt/mod.rs +++ b/src/fmt/mod.rs @@ -129,6 +129,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() From 62713d1688039a12a4da3567f2cbfb146a6be781 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Feb 2024 14:52:33 -0600 Subject: [PATCH 5/6] refactor(docs): Use intra-doc links --- src/fmt/humantime.rs | 5 +---- src/fmt/mod.rs | 14 ++++---------- src/lib.rs | 4 ---- 3 files changed, 5 insertions(+), 18 deletions(-) diff --git a/src/fmt/humantime.rs b/src/fmt/humantime.rs index 582a631..9c93d3b 100644 --- a/src/fmt/humantime.rs +++ b/src/fmt/humantime.rs @@ -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(), @@ -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, diff --git a/src/fmt/mod.rs b/src/fmt/mod.rs index f0340e4..92363fc 100644 --- a/src/fmt/mod.rs +++ b/src/fmt/mod.rs @@ -24,10 +24,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; @@ -95,8 +93,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 +/// [`Write`]: std::io::Write +/// [`writeln`]: std::writeln /// [`style`]: #method.style pub struct Formatter { buf: Rc>, @@ -240,10 +238,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 { style: style::Style, diff --git a/src/lib.rs b/src/lib.rs index cf20611..86db145 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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", From c67579cc5fb496573d9990d250fb66a9ec72171f Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Feb 2024 14:57:34 -0600 Subject: [PATCH 6/6] docs(fmt): Talk about new styling API The documentation for the old API was overlooked in #298 --- src/fmt/mod.rs | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/fmt/mod.rs b/src/fmt/mod.rs index 92363fc..883f943 100644 --- a/src/fmt/mod.rs +++ b/src/fmt/mod.rs @@ -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; @@ -78,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 /// @@ -95,7 +101,6 @@ impl Default for TimestampPrecision { /// /// [`Write`]: std::io::Write /// [`writeln`]: std::writeln -/// [`style`]: #method.style pub struct Formatter { buf: Rc>, write_style: WriteStyle,