Skip to main content

Modern idioms: reading and modernizing CGP

Prefer modern CGP syntax in new code, and keep explicit forms for cases the shorthand cannot express. This reference pairs older forms with their modern equivalents so you can read generated code and revise existing implementations. The examples assume use cgp::prelude::*;, with handler names such as ComputerComponent from cgp::extra::handler and HasField from cgp::core::field::traits, and describe CGP v0.8.0.

Modern syntax makes providers resemble ordinary trait impls and expresses dependencies through attributes. The macros still expand to explicit traits, bounds, and provider calls, so those forms remain useful when reading expansions. The exceptions below identify cases that need explicit syntax.

Each comparison explains the rule connecting the forms. Preserve the original bounds and behavior when applying it; field access and dispatch rewrites also require checking the context's fields and wiring.

Provider shape: #[cgp_impl] over the raw provider forms​

Write providers with #[cgp_impl] to use self, Self, and consumer-style method signatures. The lower-level #[cgp_provider] and #[cgp_new_provider] forms take an explicit context parameter and a receiver such as context: &Context. This older implementation reads the rectangle's fields through HasField:

#[cgp_new_provider]
impl<Context> AreaCalculator<Context> for RectangleArea
where
Context: HasField<Symbol!("width"), Value = f64>,
Context: HasField<Symbol!("height"), Value = f64>,
{
fn area(context: &Context) -> f64 {
*context.get_field(PhantomData::<Symbol!("width")>)
* *context.get_field(PhantomData::<Symbol!("height")>)
}
}

The modern form uses #[cgp_impl] and #[implicit] arguments to read the same fields:

#[cgp_impl(new RectangleArea)]
impl AreaCalculator {
fn area(&self, #[implicit] width: f64, #[implicit] height: f64) -> f64 {
width * height
}
}

#[cgp_impl] expands through the lower-level provider macros, so their explicit form still appears in generated code. Write that form directly only when you need a provider-trait impl or bounds the shorthand cannot express.

Context parameter: omit for Context​

Omit for Context from a #[cgp_impl] header unless the context needs an explicit name or bound. The macro supplies its reserved context parameter. For example, this implementation names the context only to require HasDimensions:

#[cgp_impl(new RectangleArea)]
impl<Context> AreaCalculator for Context
where
Context: HasDimensions,
{
fn area(&self) -> f64 { self.width() * self.height() }
}

The bare header and #[uses] express the same requirement without naming the context:

#[cgp_impl(new RectangleArea)]
#[uses(HasDimensions)]
impl AreaCalculator {
fn area(&self) -> f64 { self.width() * self.height() }
}

Dependencies: #[uses] and #[use_provider] over hand-written where​

Declare trait dependencies on the context with #[uses(...)] and inner-provider requirements with #[use_provider(...)]. These attributes generate impl-side dependencies: #[uses(CanCalculateArea)] adds Self: CanCalculateArea, and #[use_provider(Inner: AreaCalculator)] adds Inner: AreaCalculator<Self>. The explicit form names those bounds in a where clause:

#[cgp_impl(new ScaledArea<InnerCalculator>)]
impl<Context, InnerCalculator> AreaCalculator for Context
where
Context: HasField<Symbol!("scale_factor"), Value = f64>,
InnerCalculator: AreaCalculator<Context>,
{
fn area(&self) -> f64 { /* ... */ }
}

The modern form moves the inner-provider bound to an attribute and the field requirement to an implicit argument:

#[cgp_impl(new ScaledArea<InnerCalculator>)]
#[use_provider(InnerCalculator: AreaCalculator)]
impl<InnerCalculator> AreaCalculator {
fn area(&self, #[implicit] scale_factor: f64) -> f64 { /* ... */ }
}

Use one comma-separated #[uses] attribute for several traits, as in #[uses(CanQueryUserBalance, CanRaiseHttpError<ErrNotFound, String>)]. It accepts where-clause bounds, though the simple Trait<Params> form is preferred. For an abstract-type equality such as Self: HasErrorType<Error = AppError>, prefer the #[use_type] equality form. Keep explicit bounds for traits whose associated types you would not import, such as Iterator<Item = u8>.

Give each inner provider its own #[use_provider] attribute. A comma-separated list of provider-and-trait pairs does not parse. To require several traits on one provider, join its bounds with +.

Field reads: #[implicit] over a getter trait​

Prefer #[implicit] arguments for fields on the provider's own context. Each argument names the field and the local value, and a plain &T borrows without cloning. This also applies when several providers read the same field. The following getter-based implementation can use implicit arguments instead:

#[cgp_auto_getter]
pub trait HasDimensions {
fn width(&self) -> &f64;
fn height(&self) -> &f64;
}

#[cgp_impl(new RectangleArea)]
#[uses(HasDimensions)]
impl AreaCalculator {
fn area(&self) -> f64 { self.width() * self.height() }
}

Implicit arguments read width and height directly from the context:

#[cgp_impl(new RectangleArea)]
impl AreaCalculator {
fn area(&self, #[implicit] width: f64, #[implicit] height: f64) -> f64 {
width * height
}
}

Use #[cgp_auto_getter] when the access needs a trait of its own:

