version = "0.3.4" # remember to update html_root_url

version = "0.3.5" # remember to update html_root_url

//! This crate is a fork of [`anyhow`] by @dtolnay. By default this crate does not
//! add any new features that anyhow doesn't already support, though it does rename
//! a number of the APIs to try to make the proper usage more obvious. The magic of
//! this crate is when you need to add extra context to a chain of errors beyond
//! what you can or should insert into the error chain. For an example of a
//! customized version of eyre check out
//! [`jane-eyre`](https://github.com/yaahc/jane-eyre).
//!
//! My goal in writing this crate is to explore new ways to associate context with
//! errors, to cleanly separate the concept of an error and context about an error,
//! and to more clearly communicate the intended usage of this crate via changes to
//! the API.
//!
//! The main changes this crate brings to anyhow are
//!
//! * Addition of the [`eyre::EyreContext`] trait and a type parameter on the core
//!   error handling type which users can use to insert custom forms of context
//!   into their catch-all error handling type.
//! * Rebranding the type as principally for error reporting, rather than
//!   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
//!   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
//!   meant to be used when the only way you expect to handle errors is to print
//!   them.
//! * Changing the [`anyhow::Context`] trait to [`eyre::WrapErr`] to make it clear
//!   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
//!   context and extracting forms of context based on their type independent of
//!   the type of the custom context.
//!
//! These changes were made in order to facilitate the usage of
//! [`tracing_error::SpanTrace`] with anyhow, which is a Backtrace-like type for
//! rendering custom defined runtime context.
//!
//! ```toml
//! [dependencies]
//! eyre = "0.3"
//! ```

//!
//! ## Customization
//!
//! In order to insert your own custom context type you must first implement the
//! `eyre::EyreContext` trait for said type, which has three required methods and
//! two optional methods.

//! ### Required Methods
//!
//! * `fn default(error: &Error) -> Self` - For constructing default context while
//! allowing special case handling depending on the content of the error you're
//! wrapping.
//!
//! This is essentially `Default::default` but more flexible, for example, the
//! `eyre::DefaultContext` type provide by this crate uses this to only capture a
//! `Backtrace` if the inner `Error` does not already have one.
//!
//! ```rust,compile_fail
//! fn default(error: &(dyn StdError + 'static)) -> Self {
//!     let backtrace = backtrace_if_absent!(error);
//!
//!     Self { backtrace }
//! }
//! ```
//!
//! * `fn debug(&self, error: &(dyn Error + 'static), f: &mut fmt::Formatter<'_>) -> fmt Result`
//!   it's companion `display` version. - For formatting the entire error chain and
//!   the user provided context.
//!
//! When overriding the context it no longer makes sense for `eyre::ErrReport` 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
//! `Debug` to these methods on the inner `EyreContext` type.
//!
//! This crate does provide a few helpers to assist in writing display
//! implementations, specifically the `Chain` type, for treating an error and its
//! sources like an iterator, and the `Indented` type, for indenting multi line
//! errors consistently without using heap allocations.
//!
//! **Note**: best practices for printing errors suggest that `{}` should only
//! print the current error and none of its sources, and that the primary method of
//! displaying an error, its sources, and its context should be handled by the
//! `Debug` implementation, which is what is used to print errors that are returned
//! from `main`. For examples on how to implement this please refer to the
//! implementations of `display` and `debug` on `eyre::DefaultContext`
//!
//! ### Optional Methods
//!
//! * `fn member_ref(&self, typeid TypeID) -> Option<&dyn Any>` - For extracting
//!   arbitrary members from a context based on their type and `member_mut` for
//!   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
//! 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
//! 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
//! a `Backtrace` type like below.
//!
//! Here is how the `eyre::DefaultContext` type uses this to return `Backtrace`s.
//!
//! ```rust,compile_fail
//! fn member_ref(&self, typeid: TypeId) -> Option<&dyn Any> {
//!     if typeid == TypeId::of::<Backtrace>() {
//!         self.backtrace.as_ref().map(|b| b as &dyn Any)
//!     } else {
//!         None
//!     }
//! }
//! ```
//!
//! Once you've defined a custom Context type you can use it throughout your
//! application by defining a type alias.
//!
//!
//! ```rust,compile_fail
//! type ErrReport = eyre::ErrReport<MyContext>;
//!
//! // And optionally...
//! type Result<T, E = eyre::ErrReport<MyContext>> = core::result::Result<T, E>;
//! ```
//! <br>
//!

#![doc(html_root_url = "https://docs.rs/eyre/0.3.4")]

#![doc(html_root_url = "https://docs.rs/eyre/0.3.5")]