Bounded no-heap XML pull-reader implementation. More...

#include "xml.h"
#include <limits.h>
#include <string.h>
#include "ra8_attributes.h"
#include "xml_internal.h"
#include "xml_reader_internal.h"

Include dependency graph for xml.c:

Functions
static bool	internal_space (uint8_t c)
static bool	internal_ascii_letter (uint8_t c)
static bool	internal_name_start (uint8_t c)
static bool	internal_name_continue (uint8_t c)
ra8_err_t	priv_xml_qname (const uint8_t source, size_t end, size_t start, size_t out_end)
	Scan the supported QName subset over a bounded byte range.
void	xml_attr_begin (const xml_event_t event, xml_attr_cursor_t cursor)
	Initialise source-order attribute iteration for a start event.
static ra8_err_t	internal_attr_value (const uint8_t source, uint32_t end, uint32_t position, xml_attribute_t *out)
	Parse the equals sign, quote, and value of one XML attribute.
static ra8_err_t	internal_attr_parse (const uint8_t source, size_t source_len, uint32_t end, xml_attr_cursor_t cursor, xml_attribute_t *out)
static bool	internal_attr_duplicate (const uint8_t source, size_t source_len, const xml_event_t event, const xml_attribute_t *current, uint16_t prior_count)
ra8_err_t	xml_attr_next (const uint8_t source, size_t source_len, const xml_event_t event, xml_attr_cursor_t cursor, xml_attribute_t out_attribute, bool *out_has_value)
	Return the next source-order attribute.
static ra8_err_t	internal_markup_end (const uint8_t source, size_t length, size_t start, size_t out_end)
static ra8_err_t	internal_attributes (const uint8_t source, size_t source_len, xml_event_t event)
static ra8_err_t	internal_start (xml_reader_t reader, size_t end, xml_event_t event)
static ra8_err_t	internal_end (xml_reader_t reader, size_t end, xml_event_t event)
static ra8_err_t	internal_terminator (const uint8_t source, size_t length, size_t start, const char terminator, size_t *out_start)
static ra8_err_t	internal_comment (xml_reader_t *reader)
static bool	internal_xml_target (const uint8_t *source, size_t start, size_t end)
static bool	internal_encoding (const uint8_t *source, xml_span_t value)
static bool	internal_declaration_attr (const uint8_t source, size_t source_len, const xml_attribute_t attribute, uint16_t ordinal, bool saw_encoding, bool saw_standalone)
static ra8_err_t	internal_declaration (xml_reader_t *reader, size_t target_end, size_t term)
static ra8_err_t	internal_pi (xml_reader_t *reader)
static ra8_err_t	internal_cdata (xml_reader_t reader, xml_event_t event)
static ra8_err_t	internal_special (xml_reader_t reader, xml_event_t event, bool *out_emitted)
static ra8_err_t	internal_text (xml_reader_t reader, xml_event_t event)
ra8_err_t	xml_reader_init (xml_reader_t reader, const uint8_t source, size_t source_len, xml_workspace_t *workspace)
	Initialise a pull pass over immutable bytes.
ra8_err_t	xml_reader_next (xml_reader_t reader, xml_event_t out_event)
	Return the next semantic event and validate syntax incrementally.
ra8_err_t	xml_validate (const uint8_t source, size_t source_len, xml_workspace_t workspace)
	Validate a complete document before any consumer mutation.

Detailed Description

Bounded no-heap XML pull-reader implementation.

Implements strict UTF-8/XML 1.0 lexical validation, bounded entity decoding, attribute traversal, and source-aliasing pull events using only caller-owned stack storage.

[Ring 3 / LIB] {World: NS}

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file xml.c.

Function Documentation

◆ internal_ascii_letter()

bool internal_ascii_letter ( uint8_t c )

static

Definition at line 30 of file xml.c.

References RA8_INTERNAL.

Referenced by internal_name_start().

◆ internal_attr_duplicate()

bool internal_attr_duplicate	(	const uint8_t *	source,
		size_t	source_len,
		const xml_event_t *	event,
		const xml_attribute_t *	current,
		uint16_t	prior_count )

static

Definition at line 158 of file xml.c.

References internal_attr_parse(), k_ra8_ok, xml_span_t::length, memcmp(), xml_attribute_t::name, xml_span_t::offset, RA8_INTERNAL, and xml_attr_begin().

