tamanegi_error/lib.rs
1//! # What is this library
2//! Tamanegi-Error is a library that helps you create error types that can track the propagation history.
3//!
4//! See README.md for more details.
5//! (Only the Japanese version is available. Please wait for English version or send PR)
6//!
7//! # How to use
8//!
9//! Please add `TamanegiError` to the error struct made by Snafu as follows:
10//!
11//! ```rust
12//! use snafu::{GenerateImplicitData, Snafu};
13//! use tamanegi_error::{TamanegiError, location::StaticLocationRef};
14//!
15//! #[derive(Snafu, TamanegiError)]
16//! pub struct ErrorSubA {
17//! #[snafu(implicit)]
18//! location: StaticLocationRef,
19//! }
20//!
21//! impl ErrorSubA {
22//! pub fn new() -> Self {
23//! Self {
24//! location: StaticLocationRef::generate(),
25//! }
26//! }
27//! }
28//!
29//! #[derive(Snafu, TamanegiError)]
30//! #[snafu(context(false))]
31//! struct MyError {
32//! #[snafu(source)]
33//! source: ErrorSubA,
34//! #[snafu(implicit)]
35//! location: StaticLocationRef,
36//! }
37//!
38//! fn err() -> Result<(), MyError> {
39//! let err: Result<(), ErrorSubA> = Err(ErrorSubA::new());
40//! let _ = err?;
41//! Ok(())
42//! }
43//!
44//! fn main() {
45//! if let Err(e) = err() {
46//! println!("{:?}", e);
47//! }
48//! }
49//! ```
50//!
51//! Then the following propagation history can be seen:
52//!
53//! ```text
54//! 1: MyError, at examples/basic_struct.rs:29:13
55//! 0: ErrorSubA, at examples/basic_struct.rs:13:23
56//! ```
57//!
58//! # Relation to [Stack Error](https://greptime.com/blogs/2024-05-07-error-rust#how-error-looks-like-with-virtual-user-stack)
59//!
60//! This library is based on [Stack Error](https://greptime.com/blogs/2024-05-07-error-rust#how-error-looks-like-with-virtual-user-stack)'s idea.
61//! I initially intended to use StackError as is because it is a great idea, but it was not suitable for no_std.
62//! So I write this crate from scratch suitable for no_std, using only the idea as a reference.
63#![cfg_attr(not(test), no_std)]
64
65pub mod location;
66
67pub use tamanegi_error_impl::TamanegiError;
68
69/// This is a marker trait that indicates the implementation of Tamanegi-Error.
70/// It is implemented by the [tamanegi_error_impl::TamanegiError] derive macro.
71pub trait TamanegiTrait: snafu::ErrorCompat {}