Allow using tokio's AsyncBufRead

Author: endor

Cargo.toml

@@ -3,6 +3,7 @@ name = "quick-xml"
 version = "0.22.0"
 authors = ["Johann Tuffe <[email protected]>"]
 description = "High performance xml reader and writer"
+edition = "2018"
 
 documentation = "https://docs.rs/quick-xml"
 repository = "https://github.com/tafia/quick-xml"
@@ -15,14 +16,17 @@ license = "MIT"
 travis-ci = { repository = "tafia/quick-xml" }
 
 [dependencies]
+async-recursion = { version = "0.3.2", optional = true }
 encoding_rs = { version = "0.8.26", optional = true }
+tokio = { version = "0.2.22", features = ["fs", "io-util"], optional = true }
 serde = { version = "1.0", optional = true }
 memchr = "2.3.4"
 
 [dev-dependencies]
 serde = { version = "1.0", features = ["derive"] }
 serde-value = "0.7"
 regex = "1"
+tokio = { version = "0.2.22", features = ["macros", "rt-threaded"] }
 
 [lib]
 bench = false
@@ -32,6 +36,7 @@ default = []
 encoding = ["encoding_rs"]
 serialize = ["serde"]
 escape-html = []
+asynchronous = ["tokio", "async-recursion"]
 
 [package.metadata.docs.rs]
 features = ["serialize"]

README.md

