Dispatch combinators
The providers that route an extensible-data value (an enum or a record) to per-variant or per-field handlers: the matchers take an enum apart, and the builders assemble a record.
Overview
The dispatch combinators handle an enum or a record generically, where the logic for each variant
or field lives in its own provider. Context-Generic Programming (CGP) enables pluggable
trait implementations in Rust, and these combinators extend that to extensible data: the handler
for each variant or field is a provider the context chooses. A hand-written match names every
variant in one place. These combinators drive the extractor and builder traits instead, trying one
variant or filling one field at a time on a context, the
type the implementation runs against. They prove at compile time that every variant is matched or
every field is set. Like every CGP provider, each is zero-sized: its type parameters ride in
PhantomData.
The two halves implement different members of the handler family. The matchers and their adapters
implement Computer and
AsyncComputer only, so a fallible slot takes them
through a promotion. The builders implement Computer,
TryComputer, and
Handler, propagating a step's error in the fallible forms.
None of these names is in the prelude. Every one of them, the value matchers included, is
imported from cgp::extra::dispatch.
The matchers
A matcher consumes an enum. It tries each variant in turn, hands the matched payload to a handler, and needs no wildcard arm, because a variant with no handler is a compile error:
MatchWithHandlersruns a spelled-out list of per-variant handlers, over an owned or a borrowed input.MatchFirstWithHandlersdoes the same for an(Input, Args)input, passing the extra arguments to every handler.MatchWithValueHandlersandMatchWithFieldHandlersbuild that list from the enum's own variants, passing each payload bare or tagged with its variant name.
The list a matcher runs is a list of adapters, each trying one variant or group:
ExtractFieldAndHandleextracts one variant and hands its payload, tagged, to an inner provider.HandleFieldValuestrips the tag, so the inner provider receives the bare payload.DowncastAndHandlenarrows the input to a smaller enum and hands a whole group of variants to one provider.
The builders
A builder produces a record. It starts from an empty partial record, runs a step per field or group of fields, and finalizes the record once every field is set:
BuildWithHandlersruns a list of builder steps and finalizes.BuildAndSetFieldcomputes and sets one field.BuildAndMergebuilds a sub-record and copies its fields in.BuildAndMergeOutputstakes a list of sub-record providers and adds the merge step to each.
Both halves are handler providers, so they compose with the
handler combinators and wire into a context with
delegate_components!.
Related constructs
#[cgp_auto_dispatch]— generates a matcher-backed trait impl for an enum.ExtractField,HasExtractor,FinalizeExtract— the enum-deconstruction traits the matchers stand on.HasBuilder,BuildField,FinalizeBuild— the record-assembly traits the builders stand on.#[derive(CgpData)]— the derive that gives a type the shape these operate over.
The ideas behind it:
- Dispatching — routing an extensible-data value to per-variant and per-field handlers.
- Extensible variants and Extensible records — the data patterns the matchers and builders serve.
Source
- The provider structs are in
cgp-dispatchunderproviders/.
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.