docx_rs/reader/
xml_parser.rs

1use std::collections::VecDeque;
2use std::io::{BufReader, Read};
3
4use quick_xml::encoding::Decoder;
5use quick_xml::escape::unescape;
6use quick_xml::events::{BytesEnd, BytesRef, BytesStart, BytesText, Event};
7use quick_xml::Reader;
8use quick_xml::XmlVersion;
9
10#[derive(Clone, Debug, PartialEq, Eq)]
11pub struct OwnedName {
12    pub local_name: String,
13    pub namespace: Option<String>,
14    pub prefix: Option<String>,
15}
16
17#[derive(Clone, Debug, PartialEq, Eq)]
18pub struct OwnedAttribute {
19    pub name: OwnedName,
20    pub value: String,
21}
22
23#[derive(Clone, Debug, Default, PartialEq, Eq)]
24pub struct Namespace {
25    mappings: Vec<(String, String)>,
26}
27
28impl Namespace {
29    pub fn empty() -> Self {
30        Self {
31            mappings: Vec::new(),
32        }
33    }
34}
35
36impl IntoIterator for Namespace {
37    type Item = (String, String);
38    type IntoIter = std::vec::IntoIter<(String, String)>;
39
40    fn into_iter(self) -> Self::IntoIter {
41        self.mappings.into_iter()
42    }
43}
44
45#[derive(Clone, Debug, PartialEq)]
46pub enum XmlEvent {
47    StartElement {
48        name: OwnedName,
49        attributes: Vec<OwnedAttribute>,
50        namespace: Namespace,
51    },
52    EndElement {
53        name: OwnedName,
54    },
55    Characters(String),
56    Whitespace(String),
57    EndDocument,
58}
59
60pub struct EventReader<R: Read> {
61    reader: Reader<BufReader<R>>,
62    buf: Vec<u8>,
63    pending: VecDeque<XmlEvent>,
64    finished: bool,
65}
66
67impl<R: Read> EventReader<R> {
68    pub fn new(reader: R) -> Self {
69        let mut reader = Reader::from_reader(BufReader::new(reader));
70        {
71            let config = reader.config_mut();
72            config.trim_text(false);
73            config.check_end_names = true;
74            config.expand_empty_elements = false;
75        }
76        Self {
77            reader,
78            buf: Vec::new(),
79            pending: VecDeque::new(),
80            finished: false,
81        }
82    }
83
84    pub fn next_event(&mut self) -> Result<XmlEvent, quick_xml::Error> {
85        self.read_next()
86    }
87
88    fn read_next(&mut self) -> Result<XmlEvent, quick_xml::Error> {
89        if let Some(event) = self.pending.pop_front() {
90            return Ok(event);
91        }
92
93        loop {
94            self.buf.clear();
95            match self.reader.read_event_into(&mut self.buf)? {
96                Event::Start(element) => {
97                    let decoder = self.reader.decoder();
98                    let event = Self::build_start_event(element, decoder)?;
99                    return Ok(event);
100                }
101                Event::Empty(element) => {
102                    let decoder = self.reader.decoder();
103                    let event = Self::build_start_event(element, decoder)?;
104                    if let XmlEvent::StartElement { name, .. } = &event {
105                        self.pending
106                            .push_back(XmlEvent::EndElement { name: name.clone() });
107                    }
108                    return Ok(event);
109                }
110                Event::End(element) => {
111                    let name = build_name_from_end(&element)?;
112                    return Ok(XmlEvent::EndElement { name });
113                }
114                Event::Text(text) => {
115                    let text = decode_text(text)?;
116                    return self.read_text_event(text);
117                }
118                Event::GeneralRef(reference) => {
119                    let text = decode_reference(reference)?;
120                    return self.read_text_event(text);
121                }
122                Event::CData(text) => {
123                    let decoded = self.reader.decoder().decode(text.as_ref())?.into_owned();
124                    return Ok(XmlEvent::Characters(decoded));
125                }
126                Event::Eof => {
127                    self.finished = true;
128                    return Ok(XmlEvent::EndDocument);
129                }
130                Event::Decl(_) | Event::PI(_) | Event::Comment(_) | Event::DocType(_) => {
131                    // Skip non-structural events
132                }
133            }
134        }
135    }
136
137    fn read_text_event(&mut self, mut text: String) -> Result<XmlEvent, quick_xml::Error> {
138        loop {
139            self.buf.clear();
140            match self.reader.read_event_into(&mut self.buf)? {
141                Event::Text(next_text) => {
142                    text.push_str(&decode_text(next_text)?);
143                }
144                Event::GeneralRef(reference) => {
145                    text.push_str(&decode_reference(reference)?);
146                }
147                Event::Start(element) => {
148                    let decoder = self.reader.decoder();
149                    let event = Self::build_start_event(element, decoder)?;
150                    self.pending.push_back(event);
151                    break;
152                }
153                Event::Empty(element) => {
154                    let decoder = self.reader.decoder();
155                    let event = Self::build_start_event(element, decoder)?;
156                    let end_event = if let XmlEvent::StartElement { name, .. } = &event {
157                        Some(XmlEvent::EndElement { name: name.clone() })
158                    } else {
159                        None
160                    };
161                    self.pending.push_back(event);
162                    if let Some(end_event) = end_event {
163                        self.pending.push_back(end_event);
164                    }
165                    break;
166                }
167                Event::End(element) => {
168                    let name = build_name_from_end(&element)?;
169                    self.pending.push_back(XmlEvent::EndElement { name });
170                    break;
171                }
172                Event::CData(text) => {
173                    let decoded = self.reader.decoder().decode(text.as_ref())?.into_owned();
174                    self.pending.push_back(XmlEvent::Characters(decoded));
175                    break;
176                }
177                Event::Eof => {
178                    self.pending.push_back(XmlEvent::EndDocument);
179                    break;
180                }
181                Event::Decl(_) | Event::PI(_) | Event::Comment(_) | Event::DocType(_) => {
182                    break;
183                }
184            }
185        }
186
187        if text.chars().all(char::is_whitespace) {
188            Ok(XmlEvent::Whitespace(text))
189        } else {
190            Ok(XmlEvent::Characters(text))
191        }
192    }
193
194    fn build_start_event(
195        element: BytesStart<'_>,
196        decoder: Decoder,
197    ) -> Result<XmlEvent, quick_xml::Error> {
198        let name = build_name_from_start(&element)?;
199        let attributes = build_attributes(&element, decoder)?;
200        Ok(XmlEvent::StartElement {
201            name,
202            attributes,
203            namespace: Namespace::empty(),
204        })
205    }
206}
207
208impl<R: Read> Iterator for EventReader<R> {
209    type Item = Result<XmlEvent, quick_xml::Error>;
210
211    fn next(&mut self) -> Option<Self::Item> {
212        if self.finished {
213            return None;
214        }
215        match self.read_next() {
216            Ok(XmlEvent::EndDocument) => {
217                self.finished = true;
218                Some(Ok(XmlEvent::EndDocument))
219            }
220            Ok(event) => Some(Ok(event)),
221            Err(e) => {
222                self.finished = true;
223                Some(Err(e))
224            }
225        }
226    }
227}
228
229fn build_name_from_start(element: &BytesStart<'_>) -> Result<OwnedName, quick_xml::Error> {
230    let name = element.name();
231    Ok(split_qname(name.as_ref()))
232}
233
234fn build_name_from_end(element: &BytesEnd<'_>) -> Result<OwnedName, quick_xml::Error> {
235    let name = element.name();
236    Ok(split_qname(name.as_ref()))
237}
238
239fn decode_text(text: BytesText<'_>) -> Result<String, quick_xml::Error> {
240    Ok(text.xml_content(XmlVersion::Implicit1_0)?.into_owned())
241}
242
243fn decode_reference(reference: BytesRef<'_>) -> Result<String, quick_xml::Error> {
244    let reference = reference.xml_content(XmlVersion::Implicit1_0)?;
245    let escaped = format!("&{reference};");
246    Ok(unescape(&escaped)?.into_owned())
247}
248
249fn split_qname(raw: &[u8]) -> OwnedName {
250    let text = String::from_utf8_lossy(raw).into_owned();
251    if let Some(idx) = text.find(':') {
252        let prefix = text[..idx].to_string();
253        let local = text[idx + 1..].to_string();
254        OwnedName {
255            local_name: local,
256            namespace: None,
257            prefix: Some(prefix),
258        }
259    } else {
260        OwnedName {
261            local_name: text,
262            namespace: None,
263            prefix: None,
264        }
265    }
266}
267
268fn build_attributes(
269    element: &BytesStart<'_>,
270    decoder: Decoder,
271) -> Result<Vec<OwnedAttribute>, quick_xml::Error> {
272    let mut attributes = Vec::new();
273    for attr_result in element.attributes().with_checks(false) {
274        let attr = attr_result.map_err(quick_xml::Error::from)?;
275        let value = attr
276            .decoded_and_normalized_value(XmlVersion::Implicit1_0, decoder)?
277            .into_owned();
278        let name = split_qname(attr.key.as_ref());
279        attributes.push(OwnedAttribute { name, value });
280    }
281    Ok(attributes)
282}
283
284#[cfg(test)]
285mod tests {
286    use super::*;
287
288    #[test]
289    fn decodes_xml_entities_in_text_and_attributes() {
290        let xml = r#"<w:t w:val="A &amp; B">A &amp; B</w:t>"#;
291        let mut reader = EventReader::new(xml.as_bytes());
292
293        let start = reader.next_event().unwrap();
294        match start {
295            XmlEvent::StartElement {
296                name, attributes, ..
297            } => {
298                assert_eq!(name.prefix.as_deref(), Some("w"));
299                assert_eq!(name.local_name, "t");
300                assert_eq!(attributes[0].name.prefix.as_deref(), Some("w"));
301                assert_eq!(attributes[0].name.local_name, "val");
302                assert_eq!(attributes[0].value, "A & B");
303            }
304            event => panic!("expected start element, got {event:?}"),
305        }
306
307        assert_eq!(
308            reader.next_event().unwrap(),
309            XmlEvent::Characters("A & B".to_string())
310        );
311        assert!(matches!(
312            reader.next_event().unwrap(),
313            XmlEvent::EndElement { name } if name.local_name == "t"
314        ));
315        assert_eq!(reader.next_event().unwrap(), XmlEvent::EndDocument);
316    }
317}
docx_rs/reader/xml_parser.rs

docx_rs/reader/
xml_parser.rs
