Private contracts for the EPUB NCX and nav table-of-contents consumers. More...

#include <stddef.h>
#include <stdint.h>
#include "epub_xml_consumer_internal.h"
#include "ra8_attributes.h"
#include "xml.h"

Include dependency graph for epub_xml_toc_internal.h:

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

Go to the source code of this file.

Data Structures
struct	priv_nav_ctx_t
	Mutable state for one validated EPUB navigation pass. More...
struct	priv_ncx_ctx_t
	Mutable state for one validated NCX navigation-map pass. More...

Functions
static xml_span_t	internal_ancestor_name (const xml_reader_t *reader, uint16_t depth, uint16_t levels)
	Return a checked ancestor name span.
static uint8_t	internal_ancestor_depth (const uint8_t source, size_t source_len, const xml_reader_t reader, uint16_t depth, const char *local)
	Count local-name ancestors of a TOC entry type.
static uint16_t	internal_toc_reserve (const uint8_t source, size_t source_len, const xml_event_t event, xml_reader_t reader, epub_book_t book, const char *local)
	Reserve one preflight-proven TOC slot and mark its frame.
static uint16_t	internal_toc_marker (const xml_reader_t *reader, uint16_t depth)
	Find the nearest marked ancestor frame.
static ra8_err_t	internal_toc_capacity (const uint8_t source, size_t length, epub_xml_workspace_t workspace, const xml_event_t selected, const char entry_local, bool require_list)
	Prove a selected TOC subtree fits before changing the book.
static void	internal_ncx_event (priv_ncx_ctx_t ctx, const xml_event_t event)
	Consume one event from the selected NCX navigation map.
static ra8_err_t	internal_select_nav (const uint8_t source, size_t length, epub_xml_workspace_t workspace, xml_event_t *out)
	Select typed TOC nav, falling back to the first nav descendant.
static ra8_err_t	internal_nav_has_list (const uint8_t source, size_t length, epub_xml_workspace_t workspace, const xml_event_t *selected)
	Require a direct ordered-list child before TOC mutation.
static void	internal_nav_event (priv_nav_ctx_t ctx, const xml_event_t event)
	Consume one event from the selected EPUB navigation subtree.

Detailed Description

Private contracts for the EPUB NCX and nav table-of-contents consumers.

Declares the walk state and the file-local helpers of epub_xml_toc.c; the helpers both it and the container/OPF pass call stay in epub_xml_consumer_internal.h, which this header includes. [Ring 4 / EPUB] {World: NS}

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

Since: 0.1.0

Definition in file epub_xml_toc_internal.h.

Function Documentation

◆ internal_ancestor_depth()

uint8_t internal_ancestor_depth	(	const uint8_t *	source,
		size_t	source_len,
		const xml_reader_t *	reader,
		uint16_t	depth,
		const char *	local )

static

Count local-name ancestors of a TOC entry type.

Uses live reader frames to derive flattened TOC depth.

Parameters

[in]	source	Immutable navigation source.
[in]	source_len	Exact source extent.
[in]	reader	Active reader.
[in]	depth	Current event depth.
[in]	local	NUL-terminated ancestor local name.

Returns: Bounded matching ancestor count.

Return values

count Count narrowed only within accepted reader depth.

Precondition: Reader frames belong to source and are live through depth.; local remains readable for the call.

Postcondition: No input memory is modified.; Result preserves legacy uint8_t TOC depth semantics.

Note: Accepted parser depth bounds make the narrowing deterministic.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_ancestor_name()

xml_span_t internal_ancestor_name	(	const xml_reader_t *	reader,
		uint16_t	depth,
		uint16_t	levels )

static

Return a checked ancestor name span.

Converts an invalid ancestor request to an empty span.

Parameters

[in]	reader	Active reader.
[in]	depth	Current event depth.
[in]	levels	Ancestor distance.

Returns: Ancestor name or an empty span.

Return values

span	Source-relative name when the ancestor exists.

Precondition: Reader workspace contains live frames for depth.; Source remains live and immutable.

Postcondition: Reader/workspace bytes are unchanged.; Returned nonempty span aliases source.

Note: Pure with respect to parser state.

Since: 0.1.0

◆ internal_nav_event()

void internal_nav_event	(	priv_nav_ctx_t *	ctx,
		const xml_event_t *	event )

static

Consume one event from the selected EPUB navigation subtree.

Maintains list/entry markers and copies anchor/span labels and hrefs.

Parameters

[in,out]	ctx	Active navigation consumer state.
[in]	event	Next validated pull event.

Precondition: List existence and TOC capacity were preflighted.; Event aliases the same immutable source owned by ctx.

Postcondition: Matching events update at most one reserved TOC entry.; Source bytes remain unchanged.

Note: This emission pass has no remaining error path after preflight.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_nav_has_list()

ra8_err_t internal_nav_has_list	(	const uint8_t *	source,
		size_t	length,
		epub_xml_workspace_t *	workspace,
		const xml_event_t *	selected )

static

Require a direct ordered-list child before TOC mutation.

Replays only the selected nav region and fails before emission.

Parameters

