xso/dynxso/

linktime.rs

use alloc::boxed::Box;
use core::{cmp::Ordering, marker::PhantomData};

use crate::{
    dynxso::MayContain,
    error::{Error, FromEventsError},
    fromxml::XmlNameMatcher,
    Context, FromEventsBuilder, FromXml,
};

/// Dynamic XSO traits using a link-time registry
///
/// This macro is used for (a) declaring [`DynXso`][`crate::dynxso::DynXso`]
/// traits using a registry filled at link-time and (b) for registering types
/// with a trait.
///
/// ## Declaring a link-time `DynXso` trait
///
/// To declare a trait as a link-time `DynXso` trait, wrap its declaration in
/// a `linktime!` invocation.
///
/// ### Example
///
/// ```rust
/// use xso::{dynxso::linktime, asxml::AsXmlDyn};
///
/// linktime! {
///     pub trait MyPayload: AsXmlDyn {}
/// }
/// ```
///
/// ### Usage notes
///
/// - A bound on [`Any`][`core::any::Any`] is automatically added, because it
///   is a requirement for implementing [`DynXso`][`crate::dynxso::DynXso`]
///   on `dyn Trait`.
/// - If you want to specify more than one trait bound, you have to separate
///   them with `,` instead of `+`, due to rustc limitations with declarative
///   macros.
/// - A trait bound on [`AsXmlDyn`][`crate::asxml::AsXmlDyn`] is required (but
///   has to be added manually, as seen in the above example) for
///   [`Xso<dyn Trait>`][`crate::dynxso::Xso`] to implement
///   [`AsXml`][`crate::AsXml`].
/// - This macro automatically calls [`crate::derive_dyn_traits!`], but does
///   not use the default `BuilderRegistry`, removing the `std` dependency at
///   the cost of being unable to register more types at runtime.
///
/// ## Implement a `DynXso` trait
///
/// To implement a trait declared with `linktime!`, wrap the `impl` block in
/// a `linktime!` invocation.
///
/// Doing so allows a [`Xso<dyn Trait>`][`crate::dynxso::Xso`]'s [`FromXml`]
/// implementation to parse the registered type.
///
/// ### Example
///
#[cfg_attr(
    not(feature = "macros"),
    doc = "Because the macros feature was not enabled at doc build time, the example cannot be tested.\n\n```ignore\n"
)]
#[cfg_attr(feature = "macros", doc = "\n```\n")]
/// use xso::{dynxso::{linktime, Xso}, FromXml, AsXml, asxml::AsXmlDyn, from_bytes};
///
/// linktime! {
///     trait Foo: AsXmlDyn {}
/// }
///
/// #[derive(FromXml, AsXml, Debug, Clone, Copy)]
/// #[xml(namespace = "urn:example", name = "a")]
/// struct A {}
///
/// #[derive(FromXml, AsXml, Debug, Clone, Copy)]
/// #[xml(namespace = "urn:example", name = "b")]
/// struct B {}
///
/// linktime! {
///     impl Foo for A {}
///     impl Foo for B {}
/// }
///
/// let foo: Xso<dyn Foo> = from_bytes(b"<a xmlns='urn:example'/>").unwrap();
/// let foo: Xso<dyn Foo> = from_bytes(b"<b xmlns='urn:example'/>").unwrap();
/// ```
///
/// ### Usage notes
///
/// - `linktime!` can be placed anywhere; unlike the `Xso::register_type`
///   calls needed with the
///   [`BuilderRegistry`][`crate::dynxso::BuilderRegistry`], registrations are
///   handled at compile-time (or more precisely: at link-time, with a minimal
///   startup overhead of postprocessing the list generated by the linker).
#[doc(hidden)]
#[macro_export]
macro_rules! __linktime {
    // First variant: declaring a trait.
    (
        $(
            $(#[$meta:meta])*
            $vis:vis trait $trait:ident $(: $bound:path $(, $bound2:path)*)? {
                $($item:item)*
            }
        )*
    ) => {
        $(
            // Just "copy" the trait decl over, but add the mandatory bound on
            // Any.
            $(#[$meta])*
            $vis trait $trait: core::any::Any $(+ $bound $(+ $bound2)*)? {
                $($item)*
            }

            $crate::exports::paste::paste! {
                #[doc = concat!("Link-time type registry for ", stringify!($trait), ".\n\nGenerated by the `linktime!` macro in the `xso` crate.")]
                #[doc(hidden)]
                $vis struct [<$trait LinktimeRegistry>]();

                $crate::exports::scattered_collect::declarative::gather! {
                    #[gather]
                    #[doc = concat!("Link-time type registry data for ", stringify!($trait), ".\n\nGenerated by the `linktime!` macro in the `xso` crate.")]
                    #[doc(hidden)]
                    $vis static [<$trait:upper _LINKTIME_REGISTRY_DATA>]: $crate::exports::scattered_collect::ScatteredSortedSlice<
                        $crate::dynxso::linktime::BuilderRegistryEntry<dyn $trait>
                    >;
                }

                impl $crate::dynxso::registry::DynXsoRegistryLookup<dyn $trait> for [<$trait LinktimeRegistry>] {
                    fn make_builder(
                        &self,
                        name: $crate::exports::rxml::QName,
                        attrs: $crate::exports::rxml::AttrMap,
                        ctx: &$crate::Context<'_>,
                    ) -> Result<
                        Box<dyn $crate::FromEventsBuilder<Output = Box<dyn $trait>>>,
                        $crate::error::FromEventsError,
                    > {
                        let registry = &[<$trait:upper _LINKTIME_REGISTRY_DATA>][..];
                        $crate::dynxso::linktime::make_builder(registry, name, attrs, ctx)
                    }
                }

                // This is a fun trick!
                //
                // You'd think that that wouldn't work, because statics and traits
                // cannot share the same name, but in fact, they can! And the
                // particularly good thing about this is that macros can, too,
                // because what is *actually* relevant is the macro, not the
                // static: the scatter! macro needs access to a hidden macro
                // generated by the gather! trait and named exactly like the
                // registry static.
                $vis use [<$trait:upper _LINKTIME_REGISTRY_DATA>] as $trait;

                $crate::derive_dyn_traits!(
                    $trait
                    use [<$trait LinktimeRegistry>] = [<$trait LinktimeRegistry>]()
                );
            }
        )*
    };

    // Second variant: Implementing a trait.
    (
        $(
            $(#[$meta:meta])*
            impl $trait_seg1:ident $(:: $trait_segn:ident)* for $ty:ty {
                $($item:item)*
            }
        )*
    ) => {
        $(
            // Just "copy" the `impl` block over.
            impl $trait_seg1 $(:: $trait_segn)* for $ty {
                $($item)*
            }

            $crate::exports::scattered_collect::declarative::scatter! {
                // Register the type using linker magic.
                //
                // The `scatter!` macro invocation needs us to pass the
                // `static` we declared above with the `gather!` macro (well,
                // in fact it needs the macro which overloads the `static`).
                #[scatter($trait_seg1 $(:: $trait_segn)*)]
                const _: $crate::dynxso::linktime::BuilderRegistryEntry<dyn $trait_seg1 $(:: $trait_segn)*> = $crate::dynxso::linktime::BuilderRegistryEntry {
                    matcher: <$ty as $crate::FromXml>::XML_NAME_MATCHER,
                    builder: $crate::dynxso::linktime::build_boxed::<$ty, dyn $trait_seg1 $(:: $trait_segn)*>,
                };
            }
        )*
    }
}

/// A function to attempt to construct a specific XSO.
///
/// This can be used as a type-erased [`FromXml::from_events`] if `T` is a
/// `dyn Trait`.
///
/// **NOT** part of the public API -- only exposed for use by macros.
#[doc(hidden)]
pub type Builder<T> = fn(
    rxml::QName,
    rxml::AttrMap,
    &Context<'_>,
) -> Result<Box<dyn FromEventsBuilder<Output = Box<T>>>, FromEventsError>;

/// Entry in a linktime registry of builder functions for `T`.
///
/// **NOT** part of the public API -- only exposed for use by macros.
#[doc(hidden)]
pub struct BuilderRegistryEntry<T: ?Sized> {
    pub matcher: XmlNameMatcher<'static>,
    pub builder: Builder<T>,
}

impl<T: ?Sized> PartialEq for BuilderRegistryEntry<T> {
    fn eq(&self, other: &Self) -> bool {
        (self.matcher, self.builder) == (other.matcher, other.builder)
    }
}

impl<T: ?Sized> Eq for BuilderRegistryEntry<T> {}

impl<T: ?Sized> Ord for BuilderRegistryEntry<T> {
    fn cmp(&self, other: &Self) -> Ordering {
        (&self.matcher, self.builder).cmp(&(&other.matcher, other.builder))
    }
}

impl<T: ?Sized> PartialOrd for BuilderRegistryEntry<T> {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

/// Look up builders matching the result of `matcher_builder` in `registry`
/// and try initialising them in the order they are in the registry.
///
/// If a builder returns [`FromEventsError::Invalid`], that error is propagated
/// immediately. If a builder returns [`FromEventsError::Mismatch`], the next
/// matching builder is tried. If there are no more matching builders, the
/// function returns the `Mismatch` error.
///
/// `matcher_builder` is a closure instead of an argument, because we want to
/// borrow from the `name`, which must be passed by value to `from_events`.
fn try_build<T: ?Sized>(
    registry: &[BuilderRegistryEntry<T>],
    mut name: rxml::QName,
    mut attrs: rxml::AttrMap,
    ctx: &Context<'_>,
    matcher_builder: impl for<'x> FnOnce(&'x rxml::QName) -> XmlNameMatcher<'x>,
) -> Result<Box<dyn FromEventsBuilder<Output = Box<T>>>, FromEventsError> {
    let matcher = matcher_builder(&name);
    let start_scan_at = registry.partition_point(|entry| entry.matcher < matcher);
    let end_scan_at = registry.partition_point(|entry| entry.matcher >= matcher);

    for entry in &registry[start_scan_at..end_scan_at] {
        if !entry.matcher.matches(&name) {
            return Err(FromEventsError::Mismatch { name, attrs });
        }

        match (entry.builder)(name, attrs, ctx) {
            Ok(v) => return Ok(v),
            Err(FromEventsError::Invalid(e)) => return Err(FromEventsError::Invalid(e)),
            Err(FromEventsError::Mismatch {
                name: new_name,
                attrs: new_attrs,
            }) => {
                name = new_name;
                attrs = new_attrs;
            }
        }
    }

    Err(FromEventsError::Mismatch { name, attrs })
}

/// Find and start a builder matching the given `name` and `attrs` from the
/// `registry`.
///
/// **NOT** part of the public API -- only exposed for use by macros.
#[doc(hidden)]
pub fn make_builder<T: ?Sized>(
    registry: &[BuilderRegistryEntry<T>],
    name: rxml::QName,
    attrs: rxml::AttrMap,
    ctx: &Context<'_>,
) -> Result<Box<dyn FromEventsBuilder<Output = Box<T>>>, FromEventsError> {
    let (name, attrs) = match try_build(registry, name, attrs, ctx, |qname| {
        XmlNameMatcher::Specific(qname.0.as_str(), qname.1.as_str())
    }) {
        Ok(v) => return Ok(v),
        Err(FromEventsError::Invalid(e)) => return Err(FromEventsError::Invalid(e)),
        Err(FromEventsError::Mismatch { name, attrs }) => (name, attrs),
    };

    let (name, attrs) = match try_build(registry, name, attrs, ctx, |qname| {
        XmlNameMatcher::InNamespace(qname.0.as_str())
    }) {
        Ok(v) => return Ok(v),
        Err(FromEventsError::Invalid(e)) => return Err(FromEventsError::Invalid(e)),
        Err(FromEventsError::Mismatch { name, attrs }) => (name, attrs),
    };

    try_build(registry, name, attrs, ctx, |_| XmlNameMatcher::Any)
}

/// Build a `U` using its [`FromXml`] implementation and return it as `Box<T>`.
///
/// **NOT** part of the public API -- only exposed for use by macros.
#[doc(hidden)]
pub fn build_boxed<U: FromXml + 'static, T: ?Sized + 'static>(
    name: rxml::QName,
    attrs: rxml::AttrMap,
    ctx: &Context<'_>,
) -> Result<Box<dyn crate::FromEventsBuilder<Output = Box<T>>>, FromEventsError>
where
    T: super::MayContain<U>,
{
    struct Wrapper<B, X: ?Sized> {
        inner: B,
        output: PhantomData<X>,
    }

    impl<X: ?Sized, O, B: FromEventsBuilder<Output = O>> FromEventsBuilder for Wrapper<B, X>
    where
        X: MayContain<O>,
    {
        type Output = Box<X>;

        fn feed(
            &mut self,
            ev: rxml::Event,
            ctx: &Context<'_>,
        ) -> Result<Option<Self::Output>, Error> {
            self.inner
                .feed(ev, ctx)
                .map(|x| x.map(|x| <X as MayContain<O>>::upcast_into(x)))
        }
    }

    <U as crate::FromXml>::from_events(name, attrs, ctx).map(|builder| {
        Box::new(Wrapper {
            inner: builder,
            output: PhantomData,
        }) as Box<dyn FromEventsBuilder<Output = Box<T>>>
    })
}