epub_xml_toc.c File Reference

Bounded NCX and EPUB 3 nav table-of-contents consumers. More...

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

Include dependency graph for epub_xml_toc.c:

Go to the source code of this file.

Functions
static xml_span_t	internal_ancestor_name (const xml_reader_t *reader, uint16_t depth, uint16_t levels)
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)
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)
static uint16_t	internal_toc_marker (const xml_reader_t *reader, uint16_t depth)
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)
static void	internal_ncx_event (priv_ncx_ctx_t *ctx, const xml_event_t *event)
ra8_err_t	priv_epub_xml_parse_ncx (const uint8_t *xml_bytes, size_t xml_len, epub_book_t *book)
	Parse an EPUB 2 NCX document into book->toc.
static ra8_err_t	internal_select_nav (const uint8_t *source, size_t length, epub_xml_workspace_t *workspace, xml_event_t *out)
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)
static void	internal_nav_event_start (priv_nav_ctx_t *ctx, const xml_event_t *event)
	Dispatch one start-tag event inside an active nav-list subtree.
static void	internal_nav_event (priv_nav_ctx_t *ctx, const xml_event_t *event)
ra8_err_t	priv_epub_xml_parse_nav (const uint8_t *xml_bytes, size_t xml_len, epub_book_t *book)
	Parse an EPUB 3 nav document into book->toc.

Detailed Description

Bounded NCX and EPUB 3 nav table-of-contents consumers.

Replays an already-validated navigation document through the caller-owned pull-reader workspace, proves the selected subtree fits the fixed-capacity TOC table before a single entry is written, and only then records each entry's nesting depth, title, and href. The container and OPF passes that name the navigation document live in epub_xml_shim.c; the helpers both sides share are declared in epub_xml_consumer_internal.h.

