Skip to main content

Module envelopes

Module envelopes 

Source
Expand description

Envelopes an ErrorKind to collect optional diagnostic information.

  • Described collects an error description.
  • Diagnostic collects all possible diagnostics information.
  • Located collects the location the error occurred.

These types do not compose, so you cannot Described<Located<K>>.

Using an envelope is optional, ErrorKind by itself just ignores all diagnostic information.

§About Envelopes

The ErrorEnvelope types exist to wrap an ErrorKind, allowing it to collect additional information littered around the codebase during error propagation.

This allows us to control how detailed our error message will be without changing other parts of the code!

use error_kind::{error, Err, Error, ErrorKind};

#[derive(Copy, Clone, Debug, ErrorKind, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub enum MyErrorKind {
    SomeSimpleError,
}

#[derive(Clone, Debug, Error)]
pub struct MyError {
    error: error_kind::envelopes::Diagnostic<MyErrorKind>,
}

#[error("calling some_function with fail={fail}")]
fn some_function(fail: bool) -> Result<(), MyError> {
    if fail {
        return Err!(
            MyErrorKind::SomeSimpleError,
            "asked to fail explicitly",
        );
    }
    Ok(())
}

fn main() {
    let err = some_function(true).unwrap_err();
    println!("error: {err}");
}

Since the envelope is Diagnostic, all the additional context is captured and presented!

error: some simple error: asked to fail explicitly
  with context
  ╰─ calling some_function with fail=true

The Diagnostic envelope even collects source lines and backtraces, which can be printed when formatting with the alternate error format ("{error:#}").

This system takes advantage of the heavy optimizations of the Rust compiler.

If an envelope type doesn’t capture some piece of debugging information, it will aggressively inline to suggest to the calling code that the data is not needed.

§Printing Locations and Backtraces

The default display format for any envelopes provided by this crate work in the following way:

  • "{error}" will print all collected user-relevant information.
    • Will Print: description, context, and error kind.
    • Will Omit: backtraces and source locations.
  • "{error:#}" will print all collected information.
    • Will Print: Everything.
    • Will Omit: Nothing.
fn main() {
    let err = some_function(true).unwrap_err();

    // Backtrace & locations printed (if captured)!
    println!("error: {err:#}");
}

§Accessing Internal Information

ErrorEnvelopes explicitly don’t grant access to the information they wrap.

You should always construct your code in a way in which the information passed into the error envelope is not necessary. It’s only there to help understand why a failure occurred.

As such, there’s no way to inspect any of this “diagnostic” information.

Structs§

Describedalloc
An envelope that collects error descriptions
Diagnosticalloc
An envelope that collects detailed diagnostic information.
Located
An envelope that collects error locations

Traits§

ErrorEnvelope
Wraps an ErrorKind collecting optional debugging information.