rocket/request/
mod.rs

Help
1//! Types and traits for request parsing and handling.
2
3mod request;
4mod from_param;
5mod from_request;
6
7#[cfg(test)]
8mod tests;
9
10pub use self::request::Request;
11pub use self::from_request::{FromRequest, Outcome};
12pub use self::from_param::{FromParam, FromSegments};
13
14#[doc(inline)]
15pub use crate::response::flash::FlashMessage;
16
17pub(crate) use self::request::ConnectionMeta;
18
19crate::export! {
20    /// Store and immediately retrieve a vector-like value `$v` (`String` or
21    /// `Vec<T>`) in `$request`'s local cache using a locally generated
22    /// anonymous type to avoid type conflicts.
23    ///
24    /// Unlike `local_cache_once`, this macro's generated code _always_ returns
25    /// a unique reference to request-local cache.
26    ///
27    /// # Note
28    ///
29    /// The value `$v` must be of type `String` or `Vec<T>`, that is, a type
30    /// that implements the sealed trait [`Shareable`](crate::form::Shareable)bb).
31    ///
32    /// # Example
33    ///
34    /// ```rust
35    /// use rocket::request::{local_cache, local_cache_once};
36    /// # let c = rocket::local::blocking::Client::debug_with(vec![]).unwrap();
37    /// # let request = c.get("/");
38    ///
39    /// // The first store into local cache for a given type wins.
40    /// for i in 0..4 {
41    ///     assert_eq!(request.local_cache(|| i.to_string()), "0");
42    /// }
43    ///
44    /// // This shows that we cannot cache different values of the same type; we
45    /// // _must_ use a proxy type. To avoid the need to write these manually, use
46    /// // `local_cache!`, which generates one of the fly.
47    /// for i in 0..4 {
48    ///     assert_eq!(local_cache!(request, i.to_string()), i.to_string());
49    /// }
50    ///
51    /// // Note that while `local_cache_once!` generates a new type for the
52    /// // _macro_ invocation, that type is the same per run-time invocation, so
53    /// // all "calls" to `local_cache_once!` on the same line return the same
54    /// // reference for a given request.
55    /// for i in 1..4 {
56    ///     // Note that this is `1`, so _not_ the `String` from line 4.
57    ///     assert_eq!(local_cache_once!(request, i.to_string()), "1");
58    /// }
59    /// ```
60    macro_rules! local_cache {
61        ($request:expr, $v:expr $(,)?) => ({
62            struct Local<T: $crate::form::Shareable>($crate::form::SharedStack<T>);
63            let stack = $request.local_cache(|| Local($crate::form::SharedStack::new()));
64            stack.0.push_owned($v)
65        })
66    }
67}
68
69crate::export! {
70    /// Store and immediately retrieve a value `$v` in `$request`'s local cache
71    /// using a locally generated anonymous type to avoid type conflicts.
72    ///
73    /// The code generated by this macro is expected to be invoked at-most once
74    /// per-request. This is because while `local_cache_once!` generates a new
75    /// type for the _macro_ invocation, that type is the same per run-time
76    /// invocation. Thus, for a given request, a `local_cache_once!` invocation
77    /// always returns the same reference.
78    ///
79    /// To get a unique request-local reference to string-like values, use
80    /// [`local_cache!`] instead.
81    ///
82    /// # Example
83    ///
84    /// ```rust
85    /// use rocket::request::local_cache_once;
86    /// # let c = rocket::local::blocking::Client::debug_with(vec![]).unwrap();
87    /// # let request = c.get("/");
88    ///
89    /// // The first store into local cache for a given type wins.
90    /// assert_eq!(request.local_cache(|| String::from("hello")), "hello");
91    ///
92    /// // The following returns the cached, previously stored value for the type.
93    /// assert_eq!(request.local_cache(|| String::from("goodbye")), "hello");
94    ///
95    /// // This shows that we cannot cache different values of the same type;
96    /// // we _must_ use a proxy type. To avoid the need to write these manually,
97    /// // use `local_cache_once!`, which generates one of the fly.
98    /// assert_eq!(local_cache_once!(request, String::from("hello")), "hello");
99    /// assert_eq!(local_cache_once!(request, String::from("goodbye")), "goodbye");
100    ///
101    /// // But a macro invocation for the same request always resolves to the
102    /// // first reference as the unique type is generated at compile-time.
103    /// for i in 1..4 {
104    ///     assert_eq!(local_cache_once!(request, i.to_string()), "1");
105    /// }
106    /// ```
107    macro_rules! local_cache_once {
108        ($request:expr, $v:expr $(,)?) => ({
109            struct Local<T>(T);
110            &$request.local_cache(move || Local($v)).0
111        })
112    }
113}
rocket/request/mod.rs

rocket/request/
mod.rs
