Skip to main content

error_kind/traits/
error_domain.rs

1// =============================================================================
2// USES
3// =============================================================================
4
5// -----------------------------------------------------------------------------
6use crate::ErrorKind;
7
8// =============================================================================
9// TRAITS
10// =============================================================================
11
12/// A marker trait for a type that denotes a domain of possible error kinds.
13///
14/// These types are expected to be very simple enums, with the following rules:
15///
16/// - Each field must contain a single unnamed field.
17/// - The unnamed field must contain an [`ErrorKind`] type.
18/// - Each type may only be used once within the enum.
19///
20/// # Display Formatting
21///
22/// The derive macro for this trait will automatically implement `Display` for
23/// you. The default process is to break the variant name into words, lowercase
24/// it, and then separate the words by spaces.
25///
26/// Then, the error domain will print alongside its value: "{domain}: {value}".
27///
28/// ```rust
29/// # use error_kind::{ErrorDomain, ErrorKind};
30/// # #[derive(Clone, Copy, Debug, ErrorKind)]
31/// # enum IoErrorKind { Variant }
32/// # #[derive(Clone, Copy, Debug, ErrorKind)]
33/// # enum ParseErrorKind { Variant }
34/// #[derive(Clone, Copy, Debug, ErrorDomain)]
35/// enum ParseErrorDomain {
36///     Io(IoErrorKind),        // Prints "io: {0}"
37///     Parse(ParseErrorKind),  // Prints "parse: {0}"
38///     // ...
39/// }
40/// ```
41///
42/// If you don't like a particular display format, you can change it with the
43/// `#[error(...)]` attribute on a variant.
44///
45/// ```rust
46/// # use error_kind::{ErrorDomain, ErrorKind};
47/// # #[derive(Clone, Copy, Debug, ErrorKind)]
48/// # enum IoErrorKind { Variant }
49/// # #[derive(Clone, Copy, Debug, ErrorKind)]
50/// # enum ParseErrorKind { Variant }
51/// #[derive(Clone, Copy, Debug, ErrorDomain)]
52/// enum ParseErrorDomain {
53///     Io(IoErrorKind),        // Prints "io: {0}"
54///     #[error("custom: {0}")]
55///     Parse(ParseErrorKind),  // Prints "custom: {0}"
56///     // ...
57/// }
58/// ```
59///
60/// The `{0}` will expand to the value in the unnamed field.
61///
62/// # Purpose
63///
64/// An `ErrorDomain` allows us to compose multiple different error kinds
65/// together.
66///
67/// This allows us to maintain the following design principles:
68///
69/// 1. Avoid deeply-nested enums to keep error kinds small and efficient.
70/// 2. Ensure that subset type can unambiguously convert into any given superset
71///    `ErrorDomain`.
72///
73/// The second point is the *most important*, because it'll allow for very
74/// ergonomic usage of your error types. Thanks to this rule, from conversion
75/// for `Error<SubsetDomain>` can be implemented for `Error<SupersetDomain>`.
76///
77/// ```rust
78/// # use error_kind::{ErrorDomain, ErrorKind};
79/// #[derive(Clone, Copy, Debug, ErrorKind, PartialEq)]
80/// enum IoErrorKind {
81///     BadFileDescriptor,
82///     FileNotFound,
83///     // ...
84/// }
85///
86/// #[derive(Clone, Copy, Debug, ErrorKind, PartialEq)]
87/// enum ParseErrorKind {
88///     InvalidFormat,
89///     UnexpectedEndOfData,
90///     // ...
91/// }
92///
93/// #[derive(Clone, Copy, Debug, ErrorDomain, PartialEq)]
94/// enum ParseErrorDomain {
95///     Io(IoErrorKind),
96///     Parse(ParseErrorKind),
97///     // ...
98/// }
99///
100/// // Thanks to the rules of `ErrorDomain`, this is possible!
101/// assert_eq!(
102///     ParseErrorDomain::Io(IoErrorKind::FileNotFound),
103///     From::from(IoErrorKind::FileNotFound),
104/// );
105/// ```
106///
107/// This also works across `ErrorDomain` types as well.
108///
109/// ```rust
110/// # use error_kind::{ErrorDomain, ErrorKind};
111/// # #[derive(Clone, Copy, Debug, ErrorKind, PartialEq)]
112/// # enum IoErrorKind {
113/// #     BadFileDescriptor,
114/// #     FileNotFound,
115/// #     // ...
116/// # }
117/// # #[derive(Clone, Copy, Debug, ErrorKind, PartialEq)]
118/// # enum ParseErrorKind {
119/// #     InvalidFormat,
120/// #     UnexpectedEndOfData,
121/// #     // ...
122/// # }
123/// # #[derive(Clone, Copy, Debug, ErrorDomain, PartialEq)]
124/// # enum ParseErrorDomain {
125/// #     Io(IoErrorKind),
126/// #     Parse(ParseErrorKind),
127/// #     // ...
128/// # }
129/// #[derive(Clone, Copy, Debug, ErrorKind, PartialEq)]
130/// enum LogicErrorKind {
131///     InvalidOperation,
132///     TimedOut,
133///     // ...
134/// }
135///
136/// #[derive(Clone, Copy, Debug, ErrorDomain, PartialEq)]
137/// #[error(domains(ParseErrorDomain))] // <- List subset domains here.
138/// enum ProcessingErrorDomain {
139///     Io(IoErrorKind),
140///     Logic(LogicErrorKind),
141///     Parse(ParseErrorKind),
142///     // ...
143/// }
144///
145/// // Thanks to the rules of `ErrorDomain`, this is possible!
146/// assert_eq!(
147///     ProcessingErrorDomain::Io(IoErrorKind::FileNotFound),
148///     From::from(ParseErrorDomain::Io(IoErrorKind::FileNotFound)),
149/// );
150/// ```
151///
152/// > **Learn More:** While you don't need to understand how this works, if you
153/// > are curious to learn, see the [`IsNot`] and [`MatchInto`] traits.
154///
155/// [`IsNot`]: crate::details::IsNot
156/// [`MatchInto`]: crate::details::MatchInto
157pub trait ErrorDomain: ErrorKind {}
158
159// =============================================================================
160// TRAIT IMPLS
161// =============================================================================
162
163// -----------------------------------------------------------------------------
164impl<D: ErrorDomain> ErrorKind for D {}