@@ -210,8 +210,8 @@ fn crates_io() -> Result<Html, DeError> {
 
 ### Credits
 
-This has largely been inspired by [serde-xml-rs](https://github.com/RReverser/serde-xml-rs). 
-quick-xml follows its convention for deserialization, including the 
+This has largely been inspired by [serde-xml-rs](https://github.com/RReverser/serde-xml-rs).
+quick-xml follows its convention for deserialization, including the
 [`$value`](https://github.com/RReverser/serde-xml-rs#parsing-the-value-of-a-tag) special name.
 
 ### Parsing the "value" of a tag
@@ -234,6 +234,7 @@ Note that despite not focusing on performance (there are several unecessary copi
 
 - `encoding`: support non utf8 xmls
 - `serialize`: support serde `Serialize`/`Deserialize`
+- `asynchronous`: support for `AsyncRead`s in `tokio`
 
 ## Performance
 

examples/custom_entities.rs

@@ -14,6 +14,8 @@ use quick_xml::events::Event;
 use quick_xml::Reader;
 use regex::bytes::Regex;
 use std::collections::HashMap;
+#[cfg(feature = "asynchronous")]
+use tokio::runtime::Runtime;
 
 const DATA: &str = r#"
 
@@ -33,8 +35,17 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     let mut custom_entities = HashMap::new();
     let entity_re = Regex::new(r#"<!ENTITY\s+([^ \t\r\n]+)\s+"([^"]*)"\s*>"#)?;
 
+    #[cfg(feature = "asynchronous")]
+    let mut runtime = Runtime::new().expect("Runtime cannot be initialized");
+
     loop {
-        match reader.read_event(&mut buf) {
+        #[cfg(feature = "asynchronous")]
+        let event = runtime.block_on(async { reader.read_event(&mut buf).await });
+
+        #[cfg(not(feature = "asynchronous"))]
+        let event = reader.read_event(&mut buf);
+
+        match event {
             Ok(Event::DocType(ref e)) => {
                 for cap in entity_re.captures_iter(&e) {
                     custom_entities.insert(cap[1].to_vec(), cap[2].to_vec());

examples/issue68.rs

@@ -1,10 +1,10 @@
 #![allow(unused)]
 
-extern crate quick_xml;
-
 use quick_xml::events::Event;
 use quick_xml::Reader;
 use std::io::Read;
+#[cfg(feature = "asynchronous")]
+use tokio::runtime::Runtime;
 
 struct Resource {
     etag: String,
@@ -81,8 +81,18 @@ fn parse_report(xml_data: &str) -> Vec<Resource> {
     let mut depth = 0;
     let mut state = State::MultiStatus;
 
+    #[cfg(feature = "asynchronous")]
+    let mut runtime = Runtime::new().expect("Runtime cannot be initialized");
+
     loop {
-        match reader.read_namespaced_event(&mut buf, &mut ns_buffer) {
+        #[cfg(feature = "asynchronous")]
+        let event = runtime
+            .block_on(async { reader.read_namespaced_event(&mut buf, &mut ns_buffer).await });
+
+        #[cfg(not(feature = "asynchronous"))]
+        let event = reader.read_namespaced_event(&mut buf, &mut ns_buffer);
+
+        match event {
             Ok((namespace_value, Event::Start(e))) => {
                 let namespace_value = namespace_value.unwrap_or_default();
                 match (depth, state, namespace_value, e.local_name()) {

examples/nested_readers.rs

@@ -1,6 +1,8 @@
-extern crate quick_xml;
 use quick_xml::events::Event;
 use quick_xml::Reader;
+#[cfg(feature = "asynchronous")]
+use tokio::runtime::Runtime;
+
 // a structure to capture the rows we've extracted
 // from a ECMA-376 table in document.xml
 #[derive(Debug, Clone)]
@@ -16,10 +18,26 @@ fn main() -> Result<(), quick_xml::Error> {
     // buffer for nested reader
     let mut skip_buf = Vec::new();
     let mut count = 0;
+
+    #[cfg(feature = "asynchronous")]
+    let mut runtime = Runtime::new().expect("Runtime cannot be initialized");
+
+    #[cfg(feature = "asynchronous")]
+    let mut reader =
+        runtime.block_on(async { Reader::from_file("tests/documents/document.xml").await })?;
+
+    #[cfg(not(feature = "asynchronous"))]
     let mut reader = Reader::from_file("tests/documents/document.xml")?;
+
     let mut found_tables = Vec::new();
     loop {
-        match reader.read_event(&mut buf)? {
+        #[cfg(feature = "asynchronous")]
+        let event = runtime.block_on(async { reader.read_event(&mut buf).await })?;
+
+        #[cfg(not(feature = "asynchronous"))]
+        let event = reader.read_event(&mut buf)?;
+
+        match event {
             Event::Start(element) => match element.name() {
                 b"w:tbl" => {
                     count += 1;
@@ -32,7 +50,15 @@ fn main() -> Result<(), quick_xml::Error> {
                     let mut row_index = 0;
                     loop {
                         skip_buf.clear();
-                        match reader.read_event(&mut skip_buf)? {
+
+                        #[cfg(feature = "asynchronous")]
+                        let event =
+                            runtime.block_on(async { reader.read_event(&mut skip_buf).await })?;
+
+                        #[cfg(not(feature = "asynchronous"))]
+                        let event = reader.read_event(&mut skip_buf)?;
+
+                        match event {
                             Event::Start(element) => match element.name() {
                                 b"w:tr" => {
                                     stats.rows.push(vec![]);

examples/read_texts.rs

@@ -1,4 +1,5 @@
-extern crate quick_xml;
+#[cfg(feature = "asynchronous")]
+use tokio::runtime::Runtime;
 
 fn main() {
     use quick_xml::events::Event;
@@ -13,14 +14,32 @@ fn main() {
     let mut txt = Vec::new();
     let mut buf = Vec::new();
 
+    #[cfg(feature = "asynchronous")]
+    let mut runtime = Runtime::new().expect("Runtime cannot be initialized");
+
     loop {
-        match reader.read_event(&mut buf) {
+        #[cfg(feature = "asynchronous")]
+        let event = runtime.block_on(async { reader.read_event(&mut buf).await });
+
+        #[cfg(not(feature = "asynchronous"))]
+        let event = reader.read_event(&mut buf);
+
+        match event {
             Ok(Event::Start(ref e)) if e.name() == b"tag2" => {
-                txt.push(
+                #[cfg(feature = "asynchronous")]
+                let text = runtime.block_on(async {
                     reader
                         .read_text(b"tag2", &mut Vec::new())
-                        .expect("Cannot decode text value"),
-                );
+                        .await
+                        .expect("Cannot decode text value")
+                });
+
+                #[cfg(not(feature = "asynchronous"))]
+                let text = reader
+                    .read_text(b"tag2", &mut Vec::new())
+                    .expect("Cannot decode text value");
+
+                txt.push(text);
                 println!("{:?}", txt);
             }
             Ok(Event::Eof) => break, // exits the loop when reaching end of file

src/de/mod.rs

@@ -115,6 +115,7 @@ mod var;
 pub use crate::errors::serialize::DeError;
 use crate::{
     events::{BytesStart, BytesText, Event},
+    reader::Decode,
     Reader,
 };
 use serde::de::{self, DeserializeOwned};

src/errors.rs

@@ -33,7 +33,7 @@ pub enum Error {
     /// Duplicate attribute
     DuplicatedAttribute(usize, usize),
     /// Escape error
-    EscapeError(::escape::EscapeError),
+    Escape(crate::escape::EscapeError),
 }
 
 impl From<::std::io::Error> for Error {
@@ -101,7 +101,7 @@ impl std::fmt::Display for Error {
                  Duplicate attribute at position {1} and {0}",
                 pos1, pos2
             ),
-            Error::EscapeError(e) => write!(f, "{}", e),
+            Error::Escape(e) => write!(f, "{}", e),
         }
     }
 }
@@ -111,7 +111,7 @@ impl std::error::Error for Error {
         match self {
             Error::Io(e) => Some(e),
             Error::Utf8(e) => Some(e),
-            Error::EscapeError(e) => Some(e),
+            Error::Escape(e) => Some(e),
             _ => None,
         }
     }

src/escape.rs

@@ -0,0 +1,4 @@
+//! Pub escape module.
+
+pub(crate) use crate::escapei::{do_unescape, EscapeError};
+pub use crate::escapei::{escape, unescape, unescape_with};

src/escapei.rs

@@ -1,6 +1,5 @@
 //! Manage xml character escapes
 
-use memchr;
 use std::borrow::Cow;
 use std::collections::HashMap;
 use std::ops::Range;
@@ -181,7 +180,7 @@ const fn named_entity(name: &[u8]) -> Option<&str> {
         b"amp" => "&",
         b"apos" => "'",
         b"quot" => "\"",
-        _ => return None
+        _ => return None,
     };
     Some(s)
 }
@@ -820,11 +819,9 @@ const fn named_entity(name: &[u8]) -> Option<&str> {
         b"mid" | b"VerticalBar" | b"smid" | b"shortmid" => "\u{2223}",
         b"nmid" | b"NotVerticalBar" | b"nsmid" | b"nshortmid" => "\u{2224}",
         b"par" | b"parallel" | b"DoubleVerticalBar" | b"spar" | b"shortparallel" => "\u{2225}",
-        b"npar"
-        | b"nparallel"
-        | b"NotDoubleVerticalBar"
-        | b"nspar"
-        | b"nshortparallel" => "\u{2226}",
+        b"npar" | b"nparallel" | b"NotDoubleVerticalBar" | b"nspar" | b"nshortparallel" => {
+            "\u{2226}"
+        }
         b"and" | b"wedge" => "\u{2227}",
         b"or" | b"vee" => "\u{2228}",
         b"cap" => "\u{2229}",
@@ -1645,13 +1642,13 @@ const fn named_entity(name: &[u8]) -> Option<&str> {
         b"xopf" => "\u{1D56}",
         b"yopf" => "\u{1D56}",
         b"zopf" => "\u{1D56}",
-        _ => return None
+        _ => return None,
     };
     Some(s)
 }
 
 fn push_utf8(out: &mut Vec<u8>, code: char) {
-    let mut buf = [0u8; 4];
+    let mut buf = [0_u8; 4];
     out.extend_from_slice(code.encode_utf8(&mut buf).as_bytes());
 }