Skip to main content

cgp v0.4.0

Version 0.4.0 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, makes an unmet dependency show up in compiler errors, and adds presets, contexts, and datatype-generic traits. This page lists every change a user can see and the steps that take a project there from v0.3.1.

Released on 2025-05-09.

Summary​

IsProviderFor, CanUseComponent, check_components!, and delegate_and_check_components! put a missing dependency into the compiler's error, at the price of an attribute on every provider impl. cgp_preset! groups wirings and inherits other presets, #[cgp_context] declares a context's provider, and #[derive(HasFields)] exposes a type's fields as a type-level list. The getter macros read more kinds of field, and a getter trait may be generic. The release also renames HasComponents, replaces the macro crates with cgp-macro, and lowers the minimum Rust version to 1.81.

Compatibility​

  • Minimum Rust version: 1.81, down from 1.84 (#62).
  • Released together: the workspace's 19 crates published on crates.io, all at 0.4.0.
  • New crates: cgp-macro and cgp-macro-lib, which replace cgp-component-macro, cgp-component-macro-lib, cgp-field-macro, and cgp-field-macro-lib; those four have no 0.4.0 version. See the macro crates.
  • Features: the static feature of cgp-async stays declared but gates nothing, because MaybeStatic is removed; see the Async bound.

Upgrading​

A project moving from v0.3.1 takes these steps, in this order:

  1. Change the version to cgp = "0.4.0". Rust 1.81 or newer builds it.
  2. Annotate each provider impl with #[cgp_provider] or #[cgp_new_provider], per the provider attribute.
  3. Rename HasComponents to HasCgpProvider and its Components type to CgpProvider, per the rename.
  4. Replace each cgp_type! with a #[cgp_type] trait and rename the generated provider traits and component keys, per the attribute.
  5. Add 'static where code relied on Async implying it, per the Async bound.
  6. Write symbols with symbol!, per the symbol type.
  7. Rename the items of each preset, per the preset module.
  8. Delete a hand-written UseContext impl of a component, per the generated impl.
  9. Remove each for_each_replace!, per the removal.
  10. Import macros from cgp::prelude or cgp-macro, per the macro crates.
  11. Make the error Async in a context that implements CanRun, per the CanRun bound.

Breaking changes​

Provider impls need #[cgp_provider]​

Every provider trait has the supertrait IsProviderFor<Component, Context, Params> (#63, #73), which an impl of the provider trait must satisfy. #[cgp_provider] writes that impl under the provider's own bounds.

  • Old: impl<Context> Greeter<Context> for GreetHello { … }, with no attribute.
  • New: #[cgp_provider] above the impl, which names the component as the provider trait's name followed by Component, or #[cgp_provider(GreeterComponent)] to name it. #[cgp_new_provider] also declares the provider struct from the impl's self type (#67).
  • What to do: add the attribute to each provider impl, including impls of ProvideType, ErrorRaiser, and the other provider traits. Without it, the build fails with the unsatisfied bound GreetHello: IsProviderFor<GreeterComponent, Context>.

HasComponents is renamed HasCgpProvider​

The consumer trait's blanket impl reads the context's provider from HasCgpProvider, whose associated type is CgpProvider (#69, #97).

  • Old: impl HasComponents for App { type Components = AppComponents; }.
  • New: impl HasCgpProvider for App { type CgpProvider = AppComponents; }, which #[cgp_context] writes.
  • What to do: rename the trait and its associated type, or replace the impl with #[cgp_context]. The prelude exports HasCgpProvider.

cgp_type! becomes the #[cgp_type] attribute​

#[cgp_type] goes on a trait that declares one associated type (#68). The provider trait is named after the associated type, as {Type}TypeProvider, and the component after the provider trait.

  • Old: cgp_type! { Error: Debug } generated HasErrorType, ProvideErrorType, ErrorTypeComponent, and the alias ErrorOf.
  • New: #[cgp_type] pub trait HasErrorType { type Error: Debug; } generates the same trait and alias, the provider trait ErrorTypeProvider, and the component ErrorTypeProviderComponent.
  • What to do: replace each cgp_type! call with the trait and the attribute, and rename each use of a generated name.
CrateOldNew
cgp-errorProvideErrorTypeErrorTypeProvider
cgp-errorErrorTypeComponentErrorTypeProviderComponent
cgp-runtimeProvideRuntimeTypeRuntimeTypeProvider
cgp-runtimeRuntimeTypeComponentRuntimeTypeProviderComponent

Async no longer requires 'static​

Async is MaybeSend + MaybeSync, and the trait MaybeStatic is removed (#89). An abstract type bounded by Async can now be a type that borrows.

  • Old: with the default features, Async meant Send + Sync + 'static, and the prelude exported MaybeStatic.
  • New: Async means Send + Sync, and MaybeStatic does not exist.
  • What to do: add 'static to each bound that needs it, such as a context passed to tokio::spawn, and delete imports of MaybeStatic.

symbol! builds a chain of Char types​

Char<const CHAR: char, Tail> carries the rest of the string as its second parameter, so symbol!("name") expands to one nested type (#85).

  • Old: Cons<Char<'n'>, Cons<Char<'a'>, Cons<Char<'m'>, Cons<Char<'e'>, Nil>>>>.
  • New: Char<'n', Char<'a', Char<'m', Char<'e', Nil>>>>.
  • What to do: write a field's key with symbol!. Code that spelled out the old expansion, or named Char with one parameter, changes it. The HasField impls that #[derive(HasField)] generates use the new key.

cgp_preset! expands to a module​

cgp_preset! declares a module named after the preset, in place of a struct (#72, #91). The module holds the provider struct Provider and a hidden trait IsPreset, and the trait DelegatesToMyPreset is no longer generated.

  • Old: cgp_preset! { MyPreset { … } } declared the struct MyPreset and the trait IsMyPreset, and a table wired […]: MyPreset.
  • New: MyPreset::Provider replaces the struct and MyPreset::IsPreset replaces the trait, so a table wires […]: MyPreset::Provider.
  • What to do: rename each use of the preset's struct and trait.

#[cgp_component] implements the provider trait for UseContext​

The macro writes the impl of the provider trait for UseContext, and its IsProviderFor impl, for each component (#88). See UseContext.

  • Old: a component that needed the impl had it written by hand.
  • New: the macro writes it, so a hand-written impl Greeter<Context> for UseContext conflicts with it and fails with E0119.
  • What to do: delete the hand-written impl.

for_each_replace! is removed​

for_each_replace!, which repeated a body for each type in a list, is no longer exported (#77). replace_with! remains, and nothing replaces for_each_replace!.

  • What to do: write the repeated items out.

The macro crates are replaced by cgp-macro​

cgp-macro holds every macro and derive, and cgp-macro-lib their implementation (#83). cgp::core::macros re-exports cgp-macro, and cgp::re_export_imports exports the attribute of that name.

  • Old: use cgp_component_macro::cgp_component; and use cgp_field_macro::symbol;.
  • New: the macros come from cgp::prelude, or from cgp_macro for a crate that depends on it directly.
  • What to do: write use cgp::prelude::*;. A crate that depends on the old macro crates changes its manifest to cgp-macro.

CanRun requires an Async error type​

CanRun requires HasAsyncErrorType (#90), which also requires the context's Error to be Async.

  • Old: CanRun: Async + HasErrorType, which left the error type unconstrained.
  • New: CanRun: HasAsyncErrorType.
  • What to do: make the error type Send + Sync for a context that implements or wires CanRun.

New features​

Checking wiring​

  • IsProviderFor and CanUseComponent name the missing dependency. IsProviderFor<Component, Context, Params = ()> is an empty trait that each provider trait carries as a supertrait and #[cgp_provider] implements under the provider's own where bounds. A dependency the provider needs but the context lacks then appears in the error. CanUseComponent<Component, Params = ()> holds for a context whose HasCgpProvider provider implements IsProviderFor for the component (#63, #65, #73). See IsProviderFor and CanUseComponent.
  • check_components! asserts that a context can use components. check_components! { CanUseApp for App { GreeterComponent, FooGetterComponent: [Index<0>, Index<1>] } } implements the trait CanUseApp for App once per entry, and each impl requires CanUseComponent. A component with type parameters lists them after a colon, in brackets for several, and the macro accepts impl generics and a where clause (#78). See check_components!.
  • delegate_and_check_components! wires and checks in one step. delegate_and_check_components! { CanUseApp for App; AppComponents { … } } wires the entries and checks each of them (#98). See delegate_and_check_components!.

Components, providers, and contexts​

  • #[cgp_component(Greeter)] takes only the provider name. The component is named by adding Component to it, and the context type parameter is Context (#96). See #[cgp_component].
  • A component trait may declare associated constants. A provider impl defines each one with const CONSTANT: u64 = CONSTANT; (#95).
  • #[cgp_context] declares a context. #[cgp_context] pub struct App; declares the provider struct AppComponents and implements HasCgpProvider for App. #[cgp_context(AppProvider)] names the provider struct, and #[cgp_context(AppProvider<T>)] serves a generic context (#66, #96).
  • delegate_components! declares a new struct. delegate_components! { new MyComponents { … } } declares MyComponents and wires it, new MyComponents<T> { … } takes generic parameters, and UseDelegate<new Inner { … }> declares a nested table in the same way (#93). See delegate_components!.
  • #[blanket_trait] defines a trait alias. A trait with supertraits, default methods, and associated types gets a blanket impl for every type that meets its supertraits (#79, #82). See #[blanket_trait].

Presets​

  • A preset inherits other presets. cgp_preset! { Child: ParentA + ParentB { … } } copies the parents' entries into the child, an entry marked override replaces a parent's entry for the same component, and presets may take generic parameters (#91, #92).
  • A context inherits a preset. #[cgp_context(AppComponents: MyPreset)] wires every component of the preset to MyPreset::Provider, and the context's own entries add to it (#66, #91).
  • #[cgp::re_export_imports] re-exports a module's imports. On a module, it re-exports the use items through a hidden re_exports module and the other items from the parent. A preset that inherits another can then import the parent's components (#70, #71, #72).

Getters and fields​

  • A getter trait may take generic parameters. #[cgp_auto_getter] and #[cgp_getter] traits may be generic, and a getter method may take a second PhantomData<Tag> argument that selects a field by a type parameter (#64, #76, #80, #81). See #[cgp_auto_getter] and #[cgp_getter].
  • A getter returns more than &T. A method may return &str, read from a String field; &[T], read from a Vec<T> field; Option<&T>, read from an Option<T> field; MRef<'a, T>; or an owned value, which the impl clones from the field (#81, #87). MRef is an enum of a borrowed &'a T or an owned T that dereferences to T.
  • #[cgp_getter] names its provider by convention. A trait named HasName gets the provider NameGetter and the component NameGetterComponent when the attribute names neither (#94).
  • ChainGetters and UseFieldRef read nested and referenced fields. ChainGetters<Product![UseField<symbol!("inner")>, UseField<symbol!("name")>]> reads a field through a chain of getters, and UseFieldRef<Tag, Value> reads a field through AsRef. FieldMapper and MapField carry the lifetimes the chain needs (#81, #94). See ChainGetters, UseFieldRef, FieldMapper, and MapField.

Data shapes​

  • #[derive(HasFields)] lists a type's fields. HasFields::Fields is a Cons list of Field<Tag, Value> entries for a struct's fields, and an Either list for an enum's variants. HasFieldsRef gives the borrowed form, and ToFields, FromFields, and ToFieldsRef convert a value to and from it (#84). See #[derive(HasFields)], HasFields, ToFields, and FromFields.

Improvements​

  • The type-level types are declared under Greek letters. π is Cons, ε is Nil, σ is Either, θ is Void, ω is Field, ι is Char, and δ is Index, with the English names as aliases, so existing code compiles unchanged and compiler output prints the shorter names (#85).
  • Type-level types implement more traits. A Char list implements Display and prints its text, and Cons, Nil, Either, Void, Field, and Index implement Debug, PartialEq, and Eq where their parameters do (#85, #86).
  • Core traits explain an unmet bound. DelegateComponent, IsProviderFor, HasField, and HasFieldMut carry #[diagnostic::on_unimplemented] messages, and the Deref blanket impl of HasField carries #[diagnostic::do_not_recommend] (#63, #74).
  • HasField reads through Deref without a 'static target. A context that dereferences to a struct borrowing other data can use the field traits (#94).

An AI agent wrote this page from the release's source changes and the CGP knowledge base. Its content was verified against the library's source at the release's tag. See How AI is used in this project.