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