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:
| Alias | Expands to | Import from |
|---|---|---|
WithContext | WithProvider<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.
Related constructs
#[cgp_type]and#[cgp_getter]— generate theWithProviderimpls that make a component adaptable.TypeProviderandFieldGetter— the foundational traits it adapts.UseContext,UseType,UseField,UseFieldRef, andUseDelegatedType— the inner providers its aliases wrap.WithContext,WithType,WithField,WithFieldRef, andWithDelegatedType— the aliases this adapter is spelled through, one page each.delegate_components!— wires the aliases, andcheck_components!verifies them.
The ideas behind it:
- Abstract types — where the
TypeProviderlayer this adapts is used. - Consumer and provider traits — the provider-trait layer the adapter bridges.
Source
- Struct:
with_provider.rs; theWithContextalias inuse_context.rs - The
WithType/WithDelegatedTypealiases incgp-type/src/impls/, andWithField/WithFieldRefincgp-field/src/impls/ - The generated
WithProviderimpls:cgp_type/item.rsandcgp_getter/with_provider.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.