facet_format/
parser.rs

1use crate::FieldEvidence;
2
3/// Streaming cursor that yields serialized fields for solver probing.
4pub trait ProbeStream<'de> {
5    /// Parser-specific error type.
6    type Error;
7
8    /// Produce the next field evidence entry. Returning `Ok(None)` indicates
9    /// the parser ran out of evidence or the format does not need additional
10    /// passes.
11    fn next(&mut self) -> Result<Option<FieldEvidence<'de>>, Self::Error>;
12}
13
14/// Streaming parser for a specific wire format.
15pub trait FormatParser<'de> {
16    /// Parser-specific error type.
17    type Error;
18
19    /// Evidence cursor type produced by [`FormatParser::begin_probe`].
20    type Probe<'a>: ProbeStream<'de, Error = Self::Error>
21    where
22        Self: 'a;
23
24    /// Read the next parse event.
25    fn next_event(&mut self) -> Result<crate::ParseEvent<'de>, Self::Error>;
26
27    /// Peek at the next event without consuming it.
28    fn peek_event(&mut self) -> Result<crate::ParseEvent<'de>, Self::Error>;
29
30    /// Skip the current value (for unknown fields, etc.).
31    fn skip_value(&mut self) -> Result<(), Self::Error>;
32
33    /// Begin evidence collection for untagged-enum resolution.
34    fn begin_probe(&mut self) -> Result<Self::Probe<'_>, Self::Error>;
35
36    /// Capture the raw representation of the current value without parsing it.
37    ///
38    /// This is used for types like `RawJson` that want to defer parsing.
39    /// The parser should skip the value and return the raw bytes/string
40    /// from the input.
41    ///
42    /// Returns `Ok(None)` if raw capture is not supported (e.g., streaming mode
43    /// or formats where raw capture doesn't make sense).
44    fn capture_raw(&mut self) -> Result<Option<&'de str>, Self::Error> {
45        // Default: not supported
46        self.skip_value()?;
47        Ok(None)
48    }
49
50    /// Returns the shape of the format's raw capture type (e.g., `RawJson::SHAPE`).
51    ///
52    /// When the deserializer encounters a shape that matches this, it will use
53    /// `capture_raw` to capture the raw representation and store it in a
54    /// `Cow<str>` (the raw type must be a newtype over `Cow<str>`).
55    ///
56    /// Returns `None` if this format doesn't support raw capture types.
57    fn raw_capture_shape(&self) -> Option<&'static facet_core::Shape> {
58        None
59    }
60}
facet_format/parser.rs

facet_format/
parser.rs
