wherr 0.1.6

Enhance Rust errors with file and line details using the `#[wherr]` macro for clearer debugging.
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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202

# `wherr` Examples

In this guide, we'll delve deeper into using the `wherr` crate with practical examples. These examples help demonstrate the value `wherr` adds to error handling in Rust by appending file and line number details to errors.

## Basic Usage

### Without `wherr`

In our basic example, we try to add two numbers represented as strings:

`examples/without_wherr.rs`:

```rust
 1 | fn concat_files(path1: &str, path2: &str) -> Result<String, std::io::Error> {
 2 |     let mut content1 = std::fs::read_to_string(path1)?;
 3 |     let content2 = std::fs::read_to_string(path2)?;
 4 |
 5 |     content1.push_str(&content2);
 6 |     Ok(content1)
 7 | }
 8 |
 9 | fn main() {
10 |     let content = concat_files("file1.txt", "file2.txt").expect("Failed to concatenate the files");
11 |     println!("Concatenated content:\n{}", content);
12 | }
```

Executing the code:

```sh
% cargo run --example without_wherr
```

Yields:

```
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/examples/without_wherr`
thread 'main' panicked at 'Failed to concatenate the files: Os { code: 2, kind: NotFound, message: "No such file or directory" }', wherr/examples/without_wherr.rs:10:58
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```

As observed, the error does not provide information on where the *error* occurred, only where the *panic* occurred:

```rust
10 |     let content = concat_files("file1.txt", "file2.txt").expect("Failed to concatenate the files");
```

Unfortunately, if we suspect we have a bug somewhere in `concat_files()`, we might need to know what specific line that causes a certain error.

This might be tricky, especially when you have nested layers of functions, where the same error kind might occurr at multiple different places.

In our example, there are two calls to `read_to_string()`. Any one of them could have caused the `NotFound` kind of error.

Running with `RUST_BACKTRACE=1` doesn't help:

```sh
% RUST_BACKTRACE=1 cargo run --example without_wherr
```
```
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/examples/without_wherr`
thread 'main' panicked at 'Failed to concatenate the files: Os { code: 2, kind: NotFound, message: "No such file or directory" }', wherr/examples/without_wherr.rs:10:58
stack backtrace:
   0: rust_begin_unwind
             at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:579:5
   1: core::panicking::panic_fmt
             at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/panicking.rs:64:14
   2: core::result::unwrap_failed
             at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/result.rs:1750:5
   3: core::result::Result<T,E>::expect
             at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/result.rs:1047:23
   4: without_wherr::main
             at ./wherr/examples/without_wherr.rs:10:19
   5: core::ops::function::FnOnce::call_once
             at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/ops/function.rs:250:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
```

Still only `without_wherr.rs:10`.

Not even `RUST_BACKTRACE=full` helps:

