1//! Provides an `Element` type, which represents DOM nodes, and a builder to create them with.
2
3use std::io:: Write;
4use std::collections::{btree_map, BTreeMap};
5
6use std::str;
7use std::rc::Rc;
8use std::borrow::Cow;
9
10use error::{Error, Result};
11
12use quick_xml::Reader as EventReader;
13use quick_xml::Writer as EventWriter;
14use quick_xml::events::{Event, BytesStart, BytesEnd, BytesDecl};
15
16use std::io::BufRead;
17
18use std::str::FromStr;
19
20use std::slice;
21
22use convert::IntoAttributeValue;
23use namespace_set::NamespaceSet;
24use node::Node;
25
26/// helper function to escape a `&[u8]` and replace all
27/// xml special characters (<, >, &, ', ") with their corresponding
28/// xml escaped value.
29pub fn escape(raw: &[u8]) -> Cow<[u8]> {
30 let mut escapes: Vec<(usize, &'static [u8])> = Vec::new();
31 let mut bytes = raw.iter();
32 fn to_escape(b: u8) -> bool {
33 match b {
34 b'<' | b'>' | b'\'' | b'&' | b'"' => true,
35 _ => false,
36 }
37 }
38
39 let mut loc = 0;
40 while let Some(i) = bytes.position(|&b| to_escape(b)) {
41 loc += i;
42 match raw[loc] {
43 b'<' => escapes.push((loc, b"<")),
44 b'>' => escapes.push((loc, b">")),
45 b'\'' => escapes.push((loc, b"'")),
46 b'&' => escapes.push((loc, b"&")),
47 b'"' => escapes.push((loc, b""")),
48 _ => unreachable!("Only '<', '>','\', '&' and '\"' are escaped"),
49 }
50 loc += 1;
51 }
52
53 if escapes.is_empty() {
54 Cow::Borrowed(raw)
55 } else {
56 let len = raw.len();
57 let mut v = Vec::with_capacity(len);
58 let mut start = 0;
59 for (i, r) in escapes {
60 v.extend_from_slice(&raw[start..i]);
61 v.extend_from_slice(r);
62 start = i + 1;
63 }
64
65 if start < len {
66 v.extend_from_slice(&raw[start..]);
67 }
68 Cow::Owned(v)
69 }
70}
71
72
73#[derive(Clone, PartialEq, Eq, Debug)]
74/// A struct representing a DOM Element.
75pub struct Element {
76 prefix: Option<String>,
77 name: String,
78 namespaces: Rc<NamespaceSet>,
79 attributes: BTreeMap<String, String>,
80 children: Vec<Node>,
81}
82
83impl<'a> From<&'a Element> for String {
84 fn from(elem: &'a Element) -> String {
85 let mut writer = Vec::new();
86 elem.write_to(&mut writer).unwrap();
87 String::from_utf8(writer).unwrap()
88 }
89}
90
91impl FromStr for Element {
92 type Err = Error;
93
94 fn from_str(s: &str) -> Result<Element> {
95 let mut reader = EventReader::from_str(s);
96 Element::from_reader(&mut reader)
97 }
98}
99
100impl Element {
101 fn new<NS: Into<NamespaceSet>>(name: String, prefix: Option<String>, namespaces: NS, attributes: BTreeMap<String, String>, children: Vec<Node>) -> Element {
102 Element {
103 prefix, name,
104 namespaces: Rc::new(namespaces.into()),
105 attributes,
106 children,
107 }
108 }
109
110 /// Return a builder for an `Element` with the given `name`.
111 ///
112 /// # Examples
113 ///
114 /// ```rust
115 /// use minidom::Element;
116 ///
117 /// let elem = Element::builder("name")
118 /// .ns("namespace")
119 /// .attr("name", "value")
120 /// .append("inner")
121 /// .build();
122 ///
123 /// assert_eq!(elem.name(), "name");
124 /// assert_eq!(elem.ns(), Some("namespace".to_owned()));
125 /// assert_eq!(elem.attr("name"), Some("value"));
126 /// assert_eq!(elem.attr("inexistent"), None);
127 /// assert_eq!(elem.text(), "inner");
128 /// ```
129 pub fn builder<S: AsRef<str>>(name: S) -> ElementBuilder {
130 let (prefix, name) = split_element_name(name).unwrap();
131 ElementBuilder {
132 root: Element::new(name, prefix, None, BTreeMap::new(), Vec::new()),
133 namespaces: Default::default(),
134 }
135 }
136
137 /// Returns a bare minimum `Element` with this name.
138 ///
139 /// # Examples
140 ///
141 /// ```rust
142 /// use minidom::Element;
143 ///
144 /// let bare = Element::bare("name");
145 ///
146 /// assert_eq!(bare.name(), "name");
147 /// assert_eq!(bare.ns(), None);
148 /// assert_eq!(bare.attr("name"), None);
149 /// assert_eq!(bare.text(), "");
150 /// ```
151 pub fn bare<S: Into<String>>(name: S) -> Element {
152 Element {
153 prefix: None,
154 name: name.into(),
155 namespaces: Rc::new(NamespaceSet::default()),
156 attributes: BTreeMap::new(),
157 children: Vec::new(),
158 }
159 }
160
161 /// Returns a reference to the name of this element.
162 pub fn name(&self) -> &str {
163 &self.name
164 }
165
166 /// Returns a reference to the prefix of this element.
167 ///
168 /// # Examples
169 /// ```rust
170 /// use minidom::Element;
171 ///
172 /// let elem = Element::builder("prefix:name")
173 /// .build();
174 ///
175 /// assert_eq!(elem.name(), "name");
176 /// assert_eq!(elem.prefix(), Some("prefix"));
177 /// ```
178 pub fn prefix(&self) -> Option<&str> {
179 self.prefix.as_ref().map(String::as_ref)
180 }
181
182 /// Returns a reference to the namespace of this element, if it has one, else `None`.
183 pub fn ns(&self) -> Option<String> {
184 self.namespaces.get(&self.prefix)
185 }
186
187 /// Returns a reference to the value of the given attribute, if it exists, else `None`.
188 pub fn attr(&self, name: &str) -> Option<&str> {
189 if let Some(value) = self.attributes.get(name) {
190 return Some(value)
191 }
192 None
193 }
194
195 /// Returns an iterator over the attributes of this element.
196 ///
197 /// # Example
198 ///
199 /// ```rust
200 /// use minidom::Element;
201 ///
202 /// let elm: Element = "<elem a=\"b\" />".parse().unwrap();
203 ///
204 /// let mut iter = elm.attrs();
205 ///
206 /// assert_eq!(iter.next().unwrap(), ("a", "b"));
207 /// assert_eq!(iter.next(), None);
208 /// ```
209 pub fn attrs(&self) -> Attrs {
210 Attrs {
211 iter: self.attributes.iter(),
212 }
213 }
214
215 /// Returns an iterator over the attributes of this element, with the value being a mutable
216 /// reference.
217 pub fn attrs_mut(&mut self) -> AttrsMut {
218 AttrsMut {
219 iter: self.attributes.iter_mut(),
220 }
221 }
222
223 /// Modifies the value of an attribute.
224 pub fn set_attr<S: Into<String>, V: IntoAttributeValue>(&mut self, name: S, val: V) {
225 let name = name.into();
226 let val = val.into_attribute_value();
227
228 if let Some(value) = self.attributes.get_mut(&name) {
229 *value = val.expect("removing existing value via set_attr, this is not yet supported (TODO)"); // TODO
230 return;
231 }
232
233 if let Some(val) = val {
234 self.attributes.insert(name, val);
235 }
236 }
237
238 /// Returns whether the element has the given name and namespace.
239 ///
240 /// # Examples
241 ///
242 /// ```rust
243 /// use minidom::Element;
244 ///
245 /// let elem = Element::builder("name").ns("namespace").build();
246 ///
247 /// assert_eq!(elem.is("name", "namespace"), true);
248 /// assert_eq!(elem.is("name", "wrong"), false);
249 /// assert_eq!(elem.is("wrong", "namespace"), false);
250 /// assert_eq!(elem.is("wrong", "wrong"), false);
251 /// ```
252 pub fn is<N: AsRef<str>, NS: AsRef<str>>(&self, name: N, namespace: NS) -> bool {
253 self.name == name.as_ref() &&
254 self.has_ns(namespace)
255 }
256
257 /// Returns whether the element has the given namespace.
258 ///
259 /// # Examples
260 ///
261 /// ```rust
262 /// use minidom::Element;
263 ///
264 /// let elem = Element::builder("name").ns("namespace").build();
265 ///
266 /// assert_eq!(elem.has_ns("namespace"), true);
267 /// assert_eq!(elem.has_ns("wrong"), false);
268 /// ```
269 pub fn has_ns<NS: AsRef<str>>(&self, namespace: NS) -> bool {
270 self.namespaces.has(&self.prefix, namespace)
271 }
272
273 /// Parse a document from an `EventReader`.
274 pub fn from_reader<R: BufRead>(reader: &mut EventReader<R>) -> Result<Element> {
275 let mut buf = Vec::new();
276
277 let root: Element = loop {
278 let e = reader.read_event(&mut buf)?;
279 match e {
280 Event::Empty(ref e) | Event::Start(ref e) => {
281 break build_element(reader, e)?;
282 },
283 Event::Eof => {
284 return Err(Error::EndOfDocument);
285 },
286 #[cfg(not(feature = "comments"))]
287 Event::Comment { .. } => {
288 return Err(Error::CommentsDisabled);
289 }
290 #[cfg(feature = "comments")]
291 Event::Comment { .. } => (),
292 Event::Text { .. } |
293 Event::End { .. } |
294 Event::CData { .. } |
295 Event::Decl { .. } |
296 Event::PI { .. } |
297 Event::DocType { .. } => (), // TODO: may need more errors
298 }
299 };
300
301 let mut stack = vec![root];
302
303 loop {
304 match reader.read_event(&mut buf)? {
305 Event::Empty(ref e) => {
306 let elem = build_element(reader, e)?;
307 // Since there is no Event::End after, directly append it to the current node
308 stack.last_mut().unwrap().append_child(elem);
309 },
310 Event::Start(ref e) => {
311 let elem = build_element(reader, e)?;
312 stack.push(elem);
313 },
314 Event::End(ref e) => {
315 if stack.len() <= 1 {
316 break;
317 }
318 let elem = stack.pop().unwrap();
319 if let Some(to) = stack.last_mut() {
320 // TODO: check whether this is correct, we are comparing &[u8]s, not &strs
321 let elem_name = e.name();
322 let mut split_iter = elem_name.splitn(2, |u| *u == 0x3A);
323 let possible_prefix = split_iter.next().unwrap(); // Can't be empty.
324 match split_iter.next() {
325 Some(name) => {
326 match elem.prefix() {
327 Some(prefix) => {
328 if possible_prefix != prefix.as_bytes() {
329 return Err(Error::InvalidElementClosed);
330 }
331 },
332 None => {
333 return Err(Error::InvalidElementClosed);
334 },
335 }
336 if name != elem.name().as_bytes() {
337 return Err(Error::InvalidElementClosed);
338 }
339 },
340 None => {
341 if elem.prefix().is_some() {
342 return Err(Error::InvalidElementClosed);
343 }
344 if possible_prefix != elem.name().as_bytes() {
345 return Err(Error::InvalidElementClosed);
346 }
347 },
348 }
349 to.append_child(elem);
350 }
351 },
352 Event::Text(s) => {
353 let text = s.unescape_and_decode(reader)?;
354 if text != "" {
355 let current_elem = stack.last_mut().unwrap();
356 current_elem.append_text_node(text);
357 }
358 },
359 Event::CData(s) => {
360 let text = reader.decode(&s)?.to_owned();
361 if text != "" {
362 let current_elem = stack.last_mut().unwrap();
363 current_elem.append_text_node(text);
364 }
365 },
366 Event::Eof => {
367 break;
368 },
369 #[cfg(not(feature = "comments"))]
370 Event::Comment(_) => return Err(Error::CommentsDisabled),
371 #[cfg(feature = "comments")]
372 Event::Comment(s) => {
373 let comment = reader.decode(&s)?.to_owned();
374 if comment != "" {
375 let current_elem = stack.last_mut().unwrap();
376 current_elem.append_comment_node(comment);
377 }
378 },
379 Event::Decl { .. } |
380 Event::PI { .. } |
381 Event::DocType { .. } => (),
382 }
383 }
384 Ok(stack.pop().unwrap())
385 }
386
387 /// Output a document to a `Writer`.
388 pub fn write_to<W: Write>(&self, writer: &mut W) -> Result<()> {
389 self.to_writer(&mut EventWriter::new(writer))
390 }
391
392 /// Output the document to quick-xml `Writer`
393 pub fn to_writer<W: Write>(&self, writer: &mut EventWriter<W>) -> Result<()> {
394 writer.write_event(Event::Decl(BytesDecl::new(b"1.0", Some(b"utf-8"), None)))?;
395 self.write_to_inner(writer)
396 }
397
398 /// Like `write_to()` but without the `<?xml?>` prelude
399 pub fn write_to_inner<W: Write>(&self, writer: &mut EventWriter<W>) -> Result<()> {
400 let name = match self.prefix {
401 None => Cow::Borrowed(&self.name),
402 Some(ref prefix) => Cow::Owned(format!("{}:{}", prefix, self.name)),
403 };
404
405 let mut start = BytesStart::borrowed(name.as_bytes(), name.len());
406 for (prefix, ns) in self.namespaces.declared_ns() {
407 match *prefix {
408 None => start.push_attribute(("xmlns", ns.as_ref())),
409 Some(ref prefix) => {
410 let key = format!("xmlns:{}", prefix);
411 start.push_attribute((key.as_bytes(), ns.as_bytes()))
412 },
413 }
414 }
415 for (key, value) in &self.attributes {
416 start.push_attribute((key.as_bytes(), escape(value.as_bytes()).as_ref()));
417 }
418
419 if self.children.is_empty() {
420 writer.write_event(Event::Empty(start))?;
421 return Ok(())
422 }
423
424 writer.write_event(Event::Start(start))?;
425
426 for child in &self.children {
427 child.write_to_inner(writer)?;
428 }
429
430 writer.write_event(Event::End(BytesEnd::borrowed(name.as_bytes())))?;
431 Ok(())
432 }
433
434 /// Returns an iterator over references to every child node of this element.
435 ///
436 /// # Examples
437 ///
438 /// ```rust
439 /// use minidom::Element;
440 ///
441 /// let elem: Element = "<root>a<c1 />b<c2 />c</root>".parse().unwrap();
442 ///
443 /// let mut iter = elem.nodes();
444 ///
445 /// assert_eq!(iter.next().unwrap().as_text().unwrap(), "a");
446 /// assert_eq!(iter.next().unwrap().as_element().unwrap().name(), "c1");
447 /// assert_eq!(iter.next().unwrap().as_text().unwrap(), "b");
448 /// assert_eq!(iter.next().unwrap().as_element().unwrap().name(), "c2");
449 /// assert_eq!(iter.next().unwrap().as_text().unwrap(), "c");
450 /// assert_eq!(iter.next(), None);
451 /// ```
452 #[inline] pub fn nodes(&self) -> Nodes {
453 self.children.iter()
454 }
455
456 /// Returns an iterator over mutable references to every child node of this element.
457 #[inline] pub fn nodes_mut(&mut self) -> NodesMut {
458 self.children.iter_mut()
459 }
460
461 /// Returns an iterator over references to every child element of this element.
462 ///
463 /// # Examples
464 ///
465 /// ```rust
466 /// use minidom::Element;
467 ///
468 /// let elem: Element = "<root>hello<child1 />this<child2 />is<child3 />ignored</root>".parse().unwrap();
469 ///
470 /// let mut iter = elem.children();
471 /// assert_eq!(iter.next().unwrap().name(), "child1");
472 /// assert_eq!(iter.next().unwrap().name(), "child2");
473 /// assert_eq!(iter.next().unwrap().name(), "child3");
474 /// assert_eq!(iter.next(), None);
475 /// ```
476 #[inline] pub fn children(&self) -> Children {
477 Children {
478 iter: self.children.iter(),
479 }
480 }
481
482 /// Returns an iterator over mutable references to every child element of this element.
483 #[inline] pub fn children_mut(&mut self) -> ChildrenMut {
484 ChildrenMut {
485 iter: self.children.iter_mut(),
486 }
487 }
488
489 /// Returns an iterator over references to every text node of this element.
490 ///
491 /// # Examples
492 ///
493 /// ```rust
494 /// use minidom::Element;
495 ///
496 /// let elem: Element = "<root>hello<c /> world!</root>".parse().unwrap();
497 ///
498 /// let mut iter = elem.texts();
499 /// assert_eq!(iter.next().unwrap(), "hello");
500 /// assert_eq!(iter.next().unwrap(), " world!");
501 /// assert_eq!(iter.next(), None);
502 /// ```
503 #[inline] pub fn texts(&self) -> Texts {
504 Texts {
505 iter: self.children.iter(),
506 }
507 }
508
509 /// Returns an iterator over mutable references to every text node of this element.
510 #[inline] pub fn texts_mut(&mut self) -> TextsMut {
511 TextsMut {
512 iter: self.children.iter_mut(),
513 }
514 }
515
516 /// Appends a child node to the `Element`, returning the appended node.
517 ///
518 /// # Examples
519 ///
520 /// ```rust
521 /// use minidom::Element;
522 ///
523 /// let mut elem = Element::bare("root");
524 ///
525 /// assert_eq!(elem.children().count(), 0);
526 ///
527 /// elem.append_child(Element::bare("child"));
528 ///
529 /// {
530 /// let mut iter = elem.children();
531 /// assert_eq!(iter.next().unwrap().name(), "child");
532 /// assert_eq!(iter.next(), None);
533 /// }
534 ///
535 /// let child = elem.append_child(Element::bare("new"));
536 ///
537 /// assert_eq!(child.name(), "new");
538 /// ```
539 pub fn append_child(&mut self, child: Element) -> &mut Element {
540 child.namespaces.set_parent(Rc::clone(&self.namespaces));
541
542 self.children.push(Node::Element(child));
543 if let Node::Element(ref mut cld) = *self.children.last_mut().unwrap() {
544 cld
545 } else {
546 unreachable!()
547 }
548 }
549
550 /// Appends a text node to an `Element`.
551 ///
552 /// # Examples
553 ///
554 /// ```rust
555 /// use minidom::Element;
556 ///
557 /// let mut elem = Element::bare("node");
558 ///
559 /// assert_eq!(elem.text(), "");
560 ///
561 /// elem.append_text_node("text");
562 ///
563 /// assert_eq!(elem.text(), "text");
564 /// ```
565 pub fn append_text_node<S: Into<String>>(&mut self, child: S) {
566 self.children.push(Node::Text(child.into()));
567 }
568
569 /// Appends a comment node to an `Element`.
570 ///
571 /// # Examples
572 ///
573 /// ```rust
574 /// use minidom::Element;
575 ///
576 /// let mut elem = Element::bare("node");
577 ///
578 /// elem.append_comment_node("comment");
579 /// ```
580 #[cfg(feature = "comments")]
581 pub fn append_comment_node<S: Into<String>>(&mut self, child: S) {
582 self.children.push(Node::Comment(child.into()));
583 }
584
585 /// Appends a node to an `Element`.
586 ///
587 /// # Examples
588 ///
589 /// ```rust
590 /// use minidom::{Element, Node};
591 ///
592 /// let mut elem = Element::bare("node");
593 ///
594 /// elem.append_node(Node::Text("hello".to_owned()));
595 ///
596 /// assert_eq!(elem.text(), "hello");
597 /// ```
598 pub fn append_node(&mut self, node: Node) {
599 self.children.push(node);
600 }
601
602 /// Returns the concatenation of all text nodes in the `Element`.
603 ///
604 /// # Examples
605 ///
606 /// ```rust
607 /// use minidom::Element;
608 ///
609 /// let elem: Element = "<node>hello,<split /> world!</node>".parse().unwrap();
610 ///
611 /// assert_eq!(elem.text(), "hello, world!");
612 /// ```
613 pub fn text(&self) -> String {
614 self.texts().fold(String::new(), |ret, new| ret + new)
615 }
616
617 /// Returns a reference to the first child element with the specific name and namespace, if it
618 /// exists in the direct descendants of this `Element`, else returns `None`.
619 ///
620 /// # Examples
621 ///
622 /// ```rust
623 /// use minidom::Element;
624 ///
625 /// let elem: Element = r#"<node xmlns="ns"><a /><a xmlns="other_ns" /><b /></node>"#.parse().unwrap();
626 ///
627 /// assert!(elem.get_child("a", "ns").unwrap().is("a", "ns"));
628 /// assert!(elem.get_child("a", "other_ns").unwrap().is("a", "other_ns"));
629 /// assert!(elem.get_child("b", "ns").unwrap().is("b", "ns"));
630 /// assert_eq!(elem.get_child("c", "ns"), None);
631 /// assert_eq!(elem.get_child("b", "other_ns"), None);
632 /// assert_eq!(elem.get_child("a", "inexistent_ns"), None);
633 /// ```
634 pub fn get_child<N: AsRef<str>, NS: AsRef<str>>(&self, name: N, namespace: NS) -> Option<&Element> {
635 for fork in &self.children {
636 if let Node::Element(ref e) = *fork {
637 if e.is(name.as_ref(), namespace.as_ref()) {
638 return Some(e);
639 }
640 }
641 }
642 None
643 }
644
645 /// Returns a mutable reference to the first child element with the specific name and namespace,
646 /// if it exists in the direct descendants of this `Element`, else returns `None`.
647 pub fn get_child_mut<N: AsRef<str>, NS: AsRef<str>>(&mut self, name: N, namespace: NS) -> Option<&mut Element> {
648 for fork in &mut self.children {
649 if let Node::Element(ref mut e) = *fork {
650 if e.is(name.as_ref(), namespace.as_ref()) {
651 return Some(e);
652 }
653 }
654 }
655 None
656 }
657
658 /// Returns whether a specific child with this name and namespace exists in the direct
659 /// descendants of the `Element`.
660 ///
661 /// # Examples
662 ///
663 /// ```rust
664 /// use minidom::Element;
665 ///
666 /// let elem: Element = r#"<node xmlns="ns"><a /><a xmlns="other_ns" /><b /></node>"#.parse().unwrap();
667 ///
668 /// assert_eq!(elem.has_child("a", "other_ns"), true);
669 /// assert_eq!(elem.has_child("a", "ns"), true);
670 /// assert_eq!(elem.has_child("a", "inexistent_ns"), false);
671 /// assert_eq!(elem.has_child("b", "ns"), true);
672 /// assert_eq!(elem.has_child("b", "other_ns"), false);
673 /// assert_eq!(elem.has_child("b", "inexistent_ns"), false);
674 /// ```
675 pub fn has_child<N: AsRef<str>, NS: AsRef<str>>(&self, name: N, namespace: NS) -> bool {
676 self.get_child(name, namespace).is_some()
677 }
678
679 /// Removes the first child with this name and namespace, if it exists, and returns an
680 /// `Option<Element>` containing this child if it succeeds.
681 /// Returns `None` if no child matches this name and namespace.
682 ///
683 /// # Examples
684 ///
685 /// ```rust
686 /// use minidom::Element;
687 ///
688 /// let mut elem: Element = r#"<node xmlns="ns"><a /><a xmlns="other_ns" /><b /></node>"#.parse().unwrap();
689 ///
690 /// assert!(elem.remove_child("a", "ns").unwrap().is("a", "ns"));
691 /// assert!(elem.remove_child("a", "ns").is_none());
692 /// assert!(elem.remove_child("inexistent", "inexistent").is_none());
693 /// ```
694 pub fn remove_child<N: AsRef<str>, NS: AsRef<str>>(&mut self, name: N, namespace: NS) -> Option<Element> {
695 let name = name.as_ref();
696 let namespace = namespace.as_ref();
697 let idx = self.children.iter().position(|x| {
698 if let Node::Element(ref elm) = x {
699 elm.is(name, namespace)
700 } else {
701 false
702 }
703 })?;
704 self.children.remove(idx).into_element()
705 }
706}
707
708fn split_element_name<S: AsRef<str>>(s: S) -> Result<(Option<String>, String)> {
709 let name_parts = s.as_ref().split(':').collect::<Vec<&str>>();
710 match name_parts.len() {
711 2 => Ok((Some(name_parts[0].to_owned()), name_parts[1].to_owned())),
712 1 => Ok((None, name_parts[0].to_owned())),
713 _ => Err(Error::InvalidElement),
714 }
715}
716
717fn build_element<R: BufRead>(reader: &EventReader<R>, event: &BytesStart) -> Result<Element> {
718 let mut namespaces = BTreeMap::new();
719 let attributes = event.attributes()
720 .map(|o| {
721 let o = o?;
722 let key = str::from_utf8(o.key)?.to_owned();
723 let value = o.unescape_and_decode_value(reader)?;
724 Ok((key, value))
725 })
726 .filter(|o| {
727 match *o {
728 Ok((ref key, ref value)) if key == "xmlns" => {
729 namespaces.insert(None, value.to_owned());
730 false
731 },
732 Ok((ref key, ref value)) if key.starts_with("xmlns:") => {
733 namespaces.insert(Some(key[6..].to_owned()), value.to_owned());
734 false
735 },
736 _ => true,
737 }
738 })
739 .collect::<Result<BTreeMap<String, String>>>()?;
740
741 let (prefix, name) = split_element_name(str::from_utf8(event.name())?)?;
742 let element = Element::new(name, prefix, namespaces, attributes, Vec::new());
743 Ok(element)
744}
745
746/// An iterator over references to child elements of an `Element`.
747pub struct Children<'a> {
748 iter: slice::Iter<'a, Node>,
749}
750
751impl<'a> Iterator for Children<'a> {
752 type Item = &'a Element;
753
754 fn next(&mut self) -> Option<&'a Element> {
755 for item in &mut self.iter {
756 if let Node::Element(ref child) = *item {
757 return Some(child);
758 }
759 }
760 None
761 }
762}
763
764/// An iterator over mutable references to child elements of an `Element`.
765pub struct ChildrenMut<'a> {
766 iter: slice::IterMut<'a, Node>,
767}
768
769impl<'a> Iterator for ChildrenMut<'a> {
770 type Item = &'a mut Element;
771
772 fn next(&mut self) -> Option<&'a mut Element> {
773 for item in &mut self.iter {
774 if let Node::Element(ref mut child) = *item {
775 return Some(child);
776 }
777 }
778 None
779 }
780}
781
782/// An iterator over references to child text nodes of an `Element`.
783pub struct Texts<'a> {
784 iter: slice::Iter<'a, Node>,
785}
786
787impl<'a> Iterator for Texts<'a> {
788 type Item = &'a str;
789
790 fn next(&mut self) -> Option<&'a str> {
791 for item in &mut self.iter {
792 if let Node::Text(ref child) = *item {
793 return Some(child);
794 }
795 }
796 None
797 }
798}
799
800/// An iterator over mutable references to child text nodes of an `Element`.
801pub struct TextsMut<'a> {
802 iter: slice::IterMut<'a, Node>,
803}
804
805impl<'a> Iterator for TextsMut<'a> {
806 type Item = &'a mut String;
807
808 fn next(&mut self) -> Option<&'a mut String> {
809 for item in &mut self.iter {
810 if let Node::Text(ref mut child) = *item {
811 return Some(child);
812 }
813 }
814 None
815 }
816}
817
818/// An iterator over references to all child nodes of an `Element`.
819pub type Nodes<'a> = slice::Iter<'a, Node>;
820
821/// An iterator over mutable references to all child nodes of an `Element`.
822pub type NodesMut<'a> = slice::IterMut<'a, Node>;
823
824/// An iterator over the attributes of an `Element`.
825pub struct Attrs<'a> {
826 iter: btree_map::Iter<'a, String, String>,
827}
828
829impl<'a> Iterator for Attrs<'a> {
830 type Item = (&'a str, &'a str);
831
832 fn next(&mut self) -> Option<Self::Item> {
833 self.iter.next().map(|(x, y)| (x.as_ref(), y.as_ref()))
834 }
835}
836
837/// An iterator over the attributes of an `Element`, with the values mutable.
838pub struct AttrsMut<'a> {
839 iter: btree_map::IterMut<'a, String, String>,
840}
841
842impl<'a> Iterator for AttrsMut<'a> {
843 type Item = (&'a str, &'a mut String);
844
845 fn next(&mut self) -> Option<Self::Item> {
846 self.iter.next().map(|(x, y)| (x.as_ref(), y))
847 }
848}
849
850/// A builder for `Element`s.
851pub struct ElementBuilder {
852 root: Element,
853 namespaces: BTreeMap<Option<String>, String>,
854}
855
856impl ElementBuilder {
857 /// Sets the namespace.
858 pub fn ns<S: Into<String>>(mut self, namespace: S) -> ElementBuilder {
859 self.namespaces
860 .insert(self.root.prefix.clone(), namespace.into());
861 self
862 }
863
864 /// Sets an attribute.
865 pub fn attr<S: Into<String>, V: IntoAttributeValue>(mut self, name: S, value: V) -> ElementBuilder {
866 self.root.set_attr(name, value);
867 self
868 }
869
870 /// Appends anything implementing `Into<Node>` into the tree.
871 pub fn append<T: Into<Node>>(mut self, node: T) -> ElementBuilder {
872 self.root.append_node(node.into());
873 self
874 }
875
876 /// Appends an iterator of things implementing `Into<Node>` into the tree.
877 pub fn append_all<T: Into<Node>, I: IntoIterator<Item = T>>(mut self, iter: I) -> ElementBuilder {
878 for node in iter {
879 self.root.append_node(node.into());
880 }
881 self
882 }
883
884 /// Builds the `Element`.
885 pub fn build(self) -> Element {
886 let mut element = self.root;
887 // Set namespaces
888 element.namespaces = Rc::new(NamespaceSet::from(self.namespaces));
889 // Propagate namespaces
890 for node in &element.children {
891 if let Node::Element(ref e) = *node {
892 e.namespaces.set_parent(Rc::clone(&element.namespaces));
893 }
894 }
895 element
896 }
897}
898
899#[cfg(test)]
900mod tests {
901 use super::*;
902
903 #[test]
904 fn test_element_new() {
905 use std::iter::FromIterator;
906
907 let elem = Element::new( "name".to_owned()
908 , None
909 , Some("namespace".to_owned())
910 , BTreeMap::from_iter(vec![ ("name".to_string(), "value".to_string()) ].into_iter() )
911 , Vec::new() );
912
913 assert_eq!(elem.name(), "name");
914 assert_eq!(elem.ns(), Some("namespace".to_owned()));
915 assert_eq!(elem.attr("name"), Some("value"));
916 assert_eq!(elem.attr("inexistent"), None);
917 }
918
919 #[test]
920 fn test_from_reader_simple() {
921 let xml = "<foo></foo>";
922 let mut reader = EventReader::from_str(xml);
923 let elem = Element::from_reader(&mut reader);
924
925 let elem2 = Element::builder("foo").build();
926
927 assert_eq!(elem.unwrap(), elem2);
928 }
929
930 #[test]
931 fn test_from_reader_nested() {
932 let xml = "<foo><bar baz='qxx' /></foo>";
933 let mut reader = EventReader::from_str(xml);
934 let elem = Element::from_reader(&mut reader);
935
936 let nested = Element::builder("bar")
937 .attr("baz", "qxx")
938 .build();
939 let elem2 = Element::builder("foo")
940 .append(nested)
941 .build();
942
943 assert_eq!(elem.unwrap(), elem2);
944 }
945
946 #[test]
947 fn test_from_reader_with_prefix() {
948 let xml = "<foo><prefix:bar baz='qxx' /></foo>";
949 let mut reader = EventReader::from_str(xml);
950 let elem = Element::from_reader(&mut reader);
951
952 let nested = Element::builder("prefix:bar")
953 .attr("baz", "qxx")
954 .build();
955 let elem2 = Element::builder("foo")
956 .append(nested)
957 .build();
958
959 assert_eq!(elem.unwrap(), elem2);
960 }
961
962 #[test]
963 fn parses_spectest_xml() { // From: https://gitlab.com/lumi/minidom-rs/issues/8
964 let xml = r#"
965 <rng:grammar xmlns:rng="http://relaxng.org/ns/structure/1.0">
966 <rng:name xmlns:rng="http://relaxng.org/ns/structure/1.0"></rng:name>
967 </rng:grammar>
968 "#;
969 let mut reader = EventReader::from_str(xml);
970 let _ = Element::from_reader(&mut reader).unwrap();
971 }
972
973 #[test]
974 fn does_not_unescape_cdata() {
975 let xml = "<test><![CDATA['>blah<blah>]]></test>";
976 let mut reader = EventReader::from_str(xml);
977 let elem = Element::from_reader(&mut reader).unwrap();
978 assert_eq!(elem.text(), "'>blah<blah>");
979 }
980}