ron/
options.rs

1//! Roundtrip serde Options module.
2
3use std::io;
4
5use serde::{de, ser};
6use serde_derive::{Deserialize, Serialize};
7
8use crate::{
9    de::Deserializer,
10    error::{Result, SpannedResult},
11    extensions::Extensions,
12    ser::{PrettyConfig, Serializer},
13};
14
15/// Roundtrip serde options.
16///
17/// # Examples
18///
19/// ```
20/// use ron::{Options, extensions::Extensions};
21///
22/// let ron = Options::default()
23///     .with_default_extension(Extensions::IMPLICIT_SOME);
24///
25/// let de: Option<i32> = ron.from_str("42").unwrap();
26/// let ser = ron.to_string(&de).unwrap();
27///
28/// assert_eq!(ser, "42");
29/// ```
30#[derive(Clone, Debug, Serialize, Deserialize)]
31#[serde(default)]
32#[non_exhaustive]
33pub struct Options {
34    /// Extensions that are enabled by default during serialization and
35    ///  deserialization.
36    /// During serialization, these extensions do NOT have to be explicitly
37    ///  enabled in the parsed RON.
38    /// During deserialization, these extensions are used, but their explicit
39    ///  activation is NOT included in the output RON.
40    /// No extensions are enabled by default.
41    pub default_extensions: Extensions,
42    /// Default recursion limit that is checked during serialization and
43    ///  deserialization.
44    /// If set to `None`, infinite recursion is allowed and stack overflow
45    ///  errors can crash the serialization or deserialization process.
46    /// Defaults to `Some(128)`, i.e. 128 recursive calls are allowed.
47    pub recursion_limit: Option<usize>,
48}
49
50impl Default for Options {
51    fn default() -> Self {
52        Self {
53            default_extensions: Extensions::empty(),
54            recursion_limit: Some(128),
55        }
56    }
57}
58
59impl Options {
60    #[must_use]
61    /// Enable `default_extension` by default during serialization and deserialization.
62    pub fn with_default_extension(mut self, default_extension: Extensions) -> Self {
63        self.default_extensions |= default_extension;
64        self
65    }
66
67    #[must_use]
68    /// Do NOT enable `default_extension` by default during serialization and deserialization.
69    pub fn without_default_extension(mut self, default_extension: Extensions) -> Self {
70        self.default_extensions &= !default_extension;
71        self
72    }
73
74    #[must_use]
75    /// Set a maximum recursion limit during serialization and deserialization.
76    pub fn with_recursion_limit(mut self, recursion_limit: usize) -> Self {
77        self.recursion_limit = Some(recursion_limit);
78        self
79    }
80
81    #[must_use]
82    /// Disable the recursion limit during serialization and deserialization.
83    ///
84    /// If you expect to handle highly recursive datastructures, consider wrapping
85    /// `ron` with [`serde_stacker`](https://docs.rs/serde_stacker/latest/serde_stacker/).
86    pub fn without_recursion_limit(mut self) -> Self {
87        self.recursion_limit = None;
88        self
89    }
90}
91
92impl Options {
93    /// A convenience function for building a deserializer
94    /// and deserializing a value of type `T` from a reader.
95    pub fn from_reader<R, T>(&self, mut rdr: R) -> SpannedResult<T>
96    where
97        R: io::Read,
98        T: de::DeserializeOwned,
99    {
100        let mut bytes = Vec::new();
101        rdr.read_to_end(&mut bytes)?;
102
103        self.from_bytes(&bytes)
104    }
105
106    /// A convenience function for building a deserializer
107    /// and deserializing a value of type `T` from a string.
108    pub fn from_str<'a, T>(&self, s: &'a str) -> SpannedResult<T>
109    where
110        T: de::Deserialize<'a>,
111    {
112        self.from_bytes(s.as_bytes())
113    }
114
115    /// A convenience function for building a deserializer
116    /// and deserializing a value of type `T` from bytes.
117    pub fn from_bytes<'a, T>(&self, s: &'a [u8]) -> SpannedResult<T>
118    where
119        T: de::Deserialize<'a>,
120    {
121        self.from_bytes_seed(s, std::marker::PhantomData)
122    }
123
124    /// A convenience function for building a deserializer
125    /// and deserializing a value of type `T` from a reader
126    /// and a seed.
127    pub fn from_reader_seed<R, S, T>(&self, mut rdr: R, seed: S) -> SpannedResult<T>
128    where
129        R: io::Read,
130        S: for<'a> de::DeserializeSeed<'a, Value = T>,
131    {
132        let mut bytes = Vec::new();
133        rdr.read_to_end(&mut bytes)?;
134
135        self.from_bytes_seed(&bytes, seed)
136    }
137
138    /// A convenience function for building a deserializer
139    /// and deserializing a value of type `T` from a string
140    /// and a seed.
141    pub fn from_str_seed<'a, S, T>(&self, s: &'a str, seed: S) -> SpannedResult<T>
142    where
143        S: de::DeserializeSeed<'a, Value = T>,
144    {
145        self.from_bytes_seed(s.as_bytes(), seed)
146    }
147
148    /// A convenience function for building a deserializer
149    /// and deserializing a value of type `T` from bytes
150    /// and a seed.
151    pub fn from_bytes_seed<'a, S, T>(&self, s: &'a [u8], seed: S) -> SpannedResult<T>
152    where
153        S: de::DeserializeSeed<'a, Value = T>,
154    {
155        let mut deserializer = Deserializer::from_bytes_with_options(s, self.clone())?;
156
157        let value = seed
158            .deserialize(&mut deserializer)
159            .map_err(|e| deserializer.span_error(e))?;
160
161        deserializer.end().map_err(|e| deserializer.span_error(e))?;
162
163        Ok(value)
164    }
165
166    /// Serializes `value` into `writer`.
167    ///
168    /// This function does not generate any newlines or nice formatting;
169    /// if you want that, you can use
170    /// [`to_writer_pretty`][Self::to_writer_pretty] instead.
171    pub fn to_writer<W, T>(&self, writer: W, value: &T) -> Result<()>
172    where
173        W: io::Write,
174        T: ?Sized + ser::Serialize,
175    {
176        let mut s = Serializer::with_options(writer, None, self.clone())?;
177        value.serialize(&mut s)
178    }
179
180    /// Serializes `value` into `writer` in a pretty way.
181    pub fn to_writer_pretty<W, T>(&self, writer: W, value: &T, config: PrettyConfig) -> Result<()>
182    where
183        W: io::Write,
184        T: ?Sized + ser::Serialize,
185    {
186        let mut s = Serializer::with_options(writer, Some(config), self.clone())?;
187        value.serialize(&mut s)
188    }
189
190    /// Serializes `value` and returns it as string.
191    ///
192    /// This function does not generate any newlines or nice formatting;
193    /// if you want that, you can use
194    /// [`to_string_pretty`][Self::to_string_pretty] instead.
195    pub fn to_string<T>(&self, value: &T) -> Result<String>
196    where
197        T: ?Sized + ser::Serialize,
198    {
199        let mut output = Vec::new();
200        let mut s = Serializer::with_options(&mut output, None, self.clone())?;
201        value.serialize(&mut s)?;
202        Ok(String::from_utf8(output).expect("Ron should be utf-8"))
203    }
204
205    /// Serializes `value` in the recommended RON layout in a pretty way.
206    pub fn to_string_pretty<T>(&self, value: &T, config: PrettyConfig) -> Result<String>
207    where
208        T: ?Sized + ser::Serialize,
209    {
210        let mut output = Vec::new();
211        let mut s = Serializer::with_options(&mut output, Some(config), self.clone())?;
212        value.serialize(&mut s)?;
213        Ok(String::from_utf8(output).expect("Ron should be utf-8"))
214    }
215}