Struct eyre::Report

pub struct Report { /* fields omitted */ }

The core error reporting type of the library, a wrapper around a dynamic error reporting type.

Report works a lot like Box<dyn std::error::Error>, but with these differences:

• Report requires that the error is Send, Sync, and 'static.
• Report guarantees that a backtrace is available, even if the underlying error type does not provide one.
• Report is represented as a narrow pointer — exactly one word in size instead of two.

Display representations

When you print an error object using "{}" or to_string(), only the outermost underlying error is printed, not any of the lower level causes. This is exactly as if you had called the Display impl of the error from which you constructed your eyre::Report.

Failed to read instrs from ./path/to/instrs.json

To print causes as well using eyre's default formatting of causes, use the alternate selector "{:#}".

Failed to read instrs from ./path/to/instrs.json: No such file or directory (os error 2)

The Debug format "{:?}" includes your backtrace if one was captured. Note that this is the representation you get by default if you return an error from fn main instead of printing it explicitly yourself.

Error: Failed to read instrs from ./path/to/instrs.json

Caused by:
    No such file or directory (os error 2)

Stack backtrace:
   0: <E as eyre::context::ext::StdError>::ext_report
             at /git/eyre/src/backtrace.rs:26
   1: core::result::Result<T,E>::map_err
             at /git/rustc/src/libcore/result.rs:596
   2: eyre::context::<impl eyre::WrapErr<T,E,H> for core::result::Result<T,E>>::wrap_err_with
             at /git/eyre/src/context.rs:58
   3: testing::main
             at src/main.rs:5
   4: std::rt::lang_start
             at /git/rustc/src/libstd/rt.rs:61
   5: main
   6: __libc_start_main
   7: _start

To see a conventional struct-style Debug representation, use "{:#?}".

Error {
    msg: "Failed to read instrs from ./path/to/instrs.json",
    source: Os {
        code: 2,
        kind: NotFound,
        message: "No such file or directory",
    },
}

If none of the built-in representations are appropriate and you would prefer to render the error and its cause chain yourself, it can be done by defining your own EyreHandler and hook to use it.

Implementations

impl Report

pub fn new<E>(error: E) -> Self where
    E: StdError + Send + Sync + 'static, 

Create a new error object from any error type.

The error type must be threadsafe and 'static, so that the Report will be as well.

If the error type does not provide a backtrace, a backtrace will be created here to ensure that a backtrace exists.

pub fn msg<M>(message: M) -> Self where
    M: Display + Debug + Send + Sync + 'static, 

Create a new error object from a printable error message.

If the argument implements std::error::Error, prefer Report::new instead which preserves the underlying error's cause chain and backtrace. If the argument may or may not implement std::error::Error now or in the future, use eyre!(err) which handles either way correctly.

Report::msg("...") is equivalent to eyre!("...") but occasionally convenient in places where a function is preferable over a macro, such as iterator or stream combinators:

use eyre::{Report, Result};
use futures::stream::{Stream, StreamExt, TryStreamExt};

async fn demo<S>(stream: S) -> Result<Vec<Output>>
where
    S: Stream<Item = Input>,
{
    stream
        .then(ffi::do_some_work) // returns Result<Output, &str>
        .map_err(Report::msg)
        .try_collect()
        .await
}

pub fn wrap_err<D>(self, msg: D) -> Self where
    D: Display + Send + Sync + 'static, 

Create a new error from an error message to wrap the existing error.

For attaching a higher level error message to a Result as it is propagated, the WrapErr extension trait may be more convenient than this function.

The primary reason to use error.wrap_err(...) instead of result.wrap_err(...) via the WrapErr trait would be if the message needs to depend on some data held by the underlying error:

use eyre::Result;
use std::fs::File;
use std::path::Path;

struct ParseError {
    line: usize,
    column: usize,
}

fn parse_impl(file: File) -> Result<T, ParseError> {
    ...
}

pub fn parse(path: impl AsRef<Path>) -> Result<T> {
    let file = File::open(&path)?;
    parse_impl(file).map_err(|error| {
        let message = format!(
            "only the first {} lines of {} are valid",
            error.line, path.as_ref().display(),
        );
        eyre::Report::new(error).wrap_err(message)
    })
}

pub fn chain(&self) -> Chain<'_>

An iterator of the chain of source errors contained by this Report.

This iterator will visit every error in the cause chain of this error object, beginning with the error that this error object was created from.

Example

use eyre::Report;
use std::io;

pub fn underlying_io_error_kind(error: &Report) -> Option<io::ErrorKind> {
    for cause in error.chain() {
        if let Some(io_error) = cause.downcast_ref::<io::Error>() {
            return Some(io_error.kind());
        }
    }
    None
}

