toml/ser/
mod.rs

Help
1//! Serializing Rust structures into TOML.
2//!
3//! This module contains all the Serde support for serializing Rust structures
4//! into TOML documents (as strings). Note that some top-level functions here
5//! are also provided at the top of the crate.
6
7#[cfg(feature = "display")]
8mod array;
9#[cfg(feature = "display")]
10mod map;
11#[cfg(feature = "display")]
12mod ser_value;
13
14#[cfg(feature = "display")]
15pub use ser_value::ValueSerializer;
16
17/// Serialize the given data structure as a String of TOML.
18///
19/// Serialization can fail if `T`'s implementation of `Serialize` decides to
20/// fail, if `T` contains a map with non-string keys, or if `T` attempts to
21/// serialize an unsupported datatype such as an enum, tuple, or tuple struct.
22///
23/// To serialize TOML values, instead of documents, see [`ValueSerializer`].
24///
25/// # Examples
26///
27/// ```
28/// use serde::Serialize;
29///
30/// #[derive(Serialize)]
31/// struct Config {
32///     database: Database,
33/// }
34///
35/// #[derive(Serialize)]
36/// struct Database {
37///     ip: String,
38///     port: Vec<u16>,
39///     connection_max: u32,
40///     enabled: bool,
41/// }
42///
43/// let config = Config {
44///     database: Database {
45///         ip: "192.168.1.1".to_string(),
46///         port: vec![8001, 8002, 8003],
47///         connection_max: 5000,
48///         enabled: false,
49///     },
50/// };
51///
52/// let toml = toml::to_string(&config).unwrap();
53/// println!("{}", toml)
54/// ```
55#[cfg(feature = "display")]
56pub fn to_string<T>(value: &T) -> Result<String, Error>
57where
58    T: serde::ser::Serialize + ?Sized,
59{
60    let mut output = String::new();
61    let serializer = Serializer::new(&mut output);
62    value.serialize(serializer)?;
63    Ok(output)
64}
65
66/// Serialize the given data structure as a "pretty" String of TOML.
67///
68/// This is identical to `to_string` except the output string has a more
69/// "pretty" output. See `Serializer::pretty` for more details.
70///
71/// To serialize TOML values, instead of documents, see [`ValueSerializer`].
72///
73/// For greater customization, instead serialize to a
74/// [`toml_edit::DocumentMut`](https://docs.rs/toml_edit/latest/toml_edit/struct.DocumentMut.html).
75#[cfg(feature = "display")]
76pub fn to_string_pretty<T>(value: &T) -> Result<String, Error>
77where
78    T: serde::ser::Serialize + ?Sized,
79{
80    let mut output = String::new();
81    let serializer = Serializer::pretty(&mut output);
82    value.serialize(serializer)?;
83    Ok(output)
84}
85
86/// Errors that can occur when serializing a type.
87#[derive(Clone, PartialEq, Eq)]
88pub struct Error {
89    pub(crate) inner: crate::edit::ser::Error,
90}
91
92impl Error {
93    pub(crate) fn new(inner: impl std::fmt::Display) -> Self {
94        Self {
95            inner: crate::edit::ser::Error::Custom(inner.to_string()),
96        }
97    }
98
99    #[cfg(feature = "display")]
100    pub(crate) fn wrap(inner: crate::edit::ser::Error) -> Self {
101        Self { inner }
102    }
103
104    pub(crate) fn unsupported_type(t: Option<&'static str>) -> Self {
105        Self {
106            inner: crate::edit::ser::Error::UnsupportedType(t),
107        }
108    }
109
110    pub(crate) fn unsupported_none() -> Self {
111        Self {
112            inner: crate::edit::ser::Error::UnsupportedNone,
113        }
114    }
115
116    pub(crate) fn key_not_string() -> Self {
117        Self {
118            inner: crate::edit::ser::Error::KeyNotString,
119        }
120    }
121}
122
123impl serde::ser::Error for Error {
124    fn custom<T>(msg: T) -> Self
125    where
126        T: std::fmt::Display,
127    {
128        Error::new(msg)
129    }
130}
131
132impl std::fmt::Display for Error {
133    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
134        self.inner.fmt(f)
135    }
136}
137
138impl std::fmt::Debug for Error {
139    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
140        self.inner.fmt(f)
141    }
142}
143
144impl std::error::Error for Error {}
145
146/// Serialization for TOML documents.
147///
148/// This structure implements serialization support for TOML to serialize an
149/// arbitrary type to TOML. Note that the TOML format does not support all
150/// datatypes in Rust, such as enums, tuples, and tuple structs. These types
151/// will generate an error when serialized.
152///
153/// Currently a serializer always writes its output to an in-memory `String`,
154/// which is passed in when creating the serializer itself.
155///
156/// To serialize TOML values, instead of documents, see [`ValueSerializer`].
157#[cfg(feature = "display")]
158pub struct Serializer<'d> {
159    dst: &'d mut String,
160    settings: crate::fmt::DocumentFormatter,
161}
162
163#[cfg(feature = "display")]
164impl<'d> Serializer<'d> {
165    /// Creates a new serializer which will emit TOML into the buffer provided.
166    ///
167    /// The serializer can then be used to serialize a type after which the data
168    /// will be present in `dst`.
169    pub fn new(dst: &'d mut String) -> Self {
170        Self {
171            dst,
172            settings: Default::default(),
173        }
174    }
175
176    /// Apply a default "pretty" policy to the document
177    ///
178    /// For greater customization, instead serialize to a
179    /// [`toml_edit::DocumentMut`](https://docs.rs/toml_edit/latest/toml_edit/struct.DocumentMut.html).
180    pub fn pretty(dst: &'d mut String) -> Self {
181        let mut ser = Serializer::new(dst);
182        ser.settings.multiline_array = true;
183        ser
184    }
185}
186
187#[cfg(feature = "display")]
188impl<'d> serde::ser::Serializer for Serializer<'d> {
189    type Ok = ();
190    type Error = Error;
191    type SerializeSeq = array::SerializeDocumentArray<'d>;
192    type SerializeTuple = array::SerializeDocumentArray<'d>;
193    type SerializeTupleStruct = array::SerializeDocumentArray<'d>;
194    type SerializeTupleVariant = array::SerializeDocumentArray<'d>;
195    type SerializeMap = map::SerializeDocumentTable<'d>;
196    type SerializeStruct = map::SerializeDocumentTable<'d>;
197    type SerializeStructVariant = serde::ser::Impossible<Self::Ok, Self::Error>;
198
199    fn serialize_bool(self, v: bool) -> Result<Self::Ok, Self::Error> {
200        write_document(
201            self.dst,
202            self.settings,
203            toml_edit::ser::ValueSerializer::new().serialize_bool(v),
204        )
205    }
206
207    fn serialize_i8(self, v: i8) -> Result<Self::Ok, Self::Error> {
208        write_document(
209            self.dst,
210            self.settings,
211            toml_edit::ser::ValueSerializer::new().serialize_i8(v),
212        )
213    }
214
215    fn serialize_i16(self, v: i16) -> Result<Self::Ok, Self::Error> {
216        write_document(
217            self.dst,
218            self.settings,
219            toml_edit::ser::ValueSerializer::new().serialize_i16(v),
220        )
221    }
222
223    fn serialize_i32(self, v: i32) -> Result<Self::Ok, Self::Error> {
224        write_document(
225            self.dst,
226            self.settings,
227            toml_edit::ser::ValueSerializer::new().serialize_i32(v),
228        )
229    }
230
231    fn serialize_i64(self, v: i64) -> Result<Self::Ok, Self::Error> {
232        write_document(
233            self.dst,
234            self.settings,
235            toml_edit::ser::ValueSerializer::new().serialize_i64(v),
236        )
237    }
238
239    fn serialize_u8(self, v: u8) -> Result<Self::Ok, Self::Error> {
240        write_document(
241            self.dst,
242            self.settings,
243            toml_edit::ser::ValueSerializer::new().serialize_u8(v),
244        )
245    }
246
247    fn serialize_u16(self, v: u16) -> Result<Self::Ok, Self::Error> {
248        write_document(
249            self.dst,
250            self.settings,
251            toml_edit::ser::ValueSerializer::new().serialize_u16(v),
252        )
253    }
254
255    fn serialize_u32(self, v: u32) -> Result<Self::Ok, Self::Error> {
256        write_document(
257            self.dst,
258            self.settings,
259            toml_edit::ser::ValueSerializer::new().serialize_u32(v),
260        )
261    }
262
263    fn serialize_u64(self, v: u64) -> Result<Self::Ok, Self::Error> {
264        write_document(
265            self.dst,
266            self.settings,
267            toml_edit::ser::ValueSerializer::new().serialize_u64(v),
268        )
269    }
270
271    fn serialize_f32(self, v: f32) -> Result<Self::Ok, Self::Error> {
272        write_document(
273            self.dst,
274            self.settings,
275            toml_edit::ser::ValueSerializer::new().serialize_f32(v),
276        )
277    }
278
279    fn serialize_f64(self, v: f64) -> Result<Self::Ok, Self::Error> {
280        write_document(
281            self.dst,
282            self.settings,
283            toml_edit::ser::ValueSerializer::new().serialize_f64(v),
284        )
285    }
286
287    fn serialize_char(self, v: char) -> Result<Self::Ok, Self::Error> {
288        write_document(
289            self.dst,
290            self.settings,
291            toml_edit::ser::ValueSerializer::new().serialize_char(v),
292        )
293    }
294
295    fn serialize_str(self, v: &str) -> Result<Self::Ok, Self::Error> {
296        write_document(
297            self.dst,
298            self.settings,
299            toml_edit::ser::ValueSerializer::new().serialize_str(v),
300        )
301    }
302
303    fn serialize_bytes(self, v: &[u8]) -> Result<Self::Ok, Self::Error> {
304        write_document(
305            self.dst,
306            self.settings,
307            toml_edit::ser::ValueSerializer::new().serialize_bytes(v),
308        )
309    }
310
311    fn serialize_none(self) -> Result<Self::Ok, Self::Error> {
312        write_document(
313            self.dst,
314            self.settings,
315            toml_edit::ser::ValueSerializer::new().serialize_none(),
316        )
317    }
318
319    fn serialize_some<T>(self, v: &T) -> Result<Self::Ok, Self::Error>
320    where
321        T: serde::ser::Serialize + ?Sized,
322    {
323        write_document(
324            self.dst,
325            self.settings,
326            toml_edit::ser::ValueSerializer::new().serialize_some(v),
327        )
328    }
329
330    fn serialize_unit(self) -> Result<Self::Ok, Self::Error> {
331        write_document(
332            self.dst,
333            self.settings,
334            toml_edit::ser::ValueSerializer::new().serialize_unit(),
335        )
336    }
337
338    fn serialize_unit_struct(self, name: &'static str) -> Result<Self::Ok, Self::Error> {
339        write_document(
340            self.dst,
341            self.settings,
342            toml_edit::ser::ValueSerializer::new().serialize_unit_struct(name),
343        )
344    }
345
346    fn serialize_unit_variant(
347        self,
348        name: &'static str,
349        variant_index: u32,
350        variant: &'static str,
351    ) -> Result<Self::Ok, Self::Error> {
352        write_document(
353            self.dst,
354            self.settings,
355            toml_edit::ser::ValueSerializer::new().serialize_unit_variant(
356                name,
357                variant_index,
358                variant,
359            ),
360        )
361    }
362
363    fn serialize_newtype_struct<T>(self, name: &'static str, v: &T) -> Result<Self::Ok, Self::Error>
364    where
365        T: serde::ser::Serialize + ?Sized,
366    {
367        write_document(
368            self.dst,
369            self.settings,
370            toml_edit::ser::ValueSerializer::new().serialize_newtype_struct(name, v),
371        )
372    }
373
374    fn serialize_newtype_variant<T>(
375        self,
376        name: &'static str,
377        variant_index: u32,
378        variant: &'static str,
379        value: &T,
380    ) -> Result<Self::Ok, Self::Error>
381    where
382        T: serde::ser::Serialize + ?Sized,
383    {
384        write_document(
385            self.dst,
386            self.settings,
387            toml_edit::ser::ValueSerializer::new().serialize_newtype_variant(
388                name,
389                variant_index,
390                variant,
391                value,
392            ),
393        )
394    }
395
396    fn serialize_seq(self, len: Option<usize>) -> Result<Self::SerializeSeq, Self::Error> {
397        let ser = toml_edit::ser::ValueSerializer::new()
398            .serialize_seq(len)
399            .map_err(Error::wrap)?;
400        let ser = array::SerializeDocumentArray::new(self, ser);
401        Ok(ser)
402    }
403
404    fn serialize_tuple(self, len: usize) -> Result<Self::SerializeTuple, Self::Error> {
405        self.serialize_seq(Some(len))
406    }
407
408    fn serialize_tuple_struct(
409        self,
410        _name: &'static str,
411        len: usize,
412    ) -> Result<Self::SerializeTupleStruct, Self::Error> {
413        self.serialize_seq(Some(len))
414    }
415
416    fn serialize_tuple_variant(
417        self,
418        _name: &'static str,
419        _variant_index: u32,
420        _variant: &'static str,
421        len: usize,
422    ) -> Result<Self::SerializeTupleVariant, Self::Error> {
423        self.serialize_seq(Some(len))
424    }
425
426    fn serialize_map(self, len: Option<usize>) -> Result<Self::SerializeMap, Self::Error> {
427        let ser = toml_edit::ser::ValueSerializer::new()
428            .serialize_map(len)
429            .map_err(Error::wrap)?;
430        let ser = map::SerializeDocumentTable::new(self, ser);
431        Ok(ser)
432    }
433
434    fn serialize_struct(
435        self,
436        _name: &'static str,
437        len: usize,
438    ) -> Result<Self::SerializeStruct, Self::Error> {
439        self.serialize_map(Some(len))
440    }
441
442    fn serialize_struct_variant(
443        self,
444        name: &'static str,
445        _variant_index: u32,
446        _variant: &'static str,
447        _len: usize,
448    ) -> Result<Self::SerializeStructVariant, Self::Error> {
449        Err(Error::unsupported_type(Some(name)))
450    }
451}
452
453#[cfg(feature = "display")]
454pub(crate) fn write_document(
455    dst: &mut String,
456    mut settings: crate::fmt::DocumentFormatter,
457    value: Result<toml_edit::Value, crate::edit::ser::Error>,
458) -> Result<(), Error> {
459    use std::fmt::Write;
460    use toml_edit::visit_mut::VisitMut as _;
461
462    let value = value.map_err(Error::wrap)?;
463    let mut table = match toml_edit::Item::Value(value).into_table() {
464        Ok(i) => i,
465        Err(_) => {
466            return Err(Error::unsupported_type(None));
467        }
468    };
469
470    settings.visit_table_mut(&mut table);
471
472    let doc: toml_edit::DocumentMut = table.into();
473    write!(dst, "{doc}").unwrap();
474
475    Ok(())
476}
toml/ser/mod.rs

toml/ser/
mod.rs
