Trait FormatParser 

pub trait FormatParser<'de> {
    // Required methods
    fn next_event(&mut self) -> Result<Option<ParseEvent<'de>>, ParseError>;
    fn peek_event(&mut self) -> Result<Option<ParseEvent<'de>>, ParseError>;
    fn skip_value(&mut self) -> Result<(), ParseError>;
    fn save(&mut self) -> SavePoint;
    fn restore(&mut self, save_point: SavePoint);

    // Provided methods
    fn next_events(
        &mut self,
        buf: &mut VecDeque<ParseEvent<'de>>,
        limit: usize,
    ) -> Result<usize, ParseError> { ... }
    fn capture_raw(&mut self) -> Result<Option<&'de str>, ParseError> { ... }
    fn input(&self) -> Option<&'de [u8]> { ... }
    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_byte_sequence(&mut self) -> bool { ... }
    fn hint_remaining_byte_sequence(&mut self) -> bool { ... }
    fn hint_array(&mut self, _len: usize) { ... }
    fn hint_option(&mut self) { ... }
    fn hint_map(&mut self) { ... }
    fn hint_dynamic_value(&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> { ... }
    fn format_namespace(&self) -> Option<&'static str> { ... }
}

Streaming parser for a specific wire format.

Required Methods

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

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.

If restore was called, events are first replayed from the internal buffer before reading new events from the input.

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

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

fn skip_value(&mut self) -> Result<(), ParseError>

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

fn save(&mut self) -> SavePoint

Save the current parser position and start recording events.

Returns a SavePoint token. All events returned by next_event after this call are recorded internally. Call restore with this token to replay all recorded events.

This is used for untagged enum resolution: save, read ahead to determine the variant, then restore and parse with the correct type.

fn restore(&mut self, save_point: SavePoint)

Restore to a previous save point, replaying recorded events.

After calling this, subsequent calls to next_event will first return all events that were recorded since the save point, then continue reading from the input.

The save point is consumed - to save again, call save.

Provided Methods

fn next_events( &mut self, buf: &mut VecDeque<ParseEvent<'de>>, limit: usize, ) -> Result<usize, ParseError>

Read multiple parse events into a deque, returning the number of events read.

This is an optimization for parsers that can produce multiple events efficiently in a single call, amortizing function call overhead and improving cache locality.

Returns Ok(0) at end-of-input (EOF).

The default implementation calls next_event repeatedly up to limit times. Parsers can override this for better performance.

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

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 input(&self) -> Option<&'de [u8]>

Returns the raw input bytes, if available.

This is used by the deserializer to implement raw capture when buffering events. The deserializer tracks value boundaries using event spans and slices the input directly.

Returns None for streaming parsers that don’t have the full input.

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_byte_sequence(&mut self) -> bool

Hint to the parser that a byte sequence (Vec<u8>, &[u8], etc.) is expected.

For binary formats like postcard that store Vec<u8> as raw bytes (varint length followed by raw data), this allows bulk reading instead of element-by-element deserialization.

If the parser handles this hint, it should emit Scalar(Bytes(...)) directly. If it doesn’t support this optimization, it should return false and the deserializer will fall back to element-by-element deserialization via hint_sequence.

Returns true if the hint is handled (parser will emit Scalar(Bytes(...))), false otherwise.

fn hint_remaining_byte_sequence(&mut self) -> bool

Hint to the parser that all remaining input bytes should be consumed as a byte slice.

This is used by formats like postcard for trailing opaque payloads where the field boundary is “until end of input” rather than a length prefix.

If handled, the parser should emit Scalar(Bytes(...)) and advance to EOF. Returns true if handled, false to use normal deserialization behavior.

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_dynamic_value(&mut self)

Hint to the parser that a dynamic value is expected.

Non-self-describing formats can use this to switch to a self-describing encoding for dynamic values (e.g., tagged scalar/array/object). Self-describing formats can ignore this hint.

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.

fn format_namespace(&self) -> Option<&'static str>

Returns the format namespace for format-specific proxy resolution.

When a field or container has format-specific proxies (e.g., #[facet(xml::proxy = XmlProxy)]), this namespace is used to look up the appropriate proxy. If no namespace is returned, only the format-agnostic proxy (#[facet(proxy = ...)]) is considered.

Examples:

• XML parser should return Some("xml")
• JSON parser should return Some("json")

Default: returns None (only format-agnostic proxies are used).

Implementors