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::{ErrorExt, OptionExt, ResultExt};
21
22mod impls;
23pub use impls::{Frame, Something, Untyped};
24
25mod macros;
26
27/// An exception type that can hold an [error tree](Exn::raise_all) and the call site.
28///
29/// While an error chain, a list, is automatically created when [raise](Exn::raise)
30/// and friends are invoked, one can also use [`Exn::raise_all`] to create an error
31/// that has multiple causes.
32///
33/// # Warning: `source()` information is stringified and type-erased
34///
35/// All `source()` values are turned into frames, but lose their type information completely.
36/// This is because they are only seen as reference and thus can't be stored.
37///
38/// # `Exn` == `Exn<Untyped>`
39///
40/// `Exn` act's like `Box<dyn std::error::Error + Send + Sync + 'static>`, but with the capability
41/// to store a tree of errors along with their *call sites*.
42///
43/// # Visualisation
44///
45/// Linearized trees during display make a list of 3 children indistinguishable from
46/// 3 errors where each is the child of the other.
47///
48/// ## Debug
49///
50/// * locations: ✔️
51/// * error display: Display
52/// * tree mode: linearized
53///
54/// ## Debug + Alternate
55///
56/// * locations: ❌
57/// * error display: Display
58/// * tree mode: linearized
59///
60/// ## Display
61///
62/// * locations: ❌
63/// * error display: Debug
64/// * tree mode: None
65///
66/// ## Display + Alternate
67///
68/// * locations: ❌
69/// * error display: Debug
70/// * tree mode: verbatim
71pub struct Exn<E: std::error::Error + Send + Sync + 'static = Untyped> {
72    // trade one more indirection for less stack size
73    frame: Box<Frame>,
74    phantom: PhantomData<E>,
75}
76
77use std::marker::PhantomData;
gix_error/exn/mod.rs

gix_error/exn/
mod.rs
