Skip to main content

cgp v0.1.0

Version 0.1.0 of cgp, the library for Context-Generic Programming (CGP) that enables pluggable trait implementations in Rust, is its first release on crates.io. This page lists what the release provides.

Released on 2024-09-03.

Summary​

A trait becomes a component with #[derive_component], and delegate_components! writes the table through which a context chooses a provider for each component. define_components! writes a reusable table, #[derive(HasField)] and symbol! read a context's fields by name, and HasErrorType with CanRaiseError gives generic code an error type to raise into. The release ships as 17 crates, with backends for eyre and standard errors.

Compatibility​

  • Minimum Rust version: 1.79.
  • Released together: the workspace's 17 crates, all at 0.1.0. The facade crates are cgp, cgp-core, and cgp-extra. The library crates are cgp-component, cgp-field, cgp-error, cgp-async, cgp-sync, cgp-run, and cgp-inner. The macro crates are cgp-component-macro, cgp-component-macro-lib, cgp-field-macro, cgp-field-macro-lib, and cgp-async-macro. The error backends are cgp-error-eyre and cgp-error-std.
  • Features: the crates declare none.

Upgrading​

This is the first release, so there is nothing to upgrade from. A project adds cgp = "0.1.0" and writes use cgp::prelude::*;.

New features​

Components and wiring​

  • #[derive_component] turns a trait into a component. The attribute names the component and the provider trait positionally, as in #[derive_component(ErrorTypeComponent, ProvideErrorType<Context>)]. It generates the component's name struct, the provider trait with the context as an explicit first type parameter, a blanket impl of the consumer trait that forwards to the provider chosen by the context's Components table, and a blanket impl of the provider trait for any table that delegates the component to a provider.
  • delegate_components! writes a context's wiring table. Each entry of delegate_components! { Context { Component: Provider } } implements DelegateComponent<Component> for the target type with Provider as its Delegate. An entry may name several components in brackets, as in [A, B]: Provider, and the target and each component may carry generic parameters (#17). See delegate_components!.
  • define_components! writes a reusable table. It takes the entries of delegate_components! and declares a struct that holds them, as in define_components! { Name { ... } } (#17). Beside the struct it generates a DelegatesToName marker trait for the types that delegate every component of the table to Name, and a with_name! macro that replaces each @Name in its input with the bracketed list of the table's components.
  • DelegateComponent and HasComponents hold the table. DelegateComponent<Name> has an associated Delegate type that names the provider for a component, and HasComponents has an associated Components type that names the table of a context. See DelegateComponent.

Fields​

  • HasField<Key> reads a field by a type-level key. Its get_field(&self, key: PhantomData<Key>) returns a reference to the field, whose type is the associated type Field, and a blanket impl gives the same access to a context that dereferences to a type with the field (#19). See HasField.
  • #[derive(HasField)] implements HasField for each named field of a struct. The key of each impl is symbol! of the field's name, and a tuple struct gets no impls. See #[derive(HasField)].
  • symbol!("name") builds a type-level string. It expands to the Char<'c'> type of each character, separated by commas inside parentheses, where Char takes a char as a const parameter.

Errors​

  • HasErrorType declares the one error type of a context. Its associated Error type must be Async + Debug, and ErrorOf<Context> names it. The component is ErrorTypeComponent, with the provider trait ProvideErrorType. See HasErrorType.
  • CanRaiseError<E> converts a source error into the context's error. Context::raise_error(e) returns Self::Error. The component is ErrorRaiserComponent, with the provider trait ErrorRaiser, and DelegateErrorRaiser picks the raiser for each source error type from a table. See CanRaiseError.
  • cgp-error-eyre provides eyre's Report as the error type. ProvideEyreError sets the type, and RaiseStdError, RaiseDebugError, and RaiseDisplayError raise a source error that implements std::error::Error, Debug, or Display (#11).
  • cgp-error-std provides a boxed standard error. Its Error is Box<dyn std::error::Error + Send + Sync + 'static>, and HandleErrorsWithStdError sets it as the context's error type and raises any standard error into it (#11).

Async​

  • Async abbreviates Sized + Send + Sync + 'static. cgp-async defines the trait with a blanket impl for every such type, and its async_trait attribute rewrites each async fn of a trait to return impl Future<Output = T> + Send.
  • cgp-sync offers the same names without Send and Sync. Its Async abbreviates Sized + 'static, and its async_trait attribute strips async and .await from a trait, so the same code compiles as synchronous code.

Running and composing​

  • CanRun runs a context. Its async fn run(&self) -> Result<(), Self::Error> is the component RunnerComponent, with the provider trait Runner, in cgp-run (#3). See CanRun.
  • HasInner exposes a wrapped context. It declares an associated Inner type and inner(&self) -> &Self::Inner, as the component InnerComponent with the provider trait ProvideInner, in cgp-inner (#7).

Crates and the prelude​

  • cgp re-exports the rest. cgp::core is cgp-core, which re-exports the component, error, field, and inner crates and the Async items, cgp::extra is cgp-extra, which re-exports cgp-run as run, and cgp::prelude is the core prelude.
  • The prelude brings in the names a program writes. They are async_trait, Async, define_components, delegate_components, derive_component, DelegateComponent, HasComponents, CanRaiseError, HasErrorType, symbol, Char, and HasField.

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.