1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
//! [`supply`](crate) implements an API similar to that proposed in
//! [RFC 3192](https://rust-lang.github.io/rfcs/3192-dyno.html). 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`](core::any::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`](core::any::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
//!
//! <details>
//! <summary>Click to show</summary>
//!
//! | `core`/`std` API | `supply` API |
//! |------------------|--------------|
//! | [`TypeId`](core::any::TypeId) | [`TagTypeId`](crate::tag::TagTypeId) |
//! | [`TypeId::of()`](core::any::TypeId::of) | [`TagTypeId::of()`](crate::tag::TagTypeId::of) |
//! | | |
//! | [`Any`](core::any::Any) | [`Anything`](crate::anything::Anything) |
//! | [`Any::type_id()`](core::any::Any::type_id) | [`Anything::tag_id()`](crate::anything::Anything::tag_id) |
//! | [`Any::is()`](core::any::Any#method.is) [<sup>1</sup>](#core-1) | [`AnythingExt::is()`](crate::anything::AnythingExt::is) |
//! | [`Any::downcast_ref()`](core::any::Any#method.downcast_ref) [<sup>1</sup>](#core-1) | [`AnythingExt::downcast_ref()`](crate::anything::AnythingExt::downcast_ref) |
//! | [`Any::downcast_mut()`](core::any::Any#method.downcast_mut) [<sup>1</sup>](#core-1) | [`AnythingExt::downcast_mut()`](crate::anything::AnythingExt::downcast_mut) |
//! | | |
//! | [`Error::provide`](core::error::Error::provide) | [`Provider::provide`](crate::Provider::provide) |
//! | | |
//! | [`Request`](core::error::Request) | [`Want`](crate::want::Want) [<sup>2</sup>](#core-2) |
//! | [`Request::provide_ref()`](core::error::Request::provide_ref) </br> [`Request::provide_value()`](core::error::Request::provide_ref) | [`Want::provide_value()`](crate::want::Want#method.provide_value) |
//!
//! <sub>
//! <a name="core-1"></a> 1. In core/std, this function is implemented independently for
//! multiple types.
//! </br>
//! <a name="core-2"></a> 2. In supply, Want is a trait instead of a struct for more flexibility.
//! </sub>
//!
//! </details>
//!
//! ## `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](https://gist.github.com/alexheretic/d1e98d8433b602e57f5d0a9637927e0c). 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.
// #![forbid(unsafe_code)]
/// Commonly needed types and traits.
pub use Anything;
pub use LtList;
pub use Provider;
pub use Request;
pub use Tagged;
pub use Want;