Skip to main content

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.

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, and cgp-runtime.
  • Features: cgp-error-extra has an alloc feature, on by default, that provides DebugError and DisplayError. cgp-extra has a default full feature that turns it on, and the full feature of cgp now forwards to cgp-core and cgp-extra.

Upgrading​

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

  1. Change the version to cgp = "0.3.0" and use Rust 1.83 or newer.
  2. Import macros and items from the prelude or a crate's root, per the macro re-exports and the module paths.
  3. Rename the error providers of cgp-error-eyre and cgp-error-std, per the renames.
  4. Move cgp::core::inner to cgp::extra::inner, per the cgp-inner move.
  5. Require HasAsyncErrorType where code needs a Send + Sync + 'static error, per the error bound.
  6. Install an eyre hook in an application that builds eyre reports, 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}; and use cgp_field::{symbol, HasField}; imported the macros and the derive.
  • New: the macros come from cgp::prelude, or from cgp-component-macro and cgp-field-macro for a crate that depends on them directly.
  • What to do: write use cgp::prelude::*;. A crate that imports through cgp-component or cgp-field adds 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::Char or cgp_type::traits::has_type::ProvideType.
  • New: each item is imported from its crate's root, such as cgp_field::Char and cgp_type::ProvideType. The cgp::core and cgp::extra modules 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 at cgp::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 was Send + Sync + 'static.
  • New: type Error: Debug. The new trait HasAsyncErrorType is Async + HasErrorType<Error: Async>.
  • What to do: where code relies on the error being Send + Sync + 'static, add HasAsyncErrorType to 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).

CrateOldNew
cgp-error-eyreProvideEyreErrorUseEyreError
cgp-error-eyreRaiseStdErrorRaiseEyreError
cgp-error-eyreRaiseDebugErrorDebugEyreError
cgp-error-eyreRaiseDisplayErrorDisplayEyreError
cgp-error-stdHandleErrorsWithStdErrorUseBoxedStdError for the error type, RaiseBoxedStdError for raising
  • What to do: rename each use in the wiring. A context that wired HandleErrorsWithStdError for 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-install on, building a report panics with "a handler must always be installed if the auto-install feature is disabled" until the application installs a hook.
  • What to do: call eyre::set_hook at startup, or depend on eyre with its default features in the application.

New features​

Getters​

  • #[cgp_getter] defines a getter component. It extends #[cgp_component] and implements the provider trait for UseFields, which reads each field named like a getter method. A trait with a single getter also gets the UseField and WithProvider impls, so a context can choose the field by wiring (#56). See #[cgp_getter] and UseFields.
  • #[cgp_auto_getter] implements a getter trait for every context that has the fields. The blanket impl reads each field through HasField, 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 trait HasErrorType, the provider trait ProvideErrorType, the component ErrorTypeComponent, the alias ErrorOf, the blanket impls that connect them, and impls for UseType and WithProvider (#55). HasErrorType and HasRuntimeType are declared this way.
  • TypeOf<Context, Tag> is an alias for the Type of a context's HasType<Tag>.

Errors​

  • CanWrapError<Detail> adds detail to an error. Context::wrap_error(error, detail) returns the context's error. The component is ErrorWrapperComponent, with the provider trait ErrorWrapper, and UseDelegate dispatches it per detail type (#48).
  • cgp-error-extra holds generic ErrorRaiser and ErrorWrapper providers (#48, #53):
    • RaiseFrom raises a source error through the context error's From impl.
    • ReturnError returns a source error that is already the context's error.
    • RaiseInfallible raises an Infallible, which cannot occur.
    • PanicOnError panics with the source error's Debug text.
    • DiscardDetail wraps an error by dropping the detail.
    • DebugError and DisplayError, which need the alloc feature, format the source error into a String and 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-anyhow is a backend for anyhow. UseAnyhowError sets anyhow::Error as the error type, and RaiseAnyhowError, DebugAnyhowError, and DisplayAnyhowError raise and wrap into it (#48).
  • cgp-error-std adds providers and error types for boxed standard errors. DebugBoxedStdError and DisplayBoxedStdError raise a source error as a StringError holding its Debug or Display text, and wrap an error in a WrapError that holds the detail and the source and prints them as detail: source (#48).

Runtimes​

  • cgp-runtime gives generic code a runtime to program against. HasRuntimeType declares the runtime type, HasRuntime adds runtime(&self) -> &Self::Runtime through the getter component RuntimeGetter, and HasAsyncRuntimeType requires the runtime to be Async (#50). See HasRuntimeType and HasRuntime.

Fields​

  • Index<I> implements Display (#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.