roxml 0.4.2

Read-only, zero-copy, lazy XML reader for no_std environments, without allocation
Documentation

roxml

crates.io docs.rs MSRV license

Read-only, zero-copy, lazy XML reader for no_std environments.

  • No allocation: works without an allocator, every returned string borrows from the source.
  • No DOM: navigation functions scan the source on demand, there is no intermediate representation.
  • Structure aware: prolog, body and epilog of a document, with elements, text, CDATA, comments and processing instructions.
  • Checked: root_element() rejects structurally broken documents, e.g. mismatched tags.

It is not a complete XML processor. Its purpose is traversing XML formatted data to directly create your own representation, e.g. configuration on embedded targets.

Usage

cargo add roxml --no-default-features # no allocator needed
use roxml::prelude::*;

let xml = r#"<note priority="high">
    <to>Alice</to>
    <body>Feed the cat &amp; the dog.</body>
</note>"#;

let reader = XmlReader::parse(xml);
let root = reader.root_element().expect("well-formed XML");
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"),
        // entity references are decoded on request, without allocation
        "body" => assert_eq!(text.unescaped(), "Feed the cat & the dog."),
        _ => unreachable!(),
    }
}

See the documentation for the document model, what is validated, how text and whitespace are treated, and performance characteristics. Examples for embedded targets are in embedded.

Features

Feature Default Effect
std yes implies alloc
alloc no adds Unescaped::to_cow()

Limitations

  • Entities declared in a DOCTYPE are not supported, only the predefined ones and character references.
  • Namespace prefixes are not resolved to URIs.
  • Elements may be nested at most 64 levels deep (roxml::MAX_DEPTH).
  • The source must be UTF-8 (&str).

Contributing

See CONTRIBUTING.md for how to build, test and benchmark, also on embedded targets.

License

Licensed under either of

at your option.

Contribution

Any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.