Skip to main content

toml_writer/
string.rs

1use core::num::Saturating;
2
3/// Describes how a TOML string (key or value) should be formatted.
4///
5/// # Example
6///
7/// ```rust
8/// # #[cfg(feature = "alloc")] {
9/// # use toml_writer::ToTomlValue as _;
10/// let string = "Hello
11/// world!
12/// ";
13/// let string = toml_writer::TomlStringBuilder::new(string).as_default();
14/// let string = string.to_toml_value();
15/// assert_eq!(string, r#""""
16/// Hello
17/// world!
18/// """"#);
19/// # }
20/// ```
21#[derive(Copy, Clone, Debug)]
22pub struct TomlStringBuilder<'s> {
23    decoded: &'s str,
24    metrics: ValueMetrics,
25}
26
27impl<'s> TomlStringBuilder<'s> {
28    pub fn new(decoded: &'s str) -> Self {
29        Self {
30            decoded,
31            metrics: ValueMetrics::calculate(decoded),
32        }
33    }
34
35    pub fn as_default(&self) -> TomlString<'s> {
36        self.as_basic_pretty()
37            .or_else(|| self.as_literal())
38            .or_else(|| self.as_ml_basic_pretty())
39            .or_else(|| self.as_ml_literal())
40            .unwrap_or_else(|| {
41                if self.metrics.newline {
42                    self.as_ml_basic()
43                } else {
44                    self.as_basic()
45                }
46            })
47    }
48
49    pub fn as_literal(&self) -> Option<TomlString<'s>> {
50        if self.metrics.escape_codes
51            || 0 < self.metrics.max_seq_single_quotes
52            || self.metrics.newline
53        {
54            None
55        } else {
56            Some(TomlString {
57                decoded: self.decoded,
58                encoding: Encoding::LiteralString,
59                subset: self.metrics.subset,
60                newline: self.metrics.newline,
61            })
62        }
63    }
64
65    pub fn as_ml_literal(&self) -> Option<TomlString<'s>> {
66        if self.metrics.escape_codes || 2 < self.metrics.max_seq_single_quotes {
67            None
68        } else {
69            Some(TomlString {
70                decoded: self.decoded,
71                encoding: Encoding::MlLiteralString,
72                subset: self.metrics.subset,
73                newline: self.metrics.newline,
74            })
75        }
76    }
77
78    pub fn as_basic_pretty(&self) -> Option<TomlString<'s>> {
79        if self.metrics.escape_codes
80            || self.metrics.escape
81            || 0 < self.metrics.max_seq_double_quotes
82            || self.metrics.newline
83        {
84            None
85        } else {
86            Some(self.as_basic())
87        }
88    }
89
90    pub fn as_ml_basic_pretty(&self) -> Option<TomlString<'s>> {
91        if self.metrics.escape_codes
92            || self.metrics.escape
93            || 2 < self.metrics.max_seq_double_quotes
94        {
95            None
96        } else {
97            Some(self.as_ml_basic())
98        }
99    }
100
101    pub fn as_basic(&self) -> TomlString<'s> {
102        TomlString {
103            decoded: self.decoded,
104            encoding: Encoding::BasicString,
105            subset: self.metrics.subset,
106            newline: self.metrics.newline,
107        }
108    }
109
110    pub fn as_ml_basic(&self) -> TomlString<'s> {
111        TomlString {
112            decoded: self.decoded,
113            encoding: Encoding::MlBasicString,
114            subset: self.metrics.subset,
115            newline: self.metrics.newline,
116        }
117    }
118}
119
120#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
121pub struct TomlString<'s> {
122    decoded: &'s str,
123    encoding: Encoding,
124    subset: bool,
125    newline: bool,
126}
127
128impl crate::WriteTomlValue for TomlString<'_> {
129    fn write_toml_value<W: crate::TomlWrite + ?Sized>(&self, writer: &mut W) -> core::fmt::Result {
130        write_toml_value(
131            self.decoded,
132            Some(self.encoding),
133            self.subset,
134            self.newline,
135            writer,
136        )
137    }
138}
139
140#[derive(Copy, Clone, Debug)]
141pub struct TomlKeyBuilder<'s> {
142    decoded: &'s str,
143    metrics: KeyMetrics,
144}
145
146impl<'s> TomlKeyBuilder<'s> {
147    pub fn new(decoded: &'s str) -> Self {
148        Self {
149            decoded,
150            metrics: KeyMetrics::calculate(decoded),
151        }
152    }
153
154    pub fn as_default(&self) -> TomlKey<'s> {
155        self.as_unquoted()
156            .or_else(|| self.as_basic_pretty())
157            .or_else(|| self.as_literal())
158            .unwrap_or_else(|| self.as_basic())
159    }
160
161    pub fn as_unquoted(&self) -> Option<TomlKey<'s>> {
162        if self.metrics.unquoted {
163            Some(TomlKey {
164                decoded: self.decoded,
165                encoding: None,
166            })
167        } else {
168            None
169        }
170    }
171
172    pub fn as_literal(&self) -> Option<TomlKey<'s>> {
173        if self.metrics.escape_codes || self.metrics.single_quotes {
174            None
175        } else {
176            Some(TomlKey {
177                decoded: self.decoded,
178                encoding: Some(Encoding::LiteralString),
179            })
180        }
181    }
182
183    pub fn as_basic_pretty(&self) -> Option<TomlKey<'s>> {
184        if self.metrics.escape_codes || self.metrics.escape || self.metrics.double_quotes {
185            None
186        } else {
187            Some(self.as_basic())
188        }
189    }
190
191    pub fn as_basic(&self) -> TomlKey<'s> {
192        TomlKey {
193            decoded: self.decoded,
194            encoding: Some(Encoding::BasicString),
195        }
196    }
197}
198
199#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
200pub struct TomlKey<'s> {
201    decoded: &'s str,
202    encoding: Option<Encoding>,
203}
204
205impl crate::WriteTomlKey for TomlKey<'_> {
206    fn write_toml_key<W: crate::TomlWrite + ?Sized>(&self, writer: &mut W) -> core::fmt::Result {
207        let subset = false;
208        let newline = false;
209        write_toml_value(self.decoded, self.encoding, subset, newline, writer)
210    }
211}
212
213#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
214#[repr(u8)]
215#[allow(clippy::enum_variant_names)]
216enum Encoding {
217    LiteralString,
218    BasicString,
219    MlLiteralString,
220    MlBasicString,
221}
222
223impl Encoding {}
224
225fn write_toml_value<W: crate::TomlWrite + ?Sized>(
226    decoded: &str,
227    encoding: Option<Encoding>,
228    subset: bool,
229    newline: bool,
230    writer: &mut W,
231) -> core::fmt::Result {
232    let delimiter = match encoding {
233        Some(Encoding::LiteralString) => "'",
234        Some(Encoding::BasicString) => "\"",
235        Some(Encoding::MlLiteralString) => "'''",
236        Some(Encoding::MlBasicString) => "\"\"\"",
237        None => "",
238    };
239
240    if subset {
241        writer.write_str(delimiter)?;
242        writer.write_str(decoded)?;
243        writer.write_str(delimiter)?;
244    } else {
245        let escaped = match encoding {
246            Some(Encoding::LiteralString) | Some(Encoding::MlLiteralString) => false,
247            Some(Encoding::BasicString) | Some(Encoding::MlBasicString) => true,
248            None => false,
249        };
250        let is_ml = match encoding {
251            Some(Encoding::LiteralString) | Some(Encoding::BasicString) => false,
252            Some(Encoding::MlLiteralString) | Some(Encoding::MlBasicString) => true,
253            None => false,
254        };
255        let newline_prefix = newline && is_ml;
256
257        writer.write_str(delimiter)?;
258        if newline_prefix {
259            writer.newline()?;
260        }
261        if escaped {
262            // ```bnf
263            // basic-unescaped = wschar / %x21 / %x23-5B / %x5D-7E / non-ascii
264            // wschar =  %x20  ; Space
265            // wschar =/ %x09  ; Horizontal tab
266            // escape = %x5C                   ; \
267            // ```
268            let max_seq_double_quotes = if is_ml { 2 } else { 0 };
269            let mut stream = decoded;
270            while !stream.is_empty() {
271                let mut unescaped_end = 0;
272                let mut escaped = None;
273                let mut seq_double_quotes = 0;
274                for (i, b) in stream.as_bytes().iter().enumerate() {
275                    if *b == b'"' {
276                        seq_double_quotes += 1;
277                        if max_seq_double_quotes < seq_double_quotes {
278                            escaped = Some(r#"\""#);
279                            break;
280                        }
281                    } else {
282                        seq_double_quotes = 0;
283                    }
284
285                    match *b {
286                        0x8 => {
287                            escaped = Some(r#"\b"#);
288                            break;
289                        }
290                        0x9 => {
291                            escaped = Some(r#"\t"#);
292                            break;
293                        }
294                        0xa => {
295                            if !is_ml {
296                                escaped = Some(r#"\n"#);
297                                break;
298                            }
299                        }
300                        0xc => {
301                            escaped = Some(r#"\f"#);
302                            break;
303                        }
304                        0xd => {
305                            escaped = Some(r#"\r"#);
306                            break;
307                        }
308                        0x22 => {} // double quote handled earlier
309                        0x5c => {
310                            escaped = Some(r#"\\"#);
311                            break;
312                        }
313                        c if c <= 0x1f || c == 0x7f => {
314                            break;
315                        }
316                        _ => {}
317                    }
318
319                    unescaped_end = i + 1;
320                }
321                let unescaped = &stream[0..unescaped_end];
322                let escaped_str = escaped.unwrap_or("");
323                let end = unescaped_end + if escaped.is_some() { 1 } else { 0 };
324                stream = &stream[end..];
325                writer.write_str(unescaped)?;
326                writer.write_str(escaped_str)?;
327                if escaped.is_none() && !stream.is_empty() {
328                    let b = stream.as_bytes().first().unwrap();
329                    write!(writer, "\\u{:04X}", *b as u32)?;
330                    stream = &stream[1..];
331                }
332            }
333        } else {
334            writer.write_str(decoded)?;
335        }
336        writer.write_str(delimiter)?;
337    }
338
339    Ok(())
340}
341
342#[derive(Copy, Clone, Debug)]
343struct ValueMetrics {
344    // Subset of all string types
345    subset: bool,
346    max_seq_single_quotes: u8,
347    max_seq_double_quotes: u8,
348    escape_codes: bool,
349    escape: bool,
350    newline: bool,
351}
352
353impl ValueMetrics {
354    fn new() -> Self {
355        Self {
356            subset: false,
357            max_seq_single_quotes: 0,
358            max_seq_double_quotes: 0,
359            escape_codes: false,
360            escape: false,
361            newline: false,
362        }
363    }
364
365    fn calculate(s: &str) -> Self {
366        let mut metrics = Self::new();
367
368        // Is the string a perfwct subset of all encodings? Only focused on most common characters
369        // for no to be safe against changes to "pretty" formatting that might arise.
370        if s.bytes()
371            .all(|b| is_bare_key_byte(b) || matches!(b, b'.' | b'/' | b' ' | b':'))
372        {
373            metrics.subset = true;
374            return metrics;
375        }
376
377        let mut prev_single_quotes = Saturating(0);
378        let mut prev_double_quotes = Saturating(0);
379        for byte in s.as_bytes() {
380            if *byte == b'\'' {
381                prev_single_quotes += 1;
382                metrics.max_seq_single_quotes =
383                    metrics.max_seq_single_quotes.max(prev_single_quotes.0);
384            } else {
385                prev_single_quotes = Saturating(0);
386            }
387            if *byte == b'"' {
388                prev_double_quotes += 1;
389                metrics.max_seq_double_quotes =
390                    metrics.max_seq_double_quotes.max(prev_double_quotes.0);
391            } else {
392                prev_double_quotes = Saturating(0);
393            }
394
395            // ```bnf
396            // literal-char = %x09 / %x20-26 / %x28-7E / non-ascii
397            //
398            // basic-unescaped = wschar / %x21 / %x23-5B / %x5D-7E / non-ascii
399            // wschar =  %x20  ; Space
400            // wschar =/ %x09  ; Horizontal tab
401            // escape = %x5C                   ; \
402            // ```
403            match *byte {
404                b'\\' => metrics.escape = true,
405                // Escape codes are needed if any ascii control
406                // characters are present, including \b \f \r.
407                b'\t' => {} // always allowed; remaining neutral on this
408                b'\n' => metrics.newline = true,
409                c if c <= 0x1f || c == 0x7f => metrics.escape_codes = true,
410                _ => {}
411            }
412        }
413
414        metrics
415    }
416}
417
418#[derive(Copy, Clone, Debug)]
419struct KeyMetrics {
420    unquoted: bool,
421    single_quotes: bool,
422    double_quotes: bool,
423    escape_codes: bool,
424    escape: bool,
425}
426
427impl KeyMetrics {
428    fn new() -> Self {
429        Self {
430            unquoted: true,
431            single_quotes: false,
432            double_quotes: false,
433            escape_codes: false,
434            escape: false,
435        }
436    }
437
438    fn calculate(s: &str) -> Self {
439        let mut metrics = Self::new();
440
441        if !s.is_empty() && s.bytes().all(is_bare_key_byte) {
442            return metrics;
443        }
444        metrics.unquoted = false;
445
446        for byte in s.as_bytes() {
447            // ```bnf
448            // literal-char = %x09 / %x20-26 / %x28-7E / non-ascii
449            //
450            // basic-unescaped = wschar / %x21 / %x23-5B / %x5D-7E / non-ascii
451            // wschar =  %x20  ; Space
452            // wschar =/ %x09  ; Horizontal tab
453            // escape = %x5C                   ; \
454            // ```
455            match *byte {
456                b'\'' => metrics.single_quotes = true,
457                b'"' => metrics.double_quotes = true,
458                b'\\' => metrics.escape = true,
459                // Escape codes are needed if any ascii control
460                // characters are present, including \b \f \r.
461                b'\t' => {} // always allowed
462                c if c <= 0x1f || c == 0x7f => metrics.escape_codes = true,
463                _ => {}
464            }
465        }
466
467        metrics
468    }
469}
470
471fn is_bare_key_byte(byte: u8) -> bool {
472    // unquoted-key = 1*( ALPHA / DIGIT / %x2D / %x5F ) ; A-Z / a-z / 0-9 / - / _
473    byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_')
474}