roxml 0.4.0

Read-only, zero-copy, lazy XML reader for no_std environments, without allocation
Documentation
// Copyright © 2026 Stephan Kunz
//! 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!(),
//!     }
//! }
//! # Ok::<(), roxml::Error>(())
//! ```
//!
//! # 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::text`] and [`XmlAttribute::value`] return the raw source slice,
//!   so entity references like `&amp;` are **not** decoded. Use
//!   [`XmlText::unescaped`] and [`XmlAttribute::unescaped_value`] to decode
//!   them, see [`Unescaped`]. Entities declared in a DOCTYPE are not supported.
//! - CDATA sections are reported as [`XmlText`] without 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`: adds [`Unescaped::to_cow`].
//! - `std` (default): implements [`std::error::Error`] for [`Error`]; implies `alloc`.
//!
//! Disable default features to use the crate without an allocator.

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(missing_docs)]

#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(feature = "std")]
extern crate std;

mod body;
mod epilog;
mod error;
mod helpers;
pub mod prelude;
mod prolog;
mod unescaped;
mod xml_attribute;
mod xml_declaration;
mod xml_doctype;
mod xml_element;
mod xml_reader;
mod xml_text;

pub use body::{BodyComment, BodyNode, BodyPI};
pub use epilog::{EpilogComment, EpilogNode, EpilogPI, XmlEpilog};
pub use error::Error;
pub use prolog::{PrologComment, PrologNode, PrologPI, XmlProlog};
pub use unescaped::Unescaped;
pub use xml_attribute::{XmlAttribute, XmlAttributes};
pub use xml_declaration::XmlDeclaration;
pub use xml_doctype::XmlDoctype;
pub use xml_element::{XmlChildren, XmlElement};
pub use xml_reader::XmlReader;
pub use xml_text::XmlText;

/// Maximum nesting depth of elements, the root element counting as one level.
///
/// Checking that close tags match their open tags needs to remember the open
/// tags. Without an allocator they are kept on a fixed-size stack of this
/// many entries. [`XmlReader::root_element`] returns [`Error::TooDeep`] for
/// documents that nest deeper.
pub const MAX_DEPTH: usize = 64;

/// Makes the code examples of the README part of the doc tests.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeDoctests;