xmpp-rs/minidom/src/lib.rs

95 lines
2.5 KiB
Rust
Raw Normal View History

// Copyright (c) 2020 lumi <lumi@pew.im>
// Copyright (c) 2020 Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
// Copyright (c) 2020 Bastien Orivel <eijebong+minidom@bananium.fr>
// Copyright (c) 2020 Astro <astro@spaceboyz.net>
// Copyright (c) 2020 Maxime “pep” Buquet <pep@bouah.net>
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
#![deny(missing_docs)]
//! A minimal DOM crate built on top of quick-xml, targeting exclusively the subset of XML useful
//! for XMPP.
2017-02-21 14:46:06 +00:00
//!
//! This library exports an `Element` struct which represents a DOM tree.
//!
//! # Example
//!
//! Run with `cargo run --example articles`. Located in `examples/articles.rs`.
//!
//! ```rust
2017-02-21 14:46:06 +00:00
//! extern crate minidom;
//!
//! use minidom::Element;
//!
//! const DATA: &'static str = r#"<articles xmlns="article">
//! <article>
//! <title>10 Terrible Bugs You Would NEVER Believe Happened</title>
//! <body>
//! Rust fixed them all. &lt;3
//! </body>
//! </article>
//! <article>
//! <title>BREAKING NEWS: Physical Bug Jumps Out Of Programmer's Screen</title>
//! <body>
//! Just kidding!
//! </body>
//! </article>
//! </articles>"#;
//!
//! const ARTICLE_NS: &'static str = "article";
//!
//! #[derive(Debug)]
//! pub struct Article {
//! title: String,
//! body: String,
//! }
//!
//! fn main() {
//! let root: Element = DATA.parse().unwrap();
//!
//! let mut articles: Vec<Article> = Vec::new();
//!
//! for child in root.children() {
//! if child.is("article", ARTICLE_NS) {
//! let title = child.get_child("title", ARTICLE_NS).unwrap().text();
//! let body = child.get_child("body", ARTICLE_NS).unwrap().text();
//! articles.push(Article {
//! title: title,
//! body: body.trim().to_owned(),
//! });
//! }
//! }
//!
//! println!("{:?}", articles);
//! }
//! ```
//!
//! # Usage
//!
//! To use `minidom`, add this to your `Cargo.toml` under `dependencies`:
2017-02-21 14:46:06 +00:00
//!
//! ```toml,ignore
//! minidom = "*"
2017-02-21 14:46:06 +00:00
//! ```
pub use quick_xml;
2017-02-19 19:46:44 +00:00
pub mod convert;
pub mod element;
pub mod error;
minidom: forcing a namespace on Element. Stop requiring prefixes. Below is what I think I did. A few changes: - Change prefixes to be something less important in the API. - Rework the Element struct to force a namespace. In XMPP everything is namespaced. - Remove parent ref on what was previously NamespaceSet and is now Prefixes. More specifically this means `Element::new` has changed to require `Element`'s new new properties as parameters. `Element::builder` and `Element::bare` now require a namespace unconditionally. `Element::prefix` has been removed. This new API is based on the fact that prefixes are non-essential (really just an implementation detail) and shouldn't be visible to the user. It is possible nonetheless to set custom prefixes for compatibility reasons with `ElementBuilder::prefix`. **A prefix is firstly mapped to a namespace, and then attached to an element**, there cannot be a prefix without a namespace. Prefix inheritance is used if possible but for the case with no prefix ("xmlns") to be reused, we only check custom prefixes declared on the tag itself and not ascendants. If it's already used then we generate prefixes (ns0, ns1, ..) checking on what has been declared on all ascendants (plus of course those already set on the current tag). Example API: ```rust let mut elem = ElementBuilder("stream", "http://etherx.jabber.org/streams") .prefix(Some(String::from("stream")), "http://etherx.jabber.org/streams) .prefix(None, "jabber:client") .attr(..) .build(); assert_eq!(elem.ns(), String::from("http://etherx.jabber.org/streams")); ``` See also the few tests added in src/tests. TODO: Fix inconsistencies wrt. "prefix:name" format provided as a name when creating an Element with `Element::new` or `Element::bare`. `Element::builder` already handles this as it should, splitting name and prefix. TODO: Change `Element::name` method to `Element::local_name` to make it more explicit. Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
2020-03-27 12:45:22 +00:00
mod namespaces;
pub mod node;
mod prefixes;
2017-02-19 19:46:44 +00:00
#[cfg(test)]
mod tests;
2017-02-19 19:46:44 +00:00
pub use convert::IntoAttributeValue;
pub use element::{Children, ChildrenMut, Element, ElementBuilder};
pub use error::{Error, Result};
minidom: forcing a namespace on Element. Stop requiring prefixes. Below is what I think I did. A few changes: - Change prefixes to be something less important in the API. - Rework the Element struct to force a namespace. In XMPP everything is namespaced. - Remove parent ref on what was previously NamespaceSet and is now Prefixes. More specifically this means `Element::new` has changed to require `Element`'s new new properties as parameters. `Element::builder` and `Element::bare` now require a namespace unconditionally. `Element::prefix` has been removed. This new API is based on the fact that prefixes are non-essential (really just an implementation detail) and shouldn't be visible to the user. It is possible nonetheless to set custom prefixes for compatibility reasons with `ElementBuilder::prefix`. **A prefix is firstly mapped to a namespace, and then attached to an element**, there cannot be a prefix without a namespace. Prefix inheritance is used if possible but for the case with no prefix ("xmlns") to be reused, we only check custom prefixes declared on the tag itself and not ascendants. If it's already used then we generate prefixes (ns0, ns1, ..) checking on what has been declared on all ascendants (plus of course those already set on the current tag). Example API: ```rust let mut elem = ElementBuilder("stream", "http://etherx.jabber.org/streams") .prefix(Some(String::from("stream")), "http://etherx.jabber.org/streams) .prefix(None, "jabber:client") .attr(..) .build(); assert_eq!(elem.ns(), String::from("http://etherx.jabber.org/streams")); ``` See also the few tests added in src/tests. TODO: Fix inconsistencies wrt. "prefix:name" format provided as a name when creating an Element with `Element::new` or `Element::bare`. `Element::builder` already handles this as it should, splitting name and prefix. TODO: Change `Element::name` method to `Element::local_name` to make it more explicit. Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
2020-03-27 12:45:22 +00:00
pub use namespaces::NSChoice;
pub use node::Node;