  • Another type's field: Require a getter on that type, such as Request: HasBasicAuthHeader<Self>.
  • Named accessor: Expose an accessor that other code requires through a trait bound.
  • Abstract field type: Infer a getter's associated return type from the field.

Reserve #[cgp_getter] for choosing the getter's source field per context through wiring. Ordinary reads from the provider's own context should use implicit arguments.

Abstract types: #[use_type] over supertrait + Self::Type​

Import abstract types with #[use_type] and use their bare aliases. The attribute adds the owning trait as a supertrait on #[cgp_component] or as an impl-side bound on #[cgp_impl] and #[cgp_fn]. It also rewrites each alias to its fully qualified associated-type path. This applies to built-in types such as Error, which the explicit form qualifies as Self::Error:

#[cgp_component(Loader)]
pub trait CanLoad: HasErrorType {
fn load(&self, path: &str) -> Result<String, Self::Error>;
}

The attribute supplies the supertrait and qualifies Error for you:

#[cgp_component(Loader)]
#[use_type(HasErrorType.Error)]
pub trait CanLoad {
fn load(&self, path: &str) -> Result<String, Error>;
}

Keep a definition's own associated types qualified as Self::Assoc. The rewrite applies only to imported bare identifiers. A handler declaring type Output therefore writes Result<Self::Output, Error> when Error is imported.

Combine type imports in one comma-separated attribute, as in #[use_type(HasUserIdType.UserId, HasCurrencyType.Currency, HasErrorType.Error)]. Use braces for several types from one trait: #[use_type(HasFooType.{Foo, Bar})]. Repeated attributes behave identically, but the combined form keeps the imports together.

Use the trailing in Context clause to import an associated type from another type. For example, #[use_type(HasUserIdType.UserId in App)] adds App: HasUserIdType and rewrites UserId to <App as HasUserIdType>::UserId. It replaces the explicit bound and qualified type in this getter:

#[cgp_auto_getter]
pub trait HasLoggedInUser<App>
where
App: HasUserIdType,
{
fn logged_in_user(&self) -> &Option<App::UserId>;
}

The imported alias makes the getter's return type shorter:

#[cgp_auto_getter]
#[use_type(HasUserIdType.UserId in App)]
pub trait HasLoggedInUser<App> {
fn logged_in_user(&self) -> &Option<UserId>;
}

The attribute supplies App: HasUserIdType, so the generic parameter needs only the name App.

Import abstract types explicitly even when an imported trait's supertrait already reaches the impl. #[uses] bounds only the impl, so a #[cgp_fn] signature cannot name the type through it. If CanCreateFoo extends HasFooType, use #[uses] for the trait and #[use_type] for its type:

#[cgp_fn]
#[uses(CanCreateFoo)]
#[use_type(HasFooType.Foo)]
fn bar(&self) -> Foo { self.create_foo(42) }

Relying on the transitive supertrait does not compile, because the generated Bar trait has no HasFooType supertrait for Self::Foo to resolve through:

#[cgp_fn]
#[uses(CanCreateFoo)]
fn bar(&self) -> Self::Foo { self.create_foo(42) } // error[E0220]: associated type `Foo` not found

cargo cgp check reports this as [CGP-E035] and names the import. The #[use_type] import adds HasFooType to the generated trait and rewrites the bare Foo.

Use the equality form #[use_type(Trait.{Assoc = Type})] to constrain an abstract type to a concrete one. It replaces an explicit bound such as Self: HasErrorType<Error = AppError> in this provider:

#[cgp_impl(new DisplayHttpError)]
impl<Code, Detail> HttpErrorRaiser<Code, Detail>
where
Self: HasErrorType<Error = AppError>,
Code: IsStatusCode,
Detail: Display,
{
fn raise_http_error(_code: Code, detail: Detail) -> AppError { /* ... */ }
}

The equality moves into the attribute while the other generic bounds stay in the where clause:

#[cgp_impl(new DisplayHttpError)]
#[use_type(HasErrorType.{Error = AppError})]
impl<Code, Detail> HttpErrorRaiser<Code, Detail>
where
Code: IsStatusCode,
Detail: Display,
{
fn raise_http_error(_code: Code, detail: Detail) -> AppError { /* ... */ }
}

The attribute emits Self: HasErrorType<Error = AppError> and rewrites any bare Error. This example continues to name the concrete AppError directly.

The equality's right-hand side can also refer to imported aliases. For example, #[use_type(HasPasswordType.Password, HasHashedPasswordType.{HashedPassword = Password})] equates HashedPassword with <Self as HasPasswordType>::Password. Nested aliases work too: #[use_type(HasDbType.Db, HasTransactionType.{Transaction = Tx<Db>})] produces Self: HasTransactionType<Transaction = Tx<<Self as HasDbType>::Db>>.

The equality form is supported on #[cgp_impl] and #[cgp_fn], where it produces an impl-side bound. #[cgp_component] rejects it.

Supertraits: #[extend] over native : syntax​

Add supertraits that contribute methods with #[extend(...)]. It generates the same bound as native pub trait CanDoX: Supertrait syntax, while distinguishing a public dependency from the impl-side dependencies declared with #[uses]. The explicit form places HasName after the trait name:

#[cgp_component(Greeter)]
pub trait CanGreet: HasName {
fn greet(&self) -> String;
}

The attribute form declares the same HasName supertrait:

#[cgp_component(Greeter)]
#[extend(HasName)]
pub trait CanGreet {
fn greet(&self) -> String;
}

Use #[extend] for method supertraits and #[use_type] for abstract types named in the signature. The latter also rewrites the type aliases. Either way, each provider of the component repeats the import (#[uses(HasName)] or the same #[use_type]), because the provider trait carries the supertrait as a where bound that an impl must prove. In #[cgp_fn], ordinary where clauses describe impl-side dependencies, so use #[extend] to add a supertrait.

Per-type dispatch: open and namespaces over UseDelegate​

Use open or a namespace to choose a provider per generic argument. Both use the RedirectLookup impl generated by #[cgp_component]. The older UseDelegate pattern stores its per-type entries in a separate table:

delegate_components! {
MyApp {
AreaCalculatorComponent:
UseDelegate<new AreaCalculatorComponents {
Rectangle: RectangleArea,
Circle: CircleArea,
}>,
}
}

The open form stores the same provider choices directly on the context:

delegate_components! {
MyApp {
open AreaCalculatorComponent;

@AreaCalculatorComponent.Rectangle: RectangleArea,
@AreaCalculatorComponent.Circle: CircleArea,
}
}

A legacy UseInputDelegate table, which dispatches on a later parameter such as a handler's Input, converts the same way. The open redirect appends every type parameter to the lookup path, so each table entry becomes a key with one segment per parameter:

// legacy
delegate_components! {
Interpreter {
ComputerComponent:
UseInputDelegate<new EvalComponents {
MathExpr: DispatchEval,
Plus<MathExpr>: EvalAdd,
}>,
}
}

// modern
delegate_components! {
Interpreter {
open ComputerComponent;

@ComputerComponent.<Code> Code.MathExpr: DispatchEval,
@ComputerComponent.<Code> Code.Plus<MathExpr>: EvalAdd,
}
}

A UseDelegate table nested around UseInputDelegate tables, keyed first on the code and then on the input, becomes keys with a concrete first segment: @ComputerComponent.Eval.Plus<MathExpr>. See wiring for the one overlap rule.

Components dispatched through open or namespaces do not need #[derive_delegate(UseDelegate<Param>)]. That attribute generates the provider support for legacy UseDelegate tables. Some CGP error and handler components retain it for compatibility.

Choose open for a context's own per-type wiring. Use a namespace when several contexts should share a reusable table or inherit common routes.

When the explicit forms are still right​

Keep explicit syntax where it expresses a requirement the preferred shorthand does not cover:

  • Other trait bounds: Keep explicit bounds such as Iterator<Item = u8> or From<X> when they are not abstract-type imports. Use #[use_type] for abstract-type equalities.
  • Named context: Write impl<Context> Trait for Context when a lifetime or higher-ranked bound requires the name. Use #[cgp_impl(Self)] with an explicit concrete context for a direct consumer impl.
  • Configurable getter: Use #[cgp_getter] when wiring must choose the source field per context.
  • Explicit provider impl: Write the raw provider-trait form when the shorthand cannot express the implementation.
  • Local associated type: Keep Self::Output qualified when the definition declares Output itself.

For routine providers, dependencies, and field reads, use the modern forms above.

Reading pre-0.7 code: renamed and removed names​

Pre-0.7 code may use names that current CGP has removed or renamed. Replace #[cgp_context] with delegate_components! and the relevant derive or getter machinery. The abstract-type provider trait formerly named ProvideType is now TypeProvider.

Check an unfamiliar name against the current exports, the online knowledge base's reference, and its removal ledger, which says where each renamed or removed name went, before copying it. A missing prelude export may require an explicit import; it does not by itself prove that the name was removed.

Consult the owning reference for full syntax and expansion details: