scoped_error/lib.rs
1// Copyright (C) 2026 Kan-Ru Chen <kanru@kanru.info>
2//
3// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
4
5//! `scoped_error` - Context-aware error handling.
6//!
7//! This library provides easy error context propagation without requiring
8//! wrapper types at each layer. Context (message + location) is attached
9//! directly to error types that implement [`WithContext`].
10//!
11//! # Quick Start
12//!
13//! For simple use cases, use [`scoped_error::Error`](crate::Error) with [`expect_error`]:
14//!
15//! ```
16//! use scoped_error::{Error, expect_error};
17//! # fn internal() -> Result<(), Error> { Ok(()) }
18//!
19//! fn do_work() -> Result<(), Error> {
20//! expect_error("Failed to do something", || {
21//! internal()?;
22//! Ok(())
23//! })
24//! }
25//! ```
26//!
27//! Use [`impl_context_error!`] to create custom context error types:
28//!
29//! ```
30//! use scoped_error::{impl_context_error, expect_error};
31//!
32//! impl_context_error!(MyError);
33//! # fn internal() -> Result<(), MyError> { Ok(()) }
34//!
35//! fn do_work() -> Result<(), MyError> {
36//! expect_error("Failed to do something", || {
37//! internal()?;
38//! Ok(())
39//! })
40//! }
41//! ```
42//!
43//! # Core Concepts
44//!
45//! - **Context propagation**: Attach context (message + source location) to errors
46//! - **No wrapper types**: Context is stored directly in the error type
47//! - **Automatic location tracking**: Uses `#[track_caller]` to capture call sites
48//! - **Error reports**: Format full error chains with [`ErrorReport`]
49mod conversion;
50mod error;
51mod ext;
52mod macros;
53mod many;
54mod report;
55
56pub use conversion::expect_error;
57pub use conversion::expect_error_fn;
58pub use error::Error;
59pub use error::Frame;
60pub use error::WithContext;
61pub use ext::ErrorExt;
62pub use many::Many;
63pub use report::ErrorReport;