Skip to main content

Type-level primitives

CGP encodes field names, positions, lists, and wiring paths as types so the compiler can resolve them through traits. Use the macros when writing these types, and recognize their expanded forms when reading diagnostics. This reference describes CGP v0.8.0.

The idea​

Type-level encodings let trait resolution distinguish keys that would otherwise be values. A getter uses a field tag, a wiring table uses a component marker, and a namespace uses a path. Strings become character-list types, positions become const-generic markers, and lists become recursive types.

Prefer Symbol!, Product!, Sum!, Path!, and the shape macros Struct! and Enum! to their nested expansions. Derives also generate these encodings. Compiler errors and plain cargo expand can expose the full types; cargo cgp expand restores recognized encodings to macro notation. The definitions below explain the nested forms that remain visible.

Assume use cgp::prelude::*; throughout, with the types this reference names imported from cgp::core::field::types and HasField from cgp::core::field::traits.

Type-level lists: Product!, Cons, Nil​

Product! represents a list as nested pairs ending in Nil. Each Cons<Head, Tail> holds an element and the rest of the list, allowing generic code to process an anonymous product type one element at a time:

pub struct Cons<Head, Tail>(pub Head, pub Tail);
pub struct Nil;

Use Product! to construct the type and lowercase product! to construct a value. Both expand to the same nested Cons structure:

type Row = Product![u32, String, bool];
// Row == Cons<u32, Cons<String, Cons<bool, Nil>>>

let row: Row = product![1, "hi".to_string(), true];
// row == Cons(1, Cons("hi".to_string(), Cons(true, Nil)))

Product lists let generic providers process struct fields without naming the concrete struct. HasFields exposes a struct's fields as a product, usually containing Field entries that pair names with values. A recursive provider handles Nil as its base case and Cons<Head, Tail> as its step. See extensible data for reading and rebuilding records this way.

Type-level sums: Sum!, Either, Void​

Sum! holds a value from one branch, while Product! holds a value for every element. It nests Either<Head, Tail> enums and terminates in the uninhabited Void type:

pub enum Either<Head, Tail> { Left(Head), Right(Tail) }
pub enum Void {}

Left(head) selects the current branch, and Right(tail) continues into the remaining branches. Sum! constructs this nested type, so the number of Right wrappers identifies a value's branch:

type Token = Sum![u32, String, bool];
// Token == Either<u32, Either<String, Either<bool, Void>>>

let t: Token = Either::Right(Either::Left("hi".to_string())); // the String branch

Void makes exhausted variant handling statically complete. An extractor marks each variant it rules out IsVoid, whose payload type is Void, so once every variant is ruled out the extractor is an uninhabited enum, eliminated with match self {}. A product instead ends in constructible Nil because an empty record is a valid value. A match on a sum by value may omit its final Void arm; behind a reference it needs Either::Right(Either::Right(void)) => match *void {} (E0004 otherwise).

HasFields exposes an enum's variants as a Sum! of Field entries. This parallels a struct's Product! representation while retaining the distinction between choosing one variant and holding all fields.

Type-level strings: Symbol!, Symbol, Chars​

Symbol!("name") turns a field name into a type suitable for a HasField<Tag> key. Equal string literals produce the same type, and different strings produce different types, so trait resolution can distinguish field names.

CGP stores symbols as character lists because stable Rust cannot use &str as a const-generic parameter. Individual char parameters are supported, so Chars stores each character and Symbol wraps the list with its UTF-8 byte length:

pub struct Chars<const CHAR: char, Tail>(pub PhantomData<Tail>);
pub struct Symbol<const LEN: usize, Chars>(pub PhantomData<Chars>);

Symbol! computes the byte length and generates the nested character list. The explicit length lets the runtime string-recovery machinery size its byte array without computing that size from the list in a const-generic expression:

// before
Symbol!("abc")
// after
Symbol<3, Chars<'a', Chars<'b', Chars<'c', Nil>>>>

The length counts UTF-8 bytes, while the list has one node per Unicode scalar value. Symbol!("δΈ–η•Œδ½ ε₯½") therefore has length 12 and four character nodes. The empty string is Symbol<0, Nil>.

A HasField bound uses the symbol to identify the field a provider needs. This explicit form shows the tag lookup that an implicit field argument normally hides:

