Crate flex_error[−][src]
Expand description
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
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
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
.
An ErrorSource
that implements Display
and
can be traced by error tracers implementing ErrorMessageTracer
.
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.
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.
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
An ErrorMessageTracer
can be used to generically trace
any error detail that implements Display
.
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
.
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
Type alias to <Error as ErrorSource<Trace>>::Detail
Type alias to <Error as ErrorSource<Trace>>::Source
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.