Path!
A type-level path, used by namespaces and redirected lookups.
Overview
In Context-Generic Programming (CGP), Path!(@a.B.c) builds a type-level route: a list
of segments naming a way through nested wiring tables.
Read left to right, each segment narrows a lookup one step: through a namespace, through a prefix, down to a
component key.
CGP needs such routes because namespaces resolve lookups by path rather than by
bare component name, which lets a whole subtree be rerouted at once and a context supply a single path
the namespace leaves open without disturbing the rest. Written as the underlying list, those routes are
unreadable (PathCons<…, PathCons<…, Nil>> nested several deep), so Path! lets one be written the way
it reads:
Path!(@app.error.ErrorRaiserComponent)
It is the path-shaped sibling of CGP's other type-level construction macros. Where
Symbol! turns a literal into a type-level string and Product! and
Sum! build record and variant lists, Path! builds the routing list. It shares their
right-nested shape and, like Product!, ends in Nil.
You will more often write the syntax than the macro. The same @-path form is embedded directly in
cgp_namespace! entries, in #[prefix(...)] attributes, and in the @-path keys of
delegate_components!. That is where paths are normally written. The bare
macro is for the occasional case where a route needs naming as a type on its own.
Usage
Path! takes a single @-prefixed path of one or more dot-separated segments. The leading @ is required,
since it is the sigil marking the body as a path rather than a plain type, and at least one segment must follow:
Path!(@app)
Path!(@app.error)
Path!(@app.error.ErrorRaiserComponent)
How a segment is encoded
Each segment is parsed as a type, and its spelling decides how it is treated: a bare lowercase identifier becomes a string, and anything else stays a type. This is the one rule worth learning, because it lets a path mix names and types without any extra syntax:
| The segment | Becomes |
|---|---|
A single identifier starting with a lowercase ASCII letter (app, my_app) | a Symbol type-level string |
A capitalized name (ErrorRaiserComponent) | that named type |
A primitive type name (u32, bool, str) | that type, not a symbol. A name that only looks like one, such as f or u2, is a symbol |
Any other type (Vec<u8>, some_mod::Marker, &'static str) | that type |
So lowercase segments read as namespace and prefix names, capitalized ones as component keys or marker types,
and the primitive exception keeps @u32 meaning the type u32 rather than the string "u32". Mixing is
normal: @my_app.ShowImplComponent interleaves a symbol and a component.
This is the same convention namespaces describe for their @-paths, because it is
literally the same parser.
Examples
Used directly, Path! names a route that a RedirectLookup resolves against
a table:
use cgp::core::error::ErrorRaiserComponent;
use cgp::prelude::*;
type ErrorRoute = Path!(@app.error.ErrorRaiserComponent);
// ErrorRoute = PathCons<Symbol!("app"),
// PathCons<Symbol!("error"),
// PathCons<ErrorRaiserComponent, Nil>>>
In practice the same syntax appears embedded rather than through the bare macro. A namespace entry redirects a component along a path:
cgp_namespace! {
new MyNamespace {
FooProviderComponent =>
@MyFooComponent,
}
}
and a #[prefix(...)] attribute registers a component under one:
#[cgp_component(ShowImpl)]
#[prefix(@show in AppNamespace)]
pub trait CanShow {
fn show(&self) -> String;
}
and a wiring table keys an entry on one:
delegate_components! {
MyApp {
namespace AppNamespace;
@show.ShowImplComponent: ShowWithDebug,
}
}
All four build the same kind of list. The macro and the embedded syntax are two places to write it, not two
different things, with one difference in the last: a delegate_components! path key ends in a wildcard
parameter rather than Nil, so it also matches longer paths beneath it.
When to use it
Write the @-path syntax wherever a namespace or a wiring key asks for a route, and use the bare
Path! macro only when a route needs to be a named type on its own, which is rare.
- Prefer the embedded form. A namespace entry, a
#[prefix], or an@-path wiring key is where a route belongs, and each accepts the syntax directly. Naming atype SomeRoute = Path!(…)and using it indirectly usually makes the wiring harder to follow rather than easier. - Never hand-write the list. The macro expands to
PathCons<Symbol!("app"), PathCons<…, Nil>>, and writing it out is longer and identical in meaning. - Use the
openstatement rather than constructing paths yourself when the goal is per-type dispatch on one component.openbuilds the route for you, and its@Component.Keyentries are the paths: you write the keys, not the routing. - Do not use
Path!as a general type-level list.Product!is the list for a sequence of types;Path!differs in its segment-classification rule, which exists to serve routing and would be surprising anywhere else.
Under the hood
Path! expands to a right-nested chain of PathCons terminated by Nil, with each segment encoded by the
lowercase-versus-capitalized rule:
// before
Path!(@app.error.ErrorRaiserComponent)
// after (readable form)
PathCons<
Symbol!("app"),
PathCons<
Symbol!("error"),
PathCons<ErrorRaiserComponent, Nil>,
>,
>
The macro parses the segments after the @ into a list and folds them right to left onto Nil, wrapping each in
a PathCons whose tail is the accumulated rest. A single-segment path is therefore PathCons<Segment, Nil>.
A lowercase segment nests a second list inside the first, which is why a fully-expanded path is longer than
it looks: the Symbol is itself a Chars/Nil chain, so @app desugars all the way down to
PathCons<Symbol<3, Chars<'a', Chars<'p', Chars<'p', Nil>>>>, Nil>
A raw compiler error prints exactly that, which is the main reason this section is worth reading once. The
segment-classification rule is visible in the result: @MyComp gives PathCons<MyComp, Nil> with no Symbol
in it, and @u32 gives PathCons<u32, Nil> rather than treating the primitive as a name.
The same fold drives the embedded forms. A cgp_namespace! redirect
FooProviderComponent => @MyFooComponent produces a
RedirectLookup<__Table__, PathCons<MyFooComponent, Nil>>, and #[prefix(@show in AppNamespace)] on a
CanShow component produces a PathCons<Symbol!("show"), PathCons<ShowImplComponent, Nil>>: the prefix
followed by the component's own key.
One presentational note: cargo cgp expand resugars a path back to Path!(@…) form in most positions, but not
uniformly. An open statement's per-entry key comes back as a raw PathCons list while its header's redirect
target is resugared. Seeing the same kind of type in two spellings in one expansion is expected rather than a
sign that they differ.
Formal grammar
The input is a leading @ followed by one or more dot-separated segments, in the Rust Reference's
notation:
PathInput -> `@` PathSegment ( `.` PathSegment )*
PathSegment -> Type
The leading `@` is required and at least one segment must follow. Each PathSegment is parsed
as a Rust Type, but its encoding is decided semantically: a single identifier starting with a
lowercase ASCII letter that is not a primitive's name becomes a Symbol type-level string, while
every other segment (a capitalized name, a primitive, or any type with a path, generic arguments, or
other structure) is kept as the type. cgp_namespace! entries and
#[prefix(...)] attributes embed this same grammar, where it appears as the Path production.
Common Mistakes
The leading @ is not optional, and the macro says exactly what it wanted:
error: expected `@`
Case decides meaning, silently. @app and @App are entirely different segments (a type-level
string versus a named type), and wherever a type App exists both are valid, so a capitalization
slip produces a path that compiles and routes somewhere else. The failure surfaces later as a lookup
that resolves to nothing, with no hint that the cause was a capital letter.
A lowercase primitive is the type, not a string. @u32, @bool, and @str name those types. That is
almost always what you want, and it means a path segment cannot be the string "u32" through this syntax.
A path needs a segment after the @ and after every dot. @ alone, or a trailing dot as in
@app., fails while parsing the missing segment as a type, with a message that lists type tokens:
error: unexpected end of input, expected one of: `for`, parentheses, `fn`, `unsafe`, `extern`, identifier, `::`, `<`, `dyn`, square brackets, `*`, `&`, `!`, `impl`, `_`, lifetime
A path that routes nowhere still compiles. A route is only a type; nothing checks that anything is bound at
its end. An unbound route is reported only when a check_components! evaluates the
lookup, as an unsatisfied bound naming the expanded path. This is why namespace mistakes tend to surface at
the check rather than at the definition.
Related constructs
cgp_namespace!— where paths are mostly written, in entries and#[prefix]attributes.RedirectLookup— the provider that resolves a path against a table.delegate_components!—@-path keys and theopenstatement that builds routes for you.Symbol!— what a lowercase segment becomes.- Type-level lists — the
PathConschain the expansion builds. Product!andSum!— the sibling construction macros, sharing the fold shape.DelegateComponent— the per-key table a resolved path finally reads.
The ideas behind it:
- Namespaces — where paths are actually written, and what a route is for.
Source
- Entry point:
path.rs - Parsing and the fold:
types/path/ - Runtime
PathCons:types/path.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.