feat: impl Deref for Exn

CHANGELOG.md

@@ -9,7 +9,9 @@ All significant changes to this project will be documented in this file.
 * `Exn::from_iter` has been renamed to `Exn::raise_all`
 * `exn::Error` trait bound has been removed in favor of inlined `StdError + Send + Sync + 'static` bounds.
 * `err.raise()` has been moved to the `exn::ErrorExt` extension trait.
+* `Exn::error(&self)` has been replaced with `impl Deref<Target = E> for Exn<E>`.
 
 ### New Features
 
+* `Exn<E>` now implements `Deref<Target = E>`, allowing for more ergonomic access to the inner error.
 * This crate is now `no_std` compatible, while the `alloc` crate is still required for heap allocations. It is worth noting that `no_std` support is a nice-to-have feature, and can be dropped if it blocks other important features in the future. Before 1.0, once `exn` APIs settle down, the decision on whether to keep `no_std` as a promise will be finalized.

exn/src/display.rs

@@ -14,13 +14,14 @@
 
 use core::error::Error;
 use core::fmt;
+use core::ops::Deref;
 
 use crate::Exn;
 use crate::Frame;
 
 impl<E: Error + Send + Sync + 'static> fmt::Display for Exn<E> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "{}", self.error())
+        write!(f, "{}", self.deref())
     }
 }
 

exn/src/impls.rs

@@ -20,6 +20,7 @@ use alloc::vec::Vec;
 use core::error::Error;
 use core::fmt;
 use core::marker::PhantomData;
+use core::ops::Deref;
 use core::panic::Location;
 
 /// An exception type that can hold an error tree and additional context.
@@ -118,18 +119,24 @@ impl<E: Error + Send + Sync + 'static> Exn<E> {
         new_exn
     }
 
-    /// Return the current exception.
-    pub fn error(&self) -> &E {
+    /// Return the underlying exception frame.
+    pub fn frame(&self) -> &Frame {
+        &self.frame
+    }
+}
+
+impl<E> Deref for Exn<E>
+where
+    E: Error + Send + Sync + 'static,
+{
+    type Target = E;
+
+    fn deref(&self) -> &Self::Target {
         self.frame
             .error()
             .downcast_ref()
             .expect("error type must match")
     }
-
-    /// Return the underlying exception frame.
-    pub fn frame(&self) -> &Frame {
-        &self.frame
-    }
 }
 
 /// A frame in the exception tree.

exn/tests/common.rs

