Revision control
Copy as Markdown
Other Tools
//! Contains high-level interface for a pull-based XML parser.
//!
//! The most important type in this module is `EventReader`, which provides an iterator
//! view for events in XML document.
use std::io::{Read};
use std::result;
use common::{Position, TextPosition};
pub use self::config::ParserConfig;
pub use self::events::XmlEvent;
use self::parser::PullParser;
mod lexer;
mod parser;
mod config;
mod events;
mod error;
pub use self::error::{Error, ErrorKind};
/// A result type yielded by `XmlReader`.
pub type Result<T> = result::Result<T, Error>;
/// A wrapper around an `std::io::Read` instance which provides pull-based XML parsing.
pub struct EventReader<R: Read> {
source: R,
parser: PullParser
}
impl<R: Read> EventReader<R> {
/// Creates a new reader, consuming the given stream.
#[inline]
pub fn new(source: R) -> EventReader<R> {
EventReader::new_with_config(source, ParserConfig::new())
}
/// Creates a new reader with the provded configuration, consuming the given stream.
#[inline]
pub fn new_with_config(source: R, config: ParserConfig) -> EventReader<R> {
EventReader { source: source, parser: PullParser::new(config) }
}
/// Pulls and returns next XML event from the stream.
///
/// If returned event is `XmlEvent::Error` or `XmlEvent::EndDocument`, then
/// further calls to this method will return this event again.
#[inline]
pub fn next(&mut self) -> Result<XmlEvent> {
self.parser.next(&mut self.source)
}
pub fn source(&self) -> &R { &self.source }
pub fn source_mut(&mut self) -> &mut R { &mut self.source }
/// Unwraps this `EventReader`, returning the underlying reader.
///
/// Note that this operation is destructive; unwrapping the reader and wrapping it
/// again with `EventReader::new()` will create a fresh reader which will attempt
/// to parse an XML document from the beginning.
pub fn into_inner(self) -> R {
self.source
}
}
impl<B: Read> Position for EventReader<B> {
/// Returns the position of the last event produced by the reader.
#[inline]
fn position(&self) -> TextPosition {
self.parser.position()
}
}
impl<R: Read> IntoIterator for EventReader<R> {
type Item = Result<XmlEvent>;
type IntoIter = Events<R>;
fn into_iter(self) -> Events<R> {
Events { reader: self, finished: false }
}
}
/// An iterator over XML events created from some type implementing `Read`.
///
/// When the next event is `xml::event::Error` or `xml::event::EndDocument`, then
/// it will be returned by the iterator once, and then it will stop producing events.
pub struct Events<R: Read> {
reader: EventReader<R>,
finished: bool
}
impl<R: Read> Events<R> {
/// Unwraps the iterator, returning the internal `EventReader`.
#[inline]
pub fn into_inner(self) -> EventReader<R> {
self.reader
}
pub fn source(&self) -> &R { &self.reader.source }
pub fn source_mut(&mut self) -> &mut R { &mut self.reader.source }
}
impl<R: Read> Iterator for Events<R> {
type Item = Result<XmlEvent>;
#[inline]
fn next(&mut self) -> Option<Result<XmlEvent>> {
if self.finished && !self.reader.parser.is_ignoring_end_of_stream() { None }
else {
let ev = self.reader.next();
match ev {
Ok(XmlEvent::EndDocument) | Err(_) => self.finished = true,
_ => {}
}
Some(ev)
}
}
}
impl<'r> EventReader<&'r [u8]> {
/// A convenience method to create an `XmlReader` from a string slice.
#[inline]
pub fn from_str(source: &'r str) -> EventReader<&'r [u8]> {
EventReader::new(source.as_bytes())
}
}