#[cgp_impl(new GreetHello)]
impl Greeter
where
Self: HasField<Symbol!("name"), Value = String>,
{
fn greet(&self) {
println!("Hello, {}!", self.get_field(PhantomData::<Symbol!("name")>));
}
}

Formatting and recovery traits turn the symbol back into runtime text. See StaticFormat below.

Index<N>: type-level numbers​

Index<N> identifies a tuple field by position. It serves the same role as Symbol!("name") for named fields: Index<0>, Index<1>, and Index<2> are distinct tag types corresponding to .0, .1, and .2.

pub struct Index<const I: usize>;

Index stores its number only in the type and occupies zero bytes. A tuple struct can implement HasField<Index<0>> and HasField<Index<1>> separately. A lookup without a matching impl fails at compile time, such as Index<5> on a derived three-field struct. Its Display impl prints the number, so Index::<2>.to_string() returns "2".

Field: a named value​

Field<Tag, Value> pairs a value with its type-level name. A bare Product![String, u8] records types and order; Field<Symbol!("name"), String> also identifies the string as the name field. Providers can use that tag to select fields:

pub struct Field<Tag, Value> {
pub value: Value,
pub phantom: PhantomData<Tag>,
}

The phantom tag adds neither stored data nor size to Field. Its size equals that of Value, and its target type determines the tag when constructing it: let f: Field<Symbol!("name"), String> = "Alice".to_string().into();.

Field represents both record fields and enum payloads. Record tags use Symbol! or Index, and variant tags use Symbol!. For this struct, HasFields generates a product containing the named fields:

#[derive(HasFields)]
pub struct Person { pub name: String, pub age: u8 }

// generated:
// type Fields = Product![
// Field<Symbol!("name"), String>,
// Field<Symbol!("age"), u8>,
// ];

Shapes: Struct! and Enum!​

Struct! and Enum! write a HasFields shape as the body of a declaration. Each expands to exactly the Fields that #[derive(HasFields)] gives the same body, because it runs the derive's encoder:

Struct! { name: String, age: u8 }
// Product![Field<Symbol!("name"), String>, Field<Symbol!("age"), u8>]

Struct!(u64, String)
// Product![Field<Index<0>, u64>, Field<Index<1>, String>]

Enum! { Empty, Circle(f64), Rect { width: f64, height: f64 } }
// Sum![
// Field<Symbol!("Empty"), Nil>,
// Field<Symbol!("Circle"), f64>,
// Field<Symbol!("Rect"), Struct! { width: f64, height: f64 }>,
// ]

Use them wherever code names a shape: a bound such as T: HasFields<Fields = Struct! { … }>, an impl over a shape, a wiring entry, or an open key. cargo-cgp prints shapes in this form too.

Follow these rules when reading or writing a shape:

  • Delimiter: the Struct! invocation delimiter does not matter. The macro reads the form from the entries, so Struct!(a: u8) is the named form. Write braces for named fields and parentheses for a tuple body by convention.
  • Newtype rule: a body with one positional field is that field's type, so Struct!(u64) is u64. A one-element positional list has no Struct! spelling; write Product![Field<Index<0>, T>].
  • Empty bodies: Struct! {} is Nil and Enum! {} is Void. A unit variant carries Nil.
  • Types only: each macro builds a type. Build a value with product! and .into(), or with ToFields.
  • Rejected input: attributes, visibility, the _ field name, duplicate names, discriminants, and a mix of named and positional entries.
  • #[use_type]: an alias inside the body is not rewritten. Write <Self as HasErrorType>::Error there instead of the bare Error.

Path! and PathCons: type-level routes​

Path! identifies a lookup destination through a sequence of type-level segments. Namespaces and redirected wiring use these paths to address providers under prefixes. Each PathCons<Head, Tail> stores phantom markers for a segment and the remaining path, ending in Nil. Its parameters accept ?Sized types because the path does not store their values:

pub struct PathCons<Head: ?Sized, Tail: ?Sized>(pub PhantomData<Head>, pub PhantomData<Tail>);

Path! builds a path from dotted segments following @. A single identifier starting with a lowercase ASCII letter becomes a Symbol! unless it is a primitive type name; a capitalized name, a primitive, and any type with a path or generic arguments remain the type they name. Only real primitive names count, so @app.f makes f a symbol. For example:

use cgp::core::error::ErrorRaiserComponent;

type ErrorRoute = Path!(@app.error.ErrorRaiserComponent);
// PathCons<Symbol!("app"),
// PathCons<Symbol!("error"),
// PathCons<ErrorRaiserComponent, Nil>>>

