pep/xmpp-rs-mirror
1
0
Fork 0
mirror of https://gitlab.com/xmpp-rs/xmpp-rs.git synced 2024-07-12 22:21:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

document all the things!

Browse source
This commit is contained in:
lumi 2017-02-21 15:46:06 +01:00
parent e0b35477cd
commit 0a45a6993e
4 changed files with 334 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
examples/articles.rs Normal file
View file

@ -0,0 +1,45 @@
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);
}

19
src/attribute.rs
View file

@ -2,9 +2,16 @@ use xml::escape::escape_str_attribute;
use std::fmt;
/// An attribute of a DOM element.
///
/// This is of the form: `name`="`value`"
///
/// This does not support prefixed/namespaced attributes yet.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Attribute {
/// The name of the attribute.
pub name: String,
/// The value of the attribute.
pub value: String,
}
@ -15,6 +22,18 @@ impl fmt::Display for Attribute {
}
impl Attribute {
/// Construct a new attribute from the given `name` and `value`.
///
/// # Examples
///
/// ```
/// use minidom::Attribute;
///
/// let attr = Attribute::new("name", "value");
///
/// assert_eq!(attr.name, "name");
/// assert_eq!(attr.value, "value");
/// ```
pub fn new<N: Into<String>, V: Into<String>>(name: N, value: V) -> Attribute {
Attribute {
name: name.into(),

1
src/error.rs
View file

@ -5,6 +5,7 @@ use std::convert::From;
use xml::writer::Error as WriterError;
use xml::reader::Error as ReaderError;
/// An enum representing the possible errors.
#[derive(Debug)]
pub enum Error {
IoError(io::Error),

274
src/lib.rs
View file

@ -1,9 +1,76 @@
//! A minimal DOM crate built on top of xml-rs.
//!
//! This library exports an `Element` struct which represents a DOM tree.
//!
//! # Example
//!
//! Run with `cargo run --example articles`. Located in `examples/articles.rs`.
//!
//! ```rust,ignore
//! 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`:
//!
//! ```toml,ignore
//! [dependencies.minidom]
//! git = "https://gitlab.com/lumi/minidom-rs.git"
//! ```
extern crate xml;
pub mod error;
pub mod attribute;
mod error;
mod attribute;
use std::io::prelude::*;
use std::io::Cursor;
use std::convert::AsRef;
@ -13,16 +80,19 @@ use std::slice;
use std::fmt;
use std::str::FromStr;
use xml::reader::{XmlEvent as ReaderEvent, EventReader};
use xml::writer::{XmlEvent as WriterEvent, EventWriter};
use xml::name::Name;
use xml::namespace::NS_NO_PREFIX;
use error::Error;
pub use error::Error;
use attribute::Attribute;
pub use attribute::Attribute;
#[derive(Clone, PartialEq, Eq)]
/// A struct representing a DOM Element.
pub struct Element {
name: String,
namespace: Option<String>,
@ -57,13 +127,40 @@ impl fmt::Debug for Element {
}
}
impl FromStr for Element {
type Err = Error;
fn from_str(s: &str) -> Result<Element, Error> {
let mut reader = EventReader::new(Cursor::new(s));
Element::from_reader(&mut reader)
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Fork {
enum Fork {
Element(Element),
Text(String),
}
impl Element {
/// Constructs a new `Element` with the given `name`, `namespace` and `attributes`.
///
/// You probably should be using `Element::builder` instead of this.
///
/// # Examples
///
/// ```
/// use minidom::{Element, Attribute};
///
/// let elem = Element::new( "name".to_owned()
/// , Some("namespace".to_owned())
/// , vec![ Attribute::new("name", "value") ] );
///
/// assert_eq!(elem.name(), "name");
/// assert_eq!(elem.ns(), Some("namespace"));
/// assert_eq!(elem.attr("name"), Some("value"));
/// assert_eq!(elem.attr("inexistent"), None);
/// ```
pub fn new(name: String, namespace: Option<String>, attributes: Vec<Attribute>) -> Element {
Element {
name: name,
@ -73,6 +170,25 @@ impl Element {
}
}
/// Return a builder for an `Element` with the given `name`.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let elem = Element::builder("name")
/// .ns("namespace")
/// .attr("name", "value")
/// .text("inner")
/// .build();
///
/// assert_eq!(elem.name(), "name");
/// assert_eq!(elem.ns(), Some("namespace"));
/// assert_eq!(elem.attr("name"), Some("value"));
/// assert_eq!(elem.attr("inexistent"), None);
/// assert_eq!(elem.text(), "inner");
/// ```
pub fn builder<S: Into<String>>(name: S) -> ElementBuilder {
ElementBuilder {
name: name.into(),
@ -82,15 +198,41 @@ impl Element {
}
}
/// Returns a bare minimum `Element` with this name.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let bare = Element::bare("name");
///
/// assert_eq!(bare.name(), "name");
/// assert_eq!(bare.ns(), None);
/// assert_eq!(bare.attr("name"), None);
/// assert_eq!(bare.text(), "");
/// ```
pub fn bare<S: Into<String>>(name: S) -> Element {
Element {
name: name.into(),
namespace: None,
attributes: Vec::new(),
children: Vec::new(),
}
}
/// Returns a reference to the name of this element.
pub fn name(&self) -> &str {
&self.name
}
/// Returns a reference to the namespace of this element, if it has one, else `None`.
pub fn ns(&self) -> Option<&str> {
self.namespace.as_ref()
.map(String::as_ref)
}
/// Returns a reference to the value of the given attribute, if it exists, else `None`.
pub fn attr(&self, name: &str) -> Option<&str> {
for attr in &self.attributes {
if attr.name == name {
@ -100,6 +242,20 @@ impl Element {
None
}
/// Returns whether the element has the given name and namespace.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let elem = Element::builder("name").ns("namespace").build();
///
/// assert_eq!(elem.is("name", "namespace"), true);
/// assert_eq!(elem.is("name", "wrong"), false);
/// assert_eq!(elem.is("wrong", "namespace"), false);
/// assert_eq!(elem.is("wrong", "wrong"), false);
/// ```
pub fn is<N: AsRef<str>, NS: AsRef<str>>(&self, name: N, namespace: NS) -> bool {
let ns = self.namespace.as_ref().map(String::as_ref);
self.name == name.as_ref() && ns == Some(namespace.as_ref())
@ -196,18 +352,57 @@ impl Element {
Ok(())
}
/// Returns an iterator over references to the children of this element.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let elem: Element = "<root><child1 /><child2 /><child3 /></root>".parse().unwrap();
///
/// let mut iter = elem.children();
/// assert_eq!(iter.next().unwrap().name(), "child1");
/// assert_eq!(iter.next().unwrap().name(), "child2");
/// assert_eq!(iter.next().unwrap().name(), "child3");
/// assert_eq!(iter.next(), None);
/// ```
pub fn children<'a>(&'a self) -> Children<'a> {
Children {
iter: self.children.iter(),
}
}
/// Returns an iterator over mutable references to the children of this element.
pub fn children_mut<'a>(&'a mut self) -> ChildrenMut<'a> {
ChildrenMut {
iter: self.children.iter_mut(),
}
}
/// Appends a child node to the `Element`, returning the appended node.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let mut elem = Element::bare("root");
///
/// assert_eq!(elem.children().count(), 0);
///
/// elem.append_child(Element::bare("child"));
///
/// {
/// let mut iter = elem.children();
/// assert_eq!(iter.next().unwrap().name(), "child");
/// assert_eq!(iter.next(), None);
/// }
///
/// let child = elem.append_child(Element::bare("new"));
///
/// assert_eq!(child.name(), "new");
/// ```
pub fn append_child(&mut self, mut child: Element) -> &mut Element {
if child.namespace.is_none() {
child.namespace = self.namespace.clone();
@ -221,10 +416,36 @@ impl Element {
}
}
/// Appends a text node to an `Element`.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let mut elem = Element::bare("node");
///
/// assert_eq!(elem.text(), "");
///
/// elem.append_text_node("text");
///
/// assert_eq!(elem.text(), "text");
/// ```
pub fn append_text_node<S: Into<String>>(&mut self, child: S) {
self.children.push(Fork::Text(child.into()));
}
/// Returns the concatenation of all text nodes in the `Element`.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let elem: Element = "<node>hello, world!</node>".parse().unwrap();
///
/// assert_eq!(elem.text(), "hello, world!");
/// ```
pub fn text(&self) -> String {
let mut ret = String::new();
for fork in &self.children {
@ -235,6 +456,23 @@ impl Element {
ret
}
/// Returns a reference to the first child element with the specific name and namespace, if it
/// exists in the direct descendants of this `Element`, else returns `None`.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let elem: Element = r#"<node xmlns="ns"><a /><a xmlns="other_ns" /><b /></node>"#.parse().unwrap();
///
/// assert!(elem.get_child("a", "ns").unwrap().is("a", "ns"));
/// assert!(elem.get_child("a", "other_ns").unwrap().is("a", "other_ns"));
/// assert!(elem.get_child("b", "ns").unwrap().is("b", "ns"));
/// assert_eq!(elem.get_child("c", "ns"), None);
/// assert_eq!(elem.get_child("b", "other_ns"), None);
/// assert_eq!(elem.get_child("a", "inexistent_ns"), None);
/// ```
pub fn get_child<N: AsRef<str>, NS: AsRef<str>>(&self, name: N, namespace: NS) -> Option<&Element> {
for fork in &self.children {
if let Fork::Element(ref e) = *fork {
@ -246,6 +484,8 @@ impl Element {
None
}
/// Returns a mutable reference to the first child element with the specific name and namespace,
/// if it exists in the direct descendants of this `Element`, else returns `None`.
pub fn get_child_mut<N: AsRef<str>, NS: AsRef<str>>(&mut self, name: N, namespace: NS) -> Option<&mut Element> {
for fork in &mut self.children {
if let Fork::Element(ref mut e) = *fork {
@ -257,11 +497,29 @@ impl Element {
None
}
/// Returns whether a specific child with this name and namespace exists in the direct
/// descendants of the `Element`.
///
/// # Examples
///
/// ```
/// use minidom::Element;
///
/// let elem: Element = r#"<node xmlns="ns"><a /><a xmlns="other_ns" /><b /></node>"#.parse().unwrap();
///
/// assert_eq!(elem.has_child("a", "other_ns"), true);
/// assert_eq!(elem.has_child("a", "ns"), true);
/// assert_eq!(elem.has_child("a", "inexistent_ns"), false);
/// assert_eq!(elem.has_child("b", "ns"), true);
/// assert_eq!(elem.has_child("b", "other_ns"), false);
/// assert_eq!(elem.has_child("b", "inexistent_ns"), false);
/// ```
pub fn has_child<N: AsRef<str>, NS: AsRef<str>>(&self, name: N, namespace: NS) -> bool {
self.get_child(name, namespace).is_some()
}
}
/// An iterator over references to children of an `Element`.
pub struct Children<'a> {
iter: slice::Iter<'a, Fork>,
}
@ -279,6 +537,7 @@ impl<'a> Iterator for Children<'a> {
}
}
/// An iterator over mutable references to children of an `Element`.
pub struct ChildrenMut<'a> {
iter: slice::IterMut<'a, Fork>,
}
@ -296,6 +555,7 @@ impl<'a> Iterator for ChildrenMut<'a> {
}
}
/// A builder for `Element`s.
pub struct ElementBuilder {
name: String,
text: Option<String>,
@ -304,21 +564,25 @@ pub struct ElementBuilder {
}
impl ElementBuilder {
/// Sets the namespace.
pub fn ns<S: Into<String>>(mut self, namespace: S) -> ElementBuilder {
self.namespace = Some(namespace.into());
self
}
/// Sets an attribute.
pub fn attr<S: Into<String>, V: Into<String>>(mut self, name: S, value: V) -> ElementBuilder {
self.attributes.push(Attribute::new(name, value));
self
}
/// Sets the inner text.
pub fn text<S: Into<String>>(mut self, text: S) -> ElementBuilder {
self.text = Some(text.into());
self
}
/// Builds the `Element`.
pub fn build(self) -> Element {
let mut elem = Element::new(self.name, self.namespace, self.attributes);
if let Some(text) = self.text {