bones_asset/
lib.rs

1//! An asset interface for Bones.
2
3#![warn(missing_docs)]
4// This cfg_attr is needed because `rustdoc::all` includes lints not supported on stable
5#![cfg_attr(doc, allow(unknown_lints))]
6#![deny(rustdoc::all)]
7
8use serde::{de::DeserializeSeed, Deserializer};
9
10/// Helper to export the same types in the crate root and in the prelude.
11macro_rules! pub_use {
12    () => {
13        pub use crate::{asset::*, cid::*, handle::*, io::*, network_handle::*, server::*};
14        pub use anyhow;
15        pub use bones_schema::prelude::*;
16        pub use dashmap;
17        pub use futures_lite::future::Boxed as BoxedFuture;
18        pub use path_absolutize::Absolutize;
19        pub use semver::Version;
20    };
21}
22pub_use!();
23
24/// The prelude.
25pub mod prelude {
26    pub_use!();
27    pub use super::{Maybe, Maybe::*};
28}
29
30mod asset;
31mod cid;
32mod handle;
33mod io;
34mod network_handle;
35mod parse;
36mod server;
37
38/// An equivalent to [`Option<T>`] that has a stable memory layout and implements [`HasSchema`].
39#[derive(HasSchema, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default, Debug)]
40#[type_data(SchemaMetaAssetLoader(maybe_loader))]
41#[repr(C, u8)]
42pub enum Maybe<T> {
43    /// The value is not set.
44    #[default]
45    Unset,
46    /// The value is set.
47    Set(T),
48}
49
50impl<T> Maybe<T> {
51    /// Convert this [`Maybe`] into an [`Option`].
52    #[inline]
53    pub fn option(self) -> Option<T> {
54        self.into()
55    }
56
57    /// Returns `true` if the option is a `Set` value.
58    #[inline]
59    pub fn is_set(&self) -> bool {
60        matches!(self, Maybe::Set(_))
61    }
62
63    /// Returns `true` if the option is an `Unset` value.
64    #[inline]
65    pub fn is_unset(&self) -> bool {
66        matches!(self, Maybe::Unset)
67    }
68
69    /// Returns `true` if the option is a `Set` value.
70    #[inline]
71    pub fn is_some(&self) -> bool {
72        matches!(self, Maybe::Set(_))
73    }
74
75    /// Returns `true` if the option is an `Unset` value.
76    #[inline]
77    pub fn is_none(&self) -> bool {
78        matches!(self, Maybe::Unset)
79    }
80
81    /// Returns `true` if the option is a `Set` value containing the given value.
82    #[inline]
83    pub fn contains<U>(&self, x: &U) -> bool
84    where
85        U: PartialEq<T>,
86    {
87        match self {
88            Maybe::Set(y) => x == y,
89            Maybe::Unset => false,
90        }
91    }
92
93    /// Converts from `&Maybe<T>` to `Maybe<&T>`.
94    #[inline]
95    pub fn as_ref(&self) -> Maybe<&T> {
96        match *self {
97            Maybe::Unset => Maybe::Unset,
98            Maybe::Set(ref x) => Maybe::Set(x),
99        }
100    }
101
102    /// Converts from `&mut Maybe<T>` to `Maybe<&mut T>`.
103    #[inline]
104    pub fn as_mut(&mut self) -> Maybe<&mut T> {
105        match *self {
106            Maybe::Unset => Maybe::Unset,
107            Maybe::Set(ref mut x) => Maybe::Set(x),
108        }
109    }
110
111    /// Returns the contained `Set` value, consuming the `self` value.
112    #[inline]
113    #[track_caller]
114    pub fn expect(self, msg: &str) -> T {
115        self.option().expect(msg)
116    }
117
118    /// Returns the contained `Set` value, consuming the `self` value.
119    #[inline]
120    #[track_caller]
121    pub fn unwrap(self) -> T {
122        self.option().unwrap()
123    }
124
125    /// Returns the contained `Set` value or a provided default.
126    #[inline]
127    pub fn unwrap_or(self, default: T) -> T {
128        self.option().unwrap_or(default)
129    }
130
131    /// Returns the contained `Set` value or computes it from a closure.
132    #[inline]
133    pub fn unwrap_or_else<F: FnOnce() -> T>(self, f: F) -> T {
134        self.option().unwrap_or_else(f)
135    }
136
137    /// Maps a `Maybe<T>` to `Maybe<U>` by applying a function to a contained value.
138    #[inline]
139    pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Maybe<U> {
140        self.option().map(f).into()
141    }
142
143    /// Returns `Unset` if the option is `Unset`, otherwise calls `f` with the wrapped value and returns the result.
144    #[inline]
145    pub fn and_then<U, F: FnOnce(T) -> Maybe<U>>(self, f: F) -> Maybe<U> {
146        self.option().and_then(|x| f(x).option()).into()
147    }
148
149    /// Returns `Unset` if the option is `Unset`, otherwise returns `optb`.
150    #[inline]
151    pub fn and<U>(self, optb: Maybe<U>) -> Maybe<U> {
152        self.option().and(optb.option()).into()
153    }
154
155    /// Returns `Unset` if the option is `Unset`, otherwise calls `predicate` with the wrapped value and returns:
156    #[inline]
157    pub fn filter<P: FnOnce(&T) -> bool>(self, predicate: P) -> Maybe<T> {
158        self.option().filter(predicate).into()
159    }
160
161    /// Returns the option if it contains a value, otherwise returns `optb`.
162    #[inline]
163    pub fn or(self, optb: Maybe<T>) -> Maybe<T> {
164        self.option().or(optb.option()).into()
165    }
166
167    /// Returns the option if it contains a value, otherwise calls `f` and returns the result.
168    #[inline]
169    pub fn or_else<F: FnOnce() -> Maybe<T>>(self, f: F) -> Maybe<T> {
170        self.option().or_else(|| f().option()).into()
171    }
172
173    /// Returns `Set` if exactly one of `self`, `optb` is `Set`, otherwise returns `Unset`.
174    #[inline]
175    pub fn xor(self, optb: Maybe<T>) -> Maybe<T> {
176        self.option().xor(optb.option()).into()
177    }
178
179    /// Inserts `v` into the option if it is `Unset`, then returns a mutable reference to the contained value.
180    #[inline]
181    pub fn get_or_insert(&mut self, v: T) -> &mut T {
182        if let Maybe::Unset = self {
183            *self = Maybe::Set(v);
184        }
185        match self {
186            Maybe::Set(ref mut v) => v,
187            Maybe::Unset => unreachable!(),
188        }
189    }
190
191    /// Inserts a value computed from `f` into the option if it is `Unset`, then returns a mutable reference to the contained value.
192    #[inline]
193    pub fn get_or_insert_with<F: FnOnce() -> T>(&mut self, f: F) -> &mut T {
194        if let Maybe::Unset = self {
195            *self = Maybe::Set(f());
196        }
197        match self {
198            Maybe::Set(ref mut v) => v,
199            Maybe::Unset => unreachable!(),
200        }
201    }
202
203    /// Takes the value out of the option, leaving an `Unset` in its place.
204    #[inline]
205    pub fn take(&mut self) -> Maybe<T> {
206        std::mem::replace(self, Maybe::Unset)
207    }
208
209    /// Replaces the actual value in the option by the value given in parameter, returning the old value if present.
210    #[inline]
211    pub fn replace(&mut self, value: T) -> Maybe<T> {
212        std::mem::replace(self, Maybe::Set(value))
213    }
214
215    /// Zips `self` with another `Maybe`.
216    #[inline]
217    pub fn zip<U>(self, other: Maybe<U>) -> Maybe<(T, U)> {
218        self.option().zip(other.option()).into()
219    }
220
221    /// Returns the contained `Set` value, consuming the `self` value, without checking that the value is not `Unset`.
222    ///
223    /// # Safety
224    ///
225    /// Calling this method on an `Unset` value is undefined behavior.
226    #[inline]
227    pub unsafe fn unwrap_unchecked(self) -> T {
228        self.option().unwrap_unchecked()
229    }
230
231    /// Maps a `Maybe<T>` to `U` by applying a function to a contained value, or returns a default.
232    #[inline]
233    pub fn map_or<U, F: FnOnce(T) -> U>(self, default: U, f: F) -> U {
234        self.option().map_or(default, f)
235    }
236
237    /// Maps a `Maybe<T>` to `U` by applying a function to a contained value, or computes a default.
238    #[inline]
239    pub fn map_or_else<U, D: FnOnce() -> U, F: FnOnce(T) -> U>(self, default: D, f: F) -> U {
240        self.option().map_or_else(default, f)
241    }
242
243    /// Returns the contained `Set` value or a default.
244    #[inline]
245    pub fn unwrap_or_default(self) -> T
246    where
247        T: Default,
248    {
249        self.option().unwrap_or_default()
250    }
251
252    /// Transforms the `Maybe<T>` into a `Result<T, E>`, mapping `Set(v)` to `Ok(v)` and `Unset` to `Err(err)`.
253    #[inline]
254    pub fn ok_or<E>(self, err: E) -> Result<T, E> {
255        self.option().ok_or(err)
256    }
257
258    /// Transforms the `Maybe<T>` into a `Result<T, E>`, mapping `Set(v)` to `Ok(v)` and `Unset` to `Err(err())`.
259    #[inline]
260    pub fn ok_or_else<E, F: FnOnce() -> E>(self, err: F) -> Result<T, E> {
261        self.option().ok_or_else(err)
262    }
263}
264
265impl<T> From<Maybe<T>> for Option<T> {
266    #[inline]
267    fn from(value: Maybe<T>) -> Self {
268        match value {
269            Maybe::Set(s) => Some(s),
270            Maybe::Unset => None,
271        }
272    }
273}
274
275impl<T> From<Option<T>> for Maybe<T> {
276    #[inline]
277    fn from(value: Option<T>) -> Self {
278        match value {
279            Some(s) => Maybe::Set(s),
280            None => Maybe::Unset,
281        }
282    }
283}
284
285impl<T> From<T> for Maybe<T> {
286    #[inline]
287    fn from(value: T) -> Self {
288        Maybe::Set(value)
289    }
290}
291
292fn maybe_loader(
293    ctx: &mut MetaAssetLoadCtx,
294    ptr: SchemaRefMut<'_>,
295    deserialzer: &mut dyn erased_serde::Deserializer,
296) -> anyhow::Result<()> {
297    deserialzer.deserialize_option(MaybeVisitor { ctx, ptr })?;
298
299    Ok(())
300}
301
302struct MaybeVisitor<'a, 'srv> {
303    ctx: &'a mut MetaAssetLoadCtx<'srv>,
304    ptr: SchemaRefMut<'a>,
305}
306
307impl<'a, 'srv, 'de> serde::de::Visitor<'de> for MaybeVisitor<'a, 'srv> {
308    type Value = ();
309
310    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
311        write!(formatter, "an optional value")
312    }
313
314    fn visit_unit<E>(self) -> Result<Self::Value, E>
315    where
316        E: serde::de::Error,
317    {
318        Ok(())
319    }
320    fn visit_none<E>(self) -> Result<Self::Value, E>
321    where
322        E: serde::de::Error,
323    {
324        Ok(())
325    }
326
327    fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
328    where
329        D: Deserializer<'de>,
330    {
331        // Write the enum discriminant for the `Set` variant
332        // SOUND: we know the discriminant due to the `#[repr(C, u8)]` annotation.
333        unsafe {
334            self.ptr.as_ptr().cast::<u8>().write(1);
335        }
336
337        // Get the pointer to the enum value
338        let value_offset = self.ptr.schema().field_offsets()[0].1;
339        // NOTE: we take the schema of the first argument of the second enum variant of the
340        // [`Maybe`] enum because we know that the `Set` variant only has one argument at offset 0
341        // and we actually want to deserialize the inner type, not a typle of length zero.
342        let value_schema = self.ptr.schema().kind.as_enum().unwrap().variants[1]
343            .schema
344            .kind
345            .as_struct()
346            .unwrap()
347            .fields[0]
348            .schema;
349        // SOUND: the schema asserts this is valid.
350        let value_ref = unsafe {
351            SchemaRefMut::from_ptr_schema(self.ptr.as_ptr().add(value_offset), value_schema)
352        };
353
354        // Load the enum value
355        SchemaPtrLoadCtx {
356            ctx: self.ctx,
357            ptr: value_ref,
358        }
359        .deserialize(deserializer)
360    }
361}
bones_asset/lib.rs

bones_asset/
lib.rs
