Trait FormatSerializer 

pub trait FormatSerializer {
    type Error: Debug;

    // Required methods
    fn begin_struct(&mut self) -> Result<(), Self::Error>;
    fn field_key(&mut self, key: &str) -> Result<(), Self::Error>;
    fn end_struct(&mut self) -> Result<(), Self::Error>;
    fn begin_seq(&mut self) -> Result<(), Self::Error>;
    fn end_seq(&mut self) -> Result<(), Self::Error>;
    fn scalar(&mut self, scalar: ScalarValue<'_>) -> Result<(), Self::Error>;

    // Provided methods
    fn field_metadata(&mut self, _field: &FieldItem) -> Result<(), Self::Error> { ... }
    fn struct_metadata(&mut self, _shape: &Shape) -> Result<(), Self::Error> { ... }
    fn variant_metadata(
        &mut self,
        _variant: &'static Variant,
    ) -> Result<(), Self::Error> { ... }
    fn preferred_field_order(&self) -> FieldOrdering { ... }
    fn raw_serialize_shape(&self) -> Option<&'static Shape> { ... }
    fn raw_scalar(&mut self, content: &str) -> Result<(), Self::Error> { ... }
    fn begin_seq_with_len(&mut self, _len: usize) -> Result<(), Self::Error> { ... }
    fn typed_scalar(
        &mut self,
        scalar_type: ScalarType,
        value: Peek<'_, '_>,
    ) -> Result<(), Self::Error> { ... }
    fn begin_option_some(&mut self) -> Result<(), Self::Error> { ... }
    fn serialize_none(&mut self) -> Result<(), Self::Error> { ... }
    fn begin_enum_variant(
        &mut self,
        _variant_index: usize,
        _variant_name: &'static str,
    ) -> Result<(), Self::Error> { ... }
}

Low-level serializer interface implemented by each format backend.

This is intentionally event-ish: the shared serializer logic owns traversal (struct/enum/seq decisions), while formats own representation details.

Required Associated Types

type Error: Debug

Format-specific error type.

Required Methods

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

Begin a map/object/struct.

fn field_key(&mut self, key: &str) -> Result<(), Self::Error>

Emit a field key within a struct.

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

End a map/object/struct.

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

Begin a sequence/array.

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

End a sequence/array.

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

Emit a scalar value.

Provided Methods

fn field_metadata(&mut self, _field: &FieldItem) -> Result<(), Self::Error>

Optional: Provide field metadata before field_key is called. This allows formats like XML to extract namespace information. Default implementation does nothing.

fn struct_metadata(&mut self, _shape: &Shape) -> Result<(), Self::Error>

Optional: Provide struct/enum type metadata when beginning to serialize it. This allows formats to extract container-level attributes like xml::ns_all. Default implementation does nothing.

fn variant_metadata( &mut self, _variant: &'static Variant, ) -> Result<(), Self::Error>

Optional: Provide variant metadata before serializing an enum variant. This allows formats like XML to use the variant name as the element name for xml::elements serialization. Default implementation does nothing.

fn preferred_field_order(&self) -> FieldOrdering

Preferred field ordering for this format. Formats like XML can request attributes-first ordering to avoid buffering. Default is declaration order.

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

Returns the shape of the format’s raw capture type for serialization.

When serializing a value whose shape matches this, the serializer will extract the inner string and call FormatSerializer::raw_scalar instead of normal serialization.

fn raw_scalar(&mut self, content: &str) -> Result<(), Self::Error>

Emit a raw scalar value (for RawJson, etc.) without any encoding/escaping.

The content is the format-specific raw representation that should be output directly.

fn begin_seq_with_len(&mut self, _len: usize) -> Result<(), Self::Error>

Begin a sequence with known length.

Binary formats (postcard, msgpack) can use this to write a length prefix before the elements. Text formats can ignore the length and just call begin_seq().

Default: delegates to begin_seq().

fn typed_scalar( &mut self, scalar_type: ScalarType, value: Peek<'_, '_>, ) -> Result<(), Self::Error>

Serialize a scalar with full type information.

Binary formats need to encode different integer sizes differently:

• postcard: u8 as raw byte, u16+ as varint, signed use zigzag
• msgpack: different tags for different sizes

Text formats can ignore the type and use the normalized ScalarValue.

Default: normalizes to ScalarValue and calls scalar().

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

Begin serializing Option::Some(value).

Binary formats like postcard write a 0x01 discriminant byte here. Text formats typically don’t need a prefix (they just serialize the value).

Default: no-op (text formats).

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

Serialize Option::None.

Binary formats like postcard write a 0x00 discriminant byte. Text formats typically emit null.

Default: emits ScalarValue::Null.

fn begin_enum_variant( &mut self, _variant_index: usize, _variant_name: &'static str, ) -> Result<(), Self::Error>

Begin an enum variant with its index and name.

Binary formats like postcard write the variant index as a varint. Text formats typically use the variant name as a key or value.

This is called for externally tagged enums before the variant payload. For untagged enums, this is not called.

Default: no-op (text formats handle variants via field_key/scalar).

Implementors