From 45d3b1015156223f25af6703412ee11e535c3578 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`
---
 Cargo.toml    | 10 +++++++---
 README.md     |  3 +++
 src/errors.rs | 12 ++++++------
 3 files changed, 16 insertions(+), 9 deletions(-)

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/README.md b/README.md
index aa125a3..320bf5c 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,9 @@ failed to open file `does not exist.txt`
     caused by: 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 `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
 
 fs-err's API is the same as [`std::fs`][std::fs], so migrating code to use it is easy.
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)
     }