This will soon replace the IntoXml trait. The idea here is that we
don't generally need to take ownership of values which are going to
be transformed into XML: most of the time, the XML text is created
by building a string from some more specific type, such as an
integer or an enum. Requiring to clone an entire structure for this
purpose is wasteful.
In other cases, we actually could reference data right from the structs
we are converting to XML. In those cases, assuming that an iterator
always generates owned data would be incorrect, too.
Hence, we introduce a new `Item` type which closely mirrors the
`rxml::Item` type, but where the constituents are `Cow`. In the upcoming
changes, we are going to work toward replacing all uses of `IntoXml`
with `AsXml`, as well as modifying the macros accordingly.
Text codecs allow to customize the conversion of data from/to XML,
in particular in two scenarios:
1. When the type for which the behaviour is to be defined comes from a
foreign crate, preventing the implementation of
FromXmlText/IntoXmlText.
2. When there is not one obvious, or more than one sensible, way to
convert a value to XML text and back.
The traits have undergone a couple iterations and this is what we end up
with. The core issue which makes this entire thing ugly is the
Orphan Rule, preventing some trait implementations relating to types
which haven't been defined in this crate.
In an ideal world, we would implement FromXmlText and IntoXmlText for
all types implementing FromStr and/or fmt::Display.
This comes with two severe issues:
1. Downstream crates cannot chose to have different
parsing/serialisation behaviour for "normal" text vs. xml.
2. We ourselves cannot define a behaviour for `Option<T>`. `Option<T>`
does not implement `FromStr` (nor `Display`), but the standard
library *could* do that at some point, and thus Rust doesn't let us
implement e.g. `FromXmlText for Option<T> where T: FromXmlText`,
if we also implement it on `T: FromStr`.
The second one hurts particularly once we get to optional attributes:
For these, we need to "detect" that the type is in fact `Option<T>`,
because we then need to invoke `FromXmlText` on `T` instead of
`Option<T>`. Unfortunately, we cannot do that: macros operate on token
streams and we have no type information available.
We can of course match on the name `Option`, but that breaks down when
users re-import `Option` under a different name. Even just enumerating
all the possible correct ways of using `Option` from the standard
library (there are more than three) would be a nuisance at best.
Hence, we need *another* trait or at least a specialized implementation
of `FromXmlText for Option<T>`, and we cannot do that if we blanket-impl
`FromXmlText` on `T: FromStr`.
That makes the traits what they are, and introduces the requirement that
we know about any upstream crate which anyone might want to parse from
or to XML. This sucks a lot, but that's the state of the world. We are
late to the party, and we cannot expect everyone to do the same they
have done for `serde` (many crates have a `feature = "serde"` which then
provides Serialize/Deserialize trait impls for their types).
This is a large change and as such, it needs good motivation. Let me
remind you of the ultimate goal: we want a derive macro which allows us
to FromXml/IntoXml, and that derive macro should be usable from
`xmpp_parsers` and other crates.
For that, any code generated by the derive macro mustn't depend on any
code in the `xmpp_parsers` crate, because you cannot name the crate you
are in portably (`xmpp_parsers::..` wouldn't resolve within
`xmpp_parsers`, and `crate::..` would point at other crates if the macro
was used in other crates).
We also want to interoperate with code already implementing
`TryFrom<Element>` and `Into<Element>` on structs. This ultimately
requires that we have an error type which is shared by the two
implementations and that error type must be declared in the `xso` crate
to be usable by the macros.
Thus, we port the error type over to use the type declared in `xso`.
This changes the structure of the error type greatly; I do not think
that `xso` should have to know about all the different types we are
parsing there and they don't deserve special treatment. Wrapping them in
a `Box<dyn ..>` seems more appropriate.
The CI makes that an error anyway, and this allows developers to start
sketching stuff without running into errors all the time (and then
adding `/// TODO` to work around them).
Just like with the builder type, the concrete iterator type on IntoXml
is supposed to be an implementation detail. That allows switching freely
between various ways to generate such a type.
This adds shims which provide FromXml and IntoXml implementations to
*all* macro-generated types in `xmpp_parsers`. Mind that this does not
cover all types in `xmpp_parsers`, but a good share of them.
This is another first step toward real, fully streamed parsing.
This library provides the traits to parse structs from XML and
serialise them into XML without having to buffer the document object
model in memory.
The only implementations it provides are for minidom, basically
providing a lower-level interface to `minidom::Element::from_reader` and
`minidom::Element::to_writer`.
This is the first stepping stone into a world where `xmpp_parsers` can
parse the structs directly from XML.
