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.