Referenced by internal_attributes().

◆ internal_attr_parse()

ra8_err_t internal_attr_parse	(	const uint8_t *	source,
		size_t	source_len,
		uint32_t	end,
		xml_attr_cursor_t *	cursor,
		xml_attribute_t *	out )

static

Definition at line 131 of file xml.c.

References xml_attr_cursor_t::emitted, internal_attr_value(), internal_space(), k_ra8_err_validation_failed, k_ra8_ok, xml_attribute_t::name, xml_attr_cursor_t::position, priv_xml_qname(), RA8_INTERNAL, xml_attribute_t::value, and xml_decoded_size().

Referenced by internal_attr_duplicate(), internal_attributes(), internal_declaration(), and xml_attr_next().

◆ internal_attr_value()

ra8_err_t internal_attr_value	(	const uint8_t *	source,
		uint32_t	end,
		uint32_t *	position,
		xml_attribute_t *	out )

static

Parse the equals sign, quote, and value of one XML attribute.

Skips allowed XML whitespace, requires a quoted value, rejects a literal less-than sign, and advances the caller past the closing quote.

Parameters

[in]	source	Complete immutable XML source.
[in]	end	Exclusive end of the current start-tag payload.
[in,out]	position	Cursor just past the attribute name.
[out]	out	Attribute whose value span receives the parsed range.

Returns: Attribute-value parse status.

Return values

k_ra8_ok	A quoted value was parsed and `position` advanced.
k_ra8_err_validation_failed	The separator or value is malformed.

Precondition: source, position, and out are non-NULL.; *position <= end and source is readable through end.

Postcondition: Success initializes out->value and advances position.; Failure does not advance the caller-owned position.

Note: Pure except for the documented output fields.

Since: 0.1.0

Definition at line 98 of file xml.c.

References internal_space(), k_ra8_err_validation_failed, k_ra8_ok, and xml_attribute_t::value.

Referenced by internal_attr_parse().

◆ internal_attributes()

ra8_err_t internal_attributes	(	const uint8_t *	source,
		size_t	source_len,
		xml_event_t *	event )

static

Definition at line 231 of file xml.c.

References internal_attr_duplicate(), internal_attr_parse(), internal_space(), internal_space(), k_ra8_err_validation_failed, k_ra8_ok, xml_attr_cursor_t::position, xml_event_t::self_closing, and xml_attr_begin().

Referenced by internal_start().

◆ internal_cdata()

ra8_err_t internal_cdata	(	xml_reader_t *	reader,
		xml_event_t *	event )

static

Definition at line 492 of file xml.c.

References internal_terminator(), k_priv_xml_cdata_open_bytes, k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_cdata, xml_reader_t::position, priv_xml_raw(), RA8_INTERNAL, xml_reader_t::source, xml_reader_t::source_len, and xml_reader_t::stack_size.

Referenced by internal_special().

◆ internal_comment()

ra8_err_t internal_comment ( xml_reader_t * reader )

static

Definition at line 362 of file xml.c.

References internal_terminator(), k_ra8_err_validation_failed, k_ra8_ok, xml_reader_t::position, priv_xml_raw(), RA8_INTERNAL, xml_reader_t::source, and xml_reader_t::source_len.

Referenced by internal_special().

◆ internal_declaration()

ra8_err_t internal_declaration	(	xml_reader_t *	reader,
		size_t	target_end,
		size_t	term )

static

Definition at line 424 of file xml.c.

References xml_reader_t::declaration_seen, internal_attr_parse(), internal_declaration_attr(), internal_space(), k_priv_utf8_bom_first, k_ra8_err_validation_failed, k_ra8_ok, xml_attr_cursor_t::position, xml_reader_t::position, xml_reader_t::root_count, xml_reader_t::source, and xml_reader_t::source_len.

Referenced by internal_pi().

◆ internal_declaration_attr()

bool internal_declaration_attr	(	const uint8_t *	source,
		size_t	source_len,
		const xml_attribute_t *	attribute,
		uint16_t	ordinal,
		bool *	saw_encoding,
		bool *	saw_standalone )

static

Definition at line 399 of file xml.c.

References internal_encoding(), xml_attribute_t::name, RA8_INTERNAL, xml_attribute_t::value, and xml_span_equal().

Referenced by internal_declaration().

