#[derive(CgpRecord)]
#[derive(CgpRecord)] generates field access, a structural representation, and a builder for a struct.
Overview
In Context-Generic Programming (CGP), generic code needs traits to read and assemble fields
across different structs. A type parameter alone
does not let it refer to a field such as first_name.
#[derive(CgpRecord)] supplies those traits, making the struct an extensible record. It generates
per-field access, a representation of the whole struct, and a builder that fills fields individually.
Generic code can use these operations without naming the concrete struct.
CgpRecord accepts only structs. It produces the same output as
CgpData on a struct, but rejects an enum at parse time with
expected `struct` .
Usage
Apply CgpRecord to a struct without arguments or helper attributes:
use cgp::prelude::*;
#[derive(CgpRecord)]
pub struct Person {
pub first_name: String,
pub last_name: String,
}
Every struct shape is accepted. Named fields use Symbol! tags, a
raw-identifier field such as r#type is tagged by its plain name Symbol!("type"), and tuple fields
use Index<N> tags. A fieldless struct produces a companion without
field-state parameters, so its builder() can be finalized immediately.
Generic parameters, lifetimes, and a where clause are carried onto everything generated, including
the companion type.
What it generates
The derive combines these outputs, each also available separately:
| Group | The slice on its own |
|---|---|
Per-field access — a HasField and a HasFieldMut impl per field | #[derive(HasField)] |
| The representation — the struct as a product of named entries, with conversions | #[derive(HasFields)] |
| The builder — the partial companion type and the impls that fill it | #[derive(BuildField)] |
Examples
A record builder can combine fields from another record with fields supplied individually. In this
example, build_from moves the shared fields from Person into an Employee builder:
use cgp::core::field::impls::CanBuildFrom;
use cgp::core::field::traits::{BuildField, FinalizeBuild, HasBuilder};
use cgp::prelude::*;
#[derive(CgpRecord)]
pub struct Person {
pub first_name: String,
pub last_name: String,
}
#[derive(CgpRecord)]
pub struct Employee {
pub employee_id: u64,
pub first_name: String,
pub last_name: String,
}
fn promote(person: Person, id: u64) -> Employee {
Employee::builder() // every field absent
.build_from(person) // first_name + last_name now present
.build_field(PhantomData::<Symbol!("employee_id")>, id)
.finalize_build() // all present: this is where it closes
}
build_from matches the fields by their type-level names, so neither struct needs to name the other.
It moves first_name and last_name and leaves employee_id for the caller. Removing build_field
makes the example fail to compile because
finalize_build is available only after every field is present.
See build_from for the conversion requirements.
When to use it
Use CgpRecord when generic code needs the struct's field access, representation, and builder, and
the derive name should specify that the input is a struct. Choose among the related derives according
to the operations and input restriction you need:
CgpRecord: generate the full record output and reject non-struct inputs.CgpData: generate the same output while also accepting enums.HasField: generate per-field access when fields only need to be read.HasFields: generate the representation and conversions.BuildField: generate the builder alone.
The CgpData page explains when generic structural operations justify the additional generated code.
Under the hood
The derive generates field access, representation traits, and a builder for the input struct:
#[derive(CgpRecord)]
pub struct Person {
pub first_name: String,
pub last_name: String,
}
The field-access output contains a HasField and a
HasFieldMut implementation per field. It matches the output
of #[derive(HasField)].
The representation output describes the struct as a product of named entries and supplies conversions
in both directions. It matches #[derive(HasFields)]:
impl HasFields for Person {
type Fields = Product![
Field<Symbol!("first_name"), String>,
Field<Symbol!("last_name"), String>,
];
}
// plus HasFieldsRef, FromFields, ToFields, ToFieldsRef
The builder output adds a companion type, as documented for
#[derive(BuildField)]. Each field's type is wrapped in a
MapType marker: IsPresent stores its value, and IsNothing
stores ():
///The partial builder for [`Person`].
pub struct __PartialPerson<__F0__: MapType, __F1__: MapType> {
pub first_name: <__F0__ as MapType>::Map<String>,
pub last_name: <__F1__ as MapType>::Map<String>,
}
impl HasBuilder for Person {
type Builder = __PartialPerson<IsNothing, IsNothing>; // the empty builder
// ...
}
impl FinalizeBuild for __PartialPerson<IsPresent, IsPresent> {
// ... only at all-present
}
The builder's type prevents incomplete construction. builder() starts with every field absent,
build_field changes one marker to IsPresent, and
finalize_build applies only when every field is present.
Per-field UpdateField implementations change the markers, and
HasField implementations on the companion allow reads of fields that have been set.
The companion is named __Partial{Name} and keeps the original type's visibility, so a pub struct
yields a pub companion. Each generated impl is aimed at the token it came from (a per-field impl at
its field, a whole-type impl at the type name), so a conflict with a hand-written impl underlines that
token rather than the whole derive.
Common Mistakes
The companion type does not inherit your attributes. A #[derive(Debug, Clone)] on the record
does not apply to __Partial{Name}, so it does not make partial values printable or cloneable. Read a
set field through the companion's HasField implementation.
A tuple struct's builder is keyed by position. Its companion exposes UpdateField<Index<0>, _>
rather than symbol-keyed impls, so build_field takes PhantomData::<Index<0>>.
A single-field tuple struct's representation is the inner type directly, not a one-element product.
This is the newtype special case described on the #[derive(HasFields)] page,
which this derive inherits.
A fieldless struct has an immediately finalizable builder. Its companion does not need field-state parameters.
CgpRecord rejects enums. Use CgpVariant or
CgpData for an enum.
The full record derive adds compilation work. It generates a companion type, whole-type implementations, and per-field implementations. Use an individual derive when only part of the output is needed.
Related constructs
These references cover the related derives, generated traits, and supporting types:
#[derive(CgpData)]— the umbrella, which dispatches here for a struct.#[derive(CgpVariant)]— the enum face.#[derive(HasField)],#[derive(HasFields)], and#[derive(BuildField)]— the three slices this emits.HasBuilder— the builder family it generates impls for.MapType— theIsPresent/IsNothingmarkers the companion is parameterized by.CanBuildFrom— merging one record into another's builder.
The ideas behind it are explained on these concept pages:
- Extensible records — a struct as a product of named fields, and the extensible builder pattern.
Source
The implementation is defined in these source files:
- Entry point:
cgp_record.rs - Record codegen:
cgp_data/record.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.