Documentation
// Copyright © 2026 Stephan Kunz
//! Prolog section types: `PrologNode`, `PrologComment`, `PrologPI`, `XmlProlog`.

use core::ops::Range;

use crate::{
	helpers::{extract_tag_name, find_bytes, skip_whitespace},
	xml_declaration::XmlDeclaration,
	xml_doctype::XmlDoctype,
};

/// A node that may appear in the document prolog (before the root element).
pub enum PrologNode<'xml> {
	/// The XML declaration: `<?xml … ?>`.
	Declaration(XmlDeclaration<'xml>),
	/// A DOCTYPE declaration: `<!DOCTYPE … >`.
	Doctype(XmlDoctype<'xml>),
	/// A comment: `<!-- … -->`.
	Comment(PrologComment<'xml>),
	/// A processing instruction other than the XML declaration: `<?target content?>`.
	PI(PrologPI<'xml>),
}

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

impl<'xml> PrologComment<'xml> {
	/// Comment body with `<!--` and `-->` stripped.
	pub fn text(&self) -> &'xml str {
		let s = &self.xml_text[self.range.clone()];
		s.strip_prefix("<!--")
			.and_then(|r| r.strip_suffix("-->"))
			.unwrap_or(s)
	}

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

/// A processing instruction in the document prolog (not the XML declaration).
#[derive(Clone)]
pub struct PrologPI<'xml> {
	xml_text: &'xml str,
	range: Range<usize>,
}

impl<'xml> PrologPI<'xml> {
	/// PI target name (the token immediately after `<?`).
	pub fn target(&self) -> &'xml str {
		extract_tag_name(self.xml_text, self.range.start + 2)
	}

	/// PI content: everything after the target and its trailing whitespace,
	/// up to (but not including) `?>`.
	pub fn content(&self) -> &'xml str {
		let start = self.range.start + 2;
		let target = extract_tag_name(self.xml_text, start);
		let after_target = start + target.len();
		let end = self.range.end.saturating_sub(2); // before "?>"
		self.xml_text[after_target..end].trim_start_matches(|c: char| c.is_ascii_whitespace())
	}

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

/// Iterator over the nodes in the document prolog.
///
/// Yields [`PrologNode`] values from the start of the document until the
/// first non-prolog token (the root element open-tag). Malformed input
/// causes the iterator to stop rather than error.
pub struct XmlProlog<'xml> {
	pub(crate) xml_text: &'xml str,
	pub(crate) pos: usize,
}

impl<'xml> Iterator for XmlProlog<'xml> {
	type Item = PrologNode<'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;
		}
		if b[self.pos] != b'<' {
			return None; // non-'<' content not valid in prolog — stop
		}

		// Processing instruction or XML declaration
		if b.get(self.pos + 1) == Some(&b'?') {
			let end = find_bytes(b, self.pos + 2, b"?>")? + 2;
			let range = self.pos..end;
			self.pos = end;
			// XML declaration: <?xml followed by whitespace or '?'
			let after_q = range.start + 2;
			let is_decl = b.get(after_q..after_q + 3) == Some(b"xml")
				&& matches!(
					b.get(after_q + 3),
					Some(&b' ') | Some(&b'\t') | Some(&b'\n') | Some(&b'\r') | Some(&b'?')
				);
			if is_decl {
				return Some(PrologNode::Declaration(XmlDeclaration {
					xml_text: self.xml_text,
					range,
				}));
			}
			return Some(PrologNode::PI(PrologPI {
				xml_text: self.xml_text,
				range,
			}));
		}

		// Comment
		if b.get(self.pos + 1..self.pos + 4) == Some(b"!--") {
			let end = find_bytes(b, self.pos + 4, b"-->")? + 3;
			let range = self.pos..end;
			self.pos = end;
			return Some(PrologNode::Comment(PrologComment {
				xml_text: self.xml_text,
				range,
			}));
		}

		// DOCTYPE (case-insensitive for "DOCTYPE" — handles both upper and lower)
		if b.get(self.pos + 1..self.pos + 9) == Some(b"!DOCTYPE") || b.get(self.pos + 1..self.pos + 9) == Some(b"!doctype") {
			let rel = b[self.pos..].iter().position(|&c| c == b'>')?;
			let end = self.pos + rel + 1;
			let range = self.pos..end;
			self.pos = end;
			return Some(PrologNode::Doctype(XmlDoctype {
				xml_text: self.xml_text,
				range,
			}));
		}

		// Anything else is the start of the root element — stop
		None
	}
}

#[cfg(test)]
mod tests {
	use super::*;

	const fn is_normal<T: Sized + Send + Sync>() {}

	#[test]
	const fn normal_types() {
		is_normal::<PrologComment>();
		is_normal::<&PrologComment>();
		is_normal::<PrologPI>();
		is_normal::<&PrologPI>();
		is_normal::<XmlProlog>();
		is_normal::<&XmlProlog>();
	}

	#[test]
	fn comment_text_strips_markers() {
		let src = "<!-- hello --><root/>";
		let c = PrologComment {
			xml_text: src,
			range: 0..14,
		};
		assert_eq!(c.text(), " hello ");
		assert_eq!(c.range(), 0..14);
	}

	#[test]
	fn pi_target_and_content() {
		let src = "<?target some content?><root/>";
		// "<?target some content?>" is 23 bytes (0..23)
		let pi = PrologPI {
			xml_text: src,
			range: 0..23,
		};
		assert_eq!(pi.target(), "target");
		assert_eq!(pi.content(), "some content");
		assert_eq!(pi.range(), 0..23);
	}

	#[test]
	fn prolog_stops_before_root() {
		let xml = "<?xml version=\"1.0\"?><!-- c --><root/>";
		let mut iter = XmlProlog { xml_text: xml, pos: 0 };
		assert!(matches!(iter.next(), Some(PrologNode::Declaration(_))));
		assert!(matches!(iter.next(), Some(PrologNode::Comment(_))));
		assert!(iter.next().is_none());
	}

	#[test]
	fn prolog_empty_when_no_prolog() {
		let xml = "<root/>";
		let mut iter = XmlProlog { xml_text: xml, pos: 0 };
		assert!(iter.next().is_none());
	}

	#[test]
	fn prolog_stops_on_malformed_pi() {
		let xml = "<?unclosed<root/>";
		let mut iter = XmlProlog { xml_text: xml, pos: 0 };
		assert!(iter.next().is_none()); // find_bytes for "?>" fails → stops
	}
}