#[prefix(...)]
Register a component into a namespace under a type-level path, so every context that joins the namespace addresses the component by that path.
Overview
In Context-Generic Programming (CGP), #[prefix(...)] registers a component into a
namespace under a path prefix. CGP enables pluggable trait
implementations in Rust, and a prefix is where a component's route into a shared wiring table is
named. Written on the component's trait beside #[cgp_component], it
adds the component's own route to the namespace. A namespace is a reusable wiring table that a
context joins with one line and then overrides where it needs to. (The context is the type the
method runs on.) A namespace answers a lookup by routing it: asked for a component, it says
where to look next.
#[cgp_component(Greeter)]
#[prefix(@app in AppNamespace)]
pub trait CanGreet {
fn greet(&self) -> String;
}
Read that as: in AppNamespace, GreeterComponent is found at @app.GreeterComponent. When a
context joins AppNamespace and asks for GreeterComponent, the namespace sends it to that path, and
the provider bound there is the one that runs. The attribute records only the route. Something else
binds a provider at the path: a direct @app.GreeterComponent: GreetHello entry on the context, an
entry in the namespace's body, or a #[default_impl] on a provider.
Prefixes turn a flat wiring table into a tree. With components registered under @app.auth,
@app.finance, and @app.error, related entries sort together, a reader finds the auth wiring
without reading the finance wiring, and a library can register its components into a shared
namespace for applications it will never see. CGP's own components do this. HasErrorType and the
error components carry #[prefix(@cgp.core.error in DefaultNamespace)], and the handler family
carries #[prefix(@cgp.extra.handler in DefaultNamespace)].
Usage
Apply the attribute to a trait that carries #[cgp_component], or one
of the macros built on it, #[cgp_type] and
#[cgp_getter]. The argument has two parts joined by the keyword in:
#[prefix(@path.segments in NamespacePath)]
| Part | Meaning |
|---|---|
@path.segments | The prefix: a @-sigil path of one or more dot-separated segments, in Path!'s syntax. The macro appends the component's marker after it. |
in | Required keyword. |
NamespacePath | The namespace to register into: DefaultNamespace, or one defined with cgp_namespace!. It may be a qualified path and may carry generic arguments. |
The path is a prefix, and the macro appends the component marker for you.
#[prefix(@app in DefaultNamespace)] on CanGreet registers GreeterComponent at
@app.GreeterComponent. Writing the marker yourself doubles it. See
Common Mistakes.
Segments follow Path!'s convention. A lowercase identifier that is not a
primitive type name becomes a type-level string, so @app and @cgp.core.error are strings. Any
other segment names a type, so @MyApp.MyBarComponent is two types. Case decides the meaning. A
segment cannot declare generic parameters, and the parser accepts neither of the […] and {…}
grouping forms a delegate_components! key allows. One
attribute registers under exactly one prefix.
Repeat the attribute to register into several namespaces, one attribute per namespace:
#[cgp_component(BarProvider)]
#[prefix(@MyApp.MyBarComponent in MyNamespace)]
#[prefix(@my_app.MyBarComponent in OtherNamespace)]
pub trait Bar {
fn bar(&self);
}
A component with type parameters is addressed with the parameters after the marker. The lookup
appends them to the path, so a context joining the namespace wires a CanShow<T> registered under
@app with entries such as @app.ShowImplComponent.String: ShowWithDisplay. Lifetime parameters
do not appear in the path.
Any crate may register its own components into any namespace. The emitted impl is for the
component's marker, a type the component's crate owns, so Rust's orphan rule is satisfied even when
the namespace comes from another crate. That is why an application can register into
DefaultNamespace. It is also the difference from #[default_impl], whose key
on a prefixed component is a foreign path.
Choosing a prefix
A prefix is part of the component's public surface, and costly to change once wiring depends on
it. So choose it with every implementation the component might have in mind, not only the one you are
writing now. Give components separate sub-paths whenever they are likely to need separate providers,
even when the current wiring happens to treat them alike. Abstract types belong under a types sub-path
of their layer, such as @app.auth.types, because a production context typically points the logic
under @app.auth at a database while leaving the types on the same concrete choices.
Register prefixes into a base namespace, DefaultNamespace or a namespace that describes the
application's structure, and bind providers in a namespace that inherits it. A namespace's entry for
a key cannot be overridden once defined, so a namespace that held both the prefixes and one backend's
providers could not lend its prefixes to a second backend.
Examples
A component registered under a prefix, a provider, and a context that joins the namespace and binds the provider at the prefixed path:
use cgp::prelude::*;
#[cgp_component(Greeter)]
#[prefix(@app in DefaultNamespace)]
pub trait CanGreet {
fn greet(&self) -> String;
}
#[cgp_impl(new GreetHello)]
impl Greeter {
fn greet(&self, #[implicit] name: &str) -> String {
format!("Hello, {name}!")
}
}
#[derive(HasField)]
pub struct App {
pub name: String,
}
delegate_components! {
App {
namespace DefaultNamespace;
@app.GreeterComponent: GreetHello,
}
}
check_components! {
App {
GreeterComponent,
}
}
Reading the resolution: app.greet() looks up GreeterComponent. App does not wire it directly,
so the lookup falls through to DefaultNamespace, which redirects to @app.GreeterComponent, and
App's own table binds that path to GreetHello. Environmental context, self-targeted: App
exists to carry the wiring and a name field, and the operation is about App itself.
A second context joins the same namespace and binds a different provider at the same path, without repeating anything from the first:
#[cgp_impl(new GreetFormally)]
impl Greeter {
fn greet(&self, #[implicit] name: &str) -> String {
format!("Good day, {name}.")
}
}
#[derive(HasField)]
pub struct FormalApp {
pub name: String,
}
delegate_components! {
FormalApp {
namespace DefaultNamespace;
@app.GreeterComponent: GreetFormally,
}
}
The prefixes CGP's own components carry are wired the same way. A context that joins
DefaultNamespace chooses its error type and an error strategy by full path, with the dispatch type
of the generic CanRaiseError component written after its marker:
use cgp::core::error::{ErrorRaiserComponent, ErrorTypeProviderComponent};
use cgp::extra::error::ReturnError;
pub struct Service;
delegate_components! {
Service {
namespace DefaultNamespace;
@cgp.core.error.ErrorTypeProviderComponent: UseType<String>,
@cgp.core.error.ErrorRaiserComponent.String: ReturnError,
}
}
When to use it
Reach for #[prefix] as soon as a wiring table has enough components that grouping helps a
reader. It costs nothing at the point of use, it is the one namespace tool without a downstream
restriction, and the table it produces reads like a directory listing. It is also the form a library
uses to publish its components into a shared namespace.
Some situations call for something else.
- A component only ever wired directly on a context does not need a prefix. The
openstatement ofdelegate_components!dispatches it per type without a namespace, and the two do not combine on one component. - The wiring binds a provider at a path, not the component. Use a direct entry on the context, a
cgp_namespace!body entry, or#[default_impl]on the provider. - A small, explicitly delegated bundle is an aggregate provider, which contexts adopt by delegating named components to it. Namespaces and prefixes justify their extra indirection when there are many components, when inheritance is wanted, or when a library publishes defaults for applications it does not know about.
Under the hood
The attribute adds one impl to #[cgp_component]'s output, after the standard provider impls: an
impl of the namespace trait for the component marker, whose Delegate is a
RedirectLookup down the prefixed path. From
#[prefix(@app in DefaultNamespace)] on CanGreet:
impl<__Components__> DefaultNamespace<__Components__> for GreeterComponent {
type Delegate = RedirectLookup<__Components__, Path!(@app.GreeterComponent)>;
}
__Components__ is the table the lookup runs against. The macro appends it as the namespace trait's
last generic argument and leaves it generic, so one registration serves every context that joins. A
namespace defined with cgp_namespace! gets the same shape against its own trait:
impl<__Components__> MyNamespace<__Components__> for BarProviderComponent.
The path is the prefix with the marker appended, a PathCons list.
cargo cgp expand prints it as Path!(@app.GreeterComponent), and a raw compiler error prints the
underlying PathCons<Symbol<3, Chars<'a', …>>, PathCons<GreeterComponent, Nil>>.
Resolution then runs through the namespace, then the redirect, then the context's own table. Joining
the namespace emits, on the context, a blanket DelegateComponent impl whose Delegate is whatever
the namespace answers, so asking App for GreeterComponent yields
RedirectLookup<App, Path!(@app.GreeterComponent)>. That provider's impl
of Greeter looks the path up in App's own table, as App: DelegateComponent<Path!(...)>, and
forwards to the delegate it finds there, GreetHello. For a component with type parameters,
RedirectLookup appends the parameters to the path before the lookup, which is why per-type entries
carry them after the marker.
The impl has the same shape as a => entry written in a namespace body:
GreeterComponent => @app.GreeterComponent inside cgp_namespace! emits the same item. The
attribute lets the component's own crate contribute that entry, which a foreign crate could not write
into the namespace's body.
The namespace's key is the marker rather than the path, which is easy to misread: a help: list in
an error names GreeterComponent as implementing the namespace trait even when the path it routes
to is empty. A component marker declared with generics through the name: key of
#[cgp_component] also carries those generics onto the impl after __Components__.
Formal grammar
The attribute argument is a path, the keyword in, and a namespace path, in the Rust Reference's
notation:
PrefixArgs -> Path `in` NamespacePath
Path -> `@` PathSegment ( `.` PathSegment )*
PathSegment -> Type
NamespacePath -> TypePath GenericArgs?
Path is Path!'s own production: a leading @, then one or more segments,
each parsed as a Rust Type and encoded as a type-level string or a named type by the rule above. A
segment cannot declare generic parameters, and the parser does not accept the […] and {…} groups
of a delegate_components! path key. NamespacePath is a Rust
type path with optional generic arguments, and the macro appends the table argument itself. Both
parts are required, the attribute takes exactly one such argument, and it is repeated for several
namespaces.
Common Mistakes
The macro appends the marker, so do not write it. #[prefix(@app.GreeterComponent in Ns)]
routes the component to @app.GreeterComponent.GreeterComponent. On a component without type
parameters the mistake stays hidden, because a context's @app.GreeterComponent entry also matches
every longer path beneath it and so catches the doubled route. On a component with type parameters it
surfaces. With #[prefix(@app.ShowImplComponent in DefaultNamespace)] on a CanShow<T>, the entry
@app.ShowImplComponent.String does not match the route
@app.ShowImplComponent.ShowImplComponent.String, and the check reports the unbound path described
next. Write the prefix alone.
Registering routes a component but does not bind a provider. A prefixed component compiles even
when nothing binds its path, and so does a context that joins the namespace. Only a
check_components! reports it, as an unsatisfied bound on the
path rather than on a provider. With the CanGreet component from Examples and a
context that joins the namespace without binding the path:
delegate_components! {
App {
namespace DefaultNamespace;
// nothing binds @app.GreeterComponent
}
}
check_components! {
App {
GreeterComponent,
}
}
error[E0277]: the trait bound `PathCons<Symbol<3, Chars<'a', ...>>, PathCons<GreeterComponent, Nil>>: DefaultNamespace<App>` is not satisfied
|
| GreeterComponent,
| ^^^^^^^^^^^^^^^^ unsatisfied trait bound
|
= help: the following other types implement trait `DefaultNamespace<Components>`:
ErrorRaiserComponent
GreeterComponent
The help: list names GreeterComponent itself, which reads like a contradiction and is in fact the
diagnosis: the registration worked, and only the binding at the leaf is missing.
The compile errors page reads this diagnostic in full. The
fix is to bind a provider at the path: a direct entry on the context, a namespace body entry, or a
#[default_impl] on the provider.
Two attributes naming the same namespace conflict. Each emits an impl of that namespace's trait for the same marker, and the compiler rejects the second:
#[cgp_component(Greeter)]
#[prefix(@app in AppNamespace)]
#[prefix(@greeting in AppNamespace)]
pub trait CanGreet {
fn greet(&self) -> String;
}
error[E0119]: conflicting implementations of trait `AppNamespace<_>` for type `GreeterComponent`
Both carets land on the #[cgp_component] attribute rather than on the two #[prefix] lines, so the
message does not say which registration is the duplicate. A component has one route per namespace. To
reach it under two paths, define two namespaces.
open does not reach a prefixed component in a joined namespace. open roots the route at the
bare marker, while the prefix routes under the path, so the per-type entries open expects are never
consulted. Write the entries with the full prefixed path instead, as
cgp_namespace! explains.
Case decides a segment's meaning without a warning. @app is a type-level string and @App is a
type, both are valid, and a capitalization slip routes to a path nothing binds. The failure surfaces
as the unbound path above, without a hint about the letter. See
Path!.
On #[cgp_auto_getter] the attribute is accepted and dropped. That macro runs the same attribute
collector as #[cgp_component], to apply #[extend] and #[use_type], but it generates no
component to register, so a #[prefix] on it registers nothing and reports nothing. A getter that
must live in a namespace is a #[cgp_getter] component.
On #[cgp_impl] or #[cgp_fn] the compiler does not recognize the attribute. Neither macro
consumes it, so it reaches the compiler as an attribute that does not exist:
#[cgp_impl(new GreetHello)]
#[prefix(@app in DefaultNamespace)]
impl Greeter {
fn greet(&self) -> String {
"Hello!".to_owned()
}
}
error: cannot find attribute `prefix` in this scope
The provider-side counterpart is #[default_impl], which binds a provider at a
path rather than routing a component to one.
Related constructs
cgp_namespace!— defines the namespaces a prefix registers into, and the=>body entry that emits the same impl.delegate_components!— thenamespacestatement that joins, and the@-path entries that bind a provider at a prefixed path.#[default_impl]— the provider-side registration: it binds, where this attribute routes.DefaultNamespace— the built-in namespace CGP's own components register into.RedirectLookup— the delegate every registration resolves through.Path!andPathCons— the path syntax and the type-level list it builds.#[cgp_component],#[cgp_type], and#[cgp_getter]— the hosts.check_components!— the only thing that catches a route bound to nothing.
The ideas behind it:
- Namespaces — reusable, inheritable wiring tables, and why presets need no separate construct.
Source
- The attribute:
types/attributes/prefix.rs - Collection on the component:
types/attributes/cgp_component_attributes.rs - Emission, after the standard provider impls:
types/cgp_component/evaluated/item.rs - A library use:
has_error_type.rs
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.