Implement high-level Reader

Author: Mingun

Changelog.md

@@ -20,10 +20,17 @@ Now references to entities (as predefined, such as `<`, as user-defined) repo
 Caller can parse the content of the entity and stream events from it as it is required by the
 XML specification. See the updated `custom_entities` example!
 
+The `Reader` type was significantly reworked. The old type now called `RawReader` and should be
+used only for very low-level manipulations with the document. Since that it is preferred to use
+new `Reader` which can automatically handle entity references.
+
 ### New Features
 
 - [#766]: Allow to parse resolved entities as XML fragments and stream events from them.
 - [#766]: Added new event `Event::GeneralRef` with content of [general entity].
+- [#766]: Added `quick_xml::reader::EntityResolver` which is able to resolve external entities.
+- [#766]: Added `quick_xml::reader::Reader` -- a new high-level reader which should be preferred
+  over old `RawReader`.
 
 ### Bug Fixes
 

src/reader/event.rs

@@ -0,0 +1,79 @@
+//! Defines zero-copy XML reader events used throughout this library.
+//!
+//! An XML event often represents part of an XML element.
+//! They occur during reading and are usually used with the stream-oriented API.
+//!
+//! For example, the XML element
+//! ```xml
+//! <name attr="value">Inner text</name>
+//! ```
+//! consists of the three events `Start`, `Text` and `End`. They can also represent
+//! other parts in an XML document like the XML declaration. Each [`Event`] usually
+//! contains further information, like the tag name, the attribute or the inner text.
+//!
+//! See [`Event`] for a list of all possible events.
+//!
+//! # Reading
+//!
+//! When reading an XML stream, the events are emitted by [`Reader::read_event`]
+//! or [`Reader::read_event_into`]. You must listen for the different types of
+//! events you are interested in.
+//!
+//! See [`Reader`] for further information.
+//!
+//! # Writing
+//!
+//! The [`Event`] can be directly passed to the [`Writer::write_event`] or converted
+//! to a [`writer::Event`] if you want to change it before write.
+//!
+//! [`Reader::read_event`]: crate::reader::Reader::read_event
+//! [`Reader::read_event_into`]: crate::reader::Reader::read_event_into
+//! [`Reader`]: crate::reader::Reader
+//! [`Writer::write_event`]: crate::writer::Writer::write_event
+//! [`writer::Event`]: crate::writer::Event
+
+use crate::events::{BytesCData, BytesEnd, BytesPI, BytesStart, BytesText};
+
+/// Event emitted by [`Reader::read_event`].
+///
+/// # Lifetime
+///
+/// The `'i` lifetime of this struct is the lifetime of data that may be borrowed
+/// from the XML input (when reader reads from `&[u8]` or `&str`) or from the
+/// user-provided buffer.
+///
+/// [`Reader::read_event`]: crate::reader::Reader::read_event
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
+pub enum Event<'i> {
+    /// Empty element tag (with attributes) `<tag attr="value" />`.
+    Empty(BytesStart<'i>),
+    /// Start tag (with attributes) `<tag attr="value">`.
+    Start(BytesStart<'i>),
+    /// End tag `</tag>`.
+    End(BytesEnd<'i>),
+    /// Character data between `Start` and `End` element.
+    Text(BytesText<'i>),
+    /// CData `<![CDATA[...]]>`.
+    CData(BytesCData<'i>),
+    /// Processing instruction `<?...?>`.
+    PI(BytesPI<'i>),
+    /// End of XML document.
+    Eof,
+}
+
+impl<'i> Event<'i> {
+    /// Ensures that all data is owned to extend the object's lifetime if necessary.
+    #[inline]
+    pub fn into_owned(self) -> Event<'static> {
+        match self {
+            Self::Empty(e) => Event::Empty(e.into_owned()),
+            Self::Start(e) => Event::Start(e.into_owned()),
+            Self::End(e) => Event::End(e.into_owned()),
+            Self::Text(e) => Event::Text(e.into_owned()),
+            Self::CData(e) => Event::CData(e.into_owned()),
+            Self::PI(e) => Event::PI(e.into_owned()),
+            Self::Eof => Event::Eof,
+        }
+    }
+}