feat: Adds external data support to deserialization process. (#116)

* feat(core)!: Adds external data support to deserialization.

* Improved external data API for `xmlity-quick-xml`.

* Changed from `Arc<ExternalData>` to `Rc<ExternalData>`.

* `cargo clippy`

Author: lukasfri

xmlity-derive/src/common.rs

@@ -32,7 +32,7 @@ impl FieldIdent {
 impl fmt::Display for FieldIdent {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            FieldIdent::Named(ident) => write!(f, "{}", ident),
+            FieldIdent::Named(ident) => write!(f, "{ident}"),
             FieldIdent::Indexed(index) => write!(f, "{}", index.index),
         }
     }

xmlity-quick-xml/src/de.rs

@@ -1,7 +1,7 @@
 /// The [`xmlity::de::Deserializer`] implementation for the `quick-xml` crate.
 ///
 /// This deserializer is based upon the [`quick_xml::NsReader`] with the same limits as the underlying reader, including requiring a `[u8]` backing.
-use std::{borrow::Cow, ops::Deref};
+use std::{borrow::Cow, collections::HashMap, ops::Deref, rc::Rc};
 
 use quick_xml::{
     events::{attributes::Attribute, BytesCData, BytesDecl, BytesPI, BytesStart, BytesText, Event},
@@ -11,7 +11,7 @@ use quick_xml::{
 
 use xmlity::{
     de::{
-        self, Error as _, NamespaceContext, Visitor, XmlCData, XmlComment, XmlDeclaration,
+        self, DeserializeContext, Error as _, Visitor, XmlCData, XmlComment, XmlDeclaration,
         XmlDoctype, XmlProcessingInstruction, XmlText,
     },
     Deserialize, ExpandedName, LocalName, XmlNamespace,
@@ -202,6 +202,42 @@ impl<'i> Reader<'i> {
     }
 }
 
+/// A struct to hold external data that can be used during deserialization.
+#[derive(Debug)]
+pub struct ExternalData {
+    data: HashMap<core::any::TypeId, Box<dyn core::any::Any>>,
+}
+
+impl ExternalData {
+    /// Creates a new [`ExternalData`] instance.
+    pub fn new() -> Self {
+        Self {
+            data: HashMap::new(),
+        }
+    }
+
+    /// Inserts data into the external data map.
+    pub fn insert<T: 'static>(&mut self, data: T) {
+        self.data.insert(
+            core::any::TypeId::of::<T>(),
+            Box::new(data) as Box<dyn core::any::Any>,
+        );
+    }
+
+    /// Retrieves data from the external data map.
+    pub fn get<T: 'static>(&self) -> Option<&T> {
+        self.data
+            .get(&core::any::TypeId::of::<T>())
+            .and_then(|data| data.downcast_ref::<T>())
+    }
+}
+
+impl Default for ExternalData {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 /// The [`xmlity::Deserializer`] for the `quick-xml` crate.
 ///
 /// This currently only supports an underlying reader of type `&[u8]` due to limitations in the `quick-xml` crate.
@@ -210,6 +246,7 @@ pub struct Deserializer<'i> {
     reader: Reader<'i>,
     // Limit depth
     limit_depth: i16,
+    external_data: Option<Rc<ExternalData>>,
 }
 
 impl<'i> From<NsReader<&'i [u8]>> for Deserializer<'i> {
@@ -230,9 +267,16 @@ impl<'i> Deserializer<'i> {
         Self {
             reader: Reader::new(reader),
             limit_depth: 0,
+            external_data: None,
         }
     }
 
+    /// Set the external data for the deserializer.
+    pub fn with_external_data(mut self, external_data: ExternalData) -> Self {
+        self.external_data = Some(Rc::new(external_data));
+        self
+    }
+
     fn read_until_end(&mut self) -> Result<(), Error> {
         while let Some(event) = self.next_event() {
             debug_assert!(!matches!(event, Event::Eof));
@@ -281,6 +325,7 @@ impl<'i> Deserializer<'i> {
         Self {
             reader: self.reader.clone(),
             limit_depth,
+            external_data: self.external_data.clone(),
         }
     }
 
@@ -315,7 +360,7 @@ impl<'r> ElementAccess<'_, 'r> {
 
 const PLACEHOLDER_ELEMENT_NAME: &str = "a";
 
-impl NamespaceContext for &Deserializer<'_> {
+impl DeserializeContext for &Deserializer<'_> {
     fn default_namespace(&self) -> Option<XmlNamespace<'_>> {
         let (_, namespace) = self
             .resolve_qname(QuickName(PLACEHOLDER_ELEMENT_NAME.as_bytes()), false)
@@ -332,6 +377,13 @@ impl NamespaceContext for &Deserializer<'_> {
 
         namespace.map(XmlNamespace::into_owned)
     }
+
+    fn external_data<T>(&self) -> Option<&T>
+    where
+        T: core::any::Any,
+    {
+        self.external_data.as_ref().and_then(|data| data.get::<T>())
+    }
 }
 
 struct AttributeAccess<'a, 'v> {
@@ -367,7 +419,7 @@ struct TextDeserializer<'a, 'v> {
 }
 
 impl<'de> de::XmlText<'de> for TextDeserializer<'_, 'de> {
-    type NamespaceContext<'a>
+    type DeserializeContext<'a>
         = &'a Deserializer<'a>
     where
         Self: 'a;
@@ -391,7 +443,7 @@ impl<'de> de::XmlText<'de> for TextDeserializer<'_, 'de> {
         std::str::from_utf8(self.value.as_ref()).unwrap()
     }
 
-    fn namespace_context(&self) -> Self::NamespaceContext<'_> {
+    fn context(&self) -> Self::DeserializeContext<'_> {
         self.deserializer
     }
 }
@@ -617,7 +669,7 @@ impl<'de> de::AttributesAccess<'de> for ElementAccess<'_, 'de> {
 
 impl<'a, 'de> de::ElementAccess<'de> for ElementAccess<'a, 'de> {
     type ChildrenAccess = SeqAccess<'a, 'de>;
-    type NamespaceContext<'b>
+    type DeserializeContext<'b>
         = &'b Deserializer<'de>
     where
         Self: 'b;
@@ -646,7 +698,7 @@ impl<'a, 'de> de::ElementAccess<'de> for ElementAccess<'a, 'de> {
         })
     }
 
