From 1a26274422d905e964c710c5ba4e9087017fb09a Mon Sep 17 00:00:00 2001 From: Andrew Hickman Date: Wed, 23 Oct 2024 21:23:21 +0100 Subject: [PATCH] Update changelog and docs for #60 --- CHANGELOG.md | 16 +++++++++++++++- README.md | 17 +++++++++++------ src/errors.rs | 4 ++-- src/lib.rs | 20 +++++++++++++++----- 4 files changed, 43 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6baeb14..f3a4eeb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,20 @@ # fs-err Changelog -* Change errors to output original `std::io::Error` information Display by default. This functionality can be disabled for [anyhow](https://docs.rs/anyhow/latest/anyhow/) users by using the new feature `expose_original_error` ([#60](https://github.com/andrewhickman/fs-err/pull/60)). +## 3.0.0 + +* Error messages now include the original message from `std::io::Error` by default ([#60](https://github.com/andrewhickman/fs-err/pull/60)). Previously this was exposed through the [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) method. For example, previously a message would look like: + + ``` + failed to open file `file.txt` + ``` + + and you would have to remember to print the source, or use a library like `anyhow` to print the full chain of source errors. The new error message includes the cause by default + + ``` + failed to open file `file.txt`: The system cannot find the file specified. (os error 2) + ``` + + Note that the original error is no longer exposed though [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) by default. If you need access to it, you can restore the previous behaviour with the `expose_original_error` feature flag. ## 2.11.0 diff --git a/README.md b/README.md index aa125a3..0197cb8 100644 --- a/README.md +++ b/README.md @@ -30,8 +30,7 @@ The system cannot find the file specified. (os error 2) ...but if we use fs-err instead, our error contains more actionable information: ```txt -failed to open file `does not exist.txt` - caused by: The system cannot find the file specified. (os error 2) +failed to open file `does not exist.txt`: The system cannot find the file specified. (os error 2) ``` ## Usage @@ -66,10 +65,11 @@ println!("Program config: {:?}", decoded); ``` -[std::fs]: https://doc.rust-lang.org/stable/std/fs/ -[std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html -[std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html -[serde_json]: https://crates.io/crates/serde_json +## Feature flags + +* `expose_original_error`: when enabled, the [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) method of errors returned by this crate return the original `io::Error`. To avoid duplication in error messages, + this also suppresses printing its message in their `Display` implementation, so make sure that you are printing the full error chain. + ## Minimum Supported Rust Version @@ -79,6 +79,11 @@ This crate will generally be conservative with rust version updates. It uses the If the `tokio` feature is enabled, this crate will inherit the MSRV of the selected [`tokio`](https://crates.io/crates/tokio) version. +[std::fs]: https://doc.rust-lang.org/stable/std/fs/ +[std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html +[std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html +[serde_json]: https://crates.io/crates/serde_json + ## License Licensed under either of diff --git a/src/errors.rs b/src/errors.rs index 56fd4f8..dbb6a3e 100644 --- a/src/errors.rs +++ b/src/errors.rs @@ -103,7 +103,7 @@ impl fmt::Display for Error { // The `expose_original_error` feature indicates the caller should display the original error #[cfg(not(feature = "expose_original_error"))] - write!(formatter, " caused by: {}", self.source)?; + write!(formatter, ": {}", self.source)?; Ok(()) } @@ -204,7 +204,7 @@ impl fmt::Display for SourceDestError { // The `expose_original_error` feature indicates the caller should display the original error #[cfg(not(feature = "expose_original_error"))] - write!(formatter, " caused by: {}", self.source)?; + write!(formatter, ": {}", self.source)?; Ok(()) } diff --git a/src/lib.rs b/src/lib.rs index 52eb2b1..b6f9b7b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -22,13 +22,9 @@ The system cannot find the file specified. (os error 2) ...but if we use fs-err instead, our error contains more actionable information: ```txt -failed to open file `does not exist.txt` - caused by: The system cannot find the file specified. (os error 2) +failed to open file `does not exist.txt`: The system cannot find the file specified. (os error 2) ``` -> Note: Users of `anyhow` or other libraries that format an Error's sources can enable the `expose_original_error` feature to control the formatting of the orginal error message. -> When enabled, the `std::fmt::Display` implementation will emit the failed operation and paths but not the original `std::io::Error`. It will instead provide access via [Error::source](https://doc.rust-lang.org/std/error/trait.Error.html#method.source), which will be used by `anyhow` (or similar) libraries. - # Usage fs-err's API is the same as [`std::fs`][std::fs], so migrating code to use it is easy. @@ -63,6 +59,20 @@ println!("Program config: {:?}", decoded); # Ok::<(), Box>(()) ``` +# Feature flags + +* `expose_original_error`: when enabled, the [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) method of errors returned by this crate return the original `io::Error`. To avoid duplication in error messages, + this also suppresses printing its message in their `Display` implementation, so make sure that you are printing the full error chain. + + +# Minimum Supported Rust Version + +The oldest rust version this crate is tested on is **1.40**. + +This crate will generally be conservative with rust version updates. It uses the [`autocfg`](https://crates.io/crates/autocfg) crate to allow wrapping new APIs without incrementing the MSRV. + +If the `tokio` feature is enabled, this crate will inherit the MSRV of the selected [`tokio`](https://crates.io/crates/tokio) version. + [std::fs]: https://doc.rust-lang.org/stable/std/fs/ [std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html [std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html