Enum!
The type-level shape of an enum, written as the body of an enum declaration.
Overview
In Context-Generic Programming (CGP), generic code over enums works on an enum's
shape: one type that lists every variant by name,
which #[derive(HasFields)] generates for an enum as its Fields
type. Written out by hand, that shape is a Sum! of Field
entries that repeats each variant name as a
type-level string:
Sum![Field<Symbol!("Circle"), f64>, Field<Symbol!("Square"), f64>]
Enum! writes the same type as the enum body it describes:
Enum! { Circle(f64), Square(f64) }
The two are the identical type, and it is exactly the Fields the derive gives an enum with that
body. Reach for Enum! wherever code names a variant set's shape rather than deriving it, such as
a trait bound on FromFields. It is also the
form cargo cgp check and cargo cgp expand
print a variant list in, so a list read in the tool's output can be copied back into code.
Usage
The body is the inside of an enum declaration, and each variant takes one of the three Rust variant shapes:
Enum! {
Empty, // a unit variant
Circle(f64), // positional fields
Rectangle { width: f64, height: f64 }, // named fields
}
Inside the body, a variant's brackets keep their Rust meaning: parentheses hold positional fields,
and braces hold named fields. The brackets around the whole Enum! invocation do not matter. A
variant name may be a raw identifier, tagged without the r#, and the list accepts a trailing comma.
An empty body, Enum! {}, is allowed.
Each variant carries its fields as one payload, and two cases matter when you build a value. A
variant with exactly one positional field carries that field's type directly, so Circle(f64)
carries an f64, and a unit variant carries Nil, the empty list. Every other variant,
including one with a single named field, carries a list, as a Struct! body
would. Under the hood lists every case.
Enum! builds a type, never a value. A value of the shape selects its variant with Either::Left
and Either::Right, wrapping the payload with Field::from, or comes from an existing enum through
to_fields().
Examples
A function bounded on an enum's shape converts a value built in that shape into the enum. Here
Value derives the whole variant family, and from_shape works for any enum with the same variants:
use cgp::core::field::traits::FromFields;
use cgp::core::field::types::{Either, Field};
use cgp::prelude::*;
#[derive(Debug, PartialEq, CgpData)]
pub enum Value {
Int(u64),
Text(String),
}
pub fn from_shape<T>(fields: Enum! { Int(u64), Text(String) }) -> T
where
T: FromFields<Fields = Enum! { Int(u64), Text(String) }>,
{
T::from_fields(fields)
}
assert_eq!(from_shape::<Value>(Either::Left(Field::from(7))), Value::Int(7));
assert_eq!(
from_shape::<Value>(Either::Right(Either::Left(Field::from("seven".to_owned())))),
Value::Text("seven".to_owned()),
);
Either::Left selects the first variant and each Either::Right moves one variant further, and the
variant's name comes from the Enum! type the argument is expected to have.
When to use it
Write Enum! whenever you would otherwise spell a variant list by hand. A
Sum![Field<Symbol!("Int"), u64>, …] written out is longer and hides the fact that it describes an
enum.
- Let
#[derive(HasFields)]or#[derive(CgpData)]produce an enum's shape, and useEnum!only where code has to name one. Restating an enum you own as anEnum!next to it is a second copy that can drift. - Use
Struct!for a record's shape, where every field is present at once. - Use
Sum!for a choice among types that are not named variants. - Use a plain
enumandmatchwhen the variant set is closed and consumed in one place. A shape is worth naming when independent code handles variants it did not define.
Under the hood
Enum! expands exactly as #[derive(HasFields)] expands the same body, because the macro runs the
derive's own code. Each variant becomes a Field entry keyed by its name, and the entries are chained
into a sum that ends in Void:
// before
Enum! { Circle(f64), Square(f64) }
// after
Either<Field<Symbol!("Circle"), f64>, Either<Field<Symbol!("Square"), f64>, Void>>
A variant's payload is its fields, encoded by the Struct! rules:
| Variant | Payload |
|---|---|
Empty, Empty(), or Empty {} | Nil |
Circle(f64) | f64, the bare type |
Pair(u32, u32) | Struct!(u32, u32), a list keyed by position |
Rect { width: f64, height: f64 } | Struct! { width: f64, height: f64 }, a list keyed by name |
So several spellings are the same type: V, V(), V {}, and V(Nil) are one variant, and
V { a: u32 } is V(Struct! { a: u32 }). cargo cgp relies on this when it prints a variant list,
choosing the shortest spelling. An empty body is Void, the shape of an enum with no variants.
Formal grammar
The body is a list of variants, each a name with an optional field list, in the Rust Reference's notation:
EnumInput -> ( Variant ( `,` Variant )* `,`? )?
Variant -> IDENTIFIER ( `(` TupleFields `)` | `{` NamedFields `}` )?
IDENTIFIER includes raw identifiers. TupleFields and NamedFields are the
Struct! productions, so a variant's fields follow the rules of a
Struct! body of the same form.
Common Mistakes
The variant derives need each variant to hold one positional field or none. Enum! describes
any variant, as #[derive(HasFields)] does, and
#[derive(CgpData)], CgpVariant, ExtractField, and
FromVariant accept a unit variant with the same Nil payload, but reject a multi-field or
named-field variant. A shape with such variants therefore has no generic constructor or extractor.
An enum body's other parts are rejected. An attribute on a variant (such as #[default] or a doc
comment), pub on a variant, a discriminant such as = 1, and a variant name given twice each fail
with their own error. A variant's fields are checked as a Struct! body's are, with the same
messages, so an attribute, visibility, a field named _, a field name given twice, a keyword field
name without its r#, and a value where a type belongs are each rejected inside a variant too.
A variant's brackets decide its form, and a field that contradicts them is rejected. A bare
type inside braces, as in V { u8 }, and a name: Type entry inside parentheses, as in
V(a: u8), each fail with a message saying which form the brackets require. This differs from the
brackets around the whole Enum! invocation, which do not matter.
A list whose tags are not identifiers has no Enum! spelling. A variant needs a name that is a
Rust identifier, so a sum whose entries are keyed by Index<N>, or by a type-level string that is
not an identifier, is written with Sum!.
Clippy's type_complexity lint, and an imported abstract type inside the body, behave as they do
for Struct!.
Related constructs
Struct!— the struct counterpart, whose rules encode each variant's payload.Sum!— the sumEnum!expands to.FieldandSymbol!— the entry and the tag each variant becomes.HasFields— the trait whoseFieldsanEnum!names.#[derive(HasFields)]— the derive whose encodingEnum!runs.FromVariantandExtractField— constructing and taking apart a variant generically.
The ideas behind it:
- Extensible variants — the variant representation a shape describes.
Source
- Entry point:
enum_type.rs - Parsing the body:
types/shape/enum_type.rs - The encoding shared with the derive:
derive_has_fields/sum.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.