gix_error/exn/
mod.rs

1// Copyright 2025 FastLabs Developers
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! A context-aware concrete Error type built on `std::error::Error`
16#![cfg_attr(docsrs, feature(doc_cfg))]
17#![deny(missing_docs)]
18
19mod ext;
20pub use ext::{BoxedResultExt, ErrorExt, OptionExt, ResultExt};
21
22mod impls;
23#[cfg(any(feature = "tree-error", not(feature = "auto-chain-error")))]
24pub(crate) use impls::ErrorNode;
25pub use impls::{Frame, Something, Untyped};
26
27mod macros;
28
29/// An exception type that can hold an [error tree](Exn::raise_all) and the call site.
30///
31/// While an error chain, a list, is automatically created when [raise](Exn::raise)
32/// and friends are invoked, one can also use [`Exn::raise_all`] to create an error
33/// that has multiple causes.
34///
35/// # Native error sources
36///
37/// Values reached through [`std::error::Error::source()`] remain owned by their original errors and are traversed by
38/// reference, preserving their concrete types. They aren't exception frames and therefore have no captured call site of
39/// their own.
40///
41/// # `Exn` == `Exn<Untyped>`
42///
43/// `Exn` act's like `Box<dyn std::error::Error + Send + Sync + 'static>`, but with the capability
44/// to store a tree of errors along with their *call sites*.
45///
46/// # Visualisation
47///
48/// Linearized trees during display make a list of 3 children indistinguishable from
49/// 3 errors where each is the child of the other.
50///
51/// ## Debug
52///
53/// * locations: ✔️
54/// * error display: Display
55/// * tree mode: linearized
56///
57/// ## Debug + Alternate
58///
59/// * locations: ❌
60/// * error display: Display
61/// * tree mode: linearized
62///
63/// ## Display
64///
65/// * locations: ❌
66/// * error display: Debug
67/// * tree mode: None
68///
69/// ## Display + Alternate
70///
71/// * locations: ❌
72/// * error display: Debug
73/// * tree mode: verbatim
74pub struct Exn<E: std::error::Error + Send + Sync + 'static = Untyped> {
75    // trade one more indirection for less stack size
76    frame: Box<Frame>,
77    phantom: PhantomData<E>,
78}
79
80use std::marker::PhantomData;
gix_error/exn/mod.rs

gix_error/exn/
mod.rs
