1 //! [![github]](https://github.com/dtolnay/thiserror) [![crates-io]](https://crates.io/crates/thiserror) [![docs-rs]](https://docs.rs/thiserror)
2 //!
3 //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
4 //! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
5 //! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
6 //!
7 //! <br>
8 //!
9 //! This library provides a convenient derive macro for the standard library's
10 //! [`std::error::Error`] trait.
11 //!
12 //! [`std::error::Error`]: https://doc.rust-lang.org/std/error/trait.Error.html
13 //!
14 //! <br>
15 //!
16 //! # Example
17 //!
18 //! ```rust
19 //! # use std::io;
20 //! use thiserror::Error;
21 //!
22 //! #[derive(Error, Debug)]
23 //! pub enum DataStoreError {
24 //!     #[error("data store disconnected")]
25 //!     Disconnect(#[from] io::Error),
26 //!     #[error("the data for key `{0}` is not available")]
27 //!     Redaction(String),
28 //!     #[error("invalid header (expected {expected:?}, found {found:?})")]
29 //!     InvalidHeader {
30 //!         expected: String,
31 //!         found: String,
32 //!     },
33 //!     #[error("unknown data store error")]
34 //!     Unknown,
35 //! }
36 //! ```
37 //!
38 //! <br>
39 //!
40 //! # Details
41 //!
42 //! - Thiserror deliberately does not appear in your public API. You get the
43 //!   same thing as if you had written an implementation of `std::error::Error`
44 //!   by hand, and switching from handwritten impls to thiserror or vice versa
45 //!   is not a breaking change.
46 //!
47 //! - Errors may be enums, structs with named fields, tuple structs, or unit
48 //!   structs.
49 //!
50 //! - A `Display` impl is generated for your error if you provide
51 //!   `#[error("...")]` messages on the struct or each variant of your enum, as
52 //!   shown above in the example.
53 //!
54 //!   The messages support a shorthand for interpolating fields from the error.
55 //!
56 //!     - `#[error("{var}")]`&ensp;⟶&ensp;`write!("{}", self.var)`
57 //!     - `#[error("{0}")]`&ensp;⟶&ensp;`write!("{}", self.0)`
58 //!     - `#[error("{var:?}")]`&ensp;⟶&ensp;`write!("{:?}", self.var)`
59 //!     - `#[error("{0:?}")]`&ensp;⟶&ensp;`write!("{:?}", self.0)`
60 //!
61 //!   These shorthands can be used together with any additional format args,
62 //!   which may be arbitrary expressions. For example:
63 //!
64 //!   ```rust
65 //!   # use std::i32;
66 //!   # use thiserror::Error;
67 //!   #
68 //!   #[derive(Error, Debug)]
69 //!   pub enum Error {
70 //!       #[error("invalid rdo_lookahead_frames {0} (expected < {})", i32::MAX)]
71 //!       InvalidLookahead(u32),
72 //!   }
73 //!   ```
74 //!
75 //!   If one of the additional expression arguments needs to refer to a field of
76 //!   the struct or enum, then refer to named fields as `.var` and tuple fields
77 //!   as `.0`.
78 //!
79 //!   ```rust
80 //!   # use thiserror::Error;
81 //!   #
82 //!   # fn first_char(s: &String) -> char {
83 //!   #     s.chars().next().unwrap()
84 //!   # }
85 //!   #
86 //!   # #[derive(Debug)]
87 //!   # struct Limits {
88 //!   #     lo: usize,
89 //!   #     hi: usize,
90 //!   # }
91 //!   #
92 //!   #[derive(Error, Debug)]
93 //!   pub enum Error {
94 //!       #[error("first letter must be lowercase but was {:?}", first_char(.0))]
95 //!       WrongCase(String),
96 //!       #[error("invalid index {idx}, expected at least {} and at most {}", .limits.lo, .limits.hi)]
97 //!       OutOfBounds { idx: usize, limits: Limits },
98 //!   }
99 //!   ```
100 //!
101 //! - A `From` impl is generated for each variant containing a `#[from]`
102 //!   attribute.
103 //!
104 //!   Note that the variant must not contain any other fields beyond the source
105 //!   error and possibly a backtrace. A backtrace is captured from within the
106 //!   `From` impl if there is a field for it.
107 //!
108 //!   ```rust
109 //!   # const IGNORE: &str = stringify! {
110 //!   #[derive(Error, Debug)]
111 //!   pub enum MyError {
112 //!       Io {
113 //!           #[from]
114 //!           source: io::Error,
115 //!           backtrace: Backtrace,
116 //!       },
117 //!   }
118 //!   # };
119 //!   ```
120 //!
121 //! - The Error trait's `source()` method is implemented to return whichever
122 //!   field has a `#[source]` attribute or is named `source`, if any. This is
123 //!   for identifying the underlying lower level error that caused your error.
124 //!
125 //!   The `#[from]` attribute always implies that the same field is `#[source]`,
126 //!   so you don't ever need to specify both attributes.
127 //!
128 //!   Any error type that implements `std::error::Error` or dereferences to `dyn
129 //!   std::error::Error` will work as a source.
130 //!
131 //!   ```rust
132 //!   # use std::fmt::{self, Display};
133 //!   # use thiserror::Error;
134 //!   #
135 //!   #[derive(Error, Debug)]
136 //!   pub struct MyError {
137 //!       msg: String,
138 //!       #[source]  // optional if field name is `source`
139 //!       source: anyhow::Error,
140 //!   }
141 //!   #
142 //!   # impl Display for MyError {
143 //!   #     fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
144 //!   #         unimplemented!()
145 //!   #     }
146 //!   # }
147 //!   ```
148 //!
149 //! - The Error trait's `provide()` method is implemented to provide whichever
150 //!   field has a type named `Backtrace`, if any, as a
151 //!   `std::backtrace::Backtrace`.
152 //!
153 //!   ```rust
154 //!   # const IGNORE: &str = stringify! {
155 //!   use std::backtrace::Backtrace;
156 //!
157 //!   #[derive(Error, Debug)]
158 //!   pub struct MyError {
159 //!       msg: String,
160 //!       backtrace: Backtrace,  // automatically detected
161 //!   }
162 //!   # };
163 //!   ```
164 //!
165 //! - If a field is both a source (named `source`, or has `#[source]` or
166 //!   `#[from]` attribute) *and* is marked `#[backtrace]`, then the Error
167 //!   trait's `provide()` method is forwarded to the source's `provide` so that
168 //!   both layers of the error share the same backtrace.
169 //!
170 //!   ```rust
171 //!   # const IGNORE: &str = stringify! {
172 //!   #[derive(Error, Debug)]
173 //!   pub enum MyError {
174 //!       Io {
175 //!           #[backtrace]
176 //!           source: io::Error,
177 //!       },
178 //!   }
179 //!   # };
180 //!   ```
181 //!
182 //! - Errors may use `error(transparent)` to forward the source and Display
183 //!   methods straight through to an underlying error without adding an
184 //!   additional message. This would be appropriate for enums that need an
185 //!   "anything else" variant.
186 //!
187 //!   ```
188 //!   # use thiserror::Error;
189 //!   #
190 //!   #[derive(Error, Debug)]
191 //!   pub enum MyError {
192 //!       # /*
193 //!       ...
194 //!       # */
195 //!
196 //!       #[error(transparent)]
197 //!       Other(#[from] anyhow::Error),  // source and Display delegate to anyhow::Error
198 //!   }
199 //!   ```
200 //!
201 //!   Another use case is hiding implementation details of an error
202 //!   representation behind an opaque error type, so that the representation is
203 //!   able to evolve without breaking the crate's public API.
204 //!
205 //!   ```
206 //!   # use thiserror::Error;
207 //!   #
208 //!   // PublicError is public, but opaque and easy to keep compatible.
209 //!   #[derive(Error, Debug)]
210 //!   #[error(transparent)]
211 //!   pub struct PublicError(#[from] ErrorRepr);
212 //!
213 //!   impl PublicError {
214 //!       // Accessors for anything we do want to expose publicly.
215 //!   }
216 //!
217 //!   // Private and free to change across minor version of the crate.
218 //!   #[derive(Error, Debug)]
219 //!   enum ErrorRepr {
220 //!       # /*
221 //!       ...
222 //!       # */
223 //!   }
224 //!   ```
225 //!
226 //! - See also the [`anyhow`] library for a convenient single error type to use
227 //!   in application code.
228 //!
229 //!   [`anyhow`]: https://github.com/dtolnay/anyhow
230 
231 #![doc(html_root_url = "https://docs.rs/thiserror/1.0.49")]
232 #![allow(
233     clippy::module_name_repetitions,
234     clippy::needless_lifetimes,
235     clippy::return_self_not_must_use,
236     clippy::wildcard_imports
237 )]
238 #![cfg_attr(error_generic_member_access, feature(error_generic_member_access))]
239 
240 mod aserror;
241 mod display;
242 #[cfg(error_generic_member_access)]
243 mod provide;
244 
245 pub use thiserror_impl::*;
246 
247 // Not public API.
248 #[doc(hidden)]
249 pub mod __private {
250     #[doc(hidden)]
251     pub use crate::aserror::AsDynError;
252     #[doc(hidden)]
253     pub use crate::display::AsDisplay;
254     #[cfg(error_generic_member_access)]
255     #[doc(hidden)]
256     pub use crate::provide::ThiserrorProvide;
257 }
258