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.

• An application error is of type ErrorReport<ErrorDetail, ErrorTracer>, which holds both the error details and trace.

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 as alias to ErrorReport<Detail, 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.

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:
define_error_constructor	Internal macro used to define suberror constructor functions
define_error_with_tracer	This macro allows error types to be defined with custom error tracer types other than DefaultTracer. Behind the scene, a macro call to define_error!{ ... } really expands to define_error_with_tracer!{ flex_error::DefaultTracer; … }
define_suberror	Internal macro used to define suberror structs

Structs

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.
ErrorReport	An ErrorSource that provides both the error detail and error trace separately. The error trace in an error report also already contains the trace of the current error detail already. so new errors that arise from an ErrorReport only need to access the trace object to add new traces to it.
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.
StdError	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.

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.