Bounded, caller-owned, no-heap XML pull reader. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for xml.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	xml_span_t
	Immutable byte span expressed relative to the source. More...
struct	xml_frame_t
	One open-element identity retained for close-tag validation. More...
struct	xml_workspace_t
	Exactly bounded caller-owned nesting storage. More...
struct	xml_event_t
	One XML pull event. More...
struct	xml_attribute_t
	Source-order attribute view. More...
struct	xml_attr_cursor_t
	Mutable cursor for one start event's attributes. More...
struct	xml_reader_t
	Pull-reader state; initialise before each pass. More...

Enumerations
enum	xml_limits_t : uint16_t { k_xml_max_element_depth = 499U , k_xml_workspace_frames = 512U }
	Fixed parser geometry. More...
enum	xml_event_kind_t : uint8_t { k_xml_event_none = 0U , k_xml_event_start = 1U , k_xml_event_end = 2U , k_xml_event_text = 3U , k_xml_event_cdata = 4U }
	Pull-event kind. More...

Functions
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.
void	xml_attr_begin (const xml_event_t event, xml_attr_cursor_t cursor)
	Initialise source-order attribute iteration for a start event.
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.
bool	xml_span_equal (const uint8_t source, size_t source_len, xml_span_t span, const char literal)
	Compare a bounded span with an exact ASCII literal.
bool	xml_span_local_equal (const uint8_t source, size_t source_len, xml_span_t span, const char literal)
	Compare the namespace-local tail of a bounded span with an ASCII literal.
bool	xml_decoded_equal (const uint8_t *source, size_t source_len, xml_span_t left, xml_span_t right)
	Compare two entity-decoded spans from the same immutable source.
ra8_err_t	xml_decode (const uint8_t source, size_t source_len, xml_span_t span, char destination, size_t capacity, size_t *out_length)
	Entity-decode a source span into a bounded NUL-terminated buffer.
ra8_err_t	xml_decoded_size (const uint8_t source, size_t source_len, xml_span_t span, size_t out_length)
	Measure the entity-decoded byte count of a bounded span.
ra8_err_t	xml_decode_prefix (const uint8_t source, size_t source_len, xml_span_t span, char destination, size_t capacity, size_t *out_length)
	Decode the longest complete prefix that fits the destination.

Detailed Description

Bounded, caller-owned, no-heap XML pull reader.

The reader validates and scans immutable XML bytes without building a DOM. Element nesting lives in an explicit caller-owned workspace. Event and attribute spans alias the input and remain valid for its lifetime. The supported markup-name grammar is an explicit ASCII QName subset: one or two NCName components separated by at most one interior colon, each beginning with [A-Za-z_] and continuing with [A-Za-z0-9_.-]. Text and attribute values accept canonical UTF-8 XML 1.0 characters and the five predefined or numeric character references. One leading UTF-8 BOM and a beginning-only XML 1.0 declaration with absent or exact UTF-8/utf-8 encoding are supported. Before the root, a bare, SYSTEM, or PUBLIC external-only DOCTYPE is lexically validated and ignored; no external resource is fetched and no entity is expanded. Internal subsets, entity declarations, and every other declaration fail closed. Comments, processing instructions, and in-element CDATA are validated without becoming consumer-owned storage.

[Ring 3 / LIB] {World: NS}

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

Definition in file xml.h.

Enumeration Type Documentation

◆ xml_event_kind_t

enum xml_event_kind_t : uint8_t

Pull-event kind.

Enumerator
k_xml_event_none	No event / end of source.
k_xml_event_start	Element start.
k_xml_event_end	Element end.
k_xml_event_text	Character-data run.
k_xml_event_cdata	CDATA payload.

Definition at line 62 of file xml.h.

◆ xml_limits_t

enum xml_limits_t : uint16_t

Fixed parser geometry.

Enumerator
k_xml_max_element_depth	Accepted element levels, including root.
k_xml_workspace_frames	Physical frame capacity with headroom.