@@ -0,0 +1,71 @@
+// Copyright 2025 FastLabs Developers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use exn::ErrorExt;
+use exn::Exn;
+
+pub fn new_tree_error() -> Exn<Error> {
+    let e1 = Error("E1").raise();
+    let e3 = e1.raise(Error("E3"));
+
+    let e9 = Error("E9").raise();
+    let e10 = e9.raise(Error("E10"));
+
+    let e11 = Error("E11").raise();
+    let e12 = e11.raise(Error("E12"));
+
+    let e5 = Exn::raise_all(Error("E5"), [e3, e10, e12]);
+
+    let e2 = Error("E2").raise();
+    let e4 = e2.raise(Error("E4"));
+
+    let e7 = Error("E7").raise();
+    let e8 = e7.raise(Error("E8"));
+
+    Exn::raise_all(Error("E6"), [e5, e4, e8])
+}
+
+pub fn new_linear_error() -> Exn<Error> {
+    let e1 = Error("E1").raise();
+    let e2 = e1.raise(Error("E2"));
+    let e3 = e2.raise(Error("E3"));
+    let e4 = e3.raise(Error("E4"));
+    e4.raise(Error("E5"))
+}
+
+#[derive(Debug)]
+pub struct Error(pub &'static str);
+
+impl std::fmt::Display for Error {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl std::error::Error for Error {}
+
+#[derive(Debug)]
+pub struct ErrorWithSource(pub &'static str, pub Error);
+
+impl std::fmt::Display for ErrorWithSource {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl std::error::Error for ErrorWithSource {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        Some(&self.1)
+    }
+}

exn/tests/main.rs

@@ -0,0 +1,97 @@
+// Copyright 2025 FastLabs Developers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use exn::Exn;
+use exn::OptionExt;
+use exn::ResultExt;
+
+mod common;
+use common::Error;
+use common::ErrorWithSource;
+
+#[test]
+fn linear_error() {
+    let e = common::new_linear_error().raise(Error("topmost"));
+    assert_eq!(e.to_string(), "topmost");
+    insta::assert_debug_snapshot!(e);
+}
+
+#[test]
+fn tree_error() {
+    let e = common::new_tree_error().raise(Error("topmost"));
+    assert_eq!(e.to_string(), "topmost");
+    insta::assert_debug_snapshot!(e);
+}
+
+#[test]
+fn new_with_source() {
+    let e = Exn::new(ErrorWithSource("top", Error("source")));
+    insta::assert_debug_snapshot!(e);
+}
+
+#[test]
+fn result_ext() {
+    let result: Result<(), Error> = Err(Error("An error"));
+    let result = result.or_raise(|| Error("Another error"));
+    insta::assert_debug_snapshot!(result.unwrap_err());
+}
+
+#[test]
+fn option_ext() {
+    let result: Option<()> = None;
+    let result = result.ok_or_raise(|| Error("An error"));
+    insta::assert_debug_snapshot!(result.unwrap_err());
+}
+
+#[test]
+fn from_error() {
+    fn foo() -> exn::Result<(), Error> {
+        Err(Error("An error"))?;
+        Ok(())
+    }
+
+    let result = foo();
+    insta::assert_debug_snapshot!(result.unwrap_err());
+}
+
+#[test]
+fn bail() {
+    fn foo() -> exn::Result<(), Error> {
+        exn::bail!(Error("An error"));
+    }
+
+    let result = foo();
+    insta::assert_debug_snapshot!(result.unwrap_err());
+}
+
+#[test]
+fn ensure_ok() {
+    fn foo() -> exn::Result<(), Error> {
+        exn::ensure!(true, Error("An error"));
+        Ok(())
+    }
+
+    foo().unwrap();
+}
+
+#[test]
+fn ensure_fail() {
+    fn foo() -> exn::Result<(), Error> {
+        exn::ensure!(false, Error("An error"));
+        Ok(())
+    }
+
+    let result = foo();
+    insta::assert_debug_snapshot!(result.unwrap_err());
+}

exn/tests/snapshots/main__bail.snap

@@ -0,0 +1,5 @@
+---
+source: exn/tests/main.rs
+expression: result.unwrap_err()
+---
+An error, at exn/tests/main.rs:71:9

exn/tests/snapshots/main__ensure_fail.snap

@@ -0,0 +1,5 @@
+---
+source: exn/tests/main.rs
+expression: result.unwrap_err()
+---
+An error, at exn/tests/main.rs:91:9

exn/tests/snapshots/main__from_error.snap

@@ -0,0 +1,5 @@
+---
+source: exn/tests/main.rs
+expression: result.unwrap_err()
+---
+An error, at exn/tests/main.rs:60:9

exn/tests/snapshots/main__linear_error.snap

@@ -0,0 +1,15 @@
+---
+source: exn/tests/main.rs
+expression: e
+---
+topmost, at exn/tests/main.rs:25:40
+|
+|-> E5, at exn/tests/common.rs:44:8
+|
+|-> E4, at exn/tests/common.rs:43:17
+|
+|-> E3, at exn/tests/common.rs:42:17
+|
+|-> E2, at exn/tests/common.rs:41:17
+|
+|-> E1, at exn/tests/common.rs:40:26

exn/tests/snapshots/main__new_with_source.snap

@@ -0,0 +1,7 @@
+---
+source: exn/tests/main.rs
+expression: e
+---
+top, at exn/tests/main.rs:39:13
+|
+|-> source, at exn/tests/main.rs:39:13