Debian Codegraph @

.cargo/vendor/thiserror/src/lib.rs

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