steam_vdf_parser/binary/
options.rs

1//! Options controlling binary VDF parsing.
2
3/// Strategy for handling byte sequences that are not valid UTF-8 (or UTF-16).
4///
5/// Steam stores string values in binary VDF files as raw byte strings and does
6/// **not** guarantee they are valid UTF-8. Localized fields in particular often
7/// carry legacy code-page bytes (e.g. a Czech app name `Moje Spore v\u{fffd}tvory`
8/// where `0xFD` is Windows-1250 `ý`), which are not valid UTF-8 on their own.
9///
10/// This enum selects what the parser does when it encounters such bytes.
11#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
12#[non_exhaustive]
13pub enum InvalidUtf8 {
14    /// Replace invalid byte sequences with the U+FFFD REPLACEMENT CHARACTER.
15    ///
16    /// Parsing always succeeds. Valid strings are still borrowed zero-copy from
17    /// the input; only strings that actually contain invalid bytes are
18    /// allocated (to hold the replacement characters). This is the default.
19    #[default]
20    Lossy,
21    /// Return an [`Error::InvalidUtf8`](crate::Error::InvalidUtf8) (or
22    /// [`Error::InvalidUtf16`](crate::Error::InvalidUtf16)) error.
23    ///
24    /// Use this when you need to detect corruption rather than silently
25    /// substituting replacement characters.
26    Strict,
27}
28
29/// Options controlling how binary VDF data is parsed.
30///
31/// Construct with [`ParseOptions::new`] (or [`Default`]) and configure with the
32/// builder-style methods:
33///
34/// ```
35/// use steam_vdf_parser::{InvalidUtf8, ParseOptions};
36///
37/// // Default: lossy handling of invalid UTF-8.
38/// let opts = ParseOptions::new();
39/// assert_eq!(opts.invalid_utf8, InvalidUtf8::Lossy);
40///
41/// // Opt into strict error-on-invalid behavior.
42/// let strict = ParseOptions::new().invalid_utf8(InvalidUtf8::Strict);
43/// assert_eq!(strict.invalid_utf8, InvalidUtf8::Strict);
44/// ```
45#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
46#[non_exhaustive]
47pub struct ParseOptions {
48    /// How to handle strings that are not valid UTF-8. Defaults to
49    /// [`InvalidUtf8::Lossy`].
50    pub invalid_utf8: InvalidUtf8,
51}
52
53impl ParseOptions {
54    /// Create a new set of options with default values (lossy UTF-8 handling).
55    pub fn new() -> Self {
56        Self::default()
57    }
58
59    /// Set how invalid UTF-8 byte sequences are handled.
60    pub fn invalid_utf8(mut self, mode: InvalidUtf8) -> Self {
61        self.invalid_utf8 = mode;
62        self
63    }
64}
steam_vdf_parser/binary/options.rs

steam_vdf_parser/binary/
options.rs
