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