Skip to main content

#[use_type]

Import an abstract associated type and write it as a bare name.

Overview​

In Context-Generic Programming (CGP), #[use_type] imports a type from the context, the type the code runs against. In CGP a type supplied this way is called an abstract type: the code names it, and the context chooses what it actually is, at compile time, through its delegate_components! wiring.

The type most often imported this way is a context's error type. One attribute lets a fallible signature name it as a bare Error:

#[use_type(HasErrorType.Error)]

A method can then return Result<String, Error>, and that method compiles unchanged whether the context chose anyhow::Error, Box<dyn core::error::Error>, or a plain String as its error type. The method never names any of those. The context names one, in its wiring.

#[use_type] reads like a use statement for a type, and Under the hood shows how the bare name resolves. It also has advanced forms that a bare identifier could not express, covered below: pinning the type to a concrete one, importing it from a parameter rather than the context, and tying two abstract types together.

Usage​

Apply #[use_type] beside the macro it modifies, naming a trait and the associated type to import:

#[use_type(HasScalarType.Scalar)]

The part before the . is the trait and the identifier after it is the type. The separator is a dot, not ::, and that is deliberate. It leaves :: free for the trait's own path, so #[use_type(errors::HasErrorType.Error)] imports from a trait named by path and #[use_type(HasFooType<X>.Foo)] imports from a particular generic instantiation.

By default the macro projects the type from Self, so Scalar expands to <Self as HasScalarType>::Scalar.

The attribute is accepted on #[cgp_fn], #[cgp_impl], #[cgp_component], and the macros built on #[cgp_component]: #[cgp_type], #[cgp_getter], and #[cgp_auto_getter].

Importing several types​

Separate entries with commas, and prefer one attribute carrying the whole list, because it reads as a single import list:

#[use_type(HasUserIdType.UserId, HasCurrencyType.Currency, HasErrorType.Error)]

Several types from the same trait go in a braced group, and any entry may be renamed with as to give it a local alias:

#[use_type(HasFooType.{Foo, Bar as Baz})]

Renaming is also how one associated type is imported from two instantiations of a generic trait, since the two imports would otherwise share a name:

#[use_type(HasFooType<X>.{Foo as FooX}, HasFooType<Y>.{Foo as FooY})]

An empty group, as in #[use_type(HasFooType.{})], parses too. It imports no name but still adds the trait's bound.

Stacking several #[use_type] attributes behaves identically, because the macro collects every attribute's entries into one list before it resolves any of them. So an alias declared in one is available to another regardless of which comes first. Use a second attribute only when there is a reason.

Pinning a type to a concrete one​

An = Type clause imports the type and constrains it. A provider uses it to say "this only works when the error type is anyhow::Error":

#[use_type(HasErrorType.{Error = anyhow::Error})]

That emits Self: HasErrorType<Error = anyhow::Error> in place of the plain bound. On a generic trait the binding joins the trait's own arguments, so #[use_type(HasFooType<u8>.{Foo = u32})] emits Self: HasFooType<u8, Foo = u32>. The binding always names the associated type's own name, even when the import renames it with as.

The macro substitutes the right-hand side too, so it may name another import, alone or inside a larger type. One import can therefore tie two abstract types together:

#[use_type(HasPasswordType.Password, HasHashedPasswordType.{HashedPassword = Password})]

An alias nested inside the right-hand side is grounded in place, so #[use_type(HasDbType.Db, HasTransactionType.{Transaction = Tx<Db>})] emits Self: HasTransactionType<Transaction = Tx<<Self as HasDbType>::Db>>. The one name the macro leaves alone on the right-hand side is the pinned alias itself, so a pin such as {Foo = Foo} fails with cannot find type `Foo` in this scope rather than becoming a bound that says nothing.

The pin is an implementation-side constraint, so the macro rejects it on #[cgp_component] and on the macros built on it, whose trait definitions have nowhere to put it.

Importing from another type​

A trailing in Context clause changes what the type is projected from, so an import can reach a type on a parameter rather than on Self:

#[use_type(HasScalarType.Scalar in Types)]

Scalar now expands to <Types as HasScalarType>::Scalar. The clause scopes over the whole entry, so a braced group projects every type in it against the same target. And because in is a reserved word, the parser can never mistake it for a type name.

This form also lets an import parameterize the trait it comes from. An alias may appear in another entry's in clause or in its trait arguments, and the macro resolves the chain for you:

#[use_type(HasDbType.Db, HasPoolType<Db>.Pool)]

Here Pool is projected from HasPoolType<<Self as HasDbType>::Db>. Such chains may be written in any order (see Under the hood), provided they do not form a cycle.

Examples​

One abstract scalar shared by a component and a provider, with neither writing Self:: anywhere:

use cgp::prelude::*;
use core::ops::Mul;

#[cgp_type]
pub trait HasScalarType {
type Scalar: Clone + Mul<Output = Self::Scalar>;
}

