Skip to main content

PathCons

One segment of a type-level path: the list that names a route through nested delegation tables, so a lookup can reach an entry several layers deep.

Overview​

In Context-Generic Programming (CGP), PathCons<Head, Tail> expresses a route through nested delegation tables as a single type. A bare component name picks one entry out of a context's table. Here the context is the type the implementation runs against, and its table records which provider it uses for each component. Sometimes the entry a lookup wants sits behind a layer of indirection: inside a namespace, behind a namespace it inherits from, or under a prefix. A path names such a route as a list of segments read left to right, and each segment narrows the lookup a step further. PathCons is the cell of that list, and Nil terminates it, so PathCons<A, PathCons<B, Nil>> is the path that steps through A and then B.

A path differs from the Cons product list in its unsized bound, even though both are right-nested and end in Nil. PathCons declares its head and tail ?Sized, so a segment may be an unsized type such as str, and code can manipulate the whole path without its parts having a known size. A product list keys a struct's fields, and its elements are always sized values. A path keys a lookup, and its segments are pure type-level markers that never need to be Sized.

The segments are the markers CGP uses elsewhere. A lowercase dotted name becomes a Symbol type-level string, and a capitalized name becomes that named type, usually a component key such as FooProviderComponent or a namespace marker. So a path interleaves symbols and component names, in the form @a.B.c, assembled into a PathCons chain. You write paths through the Path! macro. This page covers the list type, and that macro's page covers the @-segment syntax.

Definition​

PathCons is a zero-sized struct holding a phantom marker for the head segment and another for the rest:

pub struct PathCons<Head: ?Sized, Tail: ?Sized>(pub PhantomData<Head>, pub PhantomData<Tail>);

Head is the first segment, and Tail is the remainder, which is another PathCons or Nil at the end. Both bounds are ?Sized, so any type may occupy a segment. The struct holds nothing at run time. Like the other type-level building blocks, it exists through PhantomData so that trait resolution can name and match a route. It is not in the prelude, so import it from cgp::core::base::types, or let the prelude's Path! macro write it for you.

Behavior​

PathCons supports path concatenation through the ConcatPath trait, which appends one path onto the end of another at the type level. The trait recurses down the list: PathCons<Head, Tail> concatenates with Other by keeping Head and concatenating Tail with Other, while Nil concatenates with Other by becoming Other. The result is ordinary list append, computed as an associated-type projection.

RedirectLookup consumes a path. When a namespace entry, an open statement, or a => redirect reroutes a lookup, it produces a RedirectLookup<Components, Path> whose Path is a PathCons chain. Its impl, which #[cgp_component] generates for each component, extends the path with the component's type parameters through ConcatPath, then looks the whole extended path up in Components as one key, through DelegateComponent. The path never names a provider itself. It only says which key to look up, so the same path can resolve to different providers in different tables, and the entry it reaches may redirect again.

Examples​

A path is a type, so the checks here are type equalities. The cgp_namespace! entry at the top reroutes one component to a path:

use cgp::core::base::traits::ConcatPath;
use cgp::core::base::types::PathCons;
use cgp::core::field::types::Nil;
use cgp::prelude::*;

#[cgp_component(FooProvider)]
pub trait CanFoo {
fn foo(&self);
}

#[cgp_component(MyFoo)]
pub trait CanMyFoo {
fn my_foo(&self);
}

cgp_namespace! {
new MyNamespace {
FooProviderComponent =>
@MyFooComponent,
}
}

pub fn demo() {
// A lowercase segment is a `Symbol`, and a capitalized one names its type.
let _: PhantomData<PathCons<Symbol!("app"), PathCons<MyFooComponent, Nil>>> =
PhantomData::<Path!(@app.MyFooComponent)>;

// A one-segment path.
let _: PhantomData<PathCons<MyFooComponent, Nil>> = PhantomData::<Path!(@MyFooComponent)>;

// `ConcatPath` appends one path to another.
let _: PhantomData<Path!(@a.b.c)> =
PhantomData::<<Path!(@a.b) as ConcatPath<Path!(@c)>>::Output>;
}

The namespace entry expands into a RedirectLookup over the one-segment path. cargo cgp expand prints the path in its Path! form:

impl<__Table__> MyNamespace<__Table__> for FooProviderComponent {
type Delegate = RedirectLookup<__Table__, Path!(@MyFooComponent)>;
}

which is RedirectLookup<__Table__, PathCons<MyFooComponent, Nil>>. A single-segment path is PathCons<Segment, Nil>, and the empty path is Nil alone.

When to use it​

You read PathCons in an expansion. You write Path!, or you wire a namespace.

  • Decode a PathCons chain by reading the segments left to right. Each segment is one step of the route: a Symbol for a lowercase name, or a component or namespace type for a capitalized one.
  • Use Path! to write a path when you need one directly, in its @a.B.c form.
  • Use a namespace rather than a raw path for the common case: joining a cgp_namespace! or the open statement of delegate_components! produces the paths for you.

Common Mistakes​

A path names a route, not a provider. A PathCons chain describes which key to look up. The provider it resolves to depends on the table that RedirectLookup looks it up in, so the same path can resolve to different providers in different contexts.

A path list is ?Sized, unlike the Cons product list. Its segments are markers rather than values, so a segment need not have a known size. Expecting a path to behave like a product list of values is the usual source of confusion.

Both a path and a product end in Nil. A Nil at the end of a PathCons chain is the same terminator doing the same job it does for a record. It does not mean the two lists have been mixed.

A table's own path keys end in a parameter, not in Nil. A path key written in delegate_components! matches every longer path beneath it, so its last PathCons holds a generic parameter where a Path! holds Nil. The expansion of such a table shows that parameter rather than Nil.

  • Nil: the end marker that terminates a PathCons chain.
  • Cons: the product list this one parallels, whose elements are sized values rather than ?Sized markers.
  • Chars: the Symbol segments a path is built from.
  • Path!: the macro that folds @-segments onto this list.
  • ConcatPath: appends one path onto another.
  • RedirectLookup: looks a path up in a table at resolution time.
  • cgp_namespace!: emits these paths to reroute and register entries.

The ideas behind it:

  • Namespaces: where a path routes a component lookup through a reusable table.

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.