Skip to main content

cgp v0.2.0

Version 0.2.0 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, renames its component macro and adds type-level lists and sums. This page lists every change a user can see and the steps that take a project there from v0.1.0.

Released on 2024-12-08.

Summary​

#[cgp_component] replaces #[derive_component] with named arguments, and cgp_preset! replaces define_components!. The Cons, Nil, Either, and Void types with the Product! and Sum! macros give CGP type-level lists and sums, and symbol! now builds such a list. The new cgp-type crate adds HasType, and cgp-async gains feature flags that can compile async code away.

Compatibility​

  • Minimum Rust version: 1.81, up from 1.79. cgp-error-std now uses core::error::Error, which Rust stabilized in 1.81.
  • Released together: the workspace's 18 crates, all at 0.2.0.
  • New crates: cgp-type.
  • Features: cgp-async gains async, send, sync, static, and full, with full on by default. cgp and cgp-core gain a default full feature that turns on cgp-async/full; see the async feature flags.

Upgrading​

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

  1. Change the version to cgp = "0.2.0" and use Rust 1.81 or newer.
  2. Rewrite each #[derive_component] as #[cgp_component], per the component macro.
  3. Rename each define_components! to cgp_preset!, per the preset macro.
  4. Rename the associated type HasField::Field to Value, per the field type.
  5. Replace DelegateErrorRaiser with UseDelegate, per the error raiser.
  6. Spell a symbol's type as a list, and import MaybeSend where #[async_trait] is used without the prelude, per the symbol type and #[async_trait].

Breaking changes​

#[cgp_component] replaces #[derive_component]​

#[cgp_component] takes the component's names as key: value entries (#38), and the prelude no longer exports derive_component.

  • Old: #[derive_component(NameGetterComponent, NameGetter<MyContext>)].
  • New: #[cgp_component { name: NameGetterComponent, context: MyContext, provider: NameGetter }]. Only provider is required: name defaults to the provider's name followed by Component, and context defaults to Context.
  • What to do: rewrite each attribute. A global search and replace does it for the common form: search for #\[derive_component\(([\w<>, ]+), (\w+)<(\w+)>\)\] and replace with #[cgp_component {\n name: $1,\n provider: $2,\n context: $3,\n}].

cgp_preset! replaces define_components!​

cgp_preset! takes the entries that define_components! took (#41). The prelude no longer exports define_components.

  • Old: define_components! { MyPreset { ... } }.
  • New: cgp_preset! { MyPreset { ... } }, which also generates a marker trait IsMyPreset<Component>. The generated with_my_preset! macro now expands through replace_with!, which the prelude exports.
  • What to do: rename each use.

HasField::Field is renamed HasField::Value​

The associated type of HasField is Value (#35), and the new FieldGetter trait uses the same name.

  • Old: type Field, as in HasField<Tag, Field = String>.
  • New: type Value, as in HasField<Tag, Value = String>.
  • What to do: rename each Field = bound and each Self::Field path. #[derive(HasField)] generates the new name.

symbol! builds a Cons list​

symbol!("name") expands to a list of Char types built from Cons and Nil (#36).

  • Old: the expansion was the Char<'c'> types of the characters, separated by commas inside parentheses.
  • New: Cons<Char<'n'>, Cons<Char<'a'>, Cons<Char<'m'>, Cons<Char<'e'>, Nil>>>> for symbol!("name").
  • What to do: write a field's key with symbol! rather than spelling out the expansion. The HasField impls that #[derive(HasField)] generates use the new key.

UseDelegate replaces DelegateErrorRaiser​

UseDelegate<Components> implements ErrorRaiser by looking the source error type up in Components, and cgp-error no longer exports DelegateErrorRaiser (#23, #24). See UseDelegate.

  • Old: ErrorRaiserComponent: DelegateErrorRaiser<MyRaisers>.
  • New: ErrorRaiserComponent: UseDelegate<MyRaisers>, with UseDelegate imported from cgp::core::component.
  • What to do: rename each use and add the import.

#[async_trait] expands through MaybeSend​

#[async_trait] rewrites each async fn of a trait to return impl Future<Output = T> + MaybeSend (#37), so MaybeSend must be in scope where the attribute is used.

  • Old: the return type named Send, which every module has.
  • New: the return type names MaybeSend, which use cgp::prelude::*; imports.
  • What to do: write use cgp::prelude::*; in each module that uses #[async_trait].

New features​

Components and wiring​

  • UseContext, WithProvider, and WithContext turn existing impls into providers. UseContext is a provider that answers ProvideType and FieldGetter through the context's own HasType and HasField. WithProvider<Provider> adapts a provider of a general trait into the provider of a named component, as it does for ProvideErrorType, and WithContext is WithProvider<UseContext> (#23, #24). See UseContext, WithProvider, and WithContext.
  • UseDelegate dispatches a provider trait through a table. It implements ErrorRaiser by looking the source error type up in its table, and ProvideType by looking the tag up (#24).
  • replace_with! and for_each_replace! rewrite a body with a list of types. replace_with! replaces an identifier in a body with a bracketed list of types, and for_each_replace! repeats a body once for each type in a list (#41).

Abstract types​

  • The cgp-type crate adds HasType<Tag>. The component is TypeComponent, with the provider trait ProvideType, and cgp::core::types re-exports the crate. UseType<Type> fixes the type, UseDelegatedType<Components> looks the type up in a table by the tag, and WithType and WithDelegatedType adapt them to a named component (#23, #24). See HasType, UseType, and UseDelegatedType.
  • HasErrorType accepts a ProvideType provider. WithProvider<Provider> implements ProvideErrorType when Provider provides the error type through ProvideType, as in WithProvider<UseType<MyError>> (#23).

Type-level data and fields​

  • Cons, Nil, Either, and Void build lists and sums at the type level. Cons<Head, Tail> and Nil form a product list, and Either<Head, Tail> and the empty Void form a sum. Field<Tag, Value> pairs a value with its name tag, and Index<I> is a type-level number (#36). See Cons, Either, and Field.
  • Product!, product!, and Sum! write those types. Product![A, B] is the product type, product![a, b] builds a value of it, and Sum![A, B] is the sum type (#36). See Product! and Sum!.
  • HasFieldMut reads a field mutably. HasFieldMut<Tag> returns &mut Self::Value, and #[derive(HasField)] implements it beside HasField (#23). See HasFieldMut.
  • FieldGetter and MutFieldGetter are the provider traits of field access. UseField<Tag> implements them, and ProvideType, by reading the field named by Tag, and WithField<Tag> adapts it to a named component (#23, #24). See FieldGetter and UseField.

Async code compiles away through feature flags​

cgp-async has the features async, send, sync, and static, and full turns on all four (#37).

  • MaybeSend, MaybeSync, and MaybeStatic stand for Send, Sync, and 'static when their feature is on, and for an empty trait when it is off. Async is now MaybeSend + MaybeSync + MaybeStatic.
  • #[async_trait] strips async and .await from a trait when the async feature is off, so the code compiles as synchronous code.
  • Turning the flags off takes default-features = false on cgp, because cgp and cgp-core depend on cgp-async without its default features and forward their own default full feature.

Improvements​

  • Async no longer requires Sized, so a dyn trait can use it as a bound (#34).
  • HasInner and ProvideEyreError ask less of their types. HasInner and its Inner type no longer require Async, and ProvideEyreError no longer requires the context to be Async (#23).
  • cgp-error-std builds without std. It is no_std with alloc, since it uses core::error::Error (#23).

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.