xso-proc: add support for optional children

xso/ChangeLog

@@ -14,7 +14,8 @@ Version NEXT:
         All this is to avoid triggering the camel case lint on the types we
         generate.
     * Added
-      - Support for child elements in derive macros.
+      - Support for child elements in derive macros. Child elements may be
+        wrapped in Option.
 
 Version 0.1.2:
 2024-07-26 Jonas Schäfer <jonas@zombofant.net>

xso/src/from_xml_doc.md

@@ -139,8 +139,19 @@ assert_eq!(foo, Foo {
 #### `child` meta
 
 The `child` meta causes the field to be mapped to a child element of the
-element. It supports no options. The field's type must implement [`FromXml`]
-in order to derive `FromXml` and [`AsXml`] in order to derive `AsXml`.
+element.
+
+| Key | Value type | Description |
+| --- | --- | --- |
+| `default` | flag | If present, an absent child will substitute the default value instead of raising an error. |
+
+The field's type must implement [`FromXml`] in order to derive `FromXml` and
+[`AsXml`] in order to derive `AsXml`.
+
+If `default` is specified and the child is absent in the source, the value
+is generated using [`std::default::Default`], requiring the field type to
+implement the `Default` trait for a `FromXml` derivation. `default` has no
+influence on `AsXml`.
 
 ##### Example
 

xso/src/lib.rs

@@ -83,6 +83,28 @@ pub trait AsXml {
     fn as_xml_iter(&self) -> Result<Self::ItemIter<'_>, self::error::Error>;
 }
 
+/// Helper iterator to convert an `Option<T>` to XML.
+pub struct OptionAsXml<T: Iterator>(Option<T>);
+
+impl<'x, T: Iterator<Item = Result<Item<'x>, self::error::Error>>> Iterator for OptionAsXml<T> {
+    type Item = Result<Item<'x>, self::error::Error>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.0.as_mut()?.next()
+    }
+}
+
+impl<T: AsXml> AsXml for Option<T> {
+    type ItemIter<'x> = OptionAsXml<T::ItemIter<'x>> where T: 'x;
+
+    fn as_xml_iter(&self) -> Result<Self::ItemIter<'_>, self::error::Error> {
+        match self {
+            Some(ref value) => Ok(OptionAsXml(Some(T::as_xml_iter(value)?))),
+            None => Ok(OptionAsXml(None)),
+        }
+    }
+}
+
 /// Trait for a temporary object allowing to construct a struct from
 /// [`rxml::Event`] items.
 ///
@@ -109,6 +131,17 @@ pub trait FromEventsBuilder {
     fn feed(&mut self, ev: rxml::Event) -> Result<Option<Self::Output>, self::error::Error>;
 }
 
+/// Helper struct to construct an `Option<T>` from XML events.
+pub struct OptionBuilder<T: FromEventsBuilder>(T);
+
+impl<T: FromEventsBuilder> FromEventsBuilder for OptionBuilder<T> {
+    type Output = Option<T::Output>;
+
+    fn feed(&mut self, ev: rxml::Event) -> Result<Option<Self::Output>, self::error::Error> {
+        self.0.feed(ev).map(|ok| ok.map(|value| Some(value)))
+    }
+}
+
 /// Trait allowing to construct a struct from a stream of
 /// [`rxml::Event`] items.
 ///
@@ -146,6 +179,17 @@ pub trait FromXml {
     ) -> Result<Self::Builder, self::error::FromEventsError>;
 }
 
+impl<T: FromXml> FromXml for Option<T> {
+    type Builder = OptionBuilder<T::Builder>;
+
+    fn from_events(
+        name: rxml::QName,
+        attrs: rxml::AttrMap,
+    ) -> Result<Self::Builder, self::error::FromEventsError> {
+        Ok(OptionBuilder(T::from_events(name, attrs)?))
+    }
+}
+
 /// Trait allowing to convert XML text to a value.
 ///
 /// This trait is similar to [`std::str::FromStr`], however, due to