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::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 thiserror::Error; 66 //! # 67 //! #[derive(Error, Debug)] 68 //! pub enum Error { 69 //! #[error("invalid rdo_lookahead_frames {0} (expected < {})", i32::max_value())] 70 //! InvalidLookahead(u32), 71 //! } 72 //! ``` 73 //! 74 //! If one of the additional expression arguments needs to refer to a field of 75 //! the struct or enum, then refer to named fields as `.var` and tuple fields 76 //! as `.0`. 77 //! 78 //! ```rust 79 //! # use thiserror::Error; 80 //! # 81 //! # fn first_char(s: &String) -> char { 82 //! # s.chars().next().unwrap() 83 //! # } 84 //! # 85 //! # #[derive(Debug)] 86 //! # struct Limits { 87 //! # lo: usize, 88 //! # hi: usize, 89 //! # } 90 //! # 91 //! #[derive(Error, Debug)] 92 //! pub enum Error { 93 //! #[error("first letter must be lowercase but was {:?}", first_char(.0))] 94 //! WrongCase(String), 95 //! #[error("invalid index {idx}, expected at least {} and at most {}", .limits.lo, .limits.hi)] 96 //! OutOfBounds { idx: usize, limits: Limits }, 97 //! } 98 //! ``` 99 //! 100 //! - A `From` impl is generated for each variant containing a `#[from]` 101 //! attribute. 102 //! 103 //! Note that the variant must not contain any other fields beyond the source 104 //! error and possibly a backtrace. A backtrace is captured from within the 105 //! `From` impl if there is a field for it. 106 //! 107 //! ```rust 108 //! # const IGNORE: &str = stringify! { 109 //! #[derive(Error, Debug)] 110 //! pub enum MyError { 111 //! Io { 112 //! #[from] 113 //! source: io::Error, 114 //! backtrace: Backtrace, 115 //! }, 116 //! } 117 //! # }; 118 //! ``` 119 //! 120 //! - The Error trait's `source()` method is implemented to return whichever 121 //! field has a `#[source]` attribute or is named `source`, if any. This is 122 //! for identifying the underlying lower level error that caused your error. 123 //! 124 //! The `#[from]` attribute always implies that the same field is `#[source]`, 125 //! so you don't ever need to specify both attributes. 126 //! 127 //! Any error type that implements `std::error::Error` or dereferences to `dyn 128 //! std::error::Error` will work as a source. 129 //! 130 //! ```rust 131 //! # use std::fmt::{self, Display}; 132 //! # use thiserror::Error; 133 //! # 134 //! #[derive(Error, Debug)] 135 //! pub struct MyError { 136 //! msg: String, 137 //! #[source] // optional if field name is `source` 138 //! source: anyhow::Error, 139 //! } 140 //! # 141 //! # impl Display for MyError { 142 //! # fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { 143 //! # unimplemented!() 144 //! # } 145 //! # } 146 //! ``` 147 //! 148 //! - The Error trait's `backtrace()` method is implemented to return whichever 149 //! field has a type named `Backtrace`, if any. 150 //! 151 //! ```rust 152 //! # const IGNORE: &str = stringify! { 153 //! use std::backtrace::Backtrace; 154 //! 155 //! #[derive(Error, Debug)] 156 //! pub struct MyError { 157 //! msg: String, 158 //! backtrace: Backtrace, // automatically detected 159 //! } 160 //! # }; 161 //! ``` 162 //! 163 //! - Errors may use `error(transparent)` to forward the source and Display 164 //! methods straight through to an underlying error without adding an 165 //! additional message. This would be appropriate for enums that need an 166 //! "anything else" variant. 167 //! 168 //! ``` 169 //! # use thiserror::Error; 170 //! # 171 //! #[derive(Error, Debug)] 172 //! pub enum MyError { 173 //! # /* 174 //! ... 175 //! # */ 176 //! 177 //! #[error(transparent)] 178 //! Other(#[from] anyhow::Error), // source and Display delegate to anyhow::Error 179 //! } 180 //! ``` 181 //! 182 //! - See also the [`anyhow`] library for a convenient single error type to use 183 //! in application code. 184 //! 185 //! [`anyhow`]: https://github.com/dtolnay/anyhow 186 187 mod aserror; 188 mod display; 189 190 pub use thiserror_impl::*; 191 192 // Not public API. 193 #[doc(hidden)] 194 pub mod private { 195 pub use crate::aserror::AsDynError; 196 pub use crate::display::{DisplayAsDisplay, PathAsDisplay}; 197 } 198