Crate suzunari_error 

A highly traceable and noise-free error handling library for Rust.

Built on SNAFU, this crate propagates error locations as error contexts and formats error chains as stack-trace-like reports. #![no_std] compatible with 3 feature tiers: core-only / alloc / std.

Quick Start

Use #[suzunari_error] to define error types — it combines location injection, Snafu derive, and StackError derive in one attribute:

use suzunari_error::*;

#[suzunari_error]
#[suzu(display("operation failed"))]
struct AppError {
    source: std::io::Error,
}

Key Types

• Location — Type alias for &'static core::panic::Location<'static>; captures call-site file/line/column
• StackError — Extends Error with location(), type_name(), stack_source(), and depth()
• StackReport — Formats a StackError chain for display with location info
• BoxedStackError — Type-erased StackError wrapper (requires alloc)
• DisplayError — Adapter for Debug + Display types that don’t implement Error

Feature Flags

Feature	Default	Provides
std	Yes	alloc + StackReport’s Termination impl + #[report] macro
alloc	via std	BoxedStackError + From<T> for BoxedStackError generation
(none)	—	Core-only: Location, StackError, StackReport (formatting only), DisplayError

#[suzu(...)] Attribute

Use #[suzu(...)] for all attributes under #[suzunari_error]. It is a superset of #[snafu(...)] — standard snafu keywords (display, source, visibility, etc.) pass through as-is, plus suzunari extensions are available. #[snafu(...)] also works, but #[suzu(...)] is preferred for consistency.

Suzunari extensions:

• from (field-level) — wraps a field type in DisplayError<T> and generates a source(from(...)) conversion that automatically preserves the Error::source() chain when the wrapped type implements Error
• location (field-level) — marks a field as the location field with a custom name; converts to #[stack(location)] + #[snafu(implicit)]

Known Limitations

• Location type detection uses the last path segment name (Location), not the full path. A user-defined my_module::Location type may trigger false auto-detection. Writing the expanded type (&'static core::panic::Location<'static>) directly also bypasses auto-detection. Use #[suzu(location)] or #[stack(location)] to disambiguate.
• Crate renaming (my_error = { package = "suzunari-error" }) is not supported. The generated code always references ::suzunari_error. This matches the approach used by snafu and thiserror.

Re-exports

pub use snafu;

Macros

ensure

Ensure a condition is true. If it is not, return from the function with an error.

Structs

BoxedStackError

Type-erased wrapper around Box<dyn StackError + Send + Sync>.

DisplayError

Wrapper that converts a Debug + Display type (without Error impl) into a core::error::Error.

StackReport

Formats a StackError chain as a stack-trace-like report with type names and locations.

Traits

OptionExt

Additions to Option.

ResultExt

Additions to Result.

StackError

Error trait extension that adds source code location tracking.

Type Aliases

Location

Type alias for &'static core::panic::Location<'static>.

Attribute Macros

report

Transforms fn() -> Result<(), E> into fn() -> StackReport<E>.

suzunari_error

The main entry point for defining error types.

Derive Macros

StackError

Derives the StackError trait for a struct or enum.