cgp v0.3.0
Version 0.3.0 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, adds getter macros, one-line abstract-type declarations, and error wrapping. This page lists every change a user can see and the steps that take a project there from v0.2.0.
Released on 2025-01-08.
- Release post: CGP Updates: v0.3.0 Release and New Chapters
- Crate:
cgp0.3.0 on crates.io - Changes: v0.2.0...v0.3.0
Summary
#[cgp_getter] and #[cgp_auto_getter] define getter traits that read a context's fields, and cgp_type! declares an abstract type in one line. CanWrapError adds detail to an error, the new cgp-error-extra crate holds generic error providers, and cgp-error-anyhow and cgp-runtime are new crates. The release also reorganizes the crates: macros and modules are no longer re-exported through the library crates, and the eyre and standard-library error providers have new names.
Compatibility
- Minimum Rust version: 1.83, up from 1.81.
- Released together: the workspace's 21 crates, all at 0.3.0.
- New crates:
cgp-error-extra,cgp-error-anyhow, andcgp-runtime. - Features:
cgp-error-extrahas anallocfeature, on by default, that providesDebugErrorandDisplayError.cgp-extrahas a defaultfullfeature that turns it on, and thefullfeature ofcgpnow forwards tocgp-coreandcgp-extra.
Upgrading
A project moving from v0.2.0 takes these steps, in this order:
- Change the version to
cgp = "0.3.0"and use Rust 1.83 or newer. - Import macros and items from the prelude or a crate's root, per the macro re-exports and the module paths.
- Rename the error providers of
cgp-error-eyreandcgp-error-std, per the renames. - Move
cgp::core::innertocgp::extra::inner, per thecgp-innermove. - Require
HasAsyncErrorTypewhere code needs aSend + Sync + 'staticerror, per the error bound. - Install an eyre hook in an application that builds
eyrereports, per the eyre features.
Breaking changes
cgp-component and cgp-field no longer export their macros
The macro crates are no longer dependencies of the library crates they generate code for (#47). The prelude exports the macros from their own crates.
- Old:
use cgp_component::{cgp_component, delegate_components};anduse cgp_field::{symbol, HasField};imported the macros and the derive. - New: the macros come from
cgp::prelude, or fromcgp-component-macroandcgp-field-macrofor a crate that depends on them directly. - What to do: write
use cgp::prelude::*;. A crate that imports throughcgp-componentorcgp-fieldadds the macro crate or switches to the prelude.
Crate modules are private
The crates keep their submodules private and export each item by name (#53).
- Old: an import could name a module path, such as
cgp_field::types::Charorcgp_type::traits::has_type::ProvideType. - New: each item is imported from its crate's root, such as
cgp_field::Charandcgp_type::ProvideType. Thecgp::coreandcgp::extramodules stay as they were, apart from the move below. - What to do: shorten each deep import to the crate root, or import from the prelude.
cgp-inner moves to cgp-extra
cgp::core no longer re-exports cgp-inner, and cgp::extra re-exports it along with cgp-runtime (#51).
- Old:
cgp::core::inner. - New:
cgp::extra::inner, with the new runtime crate atcgp::extra::runtime. - What to do: change the path.
HasErrorType::Error no longer requires Async
The associated Error type of HasErrorType requires only Debug (#48).
- Old:
type Error: Async + Debug, so with the default features every context's error wasSend + Sync + 'static. - New:
type Error: Debug. The new traitHasAsyncErrorTypeisAsync + HasErrorType<Error: Async>. - What to do: where code relies on the error being
Send + Sync + 'static, addHasAsyncErrorTypeto its bounds.
The eyre and std error providers are renamed
The providers of cgp-error-eyre and cgp-error-std have new names, and cgp-error-std splits one provider in two (#48).
| Crate | Old | New |
|---|---|---|
cgp-error-eyre | ProvideEyreError | UseEyreError |
cgp-error-eyre | RaiseStdError | RaiseEyreError |
cgp-error-eyre | RaiseDebugError | DebugEyreError |
cgp-error-eyre | RaiseDisplayError | DisplayEyreError |
cgp-error-std | HandleErrorsWithStdError | UseBoxedStdError for the error type, RaiseBoxedStdError for raising |
- What to do: rename each use in the wiring. A context that wired
HandleErrorsWithStdErrorfor both the error type and the raiser wires the two new providers.
cgp-error-eyre builds eyre without its default features
cgp-error-eyre depends on eyre 0.6.12 with default-features = false, which leaves out eyre's auto-install and track-caller features (#48).
- Old: eyre's default features were on, so a report could be built at any time.
- New: when nothing else in the build turns
auto-installon, building a report panics with "a handler must always be installed if theauto-installfeature is disabled" until the application installs a hook. - What to do: call
eyre::set_hookat startup, or depend oneyrewith its default features in the application.
New features
Getters
#[cgp_getter]defines a getter component. It extends#[cgp_component]and implements the provider trait forUseFields, which reads each field named like a getter method. A trait with a single getter also gets theUseFieldandWithProviderimpls, so a context can choose the field by wiring (#56). See#[cgp_getter]andUseFields.#[cgp_auto_getter]implements a getter trait for every context that has the fields. The blanket impl reads each field throughHasField, so the trait needs no wiring, and the attribute takes no argument (#56). See#[cgp_auto_getter].
Abstract types
cgp_type!declares an abstract type in one line.cgp_type! { Error: Debug }generates the consumer traitHasErrorType, the provider traitProvideErrorType, the componentErrorTypeComponent, the aliasErrorOf, the blanket impls that connect them, and impls forUseTypeandWithProvider(#55).HasErrorTypeandHasRuntimeTypeare declared this way.TypeOf<Context, Tag>is an alias for theTypeof a context'sHasType<Tag>.
Errors
CanWrapError<Detail>adds detail to an error.Context::wrap_error(error, detail)returns the context's error. The component isErrorWrapperComponent, with the provider traitErrorWrapper, andUseDelegatedispatches it per detail type (#48).cgp-error-extraholds genericErrorRaiserandErrorWrapperproviders (#48, #53):RaiseFromraises a source error through the context error'sFromimpl.ReturnErrorreturns a source error that is already the context's error.RaiseInfallibleraises anInfallible, which cannot occur.PanicOnErrorpanics with the source error'sDebugtext.DiscardDetailwraps an error by dropping the detail.DebugErrorandDisplayError, which need theallocfeature, format the source error into aStringand raise or wrap that.
- More providers implement
ErrorWrapper.DebugError,DisplayError,RaiseEyreError,RaiseAnyhowError, and the debug and display providers of the three backends wrap an error as well as raise one (#54). cgp-error-anyhowis a backend foranyhow.UseAnyhowErrorsetsanyhow::Erroras the error type, andRaiseAnyhowError,DebugAnyhowError, andDisplayAnyhowErrorraise and wrap into it (#48).cgp-error-stdadds providers and error types for boxed standard errors.DebugBoxedStdErrorandDisplayBoxedStdErrorraise a source error as aStringErrorholding itsDebugorDisplaytext, and wrap an error in aWrapErrorthat holds the detail and the source and prints them asdetail: source(#48).
Runtimes
cgp-runtimegives generic code a runtime to program against.HasRuntimeTypedeclares the runtime type,HasRuntimeaddsruntime(&self) -> &Self::Runtimethrough the getter componentRuntimeGetter, andHasAsyncRuntimeTyperequires the runtime to beAsync(#50). SeeHasRuntimeTypeandHasRuntime.
Fields
Index<I>implementsDisplay(#49).
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.