From 7c1df0a754e045efce354430812fed0689bad4ca Mon Sep 17 00:00:00 2001
From: Schneems <richard.schneeman+foo@gmail.com>
Date: Fri, 18 Oct 2024 12:41:12 -0500
Subject: [PATCH] Update feature name

I discussed the logic here https://github.com/andrewhickman/fs-err/issues/59#issuecomment-2422721867.

The prior suggested name "anyhow" was a little too specific/esoteric and in the event that the feature flag outlives the popularity of `anyhow` it wouldn't make sense.

This suggested name tries to focus on the behavior outcome of the feature. It empowers callers to format the "called by" information however they want by:

- Providing a source of that data (Error::source)
- Not formatting emitting that data in `Display`
---
 .github/workflows/ci.yml |  4 ++--
 CHANGELOG.md             |  2 +-
 Cargo.toml               | 10 +++++++---
 src/errors.rs            | 12 ++++++------
 src/lib.rs               |  5 ++---
 5 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 64aae50..6b6d64a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -68,8 +68,8 @@ jobs:
           args: --features tokio
         if: ${{ matrix.rust_version == 'stable' || matrix.rust_version == 'beta' }}
 
-      - name: cargo check --features anyhow
+      - name: cargo check --features custom_caused_by
         uses: actions-rs/cargo@v1
         with:
           command: check
-          args: --features anyhow
+          args: --features custom_caused_by
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7db14a5..33258e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # 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 `anyhow` ([#60](https://github.com/andrewhickman/fs-err/pull/60)).
+* 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 `custom_caused_by` ([#60](https://github.com/andrewhickman/fs-err/pull/60)).
 
 ## 2.11.0
 
diff --git a/Cargo.toml b/Cargo.toml
index 4d8cf44..25ee99c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -23,9 +23,13 @@ serde_json = "1.0.64"
 [features]
 # Adds I/O safety traits, introduced in Rust 1.63
 io_safety = []
-# Removes the original error text from Display and relies on a wrapper library
-# (such as anyhow) to emit them via `Error::source()`.
-anyhow = []
+
+# Allow custom formatting of the error source
+#
+# When enabled errors emit `std::error::Error::source()` as Some (default is `None`) and
+# no longer include the original `std::io::Error` source in the `Display` implementation.
+# This is useful if errors are wrapped in another library such as Anyhow.
+custom_caused_by = []
 
 [package.metadata.release]
 tag-name = "{{version}}"
diff --git a/src/errors.rs b/src/errors.rs
index a8318d0..eaf05f2 100644
--- a/src/errors.rs
+++ b/src/errors.rs
@@ -101,7 +101,7 @@ impl fmt::Display for Error {
             E::WriteAt => write!(formatter, "failed to write with offset to `{}`", path),
         }?;
 
-        #[cfg(not(feature = "anyhow"))]
+        #[cfg(not(feature = "custom_caused_by"))]
         write!(formatter, "    caused by: {}", self.source)?;
 
         Ok(())
@@ -113,12 +113,12 @@ impl StdError for Error {
         self.source()
     }
 
-    #[cfg(not(feature = "anyhow"))]
+    #[cfg(not(feature = "custom_caused_by"))]
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         None
     }
 
-    #[cfg(feature = "anyhow")]
+    #[cfg(feature = "custom_caused_by")]
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         Some(&self.source)
     }
@@ -201,7 +201,7 @@ impl fmt::Display for SourceDestError {
             }
         }?;
 
-        #[cfg(not(feature = "anyhow"))]
+        #[cfg(not(feature = "custom_caused_by"))]
         write!(formatter, "    caused by: {}", self.source)?;
 
         Ok(())
@@ -213,12 +213,12 @@ impl StdError for SourceDestError {
         self.source()
     }
 
-    #[cfg(not(feature = "anyhow"))]
+    #[cfg(not(feature = "custom_caused_by"))]
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         None
     }
 
-    #[cfg(feature = "anyhow")]
+    #[cfg(feature = "custom_caused_by")]
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         Some(&self.source)
     }
diff --git a/src/lib.rs b/src/lib.rs
index 991dd52..ee83100 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -26,9 +26,8 @@ failed to open file `does not exist.txt`
     caused by: The system cannot find the file specified. (os error 2)
 ```
 
-> Note: To bypass displaying the original error message you can enable the `anyhow` feature.
-> When the `anyhow` feature is enabled `Error::source()` will return `Some` and the original
-> error will not be `Display`-ed via fs-err.
+> Note: Users of `anyhow` or other libraries that format an Error's sources can enable the `custom_caused_by` 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