FieldGetter
The provider-side form of HasField: field access a context chooses by wiring.
Generated machinery
You are not expected to name FieldGetter in wiring. A getter component defined with
#[cgp_getter] accepts any provider of it through
WithProvider, and
UseField is the provider you usually name there, as
WithField<Tag>. What you write is the wiring entry. The one case for implementing the trait
yourself is a getter provider whose read no existing provider expresses.
Overview
In Context-Generic Programming (CGP), HasField is a bound an
implementation states about its own context. Sometimes
the field should instead be chosen by wiring, so that each
context, the type the method runs on, which supplies the
values it needs as its fields, decides which of its fields answers a getter. That needs the
provider-trait shape: a zero-sized provider as Self, and the context as an explicit type argument.
FieldGetter is that shape, and it is the ordinary consumer and provider split applied to field
access: you bound against HasField, and you wire a FieldGetter. Four library
providers implement it. UseField<Tag> reads the field Tag;
UseFieldRef reads one through AsRef;
UseContext reads the field named by the tag it is asked under;
and ChainGetters composes others to reach a nested field.
Definition
FieldGetter<Context, Tag> mirrors HasField, with the context as an explicit
type argument instead of &self:
pub trait FieldGetter<Context, Tag> {
type Value;
fn get_field(context: &Context, _tag: PhantomData<Tag>) -> &Self::Value;
}
Self is the provider, a marker carrying no data, and Context is the type the field is read from.
Tag is the tag the provider is asked under: through a getter component, that is the component's
own marker. Value is the field's type, and get_field returns a borrow of it. It is a plain trait
rather than a component provider trait, so its impls carry no
IsProviderFor pair.
Usage
It is not in the prelude; import it from cgp::core::field::traits. A getter component takes a
FieldGetter provider wrapped in WithProvider, most often through the WithField<Tag> alias for
WithProvider<UseField<Tag>>, which is imported from cgp::core::field::impls:
use cgp::core::field::impls::WithField;
delegate_components! {
Person {
NameGetterComponent: WithField<Symbol!("first_name")>,
}
}
The getter then reads first_name, whose name need not match the getter's method. A bare
UseField<Symbol!("first_name")> entry works as well, through a separate impl that #[cgp_getter]
emits for UseField directly, without going through FieldGetter.
Examples
One getter component answered on two contexts by two FieldGetter providers, UseField reading a
differently named field and a hand-written provider reading a nested one:
use cgp::core::component::WithProvider;
use cgp::core::field::impls::WithField;
use cgp::core::field::traits::{FieldGetter, HasField};
use cgp::prelude::*;
#[cgp_getter(NameGetter)]
pub trait HasName {
fn name(&self) -> &String;
}
#[derive(HasField)]
pub struct Person {
pub first_name: String,
}
delegate_components! {
Person {
NameGetterComponent: WithField<Symbol!("first_name")>,
}
}
pub struct Profile {
pub display_name: String,
}
#[derive(HasField)]
pub struct Account {
pub profile: Profile,
}
pub struct ReadDisplayName;
impl<Context, Tag> FieldGetter<Context, Tag> for ReadDisplayName
where
Context: HasField<Symbol!("profile"), Value = Profile>,
{
type Value = String;
fn get_field(context: &Context, _tag: PhantomData<Tag>) -> &String {
&context.get_field(PhantomData).display_name
}
}
delegate_components! {
Account {
NameGetterComponent: WithProvider<ReadDisplayName>,
}
}
check_components! {
Person {
NameGetterComponent,
}
}
check_components! {
Account {
NameGetterComponent,
}
}
pub fn demo() {
let person = Person {
first_name: "Ada".to_owned(),
};
let account = Account {
profile: Profile {
display_name: "ada99".to_owned(),
},
};
assert_eq!(person.name(), "Ada");
assert_eq!(account.name(), "ada99");
}
ReadDisplayName ignores the tag it is asked under and reads a field of a field, so it is an
ordinary impl on a marker type, with no attribute. Both contexts are
value contexts, and the getter is
self-targeted.
When to use it
Wire a FieldGetter only when a context must choose which field a getter reads, the advanced
case. The simpler forms come first:
- An
#[implicit]argument reads a field of the implementation's own context, and involves no provider. #[cgp_auto_getter]makes the read a named trait keyed by the method name, with no wiring.#[cgp_getter]makes the getter a component, whose wiring entry names theFieldGetterprovider:WithField<Tag>for a field of the context, orWithProvider<ChainGetters<…>>for a field of a nested value.
Write a provider of your own only for a read those do not cover. A nested field is usually a
ChainGetters list of UseField steps rather than a hand-written provider like the example's.
Under the hood
For a one-method getter, #[cgp_getter] emits an impl of the getter's provider trait for
WithProvider<P>, bounded on P: FieldGetter under the component's marker. cargo cgp expand on
the example shows:
impl<__Context__, __Provider__> NameGetter<__Context__> for WithProvider<__Provider__>
where
__Provider__: FieldGetter<__Context__, NameGetterComponent, Value = String>,
{
fn name(__context__: &__Context__) -> &String {
__Provider__::get_field(
__context__,
::core::marker::PhantomData::<NameGetterComponent>,
)
}
}
UseField<Tag> implements FieldGetter for every tag it is asked under, reading its own Tag
instead, which is why it serves any getter:
impl<Context, OutTag, Tag, Value> FieldGetter<Context, OutTag> for UseField<Tag>
where
Context: HasField<Tag, Value = Value>,
{
type Value = Value;
fn get_field(context: &Context, _tag: PhantomData<OutTag>) -> &Value {
context.get_field(PhantomData)
}
}
UseContext reads the tag it is asked under, so through
WithContext it needs the context to implement
HasField<NameGetterComponent>, keyed by the component rather than by a field name. The
lifetime-safe FieldMapper is a blanket impl over every FieldGetter, which
ChainGetters relies on.
Common Mistakes
A FieldGetter provider does not answer a getter on its own. Wiring
NameGetterComponent: ReadDisplayName, without WithProvider, names a provider that implements
FieldGetter but not the getter's provider trait, so the check fails on its missing marker:
error[E0277]: the trait bound `ReadDisplayName: IsProviderFor<NameGetterComponent, Account>` is not satisfied
Wrap it, as WithProvider<ReadDisplayName>.
Self is the provider, not the context. The context is the first type parameter, which is the
usual confusion when meeting any provider trait.
It is not an alternative to HasField. An implementation that needs a field
bounds its context on HasField; FieldGetter is what a context supplies through wiring.
The getter's method name and the field's name are independent once wired. That is the feature, and it means a reader cannot infer the field from the getter: the wiring line holds the answer.
Related constructs
HasField: the consumer side you bound against.MutFieldGetter: the mutable extension.FieldMapper: the lifetime-safe form, for nested access.UseFieldandWithField: the provider that reads a named field, and itsWithProvideralias.UseContext: the provider that reads the field named by its tag.ChainGetters: composes getters to reach a nested field.#[cgp_getter]: the macro whose getters take these providers.
The ideas behind it:
- Consumer and provider traits: the split this trait is the field-access instance of.
Source
traits/has_field.rs:FieldGetterand theUseContextimplimpls/use_field.rs: theUseFieldimpls
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.