scoped-error

Structured error handling with semantic context trees.

This library provides scoped_error::Error, a context-aware error type for idiomatic error handling with virtual backtraces - semantic breadcrumbs attached exactly where they matter.

Philosophy

Explicit context over automatic backtraces. Instead of capturing 50 frames of stack on every error, scoped_error lets you attach meaningful context at semantic boundaries. The result is information-dense, user-facing error reports without runtime overhead.

Quick Start

use std::str::FromStr;

use scoped_error::{Error, expect_error};

struct Config;
impl FromStr for Config {
    type Err = Error;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        todo!()
    }
}

fn read_config() -> Result<String, Error> {
    expect_error("reading file", || {
        let text = std::fs::read_to_string("/etc/app.conf")?;
        Ok(text)
    })
}

fn parse_config(text: &str) -> Result<Config, Error> {
    expect_error("parsing TOML", || {
        return Ok(text.parse::<Config>()?);
    })
}

fn load_config() -> Result<Config, Error> {
    expect_error("loading configuration", || {
        let text = read_config()?;
        let cfg = parse_config(&text)?;
        Ok(cfg)
    })
}

fn main() -> Result<(), Error> {
    let _config = load_config()?;
    Ok(())
}

Output:

Error: loading configuration, at src/main.rs:27:20
|-- reading file, at src/main.rs:15:12
`-- No such file or directory (os error 2)

Multiple Concurrent Failures

Unlike most error libraries, scoped_error natively handles parallel operations with Many:

use scoped_error::Many;

let results = vec![task_a(), task_b(), task_c()];
let values = Many::from_results("batch operation failed", results)?;

Output:

Error: batch operation failed, at src/main.rs:10:5 (3 errors)
|-- task A failed, at src/worker.rs:8:9
|   `-- connection timeout
|-- task B failed, at src/worker.rs:12:9
|   `-- invalid response
`-- task C failed, at src/worker.rs:16:9
    `-- parse error

Why scoped_error?

See https://kanru.info/scoped-error/

License

Apache-2.0 WITH LLVM-exception