Skip to main content

Crate roxml

Crate roxml 

Source
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 &amp; 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:

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

§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

Disable default features to use the crate without an allocator.

Modules§

prelude
Most commonly used interfaces of roxml.

Structs§

BodyComment
A comment node inside an element body: <!-- … -->.
BodyPI
A processing instruction inside an element body: <?target content?>.
EpilogComment
A comment in the document epilog (after the root element).
EpilogPI
A processing instruction in the document epilog (after the root element).
PrologComment
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§

BodyNode
The set of node types that may appear as children of an XML element.
EpilogNode
A node that may appear in the document epilog (after the root element).
Error
Things that may go wrong during reading of the XML.
PrologNode
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.