UseField
Implement a getter component by reading a context field named by a tag, so the field name is a wiring decision rather than the method name.
Overview
Under Context-Generic Programming (CGP), a getter's field is a wiring choice, and
UseField<Tag> decouples the method name from the field it reads. A getter component defined with
#[cgp_getter] describes a value the context can supply, such as
fn name(&self) -> &str. The context is the type the method
runs on, which supplies the values it needs as its fields. But the context may store the value under
a different field name, say first_name, and different contexts may store it under different names.
UseField<Tag> carries the field name as its type parameter, so wiring a getter to
UseField<Symbol!("first_name")> makes it read first_name even though the method is name. The
field name lives in the wiring, not in the trait.
This is the provider that #[cgp_getter] targets. That macro generates a
UseField implementation for the getter's provider trait with the field tag left as a free parameter,
so a context picks the field by writing UseField<Symbol!("...")> in its wiring table. UseField
itself is the general provider underneath: it works for any tag the context's
HasField implementation supports.
The Tag is usually a type-level string built with Symbol!, such as
Symbol!("name"), or a type-level integer wrapped in Index<N> for a tuple field. These are the tags
that #[derive(HasField)] produces HasField implementations for.
Like every CGP provider, UseField<Tag> carries no runtime value: it is a PhantomData marker named
in wiring, never constructed.
Usage
UseField is not in the prelude, so import it from cgp::core::field::impls to name it. It takes
one type parameter, the field tag, and appears as the value of a getter component's wiring entry:
delegate_components! {
Person {
NameGetterComponent: UseField<Symbol!("first_name")>,
}
}
The tag is a Symbol! for a named field or an Index<N> for a tuple field.
The context must have a HasField implementation for that tag, which
#[derive(HasField)] supplies for every field of a struct.
UseField<Tag> also has an alias, WithField<Tag>, which is
WithProvider<UseField<Tag>>. Both bind the same field; prefer the plain
UseField<Tag> form.
Examples
The defining use wires a getter to a field whose name differs from the method, which is the case the
simpler #[cgp_auto_getter] cannot express. The method is name, but
the context stores the value in first_name:
use cgp::core::field::impls::UseField;
use cgp::prelude::*;
#[cgp_getter]
pub trait HasName {
fn name(&self) -> &str;
}
#[derive(HasField)]
pub struct Person {
pub first_name: String,
}
delegate_components! {
Person {
NameGetterComponent: UseField<Symbol!("first_name")>,
}
}
check_components! {
Person {
NameGetterComponent,
}
}
pub fn demo() {
let person = Person { first_name: "Alice".to_owned() };
assert_eq!(person.name(), "Alice"); // reads the first_name field
}
Person is a value context: the getter reads its own
data. It wires NameGetterComponent to UseField<Symbol!("first_name")>, so person.name() reads
the first_name field. The method name and the field name diverge, and the field name comes
entirely from the wiring.
The same binding can be written with the WithField alias, which routes through
WithProvider.
When to use it
Reach for UseField only when the field name must differ from the method name, or when a context
needs full control over which field a getter reads from. That is the advanced case
#[cgp_getter] exists for, and UseField is the provider it is wired to.
For the common case of reading a field, prefer an #[implicit] argument
instead, which reads a same-named field and looks like an ordinary function parameter with no getter
trait at all. Where a getter trait is genuinely needed but the field name matches the method name, use
#[cgp_auto_getter], or wire UseFields, which keys
each method on its own name. The #[cgp_getter] page works the choice
through in full.
UseField already handles the common borrowed-view getters: a -> &str getter over a String
field and a -> &[u8] getter over a Vec<u8> field work through UseField, because the generated
implementation borrows the field through AsRef::as_ref to match the return type. Two neighbours
cover the cases it does not. When a getter returns &T and the field is stored as a different type
that borrows to T through AsRef, use UseFieldRef. When the field lives
several hops inside a nested context, use ChainGetters.
Under the hood
UseField<Tag> is implemented in four places, each forwarding to the context's
HasField implementation for Tag.
The getter component's own provider trait. For a single-method getter,
#[cgp_getter] generates a UseField implementation with the field tag
left free, and this is the implementation a direct UseField<Symbol!("...")> wiring uses. For the
HasName getter above, cargo cgp expand shows:
impl<__Context__, __Tag__> NameGetter<__Context__> for UseField<__Tag__>
where
__Context__: HasField<__Tag__, Value = String>,
{
fn name(__context__: &__Context__) -> &str {
::core::convert::AsRef::as_ref(
HasField::get_field(__context__, ::core::marker::PhantomData::<__Tag__>),
)
}
}
impl<__Context__, __Tag__> IsProviderFor<NameGetterComponent, __Context__, ()>
for UseField<__Tag__>
where
__Context__: HasField<__Tag__, Value = String>,
{}
The &str return reads a String field and wraps the read in AsRef::as_ref, the getter macros'
return-type shorthand. The paired IsProviderFor
implementation carries the same HasField bound, so a check names a missing field precisely. A
getter with more than one method gets no UseField implementation, since one tag cannot name
several fields; Common Mistakes shows the error.
The foundational field getters. UseField<Tag> implements
FieldGetter, which reads the field by reference:
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)
}
}
Two tags appear for a reason. OutTag is the tag the component asks under, the getter's own
marker, while Tag is the field tag the provider was parameterized with. The implementation
ignores OutTag and reads Tag from the context, which is the decoupling: the component's identity
and the field name are independent. The mutable getter
MutFieldGetter is implemented the same way, requiring
Context: HasFieldMut<Tag> and returning &mut Value. These are plain traits rather than
components, so the implementations carry no IsProviderFor pair; a getter component reaches them
through WithField<Tag>, whose WithProvider wrapper does.
TypeProvider. UseField<Tag> reports the field's Value type as
an abstract type, with a matching IsProviderFor
implementation, so the type of a field can be wired as a context's abstract type. The built-in
TypeProviderComponent takes UseField<Symbol!("width")> directly, while a
#[cgp_type] component takes it as WithField<Symbol!("width")>, because
the macro generates UseType and WithProvider implementations but no UseField one.
The handler family. Computer and AsyncComputer are implemented for UseField<Tag> by
forwarding the computation to the value stored in the field, which must itself implement the
consumer trait; see Computer.
Common Mistakes
A getter with more than one method cannot be wired to UseField. #[cgp_getter] generates the
UseField implementation only for a single-method getter, so wiring a two-method HasFooBar getter
to UseField<Symbol!("foo")> fails at the check:
error[E0277]: the trait bound `UseField<cgp::macro_prelude::Symbol<3, cgp::macro_prelude::Chars<'f', cgp::macro_prelude::Chars<'o', cgp::macro_prelude::Chars<'o', Nil>>>>>: IsProviderFor<FooBarGetterComponent, App>` is not satisfied
Wire such a getter to UseFields when each method reads a same-named field, or split
it into single-method getters when the field names differ.
Related constructs
#[cgp_getter]— the macro that generates aUseFieldimplementation for a getter and makes the field a wiring decision.UseFields— the sibling that keys every method on its own name, with no tag.UseFieldRef— the foundational getter for a stored type that borrows to a different return type throughAsRef.ChainGetters— reaches a field on a nested context by composing getters.WithField— theWithProvider-adapted alias that binds the same field.WithProvider— the adapter behind theWithFieldalias.UseType— the abstract-type analogue for a#[cgp_type]component.HasFieldand#[derive(HasField)]— the consumer-side field access this reads, keyed bySymbol!orIndex<N>.delegate_components!— wires it, andcheck_components!verifies the field is present.
The ideas behind it:
- Impl-side dependencies — value injection through a provider's own requirements, of which reading a field is the most common form.
Source
- Struct,
WithFieldalias, and theFieldGetter/MutFieldGetter/TypeProviderimpls:use_field.rs - The traits it implements:
cgp-field/src/traits/ - The
#[cgp_getter]-generatedUseFieldimpl:cgp_getter/use_field.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.