#[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
CgpDataorCgpVariantto 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)].
Related constructs
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/Voidchain 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:
- Entry point:
derive_from_variant.rs - Codegen:
cgp_data/derive_from_variant.rs - Trait:
from_variant.rs
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.