Definition at line 38 of file xml.h.

Function Documentation

◆ 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_decode()

ra8_err_t xml_decode	(	const uint8_t *	source,
		size_t	source_len,
		xml_span_t	span,
		char *	destination,
		size_t	capacity,
		size_t *	out_length )

nodiscard

Entity-decode a source span into a bounded NUL-terminated buffer.

Parameters

[in]	source	Immutable source containing `span`.
[in]	source_len	Exact readable extent of `source`.
[in]	span	Source-relative encoded text span.
[out]	destination	Decoded UTF-8 destination.
[in]	capacity	Writable destination capacity including the NUL.
[out]	out_length	Decoded bytes excluding the NUL.

Return values

k_ra8_ok	Decoded completely.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_no_mem	Destination too small.
k_ra8_err_validation_failed	`span`, UTF-8, or an entity is invalid.

Precondition: source spans source_len readable bytes.; destination spans capacity writable bytes and does not overlap source.

Postcondition: On success destination is NUL-terminated and *out_length < capacity.; source is unchanged on every result.

Note: On failure destination may contain an unterminated prefix and out_length is unspecified; the operation is not output-atomic.; Thread-safe for distinct buffers.

Since: 0.1.0

Definition at line 511 of file xml_decode.c.

References internal_decode(), k_ra8_err_null_ptr, k_ra8_err_validation_failed, and priv_xml_span_valid().

Referenced by internal_intern_span(), and priv_epub_xml_attr_contains().

◆ xml_decode_prefix()

ra8_err_t xml_decode_prefix	(	const uint8_t *	source,
		size_t	source_len,
		xml_span_t	span,
		char *	destination,
		size_t	capacity,
		size_t *	out_length )

nodiscard

Decode the longest complete prefix that fits the destination.

The prefix never splits an entity or UTF-8 sequence, and the entire encoded span is still validated after output clips.

Parameters

[in]	source	Immutable source containing `span`.
[in]	source_len	Exact readable extent of `source`.
[in]	span	Source-relative encoded text span.
[out]	destination	Decoded UTF-8 prefix destination.
[in]	capacity	Writable destination capacity including the NUL.
[out]	out_length	Decoded bytes excluding the NUL.

Return values

k_ra8_ok	Complete validation and maximal prefix decode succeeded.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_no_mem	`capacity` is zero.
k_ra8_err_validation_failed	`span`, UTF-8, or an entity is invalid.

Precondition: source spans source_len readable bytes.; destination spans capacity writable bytes and does not overlap source.

Postcondition: On success destination is NUL-terminated, *out_length < capacity, and no partial decoded codepoint/entity is present.; source is unchanged on every result.

Note: On validation failure destination may contain a prefix and out_length is unspecified; the operation is not output-atomic.; Thread-safe for distinct buffers.

Since: 0.1.0

Definition at line 527 of file xml_decode.c.

References internal_decode(), k_ra8_err_null_ptr, k_ra8_err_validation_failed, and priv_xml_span_valid().

Referenced by priv_epub_xml_copy().

◆ xml_decoded_equal()

bool xml_decoded_equal	(	const uint8_t *	source,
		size_t	source_len,
		xml_span_t	left,
		xml_span_t	right )

nodiscard

Compare two entity-decoded spans from the same immutable source.

Parameters

[in]	source	Immutable source containing both spans.
[in]	source_len	Exact readable extent of `source`.
[in]	left	First source-relative span.
[in]	right	Second source-relative span.

Returns: True only when both spans are valid and decode to identical UTF-8 bytes.

Return values

false source is NULL, a span/entity is invalid, or values differ.

Precondition: source spans source_len bytes when non-NULL.

Postcondition: No argument memory is modified.

Note: Pure, allocation-free, and thread-safe.

Since: 0.1.0

Definition at line 584 of file xml_decode.c.

References internal_decoded_byte(), k_ra8_ok, xml_span_t::length, xml_span_t::offset, and xml_decoded_size().

