1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
// Copyright © 2026 Stephan Kunz
//! Read-only, zero-copy, lazy XML reader for `no_std` environments.
//!
//! [`XmlReader`] gives access to an XML document held in a `&str` without
//! building a DOM tree or any other intermediate representation. Navigation
//! functions scan the source on demand and every returned string borrows from
//! it. The crate neither allocates nor needs an allocator.
//!
//! It is **not** a complete XML processor. Its purpose is traversing XML
//! formatted data to directly create your own representation, for example
//! configuration or behavior tree definitions on embedded targets.
//!
//! # Example
//! ```
//! use roxml::prelude::*;
//!
//! let xml = r#"<note priority="high">
//! <to>Alice</to>
//! <from>Bob</from>
//! <body>Don't forget to feed the cat & the dog.</body>
//! </note>"#;
//!
//! let reader = XmlReader::parse(xml);
//! let root = reader.root_element()?;
//! assert_eq!(root.tag_name(), "note");
//! assert_eq!(root.attribute("priority"), Some("high"));
//!
//! for child in root.children() {
//! let BodyNode::Element(element) = child else { continue };
//! let text = element.text_node().expect("all children have text");
//! match element.tag_name() {
//! "to" => assert_eq!(text.text(), "Alice"),
//! "from" => assert_eq!(text.text(), "Bob"),
//! "body" => assert_eq!(text.unescaped(), "Don't forget to feed the cat & the dog."),
//! _ => unreachable!(),
//! }
//! }
//! # Ok::<(), roxml::Error>(())
//! ```
//!
//! # Document model
//! A document consists of three sections, each with its own access and node
//! types:
//!
//! | Section | Access | Nodes |
//! |---------|----------------------------------------------|-------|
//! | Prolog | [`XmlReader::prolog`] → [`XmlProlog`] | [`PrologNode`]: [`XmlDeclaration`], [`XmlDoctype`], [`PrologComment`], [`PrologPI`] |
//! | Body | [`XmlReader::root_element`] → [`XmlElement`] | [`BodyNode`]: [`XmlElement`], [`XmlText`], [`BodyComment`], [`BodyPI`] |
//! | Epilog | [`XmlReader::epilog`] → [`XmlEpilog`] | [`EpilogNode`]: [`EpilogComment`], [`EpilogPI`] |
//!
//! Within the body, [`XmlElement::children`] iterates the direct children of
//! an element, [`XmlElement::first_child`] and the `next_sibling()` methods
//! walk them one by one. Every node reports its byte range in the source with
//! `range()`.
//!
//! # Errors and validation
//! [`XmlReader::root_element`] checks the structure of the whole document and
//! returns an [`Error`] if it is broken, for example on mismatched close tags
//! or content after the root element. Once the root element is obtained,
//! navigation cannot fail. The other entry points, [`XmlReader::prolog`] and
//! [`XmlReader::epilog`], do not report errors, they end at malformed input.
//!
//! The check is not a full well-formedness check, see
//! [`XmlReader::root_element`] for what is and is not detected. Elements may
//! be nested at most [`MAX_DEPTH`] levels deep.
//!
//! # Text and attribute values
//! - [`XmlText::text`] and [`XmlAttribute::value`] return the raw source slice,
//! so entity references like `&` are **not** decoded. Use
//! [`XmlText::unescaped`] and [`XmlAttribute::unescaped_value`] to decode
//! them, see [`Unescaped`]. Entities declared in a DOCTYPE are not supported.
//! - CDATA sections are reported as [`XmlText`] without their markers.
//! - The whitespace of a text node is kept as written. Whitespace-only text
//! between markup, like indentation, does not form a node.
//!
//! # Namespaces
//! Names are returned as written, including a prefix (`svg:rect`).
//! [`XmlElement::prefix`] and [`XmlElement::local_name`] (and the same on
//! [`XmlAttribute`]) split them. Prefixes are not resolved to namespace URIs;
//! the `xmlns` declarations are ordinary attributes.
//!
//! # Performance
//! Nothing is parsed in advance and nothing is cached. Each navigation step
//! scans the part of the source it needs. Finding the end of an element scans
//! its whole content, so navigating a deeply nested document costs time
//! proportional to its size times its depth. [`XmlReader::root_element`] scans
//! the whole document; call it once and keep the result.
//!
//! This trades speed for memory: there is no memory use beyond the source and
//! a fixed amount of stack. For large documents that are read completely,
//! a DOM based crate like `roxmltree` or a streaming pull parser like
//! `quick-xml` may be faster.
//!
//! # Features
//! - `alloc`: adds [`Unescaped::to_cow`].
//! - `std` (default): implies `alloc`.
//!
//! Disable default features to use the crate without an allocator.
extern crate alloc;
extern crate std;
pub use ;
pub use ;
pub use Error;
pub use ;
pub use Unescaped;
pub use ;
pub use XmlDeclaration;
pub use XmlDoctype;
pub use ;
pub use XmlReader;
pub use XmlText;
/// Maximum nesting depth of elements, the root element counting as one level.
///
/// Checking that close tags match their open tags needs to remember the open
/// tags. Without an allocator they are kept on a fixed-size stack of this
/// many entries. [`XmlReader::root_element`] returns [`Error::TooDeep`] for
/// documents that nest deeper.
pub const MAX_DEPTH: usize = 64;
/// Makes the code examples of the README part of the doc tests.
;