1//! Deserializing TOML into Rust structures.
2//!
3//! This module contains all the Serde support for deserializing TOML documents
4//! into Rust structures. Note that some top-level functions here are also
5//! provided at the top of the crate.
6
7/// Deserializes a string into a type.
8///
9/// This function will attempt to interpret `s` as a TOML document and
10/// deserialize `T` from the document.
11///
12/// To deserializes TOML values, instead of documents, see [`ValueDeserializer`].
13///
14/// # Examples
15///
16/// ```
17/// use serde::Deserialize;
18///
19/// #[derive(Deserialize)]
20/// struct Config {
21/// title: String,
22/// owner: Owner,
23/// }
24///
25/// #[derive(Deserialize)]
26/// struct Owner {
27/// name: String,
28/// }
29///
30/// let config: Config = toml::from_str(r#"
31/// title = 'TOML Example'
32///
33/// [owner]
34/// name = 'Lisa'
35/// "#).unwrap();
36///
37/// assert_eq!(config.title, "TOML Example");
38/// assert_eq!(config.owner.name, "Lisa");
39/// ```
40#[cfg(feature = "parse")]
41pub fn from_str<T>(s: &'_ str) -> Result<T, Error>
42where
43 T: serde::de::DeserializeOwned,
44{
45 T::deserialize(Deserializer::new(input:s))
46}
47
48/// Errors that can occur when deserializing a type.
49#[derive(Debug, PartialEq, Eq, Clone)]
50pub struct Error {
51 inner: crate::edit::de::Error,
52}
53
54impl Error {
55 fn new(inner: crate::edit::de::Error) -> Self {
56 Self { inner }
57 }
58
59 pub(crate) fn add_key(&mut self, key: String) {
60 self.inner.add_key(key)
61 }
62
63 /// What went wrong
64 pub fn message(&self) -> &str {
65 self.inner.message()
66 }
67
68 /// The start/end index into the original document where the error occurred
69 #[cfg(feature = "parse")]
70 pub fn span(&self) -> Option<std::ops::Range<usize>> {
71 self.inner.span()
72 }
73}
74
75impl serde::de::Error for Error {
76 fn custom<T>(msg: T) -> Self
77 where
78 T: std::fmt::Display,
79 {
80 Error::new(inner:crate::edit::de::Error::custom(msg))
81 }
82}
83
84impl std::fmt::Display for Error {
85 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
86 self.inner.fmt(f)
87 }
88}
89
90impl std::error::Error for Error {}
91
92/// Deserialization TOML document
93///
94/// To deserializes TOML values, instead of documents, see [`ValueDeserializer`].
95#[cfg(feature = "parse")]
96pub struct Deserializer<'a> {
97 input: &'a str,
98}
99
100#[cfg(feature = "parse")]
101impl<'a> Deserializer<'a> {
102 /// Deserialization implementation for TOML.
103 pub fn new(input: &'a str) -> Self {
104 Self { input }
105 }
106}
107
108#[cfg(feature = "parse")]
109impl<'de, 'a> serde::Deserializer<'de> for Deserializer<'a> {
110 type Error = Error;
111
112 fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
113 where
114 V: serde::de::Visitor<'de>,
115 {
116 let inner = self
117 .input
118 .parse::<toml_edit::de::Deserializer>()
119 .map_err(Error::new)?;
120 inner.deserialize_any(visitor).map_err(Error::new)
121 }
122
123 // `None` is interpreted as a missing field so be sure to implement `Some`
124 // as a present field.
125 fn deserialize_option<V>(self, visitor: V) -> Result<V::Value, Error>
126 where
127 V: serde::de::Visitor<'de>,
128 {
129 let inner = self
130 .input
131 .parse::<toml_edit::de::Deserializer>()
132 .map_err(Error::new)?;
133 inner.deserialize_option(visitor).map_err(Error::new)
134 }
135
136 fn deserialize_newtype_struct<V>(
137 self,
138 name: &'static str,
139 visitor: V,
140 ) -> Result<V::Value, Error>
141 where
142 V: serde::de::Visitor<'de>,
143 {
144 let inner = self
145 .input
146 .parse::<toml_edit::de::Deserializer>()
147 .map_err(Error::new)?;
148 inner
149 .deserialize_newtype_struct(name, visitor)
150 .map_err(Error::new)
151 }
152
153 fn deserialize_struct<V>(
154 self,
155 name: &'static str,
156 fields: &'static [&'static str],
157 visitor: V,
158 ) -> Result<V::Value, Error>
159 where
160 V: serde::de::Visitor<'de>,
161 {
162 let inner = self
163 .input
164 .parse::<toml_edit::de::Deserializer>()
165 .map_err(Error::new)?;
166 inner
167 .deserialize_struct(name, fields, visitor)
168 .map_err(Error::new)
169 }
170
171 // Called when the type to deserialize is an enum, as opposed to a field in the type.
172 fn deserialize_enum<V>(
173 self,
174 name: &'static str,
175 variants: &'static [&'static str],
176 visitor: V,
177 ) -> Result<V::Value, Error>
178 where
179 V: serde::de::Visitor<'de>,
180 {
181 let inner = self
182 .input
183 .parse::<toml_edit::de::Deserializer>()
184 .map_err(Error::new)?;
185 inner
186 .deserialize_enum(name, variants, visitor)
187 .map_err(Error::new)
188 }
189
190 serde::forward_to_deserialize_any! {
191 bool u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 char str string seq
192 bytes byte_buf map unit
193 ignored_any unit_struct tuple_struct tuple identifier
194 }
195}
196
197/// Deserialization TOML [value][crate::Value]
198///
199/// # Example
200///
201/// ```
202/// use serde::Deserialize;
203///
204/// #[derive(Deserialize)]
205/// struct Config {
206/// title: String,
207/// owner: Owner,
208/// }
209///
210/// #[derive(Deserialize)]
211/// struct Owner {
212/// name: String,
213/// }
214///
215/// let config = Config::deserialize(toml::de::ValueDeserializer::new(
216/// r#"{ title = 'TOML Example', owner = { name = 'Lisa' } }"#
217/// )).unwrap();
218///
219/// assert_eq!(config.title, "TOML Example");
220/// assert_eq!(config.owner.name, "Lisa");
221/// ```
222#[cfg(feature = "parse")]
223pub struct ValueDeserializer<'a> {
224 input: &'a str,
225}
226
227#[cfg(feature = "parse")]
228impl<'a> ValueDeserializer<'a> {
229 /// Deserialization implementation for TOML.
230 pub fn new(input: &'a str) -> Self {
231 Self { input }
232 }
233}
234
235#[cfg(feature = "parse")]
236impl<'de, 'a> serde::Deserializer<'de> for ValueDeserializer<'a> {
237 type Error = Error;
238
239 fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
240 where
241 V: serde::de::Visitor<'de>,
242 {
243 let inner = self
244 .input
245 .parse::<toml_edit::de::ValueDeserializer>()
246 .map_err(Error::new)?;
247 inner.deserialize_any(visitor).map_err(Error::new)
248 }
249
250 // `None` is interpreted as a missing field so be sure to implement `Some`
251 // as a present field.
252 fn deserialize_option<V>(self, visitor: V) -> Result<V::Value, Error>
253 where
254 V: serde::de::Visitor<'de>,
255 {
256 let inner = self
257 .input
258 .parse::<toml_edit::de::ValueDeserializer>()
259 .map_err(Error::new)?;
260 inner.deserialize_option(visitor).map_err(Error::new)
261 }
262
263 fn deserialize_newtype_struct<V>(
264 self,
265 name: &'static str,
266 visitor: V,
267 ) -> Result<V::Value, Error>
268 where
269 V: serde::de::Visitor<'de>,
270 {
271 let inner = self
272 .input
273 .parse::<toml_edit::de::ValueDeserializer>()
274 .map_err(Error::new)?;
275 inner
276 .deserialize_newtype_struct(name, visitor)
277 .map_err(Error::new)
278 }
279
280 fn deserialize_struct<V>(
281 self,
282 name: &'static str,
283 fields: &'static [&'static str],
284 visitor: V,
285 ) -> Result<V::Value, Error>
286 where
287 V: serde::de::Visitor<'de>,
288 {
289 let inner = self
290 .input
291 .parse::<toml_edit::de::ValueDeserializer>()
292 .map_err(Error::new)?;
293 inner
294 .deserialize_struct(name, fields, visitor)
295 .map_err(Error::new)
296 }
297
298 // Called when the type to deserialize is an enum, as opposed to a field in the type.
299 fn deserialize_enum<V>(
300 self,
301 name: &'static str,
302 variants: &'static [&'static str],
303 visitor: V,
304 ) -> Result<V::Value, Error>
305 where
306 V: serde::de::Visitor<'de>,
307 {
308 let inner = self
309 .input
310 .parse::<toml_edit::de::ValueDeserializer>()
311 .map_err(Error::new)?;
312 inner
313 .deserialize_enum(name, variants, visitor)
314 .map_err(Error::new)
315 }
316
317 serde::forward_to_deserialize_any! {
318 bool u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 char str string seq
319 bytes byte_buf map unit
320 ignored_any unit_struct tuple_struct tuple identifier
321 }
322}
323