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" )] |
41 | pub fn from_str<T>(s: &'_ str) -> Result<T, Error> |
42 | where |
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)] |
50 | pub struct Error { |
51 | inner: crate::edit::de::Error, |
52 | } |
53 | |
54 | impl 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 | |
75 | impl 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 | |
84 | impl 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 | |
90 | impl 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" )] |
96 | pub struct Deserializer<'a> { |
97 | input: &'a str, |
98 | } |
99 | |
100 | #[cfg (feature = "parse" )] |
101 | impl<'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" )] |
109 | impl<'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" )] |
223 | pub struct ValueDeserializer<'a> { |
224 | input: &'a str, |
225 | } |
226 | |
227 | #[cfg (feature = "parse" )] |
228 | impl<'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" )] |
236 | impl<'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 | |