Crate flex_error

flex-error is a lightweight Rust library that uses macros and traits to switch between different error tracing implementations and no_std. The library currently supports 3 modes via Cargo feature flags: eyre_tracer (default), anyhow_tracer, and string_tracer (no_std).

The library separates out several concepts as traits: ErrorDetail, ErrorTracer, and ErrorSource.

• ErrorDetail is responsible to structured metadata information about a specific error.

• ErrorTracer is responsible for tracing error chains and backtraces.

• ErrorSource allows generic conversion of external error types into an ErrorDetail with optional ErrorTrace.

With the separation of concerns, flex-error allows applications to easily switch between different error reporting implementations, such as eyre and anyhow, by implementing ErrorTracer for the respective reporters.

flex-error defines a define_error! macro that define custom Detail types and error types implementing ErrorSource<DefaultTracer>. The DefaultTracer type is set globally by the feature flag, so that application error types do not have to be over-generalized. The trade off is that it is not possible to use multiple ErrorTracer implementations at the same time across different crates that use flex-error.

Re-exports

pub extern crate alloc;

Modules

macros

tracer_impl

Macros

define_error

define_error! is the main macro that implements a mini DSL to define error types using flex-error. The DSL syntax is as follows:

Structs

BoxDetail

DetailOnly

An ErrorSource that only provides error details but do not provide any trace. This can typically comes from primitive error types that do not implement Error. The Detail type is the error and the returned trace is None.

DisplayError

An ErrorSource that implements Display and can be traced by error tracers implementing ErrorMessageTracer.

DisplayOnly

NoSource

An ErrorSource that can be used to represent to lack of any error source. Both its Source and Detail types are (). This can be used for primitive errors that are not caused by any error source.

TraceClone

TraceError

An ErrorSource that should implement Error and other constraints such as Send, Sync, 'static, so that it can be traced by error tracing libraries such as eyre and anyhow. Because these libraries take ownership of the source error object, the error cannot be extracted as detail at the same time.

TraceOnly

An ErrorSource that contains only the error trace with no detail. This can for example be used for upstream functions that return tracers like eyre::Report directly.

Traits

ErrorMessageTracer

An ErrorMessageTracer can be used to generically trace any error detail that implements Display.

ErrorSource

A type implementing ErrorSource<Trace> is a proxy type that provides the capability of extracting from an error source of type Self::Source, returning error detail of type Self::Detail, and an optional error tracer of type Tracer.

ErrorTracer

An error tracer implements ErrorTracer<E> if it supports more sophisticated error tracing for an error type E. The contraint for E depends on the specific error tracer implementation.

StdError

Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<T, E>.

Type Definitions

AsErrorDetail

Type alias to <Error as ErrorSource<Trace>>::Detail

AsErrorSource

Type alias to <Error as ErrorSource<Trace>>::Source

DefaultTracer

The DefaultTracer type alias is used when defining error types using define_error!. With the default Cargo features, or when the eyre_tracer feature is set, this is configured to use the EyreTracer. Otherwise, it will be set to AnyhowTracer if the anyhow_tracer feature is set. If neither eyre_tracer nor anyhow_tracer is set, then DefaultTracer is set to StringTracer.