Module dynxso 

Dynamically-typed XSOs

This module provides the utilities to make dynamically-typed XSOs work. Dynamically typed XSOs are for example contained in Xso<dyn Trait> or XsoVec<dyn Trait>, where Trait is a trait provided and defined by the user.

The given Trait constrains the specific types which can be used in the Xso<dyn Trait> box. This allows users to provide additional methods on the trait which are available on all Xso<dyn Trait> objects via the Deref and DerefMut implementations.

Xso<dyn Trait> (and also XsoVec<dyn Trait>) can be parsed from XML and serialised to XML, provided some constraints are fulfilled.

For serialisation, the Trait must have a bound on AsXmlDyn, requiring all implementors of the trait to implement AsXml.

For parsing, all implementations of the trait must register themselves with the trait so that the FromXml implementation knows about them and can use them to parse the XML data. How this is done is depends on the way the trait is declared.

XSO supports three ways of doing so:

1. Using the linktime macro (requiring the linktime crate feature) strictly at compile-time / linking-time of the final application binary.

   This is the recommended way as it incurs a very low runtime overhead and does not depend on std either.

2. Using the std-based BuilderRegistry through the xso_trait macro.

3. Using a custom registry through the xso_trait macro.

Please refer to the linked macros for usage details and examples.

Dynamically-typed XSOs vs. enums

One key question you should ask yourself when looking at this module and before going down the route of dynamically-typed XSOs is: “Is an enum enough for my use-case?”

The key difference between dynamically-typed XSOs and enums is that enums cannot be extended by other crates, or even outside the source file they are declared in. Dynamically-typed XSOs can be extended by any code place where a trait implementation of that dynamic XSO trait is possible, which is virtually anywhere.

Dynamically-typed XSOs are thus more useful in plugin-like situations or when providing an extension point for other crates. Enums are more useful when you know the exact variants of acceptable XML data. Enums are generally likely to be more performant, as the lookups needed can be hardcoded and arbitrarily optimized by the compiler.

Modules

registry

Helper traits for dynamic XSO builder registries.

xso_vec

Helper types for XsoVec.

Macros

linktimelinktime

Dynamic XSO traits using a link-time registry

xso_trait

Make a trait usable as dynamic XSO trait.

Structs

BuilderRegistrystd

Registry for type-erased FromXml builders which construct T

DynBuilder

Wrapper around a FromEventsBuilder to convert a Box<T> output to a Xso<T> output.

UnboxBuilder

Wrapper around a FromEventsBuilder to convert a Box<T> output to a T output.

Xso

Dynamic XSO container

XsoVec

Container for dynamically-typed XSOs optimized for type-keyed access

Enums

TakeOneError

Error type for retrieving a single item from XsoVec.

Traits

DynXso

Dynamic XSO type

MayContain

Declare that T may be held by Box<Self>