Expand description
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!(),
}
}§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::textandXmlAttribute::valuereturn the raw source slice, so entity references like&are not decoded. UseXmlText::unescapedandXmlAttribute::unescaped_valueto decode them, seeUnescaped. Entities declared in a DOCTYPE are not supported.- CDATA sections are reported as
XmlTextwithout 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: addsUnescaped::to_cow.std(default): implementsstd::error::ErrorforError; impliesalloc.
Disable default features to use the crate without an allocator.
Modules§
Structs§
- Body
Comment - A comment node inside an element body:
<!-- … -->. - BodyPI
- A processing instruction inside an element body:
<?target content?>. - Epilog
Comment - A comment in the document epilog (after the root element).
- EpilogPI
- A processing instruction in the document epilog (after the root element).
- Prolog
Comment - A comment in the document prolog.
- PrologPI
- A processing instruction in the document prolog (not the XML declaration).
- Unescaped
- The decoded form of a raw text or attribute value, computed on demand without allocation.
- XmlAttribute
- A single
name="value"pair inside an element’s opening tag. - XmlAttributes
- Iterator over attributes in an element’s opening tag.
- XmlChildren
- Iterator over the direct child nodes of an element.
- XmlDeclaration
- The XML declaration that may appear at the very start of a document.
- XmlDoctype
- A DOCTYPE declaration:
<!DOCTYPE … >. - XmlElement
- An XML element node produced by zero-copy parsing.
- XmlEpilog
- Iterator over the nodes in the document epilog (after the root element).
- XmlProlog
- Iterator over the nodes in the document prolog.
- XmlReader
- Lazily parses XML from a borrowed source string.
- XmlText
- A text node in the body of an element.
Enums§
- Body
Node - The set of node types that may appear as children of an XML element.
- Epilog
Node - A node that may appear in the document epilog (after the root element).
- Error
- Things that may go wrong during reading of the XML.
- Prolog
Node - A node that may appear in the document prolog (before the root element).
Constants§
- MAX_
DEPTH - Maximum nesting depth of elements, the root element counting as one level.