Crate supply

source ·
Expand description

supply implements an API similar to that proposed in RFC 3192. It allows accessing data based on type tags. Expanding on RFC 3192, supply allows accessing data with an arbitrary number of lifetimes. Additionally, supply allows for multiple values to be requested at once. supply also builds on the Any API to allow arbitrary number of lifetimes in type erased trait objects. Combined almost any need for passing data between type erased components should be easy to implement.

It is recommended to use the prelude which has the common API elements.

use supply::prelude::*;

Most users should start with implementing the Provider trait on one or more types they want to expose extra information from. Then the .request::<T>() method can be used to request a specific type of information from the provider. This is the core API flow of supply. Below is an example with a couple of the more advanced features for demonstration. See the provide module for a more detailed guide.

For users looking for a more powerful Any, you should see the anything module for a guide on using Anything.

use supply::prelude::*;
use supply::tag::AddLt;

struct Person<'a> {
    name: &'a str,
    age: u8,
}

// Implementing Provider allows requesting data from a Person value.
impl<'r, 'a> Provider<'r> for Person<'a> {
    type Lifetimes = l!['a];

    fn provide(&'r self, want: &mut dyn Want<Self::Lifetimes>) {
        // Provide the name and age fields.
        want.provide_tag::<&str>(self.name)
            .provide_value(self.age);
    }
}

// Make an example person to request data from.
let name = String::from("bob");

let provided_name;
{
    let person = Person {
        name: &name,
        age: 42,
    };

    // Convert to a trait object to show Provider is object safe.
    let provider: &dyn ProviderDyn<l!['_]> = &person;

    // Request the person's name.
    provided_name = provider.request::<&str>();
    assert_eq!(provided_name, Some("bob"));

    // Request the person's age.
    let provided_age = provider.request::<u8>();
    assert_eq!(provided_age, Some(42));

    // Request something Person doesn't provide.
    // We just don't get a value from the request.
    let provided_something = provider.request::<f32>();
    assert_eq!(provided_something, None);
};

// Because the name was tagged as &'a str we can still access it here.
assert_eq!(provided_name, Some("bob"));

§Alternatives

§core/std

No surprise but the core::any module exists, and its very good if you just need to work with 'static types.

Additionally, Error has the unstable provide API (derived from RFC 3192). However, this implementation of provide is limited to error types and has only the lifetime of the source value available.

§Mapping to supply’s API
Click to show 1. In core/std, this function is implemented independently for multiple types.
2. In supply, Want is a trait instead of a struct for more flexibility.

§no_std Support

This crate is #![no_std] by default, it can be used anywhere Rust can.

§Minimum Supported Rust Version

Requires Rust 1.79.0.

This crate follows the “Latest stable Rust” policy. The listed MSRV won’t be changed unless needed. However, updating the MSRV anywhere up to the latest stable at time of release is allowed.

Modules§

  • anything
    Any like API but with any number of lifetimes.
  • lt_list
    List of lifetimes Lt<'a, Lt<'b, Lt<'c, ...>>>.
  • prelude
    Commonly needed types and traits.
  • provide
    Main provide API.
  • request
    Request for values from a provider.
  • tag
    'static tags for types.
  • want
    Wants to be given to a provider to fulfill.

Macros§

  • l
    Create lifetime lists easily.

Traits§

  • Anything
    Any like trait with support for arbitrary number of lifetimes.
  • LtList
    A type level cons list of lifetimes.
  • Provider
    Provider of values.
  • Request
    A request that can be made of a [Provider].
  • Tagged
    Types with an associated 'static tag.
  • Want
    A want for some number of values.