joelonsql / wherr

Enhance Rust errors with file and line details using the `#[wherr]` macro for clearer debugging.

wherr Crate

Discuss wherr on Hacker News

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 the anyhow 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.

1. 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

2. 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:

1. wherr: This is the main library that offers the enhanced functionality for error handling in Rust.
2. wherr-macro: Contains the procedural macros specifically designed for the wherr 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.

wherr's Issues

Can you help review the PR to add backtrace?

Hi Joel,

I like wherr and would like to use it in our project. We are converting a C# project to rust. And one feature that we miss in rust is callstack for exception, which helps us to locate the issue. So I try to add something similar in this PR. Can you help review it?

#3

Thanks,
Kai

Use of Box<dyn Error> prevents Wherr from working with anyhow

Being able to work with the anyhow crate would make this crate much more ergonomic for use in existing code. Currently, wherr uses Box<dyn Error> as it's inner error type and error returned from wherrapper. This is not Sized, Send, or Sync, meaning it cannot be converted into anyhow's Error type. Based on some testing I've done locally, the API of anyhow::Error is similar enough to that of Box that there would be nearly no code changes necessary between the two implementations.

I'd like to propose the existence of a feature flag which would switch wherr to use anyhow::Error as its inner error type. This could either change the behavior of the #[wherr] macro directly, or enable the existence of a #[wherr_anyhow] macro, whichever seems most convenient (though I lean toward the former).

If this is something you're interested in, I'd be happy to submit a PR implementing these changes.

`anyhow` feature not additive in the Wherr implementation

If some users include your library with Anyhow, and some without it, a project including both such libraries will not build. You need to change your design so that the feature is additive, that is adding anyhow shouldn't break code which relies on using std::error::Error