Skip to main content

MatchWithValueHandlers

Match an enum by building the per-variant handler list from its own variants, passing each payload as a bare value.

Overview​

MatchWithValueHandlers<Provider> is the matcher for the common case, where every variant's payload goes to one provider. Context-Generic Programming (CGP) enables pluggable trait implementations in Rust, and MatchWithValueHandlers is that pluggability at its plainest: whichever provider the context wired serves every payload. Rather than a spelled-out list, it builds one adapter per variant from the input enum's own field list, so adding a variant needs no new arm. It hands each payload to Provider as a bare value on a context, the type the implementation runs against. That makes it the form for payload handlers that are ordinary computers over the payload type, such as ones from #[cgp_computer]. Provider defaults to UseContext, so each payload goes back through the context's own wiring. Like every CGP provider, it carries no runtime value.

Usage​

It is not in the prelude; import it from cgp::extra::dispatch. It takes one optional type parameter, the per-variant provider. With the default UseContext, it is wired by input type with the open statement, beside the entries that answer each payload type:

delegate_components! {
App {
open ComputerComponent;

@ComputerComponent.<Code> Code.[Circle, Rectangle]: ComputeArea,
@ComputerComponent.<Code> Code.Shape: MatchWithValueHandlers,
}
}

Each key has one segment per type parameter of CanCompute<Code, Input>, and the generic first segment matches any code, so the second selects by the input type. A named provider needs no per-type entries: ComputerComponent: MatchWithValueHandlers<ComputeArea> sends every payload straight to ComputeArea.

The borrowed form MatchWithValueHandlersRef<Provider> matches without moving the value and answers two components. It serves ComputerComponent over &Input with a provider over borrowed payloads, and ComputerRefComponent over Input with a ComputerRef provider over the payloads:

delegate_components! {
App {
ComputerComponent: MatchWithValueHandlersRef<ComputeAreaOfRef>,
ComputerRefComponent: MatchWithValueHandlersRef<ComputeAreaByRef>,
}
}

check_components! {
App {
ComputerComponent: <'a> ((), &'a Shape),
ComputerRefComponent: ((), Shape),
}
}

MatchWithValueHandlersMut<Provider> serves ComputerComponent the same way over &mut Input, with a provider over mutable payloads that can change them in place. Its …Ref entries cannot resolve, because PromoteRef lends only a shared borrow. The multi-argument forms MatchFirstWithValueHandlers, MatchFirstWithValueHandlersRef, and MatchFirstWithValueHandlersMut are on MatchFirstWithHandlers.

Examples​

A context that computes each shape directly, and a Shape enum by matching it:

use cgp::extra::dispatch::MatchWithValueHandlers;
use cgp::extra::handler::{Computer, ComputerComponent};
use cgp::prelude::*;
use cgp::extra::handler::CanCompute;

pub struct Circle {
pub radius: f64,
}

pub struct Rectangle {
pub width: f64,
pub height: f64,
}

#[derive(CgpData)]
pub enum Shape {
Circle(Circle),
Rectangle(Rectangle),
}

#[cgp_new_provider]
impl<Context, Code> Computer<Context, Code, Circle> for ComputeArea {
type Output = f64;

fn compute(_context: &Context, _code: PhantomData<Code>, circle: Circle) -> f64 {
core::f64::consts::PI * circle.radius * circle.radius
}
}

#[cgp_provider]
impl<Context, Code> Computer<Context, Code, Rectangle> for ComputeArea {
type Output = f64;

fn compute(_context: &Context, _code: PhantomData<Code>, rectangle: Rectangle) -> f64 {
rectangle.width * rectangle.height
}
}

pub struct App;

delegate_components! {
App {
open ComputerComponent;

@ComputerComponent.<Code> Code.[Circle, Rectangle]: ComputeArea,
@ComputerComponent.<Code> Code.Shape: MatchWithValueHandlers,
}
}

check_components! {
App {
ComputerComponent: [((), Circle), ((), Rectangle), ((), Shape)],
}
}