◆ internal_encoding()

bool internal_encoding	(	const uint8_t *	source,
		xml_span_t	value )

static

Definition at line 392 of file xml.c.

References k_priv_xml_encoding_bytes, xml_span_t::length, xml_span_t::offset, priv_xml_bytes_equal(), and RA8_INTERNAL.

Referenced by internal_declaration_attr().

◆ internal_end()

ra8_err_t internal_end	(	xml_reader_t *	reader,
		size_t	end,
		xml_event_t *	event )

static

Definition at line 313 of file xml.c.

References xml_workspace_t::frames, internal_space(), k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_end, memcmp(), xml_frame_t::name_length, xml_frame_t::name_offset, xml_reader_t::position, priv_xml_qname(), RA8_INTERNAL, xml_reader_t::root_closed, xml_reader_t::source, xml_reader_t::stack_size, and xml_reader_t::workspace.

Referenced by xml_reader_next().

◆ internal_markup_end()

ra8_err_t internal_markup_end	(	const uint8_t *	source,
		size_t	length,
		size_t	start,
		size_t *	out_end )

static

Definition at line 207 of file xml.c.

References k_ra8_err_validation_failed, and k_ra8_ok.

Referenced by xml_reader_next().

◆ internal_name_continue()

bool internal_name_continue ( uint8_t c )

static

Definition at line 41 of file xml.c.

References internal_name_start(), and RA8_INTERNAL.

Referenced by priv_xml_qname().

◆ internal_name_start()

bool internal_name_start ( uint8_t c )

static

Definition at line 36 of file xml.c.

References internal_ascii_letter(), and RA8_INTERNAL.

Referenced by internal_name_continue(), and priv_xml_qname().

◆ internal_pi()

ra8_err_t internal_pi ( xml_reader_t * reader )

static

Definition at line 465 of file xml.c.

References internal_declaration(), internal_space(), internal_terminator(), internal_xml_target(), k_ra8_err_validation_failed, k_ra8_ok, xml_reader_t::position, priv_xml_bytes_equal(), priv_xml_qname(), priv_xml_raw(), RA8_INTERNAL, xml_reader_t::source, and xml_reader_t::source_len.

Referenced by internal_special().

◆ internal_space()

bool internal_space ( uint8_t c )

static

Definition at line 24 of file xml.c.

References RA8_INTERNAL.

Referenced by internal_attr_parse(), internal_attr_value(), internal_attributes(), internal_end(), internal_pi(), internal_start(), and internal_text().

◆ internal_special()

ra8_err_t internal_special	(	xml_reader_t *	reader,
		xml_event_t *	event,
		bool *	out_emitted )

static

Definition at line 515 of file xml.c.

References internal_cdata(), internal_comment(), internal_pi(), k_priv_xml_cdata_open_bytes, k_priv_xml_doctype_open_bytes, k_ra8_err_validation_failed, k_ra8_ok, xml_reader_t::position, priv_xml_bytes_equal(), priv_xml_doctype(), xml_reader_t::source, and xml_reader_t::source_len.

Referenced by xml_reader_next().

◆ internal_start()

ra8_err_t internal_start	(	xml_reader_t *	reader,
		size_t	end,
		xml_event_t *	event )

static

◆ internal_terminator()

ra8_err_t internal_terminator	(	const uint8_t *	source,
		size_t	length,
		size_t	start,
		const char *	terminator,
		size_t *	out_start )

static

Definition at line 346 of file xml.c.

References k_ra8_err_validation_failed, k_ra8_ok, priv_xml_bytes_equal(), RA8_INTERNAL, and strlen().

Referenced by internal_cdata(), internal_comment(), and internal_pi().

◆ internal_text()

ra8_err_t internal_text	(	xml_reader_t *	reader,
		xml_event_t *	event )

static

Definition at line 539 of file xml.c.

References internal_space(), k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_text, xml_reader_t::position, RA8_INTERNAL, xml_reader_t::source, xml_reader_t::source_len, xml_reader_t::stack_size, and xml_decoded_size().

Referenced by xml_reader_next().

◆ internal_xml_target()

bool internal_xml_target	(	const uint8_t *	source,
		size_t	start,
		size_t	end )

static

Definition at line 385 of file xml.c.

References RA8_INTERNAL.

Referenced by internal_pi().

◆ priv_xml_qname()

