itsscb/eyre
1
0
Fork 0
mirror of https://github.com/eyre-rs/eyre.git synced 2025-09-27 13:01:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rename ErrReport to Report (#9)

Browse Source 
* Rename ErrReport to Report

* bump versions to prep for a release
This commit is contained in:
Jane Lusby 2020-04-13 09:10:30 -07:00 committed by GitHub
parent 6b601f8215
commit e3bf56ef5c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 154 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Cargo.toml
View File

@ -1,6 +1,6 @@
[package]
name = "eyre"
version = "0.3.7" # remember to update html_root_url
version = "0.3.8" # remember to update html_root_url
authors = ["David Tolnay <dtolnay@gmail.com>", "Jane Lusby <jlusby42@gmail.com>"]
edition = "2018"
license = "MIT OR Apache-2.0"

28
README.md
View File

@ -5,7 +5,7 @@ Eyre
[![Latest Version](https://img.shields.io/crates/v/eyre.svg)](https://crates.io/crates/eyre)
[![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/eyre)
This library provides [`eyre::ErrReport`][ErrReport], a trait object based
This library provides [`eyre::Report`][Report], a trait object based
error handling type for easy idiomatic error handling and reporting in Rust
applications.
@ -31,7 +31,7 @@ The main changes this crate brings to anyhow are
describing it as an error type in its own right. What is and isn't an error
is a fuzzy concept, for the purposes of this crate though errors are types
that implement `std::error::Error`, and you'll notice that this trait
implementation is conspicuously absent on `ErrReport`. Instead it contains
implementation is conspicuously absent on `Report`. Instead it contains
errors that it masqerades as, and provides helpers for creating new errors to
wrap those errors and for displaying those chains of errors, and the included
context, to the end user. The goal is to make it obvious that this type is
@ -41,7 +41,7 @@ The main changes this crate brings to anyhow are
that it is unrelated to the [`eyre::EyreContext`] trait and member, and is
only for inserting new errors into the chain of errors.
* Addition of new context helpers `member_ref`/`member_mut` on `EyreContext`
and `context`/`context_mut` on `ErrReport` for working with the custom
and `context`/`context_mut` on `Report` for working with the custom
context and extracting forms of context based on their type independent of
the type of the custom context.
@ -83,7 +83,7 @@ fn default(error: &(dyn StdError + 'static)) -> Self {
-> fmt Result` and optionally `display` - For formatting the entire error
chain and the user provided context.
When overriding the context it no longer makes sense for `eyre::ErrReport` to
When overriding the context it no longer makes sense for `eyre::Report` to
provide the `Display` and `Debug` implementations for the user, becase we
cannot predict what forms of context you will need to display along side your
chain of errors. Instead we forward the implementations of `Display` and
@ -108,11 +108,11 @@ implementations of `display` and `debug` on `eyre::DefaultContext`
getting a mutable reference in the same way.
This method is like a flexible version of the `fn backtrace(&self)` method on
the `Error` trait. The main `ErrReport` type provides versions of these methods
the `Error` trait. The main `Report` type provides versions of these methods
that use type inference to get the typeID that should be used by inner trait fn
to pick a member to return.
**Note**: The `backtrace()` fn on `ErrReport` relies on the implementation of
**Note**: The `backtrace()` fn on `Report` relies on the implementation of
this function to get the backtrace from the user provided context if one
exists. If you wish your type to guaruntee that it captures a backtrace for any
error it wraps you **must** implement `member_ref` and provide a path to return
@ -135,17 +135,17 @@ application by defining a type alias.
```rust
type ErrReport = eyre::ErrReport<MyContext>;
type Report = eyre::Report<MyContext>;
// And optionally...
type Result<T, E = eyre::ErrReport<MyContext>> = core::result::Result<T, E>;
type Result<T, E = eyre::Report<MyContext>> = core::result::Result<T, E>;
```
<br>
## Details
- Use `Result<T, eyre::ErrReport>`, or equivalently `eyre::Result<T>`, as the
- Use `Result<T, eyre::Report>`, or equivalently `eyre::Result<T>`, as the
return type of any fallible function.
Within the function, use `?` to easily propagate any error that implements the
@ -224,7 +224,7 @@ type Result<T, E = eyre::ErrReport<MyContext>> = core::result::Result<T, E>;
```
- One-off error messages can be constructed using the `eyre!` macro, which
supports string interpolation and produces an `eyre::ErrReport`.
supports string interpolation and produces an `eyre::Report`.
```rust
return Err(eyre!("Missing attribute: {}", missing));
@ -249,14 +249,14 @@ eyre = { version = "0.3", default-features = false }
Since the `?`-based error conversions would normally rely on the
`std::error::Error` trait which is only available through std, no_std mode will
require an explicit `.map_err(ErrReport::msg)` when working with a non-Eyre error
require an explicit `.map_err(Report::msg)` when working with a non-Eyre error
type inside a function that returns Eyre's error type.
<br>
## Comparison to failure
The `eyre::ErrReport` type works something like `failure::Error`, but unlike
The `eyre::Report` type works something like `failure::Error`, but unlike
failure ours is built around the standard library's `std::error::Error` trait
rather than a separate trait `failure::Fail`. The standard library has adopted
the necessary improvements for this to be possible as part of [RFC 2504].
@ -298,9 +298,9 @@ via your return type or a type annotation.
let val = get_optional_val.ok_or_else(|| eyre!("failed to get value)).unwrap();
// Works
let val: ErrReport = get_optional_val.ok_or_else(|| eyre!("failed to get value)).unwrap();
let val: Report = get_optional_val.ok_or_else(|| eyre!("failed to get value)).unwrap();
```
[ErrReport]: https://docs.rs/eyre/*/eyre/struct.ErrReport.html
[Report]: https://docs.rs/eyre/*/eyre/struct.Report.html
[`eyre::EyreContext`]: https://docs.rs/eyre/*/eyre/trait.EyreContext.html
[`eyre::WrapErr`]: https://docs.rs/eyre/*/eyre/trait.WrapErr.html
[`anyhow::Context`]: https://docs.rs/anyhow/*/anyhow/trait.Context.html

18
src/context.rs
View File

@ -1,5 +1,5 @@
use crate::error::ContextError;
use crate::{ErrReport, EyreContext, StdError, WrapErr};
use crate::{EyreContext, Report, StdError, WrapErr};
use core::fmt::{self, Debug, Display, Write};
#[cfg(backtrace)]
@ -12,7 +12,7 @@ mod ext {
where
C: EyreContext,
{
fn ext_report<D>(self, msg: D) -> ErrReport<C>
fn ext_report<D>(self, msg: D) -> Report<C>
where
D: Display + Send + Sync + 'static;
}
@ -23,19 +23,19 @@ mod ext {
C: EyreContext,
E: std::error::Error + Send + Sync + 'static,
{
fn ext_report<D>(self, msg: D) -> ErrReport<C>
fn ext_report<D>(self, msg: D) -> Report<C>
where
D: Display + Send + Sync + 'static,
{
ErrReport::from_msg(msg, self)
Report::from_msg(msg, self)
}
}
impl<C> StdError<C> for ErrReport<C>
impl<C> StdError<C> for Report<C>
where
C: EyreContext,
{
fn ext_report<D>(self, msg: D) -> ErrReport<C>
fn ext_report<D>(self, msg: D) -> Report<C>
where
D: Display + Send + Sync + 'static,
{
@ -49,14 +49,14 @@ where
C: EyreContext,
E: ext::StdError<C> + Send + Sync + 'static,
{
fn wrap_err<D>(self, msg: D) -> Result<T, ErrReport<C>>
fn wrap_err<D>(self, msg: D) -> Result<T, Report<C>>
where
D: Display + Send + Sync + 'static,
{
self.map_err(|error| error.ext_report(msg))
}
fn wrap_err_with<D, F>(self, msg: F) -> Result<T, ErrReport<C>>
fn wrap_err_with<D, F>(self, msg: F) -> Result<T, Report<C>>
where
D: Display + Send + Sync + 'static,
F: FnOnce() -> D,
@ -102,7 +102,7 @@ where
}
}
impl<D, C> StdError for ContextError<D, ErrReport<C>>
impl<D, C> StdError for ContextError<D, Report<C>>
where
C: EyreContext,
D: Display,

100
src/error.rs
View File

@ -1,7 +1,7 @@
use crate::alloc::Box;
use crate::chain::Chain;
use crate::EyreContext;
use crate::{ErrReport, StdError};
use crate::{Report, StdError};
use core::any::Any;
use core::any::TypeId;
use core::fmt::{self, Debug, Display};
@ -14,13 +14,13 @@ use crate::backtrace::Backtrace;
#[cfg(feature = "std")]
use core::ops::{Deref, DerefMut};
impl<C> ErrReport<C>
impl<C> Report<C>
where
C: EyreContext,
{
/// Create a new error object from any error type.
///
/// The error type must be threadsafe and `'static`, so that the `ErrReport`
/// 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
@ -30,18 +30,18 @@ where
where
E: StdError + Send + Sync + 'static,
{
ErrReport::from_std(error)
Report::from_std(error)
}
/// Create a new error object from a printable error message.
///
/// If the argument implements std::error::Error, prefer `ErrReport::new`
/// 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.
///
/// `ErrReport::msg("...")` is equivalent to `eyre!("...")` but occasionally
/// `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:
///
@ -56,7 +56,7 @@ where
/// #
/// # use ffi::{Input, Output};
/// #
/// use eyre::{ErrReport, Result};
/// use eyre::{Report, Result};
/// use futures::stream::{Stream, StreamExt, TryStreamExt};
///
/// async fn demo<S>(stream: S) -> Result<Vec<Output>>
@ -65,7 +65,7 @@ where
/// {
/// stream
/// .then(ffi::do_some_work) // returns Result<Output, &str>
/// .map_err(ErrReport::msg)
/// .map_err(Report::msg)
/// .try_collect()
/// .await
/// }
@ -74,7 +74,7 @@ where
where
M: Display + Debug + Send + Sync + 'static,
{
ErrReport::from_adhoc(message)
Report::from_adhoc(message)
}
#[cfg(feature = "std")]
@ -94,7 +94,7 @@ where
// Safety: passing vtable that operates on the right type E.
let context = Some(C::default(&error));
unsafe { ErrReport::construct(error, vtable, context) }
unsafe { Report::construct(error, vtable, context) }
}
pub(crate) fn from_adhoc<M>(message: M) -> Self
@ -116,7 +116,7 @@ where
// Safety: MessageError is repr(transparent) so it is okay for the
// vtable to allow casting the MessageError<M> to M.
let context = Some(C::default(&error));
unsafe { ErrReport::construct(error, vtable, context) }
unsafe { Report::construct(error, vtable, context) }
}
#[cfg(feature = "std")]
@ -139,7 +139,7 @@ where
// Safety: passing vtable that operates on the right type.
let context = Some(C::default(&error));
unsafe { ErrReport::construct(error, vtable, context) }
unsafe { Report::construct(error, vtable, context) }
}
#[cfg(feature = "std")]
@ -159,7 +159,7 @@ where
// Safety: BoxedError is repr(transparent) so it is okay for the vtable
// to allow casting to Box<dyn StdError + Send + Sync>.
unsafe { ErrReport::construct(error, vtable, context) }
unsafe { Report::construct(error, vtable, context) }
}
// Takes backtrace as argument rather than capturing it here so that the
@ -184,7 +184,7 @@ where
// caller rather than a builtin fat pointer vtable.
let erased = mem::transmute::<Box<ErrorImpl<E, C>>, Box<ErrorImpl<(), C>>>(inner);
let inner = ManuallyDrop::new(erased);
ErrReport { inner }
Report { inner }
}
/// Create a new error from an error message to wrap the existing error.
@ -236,7 +236,7 @@ where
/// "only the first {} lines of {} are valid",
/// error.line, path.as_ref().display(),
/// );
/// eyre::ErrReport::new(error).wrap_err(message)
/// eyre::Report::new(error).wrap_err(message)
/// })
/// }
/// ```
@ -245,23 +245,23 @@ where
D: Display + Send + Sync + 'static,
{
let context = self.inner.context.take();
let error: ContextError<D, ErrReport<C>> = ContextError { msg, error: self };
let error: ContextError<D, Report<C>> = ContextError { msg, error: self };
let vtable = &ErrorVTable {
object_drop: object_drop::<ContextError<D, ErrReport<C>>, C>,
object_ref: object_ref::<ContextError<D, ErrReport<C>>, C>,
object_drop: object_drop::<ContextError<D, Report<C>>, C>,
object_ref: object_ref::<ContextError<D, Report<C>>, C>,
#[cfg(feature = "std")]
object_mut: object_mut::<ContextError<D, ErrReport<C>>, C>,
object_boxed: object_boxed::<ContextError<D, ErrReport<C>>, C>,
object_mut: object_mut::<ContextError<D, Report<C>>, C>,
object_boxed: object_boxed::<ContextError<D, Report<C>>, C>,
object_downcast: context_chain_downcast::<D, C>,
object_drop_rest: context_chain_drop_rest::<D, C>,
};
// Safety: passing vtable that operates on the right type.
unsafe { ErrReport::construct(error, vtable, context) }
unsafe { Report::construct(error, vtable, context) }
}
/// Get the backtrace for this ErrReport.
/// Get the backtrace for this Report.
///
/// Backtraces are only available on the nightly channel. Tracking issue:
/// [rust-lang/rust#53487][tracking].
@ -277,7 +277,7 @@ where
self.inner.backtrace()
}
/// An iterator of the chain of source errors contained by this ErrReport.
/// 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
@ -286,10 +286,10 @@ where
/// # Example
///
/// ```
/// use eyre::ErrReport;
/// use eyre::Report;
/// use std::io;
///
/// pub fn underlying_io_error_kind(error: &ErrReport) -> Option<io::ErrorKind> {
/// 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());
@ -307,7 +307,7 @@ where
/// cause's cause etc.
///
/// The root cause is the last error in the iterator produced by
/// [`chain()`][ErrReport::chain].
/// [`chain()`][Report::chain].
#[cfg(feature = "std")]
pub fn root_cause(&self) -> &(dyn StdError + 'static) {
let mut chain = self.chain();
@ -354,7 +354,7 @@ where
let error = ptr::read(addr.cast::<E>().as_ptr());
// Read Box<ErrorImpl<()>> from self. Can't move it out because
// ErrReport has a Drop impl which we want to not run.
// Report has a Drop impl which we want to not run.
let inner = ptr::read(&outer.inner);
let erased = ManuallyDrop::into_inner(inner);
@ -370,7 +370,7 @@ where
/// # Example
///
/// ```
/// # use eyre::{ErrReport, eyre};
/// # use eyre::{Report, eyre};
/// # use std::fmt::{self, Display};
/// # use std::task::Poll;
/// #
@ -389,7 +389,7 @@ where
/// #
/// # const REDACTED_CONTENT: () = ();
/// #
/// # let error: ErrReport = eyre!("...");
/// # let error: Report = eyre!("...");
/// # let root_cause = &error;
/// #
/// # let ret =
@ -446,18 +446,18 @@ where
}
#[cfg(feature = "std")]
impl<E, C> From<E> for ErrReport<C>
impl<E, C> From<E> for Report<C>
where
C: EyreContext,
E: StdError + Send + Sync + 'static,
{
fn from(error: E) -> Self {
ErrReport::from_std(error)
Report::from_std(error)
}
}
#[cfg(feature = "std")]
impl<C: EyreContext> Deref for ErrReport<C> {
impl<C: EyreContext> Deref for Report<C> {
type Target = dyn StdError + Send + Sync + 'static;
fn deref(&self) -> &Self::Target {
@ -466,25 +466,25 @@ impl<C: EyreContext> Deref for ErrReport<C> {
}
#[cfg(feature = "std")]
impl<C: EyreContext> DerefMut for ErrReport<C> {
impl<C: EyreContext> DerefMut for Report<C> {
fn deref_mut(&mut self) -> &mut Self::Target {
self.inner.error_mut()
}
}
impl<C: EyreContext> Display for ErrReport<C> {
impl<C: EyreContext> Display for Report<C> {
fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
self.inner.display(formatter)
}
}
impl<C: EyreContext> Debug for ErrReport<C> {
impl<C: EyreContext> Debug for Report<C> {
fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
self.inner.debug(formatter)
}
}
impl<C> Drop for ErrReport<C>
impl<C> Drop for Report<C>
where
C: EyreContext,
{
@ -633,7 +633,7 @@ where
}
}
// Safety: requires layout of *e to match ErrorImpl<ContextError<D, ErrReport>>.
// Safety: requires layout of *e to match ErrorImpl<ContextError<D, Report>>.
unsafe fn context_chain_downcast<D, C>(e: &ErrorImpl<(), C>, target: TypeId) -> Option<NonNull<()>>
where
C: EyreContext,
@ -641,19 +641,19 @@ where
{
if TypeId::of::<D>() == target {
let unerased =
e as *const ErrorImpl<(), C> as *const ErrorImpl<ContextError<D, ErrReport<C>>, C>;
e as *const ErrorImpl<(), C> as *const ErrorImpl<ContextError<D, Report<C>>, C>;
let addr = &(*unerased)._object.msg as *const D as *mut ();
Some(NonNull::new_unchecked(addr))
} else {
// Recurse down the context chain per the inner error's vtable.
let unerased =
e as *const ErrorImpl<(), C> as *const ErrorImpl<ContextError<D, ErrReport<C>>, C>;
e as *const ErrorImpl<(), C> as *const ErrorImpl<ContextError<D, Report<C>>, C>;
let source = &(*unerased)._object.error;
(source.inner.vtable.object_downcast)(&source.inner, target)
}
}
// Safety: requires layout of *e to match ErrorImpl<ContextError<D, ErrReport>>.
// Safety: requires layout of *e to match ErrorImpl<ContextError<D, Report>>.
unsafe fn context_chain_drop_rest<D, C>(e: Box<ErrorImpl<(), C>>, target: TypeId)
where
C: EyreContext,
@ -664,14 +664,14 @@ where
if TypeId::of::<D>() == target {
let unerased = mem::transmute::<
Box<ErrorImpl<(), C>>,
Box<ErrorImpl<ContextError<ManuallyDrop<D>, ErrReport<C>>, C>>,
Box<ErrorImpl<ContextError<ManuallyDrop<D>, Report<C>>, C>>,
>(e);
// Drop the entire rest of the data structure rooted in the next ErrReport.
// Drop the entire rest of the data structure rooted in the next Report.
drop(unerased);
} else {
let unerased = mem::transmute::<
Box<ErrorImpl<(), C>>,
Box<ErrorImpl<ContextError<D, ManuallyDrop<ErrReport<C>>>, C>>,
Box<ErrorImpl<ContextError<D, ManuallyDrop<Report<C>>>, C>>,
>(e);
// Read out a ManuallyDrop<Box<ErrorImpl<()>>> from the next error.
let inner = ptr::read(&unerased._object.error.inner);
@ -798,12 +798,12 @@ where
}
}
impl<C: EyreContext> From<ErrReport<C>> for Box<dyn StdError + Send + Sync + 'static> {
fn from(error: ErrReport<C>) -> Self {
impl<C: EyreContext> From<Report<C>> for Box<dyn StdError + Send + Sync + 'static> {
fn from(error: Report<C>) -> Self {
let outer = ManuallyDrop::new(error);
unsafe {
// Read Box<ErrorImpl<()>> from error. Can't move it out because
// ErrReport has a Drop impl which we want to not run.
// Report has a Drop impl which we want to not run.
let inner = ptr::read(&outer.inner);
let erased = ManuallyDrop::into_inner(inner);
@ -814,21 +814,21 @@ impl<C: EyreContext> From<ErrReport<C>> for Box<dyn StdError + Send + Sync + 'st
}
}
impl<C: EyreContext> From<ErrReport<C>> for Box<dyn StdError + 'static> {
fn from(error: ErrReport<C>) -> Self {
impl<C: EyreContext> From<Report<C>> for Box<dyn StdError + 'static> {
fn from(error: Report<C>) -> Self {
Box::<dyn StdError + Send + Sync>::from(error)
}
}
#[cfg(feature = "std")]
impl<C: EyreContext> AsRef<dyn StdError + Send + Sync> for ErrReport<C> {
impl<C: EyreContext> AsRef<dyn StdError + Send + Sync> for Report<C> {
fn as_ref(&self) -> &(dyn StdError + Send + Sync + 'static) {
&**self
}
}
#[cfg(feature = "std")]
impl<C: EyreContext> AsRef<dyn StdError> for ErrReport<C> {
impl<C: EyreContext> AsRef<dyn StdError> for Report<C> {
fn as_ref(&self) -> &(dyn StdError + 'static) {
&**self
}

26
src/kind.rs
View File

@ -1,21 +1,21 @@
// Tagged dispatch mechanism for resolving the behavior of `eyre!($expr)`.
//
// When eyre! is given a single expr argument to turn into eyre::ErrReport, we
// want the resulting ErrReport to pick up the input's implementation of source()
// When eyre! is given a single expr argument to turn into eyre::Report, we
// want the resulting Report to pick up the input's implementation of source()
// and backtrace() if it has a std::error::Error impl, otherwise require nothing
// more than Display and Debug.
//
// Expressed in terms of specialization, we want something like:
//
// trait EyreNew {
// fn new(self) -> ErrReport;
// fn new(self) -> Report;
// }
//
// impl<T> EyreNew for T
// where
// T: Display + Debug + Send + Sync + 'static,
// {
// default fn new(self) -> ErrReport {
// default fn new(self) -> Report {
// /* no std error impl */
// }
// }
@ -24,7 +24,7 @@
// where
// T: std::error::Error + Send + Sync + 'static,
// {
// fn new(self) -> ErrReport {
// fn new(self) -> Report {
// /* use std error's source() and backtrace() */
// }
// }
@ -44,7 +44,7 @@
// let error = $msg;
// (&error).eyre_kind().new(error)
use crate::{ErrReport, EyreContext};
use crate::{EyreContext, Report};
use core::fmt::{Debug, Display};
#[cfg(feature = "std")]
@ -65,11 +65,11 @@ pub trait AdhocKind: Sized {
impl<T> AdhocKind for &T where T: ?Sized + Display + Debug + Send + Sync + 'static {}
impl Adhoc {
pub fn new<M, C: EyreContext>(self, message: M) -> ErrReport<C>
pub fn new<M, C: EyreContext>(self, message: M) -> Report<C>
where
M: Display + Debug + Send + Sync + 'static,
{
ErrReport::from_adhoc(message)
Report::from_adhoc(message)
}
}
@ -82,12 +82,12 @@ pub trait TraitKind: Sized {
}
}
impl<E> TraitKind for E where E: Into<ErrReport> {}
impl<E> TraitKind for E where E: Into<Report> {}
impl Trait {
pub fn new<E>(self, error: E) -> ErrReport
pub fn new<E>(self, error: E) -> Report
where
E: Into<ErrReport>,
E: Into<Report>,
{
error.into()
}
@ -109,7 +109,7 @@ impl BoxedKind for Box<dyn StdError + Send + Sync> {}
#[cfg(feature = "std")]
impl Boxed {
pub fn new<C: EyreContext>(self, error: Box<dyn StdError + Send + Sync>) -> ErrReport<C> {
ErrReport::from_boxed(error)
pub fn new<C: EyreContext>(self, error: Box<dyn StdError + Send + Sync>) -> Report<C> {
Report::from_boxed(error)
}
}

68
src/lib.rs
View File

@ -1,4 +1,4 @@
//! This library provides [`eyre::ErrReport`][ErrReport], a trait object based error
//! This library provides [`eyre::Report`][Report], a trait object based error
//! type for easy idiomatic error handling in Rust applications.
//!
//! This crate is a fork of [`anyhow`] by @dtolnay. By default this crate does not
@ -23,7 +23,7 @@
//! describing it as an error type in its own right. What is and isn't an error
//! is a fuzzy concept, for the purposes of this crate though errors are types
//! that implement `std::error::Error`, and you'll notice that this trait
//! implementation is conspicuously absent on `ErrReport`. Instead it contains
//! implementation is conspicuously absent on `Report`. Instead it contains
//! errors that it masqerades as, and provides helpers for creating new errors to
//! wrap those errors and for displaying those chains of errors, and the included
//! context, to the end user. The goal is to make it obvious that this type is
@ -33,7 +33,7 @@
//! that it is unrelated to the [`eyre::EyreContext`] trait and member, and is
//! only for inserting new errors into the chain of errors.
//! * Addition of new context helpers on `EyreContext` (`member_ref`/`member_mut`)
//! and `context`/`context_mut` on `ErrReport` for working with the custom
//! and `context`/`context_mut` on `Report` for working with the custom
//! context and extracting forms of context based on their type independent of
//! the type of the custom context.
//!
@ -75,7 +75,7 @@
//! -> fmt Result` and optionally `display`. - For formatting the entire
//! error chain and the user provided context.
//!
//! When overriding the context it no longer makes sense for `eyre::ErrReport` to
//! When overriding the context it no longer makes sense for `eyre::Report` to
//! provide the `Display` and `Debug` implementations for the user, becase we
//! cannot predict what forms of context you will need to display along side your
//! chain of errors. Instead we forward the implementations of `Display` and
@ -100,11 +100,11 @@
//! getting a mutable reference in the same way.
//!
//! This method is like a flexible version of the `fn backtrace(&self)` method on
//! the `Error` trait. The main `ErrReport` type provides versions of these methods
//! the `Error` trait. The main `Report` type provides versions of these methods
//! that use type inference to get the typeID that should be used by inner trait fn
//! to pick a member to return.
//!
//! **Note**: The `backtrace()` fn on `ErrReport` relies on the implementation of
//! **Note**: The `backtrace()` fn on `Report` relies on the implementation of
//! this function to get the backtrace from the user provided context if one
//! exists. If you wish your type to guaruntee that it captures a backtrace for any
//! error it wraps you **must** implement `member_ref` and provide a path to return
@ -127,20 +127,20 @@
//!
//!
//! ```rust,compile_fail
//! type ErrReport = eyre::ErrReport<MyContext>;
//! type Report = eyre::Report<MyContext>;
//!
//! // And optionally...
//! type Result<T, E = eyre::ErrReport<MyContext>> = core::result::Result<T, E>;
//! type Result<T, E = eyre::Report<MyContext>> = core::result::Result<T, E>;
//! ```
//! <br>
//!
//! # Details
//!
//! - Use `Result<T, eyre::ErrReport>`, or equivalently `eyre::Result<T>`, as
//! - Use `Result<T, eyre::Report>`, or equivalently `eyre::Result<T>`, as
//! the return type of any fallible function.
//!
//! Within the function, use `?` to easily propagate any error that implements
//! the `std::error::ErrReport` trait.
//! the `std::error::Report` trait.
//!
//! ```
//! # pub trait Deserialize {}
@ -218,7 +218,7 @@
//! mutable reference as needed.
//!
//! ```
//! # use eyre::{ErrReport, eyre};
//! # use eyre::{Report, eyre};
//! # use std::fmt::{self, Display};
//! # use std::task::Poll;
//! #
@ -237,7 +237,7 @@
//! #
//! # const REDACTED_CONTENT: () = ();
//! #
//! # let error: ErrReport = eyre!("...");
//! # let error: Report = eyre!("...");
//! # let root_cause = &error;
//! #
//! # let ret =
@ -277,7 +277,7 @@
//! ```
//!
//! - One-off error messages can be constructed using the `eyre!` macro, which
//! supports string interpolation and produces an `eyre::ErrReport`.
//! supports string interpolation and produces an `eyre::Report`.
//!
//! ```
//! # use eyre::{eyre, Result};
@ -303,18 +303,18 @@
//! ```
//!
//! Since the `?`-based error conversions would normally rely on the
//! `std::error::ErrReport` trait which is only available through std, no_std mode
//! will require an explicit `.map_err(ErrReport::msg)` when working with a
//! `std::error::Report` trait which is only available through std, no_std mode
//! will require an explicit `.map_err(Report::msg)` when working with a
//! non-Eyre error type inside a function that returns Eyre's error type.
//!
//! [ErrReport]: https://docs.rs/eyre/*/eyre/struct.ErrReport.html
//! [Report]: https://docs.rs/eyre/*/eyre/struct.Report.html
//! [`eyre::EyreContext`]: https://docs.rs/eyre/*/eyre/trait.EyreContext.html
//! [`eyre::WrapErr`]: https://docs.rs/eyre/*/eyre/trait.WrapErr.html
//! [`anyhow::Context`]: https://docs.rs/anyhow/*/anyhow/trait.Context.html
//! [`anyhow`]: https://github.com/dtolnay/anyhow
//! [`tracing_error::SpanTrace`]: https://docs.rs/tracing-error/*/tracing-error/struct.SpanTrace.html
#![doc(html_root_url = "https://docs.rs/eyre/0.3.7")]
#![doc(html_root_url = "https://docs.rs/eyre/0.3.8")]
#![cfg_attr(backtrace, feature(backtrace))]
#![cfg_attr(not(feature = "std"), no_std)]
#![allow(
@ -371,16 +371,18 @@ pub trait StdError: Debug + Display {
}
pub use eyre as format_err;
#[doc(hidden)]
pub use Report as ErrReport;
/// The `ErrReport` type, a wrapper around a dynamic error type.
/// The core error reporting type of the library, a wrapper around a dynamic error reporting type.
///
/// `ErrReport` works a lot like `Box<dyn std::error::Error>`, but with these
/// `Report` works a lot like `Box<dyn std::error::Error>`, but with these
/// differences:
///
/// - `ErrReport` requires that the error is `Send`, `Sync`, and `'static`.
/// - `ErrReport` guarantees that a backtrace is available, even if the underlying
/// - `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.
/// - `ErrReport` is represented as a narrow pointer &mdash; exactly one word in
/// - `Report` is represented as a narrow pointer &mdash; exactly one word in
/// size instead of two.
///
/// <br>
@ -389,7 +391,7 @@ pub use eyre as format_err;
///
/// 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::ErrReport.
/// impl of the error from which you constructed your eyre::Report.
///
/// ```console
/// Failed to read instrs from ./path/to/instrs.json
@ -463,7 +465,7 @@ pub use eyre as format_err;
/// # Ok(())
/// }
/// ```
pub struct ErrReport<C = DefaultContext>
pub struct Report<C = DefaultContext>
where
C: EyreContext,
{
@ -576,15 +578,15 @@ impl EyreContext for DefaultContext {
/// Iterator of a chain of source errors.
///
/// This type is the iterator returned by [`ErrReport::chain`].
/// This type is the iterator returned by [`Report::chain`].
///
/// # Example
///
/// ```
/// use eyre::ErrReport;
/// use eyre::Report;
/// use std::io;
///
/// pub fn underlying_io_error_kind(error: &ErrReport) -> Option<io::ErrorKind> {
/// 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());
@ -647,7 +649,7 @@ pub struct Chain<'a> {
/// Ok(())
/// }
/// ```
pub type Result<T, E = ErrReport<DefaultContext>> = core::result::Result<T, E>;
pub type Result<T, E = Report<DefaultContext>> = core::result::Result<T, E>;
/// Provides the `wrap_err` method for `Result`.
///
@ -794,13 +796,13 @@ where
C: EyreContext,
{
/// Wrap the error value with a new adhoc error
fn wrap_err<D>(self, msg: D) -> Result<T, ErrReport<C>>
fn wrap_err<D>(self, msg: D) -> Result<T, Report<C>>
where
D: Display + Send + Sync + 'static;
/// Wrap the error value with a new adhoc error that is evaluated lazily
/// only once an error does occur.
fn wrap_err_with<D, F>(self, f: F) -> Result<T, ErrReport<C>>
fn wrap_err_with<D, F>(self, f: F) -> Result<T, Report<C>>
where
D: Display + Send + Sync + 'static,
F: FnOnce() -> D;
@ -809,7 +811,7 @@ where
// Not public API. Referenced by macro-generated code.
#[doc(hidden)]
pub mod private {
use crate::{ErrReport, EyreContext};
use crate::{EyreContext, Report};
use core::fmt::{Debug, Display};
// #[cfg(backtrace)]
@ -825,11 +827,11 @@ pub mod private {
pub use crate::kind::BoxedKind;
}
pub fn new_adhoc<M, C>(message: M) -> ErrReport<C>
pub fn new_adhoc<M, C>(message: M) -> Report<C>
where
C: EyreContext,
M: Display + Debug + Send + Sync + 'static,
{
ErrReport::from_adhoc(message)
Report::from_adhoc(message)
}
}

6
tests/test_autotrait.rs
View File

@ -1,13 +1,13 @@
use eyre::ErrReport;
use eyre::Report;
#[test]
fn test_send() {
fn assert_send<T: Send>() {}
assert_send::<ErrReport>();
assert_send::<Report>();
}
#[test]
fn test_sync() {
fn assert_sync<T: Sync>() {}
assert_sync::<ErrReport>();
assert_sync::<Report>();
}

4
tests/test_backtrace.rs
View File

@ -6,8 +6,8 @@ fn test_backtrace() {}
#[rustversion::nightly]
#[test]
fn test_backtrace() {
use eyre::{eyre, ErrReport};
use eyre::{eyre, Report};
let error: ErrReport = eyre!("oh no!");
let error: Report = eyre!("oh no!");
let _ = error.backtrace();
}

4
tests/test_boxed.rs
View File

@ -1,4 +1,4 @@
use eyre::{eyre, ErrReport};
use eyre::{eyre, Report};
use std::error::Error as StdError;
use std::io;
use thiserror::Error;
@ -12,7 +12,7 @@ struct MyError {
#[test]
fn test_boxed_str() {
let error = Box::<dyn StdError + Send + Sync>::from("oh no!");
let error: ErrReport = eyre!(error);
let error: Report = eyre!(error);
assert_eq!("oh no!", error.to_string());
assert_eq!(
"oh no!",

4
tests/test_chain.rs
View File

@ -1,6 +1,6 @@
use eyre::{eyre, ErrReport};
use eyre::{eyre, Report};
fn error() -> ErrReport {
fn error() -> Report {
eyre!(0).wrap_err(1).wrap_err(2).wrap_err(3)
}

6
tests/test_context.rs
View File

@ -1,7 +1,7 @@
mod drop;
use crate::drop::{DetectDrop, Flag};
use eyre::{ErrReport, Result, WrapErr};
use eyre::{Report, Result, WrapErr};
use std::fmt::{self, Display};
use thiserror::Error;
@ -56,7 +56,7 @@ impl Dropped {
}
}
fn make_chain() -> (ErrReport, Dropped) {
fn make_chain() -> (Report, Dropped) {
let dropped = Dropped {
low: Flag::new(),
mid: Flag::new(),
@ -77,7 +77,7 @@ fn make_chain() -> (ErrReport, Dropped) {
.unwrap_err();
// impl Report for Result<T, Error>
let high = Err::<(), ErrReport>(mid)
let high = Err::<(), Report>(mid)
.wrap_err(HighLevel {
message: "failed to start server",
drop: DetectDrop::new(&dropped.high),

4
tests/test_convert.rs
View File

@ -1,13 +1,13 @@
mod drop;
use self::drop::{DetectDrop, Flag};
use eyre::{ErrReport, Result};
use eyre::{Report, Result};
use std::error::Error as StdError;
#[test]
fn test_convert() {
let has_dropped = Flag::new();
let error: ErrReport = ErrReport::new(DetectDrop::new(&has_dropped));
let error: Report = Report::new(DetectDrop::new(&has_dropped));
let box_dyn = Box::<dyn StdError + Send + Sync>::from(error);
assert_eq!("oh no!", box_dyn.to_string());
drop(box_dyn);

6
tests/test_downcast.rs
View File

@ -3,7 +3,7 @@ mod drop;
use self::common::*;
use self::drop::{DetectDrop, Flag};
use eyre::{DefaultContext, ErrReport};
use eyre::{DefaultContext, Report};
use std::error::Error as StdError;
use std::fmt::{self, Display};
use std::io;
@ -71,7 +71,7 @@ fn test_downcast_mut() {
#[test]
fn test_drop() {
let has_dropped = Flag::new();
let error: ErrReport = ErrReport::new(DetectDrop::new(&has_dropped));
let error: Report = Report::new(DetectDrop::new(&has_dropped));
drop(error.downcast::<DetectDrop>().unwrap());
assert!(has_dropped.get());
}
@ -90,7 +90,7 @@ fn test_large_alignment() {
impl StdError for LargeAlignedError {}
let error: ErrReport<DefaultContext> = ErrReport::new(LargeAlignedError("oh no!"));
let error: Report<DefaultContext> = Report::new(LargeAlignedError("oh no!"));
assert_eq!(
"oh no!",
error.downcast_ref::<LargeAlignedError>().unwrap().0

12
tests/test_repr.rs
View File

@ -2,19 +2,19 @@ mod drop;
use self::drop::{DetectDrop, Flag};
use eyre::DefaultContext;
use eyre::ErrReport;
use eyre::Report;
use std::marker::Unpin;
use std::mem;
#[test]
fn test_error_size() {
assert_eq!(mem::size_of::<ErrReport>(), mem::size_of::<usize>());
assert_eq!(mem::size_of::<Report>(), mem::size_of::<usize>());
}
#[test]
fn test_null_pointer_optimization() {
assert_eq!(
mem::size_of::<Result<(), ErrReport>>(),
mem::size_of::<Result<(), Report>>(),
mem::size_of::<usize>()
);
}
@ -22,14 +22,12 @@ fn test_null_pointer_optimization() {
#[test]
fn test_autotraits() {
fn assert<E: Unpin + Send + Sync + 'static>() {}
assert::<ErrReport>();
assert::<Report>();
}
#[test]
fn test_drop() {
let has_dropped = Flag::new();
drop(ErrReport::<DefaultContext>::new(DetectDrop::new(
&has_dropped,
)));
drop(Report::<DefaultContext>::new(DetectDrop::new(&has_dropped)));
assert!(has_dropped.get());
}

14
tests/test_source.rs
View File

@ -1,4 +1,4 @@
use eyre::{eyre, ErrReport};
use eyre::{eyre, Report};
use std::error::Error as StdError;
use std::fmt::{self, Display};
use std::io;
@ -26,37 +26,37 @@ impl StdError for TestError {
#[test]
fn test_literal_source() {
let error: ErrReport = eyre!("oh no!");
let error: Report = eyre!("oh no!");
assert!(error.source().is_none());
}
#[test]
fn test_variable_source() {
let msg = "oh no!";
let error: ErrReport = eyre!(msg);
let error: Report = eyre!(msg);
assert!(error.source().is_none());
let msg = msg.to_owned();
let error: ErrReport = eyre!(msg);
let error: Report = eyre!(msg);
assert!(error.source().is_none());
}
#[test]
fn test_fmt_source() {
let error: ErrReport = eyre!("{} {}!", "oh", "no");
let error: Report = eyre!("{} {}!", "oh", "no");
assert!(error.source().is_none());
}
#[test]
fn test_io_source() {
let io = io::Error::new(io::ErrorKind::Other, "oh no!");
let error: ErrReport = eyre!(TestError::Io(io));
let error: Report = eyre!(TestError::Io(io));
assert_eq!("oh no!", error.source().unwrap().to_string());
}
#[test]
fn test_eyre_from_eyre() {
let error: ErrReport = eyre!("oh no!").wrap_err("context");
let error: Report = eyre!("oh no!").wrap_err("context");
let error = eyre!(error);
assert_eq!("oh no!", error.source().unwrap().to_string());
}

6
tests/ui/no-impl.stderr
View File

@ -5,17 +5,17 @@ error[E0599]: no method named `eyre_kind` found for reference `&Error` in the cu
| -------------
| |
| doesn't satisfy `Error: eyre::kind::TraitKind`
| doesn't satisfy `Error: std::convert::Into<eyre::ErrReport>`
| doesn't satisfy `Error: std::convert::Into<eyre::Report>`
| doesn't satisfy `Error: std::fmt::Display`
...
7 | let _ = eyre!(Error);
| ^^^^^^^^^^^^ method not found in `&Error`
|
= note: the method `eyre_kind` exists but the following trait bounds were not satisfied:
`Error: std::convert::Into<eyre::ErrReport>`
`Error: std::convert::Into<eyre::Report>`
which is required by `Error: eyre::kind::TraitKind`
`Error: std::fmt::Display`
which is required by `&Error: eyre::kind::AdhocKind`
`&Error: std::convert::Into<eyre::ErrReport>`
`&Error: std::convert::Into<eyre::Report>`
which is required by `&Error: eyre::kind::TraitKind`
= note: this error originates in a macro (in Nightly builds, run with -Z macro-backtrace for more info)