#[cgp_component(AreaCalculator)]
#[use_type(HasScalarType.Scalar)]
pub trait CanCalculateArea {
fn area(&self) -> Scalar;
}

#[cgp_impl(new RectangleArea)]
#[use_type(HasScalarType.Scalar)]
impl AreaCalculator {
fn area(&self, #[implicit] width: Scalar, #[implicit] height: Scalar) -> Scalar {
width * height
}
}

The component gains HasScalarType as a supertrait, and the provider gains it as a bound. Every Scalar in both becomes the same qualified projection, so the fields the provider reads and the value it returns are guaranteed to agree on whatever scalar the context chose.

A context supplies the concrete type by wiring, and nothing above changes. Rectangle is a value context, the shape whose area is being computed:

#[derive(HasField)]
pub struct Rectangle {
pub width: f64,
pub height: f64,
}

delegate_components! {
Rectangle {
ScalarTypeProviderComponent: UseType<f64>,
AreaCalculatorComponent: RectangleArea,
}
}

check_components! {
Rectangle {
AreaCalculatorComponent,
}
}

The most common use of all is an error type, where the import saves a projection in every fallible signature:

#[cgp_component(Loader)]
#[use_type(HasErrorType.Error)]
pub trait CanLoad {
fn load(&self, path: &str) -> Result<String, Error>;
}

The error type is one of three decisions a context makes about failure, and modular error handling separates them.

When to use it​

Use #[use_type] whenever a definition names an abstract type another component supplies. You read a hand-written supertrait plus Self::-qualified paths in existing code rather than write them.

Its neighbours handle the requirements that are not types, and one of them declares the type this attribute imports.

  • A trait on the context is #[uses] for a private bound or #[extend] for a supertrait. Use #[extend] specifically when the supertrait's methods matter and its associated types are not named in your signatures, the case where #[use_type] has nothing to rewrite.
  • A value from a field is an #[implicit] argument.
  • The type itself is declared with #[cgp_type] and bound to a concrete type by wiring the component to UseType<T>. The UseType provider and this attribute are two different things despite the shared name: the provider supplies a type to a context, and the attribute imports one into a definition.

#[use_type] does not import a construct's own associated type, so it stays qualified as Self::Output. This rule is worth stating plainly, because breaking it produces a confusing error. The attribute rewrites only the names it was given, so a local type written bare resolves to nothing. A mixed signature such as Result<Self::Output, Error> is therefore correct and idiomatic: the local type qualified, the imported one bare.

Prefer an inferred parameter over an abstract type when the type only ever flows through values the body reads: #[impl_generics] on a #[cgp_fn] is shorter and does not need wiring. Move to an abstract type when the type must be named in the trait's own signature, or when two traits have to agree that they mean the same one.

Under the hood​

#[use_type] runs before the surrounding macro: it grounds each import's own type positions, substitutes every matching bare identifier, then adds the bound.

From this input:

#[cgp_fn]
#[use_type(HasScalarType.Scalar)]
pub fn area(&self, #[implicit] width: Scalar, #[implicit] height: Scalar) -> Scalar {
width * height
}

the effective result is:

pub trait Area: HasScalarType {
fn area(&self) -> <Self as HasScalarType>::Scalar;
}

impl<__Context__> Area for __Context__
where
Self: HasField<Symbol!("width"), Value = <Self as HasScalarType>::Scalar>
+ HasField<Symbol!("height"), Value = <Self as HasScalarType>::Scalar>,
Self: HasScalarType,
{
fn area(&self) -> <Self as HasScalarType>::Scalar { /* ... */ }
}

Where the bound lands depends on the target. When the type is projected from Self it becomes a supertrait of the generated trait, and also a where bound on the implementation. When an in Context clause names some other type, a supertrait of Self would be wrong, so the macro adds a plain Context: Trait predicate. That predicate goes on the implementation. On #[cgp_fn] and #[cgp_component] it goes on the generated trait's own where clause as well, because the trait's signatures now mention the projection and would not otherwise be well-formed. A plain unbounded <Types> on your function is therefore enough:

pub trait AreaOf<Types>
where
Types: HasScalarType,
{
fn area_of(&self) -> <Types as HasScalarType>::Scalar;
}

An equality pin is the exception: it stays on the implementation, and the macro never adds it to the trait.

What substitution touches. The rewrite matches a single-segment type path with no arguments whose identifier is an imported name or alias, anywhere it appears: a return type, an argument, a where predicate, a local binding, and the provider trait's arguments in a #[cgp_impl] header, so impl ErrorParser<Error> under #[use_type(HasErrorType.Error)] implements the provider trait for the context's error type. It also reaches an alias used to qualify a path, so Transaction::begin() becomes <<Self as HasTransactionType>::Transaction>::begin(), because <Self as Trait>::Assoc::method is not valid syntax.

The rewrite leaves one position alone: a bare alias in expression position, which names a value, something an abstract type can never be. So an alias sharing its name with a unit struct still constructs the struct:

