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}")]` ⟶ `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::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