pub fn root_cause(&self) -> &(dyn StdError + 'static)

The lowest level cause of this error — this error's cause's cause's cause etc.

The root cause is the last error in the iterator produced by chain().

pub fn is<E>(&self) -> bool where
    E: Display + Debug + Send + Sync + 'static, 

Returns true if E is the type held by this error object.

For errors constructed from messages, this method returns true if E matches the type of the message D or the type of the error on which the message has been attached. For details about the interaction between message and downcasting, see here.

pub fn downcast<E>(self) -> Result<E, Self> where
    E: Display + Debug + Send + Sync + 'static, 

Attempt to downcast the error object to a concrete type.

pub fn downcast_ref<E>(&self) -> Option<&E> where
    E: Display + Debug + Send + Sync + 'static, 

Downcast this error object by reference.

Example

// If the error was caused by redaction, then return a tombstone instead
// of the content.
match root_cause.downcast_ref::<DataStoreError>() {
    Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)),
    None => Err(error),
}

pub fn downcast_mut<E>(&mut self) -> Option<&mut E> where
    E: Display + Debug + Send + Sync + 'static, 

Downcast this error object by mutable reference.

pub fn handler(&self) -> &dyn EyreHandler

Get a reference to the Handler for this Report.

pub fn handler_mut(&mut self) -> &mut dyn EyreHandler

Get a mutable reference to the Handler for this Report.

Methods from Deref<Target = dyn StdError + Send + Sync + 'static>

pub fn is<T>(&self) -> bool where
    T: 'static + Error, 

Returns true if the boxed type is the same as T

pub fn downcast_ref<T>(&self) -> Option<&T> where
    T: 'static + Error, 

Returns some reference to the boxed value if it is of type T, or None if it isn't.

pub fn downcast_mut<T>(&mut self) -> Option<&mut T> where
    T: 'static + Error, 

Returns some mutable reference to the boxed value if it is of type T, or None if it isn't.

pub fn is<T>(&self) -> bool where
    T: 'static + Error, 

Forwards to the method defined on the type dyn Error.

pub fn downcast_ref<T>(&self) -> Option<&T> where
    T: 'static + Error, 

Forwards to the method defined on the type dyn Error.

pub fn downcast_mut<T>(&mut self) -> Option<&mut T> where
    T: 'static + Error, 

Forwards to the method defined on the type dyn Error.

pub fn is<T>(&self) -> bool where
    T: 'static + Error, 

Forwards to the method defined on the type dyn Error.

pub fn downcast_ref<T>(&self) -> Option<&T> where
    T: 'static + Error, 

Forwards to the method defined on the type dyn Error.

pub fn downcast_mut<T>(&mut self) -> Option<&mut T> where
    T: 'static + Error, 

Forwards to the method defined on the type dyn Error.

pub fn chain(&self) -> Chain<'_>

🔬 This is a nightly-only experimental API. (error_iter)

Returns an iterator starting with the current error and continuing with recursively calling Error::source.

If you want to omit the current error and only use its sources, use skip(1).

Examples

#![feature(error_iter)]
use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct A;

#[derive(Debug)]
struct B(Option<Box<dyn Error + 'static>>);

impl fmt::Display for A {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "A")
    }
}

impl fmt::Display for B {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "B")
    }
}

impl Error for A {}

impl Error for B {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        self.0.as_ref().map(|e| e.as_ref())
    }
}

let b = B(Some(Box::new(A)));

// let err : Box<Error> = b.into(); // or
let err = &b as &(dyn Error);

let mut iter = err.chain();

assert_eq!("B".to_string(), iter.next().unwrap().to_string());
assert_eq!("A".to_string(), iter.next().unwrap().to_string());
assert!(iter.next().is_none());
assert!(iter.next().is_none());

Trait Implementations

impl AsRef<dyn Error + 'static + Sync + Send> for Report

fn as_ref(&self) -> &(dyn StdError + Send + Sync + 'static)

Performs the conversion.

impl AsRef<dyn Error + 'static> for Report

fn as_ref(&self) -> &(dyn StdError + 'static)

Performs the conversion.

impl Debug for Report

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Report

type Target = dyn StdError + Send + Sync + 'static

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Report

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Display for Report

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Report

fn drop(&mut self)

Executes the destructor for this type.

impl<E> From<E> for Report where
    E: StdError + Send + Sync + 'static, 

fn from(error: E) -> Self

Performs the conversion.

impl From<Report> for Box<dyn StdError + Send + Sync + 'static>

fn from(error: Report) -> Self

Performs the conversion.

impl From<Report> for Box<dyn StdError + 'static>

fn from(error: Report) -> Self

Performs the conversion.