Crate gix_error 

Common error types and utilities for error handling.

Usage

• When there is no callee error to track, use simple std::error::Error implementations directly, e.g. Result<_, Simple>.
• When there is callee error to track in a gix-plumbing, use e.g. Result<_, Exn<Simple>>.
  • Remember that Exn<T> does not implement std::error::Error so it’s not easy to use outside gix- crates.
  • Use the type-erased version in callbacks like Exn (without type arguments), i.e. Result<T, Exn>.
• When there is callee error to track in the gix crate, convert both std::error::Error and Exn<E> into Error

Standard Error Types

These should always be used if they match the meaning of the error well enough instead of creating an own Error-implementing type, and used with ResultExt::or_raise(<StandardErrorType>) or OptionExt::ok_or_raise(<StandardErrorType>), or sibling methods.

All these types implement Error.

Message

The baseline that provides a formatted message. Formatting can more easily be done with the message! macro as convenience, roughly equivalent to Message::new(format!("…")) or format!("…").into().

Specialised types

• ParseError
  • like Message, but can optionally store the input that caused the failure.

Exn<ErrorType> and Exn

The Exn type does not implement Error itself, but is able to store causing errors via ResultExt::or_raise() (and sibling methods) as well as location information of the creation site.

While plumbing functions that need to track causes should always return a distinct type like Exn<Message>, if that’s not possible, use Exn::erased to let it return Result<T, Exn> instead, allowing any return type.

A side effect of this is that any callee that causes errors needs to be annotated with .or_raise(|| message!("context information")) or .or_raise_erased(|| message!("context information")).

Feature Flags

• anyhow — The Exn type converts to anyhow::Error natively so ? can be used directly.

  Otherwise, it would have to be manually converted via into_box() or into_inner().

• auto-chain-error — The Error type is always flattening the Exn error tree into a chain of errors, while keeping their locations and runtime type-information.

• tree-error — The opposite of auto-chain-error and implicitly enabled by default. Use it to override auto-chain-error.

Why not anyhow?

anyhow is a proven and optimized library, and it would certainly suffice for an error-chain based approach where users are expected to downcast to concrete types.

What’s missing though is track-caller which will always capture the location of error instantiation, along with compatibility for error trees, which are happening when multiple calls are in flight during concurrency.

Both libraries share the shortcoming of not being able to implement std::error::Error on their error type, and both provide workarounds.

exn is much less optimized, but also costs only a Box on the stack, which in any case is a step up from thiserror which exposed a lot of heft to the stack.

Re-exports

pub use bstr;

Macros

bail

Creates an Exn and returns it as Result.

ensure

Ensures $cond is met; otherwise return an error.

message

Construct a Message from a string literal or format string. Note that it always runs format!(), use the message() function for literals instead.

Structs

ChainedError

A generic error which represents a linked-list of errors and exposes it with source(). It’s meant to be the target of a conversion of any Exn error tree.

Error

An error type that wraps an inner type-erased boxed std::error::Error or an Exn frame.

Exn

An exception type that can hold an error tree and the call site.

Frame

A frame in the exception tree.

Message

An error that is further described in a message.

ParseError

An error occurred when parsing input

Something

An error that merely says that something is wrong.

Untyped

A marker to show that type information is not available, while storing all extractable information about the erased type. It’s the default type for Exn.

Traits

ErrorExt

A trait bound of the supported error type of Exn.

OptionExt

An extension trait for Option to provide raising new exceptions on None.

ResultExt

An extension trait for Result to provide context information on Exns.

Functions

message

Return a new statically allocated message.