roxml 0.4.2

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

[![crates.io](https://img.shields.io/crates/v/roxml.svg)](https://crates.io/crates/roxml)
[![docs.rs](https://img.shields.io/docsrs/roxml)](https://docs.rs/roxml)
[![MSRV](https://img.shields.io/badge/MSRV-1.95-blue)](https://blog.rust-lang.org/)
[![license](https://img.shields.io/crates/l/roxml.svg)](#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 &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](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

| 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](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.