[in]	source	Immutable navigation source.
[in]	length	Exact source extent.
[in,out]	workspace	Exclusive reader scratch.
[in]	selected	Selected nav start event.

Returns: Repository error code.

Return values

k_ra8_ok	Direct ordered-list child exists.
k_ra8_err_validation_failed	List is absent or replay failed.

Precondition: Source is fully validated and selection aliases it.; Workspace is exclusive and writable.

Postcondition: Semantic TOC fields remain unchanged.; Source bytes remain unchanged.

Note: Workspace bytes are scratch on return.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_ncx_event()

void internal_ncx_event	(	priv_ncx_ctx_t *	ctx,
		const xml_event_t *	event )

static

Consume one event from the selected NCX navigation map.

Maintains frame markers and copies title/content into reserved entries.

Parameters

[in,out]	ctx	Active NCX consumer state.
[in]	event	Next validated pull event.

Precondition: TOC capacity was preflighted and ctx owns the reader/book.; Event aliases the same immutable source.

Postcondition: Matching events update at most one reserved TOC entry.; Source bytes remain unchanged.

Note: This emission pass has no remaining error path after preflight.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_select_nav()

ra8_err_t internal_select_nav	(	const uint8_t *	source,
		size_t	length,
		epub_xml_workspace_t *	workspace,
		xml_event_t *	out )

static

Select typed TOC nav, falling back to the first nav descendant.

Prefers an epub:type containing toc in document order.

Parameters

[in]	source	Immutable navigation source.
[in]	length	Exact source extent.
[in,out]	workspace	Exclusive reader scratch.
[out]	out	Selected nav start event.

Returns: Repository error code.

Return values

k_ra8_ok	A nav was selected.
k_ra8_err_validation_failed	No nav exists or replay failed.

Precondition: Source passed complete XML validation.; Output/workspace are writable and source remains live.

Postcondition: Success fills a bounded source-aliasing event.; Failure leaves source unchanged and output unspecified.

Note: Substring token policy preserves legacy EPUB behavior.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_toc_capacity()

ra8_err_t internal_toc_capacity	(	const uint8_t *	source,
		size_t	length,
		epub_xml_workspace_t *	workspace,
		const xml_event_t *	selected,
		const char *	entry_local,
		bool	require_list )

static

Prove a selected TOC subtree fits before changing the book.

Counts entry starts, optionally only after a direct ordered list.

Parameters

[in]	source	Immutable navigation source.
[in]	length	Exact source extent.
[in,out]	workspace	Exclusive reader scratch.
[in]	selected	Selected nav/navMap start event.
[in]	entry_local	NUL-terminated entry local name.
[in]	require_list	Require a direct ol before counting entries.

Returns: Repository error code.

Return values

k_ra8_ok	Entry count fits the fixed TOC capacity.
k_ra8_err_no_mem	One entry beyond capacity was observed.

Precondition: Source is fully validated and selection aliases it.; Workspace is exclusive; strings remain readable.

Postcondition: Success proves emission cannot overflow TOC slots.; Failure leaves all semantic book fields untouched.

Note: Workspace bytes are scratch on return.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_toc_marker()

uint16_t internal_toc_marker	(	const xml_reader_t *	reader,
		uint16_t	depth )

static

Find the nearest marked ancestor frame.

Walks toward the root and returns the first one-based TOC marker.

Parameters

[in]	reader	Active navigation reader.
[in]	depth	Current event depth.

Returns: Nearest marker or zero.

Return values

0	No marked ancestor exists.

Precondition: Reader workspace has live frames below depth.; Consumer marker zero remains the unassigned sentinel.

Postcondition: Reader/workspace bytes are unchanged.; Return is a valid one-based TOC slot when nonzero.

Note: Pure with respect to parser state.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_toc_reserve()

uint16_t internal_toc_reserve	(	const uint8_t *	source,
		size_t	source_len,
		const xml_event_t *	event,
		xml_reader_t *	reader,
		epub_book_t *	book,
		const char *	local )

static

Reserve one preflight-proven TOC slot and mark its frame.

Clears the slot, derives depth, and retains a one-based marker.

Parameters

[in]	source	Immutable navigation source.
[in]	source_len	Exact source extent.
[in]	event	Valid TOC-entry start event.
[in,out]	reader	Active reader whose frame receives the marker.
[in,out]	book	TOC output.
[in]	local	Entry local-name literal.

Returns: One-based TOC marker, or zero when no capacity remains.

Return values

0	No slot was reserved.

Precondition: internal_toc_capacity succeeded for this selected subtree.; Event/frame/source coordinates are consistent.

Postcondition: Success increments TOC count and initializes exactly one slot.; Non-self-closing entries retain the marker on their live frame.

Note: Capacity failure is defensive after mandatory preflight.

Since: 0.1.0

References RA8_INTERNAL.

Data Structures

Functions

Detailed Description

Function Documentation

◆ internal_ancestor_depth()

◆ internal_ancestor_name()

◆ internal_nav_event()

◆ internal_nav_has_list()

◆ internal_ncx_event()

◆ internal_select_nav()

◆ internal_toc_capacity()

◆ internal_toc_marker()

◆ internal_toc_reserve()