thiserror_no_std/lib.rs
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&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K
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_no_std::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}")]` ⟶ `write!("{}", self.var)`
57//! - `#[error("{0}")]` ⟶ `write!("{}", self.0)`
58//! - `#[error("{var:?}")]` ⟶ `write!("{:?}", self.var)`
59//! - `#[error("{0:?}")]` ⟶ `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_no_std::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_no_std::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_no_std::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 `backtrace()` method is implemented to return whichever
150//! field has a type named `Backtrace`, if any.
151//!
152//! ```rust
153//! # const IGNORE: &str = stringify! {
154//! use std::backtrace::Backtrace;
155//!
156//! #[derive(Error, Debug)]
157//! pub struct MyError {
158//! msg: String,
159//! backtrace: Backtrace, // automatically detected
160//! }
161//! # };
162//! ```
163//!
164//! - If a field is both a source (named `source`, or has `#[source]` or
165//! `#[from]` attribute) *and* is marked `#[backtrace]`, then the Error
166//! trait's `backtrace()` method is forwarded to the source's backtrace.
167//!
168//! ```rust
169//! # const IGNORE: &str = stringify! {
170//! #[derive(Error, Debug)]
171//! pub enum MyError {
172//! Io {
173//! #[backtrace]
174//! source: io::Error,
175//! },
176//! }
177//! # };
178//! ```
179//!
180//! - Errors may use `error(transparent)` to forward the source and Display
181//! methods straight through to an underlying error without adding an
182//! additional message. This would be appropriate for enums that need an
183//! "anything else" variant.
184//!
185//! ```
186//! # use thiserror_no_std::Error;
187//! #
188//! #[derive(Error, Debug)]
189//! pub enum MyError {
190//! # /*
191//! ...
192//! # */
193//!
194//! #[error(transparent)]
195//! Other(#[from] anyhow::Error), // source and Display delegate to anyhow::Error
196//! }
197//! ```
198//!
199//! - See also the [`anyhow`] library for a convenient single error type to use
200//! in application code.
201//!
202//! [`anyhow`]: https://github.com/dtolnay/anyhow
203
204#![allow(
205 // Clippy bug: https://github.com/rust-lang/rust-clippy/issues/7421
206 clippy::doc_markdown,
207 clippy::module_name_repetitions,
208 clippy::return_self_not_must_use,
209)]
210#![cfg_attr(not(feature = "std"), no_std)]
211
212#[cfg(feature = "std")]
213mod aserror;
214mod display;
215
216pub use thiserror_impl_no_std::*;
217
218// Not public API.
219#[doc(hidden)]
220pub mod private {
221 #[cfg(feature = "std")]
222 pub use crate::aserror::AsDynError;
223 #[cfg(feature = "std")]
224 pub use crate::display::PathAsDisplay;
225
226 pub use crate::display::DisplayAsDisplay;
227}