ra8_err_t priv_xml_qname	(	const uint8_t *	source,
		size_t	end,
		size_t	start,
		size_t *	out_end )

Scan the supported QName subset over a bounded byte range.

Accepts one or two ASCII NCName components separated by one colon.

Parameters

[in]	source	Immutable XML source.
[in]	end	One-past-last readable lexical byte.
[in]	start	Candidate QName start offset.
[out]	out_end	One-past-last accepted QName byte.

Returns: Repository error code.

Return values

k_ra8_ok	At least one valid QName component was consumed.
k_ra8_err_validation_failed	Start or namespace spelling was invalid.

Precondition: source spans at least end readable bytes.; out_end is writable and does not overlap source.

Postcondition: Success sets an offset in [start + 1, end].; Failure leaves source unchanged and output unspecified.

Note: This is the documented ASCII QName subset, not full XML NameStartChar.

Since: 0.1.0

Definition at line 47 of file xml.c.

References internal_name_continue(), internal_name_start(), k_ra8_err_validation_failed, and k_ra8_ok.

Referenced by internal_attr_parse(), internal_end(), internal_pi(), internal_start(), and priv_xml_doctype().

◆ xml_attr_begin()

void xml_attr_begin	(	const xml_event_t *	event,
		xml_attr_cursor_t *	cursor )

Initialise source-order attribute iteration for a start event.

Derives the first attribute position from the event's bounded name span.

Parameters

[in]	event	Valid start event returned by the reader.
[out]	cursor	Attribute cursor to initialise.

Precondition: event aliases the same live source later passed to xml_attr_next.; cursor does not overlap event.

Postcondition: With non-NULL arguments, cursor addresses the first attribute.; If either argument is NULL, no memory is modified.

Note: Thread-safe for distinct cursors.

Since: 0.1.0

Definition at line 70 of file xml.c.

References xml_attr_cursor_t::emitted, and xml_attr_cursor_t::position.

Referenced by internal_attr_duplicate(), internal_attributes(), internal_attributes(), and priv_epub_xml_attr().

◆ xml_attr_next()

ra8_err_t xml_attr_next	(	const uint8_t *	source,
		size_t	source_len,
		const xml_event_t *	event,
		xml_attr_cursor_t *	cursor,
		xml_attribute_t *	out_attribute,
		bool *	out_has_value )

nodiscard

Return the next source-order attribute.

Parameters

[in]	source	Immutable source that produced `event`.
[in]	source_len	Exact readable extent of `source`.
[in]	event	Start event whose attributes are being traversed.
[in,out]	cursor	Cursor initialised by xml_attr_begin.
[out]	out_attribute	Next source-aliasing name/value spans.
[out]	out_has_value	False after the final attribute.

Return values

k_ra8_ok	An attribute or the clean end of the sequence was reported.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_validation_failed	An event/span/cursor is stale or malformed.

Precondition: source spans exactly source_len readable bytes and remains live.; event came from that same source and cursor belongs to event.

Postcondition: On success with *out_has_value, spans are within source_len and the cursor advances once; on clean end, out_attribute is unchanged.; source and event are never modified.

Note: On failure, discard cursor and out_attribute; progress may be partial.; Thread-safe for distinct cursors.

Since: 0.1.0

Definition at line 181 of file xml.c.

References xml_event_t::attribute_count, xml_attr_cursor_t::emitted, internal_attr_parse(), k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, xml_span_t::length, xml_event_t::markup, xml_event_t::name, and priv_xml_span_valid().

Referenced by internal_attributes(), and priv_epub_xml_attr().

◆ xml_reader_init()

ra8_err_t xml_reader_init	(	xml_reader_t *	reader,
		const uint8_t *	source,
		size_t	source_len,
		xml_workspace_t *	workspace )

nodiscard

Initialise a pull pass over immutable bytes.

Parameters

[out]	reader	Reader state to initialise.
[in]	source	Immutable complete XML byte sequence.
[in]	source_len	Exact readable extent of `source` in bytes.
[in,out]	workspace	Exclusive caller-owned element-stack storage.

Return values

k_ra8_ok	Reader ready.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_size	`source_len` is zero or exceeds UINT32_MAX.

Precondition: source remains readable and immutable for the complete pull pass.; source_len is the source's true readable extent, not a sentinel length.; workspace is not shared with another live reader.

