Skip to main content

#[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:

GroupThe 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.

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

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:


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.