toml/
de.rs

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(s))
46}
47
48/// Errors that can occur when deserializing a type.
49#[derive(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(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::fmt::Debug for Error {
91    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
92        self.inner.fmt(f)
93    }
94}
95
96impl std::error::Error for Error {}
97
98/// Deserialization TOML document
99///
100/// To deserializes TOML values, instead of documents, see [`ValueDeserializer`].
101#[cfg(feature = "parse")]
102pub struct Deserializer<'a> {
103    input: &'a str,
104}
105
106#[cfg(feature = "parse")]
107impl<'a> Deserializer<'a> {
108    /// Deserialization implementation for TOML.
109    pub fn new(input: &'a str) -> Self {
110        Self { input }
111    }
112}
113
114#[cfg(feature = "parse")]
115impl<'de> serde::Deserializer<'de> for Deserializer<'_> {
116    type Error = Error;
117
118    fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
119    where
120        V: serde::de::Visitor<'de>,
121    {
122        let inner = toml_edit::de::Deserializer::parse(self.input).map_err(Error::new)?;
123        inner.deserialize_any(visitor).map_err(Error::new)
124    }
125
126    // `None` is interpreted as a missing field so be sure to implement `Some`
127    // as a present field.
128    fn deserialize_option<V>(self, visitor: V) -> Result<V::Value, Error>
129    where
130        V: serde::de::Visitor<'de>,
131    {
132        let inner = toml_edit::de::Deserializer::parse(self.input).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 = toml_edit::de::Deserializer::parse(self.input).map_err(Error::new)?;
145        inner
146            .deserialize_newtype_struct(name, visitor)
147            .map_err(Error::new)
148    }
149
150    fn deserialize_struct<V>(
151        self,
152        name: &'static str,
153        fields: &'static [&'static str],
154        visitor: V,
155    ) -> Result<V::Value, Error>
156    where
157        V: serde::de::Visitor<'de>,
158    {
159        let inner = toml_edit::de::Deserializer::parse(self.input).map_err(Error::new)?;
160        inner
161            .deserialize_struct(name, fields, visitor)
162            .map_err(Error::new)
163    }
164
165    // Called when the type to deserialize is an enum, as opposed to a field in the type.
166    fn deserialize_enum<V>(
167        self,
168        name: &'static str,
169        variants: &'static [&'static str],
170        visitor: V,
171    ) -> Result<V::Value, Error>
172    where
173        V: serde::de::Visitor<'de>,
174    {
175        let inner = toml_edit::de::Deserializer::parse(self.input).map_err(Error::new)?;
176        inner
177            .deserialize_enum(name, variants, visitor)
178            .map_err(Error::new)
179    }
180
181    serde::forward_to_deserialize_any! {
182        bool u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 char str string seq
183        bytes byte_buf map unit
184        ignored_any unit_struct tuple_struct tuple identifier
185    }
186}
187
188/// Deserialization TOML [value][crate::Value]
189///
190/// # Example
191///
192/// ```
193/// use serde::Deserialize;
194///
195/// #[derive(Deserialize)]
196/// struct Config {
197///     title: String,
198///     owner: Owner,
199/// }
200///
201/// #[derive(Deserialize)]
202/// struct Owner {
203///     name: String,
204/// }
205///
206/// let config = Config::deserialize(toml::de::ValueDeserializer::new(
207///     r#"{ title = 'TOML Example', owner = { name = 'Lisa' } }"#
208/// )).unwrap();
209///
210/// assert_eq!(config.title, "TOML Example");
211/// assert_eq!(config.owner.name, "Lisa");
212/// ```
213#[cfg(feature = "parse")]
214pub struct ValueDeserializer<'a> {
215    input: &'a str,
216}
217
218#[cfg(feature = "parse")]
219impl<'a> ValueDeserializer<'a> {
220    /// Deserialization implementation for TOML.
221    pub fn new(input: &'a str) -> Self {
222        Self { input }
223    }
224}
225
226#[cfg(feature = "parse")]
227impl<'de> serde::Deserializer<'de> for ValueDeserializer<'_> {
228    type Error = Error;
229
230    fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
231    where
232        V: serde::de::Visitor<'de>,
233    {
234        let inner = self
235            .input
236            .parse::<toml_edit::de::ValueDeserializer>()
237            .map_err(Error::new)?;
238        inner.deserialize_any(visitor).map_err(Error::new)
239    }
240
241    // `None` is interpreted as a missing field so be sure to implement `Some`
242    // as a present field.
243    fn deserialize_option<V>(self, visitor: V) -> Result<V::Value, Error>
244    where
245        V: serde::de::Visitor<'de>,
246    {
247        let inner = self
248            .input
249            .parse::<toml_edit::de::ValueDeserializer>()
250            .map_err(Error::new)?;
251        inner.deserialize_option(visitor).map_err(Error::new)
252    }
253
254    fn deserialize_newtype_struct<V>(
255        self,
256        name: &'static str,
257        visitor: V,
258    ) -> Result<V::Value, Error>
259    where
260        V: serde::de::Visitor<'de>,
261    {
262        let inner = self
263            .input
264            .parse::<toml_edit::de::ValueDeserializer>()
265            .map_err(Error::new)?;
266        inner
267            .deserialize_newtype_struct(name, visitor)
268            .map_err(Error::new)
269    }
270
271    fn deserialize_struct<V>(
272        self,
273        name: &'static str,
274        fields: &'static [&'static str],
275        visitor: V,
276    ) -> Result<V::Value, Error>
277    where
278        V: serde::de::Visitor<'de>,
279    {
280        let inner = self
281            .input
282            .parse::<toml_edit::de::ValueDeserializer>()
283            .map_err(Error::new)?;
284        inner
285            .deserialize_struct(name, fields, visitor)
286            .map_err(Error::new)
287    }
288
289    // Called when the type to deserialize is an enum, as opposed to a field in the type.
290    fn deserialize_enum<V>(
291        self,
292        name: &'static str,
293        variants: &'static [&'static str],
294        visitor: V,
295    ) -> Result<V::Value, Error>
296    where
297        V: serde::de::Visitor<'de>,
298    {
299        let inner = self
300            .input
301            .parse::<toml_edit::de::ValueDeserializer>()
302            .map_err(Error::new)?;
303        inner
304            .deserialize_enum(name, variants, visitor)
305            .map_err(Error::new)
306    }
307
308    serde::forward_to_deserialize_any! {
309        bool u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 char str string seq
310        bytes byte_buf map unit
311        ignored_any unit_struct tuple_struct tuple identifier
312    }
313}
toml/de.rs

toml/
de.rs