Referenced by internal_manifest_lookup(), and internal_mark_metadata().

◆ xml_decoded_size()

ra8_err_t xml_decoded_size	(	const uint8_t *	source,
		size_t	source_len,
		xml_span_t	span,
		size_t *	out_length )

nodiscard

Measure the entity-decoded byte count of a bounded span.

Parameters

[in]	source	Immutable source containing `span`.
[in]	source_len	Exact readable extent of `source`.
[in]	span	Source-relative encoded text span.
[out]	out_length	Exact decoded UTF-8 byte count excluding any NUL.

Return values

k_ra8_ok	Complete span measured.
k_ra8_err_null_ptr	`source` or `out_length` is NULL.
k_ra8_err_validation_failed	`span`, UTF-8, or an entity is invalid.

Precondition: source spans source_len readable bytes.

Postcondition: On success out_length is exact; on failure it is unspecified.; source is unchanged.

Note: Pure, allocation-free, and thread-safe.

Since: 0.1.0

Definition at line 544 of file xml_decode.c.

References internal_decode(), k_ra8_err_null_ptr, k_ra8_err_validation_failed, and priv_xml_span_valid().

Referenced by internal_attr_parse(), internal_intern_span(), internal_text(), internal_text(), and xml_decoded_equal().

◆ 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_span_equal()

bool xml_span_equal	(	const uint8_t *	source,
		size_t	source_len,
		xml_span_t	span,
		const char *	literal )

nodiscard

Compare a bounded span with an exact ASCII literal.

Parameters

[in]	source	Immutable source containing `span`.
[in]	source_len	Exact readable extent of `source`.
[in]	span	Candidate source-relative byte span.
[in]	literal	NUL-terminated ASCII literal.

Returns: True only for equal byte length and contents.

Return values

false A pointer is NULL, span is out of range, or bytes differ.

Precondition: source spans source_len bytes when non-NULL.

Postcondition: No argument memory is modified.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 555 of file xml_decode.c.

References xml_span_t::length, xml_span_t::offset, priv_xml_bytes_equal(), priv_xml_span_valid(), and strlen().

Referenced by internal_collect_spine(), internal_declaration_attr(), internal_font_type(), internal_opf_metadata_child(), internal_opf_shape(), internal_select_event(), priv_epub_xml_attr(), and xml_span_local_equal().

◆ xml_span_local_equal()

bool xml_span_local_equal	(	const uint8_t *	source,
		size_t	source_len,
		xml_span_t	span,
		const char *	literal )

nodiscard

Compare the namespace-local tail of a bounded span with an ASCII literal.

Parameters

[in]	source	Immutable source containing `span`.
[in]	source_len	Exact readable extent of `source`.
[in]	span	Candidate QName span.
[in]	literal	NUL-terminated local-name literal.

Returns: True only when the bytes after the optional colon equal literal.

Return values

false A pointer is NULL, span is out of range, or bytes differ.

Precondition: source spans source_len bytes when non-NULL.

Postcondition: No argument memory is modified.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 565 of file xml_decode.c.

References xml_span_t::length, xml_span_t::offset, priv_xml_span_valid(), and xml_span_equal().

Referenced by internal_ancestor_depth(), internal_collect_spine(), internal_manifest_lookup(), internal_mark_metadata(), internal_nav_event(), internal_nav_event_start(), internal_nav_has_list(), internal_ncx_event(), internal_opf_first_event(), internal_opf_metadata_child(), internal_opf_shape(), internal_select_nav(), internal_toc_capacity(), and priv_epub_xml_find().

◆ 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().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ xml_event_kind_t

◆ xml_limits_t

Function Documentation

◆ xml_attr_begin()

◆ xml_attr_next()

◆ xml_decode()

◆ xml_decode_prefix()

◆ xml_decoded_equal()

◆ xml_decoded_size()

◆ xml_reader_init()

◆ xml_reader_next()

◆ xml_span_equal()

◆ xml_span_local_equal()

◆ xml_validate()