supply 0.3.1

Provider API for arbitrary number of lifetimes.
Documentation 
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

//! Wants to be given to a provider to fulfill.

mod want_one;

mod erased;

pub use erased::ErasedWantFor;
use ty_tag::lifetime_list::LifetimeList;
use ty_tag::{ReifySelf, ReifySized, TagTypeId};
pub use want_one::WantOne;

use crate::Want;

/// A want for a `T`.
pub trait WantFor<T> {
    /// Fulfill the want with a value.
    ///
    /// Calling this when [`WantFor::is_satisfied`] returns true may replace the value or keep the
    /// old one. It is recommended to not call this in such cases to prevent unusual behavior.
    fn fulfill(&mut self, value: T);

    /// Checks if the want for `T` is fully satisfied.
    ///
    /// Once satisfied, no more values of type `T` need to be provided.
    /// This may return a `true` when the `dyn Want` this is derived from does not.
    /// In those cases the want doesn't need any more `T` but can accept values of other types.
    fn is_satisfied(&self) -> bool {
        false
    }
}

// Extra non-object safe methods.
impl<L: LifetimeList> dyn Want<L> + '_ {
    /// Provide a value using it's [`ReifySelf`] tag.
    ///
    /// Not all values implement [`ReifySelf`], and you may want to use a custom tag
    /// instead of the value's normal tag. In those cases use `Self::provide_tag`.
    ///
    /// This method can be chained with other provide methods.
    pub fn provide_value<T: ReifySelf<L>>(&mut self, value: T) -> &mut Self {
        if let Some(want) = self.try_for::<T>() {
            want.fulfill(value);
        }

        self
    }

    /// Provide a tagged value to the want.
    ///
    /// `T` can be any [`ReifySized`] implementing type.
    ///
    /// This method can be chained with other provide methods.
    ///
    /// If `value` is expensive to create, use `Self::provide`.
    pub fn provide_tag<T: ?Sized + ReifySized<L>>(&mut self, value: T::Reified) -> &mut Self {
        if let Some(want) = self.try_for::<T>() {
            want.fulfill(value);
        }

        self
    }

    /// Provide a tagged value to the want.
    ///
    /// `T` can be any [`ReifySized`] implementing type.
    ///
    /// This method can be chained with other provide methods.
    ///
    /// The value is given as the result of a function. This allows
    /// not generating the value if the want does not need the value.
    /// This should be used for values that are expensive to create.
    ///
    /// If you need to pass in a context into `f`, use `Self::provide_with`.
    pub fn provide<T, F>(&mut self, f: F) -> &mut Self
    where
        T: ReifySized<L>,
        F: FnOnce() -> <T as ReifySized<L>>::SizedReified,
    {
        if let Some(want) = self.try_for::<T>() {
            want.fulfill(f());
        }

        self
    }

    /// Provide a tagged value to the want.
    ///
    /// `T` can be any [`ReifySized`] implementing type.
    ///
    /// This provide method does not allow chaining as it returns the context
    /// value if the want does not want a `T`. Instead the next provide call will
    /// need to start a new chain.
    ///
    /// The value is given as the result of a function. This allows
    /// not generating the value if the want does not need the value.
    /// This should be used for values that are expensive to create.
    ///
    /// If you don't need a context, use `Self::provide`.
    pub fn provide_with<T, C, F>(&mut self, ctx: C, f: F) -> Option<C>
    where
        T: ReifySized<L>,
        F: FnOnce(C) -> <T as ReifySized<L>>::SizedReified,
    {
        if let Some(want) = self.try_for::<T>() {
            want.fulfill(f(ctx));
            None
        } else {
            Some(ctx)
        }
    }

    /// Wrapper of [`Want::try_for_id`] that takes a tag instead of a [`TagTypeId`].
    ///
    /// This method should only be used if one of the provide methods doesn't work.
    pub fn try_for<T: ?Sized + ReifySized<L>>(&mut self) -> Option<&mut dyn WantFor<T::Reified>> {
        // Call try_for_id with the id of the T passed in.
        let erased = self.try_for_id(TagTypeId::<L>::of_reify::<T>())?;

        // If the want gave a bad WantFor we just ignore it.
        erased.downcast::<T>().ok()
    }
}