error2 0.13.2

A simple error handle library for Rust
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# Error2

English | [简体中文](README-zh_cn.md)

[![Crates.io version](https://img.shields.io/crates/v/error2.svg?style=flat-square)](https://crates.io/crates/error2)
[![docs.rs docs](https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square)](https://docs.rs/error2)

Error handling library with backtrace support and ergonomic error conversion.

## Installation

```toml
[dependencies]
error2 = "0.13.2"
```

## Usage

### Define Error Types

Error2 supports three types of errors based on field structure:

**1. Root Error** - Only `backtrace` field (new error source)

```rust
use error2::prelude::*;

#[derive(Debug, Error2)]
#[error2(display("User {username} not found"))]
struct UserNotFound {
    username: String,
    backtrace: Backtrace,
}
```

**2. Standard Error** - `source` + `backtrace` (wraps `std::error::Error`)

```rust
use error2::prelude::*;

#[derive(Debug, Error2)]
#[error2(display("IO error: {path}"))]
struct IoError {
    path: String,
    source: std::io::Error,
    backtrace: Backtrace,
}
```

**3. Error2 Chain** - Only `source` field (chains another `Error2` type, reuses its backtrace)

```rust
use error2::prelude::*;

#[derive(Debug, Error2)]
#[error2(display("Application error"))]
struct AppError {
    source: IoError,  // Another Error2 type
}
```

### Convert Errors

```rust
// Result<T, Source> -> Result<T, Target>
std::fs::read_to_string("file.txt")
    .context(IoError2 { path: "file.txt" })?;

// Option<T> -> Result<T, E>
database.get(id)
    .context(NotFound2 { item: "user" })?;

// E -> Result<T, E>
some_error.context(MyError2)
```

**Note:** Helper struct fields are generic with `Into` trait bounds, so you don't need to call `.into()` manually. For expensive conversions, use `.with_context()` instead:

```rust
// Lazy evaluation - only converts on error
std::fs::read(&path)
    .with_context(|| IoError2 { path: path.display().to_string() })?;
```

### Track Propagation

```rust
fn inner() -> Result<(), MyError> {
    operation().context(IoError2 { path: "file.txt" })?
}

fn outer() -> Result<(), MyError> {
    inner().attach()?  // Captures this location
}
```

### Create Root Errors

```rust
fn validate(value: i32) -> Result<(), ValidationError> {
    if value < 0 {
        return ValidationError2 { value }.fail();
    }
    Ok(())
}
```

### Use Type-Erased Errors

```rust
fn operation() -> Result<(), BoxedError2> {
    std::fs::read("file.txt").context(ViaStd)?;

    if condition {
        ViaRoot("error message").fail()?;
    }

    other_operation().context(ViaErr2)?;

    Ok(())
}
```

### Print Error Stack

```rust
fn main() {
    match operation().attach() {
        Ok(_) => println!("Success"),
        Err(e) => {
            // Print complete error chain with locations:
            //
            // IoError: io error: config.txt
            //     at src/main.rs:15:42
            //     at src/main.rs:23:5
            // std::io::Error: No such file or directory (os error 2)
            eprintln!("{}", e.backtrace().error_message());
        }
    }
}
```

For more details, see [API Documentation](https://docs.rs/error2)

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.