#[derive(HasFields)]
#[derive(HasFields)] generates a structural representation and conversions for a struct or enum.
Overview
In Context-Generic Programming (CGP), generic serializers, validators, record conversions, and enum dispatchers need a description of the whole type. Individual field access does not tell them which fields or variants exist or how to traverse them.
#[derive(HasFields)] describes that structure through a single associated type, Fields.
HasField supplies access to one field selected by a tag; HasFields
describes all fields together, for example:
type Fields = Product![
Field<Symbol!("name"), String>,
Field<Symbol!("age"), u8>,
];
A struct's representation combines its fields in a Product!, with a
Field entry pairing each value type with its tag. An enum uses a
Sum! to represent a choice of variants. Generic code can recurse over these
representations, whose types are resolved during compilation.
The derive also supplies conversions to and from the representation. Generic code can decompose a concrete value, process its structural form, and reconstruct the concrete type.
Usage
Apply HasFields to a struct or enum without arguments or helper attributes:
#[derive(HasFields)]
pub struct Person {
pub name: String,
pub age: u8,
}
#[derive(HasFields)]
pub enum Shape {
Circle(Circle),
Rectangle(Rectangle),
}
For a struct the shape is a product; for an enum it is a sum. Naming follows the same rules everywhere: a
named field or a variant is keyed by Symbol!, a positional field by
Index<N>. Applying the derive to anything other than a struct or an enum, such
as a union, fails with expect body to be either a struct or enum.
Struct shapes
Every struct shape is accepted, with its representation determined by its fields:
- Named fields: a product of
Field<Symbol!("name"), T>entries in declaration order. - Multiple tuple fields: a product with fields keyed by
Index<N>. - Unit struct: the empty product
Nil, with conversions to and from the unit value. - Single tuple field (newtype): the inner type directly, without a one-element product wrapper.
Adding a second field to a newtype changes the kind of representation. struct Wrapper(String) has
Fields = String; a tuple struct with multiple fields has a product of indexed entries. Generic code
that depends on the original representation must account for that change.
Variant shapes
HasFields accepts unit, newtype, multi-field tuple, and named-field variants. Its representation
applies the struct field rules within each variant. In contrast, the per-variant constructor and
extractor derives (FromVariant and
ExtractField, also included by CgpData)
require one unnamed payload or no fields per variant, and give a variant with no fields the same
Nil payload this derive does.
#[derive(HasFields)]
pub enum Shape {
Empty,
Circle(u32),
Rectangle(u32, u32),
Triangle { base: u32, height: u32 },
}
The variants above map to these entries in the sum:
| Variant | Its entry in the sum |
|---|---|
Empty | Field<Symbol!("Empty"), Nil> |
Circle(u32) | Field<Symbol!("Circle"), u32> |
Rectangle(u32, u32) | Field<Symbol!("Rectangle"), Product![Field<Index<0>, u32>, Field<Index<1>, u32>]> |
Triangle { base, height } | Field<Symbol!("Triangle"), Product![Field<Symbol!("base"), u32>, Field<Symbol!("height"), u32>]> |
Every listed shape supports conversion to and from the representation. A unit variant uses Nil, a
newtype variant uses its payload type directly, and multi-field variants use products keyed by
position or name.
An enum with mixed variant shapes can derive HasFields but cannot derive CgpData. It gains a
structural representation and whole-value conversions without per-variant constructors or an
incremental extractor.
Generic types
Generic parameters, lifetimes, and a where clause are carried onto every generated impl. A borrowed
field type appears verbatim in the shape, and the borrowed view of the shape layers its own borrow on top
of it: a field of type &'a Name appears as &'__a &'a Name in the borrowed form, where '__a is the
reserved lifetime the derive introduces.
Examples
Deriving HasFields alongside HasField is the common pairing, giving one
struct both indexed and structural access:
use cgp::prelude::*;
#[derive(HasField, HasFields)]
pub struct Config {
pub host: String,
pub port: u16,
}
Config::Fields is now Product![Field<Symbol!("host"), String>, Field<Symbol!("port"), u16>].
Code that needs to name that type can write it as the struct body instead, with
Struct!: Struct! { host: String, port: u16 } is the same type. A value
round-trips through it:
let config = Config { host: "localhost".to_owned(), port: 8080 };
let fields = config.to_fields(); // Config -> the product
let config_again = Config::from_fields(fields); // the product -> Config
to_fields_ref() borrows the fields so generic code can read them without consuming the value:
let config = Config { host: "localhost".to_owned(), port: 8080 };
let fields_ref = config.to_fields_ref(); // borrows each field in place
An enum's shape is a sum rather than a product, and the same conversions apply:
#[derive(HasFields)]
pub enum Shape {
Circle(Circle),
Rectangle(Rectangle),
}
Shape::Fields is Sum![Field<Symbol!("Circle"), Circle>, Field<Symbol!("Rectangle"), Rectangle>],
which Enum! writes as Enum! { Circle(Circle), Rectangle(Rectangle) }.
Generic code can operate on Self::Fields under a Self: HasFields bound. An implementation that
supports the resulting representation can work with Config, Person, or a struct in another crate
that supplies the same traits.
When to use it
Use HasFields when code must process a type's whole structure. Use
HasField for access to an individual field. Derive both when both forms of
access are needed.
Choose the extent of the generated support according to the operations you need:
HasFieldsalone: describe and convert a type for serialization, structural reads, or dispatch. This also supports enums with mixed variant shapes.CgpData: include incremental building or extraction alongside the representation. For structs, it also includes per-field access.HasFieldalone: read individual fields when the whole representation is unnecessary.HasFieldsgenerates five implementations, so omit it when nothing uses them.
The representation is a type-level description, not runtime reflection. Generic code uses trait bounds to access the shape during compilation; it does not query field metadata at runtime. A type must supply the representation traits before it can participate. If you cannot implement those traits for a type, this derive cannot expose its shape.
Under the hood
The derive preserves the type definition and adds implementations of HasFields, HasFieldsRef,
ToFields, FromFields, and ToFieldsRef. For this named-field struct:
#[derive(HasFields)]
pub struct Person {
pub name: String,
pub age: u8,
}
The shape implementations name the product and its borrowed counterpart:
impl HasFields for Person {
type Fields = Product![
Field<Symbol!("name"), String>,
Field<Symbol!("age"), u8>,
];
}
impl HasFieldsRef for Person {
type FieldsRef<'__a> = Product![
Field<Symbol!("name"), &'__a String>,
Field<Symbol!("age"), &'__a u8>,
]
where
Self: '__a;
}
The conversion implementations move or borrow values between Person and that product:
impl ToFields for Person {
fn to_fields(self) -> <Self as HasFields>::Fields {
Cons(self.name.into(), Cons(self.age.into(), Nil))
}
}
impl FromFields for Person {
fn from_fields(Cons(name, Cons(age, Nil)): <Self as HasFields>::Fields) -> Self {
Self { name: name.value, age: age.value }
}
}
impl ToFieldsRef for Person {
fn to_fields_ref<'__a>(&'__a self) -> <Self as HasFieldsRef>::FieldsRef<'__a>
where
Self: '__a,
{
Cons((&self.name).into(), Cons((&self.age).into(), Nil))
}
}
Product![A, B] is sugar for Cons<A, Cons<B, Nil>>, which is why the bodies build a Cons chain. The
type-level lists page covers that shape, and it is the form printed in
an error.
An enum's sum representation is an Either chain terminated by Void.
Each arm carries a field tagged by the variant name:
impl HasFields for Shape {
type Fields = Either<
Field<Symbol!("Circle"), Circle>,
Either<Field<Symbol!("Rectangle"), Rectangle>, Void>,
>;
}
The enum conversions map each variant to its corresponding sum arm and back. Each variant's payload
representation follows the struct rules: Nil for a unit variant, the payload itself for a newtype
variant, or a product keyed by Index or Symbol! for multiple fields.
A unit struct uses the empty product Nil as its representation:
impl HasFields for Unit {
type Fields = Nil;
}
A variantless enum uses Void as its representation. Its conversions use empty matches because the
value is uninhabited.
Each generated impl is aimed at the type name the user wrote, so a conflict with a hand-written
HasFields impl underlines the struct or enum rather than the whole #[derive(HasFields)].
Common Mistakes
A newtype's Fields is the inner type, not a one-element product. struct Wrapper(String) has
Fields = String. Generic code written against Cons<Field<Index<0>, _>, Nil> will not match it, and
adding a second field changes the shape rather than lengthening it.
Named-field and newtype variants have different representations. Circle { radius: f64 } uses a
one-entry product, while Circle(Circle) uses its payload type directly.
Only HasFields accepts every variant shape in this family. Multi-field and struct-style variants
with fields are rejected by CgpData, CgpVariant, ExtractField, and FromVariant. Wrap richer
payloads in dedicated structs to use those derives.
The borrowed shape adds a reference to each field's declared type. A field of type &'a Name
appears as &'__a &'a Name in the borrowed form. The derive introduces the reserved lifetime '__a
for that additional borrow.
Field order is declaration order, and it is part of the type. Two structs with the same field names in
different orders have different Fields types. Structural conversions that match on names cope with that;
code written against a literal Cons chain does not.
HasField and HasFields generate different interfaces. The singular derive provides per-field
access for structs. The plural derive provides a whole-type representation for structs and enums.
Related constructs
These references cover the related derives, generated traits, and supporting types:
#[derive(HasField)]— the singular counterpart, per-field access, commonly derived alongside this one.HasFields— the traits this generates and the conversions between a value and its shape.#[derive(CgpData)]— the umbrella derive, which includes this one plus the incremental machinery.Product!andSum!— the list types a struct and an enum shape are built from.Struct!andEnum!— write the shape this derive generates as the body of a struct or enum declaration, for code that names it.Field— one entry: a value paired with its type-level name.Symbol!andIndex— the tags that name an entry.- Type-level lists — the
Cons/NilandEither/Voidchains the sugar expands to. AppendProduct— operations over a shape once you have one.CanUpcast— converting between two types whose shapes overlap.
The ideas behind it are explained on these concept pages:
- Extensible records — a struct as a product of named fields, and what generic code does with one.
- Extensible variants — the enum half, and the expression problem it addresses.
Source
The implementation is defined in these source files:
- Entry point:
derive_has_fields.rs - Codegen:
cgp_data/derive_has_fields/ - Traits:
has_fields.rs,to_fields.rs, andfrom_fields.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.