Crate error_trace 

Small Rust crate for printing nice errors traits based on Error::source().

Usage

Using the crate is quite straightforward.

First, create your errors as usual:

#[derive(Debug)]
struct SomeError {
    msg : String,
}
impl Display for SomeError {
    fn fmt(&self, f: &mut Formatter<'_>) -> FResult {
        write!(f, "{}", self.msg)
    }
}
impl Error for SomeError {}

#[derive(Debug)]
struct HigherError {
    msg   : String,
    child : SomeError,
}
impl Display for HigherError {
    fn fmt(&self, f: &mut Formatter<'_>) -> FResult {
        write!(f, "{}", self.msg)
    }
}
impl Error for HigherError {
    fn source(&self) -> Option<&(dyn 'static + Error)> {
        Some(&self.child)
    }
}

Then, when it is time to report them to the user, do not print them directly but instead use the ErrorTrace-trait’s trace() function:

use error_trace::ErrorTrace as _;

// ...

let err: HigherError = HigherError {
    msg: "Oh no, something went wrong!".into(),
    child: SomeError{
        msg: "A specific reason".into()
    }
};
eprintln!("{}", err.trace());

This will show you:

Oh no, something went wrong!

Caused by:
 o A specific reason

If you enable the colors-feature, you can additionally print some neat colors:

use error_trace::ErrorTrace as _;

// ...

let err: HigherError = HigherError {
    msg: "Oh no, something went wrong!".into(),
    child: SomeError{
        msg: "A specific reason".into()
    }
};

// Requires the `colors`-feature!
eprintln!("{}", err.trace_colored());

Finally, when used in a situation where you want to show a quick error but are sure to never needs its contents, you can use the toplevel!()-macro:

use error_trace::toplevel;

// Do something that fails
let err = std::str::from_utf8(&[0xFF]).unwrap_err();

// Format it with a one-time parent error
eprintln!("{}", toplevel!(("Oh no, everything went wrong!"), err));

For users of the colors-feature, there is the associated toplevel_colored!()-macro:

use error_trace::toplevel_colored;

// Do something that fails
let err = std::str::from_utf8(&[0xFF]).unwrap_err();

// Format it with a one-time parent error
eprintln!("{}", toplevel_colored!(("Oh no, everything went wrong!"), err));

Installation

To use this crate into one of your projects, simply add it to your Cargo.toml file:

error-trace = { git = "https://github.com/Lut99/error-trace-rs" }

Optionally, you can commit to a particular tag:

error-trace = { git = "https://github.com/Lut99/error-trace-rs", tag = "v4.0.0" }

To build this crate’s documentation and open it, run:

cargo doc --all-features --no-deps --open

in the root of the repository.

Features

The crate has the following features:

• colors: Enables the use of ErrorTrace::trace_colored().
• macros: Enables the use of the toplevel!()- and toplevel_colored!()-macros.
• serde: Implements Deserialize and Serialize for the FrozenTrace-structure.

Macros

toplevelmacros

Creates a one-time ErrorTrace-compatible type from the given string, then calls trace() on it.

toplevel_coloredcolors and macros

Creates a one-time ErrorTrace-compatible type from the given string, then calls trace_colored() on it.

Structs

ErrorTraceColorFormattercolors

Formats an error and all its dependencies using neat ANSI-colors if the formatter to which we’re writing supports it.

ErrorTraceFormatter

Formats an error and all its dependencies.

FrozenTrace

A helper type that can be used to “freeze” a trace and then pass it on to a further error.

Traits

ErrorTrace

Allows one to write an error and all of its dependencies.