The consulting table determines which provider a path resolves to. RedirectLookup takes both the table and path, so the same address can resolve differently in different contexts. Namespace entries accept the same @ syntax without an explicit Path! call. See namespaces for the lookup mechanism.

Life<'a>: a lifetime as a type​

Life<'a> represents a lifetime where CGP's wiring machinery requires a type. IsProviderFor records a component's generic parameters in a type argument, which cannot contain a bare lifetime. The macros encode a lifetime parameter as Life<'a>, producing a parameter tuple such as (Life<'a>, T):

pub struct Life<'a>(pub PhantomData<*mut &'a ()>);

The *mut phantom makes Life<'a> invariant in 'a: a mutable raw pointer is invariant in its pointee type, which contains the lifetime. This preserves the lifetime as an exact parameter of the dependency marker. The macros insert Life automatically, so it usually appears only in generated IsProviderFor bounds and in checks: a lifetime component is checked as <'a> App<'a> { ReferenceGetterComponent: (Life<'a>, Config) }. Life is neither Send nor Sync, so neither is a provider struct declared over a lifetime.

A component whose type parameter is ?Sized works at an unsized argument such as str. Its params tuple, (Life<'a>, str), is then unsized too, and both IsProviderFor and a table's forwarding impl accept it, so the component is checked as ReferenceGetterComponent: (Life<'a>, str) and called through the wiring like any other.

MRef<'a, T>: owned-or-borrowed​

MRef<'a, T> lets a getter return either a borrowed or owned value. It is an ordinary runtime enum, included here because field-access macros recognize it as a return mode:

pub enum MRef<'a, T> { Ref(&'a T), Owned(T) }

A getter can return MRef::Ref for a stored value or MRef::Owned for a computed one. Callers access either through Deref<Target = T> or AsRef<T>. The From<&'a T> and From<T> impls construct the variants; get_or_clone returns an owned value, cloning only the borrowed variant when T: Clone:

let stored = String::from("hello");
let borrowed: MRef<'_, String> = MRef::from(&stored);
let made: MRef<'_, String> = MRef::from(String::from("world"));
assert_eq!(&*borrowed, "hello");
let owned: String = borrowed.get_or_clone(); // clones the borrowed case

Field macros recognize MRef alongside return modes such as &T, Option<&T>, and &str, by shape: write it bare, since a qualified cgp::core::field::types::MRef<'_, T> falls through to the owned form and fails with E0637. See functions and getters. Its lifetime constrains an ordinary borrow and does not use the Life<'a> encoding.

StaticFormat: recovering strings and paths​

Use Display to format a symbol value, StaticString::VALUE to recover a constant string, and StaticFormat to format a type without a value. These traits and the path utility use different imports:

NameImport
StaticFormatcgp::core::base::traits
StaticStringcgp::core::field::traits
ConcatPathcgp::core::base::traits

None of these types is in the prelude. Import Cons, Nil, Either, Void, Field, Index, and Life from cgp::core::field::types when you name one. The Symbol! and Path! macros write the underlying Chars, PathCons, and Symbol types for you; import those from cgp::core::base::types when you name one.

StaticFormat writes characters into a formatter and supports the Display impls on Symbol and Chars. A symbol value can therefore use ordinary string formatting:

let s = <Symbol!("hello")>::default();
assert_eq!(s.to_string(), "hello");

StaticString::VALUE recovers a symbol as a compile-time &'static str. Its implementation UTF-8-encodes the character list into a [u8; LEN], then validates the bytes as a string. This is why Symbol records its byte length, and why a bare Chars list, lacking that length, does not implement StaticString; only Symbol and Nil (whose value is "") do. Both recovery forms preserve multibyte Unicode:

use cgp::core::field::traits::StaticString;
assert_eq!(<Symbol!("δΈ–η•Œδ½ ε₯½") as StaticString>::VALUE, "δΈ–η•Œδ½ ε₯½");

ConcatPath joins two type-level paths. It retains the first path's segments and replaces its terminating Nil with the second path. Its one use in CGP is the RedirectLookup impl every component generates, which appends the component's type parameters to the lookup path:

type Joined = <Path!(@a.b) as ConcatPath<Path!(@c.d)>>::Output; // the path @a.b.c.d

Further reference​

Consult these knowledge-base references for the complete definitions: