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.
- Crate:
cgp0.2.0 on crates.io - Changes: v0.1.0...v0.2.0
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-stdnow usescore::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-asyncgainsasync,send,sync,static, andfull, withfullon by default.cgpandcgp-coregain a defaultfullfeature that turns oncgp-async/full; see the async feature flags.
Upgrading
A project moving from v0.1.0 takes these steps, in this order:
- Change the version to
cgp = "0.2.0"and use Rust 1.81 or newer. - Rewrite each
#[derive_component]as#[cgp_component], per the component macro. - Rename each
define_components!tocgp_preset!, per the preset macro. - Rename the associated type
HasField::FieldtoValue, per the field type. - Replace
DelegateErrorRaiserwithUseDelegate, per the error raiser. - Spell a symbol's type as a list, and import
MaybeSendwhere#[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 }]. Onlyprovideris required:namedefaults to the provider's name followed byComponent, andcontextdefaults toContext. - 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 traitIsMyPreset<Component>. The generatedwith_my_preset!macro now expands throughreplace_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 inHasField<Tag, Field = String>. - New:
type Value, as inHasField<Tag, Value = String>. - What to do: rename each
Field =bound and eachSelf::Fieldpath.#[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>>>>forsymbol!("name"). - What to do: write a field's key with
symbol!rather than spelling out the expansion. TheHasFieldimpls 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>, withUseDelegateimported fromcgp::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, whichuse cgp::prelude::*;imports. - What to do: write
use cgp::prelude::*;in each module that uses#[async_trait].
New features
Components and wiring
UseContext,WithProvider, andWithContextturn existing impls into providers.UseContextis a provider that answersProvideTypeandFieldGetterthrough the context's ownHasTypeandHasField.WithProvider<Provider>adapts a provider of a general trait into the provider of a named component, as it does forProvideErrorType, andWithContextisWithProvider<UseContext>(#23, #24). SeeUseContext,WithProvider, andWithContext.UseDelegatedispatches a provider trait through a table. It implementsErrorRaiserby looking the source error type up in its table, andProvideTypeby looking the tag up (#24).replace_with!andfor_each_replace!rewrite a body with a list of types.replace_with!replaces an identifier in a body with a bracketed list of types, andfor_each_replace!repeats a body once for each type in a list (#41).
Abstract types
- The
cgp-typecrate addsHasType<Tag>. The component isTypeComponent, with the provider traitProvideType, andcgp::core::typesre-exports the crate.UseType<Type>fixes the type,UseDelegatedType<Components>looks the type up in a table by the tag, andWithTypeandWithDelegatedTypeadapt them to a named component (#23, #24). SeeHasType,UseType, andUseDelegatedType. HasErrorTypeaccepts aProvideTypeprovider.WithProvider<Provider>implementsProvideErrorTypewhenProviderprovides the error type throughProvideType, as inWithProvider<UseType<MyError>>(#23).
Type-level data and fields
Cons,Nil,Either, andVoidbuild lists and sums at the type level.Cons<Head, Tail>andNilform a product list, andEither<Head, Tail>and the emptyVoidform a sum.Field<Tag, Value>pairs a value with its name tag, andIndex<I>is a type-level number (#36). SeeCons,Either, andField.Product!,product!, andSum!write those types.Product![A, B]is the product type,product![a, b]builds a value of it, andSum![A, B]is the sum type (#36). SeeProduct!andSum!.HasFieldMutreads a field mutably.HasFieldMut<Tag>returns&mut Self::Value, and#[derive(HasField)]implements it besideHasField(#23). SeeHasFieldMut.FieldGetterandMutFieldGetterare the provider traits of field access.UseField<Tag>implements them, andProvideType, by reading the field named byTag, andWithField<Tag>adapts it to a named component (#23, #24). SeeFieldGetterandUseField.
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, andMaybeStaticstand forSend,Sync, and'staticwhen their feature is on, and for an empty trait when it is off.Asyncis nowMaybeSend + MaybeSync + MaybeStatic.#[async_trait]stripsasyncand.awaitfrom a trait when theasyncfeature is off, so the code compiles as synchronous code.- Turning the flags off takes
default-features = falseoncgp, becausecgpandcgp-coredepend oncgp-asyncwithout its default features and forward their own defaultfullfeature.
Improvements
Asyncno longer requiresSized, so adyntrait can use it as a bound (#34).HasInnerandProvideEyreErrorask less of their types.HasInnerand itsInnertype no longer requireAsync, andProvideEyreErrorno longer requires the context to beAsync(#23).cgp-error-stdbuilds withoutstd. It isno_stdwithalloc, since it usescore::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.