Analogous to the already existing `IntoXml` implementation helpers
based on an `Into<Element>` implementation on a type, this provides
the utilities for `AsXml`.
This is of course exceptionally inefficient, but it is only needed
transitionally until we have everything migrated to derive macros or
otherwise rewritten in terms of AsXml/FromXml.
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.
Paths are already patched in the workspace's [patch.crates-io] block.
Not sure why this was added in the first place.
Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
By defining the variables in the parent scope, we can avoid one level of
indentation for the tuple, which makes things more readable.
Additionally, we don’t need to call .to_str() on the passed objects,
they automatically Deref to &str for the format!() call.
This depends on XEP-0313 for its MAM metadata, and many others such as
XEP-0198, XEP-0280 and XEP-0352 for the inline features, but we
currently provide those as minidom Elements instead.
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.
Previously, we only enforced the existence of at most one `#[xml(text)]`
field only at code generation time for `FromXml`. This change enforces
it at parsing time, which is more consistent and allows for a clearer
error message.
This specification defines a token-based method to streamline
authentication in XMPP, allowing fully authenticated stream
establishment within a single round-trip.
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 more in line with how we handle closely coupled specifications
already. While there are subdirectories for "large" specifications (such
as MUC and PubSub), those only refer to a single XEP document. When
there are multiple separate XEP documents, we have separate modules for
that.
