Crate bigerror

Crate bigerror 

Source
Expand description

Enhanced error handling library built on top of error-stack.

bigerror provides ergonomic error handling adding out of the box functionality to error-stack for common scenarios.

§Key Features

  • Useful context attachments - Key-value pairs, field status, type information
  • Pre-defined contexts: NotFound, ParseError, Timeout, etc.
  • no_std support: Works in embedded and constrained environments

§Quick Start

use bigerror::{ThinContext, Report, expect_field, IntoContext, ResultIntoContext, NotFound};

// Define your error type
#[derive(ThinContext)]
struct MyError;

fn parse_number(input: &str) -> Result<i32, Report<MyError>> {
    // Use context conversion for error handling
    let num: i32 = input.parse()
        .into_ctx::<MyError>()?; // `::<MyError>` can be omitted

    Ok(num)
}

// Example with `expect_field` for optional values
fn get_config_value() -> Result<&'static str, Report<NotFound>> {
    let config = Some("production");
    expect_field!(config).into_ctx()
}

§Attachments

Attach contextual information to errors using various attachment types:

use bigerror::{ThinContext, kv, ty, KeyValue};

#[derive(ThinContext)]
struct MyError;

// Key-value attachments
let error = MyError::attach_kv("user_id", 42);

// Type-value attachments
let data = vec![1, 2, 3];
let error = MyError::attach_kv(ty!(Vec<i32>), data.len());

#[derive(Debug, Clone, Eq, PartialEq)]
struct Username(String);
impl std::fmt::Display for Username {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

let username = String::from("alice");
assert_eq!(kv!(username.clone()), KeyValue("username", String::from("alice")));
let error = MyError::attach(kv!(username.clone())); // "username": "alice"

let username = Username(username);
assert_eq!(format!("{}", kv!(ty: username)), "<Username>: alice");

§Feature Flags

  • std (default) - Standard library support
  • backtrace (default) - Backtrace support
  • tracing - Integration with the tracing ecosystem
  • serde - Serialization support
  • anyhow - Compatibility with anyhow
  • eyre - Compatibility with eyre

§Pre-defined Error Contexts

Common error contexts are provided out of the box:

See the context module for the complete list.

Re-exports§

pub use attachment::Expectation;
pub use attachment::Field;
pub use attachment::Index;
pub use attachment::KeyValue;
pub use attachment::Type;
pub use error_stack;
pub use context::*;

Modules§

attachment
Error attachment types and utilities for adding context to error reports.
context
Common error context types for different categories of errors.

Macros§

bail
Re-export of error-stack types and macros for convenience. Creates a Report and returns it as Result.
ensure
Re-export of error-stack types and macros for convenience. Ensures $cond is met, otherwise return an error.
expect_field
Converts an Option to a Result, using the extracted field name for error context.
kv
Creates a KeyValue pair for error attachments with flexible key-value syntax.
reportDeprecated
Re-export of error-stack types and macros for convenience. Creates a Report from the given parameters.
ty
Creates a Type attachment for the specified type.

Structs§

Report
Re-export of error-stack types and macros for convenience. Contains a Frame stack consisting of Contexts and attachments.

Traits§

AttachExt
Extension trait that adds attachment methods to error reports and results.
ClearResult
Trait for clearing either the success or error part of a Result.
ContextDeprecated
Re-export of error-stack types and macros for convenience. Defines the current context of a Report.
IntoContext
Trait for converting error reports from one context type to another.
IntoReport
Re-export of error-stack types and macros for convenience. Provides unified way to convert an error-like structure to a Report.
OptionReport
Extension trait for Option<T> that provides methods to convert None into error reports.
ReportAs
Trait for converting Result<T, E> into Result<T, Report<C>> with automatic error wrapping.
ResultExt
Re-export of error-stack types and macros for convenience. Extension trait for Result to provide context information on Reports.
ResultIntoContext
Extension trait for Result<T, Report<C>> that provides context conversion methods.
ThinContext
A trait for zero-sized error types that provides convenient error creation methods.

Functions§

init_colour
Initialize error reporting with colored output.
init_emphasis
Initialize error reporting with emphasis only (no full color).
init_no_ansi
Initialize error reporting with no ANSI formatting.

Derive Macros§

ThinContext
Derive macro for implementing ThinContext trait on zero-sized error types.