scoped-error 0.1.3

Structured error handling with semantic context trees. Zero proc-macros. Zero backtrace overhead.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

# scoped-error

Structured error handling with semantic context trees. Zero
proc-macros. Zero backtrace overhead.

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

```rust
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:**

```text
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`:

```rust
use scoped_error::Many;

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

**Output:**

```text
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`?

| **Feature** | **scoped_error** | **Others** |
|-------------|----------------|------------|
| **Semantic context** | 	Scoped closures, zero-cost | Per-? .context() calls |
| **Multiple causes** | Native tree support (Many) | Linear chains only |
| **Compile time** | Fast, no proc-macros | Slower with derives |
| **Backtraces** | Virtual via context | Automatic, always-on overhead |

## License

Apache-2.0 WITH LLVM-exception