pub struct Report { /* private fields */ }
Expand description
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 isSend
,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§
source§impl Report
impl Report
sourcepub fn new<E>(error: E) -> Selfwhere
E: StdError + Send + Sync + 'static,
pub fn new<E>(error: E) -> Selfwhere
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.
sourcepub fn msg<M>(message: M) -> Selfwhere
M: Display + Debug + Send + Sync + 'static,
pub fn msg<M>(message: M) -> Selfwhere
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
}
sourcepub fn wrap_err<D>(self, msg: D) -> Selfwhere
D: Display + Send + Sync + 'static,
pub fn wrap_err<D>(self, msg: D) -> Selfwhere
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)
})
}
sourcepub fn chain(&self) -> Chain<'_> ⓘ
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
}
sourcepub fn root_cause(&self) -> &(dyn StdError + 'static)
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()
.
sourcepub fn is<E>(&self) -> boolwhere
E: Display + Debug + Send + Sync + 'static,
pub fn is<E>(&self) -> boolwhere
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.
sourcepub fn downcast<E>(self) -> Result<E, Self>where
E: Display + Debug + Send + Sync + 'static,
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.
sourcepub fn downcast_ref<E>(&self) -> Option<&E>where
E: Display + Debug + Send + Sync + 'static,
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),
}
sourcepub fn downcast_mut<E>(&mut self) -> Option<&mut E>where
E: Display + Debug + Send + Sync + 'static,
pub fn downcast_mut<E>(&mut self) -> Option<&mut E>where
E: Display + Debug + Send + Sync + 'static,
Downcast this error object by mutable reference.
sourcepub fn handler(&self) -> &dyn EyreHandler
pub fn handler(&self) -> &dyn EyreHandler
Get a reference to the Handler for this Report.
sourcepub fn handler_mut(&mut self) -> &mut dyn EyreHandler
pub fn handler_mut(&mut self) -> &mut dyn EyreHandler
Get a mutable reference to the Handler for this Report.