Trait FormatParser 

pub trait FormatParser<'de> {
    type Error;
    type Probe<'a>: ProbeStream<'de, Error = Self::Error>
       where Self: 'a;

    // Required methods
    fn next_event(&mut self) -> Result<Option<ParseEvent<'de>>, Self::Error>;
    fn peek_event(&mut self) -> Result<Option<ParseEvent<'de>>, Self::Error>;
    fn skip_value(&mut self) -> Result<(), Self::Error>;
    fn begin_probe(&mut self) -> Result<Self::Probe<'_>, Self::Error>;

    // Provided methods
    fn capture_raw(&mut self) -> Result<Option<&'de str>, Self::Error> { ... }
    fn raw_capture_shape(&self) -> Option<&'static Shape> { ... }
    fn is_self_describing(&self) -> bool { ... }
    fn hint_struct_fields(&mut self, _num_fields: usize) { ... }
    fn hint_scalar_type(&mut self, _hint: ScalarTypeHint) { ... }
    fn hint_sequence(&mut self) { ... }
    fn hint_array(&mut self, _len: usize) { ... }
    fn hint_option(&mut self) { ... }
    fn hint_map(&mut self) { ... }
    fn hint_enum(&mut self, _variants: &[EnumVariantHint]) { ... }
    fn hint_opaque_scalar(
        &mut self,
        _type_identifier: &'static str,
        _shape: &'static Shape,
    ) -> bool { ... }
    fn current_span(&self) -> Option<Span> { ... }
}

Streaming parser for a specific wire format.

Required Associated Types

type Error

Parser-specific error type.

type Probe<'a>: ProbeStream<'de, Error = Self::Error> where Self: 'a

Evidence cursor type produced by FormatParser::begin_probe.

Required Methods

fn next_event(&mut self) -> Result<Option<ParseEvent<'de>>, Self::Error>

Read the next parse event, or None if the input is exhausted.

Returns Ok(None) at end-of-input (EOF). For formats like TOML where structs can be “reopened” (fields added after the struct was previously exited), callers should continue processing until EOF rather than stopping at StructEnd.

fn peek_event(&mut self) -> Result<Option<ParseEvent<'de>>, Self::Error>

Peek at the next event without consuming it, or None if at EOF.

fn skip_value(&mut self) -> Result<(), Self::Error>

Skip the current value (for unknown fields, etc.).

fn begin_probe(&mut self) -> Result<Self::Probe<'_>, Self::Error>

Begin evidence collection for untagged-enum resolution.

Provided Methods

fn capture_raw(&mut self) -> Result<Option<&'de str>, Self::Error>

Capture the raw representation of the current value without parsing it.

This is used for types like RawJson that want to defer parsing. The parser should skip the value and return the raw bytes/string from the input.

Returns Ok(None) if raw capture is not supported (e.g., streaming mode or formats where raw capture doesn’t make sense).

fn raw_capture_shape(&self) -> Option<&'static Shape>

Returns the shape of the format’s raw capture type (e.g., RawJson::SHAPE).

When the deserializer encounters a shape that matches this, it will use capture_raw to capture the raw representation and store it in a Cow<str> (the raw type must be a newtype over Cow<str>).

Returns None if this format doesn’t support raw capture types.

fn is_self_describing(&self) -> bool

Returns true if this format is self-describing.

Self-describing formats (like JSON, YAML) include type information in the wire format and emit FieldKey events for struct fields.

Non-self-describing formats (like postcard, bincode) don’t include type markers and use OrderedField events, relying on the driver to provide schema information via hint_struct_fields.

fn hint_struct_fields(&mut self, _num_fields: usize)

Hint to the parser that a struct with the given number of fields is expected.

For non-self-describing formats, this allows the parser to emit the correct number of OrderedField events followed by StructEnd.

Self-describing formats can ignore this hint.

fn hint_scalar_type(&mut self, _hint: ScalarTypeHint)

Hint to the parser what scalar type is expected next.

For non-self-describing formats, this allows the parser to correctly decode the next value and emit an appropriate Scalar event.

Self-describing formats can ignore this hint (they determine the type from the wire format).

fn hint_sequence(&mut self)

Hint to the parser that a sequence (array/Vec) is expected.

For non-self-describing formats, this triggers reading the length prefix and setting up sequence state.

Self-describing formats can ignore this hint.

fn hint_array(&mut self, _len: usize)

Hint to the parser that a fixed-size array is expected.

For non-self-describing formats, this tells the parser the array length is known at compile time (from the type), so no length prefix is read. This differs from hint_sequence which reads a length prefix for Vec/slices.

Self-describing formats can ignore this hint.

fn hint_option(&mut self)

Hint to the parser that an Option<T> is expected.

For non-self-describing formats (like postcard), this allows the parser to read the discriminant byte and emit either:

• Scalar(Null) for None (discriminant 0x00)
• Set up state to parse the inner value for Some (discriminant 0x01)

Self-describing formats can ignore this hint (they determine Option presence from the wire format, e.g., null vs value in JSON).

fn hint_map(&mut self)

Hint to the parser that a map is expected.

For non-self-describing formats (like postcard), this allows the parser to read the length prefix and set up map state. The parser should then emit SequenceStart (representing the map entries) followed by pairs of key and value events, and finally SequenceEnd.

Self-describing formats can ignore this hint (they determine map structure from the wire format, e.g., {...} in JSON).

fn hint_enum(&mut self, _variants: &[EnumVariantHint])

Hint to the parser that an enum is expected, providing variant information.

For non-self-describing formats (like postcard), this allows the parser to read the variant discriminant (varint) and map it to the variant name, and to emit appropriate wrapper events for multi-field variants.

The variants slice contains metadata for each variant in declaration order, matching the indices used in the wire format.

Self-describing formats can ignore this hint (they include variant names in the wire format).

fn hint_opaque_scalar( &mut self, _type_identifier: &'static str, _shape: &'static Shape, ) -> bool

Hint to the parser that an opaque scalar type is expected.

For non-self-describing binary formats (like postcard), this allows the parser to use format-specific encoding for types like UUID (16 raw bytes), ULID, OrderedFloat, etc. that have a more efficient binary representation than their string form.

The type_identifier is the type’s identifier string (e.g., “Uuid”, “Ulid”, “OrderedFloat”, DateTime<Utc>). The shape provides access to inner type information (e.g., whether OrderedFloat wraps f32 or f64).

Returns true if the parser will handle this type specially (caller should expect format-specific ScalarValue), or false to fall back to standard handling (e.g., hint_scalar_type(String) for FromStr types).

Self-describing formats can ignore this and return false.

fn current_span(&self) -> Option<Span>

Returns the source span of the most recently consumed event.

This is used for error reporting - when a deserialization error occurs, the span of the last consumed event helps locate the problem in the input.

Parsers that track source positions should override this to return meaningful span information. The default implementation returns None.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors