xml/reader/
mod.rs

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
6use std::io::{Read};
7use std::result;
8
9use common::{Position, TextPosition};
10
11pub use self::config::ParserConfig;
12pub use self::events::XmlEvent;
13
14use self::parser::PullParser;
15
16mod lexer;
17mod parser;
18mod config;
19mod events;
20
21mod error;
22pub use self::error::{Error, ErrorKind};
23
24/// A result type yielded by `XmlReader`.
25pub type Result<T> = result::Result<T, Error>;
26
27/// A wrapper around an `std::io::Read` instance which provides pull-based XML parsing.
28pub struct EventReader<R: Read> {
29    source: R,
30    parser: PullParser
31}
32
33impl<R: Read> EventReader<R> {
34    /// Creates a new reader, consuming the given stream.
35    #[inline]
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]
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]
51    pub fn next(&mut self) -> Result<XmlEvent> {
52        self.parser.next(&mut self.source)
53    }
54
55    pub fn source(&self) -> &R { &self.source }
56    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.
63    pub fn into_inner(self) -> R {
64        self.source
65    }
66}
67
68impl<B: Read> Position for EventReader<B> {
69    /// Returns the position of the last event produced by the reader.
70    #[inline]
71    fn position(&self) -> TextPosition {
72        self.parser.position()
73    }
74}
75
76impl<R: Read> IntoIterator for EventReader<R> {
77    type Item = Result<XmlEvent>;
78    type IntoIter = Events<R>;
79
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.
89pub struct Events<R: Read> {
90    reader: EventReader<R>,
91    finished: bool
92}
93
94impl<R: Read> Events<R> {
95    /// Unwraps the iterator, returning the internal `EventReader`.
96    #[inline]
97    pub fn into_inner(self) -> EventReader<R> {
98        self.reader
99    }
100
101    pub fn source(&self) -> &R { &self.reader.source }
102    pub fn source_mut(&mut self) -> &mut R { &mut self.reader.source }
103
104}
105
106impl<R: Read> Iterator for Events<R> {
107    type Item = Result<XmlEvent>;
108
109    #[inline]
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
123impl<'r> EventReader<&'r [u8]> {
124    /// A convenience method to create an `XmlReader` from a string slice.
125    #[inline]
126    pub fn from_str(source: &'r str) -> EventReader<&'r [u8]> {
127        EventReader::new(source.as_bytes())
128    }
129}
xml/reader/mod.rs

xml/reader/
mod.rs
