Macros
The procedural macros of Context-Generic Programming (CGP) cover a few kinds of work: defining a component and writing the providers that implement it, wiring a concrete type to the providers it uses and checking that wiring holds, and building the type-level values (strings, lists, paths) that the rest of the system runs on. This page groups every macro in this section by the kind of work it does, in roughly the order most CGP code uses them.
If you are new to CGP, start with the six essentials on the reference overview rather than here; this page is the fuller reference for once those six are familiar.
Defining a component, and writing its providers
#[cgp_component] is the macro every wired trait starts from: it turns one
trait into the consumer trait callers use, the provider trait implementations target, and the marker
that wiring keys against. A provider is then written with #[cgp_impl], which keeps
self, Self, and the consumer trait's own method signatures; #[cgp_provider] and
#[cgp_new_provider] are the lower-level forms underneath it, mostly met in
generated code rather than written by hand.
When a trait has exactly one implementation and needs no wiring at all,
#[cgp_fn] builds it straight from a function, and
#[blanket_trait] does the same starting from a trait with default methods and
supertrait dependencies. #[async_trait]
is how any of these traits declares an async fn without tripping the lint a bare one produces in a
public trait.
A few macros specialize #[cgp_component] for a narrower job. #[cgp_type] is for a
component that supplies a type a context chooses rather than a value it computes.
#[cgp_auto_getter] publishes a context field as a named accessor with a
blanket impl and no wiring, and #[cgp_getter] is its wireable counterpart, for the
rarer case where a context needs to choose which field a getter reads.
Others build a provider from a plain function for CGP's computation family.
#[cgp_computer] and #[cgp_producer] wire one function to
answer every member of that family at once, synchronous, async, fallible, and infallible alike, and
#[cgp_auto_dispatch] generates a handler that routes an extensible-data
input to a per-type trait's own implementations.
Wiring a type, and checking that wiring
delegate_components! is where a concrete type says which provider
answers each component, in a table that is a compile-time fact rather than a runtime lookup. Because
that wiring is lazy, check_components! forces a missing or broken
choice to fail at the table rather than wherever the trait is finally called, and
delegate_and_check_components! fuses the two for a newcomer or
a simple table, so the check cannot be forgotten. cgp_namespace! lifts a table
out of any one type and gives it a name other types can join, which is how CGP expresses reusable
presets without a separate construct for them.
Building type-level values
Symbol! turns a string literal into a type-level field-name tag,
Product! and its value-level twin product! build a type-level list for a struct's
fields or a handler pipeline's steps, Sum! builds the dual list for an enum's variants,
and Path! builds the routing list that namespaces and redirected lookups resolve
against. Struct! and Enum! write a whole struct or enum shape as the
body of its declaration, expanding to the same Product! or Sum! of named fields that
#[derive(HasFields)] generates. You write two of them by hand in ordinary code, Symbol! in a UseField wiring entry and
Product! in a handler pipeline, and the derives, the ergonomic macros above, and the open
statement inside delegate_components! generate the rest. The skill all four ask for is reading one
back out of a compiler error, since a diagnostic prints the raw list each expands to:
Symbol<…, Chars<…>>, Cons/Nil, Either/Void, or PathCons.
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.