[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.c.

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

Definition at line 37 of file epub_xml_toc.c.

References priv_epub_xml_frame_name(), RA8_INTERNAL, and xml_span_local_equal().

Referenced by internal_toc_reserve().

internal_ancestor_name()

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

static

Definition at line 29 of file epub_xml_toc.c.

References priv_epub_xml_ancestor_frame(), and priv_epub_xml_frame_name().

Referenced by internal_nav_event(), and internal_ncx_event().

internal_nav_event()

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

static

Definition at line 347 of file epub_xml_toc.c.

References priv_nav_ctx_t::active, priv_nav_ctx_t::book, xml_event_t::depth, internal_ancestor_name(), internal_nav_event_start(), k_epub_meta_len, k_xml_event_end, k_xml_event_start, k_xml_event_text, xml_event_t::kind, xml_event_t::markup, xml_span_t::offset, priv_epub_xml_ancestor_marker(), priv_epub_xml_copy(), RA8_INTERNAL, priv_nav_ctx_t::reader, priv_nav_ctx_t::selected, priv_nav_ctx_t::source, priv_nav_ctx_t::source_len, epub_toc_entry_t::title, epub_book_t::toc, and xml_span_local_equal().

Referenced by priv_epub_xml_parse_nav().

internal_nav_event_start()

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

static

Dispatch one start-tag event inside an active nav-list subtree.

Detects the <ol> that begins the selected list, reserves a TOC slot for each <li>, and – for the first <a> or <span> label inside a reserved item – records its marker, copies an <a> href, and resets the title so the following text event can fill it in.

Parameters

[in,out]	ctx	Active nav-walk context (source, reader, book, flags).
[in]	event	Start-tag event being classified.

Returns

Nothing.

Precondition

ctx->active is true; the caller only reaches this dispatch once the selected nav's subtree has been entered.

event->kind is k_xml_event_start.

Postcondition

At most one of ctx->saw_ol, a reserved TOC slot's consumer marker, or a TOC entry's href/title is updated.

A start tag matching no arm, or one whose enclosing item never reserved a slot, leaves ctx and the book unchanged.

Note

Extracted from internal_nav_event so both stay within the 60-line function cap and the nesting-depth cap; the vectors that cover it are unchanged.

Since

0.1.0

Definition at line 313 of file epub_xml_toc.c.

References priv_nav_ctx_t::book, xml_frame_t::consumer, xml_event_t::depth, xml_workspace_t::frames, epub_toc_entry_t::href, internal_toc_marker(), internal_toc_reserve(), k_epub_max_path_len, xml_event_t::name, priv_attr_t::present, priv_epub_xml_attr(), priv_epub_xml_copy(), priv_epub_xml_direct_child(), RA8_INTERNAL, priv_nav_ctx_t::reader, priv_nav_ctx_t::saw_ol, priv_nav_ctx_t::selected, xml_event_t::self_closing, priv_nav_ctx_t::source, priv_nav_ctx_t::source_len, priv_attr_t::span, epub_toc_entry_t::title, epub_book_t::toc, xml_reader_t::workspace, and xml_span_local_equal().

Referenced by internal_nav_event().

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

Definition at line 260 of file epub_xml_toc.c.

References xml_event_t::depth, k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_end, k_xml_event_none, k_xml_event_start, xml_event_t::markup, xml_span_t::offset, priv_epub_xml_direct_child(), priv_epub_xml_reader(), RA8_INTERNAL, xml_reader_next(), and xml_span_local_equal().

Referenced by priv_epub_xml_parse_nav().

internal_ncx_event()

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

static

Definition at line 129 of file epub_xml_toc.c.

References priv_ncx_ctx_t::active, priv_ncx_ctx_t::book, xml_event_t::depth, epub_toc_entry_t::href, internal_ancestor_name(), internal_toc_marker(), internal_toc_reserve(), k_epub_max_path_len, k_epub_meta_len, k_xml_event_end, k_xml_event_start, k_xml_event_text, xml_event_t::kind, xml_event_t::markup, xml_event_t::name, xml_span_t::offset, priv_attr_t::present, priv_epub_xml_ancestor_frame(), priv_epub_xml_attr(), priv_epub_xml_copy(), RA8_INTERNAL, priv_ncx_ctx_t::reader, priv_ncx_ctx_t::selected, priv_ncx_ctx_t::source, priv_ncx_ctx_t::source_len, priv_attr_t::span, epub_toc_entry_t::title, epub_book_t::toc, and xml_span_local_equal().

Referenced by priv_epub_xml_parse_ncx().

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

Definition at line 223 of file epub_xml_toc.c.

References k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_none, k_xml_event_start, xml_event_t::kind, priv_epub_xml_attr(), priv_epub_xml_attr_contains(), priv_epub_xml_reader(), RA8_INTERNAL, xml_reader_next(), and xml_span_local_equal().

Referenced by priv_epub_xml_parse_nav().

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

Definition at line 87 of file epub_xml_toc.c.

References xml_event_t::depth, k_epub_max_toc, k_ra8_err_no_mem, k_ra8_ok, k_xml_event_end, k_xml_event_none, k_xml_event_start, xml_event_t::markup, xml_span_t::offset, priv_epub_xml_direct_child(), priv_epub_xml_reader(), RA8_INTERNAL, xml_reader_next(), and xml_span_local_equal().

Referenced by priv_epub_xml_parse_nav(), and priv_epub_xml_parse_ncx().

internal_toc_marker()

uint16_t internal_toc_marker ( const xml_reader_t * reader, uint16_t depth )

static

Definition at line 74 of file epub_xml_toc.c.

References xml_frame_t::consumer, xml_workspace_t::frames, RA8_INTERNAL, and xml_reader_t::workspace.

Referenced by internal_nav_event_start(), and internal_ncx_event().

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

Definition at line 52 of file epub_xml_toc.c.

References xml_frame_t::consumer, epub_toc_entry_t::depth, xml_event_t::depth, xml_workspace_t::frames, internal_ancestor_depth(), k_epub_max_toc, RA8_INTERNAL, xml_event_t::self_closing, epub_book_t::toc, epub_book_t::toc_count, and xml_reader_t::workspace.

Referenced by internal_nav_event_start(), and internal_ncx_event().

priv_epub_xml_parse_nav()

ra8_err_t priv_epub_xml_parse_nav	(	const uint8_t *	xml_bytes,
		size_t	xml_len,
		epub_book_t *	book )

Parse an EPUB 3 nav document into book->toc.

Locates the <nav epub:type="toc"> element, falling back to the first <nav>, then walks its <ol>/<li> tree. Each <li> contributes one entry (<a> text becomes the title, <a href> the href) and nested <ol> elements increase the entry depth.

Parameters

[in]	xml_bytes	Nav document bytes. Not NUL-terminated.
[in]	xml_len	Exact readable extent of xml_bytes in bytes.
[in,out]	book	Book record whose toc / toc_count are set.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Table of contents recorded.
k_ra8_err_null_ptr	xml_bytes or book was NULL.
k_ra8_err_invalid_size	xml_len is zero.
k_ra8_err_validation_failed	The XML is malformed or has no usable nav.
k_ra8_err_no_mem	The nav tree exceeds the fixed TOC capacity.

Precondition

xml_bytes is readable for xml_len bytes.

priv_epub_xml_parse_opf() has already run for book.

Postcondition

On success book->toc[0..toc_count) is replaced. On failure existing TOC fields are unchanged; embedded workspace scratch is unspecified.

The function performs no dynamic allocation and never changes the source.

Note

Thread-safe for distinct books.

See also

priv_epub_xml_parse_ncx()

Since

0.1.0

Definition at line 379 of file epub_xml_toc.c.

References internal_nav_event(), internal_nav_has_list(), internal_select_nav(), internal_toc_capacity(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_none, priv_epub_xml_reader(), epub_xml_workspace_t::reader, priv_nav_ctx_t::saw_ol, epub_book_t::toc_count, xml_reader_next(), xml_validate(), and epub_book_t::xml_workspace.

Referenced by internal_load_toc().

priv_epub_xml_parse_ncx()

ra8_err_t priv_epub_xml_parse_ncx	(	const uint8_t *	xml_bytes,
		size_t	xml_len,
		epub_book_t *	book )

Parse an EPUB 2 NCX document into book->toc.

Walks <navMap> depth-first. Each <navPoint> contributes one entry (<navLabel><text> becomes the title, <content src> the href) and nested <navPoint> elements increase the entry depth.

Parameters

[in]	xml_bytes	NCX document bytes. Not NUL-terminated.
[in]	xml_len	Exact readable extent of xml_bytes in bytes.
[in,out]	book	Book record whose toc / toc_count are set.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Table of contents recorded.
k_ra8_err_null_ptr	xml_bytes or book was NULL.
k_ra8_err_invalid_size	xml_len is zero.
k_ra8_err_validation_failed	The XML is malformed or has no nav map.
k_ra8_err_no_mem	The nav map exceeds the fixed TOC capacity.

Precondition

xml_bytes is readable for xml_len bytes.

priv_epub_xml_parse_opf() has already run for book.

Postcondition

On success book->toc[0..toc_count) is replaced. On failure existing TOC fields are unchanged; embedded workspace scratch is unspecified.

The function performs no dynamic allocation and never changes the source.

Note

Thread-safe for distinct books.

See also

priv_epub_xml_parse_nav()

Since

0.1.0

Definition at line 176 of file epub_xml_toc.c.

References internal_ncx_event(), internal_toc_capacity(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, k_xml_event_none, priv_epub_xml_find(), priv_epub_xml_reader(), epub_xml_workspace_t::reader, epub_book_t::toc_count, xml_reader_next(), xml_validate(), and epub_book_t::xml_workspace.

Referenced by internal_load_toc().