Skip to main content

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.