Skip to main content

ExtractFieldAndHandle

Try one variant of an enum, handing its payload to an inner provider on a match and the remainder on to the next arm otherwise.

Overview​

ExtractFieldAndHandle<Tag, Provider> is one arm of a matcher's list. Context-Generic Programming (CGP) lets a context choose the handler behind each trait call, and ExtractFieldAndHandle is where one such choice meets one variant. It takes an extractor, a view of an enum that can rule variants out one at a time, and tries to extract the variant named Tag. On a match it wraps the payload in a Field<Tag, Value> and returns Ok of what Provider computes from it; on a miss it returns Err of the remainder, the extractor with that variant ruled out, which the next arm takes as its input. It runs on a context, the type the implementation runs against, and Provider defaults to UseContext. Like every CGP provider, it carries no runtime value.

Usage​

Import it from cgp::extra::dispatch. It takes the variant's tag, a Symbol! naming it, and an optional inner provider. It is written as an element of a matcher's list, usually around HandleFieldValue so the inner provider receives the bare payload rather than the Field:

use cgp::extra::dispatch::{ExtractFieldAndHandle, HandleFieldValue, MatchWithHandlers};

delegate_components! {
App {
ComputerComponent:
MatchWithHandlers<Product![
ExtractFieldAndHandle<Symbol!("Circle"), HandleFieldValue<ComputeArea>>,
ExtractFieldAndHandle<Symbol!("Rectangle"), HandleFieldValue<ComputeArea>>,
]>,
}
}

The first-argument form ExtractFirstFieldAndHandle<Tag, Provider> is the same arm for an (Input, Args) input, as MatchFirstWithHandlers runs it. It hands Provider a (Field<Tag, Value>, Args) on a match and returns Err((remainder, args)) on a miss, so the arguments travel on with the remainder. Both forms implement Computer and AsyncComputer.

Examples​

Two arms called by hand, to show the Result a matcher's loop passes between them:

use cgp::core::field::traits::HasExtractor;
use cgp::extra::handler::{Computer, ComputerComponent};
use cgp::prelude::*;
use cgp::extra::dispatch::{ExtractFieldAndHandle, HandleFieldValue};

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 type CircleArm = ExtractFieldAndHandle<Symbol!("Circle"), HandleFieldValue<ComputeArea>>;
pub type RectangleArm =
ExtractFieldAndHandle<Symbol!("Rectangle"), HandleFieldValue<ComputeArea>>;

pub struct App;

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

// A hit: the circle arm extracts its variant and returns `Ok` of the area.
let circle = Shape::Circle(Circle { radius: 1.0 });
let hit = CircleArm::compute(&App, code, circle.to_extractor());
assert_eq!(hit.ok(), Some(core::f64::consts::PI));

// A miss: the circle arm hands back the remainder, which the rectangle arm takes.
let rectangle = Shape::Rectangle(Rectangle {
width: 3.0,
height: 4.0,
});
match CircleArm::compute(&App, code, rectangle.to_extractor()) {
Ok(_) => panic!("a rectangle is not a circle"),
Err(remainder) => {
let area = RectangleArm::compute(&App, code, remainder);
assert_eq!(area.ok(), Some(12.0));
}
}
}

The arms are called through the Computer provider trait with App as the context, which needs no wiring because ComputeArea reads nothing from it. to_extractor comes from the HasExtractor impl that #[derive(CgpData)] gives Shape. A matcher runs exactly this chain, and stops at the first Ok.

When to use it​

Reach for ExtractFieldAndHandle when you spell out a matcher's list, one arm per variant, for MatchWithHandlers. When every payload goes to one provider, MatchWithValueHandlers and MatchWithFieldHandlers build the list of these arms from the enum. To handle several variants in one arm, use DowncastAndHandle.

Under the hood​

ExtractFieldAndHandle<Tag, Provider> carries the tag and provider in PhantomData. Its Computer impl calls ExtractField<Tag> on the input, returns early with the remainder on a miss through ?, and converts the payload into a Field for Provider:

pub struct ExtractFieldAndHandle<Tag, Provider = UseContext>(pub PhantomData<(Tag, Provider)>);

#[cgp_provider]
impl<Context, Code, Input, Tag, Value, Provider, Output, Remainder> Computer<Context, Code, Input>
for ExtractFieldAndHandle<Tag, Provider>
where
Input: ExtractField<Tag, Value = Value, Remainder = Remainder>,
Provider: Computer<Context, Code, Field<Tag, Value>, Output = Output>,
{
type Output = Result<Output, Remainder>;

fn compute(
context: &Context,
tag: PhantomData<Code>,
input: Input,
) -> Result<Output, Remainder> {
let value = input.extract_field(PhantomData::<Tag>)?;
let output = Provider::compute(context, tag, value.into());
Ok(output)
}
}

The AsyncComputer impl matches on the extraction and awaits Provider::compute_async on a hit. ExtractFirstFieldAndHandle has the same two impls over (Input, Args), with Output = Result<Output, (Remainder, Args)>.

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.