```sh
% RUST_BACKTRACE=full cargo run --example without_wherr
```
```
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/examples/without_wherr`
thread 'main' panicked at 'Failed to concatenate the files: Os { code: 2, kind: NotFound, message: "No such file or directory" }', wherr/examples/without_wherr.rs:10:58
stack backtrace:
   0:        0x10266beec - std::backtrace_rs::backtrace::libunwind::trace::h2000fb4d08dbcc59
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/../../backtrace/src/backtrace/libunwind.rs:93:5
   1:        0x10266beec - std::backtrace_rs::backtrace::trace_unsynchronized::h2b5e61495350674d
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5
   2:        0x10266beec - std::sys_common::backtrace::_print_fmt::h05f5bfbdb3415936
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/sys_common/backtrace.rs:65:5
   3:        0x10266beec - <std::sys_common::backtrace::_print::DisplayBacktrace as core::fmt::Display>::fmt::h105074e3d85f800b
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/sys_common/backtrace.rs:44:22
   4:        0x10267d820 - core::fmt::write::h34766cf8fff7af1e
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/fmt/mod.rs:1232:17
   5:        0x102669f60 - std::io::Write::write_fmt::hd64c4cf6e7adea59
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/io/mod.rs:1684:15
   6:        0x10266bd00 - std::sys_common::backtrace::_print::hd92783a665d3ebfb
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/sys_common/backtrace.rs:47:5
   7:        0x10266bd00 - std::sys_common::backtrace::print::h2a6828a537036cf9
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/sys_common/backtrace.rs:34:9
   8:        0x10266d2ac - std::panicking::default_hook::{{closure}}::h4e82ce6ccef941b2
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:271:22
   9:        0x10266d004 - std::panicking::default_hook::h29f62f8795c5cb00
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:290:9
  10:        0x10266d7bc - std::panicking::rust_panic_with_hook::h19862cbd0fbda7ba
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:692:13
  11:        0x10266d6f0 - std::panicking::begin_panic_handler::{{closure}}::h3f3626935e1669fe
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:583:13
  12:        0x10266c30c - std::sys_common::backtrace::__rust_end_short_backtrace::h5054ef52bd507d0a
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/sys_common/backtrace.rs:150:18
  13:        0x10266d44c - rust_begin_unwind
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:579:5
  14:        0x102684590 - core::panicking::panic_fmt::h7e47e10600a90221
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/panicking.rs:64:14
  15:        0x102684838 - core::result::unwrap_failed::h6a1757e313e2d291
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/result.rs:1750:5
  16:        0x1026519b0 - core::result::Result<T,E>::expect::h3bb438a6543db6fe
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/result.rs:1047:23
  17:        0x102653950 - without_wherr::main::hea9e71193dce0291
                               at /Users/joel/src/wherr/wherr/examples/without_wherr.rs:10:19
  18:        0x102653218 - core::ops::function::FnOnce::call_once::ha7443c5406a2bc4c
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/ops/function.rs:250:5
  19:        0x1026518b4 - std::sys_common::backtrace::__rust_begin_short_backtrace::ha104f92716531d05
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/sys_common/backtrace.rs:134:18
  20:        0x102650b40 - std::rt::lang_start::{{closure}}::h4d7ab56f8229bc15
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/rt.rs:166:18
  21:        0x102667604 - core::ops::function::impls::<impl core::ops::function::FnOnce<A> for &F>::call_once::hf2f6b444963da11f
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/core/src/ops/function.rs:287:13
  22:        0x102667604 - std::panicking::try::do_call::h9152231fddd58858
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:487:40
  23:        0x102667604 - std::panicking::try::hcc27eab3b8ee3cb1
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:451:19
  24:        0x102667604 - std::panic::catch_unwind::hca546a4311ab9871
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panic.rs:140:14
  25:        0x102667604 - std::rt::lang_start_internal::{{closure}}::h4e65aa71fe685c85
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/rt.rs:148:48
  26:        0x102667604 - std::panicking::try::do_call::h61aea55fbdf97fc2
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:487:40
  27:        0x102667604 - std::panicking::try::hcfc3b62fb8f6215e
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panicking.rs:451:19
  28:        0x102667604 - std::panic::catch_unwind::h61a201e98b56a743
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/panic.rs:140:14
  29:        0x102667604 - std::rt::lang_start_internal::h91996717d3eb1d2a
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/rt.rs:148:20
  30:        0x102650b0c - std::rt::lang_start::ha5cfaf50836838f2
                               at /rustc/84c898d65adf2f39a5a98507f1fe0ce10a2b8dbc/library/std/src/rt.rs:165:17
  31:        0x102653a08 - _main
```

Still only `without_wherr.rs:10`.

### With `wherr`

Let's integrate `wherr` into the mix:

`examples/with_wherr.rs`:

```rust
 1 | use wherr::wherr;
 2 |
 3 | #[wherr]
 4 | fn concat_files(path1: &str, path2: &str) -> Result<String, Box<dyn std::error::Error>> {
 5 |     let mut content1 = std::fs::read_to_string(path1)?;
 6 |     let content2 = std::fs::read_to_string(path2)?;
 7 |
 8 |     content1.push_str(&content2);
 9 |     Ok(content1)
10 | }
11 |
12 | fn main() {
13 |     let content = concat_files("file1.txt", "file2.txt").expect("Failed to concatenate the files");
14 |     println!("Concatenated content:\n{}", content);
15 | }
```

Executing the code:

```sh
% cargo run --example with_wherr
```

Yields:

```
% cargo run --example with_wherr
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/examples/with_wherr`
thread 'main' panicked at 'Failed to concatenate the files: Os { code: 2, kind: NotFound, message: "No such file or directory" }
error at wherr/examples/with_wherr.rs:5', wherr/examples/with_wherr.rs:13:58
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```

Notice the appended file and line number, **error at wherr/examples/with_wherr.rs:5**, pinpointing exactly where the error arose:

The real power of `wherr` manifests in complex codebases with multiple nested function calls, where pinpointing errors can be challenging. While the basic example provides a glimpse into its utility, using `wherr` in larger projects can be invaluable for precise debugging.