dynamic-provider 0.1.1

Dynamically request arbitrarily-typed values from providers with borrowed data.

Motivation

Rust's Any trait allows for downcasting to access the underlying type of a dyn object. Unfortunately, this is limited to 'static types (types that contain no borrowed data) because there's no way to distinguish types with different lifetimes by their TypeIds.

This crate provides the dynamically-sized Query type with lifetime parameters and an internal tag indicating what type of value it's meant to hold, potentially containing those lifetimes.

The Provide and ProvideRef traits supply values to queries, the latter being dyn-capable.

Prior Art

• Rust RFC 3192
  • implementation by @nrc
• supply by @konnorandrews

Concepts

Lifetime lists

Lists of lifetime variables are represented by types implementing Lt. You can describe a lifetime list with the Lt! macro:

use dynamic_provider::Lt;

/// Lifetime list for retrieving values from `'data` with an argument that
/// borrows `'input`.
type CustomLifetimes<'data, 'input> = Lt!['data, 'input];

/// Prepend a `'local` lifetime to lifetime list `L`.
type PrependLifetime<'local, L> = Lt!['local, ..L];

Type functions

TypeFn implementations describe a type that is parameterized over an arbitrary lifetime list.

A simple type function can be described with the TypeFn! macro:

type RefPair<A, B> = dynamic_provider::TypeFn![for<'a, 'b> (&'a A, &'b B)];

Resource tags

ResourceTag implementations describe how values may be provided to a Query. The trait has two associated TypeFns: Arg, which determines what values are needed to request the resource, and Out, which defines the type of the resource value.

The [define_tag!] macro provides a convenient way to declare resource tags:

dynamic_provider::define_tag! {
    // syntax:
    // [pub] tag NAME[<...GENERICS>]: [for<...LIFETIMES>] [ARG =>] OUT [where BOUNDS];
    pub tag Field<T>: for<'data, 'key> &'key str => &'data T where T: ?Sized;
    pub tag StatusCode: i32;
}

Providers

Provide<L>

Supplies values with the lifetime variables in L to the Query object passed to the provide() method.

ProvideRef<L>

Supplies values from a reference to Self with the lifetime of the reference and the lifetime variables in L.

A reference to a Provide implementation (say, &'x impl ProvideRef<L> or &'x mut impl ProvideRef<L>) automatically implements Provide<'x, ..L> for all 'x.

Examples

Dynamic field access

use dynamic_provider::{define_tag, request, Lt, Provide, ProvideRef, Query};

define_tag! {
    /// Represents dynamic access to a field.
    ///
    /// The argument of type `&'key str` indicates the name of the field being
    /// accessed.
    pub tag Field<T: ?Sized>: for<'data, 'key> &'key str => &'data T;
}

struct MyData {
    foo: String,
    bar: String,
    baz: Vec<u8>,
}

impl<'key> ProvideRef<Lt!['key]> for MyData {
    fn provide_ref<'data>(&'data self, query: &mut Query<Lt!['data, 'key]>) {
        query
            .put_where::<Field<str>>(|key| *key == "foo", |_| &self.foo)
            .put_where::<Field<str>>(|key| *key == "bar", |_| &self.bar)
            .put_where::<Field<[u8]>>(|key| *key == "baz", |_| &self.baz);
    }
}

/// Dynamically gets a reference to the field with name `key` and type `T`, if
/// provided.
fn get_field<'data, T: ?Sized + 'static>(
    data: &'data dyn for<'key> ProvideRef<Lt!['key]>,
    key: &str,
) -> Option<&'data T> {
    request! { from data;
        tag x: Field<T> where arg <- key => Some(x),
        else => None,
    }
}

// Retrieve fields from a value of type MyData:
let data = MyData {
    foo: "foo!".into(),
    bar: "bar!".into(),
    baz: b"baz!".into(),
};

assert_eq!(get_field::<str>(&data, "foo").unwrap(), "foo!");
assert_eq!(get_field::<str>(&data, "bar").unwrap(), "bar!");
assert_eq!(get_field::<[u8]>(&data, "baz").unwrap(), b"baz!");

// Use () when you need an empty provider:
assert!(get_field::<str>(&(), "foo").is_none());

Features

"alloc"

Adds the ProvideBox trait. Adds trait implementations for Rc, Box, and String, and enables additional provided values for std types.