DeserializeVariantFields
Read an enum from {"Variant": payload}, reading the payload through the context.
Overview
In cgp-serde, a serialization library built with
Context-Generic Programming (CGP), DeserializeVariantFields is the reading half of
SerializeVariantFields. It reads the variant's name, asks the
context, the type whose wiring holds the application's choices, to read that variant's payload,
and builds the enum. The enum derives only CGP's variant traits, through
#[derive(CgpVariant)] or the narrower
HasFields derive, and every variant holds one unnamed
payload or no fields.
Definition
pub struct DeserializeVariantFields;
#[cgp_impl(DeserializeVariantFields)]
impl<'de, Value> ValueDeserializer<'de, Value>
where
Value: FromFields,
Value::Fields: VariantsDeserializer<'de, Self>,
{ ... }
FromFields builds the enum from one variant of its
variant list. VariantsDeserializer is a private trait that finds the variant by name or position,
and it requires, for each variant, that the context can read the payload's type, Nil for a
variant with no fields.
Usage
Import it from cgp_serde::providers, and wire it beside an entry for each variant's payload type:
delegate_components! {
App {
open ValueDeserializerComponent;
@ValueDeserializerComponent.[u64, String]: UseSerde,
@ValueDeserializerComponent.Nil: SerializeUnit,
@ValueDeserializerComponent.Circle: DeserializeRecordFields,
@ValueDeserializerComponent.Shape: DeserializeVariantFields,
}
}
Behavior
The provider reads the variant's identifier, then its payload through the context. A text format
names the variant, and a binary format such as postcard gives its position in the declaration, as
Serde's derive does. With JSON, {"Circle":{"radius":3}} reads as Shape::Circle, and
{"Empty":null} reads as Shape::Empty because Nil is wired to
SerializeUnit. The payload may
borrow from the input: an enum Token<'a> with a Word(&'a str) variant reads {"Word":"hello"}
without copying the string.
The context's entry for Nil decides how a variant with no fields is read. SerializeUnit
reads only a unit, so {"Empty":{}}, which Serde's derive writes for Empty {}, is rejected with
invalid type: map, expected unit. Whatever the entry, the bare "Empty" that Serde's derive
writes for a unit variant is rejected, with invalid type: unit variant, expected newtype variant.
So JSON written by Serde's derive cannot be read back for these variants.
The provider reports an unknown variant with the names it expected, in the same wording as Serde's derive:
unknown variant `Square`, expected one of `Circle`, `Rectangle`, `Label`, `Empty` at line 1 column 9
A payload of the wrong type fails with that payload's own error, and input that is not a single
variant, such as {} or an array, fails with the format's error.
Context dependencies
CanDeserializeValue<'de, P> for the payload type P of every variant, which is Nil for a
variant with no fields.
Pairing
SerializeVariantFields writes the form it reads.
When to use it
Reach for DeserializeVariantFields to read an enum whose payloads should follow the context's
choices. It reads only Serde's default enum form, with one payload or none per variant, and reads
a variant with no fields only in the {"Empty":null} form its serializing pair writes. An enum
written in another form, or with variants that hold several fields, keeps its own Serde impl and is
wired to UseSerde.
Related constructs
DeserializeRecordFieldsis the matching provider for a struct, and usually reads a variant's payload.SerializeUnitreads theNilpayload of a variant with no fields.
The ideas behind it
- Derive-free records: reading data through CGP's field traits.
- Extensible variants: building an enum from one of its named variants.
Source
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the project's source. See How AI is used in this project.