suzunari-error 0.2.0

A highly traceable and noise-free error system that propagates error locations as error contexts and minimizes information output to the log
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! A highly traceable and noise-free error handling library for Rust.
//!
//! Built on [SNAFU](https://docs.rs/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]`](macro@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`](std::process::Termination) impl + [`#[report]`](macro@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]`](macro@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.

#![no_std]
#![forbid(unsafe_code)]
#![warn(missing_docs)]

#[cfg(feature = "alloc")]
extern crate alloc;

#[cfg(feature = "std")]
extern crate std;

mod display_error;
mod stack_error;
mod stack_report;

#[doc(hidden)]
pub mod __private;

#[cfg(feature = "alloc")]
mod boxed_stack_error;

#[cfg(feature = "alloc")]
pub use boxed_stack_error::BoxedStackError;
/// Type alias for `&'static core::panic::Location<'static>`.
///
/// Used as the location field type in error structs generated by [`#[suzunari_error]`](macro@suzunari_error).
/// [`snafu::GenerateImplicitData`] is implemented for this type by snafu, so location fields
/// marked with `#[snafu(implicit)]` are automatically populated via `#[track_caller]`.
pub type Location = &'static core::panic::Location<'static>;

pub use display_error::DisplayError;
pub use stack_error::StackError;
pub use stack_report::StackReport;

// Re-export snafu so downstream crates don't need it as a direct dependency.
// The proc-macro generates `#[snafu(crate_root(::suzunari_error::snafu))]`
// to redirect snafu's generated paths here.
// Note: bumping the snafu dependency version is a semver-breaking change for
// downstream crates, because these re-exports are part of our public API.
pub use snafu;
// OptionExt is not used within this crate but re-exported for downstream
// convenience: it enables `.context()` on `Option<T>` to convert None into errors.
pub use snafu::{OptionExt, ResultExt, ensure};

// Proc-macro re-exports (wildcard is the only way to re-export proc macros).
pub use suzunari_error_macro_impl::*;