-    fn namespace_context(&self) -> Self::NamespaceContext<'_> {
+    fn context(&self) -> Self::DeserializeContext<'_> {
         self.deserializer()
     }
 }
@@ -757,7 +809,7 @@ impl<'a, T> DataWithD<'a, T> {
 }
 
 impl<'de> XmlText<'de> for DataWithD<'_, BytesText<'de>> {
-    type NamespaceContext<'a>
+    type DeserializeContext<'a>
         = &'a Deserializer<'a>
     where
         Self: 'a;
@@ -781,13 +833,13 @@ impl<'de> XmlText<'de> for DataWithD<'_, BytesText<'de>> {
         std::str::from_utf8(self.data.deref()).unwrap()
     }
 
-    fn namespace_context(&self) -> Self::NamespaceContext<'_> {
+    fn context(&self) -> Self::DeserializeContext<'_> {
         self.deserializer
     }
 }
 
 impl<'de> XmlCData<'de> for DataWithD<'_, BytesCData<'de>> {
-    type NamespaceContext<'a>
+    type DeserializeContext<'a>
         = &'a Deserializer<'a>
     where
         Self: 'a;
@@ -811,13 +863,13 @@ impl<'de> XmlCData<'de> for DataWithD<'_, BytesCData<'de>> {
         std::str::from_utf8(self.data.deref()).unwrap()
     }
 
-    fn namespace_context(&self) -> Self::NamespaceContext<'_> {
+    fn context(&self) -> Self::DeserializeContext<'_> {
         self.deserializer
     }
 }
 
 impl<'de> XmlComment<'de> for DataWithD<'_, BytesText<'de>> {
-    type NamespaceContext<'a>
+    type DeserializeContext<'a>
         = &'a Deserializer<'a>
     where
         Self: 'a;
@@ -830,7 +882,7 @@ impl<'de> XmlComment<'de> for DataWithD<'_, BytesText<'de>> {
         self.data.deref()
     }
 
-    fn namespace_context(&self) -> Self::NamespaceContext<'_> {
+    fn context(&self) -> Self::DeserializeContext<'_> {
         self.deserializer
     }
 }
