$ show shepmaster/snafu
SNAFU is a Rust library for ergonomic error handling. It provides a `#[derive(Snafu)]` proc-macro that generates custom error types with automatic 'context selectors' (e.g., `ReadConfigSnafu`) and implements standard traits (`Display`, `Error`, `From`). The library also offers extension traits (`ResultExt`, `OptionExt`, `TryFutureExt`, `TryStreamExt`) to attach contextual information to underlying errors, macros (`ensure!`, `whatever!`) for concise error creation, and a `Report` type for user-facing error output. It supports `no_std` environments (with `alloc`) and includes backtrace capture, location tracking, and an unstable provider API for attaching arbitrary data to errors. The crate is mature and widely adopted, but contains some deprecated features (e.g., `backtraces-impl-backtrace-crate`) and a complex feature-flag matrix. The companion `snafu-derive` crate handles all proc-macro generation, and the architecture cleanly separates parsing, validation, and code generation.
The LLM identified 3 files worth highlighting for reuse:
Implements a generic, reusable attribute parsing framework for proc-macros. Defines traits like `FlagAttribute`, `AtMostOne`, and `FromAttribute` to validate and extract custom attributes on enum variants and struct fields. The design produces high-quality compile errors via `SynErrors` and `ErrorLocation`, making it an excellent reference for any Rust crate that needs safe, user-friendly custom attribute handling.
A small, thread-safe `OnceBool` type that atomically records whether a value has ever been set to `true`. Used by SNAFU to track whether the `SNAFU_RAW_ERROR_MESSAGES` environment variable has been read, but designed as a general-purpose primitive. Demonstrates correct use of `AtomicBool` and `Ordering::Relaxed` for a single-writer, multiple-reader scenario. Reusable in any Rust project needing a persistent boolean that can only transition from false to true.
Provides `CleanedErrorText`, an iterator that removes redundant source text from chained error messages by deduplicating substrings, and `ReportFormatter` for formatting `Report` output. The deduplication strategy is non-trivial and can be reused in any error-reporting system that presents a chain of errors. Also includes the `__InternalExtractErrorType` trait used by the `#[snafu::report]` attribute macro, showing a clean separation between formatting logic and macro-generated code.