Postcondition: On success reader owns no source bytes and starts before the first event.; On failure source and workspace are unchanged.

Note: A leading UTF-8 BOM is consumed only when it begins at byte zero.; Thread-safe for distinct readers, sources, and workspaces.

Since: 0.1.0

Definition at line 571 of file xml.c.

References k_priv_utf8_bom_first, k_priv_utf8_bom_second, k_priv_utf8_bom_third, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, and xml_reader_t::position.

Referenced by internal_emit(), internal_select(), priv_epub_xml_reader(), and xml_validate().

◆ xml_reader_next()

ra8_err_t xml_reader_next	(	xml_reader_t *	reader,
		xml_event_t *	out_event )

nodiscard

Return the next semantic event and validate syntax incrementally.

Parameters

[in,out]	reader	Active pull pass.
[out]	out_event	Next source-aliasing event.

Return values

k_ra8_ok	Event returned, or kind==none at validated EOF.
k_ra8_err_null_ptr	`reader` or `out_event` is NULL.
k_ra8_err_validation_failed	Malformed XML or depth overflow.

Precondition: reader was initialised successfully and its source remains live.

Postcondition: On success with a non-none event, all spans stay within reader->source_len.; On success with a none event, exactly one root closed and no frame is live.; The immutable source is never modified.

Note: After a validation failure, discard the event and reinitialise the pass; reader/workspace progress is not failure-atomic.; Thread-safe for distinct reader/workspace pairs.

Since: 0.1.0

Definition at line 590 of file xml.c.

References xml_reader_t::finished, internal_end(), internal_markup_end(), internal_special(), internal_start(), internal_text(), k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, xml_reader_t::position, xml_reader_t::root_closed, xml_reader_t::root_count, xml_reader_t::source, xml_reader_t::source_len, and xml_reader_t::stack_size.

Referenced by internal_collect_spine(), internal_emit(), internal_manifest_lookup(), internal_nav_has_list(), internal_opf_first(), internal_opf_shape(), internal_select(), internal_select_nav(), internal_toc_capacity(), priv_epub_xml_find(), priv_epub_xml_parse_nav(), priv_epub_xml_parse_ncx(), and xml_validate().

◆ xml_validate()

ra8_err_t xml_validate	(	const uint8_t *	source,
		size_t	source_len,
		xml_workspace_t *	workspace )

nodiscard

Validate a complete document before any consumer mutation.

Parameters

[in]	source	Immutable complete XML byte sequence.
[in]	source_len	Exact readable extent of `source`.
[in,out]	workspace	Exclusive caller-owned validation stack.

Return values

k_ra8_ok	Document is well formed within the depth bound.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_size	`source_len` is zero or exceeds UINT32_MAX.
k_ra8_err_validation_failed	Document is malformed.

Precondition: source spans exactly source_len readable bytes.; workspace is not shared by another live reader.

Postcondition: source is byte-for-byte unchanged on success and failure.; Success permits a consumer to begin a fresh pass using the same workspace.

Note: Workspace contents are scratch and unspecified after either result.; Thread-safe for distinct sources and workspaces.

Since: 0.1.0

Definition at line 631 of file xml.c.

References k_ra8_ok, k_xml_event_none, xml_reader_init(), and xml_reader_next().

Referenced by priv_epub_xml_parse_container(), priv_epub_xml_parse_nav(), priv_epub_xml_parse_ncx(), priv_epub_xml_parse_opf(), and ra8_rabook_xml_parse_chapter().

Functions

Detailed Description

Function Documentation

◆ internal_ascii_letter()

◆ internal_attr_duplicate()

◆ internal_attr_parse()

◆ internal_attr_value()

◆ internal_attributes()

◆ internal_cdata()

◆ internal_comment()

◆ internal_declaration()

◆ internal_declaration_attr()

◆ internal_encoding()

◆ internal_end()

◆ internal_markup_end()

◆ internal_name_continue()

◆ internal_name_start()

◆ internal_pi()

◆ internal_space()

◆ internal_special()

◆ internal_start()

◆ internal_terminator()

◆ internal_text()

◆ internal_xml_target()

◆ priv_xml_qname()

◆ xml_attr_begin()

◆ xml_attr_next()

◆ xml_reader_init()

◆ xml_reader_next()

◆ xml_validate()