# roxml
[](https://crates.io/crates/roxml)
[](https://docs.rs/roxml)
[](https://blog.rust-lang.org/)
[](#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
```sh
cargo add roxml --no-default-features # no allocator needed
```
```rust
use roxml::prelude::*;
let xml = r#"<note priority="high">
<to>Alice</to>
<body>Feed the cat & 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](https://docs.rs/roxml) for the document model, what is validated,
how text and whitespace are treated, and performance characteristics.
Examples for embedded targets are in [`embedded`](https://codeberg.org/dibbots/roxml/src/branch/main/embedded).
## Features
| `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](https://codeberg.org/dibbots/roxml/src/branch/main/CONTRIBUTING.md) for how to build, test and benchmark, also on embedded targets.
## License
Licensed under either of
* Apache License, Version 2.0 [LICENSE-APACHE](LICENSE-APACHE) or [source](http://www.apache.org/licenses/LICENSE-2.0)
* MIT license [LICENSE-MIT](LICENSE-MIT) or [source](http://opensource.org/licenses/MIT)
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.