#[derive(CgpVariant)]
#[derive(CgpVariant)] generates a structural representation, constructors, and an extractor for an enum.
Overview
In Context-Generic Programming (CGP), generic code needs traits to construct and handle
variants across different enums. A type parameter
alone does not let it name a Circle variant or match exhaustively on the concrete enum.
#[derive(CgpVariant)] supplies those traits, making the enum extensible data. It generates a
representation of the whole enum, a constructor per variant, and an extractor that handles variants
individually while tracking which remain possible. Generic code can use these operations without
naming the concrete enum.
CgpVariant accepts only enums. It produces the same output as
CgpData on an enum, but rejects a struct at parse time with
expected `enum` .
Usage
Apply CgpVariant to an enum without arguments or helper attributes:
use cgp::prelude::*;
#[derive(CgpVariant)]
pub enum Shape {
Circle(Circle),
Rectangle(Rectangle),
}
Each variant is keyed by Symbol! of its name. Generic parameters, lifetimes,
and a where clause are carried onto everything generated, including the companion enums.
Every variant needs one unnamed payload or none
Every variant must contain exactly one unnamed field or no fields at all. The constructor and
extractor implementations use the field's type as the payload type. A variant with no fields,
written Closed, Closed(), or Closed {}, has the payload Nil, so it is built from Nil and
extracted as Nil. 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 its own struct so the variant contains a single payload type:
// rejected: a struct-style variant has no single payload type
pub enum Shape {
Circle { radius: f64 },
}
// accepted: the payload is one named type
pub struct Circle {
pub radius: f64,
}
#[derive(CgpVariant)]
pub enum Shape {
Circle(Circle),
}
The payload struct can also derive CgpRecord. This lets generic code
process the payload's fields after extracting it from the enum.
HasFields accepts every variant shape and provides a structural
representation with whole-value conversions. Use it alone for an enum with mixed variant shapes;
that enum cannot derive the per-variant constructor or extractor.
What it generates
The derive combines these outputs, each also available separately:
| Group | The slice on its own |
|---|---|
| The representation — the enum as a sum of named entries, with conversions | #[derive(HasFields)] |
| The constructors — one per variant | #[derive(FromVariant)] |
| The extractor — two partial companion enums and the impls that narrow them | #[derive(ExtractField)] |
Examples
An extraction chain checks exhaustiveness through the type of its remainder. Each attempt returns either the payload or a remainder whose type rules out that variant:
use cgp::core::field::traits::{ExtractField, FinalizeExtractResult, HasExtractor};
use cgp::prelude::*;
#[derive(CgpVariant)]
pub enum Shape {
Circle(Circle),
Rectangle(Rectangle),
}
fn area(shape: Shape) -> f64 {
match shape.to_extractor().extract_field(PhantomData::<Symbol!("Circle")>) {
Ok(circle) => core::f64::consts::PI * circle.radius * circle.radius,
Err(remainder) => {
let rect = remainder
.extract_field(PhantomData::<Symbol!("Rectangle")>)
.finalize_extract_result(); // no variants left, so this cannot fail
rect.width * rect.height
}
}
}
The final extraction cannot fail because its remainder type is uninhabited: a value of that type
cannot exist. finalize_extract_result therefore
returns the payload without a wildcard arm or unreachable!(). Adding another variant makes the
function fail to compile until that variant is handled. The same operations support generic code
that cannot name the enum.
When to use it
Use CgpVariant when generic code needs an enum's representation, constructors, and extractor, and
the derive name should specify that the input is an enum. Choose a narrower operation when the full
set is unnecessary:
CgpVariant: generate the full variant output and reject non-enum inputs.CgpData: generate the same output while also accepting structs.- A plain
match: handle a closed enum with fixed operations and ordinary exhaustiveness checking. FromVariant: generate only the constructors.ExtractField: generate only the extractor.HasFields: generate only the representation and conversions. This derive also accepts mixed variant shapes.
The CgpData page explains when generic structural operations justify the additional generated code.
Under the hood
The derive generates representation traits, constructors, and an extractor for the input enum:
#[derive(CgpVariant)]
pub enum Shape {
Circle(Circle),
Rectangle(Rectangle),
}
The representation describes the enum as a sum of named variants:
impl HasFields for Shape {
type Fields = Sum![
Field<Symbol!("Circle"), Circle>,
Field<Symbol!("Rectangle"), Rectangle>,
];
}
// plus HasFieldsRef, FromFields, ToFields, ToFieldsRef
The constructor output contains an implementation per variant, as documented for
#[derive(FromVariant)]:
impl FromVariant<Symbol!("Circle")> for Shape {
type Value = Circle;
fn from_variant(_tag: PhantomData<Symbol!("Circle")>, value: Circle) -> Self {
Self::Circle(value)
}
}
The extractor output adds __PartialShape for owned extraction and __PartialRefShape for borrowed
extraction, as documented for #[derive(ExtractField)]. A
MapType marker wraps each payload: IsPresent keeps the value,
and IsVoid maps it to the uninhabited Void:
///The partial extractor for [`Shape`].
pub enum __PartialShape<__F0__: MapType, __F1__: MapType> {
Circle(<__F0__ as MapType>::Map<Circle>),
Rectangle(<__F1__ as MapType>::Map<Rectangle>),
}
impl HasExtractor for Shape {
type Extractor = __PartialShape<IsPresent, IsPresent>; // every variant still possible
// ...
}
impl FinalizeExtract for __PartialShape<IsVoid, IsVoid> { // nothing left: uninhabited
// ...
}
A ruled-out variant uses IsVoid, while an absent record field uses IsNothing. IsNothing maps a
type to the inhabited (); IsVoid maps it to the uninhabited Void. Once every variant is marked
IsVoid, the companion enum is uninhabited, so an empty match on it can return any type.
The companion names are reserved: __Partial{Name} and __PartialRef{Name}. They keep the original
type's visibility. Each generated impl is aimed at the token it came from, so a conflict with a
hand-written impl underlines that variant rather than the whole derive.
Common Mistakes
Every variant needs one unnamed payload or none. Individual variants cannot opt out.
HasFields accepts all variant shapes when only the representation and
whole-value conversions are needed.
A no_std crate needs Box in scope for a variant with no fields. The mutable extractor builds
that variant's &mut Nil with Box::leak(Box::new(Nil)), which never allocates, and finds Box
in your crate. Without it, the build fails with cannot find type `Box` in this scope on the
variant; add extern crate alloc; use alloc::boxed::Box;.
#[cgp_auto_dispatch] cannot serve an enum with a variant that has no fields. The variant's
payload is Nil, and an impl of your trait for Nil conflicts with the macro's blanket impl.
Dispatch such an enum with the dispatch combinators and a
provider instead.
The companion enums do not inherit your attributes. Deriving Debug or PartialEq on the
original enum does not implement them for the extraction remainder. Use .ok(), .is_ok(), or a
match to inspect an extraction result instead of comparing the whole result with assert_eq!.
Record and variant absence use different markers. Use IsVoid for a ruled-out variant and
IsNothing for a missing record field. An error naming the wrong marker usually means record and
variant operations have been mixed.
A variantless enum is accepted. It produces empty companion enums without field-state parameters.
CgpVariant rejects structs. Use CgpRecord or
CgpData for a struct.
Related constructs
These references cover the related derives, generated traits, and supporting types:
#[derive(CgpData)]— the umbrella, which dispatches here for an enum.#[derive(CgpRecord)]— the struct face.#[derive(HasFields)],#[derive(FromVariant)], and#[derive(ExtractField)]— the three slices this emits.ExtractField— the extractor family it generates impls for.MapType— theIsPresent/IsVoidmarkers the companions are parameterized by.CanUpcastandCanDowncast— converting between two enums whose variants overlap, built on this machinery.- Dispatch combinators — the providers that route a variant to the implementation handling it.
The ideas behind it are explained on these concept pages:
- Extensible variants — the enum half, and the extensible visitor pattern.
- Dispatching — routing an extensible-data value to a handler per variant.
Source
The implementation is defined in these source files:
- Entry point:
cgp_variant.rs - Variant codegen:
cgp_data/variant.rs - Runtime traits:
cgp-field/src/traits/
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.