1 //! Contains high-level interface for a pull-based XML parser.
2 //!
3 //! The most important type in this module is `EventReader`, which provides an iterator
4 //! view for events in XML document.
5 
6 use std::io::{Read};
7 use std::result;
8 
9 use common::{Position, TextPosition};
10 
11 pub use self::config::ParserConfig;
12 pub use self::events::XmlEvent;
13 
14 use self::parser::PullParser;
15 
16 mod lexer;
17 mod parser;
18 mod config;
19 mod events;
20 
21 mod error;
22 pub use self::error::{Error, ErrorKind};
23 
24 /// A result type yielded by `XmlReader`.
25 pub type Result<T> = result::Result<T, Error>;
26 
27 /// A wrapper around an `std::io::Read` instance which provides pull-based XML parsing.
28 pub struct EventReader<R: Read> {
29     source: R,
30     parser: PullParser
31 }
32 
33 impl<R: Read> EventReader<R> {
34     /// Creates a new reader, consuming the given stream.
35     #[inline]
new(source: R) -> EventReader<R>36     pub fn new(source: R) -> EventReader<R> {
37         EventReader::new_with_config(source, ParserConfig::new())
38     }
39 
40     /// Creates a new reader with the provded configuration, consuming the given stream.
41     #[inline]
new_with_config(source: R, config: ParserConfig) -> EventReader<R>42     pub fn new_with_config(source: R, config: ParserConfig) -> EventReader<R> {
43         EventReader { source: source, parser: PullParser::new(config) }
44     }
45 
46     /// Pulls and returns next XML event from the stream.
47     ///
48     /// If returned event is `XmlEvent::Error` or `XmlEvent::EndDocument`, then
49     /// further calls to this method will return this event again.
50     #[inline]
next(&mut self) -> Result<XmlEvent>51     pub fn next(&mut self) -> Result<XmlEvent> {
52         self.parser.next(&mut self.source)
53     }
54 
source(&self) -> &R55     pub fn source(&self) -> &R { &self.source }
source_mut(&mut self) -> &mut R56     pub fn source_mut(&mut self) -> &mut R { &mut self.source }
57 
58     /// Unwraps this `EventReader`, returning the underlying reader.
59     ///
60     /// Note that this operation is destructive; unwrapping the reader and wrapping it
61     /// again with `EventReader::new()` will create a fresh reader which will attempt
62     /// to parse an XML document from the beginning.
into_inner(self) -> R63     pub fn into_inner(self) -> R {
64         self.source
65     }
66 }
67 
68 impl<B: Read> Position for EventReader<B> {
69     /// Returns the position of the last event produced by the reader.
70     #[inline]
position(&self) -> TextPosition71     fn position(&self) -> TextPosition {
72         self.parser.position()
73     }
74 }
75 
76 impl<R: Read> IntoIterator for EventReader<R> {
77     type Item = Result<XmlEvent>;
78     type IntoIter = Events<R>;
79 
into_iter(self) -> Events<R>80     fn into_iter(self) -> Events<R> {
81         Events { reader: self, finished: false }
82     }
83 }
84 
85 /// An iterator over XML events created from some type implementing `Read`.
86 ///
87 /// When the next event is `xml::event::Error` or `xml::event::EndDocument`, then
88 /// it will be returned by the iterator once, and then it will stop producing events.
89 pub struct Events<R: Read> {
90     reader: EventReader<R>,
91     finished: bool
92 }
93 
94 impl<R: Read> Events<R> {
95     /// Unwraps the iterator, returning the internal `EventReader`.
96     #[inline]
into_inner(self) -> EventReader<R>97     pub fn into_inner(self) -> EventReader<R> {
98         self.reader
99     }
100 
source(&self) -> &R101     pub fn source(&self) -> &R { &self.reader.source }
source_mut(&mut self) -> &mut R102     pub fn source_mut(&mut self) -> &mut R { &mut self.reader.source }
103 
104 }
105 
106 impl<R: Read> Iterator for Events<R> {
107     type Item = Result<XmlEvent>;
108 
109     #[inline]
next(&mut self) -> Option<Result<XmlEvent>>110     fn next(&mut self) -> Option<Result<XmlEvent>> {
111         if self.finished && !self.reader.parser.is_ignoring_end_of_stream() { None }
112         else {
113             let ev = self.reader.next();
114             match ev {
115                 Ok(XmlEvent::EndDocument) | Err(_) => self.finished = true,
116                 _ => {}
117             }
118             Some(ev)
119         }
120     }
121 }
122 
123 impl<'r> EventReader<&'r [u8]> {
124     /// A convenience method to create an `XmlReader` from a string slice.
125     #[inline]
from_str(source: &'r str) -> EventReader<&'r [u8]>126     pub fn from_str(source: &'r str) -> EventReader<&'r [u8]> {
127         EventReader::new(source.as_bytes())
128     }
129 }
130