@@ -862,7 +914,7 @@ impl<'a> TryFrom<&'a BytesDecl<'a>> for ClearedByteDecl<'a> {
 }
 
 impl XmlDeclaration for DataWithD<'_, ClearedByteDecl<'_>> {
-    type NamespaceContext<'a>
+    type DeserializeContext<'a>
         = &'a Deserializer<'a>
     where
         Self: 'a;
@@ -879,13 +931,13 @@ impl XmlDeclaration for DataWithD<'_, ClearedByteDecl<'_>> {
         self.data.standalone.as_deref()
     }
 
-    fn namespace_context(&self) -> Self::NamespaceContext<'_> {
+    fn context(&self) -> Self::DeserializeContext<'_> {
         self.deserializer
     }
 }
 
 impl XmlProcessingInstruction for DataWithD<'_, BytesPI<'_>> {
-    type NamespaceContext<'a>
+    type DeserializeContext<'a>
         = &'a Deserializer<'a>
     where
         Self: 'a;
@@ -898,13 +950,13 @@ impl XmlProcessingInstruction for DataWithD<'_, BytesPI<'_>> {
         self.data.content()
     }
 
-    fn namespace_context(&self) -> Self::NamespaceContext<'_> {
+    fn context(&self) -> Self::DeserializeContext<'_> {
         self.deserializer
     }
 }
 
 impl<'de> XmlDoctype<'de> for DataWithD<'_, BytesText<'de>> {
-    type NamespaceContext<'a>
+    type DeserializeContext<'a>
         = &'a Deserializer<'a>
     where
         Self: 'a;
@@ -917,7 +969,7 @@ impl<'de> XmlDoctype<'de> for DataWithD<'_, BytesText<'de>> {
         self.data.deref()
     }
 
-    fn namespace_context(&self) -> Self::NamespaceContext<'_> {
+    fn context(&self) -> Self::DeserializeContext<'_> {
         self.deserializer
     }
 }

xmlity-quick-xml/src/ser.rs

@@ -37,7 +37,7 @@ pub enum Error {
 
 impl xmlity::ser::Error for Error {
     fn unexpected_serialize(unexpected: ser::Unexpected) -> Self {
-        Error::Custom(format!("Unexpected serialize: {:?}", unexpected))
+        Error::Custom(format!("Unexpected serialize: {unexpected:?}"))
     }
 
     fn custom<T: ToString>(msg: T) -> Self {

xmlity-quick-xml/tests/elements/namespace_access.rs

@@ -1,4 +1,4 @@
-use xmlity::de::NamespaceContext;
+use xmlity::de::DeserializeContext;
 
 use crate::define_deserialize_test;
 use xmlity::XmlNamespace;
@@ -24,7 +24,7 @@ impl<'de> Deserialize<'de> for InternalReference {
                 })?;
 
                 let namespace = value
-                    .namespace_context()
+                    .context()
                     .resolve_prefix(prefix.as_ref())
                     .ok_or_else(|| E::custom(format!("Prefix {prefix:?} is not defined")))?
                     .into_owned();
@@ -72,7 +72,7 @@ impl<'de> Deserialize<'de> for DefaultNamespace {
                 V: xmlity::de::XmlText<'de>,
             {
                 let namespace = value
-                    .namespace_context()
+                    .context()
                     .default_namespace()
                     .map(XmlNamespace::into_owned);