deser_incomplete/source/
mod.rs

1//! Trait [`Source`] describes a resource that can be deserialized multiple times:
2//! a [`Deserializer`] together with the data it works on, such as a string
3//! reference or byte slice.
4
5use serde::Deserializer;
6
7#[cfg(feature = "serde_json")]
8mod json;
9#[cfg(feature = "serde_yaml")]
10mod yaml;
11
12#[cfg(feature = "serde_json")]
13pub use json::{JsonBytes, JsonStr};
14#[cfg(feature = "serde_yaml")]
15pub use yaml::{YamlBytes, YamlStr};
16
17/// Describes a resource that can be deserialized multiple times:
18/// a [`Deserializer`] together with the data it works on, such as a string
19/// reference or byte slice.
20///
21/// For instance, [`crate::source::JsonStr`] is a borrowed string that we should use [`serde_json`] on.
22///
23/// For your own data format, take a look at the implementation of either [`JsonStr`]
24/// and [`YamlStr`] --- depending on whether your data format implements [`Deserializer`]
25/// like [`serde_json`] or like [`serde_yaml`]:
26///
27/// - [`serde_yaml`] has `serde_yaml::Deserializer: serde::Deserializer`
28/// - [`serde_json`] has `&mut serde_json::Deserializer: serde::Deserializer`
29pub trait Source<'de> {
30    /// Stack storage for the deserializer.
31    type DeserializerStorage;
32
33    type Deserializer<'storage>: Deserializer<'de, Error = Self::Error>
34    where
35        'de: 'storage;
36
37    /// The error type cannot depend on `'storage`.
38    type Error: serde::de::Error;
39
40    /// Recreate a deserializer for this source.
41    ///
42    /// Every deserializer created from a source should behave exactly the
43    /// same.
44    ///
45    /// If end of file happens in a map in between the key and the value, then
46    /// our first go at deserializing will fail, and we have to recreate
47    /// a new deserializer for the same source.
48    fn recreate_deserializer_storage(&mut self) -> Self::DeserializerStorage;
49
50    /// Will be called exactly once per [`Self::DeserializerStorage`]. The argument
51    /// is guaranteed to be `Some`.
52    ///
53    /// Typically returns either `storage.take()` or `&mut storage`.
54    fn use_deserializer_from_storage(
55        storage: &mut Option<Self::DeserializerStorage>,
56    ) -> Self::Deserializer<'_>;
57}
deser_incomplete/source/mod.rs

deser_incomplete/source/
mod.rs