let value = Marker; // stays the unit struct `Marker`
let typed: Marker = todo!(); // becomes <Self as HasMarkerType>::Marker

Grounding, and why order does not matter. The macro resolves each import against the imports it depends on rather than the ones written before it, so every arrangement of the same entries produces the same substitutions and the same bounds. Only the order the bounds are listed in follows the source. A chain like #[use_type(HasC<B>.C in B, HasB<A>.B in A, HasA.A)] grounds exactly as its front-to-back spelling does, and two imports may share one target as readily as chain through it. A cycle is the only arrangement without a valid order. See Common Mistakes.

Formal grammar​

The tokens inside #[use_type(...)], in the Rust Reference's notation:

UseTypeArgs -> UseTypeSpec ( `,` UseTypeSpec )* `,`?

UseTypeSpec -> TraitPath `.` TypeItems ( `in` ContextPath )?

ContextPath -> TypePath
TraitPath -> TypePath

TypeItems -> UseTypeIdent
| `{` ( UseTypeIdent ( `,` UseTypeIdent )* `,`? )? `}`

UseTypeIdent -> IDENTIFIER ( `as` IDENTIFIER )? ( `=` Type )?

TraitPath and ContextPath are ordinary Rust TypePaths, whose final segment may carry generic arguments. Their :: segments belong to the path, while the . after the trait begins the associated-type list. An omitted in ContextPath defaults the target to Self. In each UseTypeIdent the leading IDENTIFIER is the associated type's own name, as gives it a local alias to write in signatures, and = Type pins it with an equality bound. The pin is accepted on #[cgp_fn] and #[cgp_impl] and rejected on #[cgp_component] and the macros built on it. An empty braced list imports no name and adds only the trait's bound.

Common Mistakes​

Two imports may not share a name or alias. The substitution could only pick one, so the macro rejects a collision rather than resolving it:

#[use_type(HasFooType.Foo, HasBarType.Bar as Foo)]
error: Multiple abstract types cannot share the same identifier or alias

Imports may not resolve through one another in a cycle. An in clause or a trait argument may name another import only if the resulting chain is acyclic, and the message names the loop:

#[use_type(HasAType.A in B, HasBType.B in A)]
error: cannot ground `#[use_type]` imports: they resolve through one another in a cycle `B` -> `A` -> `B`.
An `in Context` clause or a trait argument may name another import's alias only if the resulting chain is
acyclic, since a cycle has no valid grounding order.

A self-referential import such as #[use_type(HasAType.A in A)] is the degenerate case and reports the same way.

An equality pin is rejected on a component trait, because a trait definition cannot carry an implementation-side constraint:

#[cgp_component(Loader)]
#[use_type(HasErrorType.{Error = anyhow::Error})]
pub trait CanLoad {
fn load(&self, path: &str) -> Result<String, Error>;
}
error: Type equality constraints cannot be used in component trait definition

Pin the type on the provider with #[cgp_impl] instead, or on a #[cgp_fn].

A construct's own associated type must stay qualified. Writing a local type Output as a bare Output leaves an identifier that the substitution has no entry for, so the compiler cannot resolve it:

#[cgp_component(Maker)]
pub trait CanMake {
type Output;
fn make(&self) -> Output;
}
error[E0425]: cannot find type `Output` in this scope

Write Self::Output, and do not list it in a #[use_type] attribute.

A misspelled associated type is reported where you wrote it. The macro keeps your identifier's position when it substitutes, so #[use_type(HasErrorType.Eror)] fails with error[E0576]: cannot find associated type `Eror` in trait `HasErrorType` pointing at each use of Eror in the signature.

An alias cannot stand for the trait an import comes from. The macro grounds an import's in clause and trait arguments, but not the trait's own name, because that position must name a trait and an alias names a type. So #[use_type(HasFooType.Foo, Foo.Bar)] fails with error[E0405]: cannot find trait `Foo` in this scope.

Two pins that name each other overflow the compiler. This import grounds without trouble, since it asserts only that the two types are equal:

#[use_type(HasFooType.{Foo = Bar}, HasBarType.{Bar = Foo})]

The macro therefore emits both bounds, and the trait solver cannot discharge them:

error[E0275]: overflow evaluating the requirement `<__Context__ as HasFooType>::Foo == _`

Pin one of the two types to a concrete type, or pin only one of them to the other.

  • #[cgp_type] — declares the abstract-type component this imports from.
  • UseType — the provider a context wires to supply the concrete type; a different thing from this attribute despite the name.
  • HasType — the built-in abstract-type component underneath.
  • #[uses] — imports a trait rather than a type.
  • #[extend] — adds a supertrait without rewriting any type names.
  • #[implicit] — imports a value from a field.
  • #[cgp_fn], #[cgp_impl], and #[cgp_component] — the hosts, together with the macros built on #[cgp_component].

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.