Skip to main content

#[derive(FromVariant)]

#[derive(FromVariant)] lets generic code construct an enum variant selected by a type-level tag.

Overview​

In Context-Generic Programming (CGP), generic code needs a trait interface to construct a variant selected by a type parameter. Shape::Circle(circle) fixes both the enum and variant at the call site.

#[derive(FromVariant)] generates a constructor for each variant, keyed by its name as a type-level tag:

Shape::from_variant(PhantomData::<Symbol!("Circle")>, circle)

The tagged call constructs the same value as Shape::Circle(circle). Because the tag can be a type parameter, a function can select a variant generically. A bound on the enum type also lets the function work across different enums.

The derive generates only per-variant trait implementations, without companion types or state tracking. ExtractField provides the reverse operation: extracting a payload from an enum.

Usage​

Apply FromVariant to an enum without arguments or helper attributes:

use cgp::prelude::*;

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

Each variant's name becomes a Symbol! tag and its payload type becomes the constructor's value type. Generic parameters, lifetimes, and a where clause are carried onto every generated impl.

The derive comes with the prelude, but the FromVariant trait it implements does not, so code that calls from_variant imports the trait from cgp::core::field::traits.

Every variant needs one unnamed payload or none​

Every variant must contain exactly one unnamed field, whose type becomes the constructor's payload type, or no fields at all. A variant with no fields, written Closed, Closed(), or Closed {}, takes the payload Nil: Status::from_variant(PhantomData::<Symbol!("Closed")>, Nil) builds Status::Closed. Multi-field and struct-style variants with fields fail with Expected variant to contain exactly one unnamed field, or no fields. Individual variants cannot opt out.

Wrap a richer payload in a dedicated struct so the variant contains a single payload type:

pub struct Circle {
pub radius: f64,
}

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

HasFields accepts every variant shape when only a structural representation and whole-value conversions are needed. FromVariant accepts a variantless enum but does not emit any implementations for it.

The derive parses an enum, so applying it to a struct fails at parse time with expected `enum` . The struct analogue, setting one field of a value being assembled, is #[derive(BuildField)].

What it does not generate​

FromVariant generates constructors without a structural representation or an extractor. Derive HasFields for the representation and ExtractField for extraction, or use CgpData for all of them.

Examples​

A function can use FromVariant<Tag> to stay generic over the variant it constructs:

use cgp::core::field::traits::FromVariant;
use cgp::prelude::*;

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

fn wrap<Tag>(tag: PhantomData<Tag>, value: <Shape as FromVariant<Tag>>::Value) -> Shape
where
Shape: FromVariant<Tag>,
{
Shape::from_variant(tag, value)
}

wrap constructs either variant, with the payload type determined by the tag:

let circle = wrap(PhantomData::<Symbol!("Circle")>, Circle { radius: 2.0 });
let rect = wrap(PhantomData::<Symbol!("Rectangle")>, Rectangle { width: 3.0, height: 4.0 });

The FromVariant<Tag> bound connects each tag to its payload type and constructor. Without that interface, Shape::Circle and Shape::Rectangle remain separate expressions with different argument types.

Upcasting lets an implementation construct a small local enum and convert it into a larger one, so the implementation only needs to know the variants it constructs. The cast walks the source enum's representation with its extractor and builds each variant with the target's FromVariant constructors, so the source needs HasFields and ExtractField while the target needs only FromVariant. Both enums derive CgpData here, which covers either side:

use cgp::core::field::impls::CanUpcast; // not in the prelude

let expr = LispSubExpr::Ident(Ident("+".to_owned())).upcast(PhantomData::<LispExpr>);

An upcast succeeds when every source variant has a matching variant in the target enum. The compiler checks this correspondence, so the implementation can name only the variants it needs. See CanUpcast for the conversion and its trait requirements.

When to use it​

Use FromVariant when generic code must construct a variant selected by a tag. Prefer a direct constructor when the call site already knows the variant:

  • A variant selected by a type parameter: use FromVariant<Tag> to connect the tag, payload type, and constructor.
  • An upcast target: generic casts use these constructors to build the target enum's variants.
  • An ordinary constructor call: use Shape::Circle(circle) when the variant is known directly.
  • Construction and extraction together: use CgpData or CgpVariant to include both operations and the representation.

FromVariant constructs an enum from a payload, while ExtractField extracts a payload from an enum. Generic pipelines that do both commonly derive both.

Under the hood​

The derive emits one FromVariant implementation per variant. For this input:

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

it produces:

impl FromVariant<Symbol!("Circle")> for Shape {
type Value = Circle;

fn from_variant(_tag: PhantomData<Symbol!("Circle")>, value: <Self as FromVariant<Symbol!("Circle")>>::Value) -> Self {
Self::Circle(value)
}
}

impl FromVariant<Symbol!("Rectangle")> for Shape {
type Value = Rectangle;

fn from_variant(_tag: PhantomData<Symbol!("Rectangle")>, value: <Self as FromVariant<Symbol!("Rectangle")>>::Value) -> Self {
Self::Rectangle(value)
}
}

Each implementation calls the ordinary variant constructor. It exposes the payload type as <Shape as FromVariant<Tag>>::Value, so a generic signature can name that type without selecting a concrete variant.

PhantomData<Tag> selects the trait implementation without storing a runtime tag value. Specify a tag such as PhantomData::<Symbol!("Circle")> when the call would otherwise be ambiguous.

The FromVariant trait itself is defined in the library; the derive supplies only these per-variant impls. Each is aimed at the variant it came from, so a conflict with a hand-written impl underlines that variant rather than the whole #[derive(FromVariant)].

Common Mistakes​

Every variant must carry one unnamed payload or none. Individual variants cannot opt out. HasFields accepts all variant shapes when only a representation is needed.

Specify the tag whenever the enum has more than one variant. In Shape::from_variant(PhantomData::<Symbol!("Circle")>, value), the type argument selects Circle. The payload type does not select the implementation, even when every variant's payload type is different, so an untagged call fails:

error[E0283]: type annotations needed
|
| let _ = Shape::from_variant(PhantomData, Circle { radius: 2.0 });
| ----- ^^^^^^^^^^^ cannot infer type of the type parameter `T` declared on the struct `PhantomData`
| |
| type must be known at this point

Only an enum with a single variant lets the compiler infer the tag.

Variants sharing a payload type have distinct tags. A tag that does not match an implemented variant produces an unsatisfied FromVariant bound.

A variant name is a Symbol! of its identifier, matched exactly. Symbol!("Circle") and Symbol!("circle") are unrelated types, so a case slip reports as an unsatisfied FromVariant bound.

A variantless enum is accepted without generating implementations. It has nothing to construct; code requiring a FromVariant implementation will fail at that use site.

It does not accept a struct. The struct-side analogue is #[derive(BuildField)].

These references cover the related derives, generated traits, and supporting types:

  • #[derive(ExtractField)] — the reverse operation, taking a variant out rather than putting one in; commonly derived alongside this one.
  • #[derive(CgpData)] — the umbrella derive, which includes this slice.
  • #[derive(HasFields)] — the whole-shape representation, which this derive does not generate, and the only derive that accepts every variant shape.
  • #[derive(BuildField)] — the struct analogue: setting one field rather than choosing one variant.
  • FromVariant — the trait this generates impls of.
  • Symbol! — the tag that names a variant.
  • CanUpcast — widening a smaller enum into a larger one, built on these constructors.
  • Type-level lists — the Either/Void chain the constructed variants correspond to.

The ideas behind it are explained on these concept pages:

  • Extensible variants — construction by name, and building through a small local enum before widening.

Source​

The implementation is defined in these source files:


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.