Context-Generic Programming (CGP) in Rust
First, check the project's CGP version. Before you write, change, or debug CGP code in a
project, read the cgp entry in its Cargo.lock, or its Cargo.toml without one, and compare it
with the releases in Versions and keeping this skill current.
If it differs from the newest release described there, load versions,
follow the case that matches, and open your answer by telling the user what you found. Do this even
when the task does not mention versions.
CGP lets Rust contexts choose among interchangeable trait implementations through wiring. It works around coherence restrictions by separating the trait callers use from the trait providers implement. This primer introduces the vocabulary, core constructs, and macro expansions needed to read CGP code.
Load the relevant sub-skill before writing, modifying, reviewing, or debugging any construct it
covers. The primer introduces each construct; the references/ sub-skills supply its exact grammar,
full expansion, corner cases, and worked examples. For example,
components explains how #[cgp_impl] rewrites self, and
macro-grammar specifies which attribute forms parse. Use the
sub-skill index to find the references your task
requires.
CGP's procedural macros expand to ordinary Rust traits and impls. Understanding those expansions helps explain how the constructs work and why their errors occur. This primer includes expansions where they help establish that connection.
Tooling: use cargo-cgp for readable errors and expansionsβ
Use cargo-cgp when it is available to diagnose CGP compile errors. Its check command replaces
cargo check for diagnosis and rewrites CGP errors into a compact summary that leads with the root
cause. Each rewritten message retains rustc's error code, adds a [CGP-Exxx] tag, and shows the
dependency chain. Its expand command displays
the generated code. Recommend cargo-cgp for checking CGP code, and prefer it when diagnosing a
wiring failure.
Check availability with cargo cgp --version or cargo cgp check in a CGP project. If the
subcommand is missing, recommend installing it for clearer errors. Install it on the user's behalf
only with their approval: setup provisions a nightly toolchain and builds a compiler-linked driver.
Prefer installation through cargo on most machines. Run cargo install --locked cargo-cgp, then
cargo cgp setup. Installation builds the small front-end with the existing toolchain, which must
be Rust 1.96 or newer; setup uses rustup to provision the pinned nightly and build its matching
driver.
Use Nix only when the host has a nix command on PATH, the project has a flake.nix, or the user
requests it. Otherwise, omit Nix from the recommendation. When Nix is present and cargo-cgp is
absent, prefer running it from the project directory without installing it:
nix run github:contextgeneric/cargo-cgp/v0.1.0 -- check. Arguments after -- go to
cargo check. To install into a Nix profile, use
nix profile install github:contextgeneric/cargo-cgp/v0.1.0.
The pinned nightly applies only to cargo-cgp's own check, so the project retains its toolchain.
cargo cgp setup installs that nightly, or the Nix flake builds it. See the
installation instructions
for details.
Run cargo cgp check wherever you would run cargo check. Arguments after check are forwarded,
as in cargo cgp check --workspace. The
error-code catalog
explains the [CGP-Exxx] tags.
Rerun a check that hangs, or whose errors change between runs, on one thread:
RUSTFLAGS="-Zunstable-options --jobs-frontend=1" cargo cgp check
The pinned nightly type-checks on several threads, and the tool is meant to print the same output
under any thread count. So a difference that disappears on one thread is a bug, which the user can
report; the one expected exception is a cycle error (E0391), whose text can start from a
different item on each run. Set the flags in that command alone, never in the project's
.cargo/config.toml, which would pass them to its stable builds, and stable Rust rejects -Z
flags. The
troubleshooting page
explains how to tell a compiler bug from a cargo-cgp one.
Reading what a macro generated: cargo cgp expandβ
Read the macro expansion when a diagnostic leaves the generated impls unclear. cargo cgp expand
prints the expanded crate with CGP's type-level constructs restored to readable macro notation.
For example, it displays a field tag as Symbol!("width"), a pipeline as
Product![StepOne, StepTwo], a derived field list as Struct! { width: f64 }, and a namespace key
as Path!(@app.GreeterComponent).
Use expansion to investigate these questions:
- Generated types: Find the impl behind an unfamiliar
IsProviderFor<β¦>,PathCons<β¦>, or__Context__in a diagnostic. - Wiring entries: Inspect the actual
DelegateComponentkeys andDelegatevalues produced by a table that does not resolve. - Generated bounds: Check a provider's
whereclauses or a getter's field requirements. - Different syntax forms: Expand and compare forms when only one compiles to locate the difference responsible for the failure.
Run it on one target, narrowed to what you care about:
cargo cgp expand --lib # the whole library target
cargo cgp expand --lib --item contexts::MockApp # one module, type, or trait
Target selection is required when a package has several targets. Pass --lib or --bin NAME,
or cargo declines with "extra arguments to rustc can only be passed to one target". Other arguments
(-p, --features) forward to cargo rustc. The expansion goes to stdout, so redirect it to a file
when it is long and read that instead of flooding your context.
--item <path> makes the output manageable. The path is ::-separated, may carry a leading
crate::, and names something inside the crate being expanded. What it names decides what you get:
- a module gives its contents (
--item contexts); - a type gives its declaration and every impl written for it. For a context struct that means
the
HasField/HasFieldMutimpls the derive generated, and itsDelegateComponentwiring entries with the real key and provider types (--item Rectangle); - a trait gives its definition and every impl of it, which is usually the rule you want. Naming
a component's provider trait (
--item AreaCalculator) gives the provider trait, the delegation blanket impl, theUseContextandRedirectLookupimpls, and each wired provider's impl. Naming the consumer trait (--item CanCalculateArea) gives just the consumer trait and its routing blanket.
Use cargo cgp check to verify wiring. expand stops after macro expansion, so it can succeed
on a crate that fails type checking. That makes it useful while debugging, but its success does not
verify the generated impls.
Read the expansion as diagnostic output. It is not intended for compilation: the tool strips the
cgp::macro_prelude:: qualifier, and an open statement's per-key entry retains its raw
PathCons<β¦> key.
Scope: cargo-cgp is optional and adds only check and expand. It does not provide
cargo cgp build, run, or test, so build, run, and test the project with plain cargo. CGP itself
compiles on any stable Rust β₯ 1.89, so plain cargo check works on a CGP project too. Reach for
cargo cgp check when you hit or expect a wiring error and want it made readable.
cargo-cgp can also be Rust Analyzer's on-save check backend, via
rust-analyzer.check.overrideCommand set to
["cargo","cgp","check","--workspace","--all-targets","--message-format=json"]. But never modify
the user's Rust Analyzer settings implicitly. Mention this option and let them opt in. Edit their
editor configuration only when they ask you to, and then put the setting in the project's workspace
settings (.vscode/settings.json in VS Code) rather than their user settings, so the tool runs only on
CGP projects. The override replaces Rust Analyzer's own check options, so write any --features flag
into the array. The
editor integration page covers the
setup and its failure messages.
When cargo-cgp is not available, or leaves an error unrewritten (a block with no [CGP- code),
read the raw compiler output by hand. Only then load the error-extraction sub-skill, the
technique for reducing a raw CGP cascade to its root cause. When cargo-cgp has reshaped the error,
its [CGP-Exxx] headline states the cause, and its root cause: note and tree give the chain, so
read the headline first. That is the compact summary the sub-skill would produce, so you do not need
it.
Versions and keeping this skill currentβ
This skill supports cgp v0.8.0 and later, and does not support an older cgp. The newest
releases it describes are cgp v0.8.0 and cargo-cgp v0.1.0. Read the project's cgp
version from Cargo.lock, or Cargo.toml without one, and the tool's from cargo cgp --version,
then act on the case that matches:
- Older than v0.8.0: tell the user the skill does not support it, and read the CGP source at that version and the knowledge base instead of trusting the skill's syntax.
- Older than the newest release described: tell the user once that
cgphas a newer release, naming it, and write code for the project's version. - Newer than the newest release described, or an unreleased
cgpsuch as a Git dependency: fetchhttps://raw.githubusercontent.com/contextgeneric/cgp-skills/main/cgp/references/versions.mdand read its version table. Ifmain's table describes the project's version, this installed copy is behindmain: tell the user a newer skill is available and give the update command for their install route, which versions lists. A match onmainnever means this copy is current, since this copy's own table, above, is the one the project outgrew. Otherwise tell the user the skill has not caught up yet, and trust the code. If the fetch fails, say the check could not run.
Versions holds the details of each case. Change the project, the tool, or this skill only with the user's approval.
The problem CGP solvesβ
CGP lets contexts select different implementations of the same interface despite Rust's coherence restrictions. Rust permits at most one implementation of a trait for a given type, and its orphan rule forbids implementing a foreign trait for a foreign type. Those rules limit interchangeable implementations and downstream choices for types a crate does not own.
CGP separates the caller's interface from the provider's implementation to allow those choices.
A provider trait uses a marker type owned by the implementing crate as Self. A concrete context
then selects that provider through a type-level table. The choice belongs to the context, so
different contexts can select different implementations of the same interface.
Blanket traits and impl-side dependenciesβ
An impl-side dependency is a constraint required by an implementation but absent from its trait
interface. CGP uses these dependencies for dependency injection. The technique starts with ordinary
blanket trait implementations, also called extension traits. Here, the CanGreet implementation
requires HasName, while the trait itself does not:
pub trait CanGreet {
fn greet(&self);
}
pub trait HasName {
fn name(&self) -> &str;
}
impl<Context> CanGreet for Context
where
Context: HasName,
{
fn greet(&self) {
println!("Hello, {}!", self.name());
}
}
CanGreet hides its HasName dependency inside the blanket impl, so a caller that is itself
generic does not have to forward HasName the way it would with a free generic function. In CGP
you typically start by writing generic logic as a blanket trait like this, and promote it to a
full CGP component only when you need more than one implementation. Blanket traits are not
themselves CGP components, but the technique recurs throughout CGP.
The core vocabularyβ
CGP separates the interface callers use from the implementation a context selects. The following terms describe those roles:
- Consumer trait: The ordinary
self-style trait callers use, such asCanGreetorCanCalculateArea. Its name describes an action (CanDoX). - Provider trait: The interface generated by
#[cgp_component], withSelfmoved to an explicitContextparameter, as inGreeter<Context>. Its name is a noun such asSomethingDoer, or uses theProvidersuffix when a noun does not fit. - Provider: A zero-sized marker struct, such as
GreetHello, that implements a provider trait. It exists as a type-level name and is never instantiated. - Wiring: A type-level table that selects a provider for each component on a context.
- Impl-side dependency: A provider's
where-clause constraint that the consumer trait does not expose. - Component: The generated bundle of consumer trait, provider trait, and
β¦Componentmarker used as the wiring key.
Callers use consumer traits, and providers implement provider traits. Generated blanket impls
connect them: wiring a context to a provider makes the context implement the consumer trait.
A provider method's context: &Context serves the same role as the consumer method's &self.
Do not call any of these a capability. What a component, a #[cgp_fn] function, or a getter
defines is a trait; the thing a caller invokes is a method or an operation; what #[uses]
imports is a trait dependency; and a #[cgp_fn] or #[blanket_trait] trait that is not a
component is a blanket trait. The word "capability" names a different construct in the
object-capability model and in Rust's context-and-capabilities proposal, so using it for CGP's
own constructs misleads readers who know either. Use it only when describing those other systems.
A context can hold the data being operated on or implement the traits an operation needs.
A value context is the data, such as String in String: CanEncode or Rectangle in
Rectangle: CanCalculateArea. An environmental context carries the wiring choices and implements
the traits an application, test harness, or service relies on. Environmental contexts are more common
in CGP code and
may be fieldless: struct App; can exist solely to carry wiring. Both kinds occupy the Self
position and carry a wiring table, so their signatures do not distinguish them.
A component's target determines what its methods operate on. A self-targeted component acts on
Self, as in CanGreet, HasErrorType, and getters. A parameter-targeted component acts on a type
parameter while Self selects the implementation, as in CanEncodeValue<Value> or
CanCalculateArea<Shape>. A parameter can also select wiring: in CanCompute<Code, Input>,
Input is the target and Code is a selector.
The context and target together determine how many independent provider choices are available. A self-targeted component wired on a foreign value type has one provider program-wide; authors can define additional environmental contexts to make independent choices. Consult modularity-hierarchy when choosing an arrangement. When explaining CGP, identify the arrangement in the example because a change from value context to environmental context may leave the signature unchanged.
Inside a provider, self and Self in #[cgp_impl] refer to the context. The raw provider-trait
form names them context and Context. The provider struct is only a type-level name, so it cannot
store state or supply fields at runtime.
Reading CGP code on sightβ
Most CGP code is readable once you recognize a handful of shapes:
#[cgp_component(Greeter)] trait CanGreet { fn greet(&self); }defines a component.CanGreetis the consumer trait you call,Greeter<Context>is the provider trait implementations target, andGreeterComponentis the wiring key.#[cgp_impl(new GreetHello)] #[uses(HasName)] impl Greeter { fn greet(&self) { β¦ } }writes a provider namedGreetHellofor theGreetercomponent. Inside,self/Selfmean the context, and#[uses]lists the impl-side dependencies. It desugars towhere Self: HasName, the form you read in older code.#[cgp_fn] fn rectangle_area(&self, #[implicit] width: f64, #[implicit] height: f64) -> f64 { β¦ }defines a trait with a single blanket implementation, pullingwidth/heightfrom the context's fields automatically.delegate_components! { Person { GreeterComponent: GreetHello } }wires thePersoncontext. It says "for theGreetercomponent,Personuses theGreetHelloprovider." After this,PersonimplementsCanGreet.check_components! { Person { GreeterComponent } }is a compile-time assertion that the wiring is complete and all transitive dependencies are satisfied.
A consumer trait can also be implemented directly on a context like any normal Rust trait
(impl CanGreet for Person { β¦ }). CGP traits are a superset of vanilla traits, and the macros
only save boilerplate.
Choosing a constructβ
Prefer the modern forms in this table when writing CGP. Explicit forms remain useful for reading generated code and legacy implementations, and some advanced cases still require them. See Writing providers for exceptions and modern-idioms for complete before-and-after examples.
| To⦠| Prefer | Not (legacy / advanced / read-only) |
|---|---|---|
| write a provider | #[cgp_impl], header impl Trait (omit for Context) | raw #[cgp_provider] / #[cgp_new_provider] |
| read a field from your own context | an #[implicit] argument | #[cgp_auto_getter] / any getter trait declared just to read it |
| declare a getter (field on another type, or a named accessor other code requires) | #[cgp_auto_getter], used sparingly | #[cgp_getter] (only for per-context field choice) |
| require a trait on the context | #[uses(Trait)] | where Self: Trait |
| require an inner provider | #[use_provider(P: Trait)] | where P: Trait<Self> |
name an abstract type (e.g. Error) | #[use_type(Trait.Type)] + the bare alias | : Trait supertrait + Self::Type |
pass several args to #[uses] / #[use_type] | one attribute, comma-separated | repeating the same attribute |
bind several inner providers with #[use_provider] | one attribute per provider | a comma-separated list of pairs (it does not parse) |
| add a supertrait that contributes methods | #[extend(Trait)] | native pub trait β¦: Supertrait |
| dispatch a component per type, on any of its parameters | the open statement (or a namespace), one path segment per parameter | #[derive_delegate] + UseDelegate<new β¦> or UseInputDelegate<new β¦> tables |
| verify a context is fully wired | separate check_components! (or delegate_and_check_components! for a basic starter context) | leaving a context's wiring unchecked |
| build a field/list/string/path type | Symbol! / Product! / Sum! / Path! sugar | hand-written Cons/Nil/Chars/Either/PathCons |
| name a struct or enum shape | Struct! { a: A } / Struct!(A, B) / Enum! { V(A) } | Product![Field<Symbol!("a"), A>] and the like |
Some names are gone entirely, not merely dated. Never write #[cgp_context], which was removed
(assemble a context with delegate_components! and the derives instead), or ProvideType, which
was renamed to TypeProvider. One caveat carries across the whole table: a construct's own local
associated type stays qualified as Self::Output. Only an imported abstract type is written bare
via #[use_type].
The prelude and versionβ
The names CGP code writes come through one import, which belongs at the top of every module that uses CGP:
use cgp::prelude::*;
Import traits and markers outside the prelude from their defining modules. Missing imports can prevent otherwise valid CGP code from compiling. These modules contain names that commonly need explicit imports:
| Import from | What lives there |
|---|---|
cgp::core::field::traits | the field-access traits HasField and HasFields; the builder traits HasBuilder, BuildField, and FinalizeBuild; the extractor traits HasExtractor, HasExtractorRef, HasExtractorMut, ExtractField, FinalizeExtract, FinalizeExtractResult; FromVariant; the shape traits ToFields, ToFieldsRef, FromFields, HasFieldsRef; IntoBuilder, TakeField, UpdateField, PartialData; HasFieldMut, FieldGetter, MutFieldGetter, MapField, FieldMapper, OptionAsRef; MapType, MapTypeRef, StaticString, AppendProduct, ConcatProduct, MapFields, TransformMap, TransformMapFields |
cgp::core::field::impls | the getter provider UseField, the casts CanUpcast, CanDowncast, CanDowncastFields, CanBuildFrom, and the markers IsPresent, IsNothing, IsVoid, IsOptional, IsRef, IsMut, and IsOwned |
cgp::core::field::types | the list types Cons, Nil, Either, and Void behind Product! and Sum!, Field, Index, Life, MRef, and the Chars and Symbol types behind Symbol! |
cgp::core::base::traits | StaticFormat, ConcatPath (and cgp::core::base::types for PathCons) |
cgp::core::component | DelegateComponent, IsProviderFor, CanUseComponent, RedirectLookup, UseContext, WithProvider, WithContext, UseFields, DefaultImpls1, DefaultImpls2 |
cgp::core::types | HasType, TypeProvider |
cgp::core::error / cgp::extra::error | the error wiring keys, and the generic error providers |
cgp::extra::handler | the whole handler family: the consumer traits (CanCompute, CanTryCompute, CanHandle, CanProduce, and their Ref and async forms), the provider traits (Computer, TryComputer, AsyncComputer, Handler, Producer, and their Ref forms) with every marker, the promotion bundles PromoteComputer, PromoteTryComputer, PromoteAsyncComputer, PromoteHandler, and PromoteProducer, and the providers Promote, PromoteAsync, PromoteRef, TryPromote, ReturnInput, ComposeHandlers, PipeHandlers, and UseInputDelegate |
cgp::extra::dispatch | every dispatch combinator, the value matchers MatchWithValueHandlers and MatchFirstWithValueHandlers with their Ref and Mut forms included |
cgp::extra::monad::traits | MonadicBind, ContainsValue, LiftValue, MonadicTrans |
cgp::extra::field::impls | the whole optional-field layer: HasOptionalBuilder, ToOptional, SetOptional, FinalizeOptional, CanFinalizeWithDefault, CanBuildWithDefault |
Check imports whenever code names the wiring machinery, a field-access, builder, extractor, or shape
trait, a type-level list type such as Cons or Nil, the field-state markers, the casts, the
optional-field traits, or any handler trait or marker, because none of those groups is in the
prelude. A provider also needs its component's key in scope unless it names its provider trait by
path, as Writing providers describes, so a provider on Computer imports
ComputerComponent beside it. A derive stays in the prelude when
its trait does not: #[derive(ExtractField)] needs no import, but calling .extract_field() needs
ExtractField from cgp::core::field::traits. Likewise #[derive(HasField)] and
#[derive(BuildField)] need no import, while a HasField bound, a .get_field() call, or a
builder call needs its trait from cgp::core::field::traits.
Versions and keeping this skill current gives the releases this skill describes and how to reconcile a mismatch with the project's. Inside documentation code blocks you may omit the prelude import for brevity.
Componentsβ
#[cgp_component] generates the traits and wiring support that separate calling a trait's methods
from implementing them. Apply it to the consumer trait that callers will use:
#[cgp_component(Greeter)]
pub trait CanGreet {
fn greet(&self);
}
The macro emits CanGreet unchanged, so callers write person.greet(). It also generates the
provider trait with Self moved to a leading Context parameter and self renamed to context:
pub trait Greeter<Context>: IsProviderFor<GreeterComponent, Context, ()> {
fn greet(context: &Context);
}
The component marker pub struct GreeterComponent; is the zero-sized key into the wiring table.
The blanket impls connect the sides. One makes any context that implements the provider trait
for itself implement the consumer trait. The other lets a context that delegates this component
(via DelegateComponent) inherit the provider trait from whatever provider it delegates to. You
never write these blanket impls. They are the routing machinery, and it is enough to think of wiring
as a table lookup.
That lookup is resolved entirely at compile time. The table is a set of trait impls, so the
compiler picks the provider during type resolution and monomorphizes the call to a direct, statically
dispatched one. CGP wiring is therefore zero-cost. "Table lookup" is a useful mental model, but the
generated code involves neither a runtime table nor dynamic dispatch nor a vtable. In real generated
code the context parameter is named __Context__ and the provider parameter __Provider__, reserved
identifiers chosen so they never clash with your types. The names Context/Provider here are for
readability.
The attribute's argument sets the generated names. The bare #[cgp_component(Greeter)] form names
only the provider trait. The component marker defaults to that name plus Component
(GreeterComponent) and the context to __Context__. A key/value form with brace delimiters
overrides any of them, as in
#[cgp_component { name: GreeterComponent, provider: Greeter, context: Context }], where only
provider is required. One limitation to know: a const generic parameter on the trait is
rejected, because a component's extra parameters are recorded as a tuple of types in
IsProviderFor, and a const value has nowhere to live there. An associated const item on the
trait is fine, and a const-generic provider struct supplies it as usual. See
macro-grammar for the full argument grammar and
components for the complete expansion.
A component trait can contain as many methods, associated types, and consts as an ordinary Rust
trait. Group items when one provider choice determines their implementation. A method and its
associated output type can form one such choice, as in CanCompute and CanHandle. A getter
component can group several field reads that one UseFields provider supplies by name.
Combining independent choices in one component reduces provider reuse. For example, a Shape
trait with area, perimeter, scale, and rotate requires each provider to satisfy all methods'
dependencies. A higher-order provider must forward methods it does not change, and a context using
only part of the interface may need placeholder types and unimplemented!() bodies for the rest.
Check whether another context could reuse a provider's complete implementation. A consumer trait named after an entity rather than an action can signal unrelated choices grouped together. If the provider would not be reusable, implement the trait directly on the concrete context. See components for multi-item examples, reuse costs, and how to split a component.
IsProviderFor and error messagesβ
IsProviderFor<Component, Context, Params> is an empty marker trait used as a supertrait on
every provider trait. Its only purpose is good error messages. A provider lists its dependencies in
a where clause, and the macros implement IsProviderFor for the provider under the same bounds.
So when a dependency is unmet, the compiler can name the missing bound instead of vaguely saying
"the trait is not implemented." When you see an error that some provider does not implement
IsProviderFor<β¦>, read it as "the provider trait is not implemented, because the named dependency
is missing." You never write IsProviderFor yourself. The provider macros generate it.
Writing providersβ
Prefer #[cgp_impl] when writing a provider. It accepts consumer-style method signatures with
self and Self, then rewrites them into the provider-trait form:
#[cgp_impl(new GreetHello)]
#[uses(HasName)]
impl Greeter {
fn greet(&self) {
println!("Hello, {}!", self.name());
}
}
The attribute names the provider, and new also declares struct GreetHello;. The
#[uses(HasName)] attribute generates the impl-side bound
where Self: HasName.
Prefer impl Greeter and let the macro insert the context parameter. Use the explicit
impl<Context> Greeter for Context form only when you must name or bound the context, such as for
a lifetime or higher-ranked trait bound the shorthand cannot express. Declare that context in the
impl generics. In either form, self and Self mean the context.
The header also names the component's key. The macro derives it from the provider trait's path as
the header writes it, appending Component to the last segment: impl Greeter names
GreeterComponent, and impl crate::components::Greeter names crate::components::GreeterComponent.
A provider in another module than its component therefore imports the key beside the trait, as
use crate::components::{Greeter, GreeterComponent};, or names the trait by its path. A module that
re-exports the trait re-exports the key in the same line. A key that the component's name: renames
or gives parameters differs from the derived name, so the provider names it after a colon, as
#[cgp_impl(new UnitArea: AreaComponent)]. The provider trait's generated doc names its key,
so an editor's hover on the trait shows which key to import.
A key that does not resolve fails with E0425, cannot find type `GreeterComponent` , on the
trait's name in the header. cargo cgp check reports it as [CGP-E041], with a fix that inserts
the use line, or as [CGP-E070] when the derived name is not the component's, with a fix that
names the key in the attribute. An editor running cargo cgp check offers either fix on the trait's
name. See components for an example.
The GreetHello example expands to a provider-trait impl with an explicit context parameter:
#[cgp_new_provider]
impl<Context> Greeter<Context> for GreetHello
where
Context: HasName,
{
fn greet(context: &Context) {
println!("Hello, {}!", context.name());
}
}
The lower-level provider macros accept explicit provider-trait impls. #[cgp_provider] preserves
an impl on an existing provider struct and generates IsProviderFor with the same where bounds.
#[cgp_new_provider] also declares the provider struct. Generic providers receive a PhantomData
field over their parameters, as in pub struct Multiply<Field>(PhantomData<Field>);. The attribute
can override the component name, which defaults to the provider trait's path with Component
appended, as for #[cgp_impl].
#[cgp_impl(Self)] emits a direct consumer-trait impl on a concrete context. This form requires
for Context and bypasses the provider rewrite while still applying companion attributes such as
#[use_provider].
Use these modern forms by default, with explicit syntax only where the attributes cannot express the required bounds:
- Providers: Write
#[cgp_impl]with animpl Greeterheader, omittingfor Context. - Dependencies: Use
#[uses]for trait dependencies and#[use_provider]for inner providers. - Field access: Prefer
#[implicit]for fields on the provider's context, including fields read by several providers. Use getter traits for access on other types, named accessors other code requires, or associated types inferred from fields. - Method supertraits: Use
#[extend]. - Abstract types: Import them with
#[use_type]and use the bare alias, including in#[cgp_component]definitions. - Per-type dispatch: Use
openor a namespace when defining new components.
Combine multiple #[uses] or #[use_type] arguments in one comma-separated attribute, as in
#[uses(A, B)] or #[use_type(T.X, U.Y)]. Each #[use_provider] binds one provider, so use a
separate attribute for each binding.
Use #[use_type]'s equality form to fix an abstract type to a concrete type. For example,
#[use_type(HasErrorType.{Error = AppError})] replaces
where Self: HasErrorType<Error = AppError>. This form works on #[cgp_impl] and #[cgp_fn] but
is rejected on #[cgp_component]. The right-hand side is also substituted, so an abstract type can
be defined in terms of another imported type; see abstract-types.
Keep explicit bounds where the attributes cannot express the dependency. Equality bounds on traits
you would not import types from, such as Iterator<Item = u8> or From<X>, remain in where
clauses. A lifetime or higher-ranked trait bound (HRTB) may require a named context. A trait's own
associated type remains qualified as Self::Output; only imported abstract types use bare aliases.
Load modern-idioms when reading or modernizing existing CGP for the
complete mapping between explicit and modern forms.
The provider's where clause is where impl-side dependencies live, whether you write it by hand
or let #[uses] generate it. GreetHello requires Self: HasName, but CanGreet does not expose
that bound, so a caller bounding on CanGreet never sees HasName. The wiring satisfies each
dependency by resolving it through the same context.
A consumer trait is still an ordinary trait. When you do not need multiple implementations, write
impl CanGreet for Person { β¦ } directly and skip the provider machinery.
Wiring: connecting a context to providersβ
Wiring records, on a context type, which provider supplies each component. The underlying mechanism
is the DelegateComponent trait, a type-level table whose key is the β¦Component marker and whose
Delegate associated type is the chosen provider. You almost always write it through
delegate_components!:
#[derive(HasField)]
pub struct Person {
pub name: String,
}
delegate_components! {
Person {
GreeterComponent: GreetHello,
}
}
After this, Person implements CanGreet, and person.greet() resolves through the table to
GreetHello. Swapping the table entry is the only change needed to swap behavior.
The macro has a few shorthands. An array key maps several components to one provider:
[FooComponent, BarComponent]: FooBarProvider. A leading new keyword
(delegate_components! { new MyComponents { β¦ } }) also defines struct MyComponents;. This is how
you build an aggregate provider, a zero-sized provider that holds a table dispatching each
component to a sub-provider, so other contexts can delegate a whole group of components to it as one
reusable unit. A leading generic list (delegate_components! { <T> MyContext<T> { β¦ } }) wires a
whole family of contexts at once.
Further operators stand where the : does, and you will meet them when reading real wiring.
Key -> OtherTable forwards the key to that table's own entry for the same key instead of naming a
provider. Key => @path redirects the lookup along a type-level path, and the open statement
below is its sugared special case. Those operators, the @-path key forms, and the namespace and
for statements belong to one shared body grammar that cgp_namespace! and
delegate_and_check_components! reuse in full. wiring and
macro-grammar carry it, and all of the forms combine inside a single
block.
The target of delegate_components! is therefore not always a context. It is either a concrete
context (as Person is above) or an aggregate provider (as MyComponents is). This distinction
governs checking. An aggregate provider is dispatched to by contexts and is never its own context,
so it must be wired with plain delegate_components! and never delegate_and_check_components!.
The next section explains why.
To understand what wiring does, picture the explicit version. delegate_components! is
equivalent to implementing the consumer trait by hand and forwarding to the provider:
impl CanGreet for Person { fn greet(&self) { <GreetHello as Greeter<Person>>::greet(self) } }.
The macro generates the forwarding impls and propagates IsProviderFor.
UseContextβ
UseContext is a provider that implements a provider trait by routing back through the context's
own consumer-trait impl, the dual of the consumer blanket impl. Wiring a component to UseContext
means "use whatever this context already does for this trait," which is mainly useful as the default
inner provider of a higher-order provider (below). Delegating a component directly to UseContext
when the context's only implementation of that component is that delegation creates a circular
dependency and fails to compile.
Dispatching a generic-parameter component per type with openβ
When a component is generic over a type parameter, you often want a different provider per value of
that parameter. The modern, preferred way is the open statement inside delegate_components!.
Given a component CanCalculateArea<Shape> (provider AreaCalculator), a context dispatches per
shape like this:
delegate_components! {
MyApp {
open AreaCalculatorComponent;
@AreaCalculatorComponent.Rectangle: RectangleArea,
@AreaCalculatorComponent.Circle: CircleArea,
}
}
Place open statements before plain Component: Provider mappings or the macro will fail to
parse. Use open AreaCalculatorComponent; for one component or open { A, B }; for several.
Each @Component.Key: Provider entry assigns a provider to one value of the dispatch parameter.
Choose path grouping by what the alternatives represent. Braces group complete path tails and
end the path, as in @AreaCalculatorComponent.{u32, u64, bool}: SomeProvider. Brackets group
alternatives for one segment and allow further segments:
@app.[FooComponent, BarComponent].[u64, String]: P creates every combination. Keys may carry
generics, as in @SomeComponent.<'a, T> &'a T: SomeProvider.
A key has one segment per type parameter of the component, because the redirect appends every
type parameter to the lookup path. So open dispatches on a later parameter too: for
CanCompute<Code, Input>, @ComputerComponent.<Code> Code.Plus<MathExpr>: EvalAdd selects by the
input whatever the code, replacing a legacy UseInputDelegate table, and
@ComputerComponent.Eval.Plus<MathExpr> selects by both. A shorter key overlaps every longer key
beneath it, and a generic segment matches every value, so never key @C.Eval beside @C.Eval.X or
@C.<Code> Code.X in one table. See
wiring.
open uses the RedirectLookup impl generated by #[cgp_component], so it does not need an
extra component attribute. It does not combine with a joined namespace (#[prefix(...)]); use the full namespace
feature for that arrangement.
Legacy form (read but don't write): older code dispatches the same way by wrapping a nested
table in the UseDelegate provider, as in
AreaCalculatorComponent: UseDelegate<new AreaCalculatorComponents { Rectangle: RectangleArea, Circle: CircleArea }>,
generated by a #[derive_delegate(UseDelegate<Shape>)] attribute on the component. This still works
and is common in existing code, but it is slated for deprecation, so prefer open for new code.
Some CGP-shipped components (the error and handler families) are still defined with
#[derive_delegate] in the library, so you will see UseDelegate and UseInputDelegate tables
wiring them.
Checking: verifying wiring at compile timeβ
CGP wiring is lazy. Defining a delegate_components! entry does not itself check that the
provider's transitive dependencies are satisfied. A missing dependency therefore surfaces only when
the consumer trait is finally used, often as a confusing error. To catch it early and clearly, assert
the wiring with a check:
check_components! {
Person {
GreeterComponent,
}
}
This generates a check trait whose supertrait is CanUseComponent<GreeterComponent, ()> for
Person. If Person cannot use the component, the compiler reports the missing dependency at this
site, walking through IsProviderFor so the real cause (such as a missing
HasField<Symbol!("name")>) is named rather than hidden. For a component with generic parameters,
list the parameter after the component (GreeterComponent: Rectangle), group multiple parameters as
a tuple ((Rectangle, f64)), and use array syntax to check several at once.
delegate_and_check_components! fuses wiring and checking in one step, so every delegation is
verified the moment it is written:
delegate_and_check_components! {
Person {
GreeterComponent: GreetHello,
}
}
Its check trait is named __CanUse{Context} (versus __Check{Context} for check_components!), so
both macros can appear once per module without clashing. Override the name with
#[check_trait(Name)]. When the delegated component has generic parameters, add
#[check_params(...)] on the entry. Skip a single entry's check with #[skip_check].
Use delegate_and_check_components! for basic wiring or a starter context. It helps newcomers
avoid omitting checks and encountering delayed wiring errors. It derives checks only for plain
Component: Provider entries, so advanced mappings need more control.
Keep delegate_components! and check_components! separate in larger or more advanced codebases.
Separate checks support open and namespaced wiring, concrete parameters for generic keys, and
#[check_providers(...)] assertions for individual provider layers. Every context's wiring must be
checked regardless of which macro is used.
Wire aggregate providers with plain delegate_components!. An aggregate provider supplies
implementations to other contexts, so checking it as a context with delegate_and_check_components!
asks the wrong question. The check passes vacuously if its providers need nothing from the context,
or blames the aggregate for fields and types that the actual context would supply. Verify the
aggregate through a real context that delegates to it, or use #[check_providers(...)] to assert
IsProviderFor directly.
Not every unsatisfied bound is a CGP component. Some are ordinary or blanket traits that
check_components! cannot verify, and those must be satisfied by ordinary Rust means.
For a nested higher-order provider, checking the context
tells you a layer is broken but not which one. The #[check_providers(...)] attribute on a
check_components! table changes the assertion from CanUseComponent on the context to
IsProviderFor on each named provider. A dependency missing only from the outer wrapper then errors
on its line alone, while one missing from the inner provider errors on both, which pinpoints the
layer. See checking for debugging instructions.
Functions and gettersβ
Most basic CGP reads and writes values from the context, and the constructs here make that look like plain Rust.
HasField and #[derive(HasField)]β
HasField<Tag> is tag-keyed field access. The Tag is a type-level name: Symbol!("width") for a
named field or Index<0> for a tuple field. #[derive(HasField)] generates one impl per field:
#[derive(HasField)]
pub struct Rectangle {
pub width: f64,
pub height: f64,
}
// generates HasField<Symbol!("width"), Value = f64> and HasField<Symbol!("height"), Value = f64>
Field values are read with self.get_field(PhantomData::<Symbol!("width")>). The PhantomData
carries the tag so type inference knows which field is meant, and the call needs HasField from
cgp::core::field::traits in scope.
#[cgp_fn] and #[implicit] argumentsβ
#[cgp_fn] turns one function into a single-implementation blanket-impl trait, the simplest entry
point to CGP. Arguments marked #[implicit] are removed from the signature and pulled from context
fields via HasField:
#[cgp_fn]
fn rectangle_area(&self, #[implicit] width: f64, #[implicit] height: f64) -> f64 {
width * height
}
This generates a RectangleArea trait (named from the function in PascalCase, or #[cgp_fn(MyName)]
to override) with a blanket impl for any context that has width: f64 and height: f64 fields.
An owned implicit argument clones its field, and a &str argument borrows any field that implements
AsRef<str>, such as String or Box<str>. Generic
parameters on the function move to the trait and impl, and the where clause becomes impl-side
dependencies on the impl only. Generic method parameters are intentionally unsupported. Prefer
implicit arguments for basic code, because they make CGP look like ordinary functions.
#[uses], #[extend], #[extend_where]β
#[uses(TraitA, TraitB<Param>)] (on #[cgp_fn] or #[cgp_impl]) imports Self trait bounds, read
like a use statement. The simple Trait<Params> form is idiomatic, but any where-clause bound is
accepted, including associated-type equality (HasErrorType<Error = AppError>). For abstract-type
pins, prefer #[use_type]'s equality form:
#[cgp_fn]
#[uses(RectangleArea)]
fn scaled_rectangle_area(&self, #[implicit] scale_factor: f64) -> f64 {
self.rectangle_area() * scale_factor * scale_factor
}
#[extend(Trait)] adds supertrait bounds to the generated trait. It is the only way to add
supertraits in #[cgp_fn], where ordinary where clauses declare impl-side dependencies. It is
also the preferred form for a non-type supertrait on #[cgp_component]: the attribute
presents the trait dependency directly.
Use #[use_type] for an abstract-type supertrait whose associated type appears in the signatures.
It adds the supertrait and rewrites uses of the type.
#[extend_where(Bound)] adds where clauses to a #[cgp_fn] trait definition. It accepts arbitrary
predicates, including associated-type equality, beyond the forms accepted by #[uses] and
#[extend].
#[impl_generics(Param: Bound)] adds a bounded parameter only to the impl generated by #[cgp_fn].
Use it when a function body borrows a generic value that should not become a trait parameter.
For example, #[impl_generics(Name: Display)] can support an #[implicit] name: &Name argument.
Getters: #[cgp_auto_getter], #[cgp_getter], UseFieldβ
Prefer #[implicit] arguments for reading fields from the provider's own context. They cover
fields shared by several providers and borrow plain &T arguments without cloning.
Use getter traits sparingly, for the cases implicit arguments cannot express:
- Access on another type: Take that type as the first argument, as in
fn foo_bar(foo: &Self::Foo) -> &Self::Bar, called asApp::foo_bar(&foo), or require a getter bound such asRequest: HasBasicAuthHeader<Self>. - Named accessor: Expose an accessor that other code requires through a bound such as
#[uses(HasName)]or a supertrait. - Abstract field type: Declare an associated return type inferred from the field, keeping its concrete type hidden from callers.
#[cgp_auto_getter] generates a blanket getter impl over HasField, with the field name taken from
the method name. It is the getter form to prefer for those cases:
#[cgp_auto_getter]
pub trait HasName {
fn name(&self) -> &str;
}
// blanket impl for any context with a `name` field; &str/&String shorthands handled
A single-getter trait may instead declare a local associated type used as the return type, inferred
from the field: trait HasName { type Name; fn name(&self) -> &Self::Name; }.
#[cgp_getter] is an advanced tool, reserved for when a context needs full control over which
field a getter reads from. Most getters should use #[cgp_auto_getter] or an implicit argument
instead. It is like #[cgp_component] but also provides a UseField<Tag> blanket impl, so the
getter's source field can be chosen by wiring rather than fixed to the method name. The
UseField<Tag> provider implements a getter by reading the field named Tag, which may differ from
the method name:
delegate_components! {
Person {
NameGetterComponent: UseField<Symbol!("first_name")>,
}
}
// Person::name() now returns the `first_name` field
UseFieldRef is the AsRef/AsMut-based variant. Any getter can also be implemented by hand. The
macros only save boilerplate.
Abstract typesβ
CGP abstracts over types with associated types in components. #[cgp_type] is the dedicated macro,
so use it instead of #[cgp_component] for an abstract-type trait:
#[cgp_type]
pub trait HasNameType {
type Name;
}
This defaults the provider name to the type name plus TypeProvider (here NameTypeProvider,
marker NameTypeProviderComponent) and also generates a UseType blanket impl. A context fixes the
type by wiring the component to UseType<ConcreteType>:
delegate_components! {
Person {
NameTypeProviderComponent: UseType<String>,
}
}
// or directly: impl HasNameType for Person { type Name = String; }
The direct impl is just as valid, and it shows that abstract types are ordinary associated-type traits.
The #[use_type(HasScalarType.Scalar)] attribute is the recommended way to use an abstract type
inside #[cgp_fn], #[cgp_impl], or #[cgp_component]. It rewrites bare Scalar to the fully
qualified <Self as HasScalarType>::Scalar everywhere and adds the supertrait or where bound,
removing Self:: boilerplate and ambiguity. CGP's tag-indexed abstract-type component is HasType
(provider TypeProvider); the named ones, such as HasErrorType, are defined with #[cgp_type].
Higher-order providersβ
A higher-order provider takes another provider as a generic parameter and constrains it with a provider-trait bound, so its inner behavior is chosen by wiring rather than fixed:
#[cgp_impl(new ScaledAreaCalculator<InnerCalculator>)]
#[use_provider(InnerCalculator: AreaCalculator)]
impl<InnerCalculator> AreaCalculator {
fn area(&self, #[implicit] scale_factor: f64) -> f64 {
let base_area = InnerCalculator::area(self);
base_area * scale_factor * scale_factor
}
}
#[use_provider(InnerCalculator: AreaCalculator)] completes the inner provider's bound by adding the
Self parameter for you (you write : AreaCalculator, and it means AreaCalculator<Self>) and
moves it into the where clause. That is the only thing the attribute does. Inside the body you
still call the provider explicitly with the associated-function form InnerCalculator::area(self).
The attribute does not rewrite the call site. A context then chooses the inner provider when wiring,
for example AreaCalculatorComponent: ScaledAreaCalculator<RectangleAreaCalculator>.
A higher-order provider often defaults its inner parameter to UseContext
(pub struct IterSumArea<Inner = UseContext>(PhantomData<Inner>);), so that when an inner provider
is not named, the inner step falls back to the context's own wiring for a different trait
instance, such as an element type; asking for the instance being computed is a cycle. Not every provider with a generic
parameter is higher-order. A provider like GetName<Tag> that uses Tag only as a HasField key,
without a provider-trait bound, is not.
When a component itself is generic (#[cgp_component(AreaCalculator)] trait CanCalculateArea<Shape>),
the provider trait appends the parameters after the context (AreaCalculator<Context, Shape>),
IsProviderFor groups them into its Params tuple, and lifetimes are lifted into the Life<'a>
type. Such a component is most useful for cross-context dependencies. When the main target is a
generic parameter (CanCalculateArea<Shape>: HasScalarType), individual shape types need not
implement the shared traits. The common context supplies the shared abstract type, value-level
injection (a global scale factor via a getter), and lazy per-context provider binding, so two apps
can wire the same shape to different providers.
Error handlingβ
CGP makes the error type abstract, so generic code can fail without naming a concrete error.
HasErrorType (an abstract-type component, type Error: Debug) gives a context one shared error
type. CanRaiseError<SourceError> constructs it from a concrete source error
(Context::raise_error(source)), and CanWrapError<Detail> attaches detail. Both build on
HasErrorType and are associated-function (without self) components that dispatch per source or
detail type. An error-aware trait imports the error type with #[use_type(HasErrorType.Error)], so
it names the error as the bare Error instead of writing : HasErrorType and Self::Error by hand:
#[cgp_component(Loader)]
#[use_type(HasErrorType.Error)]
pub trait CanLoad {
fn load(&self, path: &str) -> Result<String, Error>;
}
#[cgp_impl(new LoadOrFail)]
#[uses(CanRaiseError<String>)]
#[use_type(HasErrorType.Error)]
impl Loader {
fn load(&self, path: &str) -> Result<String, Error> {
if path.is_empty() {
return Err(Self::raise_error("empty path".to_owned()));
}
Ok(format!("contents of {path}"))
}
}
A context wires its error type and the raise/wrap behavior. The generic error providers plug in per
source type, modern-style with open. They are RaiseFrom (convert via From), ReturnError,
RaiseInfallible, PanicOnError, DebugError/DisplayError (format into a String and forward),
and DiscardDetail:
delegate_components! {
App {
open ErrorRaiserComponent;
ErrorTypeProviderComponent: UseType<String>,
@ErrorRaiserComponent.String: RaiseFrom,
@ErrorRaiserComponent.ParseError: DebugError,
}
}
Imports: HasErrorType, CanRaiseError, and CanWrapError come from the prelude. The wiring
keys (ErrorTypeProviderComponent, ErrorRaiserComponent, ErrorWrapperComponent) live under
cgp::core::error, and the generic error providers (RaiseFrom, DebugError, β¦) under
cgp::extra::error, so import the specific names you wire. Standalone backends (cgp-error-anyhow,
cgp-error-eyre, cgp-error-std) set a concrete error type and supply matching raisers and
wrappers; load error backends before wiring one.
Handlers: the computation familyβ
CGP models computation as a family of components along the axes of synchronous versus async, infallible versus fallible, and input-taking versus input-free:
Computer/CanComputeis a synchronous, infallible transformcompute(&self, PhantomData<Code>, input) -> Output. By-reference (ComputerRef) and async (AsyncComputer) variants exist.TryComputer/CanTryComputeis the fallible computer.Producer/CanProduceis input-free production (only a context and aCodetag).Handler/CanHandleis the general async, fallible, error-aware computation, used for I/O and pipelines. It requiresHasErrorTypeas a supertrait.CanRun/CanSendRunare task runners.
Any CGP trait with async methods, whether a handler, a runner, or one you define, declares them under
the #[async_trait] attribute. The attribute rewrites each async fn to -> impl Future, the
lint-clean, allocation-free form. The generated future does not carry a Send bound, so spawning it
on a work-stealing executor needs the Send-recovery pattern in handlers.
#[cgp_computer] and #[cgp_producer] define a Computer/Producer provider from a function.
Providers compose through combinators. PipeHandlers<Product![A, B, C]> chains handlers left to
right, ComposeHandlers nests them, ReturnInput passes input through, and the Promote* adapters
lift a simpler handler (such as a sync Computer) into a more capable one (an async Handler). For
example, a context wires a pipeline of field-reading computers:
delegate_components! {
MyContext {
ComputerComponent:
PipeHandlers<Product![
Multiply<Symbol!("foo")>,
Add<Symbol!("bar")>,
Multiply<Symbol!("baz")>,
]>,
}
}
// context.compute(PhantomData::<()>, 5) runs ((5*foo)+bar)*baz
Dispatch routes an extensible-data input to per-variant handlers. #[cgp_auto_dispatch] generates a
handler from a trait, and the combinators MatchWithHandlers, MatchWithValueHandlers, and
ExtractFieldAndHandle match an enum's variants to sub-handlers, proving exhaustiveness without a
wildcard. Monadic handlers (PipeMonadic, BindOk, BindErr, the identity/ok/err monads) compose
handlers through a monad. The handler family is broad, so read handlers
for the full set, including Send-bound recovery for async trait methods.
Extensible dataβ
CGP can build and read structs and enums generically, by their named fields and variants. The
#[derive(HasFields)] derive exposes a type's whole field list. #[derive(CgpData)], and the
record- or variant-specific CgpRecord/CgpVariant, derive the full extensible-data machinery:
#[derive(CgpData)]
pub struct Person {
pub first_name: String,
pub last_name: String,
}
The extensible builder pattern constructs records field by field through HasBuilder and
BuildField. It assembles a context from independent outputs for each field. The underlying field
list uses Product![A, B, C], represented by Cons and Nil.
The extensible visitor pattern handles each variant of an enum. FromVariant constructs variants,
and the ExtractField family deconstructs them. Variant lists use Sum![A, B], represented by
Either and Void. The handler dispatch combinators described above route variant inputs to their
handlers.
Structural casts convert between data shapes. CanUpcast widens a smaller enum into a larger one,
CanDowncast narrows an enum, and CanBuildFrom rebuilds a record from a superset of its fields.
Namespacesβ
Namespaces provide reusable wiring tables that can inherit from a parent. Define one with
cgp_namespace! { new MyNs: ParentNs { β¦ } }, omitting the parent when inheritance is unnecessary.
A context joins it with namespace MyNs; inside delegate_components!. The context's direct entries
supply the paths the namespace leaves unbound; an entry for a key the namespace already binds
conflicts with it (E0119), so a namespace binds only what every joining context shares.
Register a component in a namespace with #[prefix(@path in MyNs)] on its #[cgp_component]
trait. A #[cgp_impl] provider registers a per-type default through
#[default_impl(T in DefaultImpls1<Component>)]. The context imports those defaults with a
for <T, Provider> in Table { β¦ } loop.
A context can also forward a whole path to an aggregate provider, as in @app.core: CoreComponents.
A bundle keyed by bare component names needs nothing more, but a bundle keyed by paths must join the
namespace itself, or its entries never match; see namespaces.
The underlying mechanism is the RedirectLookup provider, which re-routes a component lookup along
a type-level Path!. The open statement above is a lightweight special case of it.
DefaultNamespace is the built-in namespace, where CGP's own components and most applications'
components register their routes. Read namespaces for the preset and
inheritance syntax.
Type-level primitivesβ
CGP encodes lists, strings, and numbers as types. Use the shorthand macros when writing code, and recognize their expanded forms when reading errors:
Symbol!("name")is a type-level string (field-name tag). It expands toSymbol<4, Chars<'n', Chars<'a', Chars<'m', Chars<'e', Nil>>>>. The leading length works around missing const-generics.Product![A, B, C]is a type-level list. It expands toCons<A, Cons<B, Cons<C, Nil>>>.product![β¦]is the value-level form. Used for field lists and handler pipelines.Sum![A, B]is a type-level sum (the dual ofProduct!), over theEither/Voidlist. Used for enum variant lists.Struct! { name: T }/Struct!(A, B)andEnum! { V(T) }write a struct or enum shape as a declaration body. Each expands to exactly theFieldsthat#[derive(HasFields)]gives the same body.Index<N>is a type-level natural number, and tags tuple-struct fields.Fieldis a value paired with its type-level name tag.Path!/PathConsis a type-level path, used by namespaces andRedirectLookup.Life<'a>is a lifetime lifted into a type, used when a component has lifetime parameters.MRefis an owned-or-borrowed value.
Prefer the shorthand macros (Symbol!, Product!) and readable type names (Cons/Nil) when
writing code.
Sub-skills: load the one that owns your taskβ
Load each sub-skill that applies before reading, writing, reviewing, or debugging code in its area. These references provide exact grammar, expansions, corner cases, and worked examples beyond the primer. Load all relevant references when a task spans several areas, follow their cross-links, and reload a reference when entering an unfamiliar part of the topic.
Start with macro-grammar whenever writing, editing, or debugging CGP
syntax. It defines the accepted macro forms, the invariants their expansions preserve, and how to
interpret compiler errors involving IsProviderFor and DelegateComponent.
Load modern-idioms when reading or modernizing existing CGP. It maps
explicit and legacy forms to current syntax, including provider impls, handwritten where bounds,
Self::Type paths, and UseDelegate tables.
Choose the remaining references by task:
- Components: Load before writing components or providers. Covers
the complete
#[cgp_component]expansion,IsProviderFor, provider macros, the meaning ofself/Self, and how component grouping affects reuse. - Wiring: Load before wiring a context. Covers
DelegateComponent,delegate_components!forms,openand its dispatch on a later parameter such as a handler's input, direct consumer impls,UseContextcycles, legacyUseDelegatetables, and adapters such asWithProvider,WithField,WithType,WithContext, andUseDefault. - Checking: Load when wiring fails to compile. Explains lazy wiring,
check traits,
CanUseComponent, and the#[check_trait],#[check_providers],#[check_params], and#[skip_check]options for locating missing dependencies. - Error extraction: Load only when
cargo-cgpis unavailable or leaves an error largely unrewritten; see Tooling first. Covers summarizing raw errors, distinguishing hidden from surfaced causes, confirming a cause through a signature line, and delegating error reading to a sub-agent. - Functions and getters: Load for field access and
function-style traits. Covers
HasField,#[cgp_fn], implicit access and its borrowing rules, dependency attributes, getter macros,UseField/WithField, andChainGetters. - Abstract types: Load for associated-type abstraction. Covers
#[cgp_type],HasType/TypeProvider,UseType/UseDelegatedTypewiring,#[use_type]imports, andWithType/WithDelegatedTypeadapters. - Higher-order providers: Load before composing
providers. Covers inner-provider bounds, the context parameter,
#[use_provider], explicit provider calls,UseContextdefaults, generic components, and cross-context dependencies. - Error handling: Load for fallible CGP code. Covers
HasErrorType, raising and wrapping errors, the generic error providers, and which imports come from the prelude,cgp::core::error, orcgp::extra::error. - Error backends: Load before wiring
cgp-error-anyhow,cgp-error-eyre, orcgp-error-std. Covers each backend's four providers, routing each source type, when a backend is unnecessary, per-crate behavior, and the common wiring errors. - Handlers: Load for computation and I/O pipelines. Covers the
computation families, function and dispatch macros, combinators, monadic handlers,
HasRuntime/HasRuntimeType, andSendrecovery for async methods. - Extensible data: Load for generic struct and enum operations.
Covers data derives, builders, extractors, optional and defaulted fields, product and sum lists,
AppendProduct/ConcatProduct/MapFields, structural casts, exhaustiveness, and the one-payload-or-none variant rule. - Namespaces: Load for grouped or inherited wiring. Covers
cgp_namespace!, joining and iterating namespaces,#[prefix],#[default_impl],RedirectLookup,Path!, andDefaultNamespace. - Type-level primitives: Load to interpret nested types
in errors and expansions. Covers symbols, product and sum lists,
Index,Field, paths,Life,MRef, andStaticFormatrecovery traits. - Modularity hierarchy: Load when deciding how much CGP a problem needs. Compares plain blanket traits through per-provider wiring and identifies the coherence restrictions each approach avoids.
- Versions: Load when the project's
cgporcargo-cgpdiffers from the releases this skill describes. Covers what to tell the user, how to checkmainfor a newer skill, each install route's update command, and the changes between supported releases.
Exhaustive online referenceβ
For the exact macro expansion of any construct, every accepted syntax form, corner cases, or the
implementing source, consult the online knowledge base at
https://github.com/contextgeneric/cgp-knowledge-base. CGP's own section is
cgp/, whose reference/,
concepts/, guides/, and errors/ directories are the most complete record, and the worked
examples/ sit at the
base's top level beside it. The base also documents cargo-cgp, under
cargo-cgp/. Fetch the
relevant page when a detail is not covered here. Do not assume a local copy exists, because this
skill is deployed on its own.
The base's checks can miss a stale sentence or an inconsistency, so some of its documents contain errors that no review has found yet. The CGP source outranks it, as it outranks this skill: when a document and the code disagree, trust the code, and tell the user so they can report the document on the issue tracker.
Instructions for explaining CGP to usersβ
Assume basic Rust knowledge and unfamiliarity with CGP unless the user indicates otherwise. For code changes, add explanations only when asked. When explaining, introduce advanced Rust concepts such as generics, traits, blanket impls, and coherence as needed, along with unfamiliar functional or type-level programming concepts.
Explain wiring as choosing a provider from a table. Keep IsProviderFor, DelegateComponent, and
generated blanket impls out of the explanation unless the user asks about internals. Say "trait",
"method", or "operation" for what a component or #[cgp_fn] defines, never "capability", per
The core vocabulary. Familiar
analogies can help explain type-level tables, lists, and strings, but make their limits explicit:
CGP resolves wiring at compile time and generates direct static calls. If comparing it to a vtable,
state that CGP resolves calls statically, without a runtime table, dynamic dispatch, or lookup cost.
State that component traits can contain multiple items whenever component grouping comes up.
Single-method examples must not imply a macro restriction: component traits can contain methods,
associated types, and consts just as ordinary Rust traits can. CanCompute and CanHandle, for
example, define an associated Output alongside their method. Present grouping as the author's
choice about provider reuse, following components.
When asked to explain a specific piece of code, look up the definitions it depends on before
answering. To explain a delegate_components! entry, find the consumer and provider traits behind
the component key and the body of the provider it maps to. To explain a provider, read its own
definition and the definitions of every trait in its where clause. To explain how a context
implements something, follow its wiring to see which providers are chosen and trace a method call
through them. For instance, if NameGetterComponent is wired to UseField<Symbol!("first_name")>,
then a self.name() call inside another provider returns the context's first_name field.