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 colours-feature, you can additionally print some neat colours:

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 `colours`-feature!
eprintln!("{}", err.trace_coloured());

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 trace!()-macro:

use error_trace::trace;
  
// Do something that fails
let err = std::str::from_utf8(&[0xFF]).unwrap_err();
  
// Format it with a one-time parent error
eprintln!("{}", trace!(("Oh no, everything went wrong!"), err));

For users of the colours-feature, there is the associated [trace_coloured!()]-macro:

use error_trace::trace_coloured;
  
// Do something that fails
let err = std::str::from_utf8(&[0xFF]).unwrap_err();
  
// Format it with a one-time parent error
eprintln!("{}", trace_coloured!(("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 = "v1.1.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: Alias for the colours-trait.
• colours: Enables the use of [trace_coloured()].
• macros: Enables the use of the trace!()- and [trace_coloured!()]-macros.
• serde: Implements Deserialize and Serialize for the Trace-structure.

Macros

trace

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

Structs

ErrorTraceFormatter

Formats an error and all its dependencies.

Trace

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.