8 releases
0.1.7 | Sep 1, 2023 |
---|---|
0.1.6 | Aug 23, 2023 |
#717 in Rust patterns
226 downloads per month
11KB
63 lines
wherr
Crate
Enhance Rust's ?
operator by appending file and line number details to errors, simplifying the debugging process.
Features
- 📁 Appends file and line number to errors propagated with
?
. - 🧩 Integrates seamlessly with Rust's existing error handling.
- 📍 Helps locate and fix errors faster by pinpointing their origin.
- 🚀 Supports
anyhow
error handling through theanyhow
feature flag.
Why wherr
?
When using the ?
operator in Rust, errors propagated don't usually provide file and line number details about where the error occurs. Especially in nested function calls with multiple potential error points, this absence of detailed info can be a debugging headache.
wherr
remedies this, giving you precise location data for your errors.
Installation
Add the following to your Cargo.toml
:
[dependencies]
wherr = "0.1"
For anyhow
support:
[dependencies]
wherr = { version = "0.1", features = ["anyhow"] }
Quick Start
By simply annotating your functions with #[wherr]
, errors propagated using ?
will also include the file and line number.
- Standard Usage: Annotate functions with
#[wherr]
.
use wherr::wherr;
#[wherr]
fn concat_files(path1: &str, path2: &str) -> Result<String, Box<dyn std::error::Error>> {
let mut content1 = std::fs::read_to_string(path1)?;
let content2 = std::fs::read_to_string(path2)?;
content1.push_str(&content2);
Ok(content1)
}
Run the provided example:
cargo run --example with_wherr
This will highlight the difference wherr
makes. Your error will now indicate exactly where the issue arises:
error at wherr/examples/with_wherr.rs:5
- With
anyhow
:
Ensure you've added the anyhow
feature as shown in the installation section. Then:
use anyhow::{Context, Result};
use wherr::wherr;
#[wherr]
fn concat_files(path1: &str, path2: &str) -> Result<String> {
let mut content1 = std::fs::read_to_string(path1).with_context(|| format!("Failed to read {}", path1))?;
let content2 = std::fs::read_to_string(path2).with_context(|| format!("Failed to read {}", path2))?;
content1.push_str(&content2);
Ok(content1)
}
Run the provided example:
cargo run --features=anyhow --example anyhow
This will highlight the difference wherr
makes. Your error will now indicate exactly where the issue arises:
error at wherr/examples/anyhow.rs:6
Behind the Scenes
The #[wherr]
notation is a proc_macro_attribute, which allows for code transformations at compile time.
When an error is propagated using the ?
operator inside a #[wherr]
annotated function, the macro captures the file and line number where the error occurred.
Essentially, the function:
#[wherr]
fn add(s1: &str, s2: &str) -> Result<i64, Box<dyn std::error::Error>> {
...
let i1 = i64::from_str_radix(s1, radix)?;
...
}
... is transformed to:
fn add(s1: &str, s2: &str) -> Result<i64, Box<dyn std::error::Error>> {
...
let i1 = wherr::wherrapper(i64::from_str_radix(s1, radix), file!(), line!())?;
...
}
The magic happens inside wherrapper
. It checks the given result, and if it's an error, wraps it with file and line details.
Usage & Examples
Dive deeper into the problem wherr
solves and the Rust concepts involved with our detailed examples.
Note on Crate Organization
wherr
is divided into two separate crates because of Rust's restriction against mixing normal functions and procedural macros in the same crate:
wherr
: This is the main library that offers the enhanced functionality for error handling in Rust.wherr-macro
: Contains the procedural macros specifically designed for thewherr
crate.
Contributing
If you're interested in contributing to wherr
, please follow standard
Rust community guidelines and submit a PR on our repository.
License
This project is dual licensed under MIT License and Apache License.
Dependencies
~225–700KB
~16K SLoC