mirror of
https://gitlab.com/xmpp-rs/xmpp-rs.git
synced 2024-07-12 22:21:53 +00:00
A type-safe Rust XMPP library.
1f679c3af7
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). |
||
|---|---|---|
| .forgejo/workflows | ||
| jid | ||
| minidom | ||
| parsers | ||
| sasl | ||
| tokio-xmpp | ||
| xmpp | ||
| xso | ||
| xso-proc | ||
| .gitea | ||
| .github | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| Cargo.toml | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| README.md | ||
xmpp-rs
What's this?
A very much WIP set of rust XMPP library with the goals of being type-safe and well-tested.
xmpp-rsprovides a high-level API for the protocol. You shouldn't need to know about the protocol to use it.tokio-xmppis a lower-level library that handles the XMPP stream(s).xmpp-parsersparses XML into Rust and back.minidomis a DOM library quite specific for XMPPjidis a Jid parsing library.
Contact
There is an XMPP MUC for the discussion of this library, feel free to join! :)
Community
A Code of Conduct is available as CODE_OF_CONDUCT.md in the repository for the well-being of the community. Please refer to it in case of a possible conflict in any of the xmpp-rs venues (channel, forge, etc.).
License
Mozilla Public License 2 (MPL2). See the LICENSE file.
Building
Dependencies should be provided by crates if you use the default features. If
you use tokio-xmpp's tls-native feature you will need an ssl library
(openssl, libressl, etc.).
cargo build
The various features available should be explained in the crates themselves.
Contributing
Thank you for your interest in the project!
Contributing rules are available as CONTRIBUTING.md in the repository.