pub fn demo() {
let code = PhantomData::<()>;

let rectangle = Shape::Rectangle(Rectangle {
width: 3.0,
height: 4.0,
});
assert_eq!(App.compute(code, rectangle), 12.0);

let circle = App.compute(code, Shape::Circle(Circle { radius: 1.0 }));
assert!((circle - core::f64::consts::PI).abs() < 1e-9);
}

For a Shape, the matcher extracts the payload and asks App again, through UseContext, for the payload's type, which reaches ComputeArea. App is an environmental context, and the component is parameter-targeted: it acts on the input. Existing code writes the same table as a UseInputDelegate table.

When to use it​

Reach for MatchWithValueHandlers when every variant's payload goes to the same provider as a bare value. This is the usual case, and shorter than spelling out the list with MatchWithHandlers. Reach for MatchWithFieldHandlers when the handler needs the variant's name, and for MatchWithHandlers when different variants need providers the field list cannot generate.

Under the hood​

MatchWithValueHandlers<Provider> is a type alias over UseInputDelegate, which keys on the input type and, for each enum, maps it to MatchWithHandlers over a list built from the enum's HasFields:

pub type MatchWithValueHandlers<Provider = UseContext> =
UseInputDelegate<MatchWithFieldHandlersInputs<HandleFieldValue<Provider>>>;

delegate_components! {
<Input: HasFieldHandlers<MapExtractFieldAndHandle<Provider>>, Provider>
new MatchWithFieldHandlersInputs<Provider> {
Input: MatchWithHandlers<Input::Handlers>
}
}

Wrapping Provider in HandleFieldValue is its one difference from MatchWithFieldHandlers, and it makes each payload arrive bare. The list is built by the HasFieldHandlers machinery described on MatchWithFieldHandlers.

The borrowed forms are structs with a delegation table rather than aliases. The owned-input entries key a UseInputDelegate on &'a Input or &'a mut Input and reach MatchWithHandlersRef or MatchWithHandlersMut; the …Ref entries wrap that in PromoteRef, which borrows the input and hands each borrowed payload to the provider's …Ref impl:

delegate_components! {
<Provider>
MatchWithValueHandlersRef<Provider> {
[
ComputerComponent,
TryComputerComponent,
AsyncComputerComponent,
HandlerComponent,
]:
UseInputDelegate<MatchWithFieldHandlersInputsRef<HandleFieldValue<Provider>>>,
[
ComputerRefComponent,
TryComputerRefComponent,
AsyncComputerRefComponent,
HandlerRefComponent,
]:
PromoteRef<UseInputDelegate<MatchWithFieldHandlersInputsRef<HandleFieldValue<PromoteRef<Provider>>>>>,
}
}

Common Mistakes​

The input must be an enum. The list is built by walking a sum-type field list, so a struct, whose field list is a product, has no list and no extractor. Wiring a Scene struct fails with:

error[E0277]: the trait bound `MatchWithHandlers<_>: Computer<App, (), Scene>` is not satisfied

Handle a struct's fields one by one instead, or build a record with the builders.

The borrowed forms route fallible components they cannot answer. Their tables list TryComputerComponent, HandlerComponent, and the fallible …Ref components, but the borrowed matchers behind them implement only Computer and AsyncComputer, so wiring HandlerComponent: MatchWithValueHandlersRef<ComputeAreaOfRef> fails at the check:

= note: required for `MatchWithValueHandlersRef<ComputeAreaOfRef>` to implement `IsProviderFor<HandlerComponent, App, ((), &'a Shape)>`

The owned MatchWithValueHandlers has the same limit. Wire the matcher to ComputerComponent or AsyncComputerComponent, and lift it with a promotion as MatchWithHandlers shows.

Variants with no fields all reach the same handler. The variant derives give each such variant, such as Closed or Paused(), the payload Nil. The provider receives only the payload, so its Nil impl serves every one of them and cannot tell which variant it got. Use MatchWithFieldHandlers when they need different handling: its provider receives Field<Symbol!("Closed"), Nil> and can read the variant name from the tag. The borrowed forms handle these variants too, with a &Nil or &mut Nil payload.

The ideas behind it:

Source​


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.