Skip to main content

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 segmentBecomes
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 a type 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 open statement rather than constructing paths yourself when the goal is per-type dispatch on one component. open builds the route for you, and its @Component.Key entries 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.

  • 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 the open statement that builds routes for you.
  • Symbol! — what a lowercase segment becomes.
  • Type-level lists — the PathCons chain the expansion builds.
  • Product! and Sum! — 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​


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.