Supply

Provider API for arbitrary number of lifetimes.

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][core::error::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

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.

Contributing

Contributions in any form (issues, pull requests, etc.) to this project must adhere to Rust's Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in supply by you shall be licensed as below, without any additional terms or conditions.

License

This project is licensed under either of

• Apache License 2.0
• MIT License

at your option.