err_ctx/
lib.rs

1//! Minimalist helper library for providing contextual errors that display in the traditional
2//! "context: cause" format. Useful for cases where the primary goal of a `Result` is to convey
3//! detailed diagnostics to a user.
4//!
5//! Pairs well with `type Result<T> = std::result::Result<T, Box<std::error::Error + Send + Sync>>;`
6//!
7//! ```
8//! use std::fs;
9//! use err_ctx::ResultExt;
10//! let result = fs::read("foo.txt").ctx("reading foo.txt");
11//! assert!(result.unwrap_err().to_string().starts_with("reading foo.txt: "));
12//! ```
13
14use std::error::Error;
15use std::fmt;
16
17/// An error providing context for some underlying cause.
18#[derive(Debug)]
19pub struct Context<C> {
20    context: C,
21    source: Box<dyn Error + Send + Sync>,
22}
23
24impl<C> Context<C> {
25    pub fn new(context: C, source: Box<dyn Error + Send + Sync>) -> Self {
26        Self { context, source }
27    }
28}
29
30impl<C: fmt::Display> fmt::Display for Context<C> {
31    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
32        self.context.fmt(f)?;
33        f.write_str(": ")?;
34        self.source.fmt(f)
35    }
36}
37
38impl<C: fmt::Debug + fmt::Display> Error for Context<C> {
39    fn source(&self) -> Option<&(dyn Error + 'static)> {
40        Some(&*self.source)
41    }
42}
43
44pub trait ResultExt<T, E>
45where
46    E: Into<Box<dyn Error + Send + Sync>>,
47{
48    /// If this `Result` is an `Err`, wrap the error with `context`.
49    fn ctx<D>(self, context: D) -> Result<T, Context<D>>;
50
51    /// If this `Result` is an `Err`, invoke `f` and wrap the error with its result.
52    fn with_ctx<D>(self, f: impl FnOnce(&E) -> D) -> Result<T, Context<D>>;
53}
54
55impl<T, E> ResultExt<T, E> for Result<T, E>
56where
57    E: Into<Box<dyn Error + Send + Sync>>,
58{
59    fn ctx<D>(self, context: D) -> Result<T, Context<D>> {
60        self.map_err(|e| e.ctx(context))
61    }
62
63    fn with_ctx<D>(self, f: impl FnOnce(&E) -> D) -> Result<T, Context<D>> {
64        self.map_err(|e| {
65            let context = f(&e);
66            e.ctx(context)
67        })
68    }
69}
70
71pub trait ErrorExt {
72    /// Construct a `Context` wrapping this error.
73    fn ctx<D>(self, context: D) -> Context<D>;
74}
75
76impl<T: Into<Box<Error + Send + Sync>>> ErrorExt for T {
77    fn ctx<D>(self, context: D) -> Context<D> {
78        Context {
79            context,
80            source: self.into(),
81        }
82    }
83}
err_ctx/lib.rs

err_ctx/
lib.rs
