Skip to main content

WithProvider

Adapt a foundational provider, one implementing TypeProvider or FieldGetter, into a provider of a specific named component.

Overview​

Context-Generic Programming (CGP) has two layers of provider trait, one foundational and one per named component, and WithProvider<Provider> bridges them. Foundational traits like TypeProvider and FieldGetter are generic, component-agnostic mechanisms: a TypeProvider supplies some abstract type for some tag, and a FieldGetter reads some field for some output tag, without either knowing which named component it serves. A named component, by contrast, has a specific provider trait, such as NameTypeProvider or NameGetter, that a context wires to, where the context is the type the implementation runs against. WithProvider<Provider> is the adapter that lets a foundational provider stand in as the provider for one of those named components: it implements the component's provider trait by forwarding to the foundational provider's method.

This adapter lets the foundational layer be wired without each foundational provider implementing every component trait by hand. A field getter written once as a FieldGetter can serve any number of getter components through WithProvider, and an abstract-type implementation written once as a TypeProvider can serve any type component the same way.

WithProvider is rarely written in full, because its common uses are packaged as aliases. The family WithContext, WithType, WithField, WithFieldRef, and WithDelegatedType are each WithProvider<...> specialized to a particular inner provider, and those aliases are what appear in everyday wiring. Understanding WithProvider explains why the aliases work. Like every CGP provider, it carries no runtime value.

Usage​

WithProvider is not in the prelude; import it from cgp::core::component. It takes one type parameter, the foundational provider to adapt, and appears as the value of a named component's wiring entry. In practice you write one of its aliases instead:

AliasExpands toImport from
WithContextWithProvider<UseContext>cgp::core::component
WithType<Type>WithProvider<UseType<Type>>cgp::core::types
WithField<Tag>WithProvider<UseField<Tag>>cgp::core::field::impls
WithFieldRef<Tag, Value>WithProvider<UseFieldRef<Tag, Value>>cgp::core::field::impls
WithDelegatedType<Components>WithProvider<UseDelegatedType<Components>>cgp::core::types

Each alias wires the inner provider it names as a specific component's provider. A component becomes adaptable this way only when its macro generates the WithProvider impl: #[cgp_type] does so for every abstract-type component, and #[cgp_getter] does so for a getter with exactly one method.

Examples​

The everyday way to use WithProvider is through one of its aliases, which reads as a single wiring choice. Adapting the context's own field getter into a getter component uses WithField:

use cgp::prelude::*;
use cgp::core::field::impls::WithField;

#[cgp_getter]
pub trait HasName {
fn name(&self) -> &str;
}

#[derive(HasField)]
pub struct Person {
pub first_name: String,
}

delegate_components! {
Person {
NameGetterComponent: WithField<Symbol!("first_name")>,
}
}

check_components! {
Person {
NameGetterComponent,
}
}

pub fn demo() {
let person = Person { first_name: "Ada".to_owned() };
assert_eq!(person.name(), "Ada");
}

WithField<Symbol!("first_name")> expands to WithProvider<UseField<Symbol!("first_name")>>, so Person's NameGetter provider is the adapter wrapping the foundational UseField getter for the first_name field. The generated WithProvider impl forwards name() to UseField's FieldGetter::get_field, which reads first_name. The same shape recurs for abstract types: wiring a type component to WithType<String> adapts UseType<String>, and to WithDelegatedType<SomeTable> adapts a UseDelegatedType that resolves the type through a table.

When to use it​

Reach for one of the aliases, not WithProvider directly. WithType<T> and UseType<T> are interchangeable on every #[cgp_type] component, and WithField<Tag> and UseField<Tag> on every single-method getter, so prefer the plain provider there. WithField is the form to wire when a #[cgp_type] component should take a field's type, since such a component has no UseField impl. WithContext is not interchangeable with UseContext: wired to a component, UseContext calls the context's own consumer trait for that component, which loops, while WithContext reads the context's HasField or HasType entry keyed by the component. WithFieldRef and WithDelegatedType have no plain wireable form, because their inner providers are foundational, so you wire the alias. Each alias is documented on its own page, linked from the table above.

Write WithProvider<Provider> in full only when adapting a foundational provider that has no ready alias.

Under the hood​

#[cgp_type] and #[cgp_getter] generate a WithProvider impl that forwards a component's provider-trait method to the inner provider's foundational method. For a type component such as

#[cgp_type]
pub trait HasNameType {
type Name;
}

#[cgp_type] emits a WithProvider impl that defines the component's associated type from the inner TypeProvider (shown with the macro's real placeholder identifiers):

impl<__Provider__, Name, __Context__> NameTypeProvider<__Context__> for WithProvider<__Provider__>
where
__Provider__: TypeProvider<__Context__, NameTypeProviderComponent, Type = Name>,
{
type Name = Name;
}

For a single-method getter, #[cgp_getter] emits an analogous impl that reads the value through the inner FieldGetter:

impl<__Context__, __Provider__> NameGetter<__Context__> for WithProvider<__Provider__>
where
__Provider__: FieldGetter<__Context__, NameGetterComponent, Value = String>,
{
fn name(__context__: &__Context__) -> &str {
::core::convert::AsRef::as_ref(
__Provider__::get_field(
__context__,
::core::marker::PhantomData::<NameGetterComponent>,
),
)
}
}

A &mut self getter bounds the inner provider by MutFieldGetter instead, and a slice getter bounds the value by AsRef<[T]> + 'static rather than fixing it.

In both cases the bound names the foundational trait, keyed by the component marker, and the method or associated type forwards to it. #[cgp_getter] generates the WithProvider impl only when the getter has exactly one method, since a single foundational getter cannot serve several methods at once. Each impl is paired with a matching IsProviderFor impl.

The struct itself is a plain marker, pub struct WithProvider<Provider>(pub PhantomData<Provider>);, with no implementations of its own. The aliases specialize WithProvider to a fixed inner provider so the common cases need no WithProvider<...> spelled out. Each has its own page: WithContext, WithType, WithField, WithFieldRef, and WithDelegatedType, and each lives beside the inner provider it wraps.

The ideas behind it:

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.