roxml 0.4.1

Read-only, zero-copy, lazy XML reader for no_std environments, without allocation
Documentation
// Copyright © 2026 Stephan Kunz
//! Epilog section types: `EpilogNode`, `EpilogComment`, `EpilogPI`, `XmlEpilog`.

use core::{fmt, ops::Range};

use crate::helpers::{comment_text, pi_content, pi_target, skip_past, skip_whitespace};

/// A node that may appear in the document epilog (after the root element).
#[derive(Clone, Debug)]
pub enum EpilogNode<'xml> {
	/// A comment: `<!-- … -->`.
	Comment(EpilogComment<'xml>),
	/// A processing instruction: `<?target content?>`.
	PI(EpilogPI<'xml>),
}

/// A comment in the document epilog (after the root element).
#[derive(Clone)]
pub struct EpilogComment<'xml> {
	xml_text: &'xml str,
	range: Range<usize>,
}

impl<'xml> EpilogComment<'xml> {
	/// Comment body with `<!--` and `-->` stripped.
	#[must_use]
	pub fn text(&self) -> &'xml str {
		comment_text(&self.xml_text[self.range.clone()])
	}

	/// Byte range of this node in the source text.
	#[must_use]
	pub fn range(&self) -> Range<usize> {
		self.range.clone()
	}
}

/// A processing instruction in the document epilog (after the root element).
#[derive(Clone)]
pub struct EpilogPI<'xml> {
	xml_text: &'xml str,
	range: Range<usize>,
}

impl<'xml> EpilogPI<'xml> {
	/// PI target name (the token immediately after `<?`).
	#[must_use]
	pub fn target(&self) -> &'xml str {
		pi_target(self.xml_text, &self.range)
	}

	/// PI content: everything after the target and its trailing whitespace,
	/// up to (but not including) `?>`.
	#[must_use]
	pub fn content(&self) -> &'xml str {
		pi_content(self.xml_text, &self.range)
	}

	/// Byte range of this node in the source text.
	#[must_use]
	pub fn range(&self) -> Range<usize> {
		self.range.clone()
	}
}

/// Iterator over the nodes in the document epilog (after the root element).
///
/// Whitespace is skipped. Any other content causes the iterator to stop.
/// Malformed input causes the iterator to stop rather than error; use
/// [`XmlReader::root_element`](crate::XmlReader::root_element) to check the
/// document.
///
/// # Examples
/// ```
/// use roxml::prelude::*;
///
/// let reader = XmlReader::parse("<log/><!-- end --><?checksum 4711?>");
/// let mut epilog = reader.epilog();
///
/// let Some(EpilogNode::Comment(comment)) = epilog.next() else { panic!() };
/// assert_eq!(comment.text(), " end ");
/// let Some(EpilogNode::PI(pi)) = epilog.next() else { panic!() };
/// assert_eq!((pi.target(), pi.content()), ("checksum", "4711"));
/// assert!(epilog.next().is_none());
/// ```
#[derive(Clone)]
pub struct XmlEpilog<'xml> {
	pub(crate) xml_text: &'xml str,
	pub(crate) pos: usize,
}

impl<'xml> Iterator for XmlEpilog<'xml> {
	type Item = EpilogNode<'xml>;

	fn next(&mut self) -> Option<Self::Item> {
		let b = self.xml_text.as_bytes();
		self.pos = skip_whitespace(self.xml_text, self.pos);
		if self.pos >= b.len() {
			return None;
		}
		// the document has been checked, only comments and PIs follow the root
		if b.get(self.pos + 1) == Some(&b'?') {
			let end = skip_past(b, self.pos + 2, b"?>");
			let range = self.pos..end;
			self.pos = end;
			Some(EpilogNode::PI(EpilogPI {
				xml_text: self.xml_text,
				range,
			}))
		} else {
			let end = skip_past(b, self.pos + 4, b"-->");
			let range = self.pos..end;
			self.pos = end;
			Some(EpilogNode::Comment(EpilogComment {
				xml_text: self.xml_text,
				range,
			}))
		}
	}
}

impl fmt::Debug for EpilogComment<'_> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		f.debug_struct("EpilogComment")
			.field("text", &self.text())
			.field("range", &self.range)
			.finish()
	}
}

impl fmt::Debug for EpilogPI<'_> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		f.debug_struct("EpilogPI")
			.field("target", &self.target())
			.field("content", &self.content())
			.field("range", &self.range)
			.finish()
	}
}

impl fmt::Debug for XmlEpilog<'_> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		f.debug_struct("XmlEpilog")
			.field("pos", &self.pos)
			.finish()
	}
}