Zero-heap builder that emits a RABOOK1 blob (the #149 compiler back-end). More...

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

Include dependency graph for rabook_compile.h:

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

Data Structures
struct	ra8_rabook_buffers_t
	Caller-owned, fixed-capacity arenas the builder appends into (no heap). More...
struct	ra8_rabook_ctx_t
	Builder state: the arenas plus running counts and a sticky-fail flag. More...

Typedefs
typedef ra8_err_t(*	ra8_rabook_image_read_fn) (void ctx, uint32_t offset, uint8_t dst, uint32_t requested, uint32_t *out_read)
	Read bytes from an externally stored image pool.
typedef ra8_err_t(*	ra8_rabook_write_fn) (void ctx, const uint8_t src, uint32_t requested, uint32_t *out_written)
	Append bytes to a streaming RABOOK1 destination.

Functions
ra8_err_t	rabook_compile_init (ra8_rabook_ctx_t ctx, const ra8_rabook_buffers_t buf)
	Bind a builder context to its caller-provided arenas.
uint32_t	ra8_rabook_intern (ra8_rabook_ctx_t ctx, const char str)
	Intern a NUL-terminated UTF-8 string into the pool, de-duplicated.
uint32_t	ra8_rabook_add_element (ra8_rabook_ctx_t ctx, uint32_t name_off, const book_attr_t attrs, uint16_t attr_count)
	Append an element node with its attributes; return its node index.
uint32_t	ra8_rabook_add_text (ra8_rabook_ctx_t *ctx, uint32_t text_off)
	Append a text node carrying `text_off`; return its node index.
ra8_err_t	ra8_rabook_link_child (ra8_rabook_ctx_t *ctx, uint32_t parent, uint32_t child)
	Set `parent's` first child to `child`.
ra8_err_t	ra8_rabook_link_sibling (ra8_rabook_ctx_t *ctx, uint32_t previous_node, uint32_t next_sibling)
	Set `previous_node's` next sibling to `next_sibling`.
uint32_t	ra8_rabook_add_chapter (ra8_rabook_ctx_t *ctx, uint32_t title_off, uint32_t href_off, uint32_t root_node)
	Append a spine chapter; return its chapter index.
uint32_t	ra8_rabook_add_image (ra8_rabook_ctx_t ctx, uint32_t id_off, uint16_t width, uint16_t height, uint8_t format, uint8_t pixel_format, const uint8_t data, uint32_t data_size)
	Append an image descriptor and copy its pixel/SVG bytes into the pool.
uint32_t	ra8_rabook_add_image_external (ra8_rabook_ctx_t ctx, uint32_t id_off, uint16_t width, uint16_t height, uint8_t format, uint8_t pixel_format, uint32_t data_size, uint32_t out_data_off)
	Append an image descriptor whose bytes live in a caller-owned spool.
uint32_t	ra8_rabook_add_stylesheet (ra8_rabook_ctx_t *ctx, uint32_t source_off, uint32_t scope_chapter)
	Append a preserved stylesheet; return its stylesheet index.
ra8_err_t	ra8_rabook_set_metadata (ra8_rabook_ctx_t *ctx, uint32_t title_off, uint32_t author_off, uint32_t language_off, uint32_t identifier_off, uint32_t cover_image_index)
	Record the book metadata offsets that land in the blob header.
ra8_err_t	ra8_rabook_finalize (ra8_rabook_ctx_t ctx, const void out_blob, uint32_t out_len)
	Lay out the tables and pools, fill the header, CRC, and emit the blob.
ra8_err_t	ra8_rabook_finalize_stream (const ra8_rabook_ctx_t ctx, ra8_rabook_image_read_fn image_read, void image_ctx, ra8_rabook_write_fn write, void write_ctx, uint8_t scratch, uint32_t scratch_cap, uint32_t *out_len)
	Stream a canonical flat RABOOK1 blob without a full output arena.

Detailed Description

Zero-heap builder that emits a RABOOK1 blob (the #149 compiler back-end).

rabook_compile is the serialization back-end of the on-device EPUB -> .rabook compiler (issue #149). It takes an in-memory book model – a DOM of element/text nodes with attributes, spine chapters, a string pool, transcoded images and preserved stylesheets, plus metadata – and lays it out as the exact binary RABOOK1 blob that the desktop tool tools/epub_compile/src/epub_compile.py emits and the on-device reader book parses. This file is ONLY the emitter; the XHTML -> DOM front-end and the raster -> gray4 image transcode are the next stage-(a) pieces that drive this builder.

Zero allocation: NASA Power-of-10 Rule 3: there is no malloc anywhere. The caller hands the builder a set of fixed, caller-sized arenas (one per table plus the string and image pools plus the output buffer) via ra8_rabook_buffers_t. Every builder call appends into those arenas; an overflow latches a sticky failure that ra8_rabook_finalize reports, so the caller checks once at the end.

Byte layout (matches book.h and the desktop tool): [ book_header_t ] fixed 100-byte header

[ chapter table ] header.chapter_count entries

[ node table ] header.node_count entries

[ attr table ] header.attr_count entries

[ stylesheet table ] header.stylesheet_count entries

[ image table ] header.image_count entries

[ string pool ] deduped NUL-terminated UTF-8

[ image pool ] raw 4bpp grayscale / SVG bytes

book_header_t
Fixed 100-byte prologue describing every table and pool in the blob.
Definition book.h:246

The body CRC-32 (reflected 0xEDB88320, init/final 0xFFFFFFFF – matches Python zlib.crc32) covers every byte after the 100-byte header, exactly as book_validate expects.

Note: Not thread-safe: a builder context is single-owner, mutated in place.

See also: book.h The format definition + the reader this emitter targets.

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

Since: Version 0.1.0

Definition in file rabook_compile.h.

Typedef Documentation

◆ ra8_rabook_image_read_fn

typedef ra8_err_t(* ra8_rabook_image_read_fn) (void *ctx, uint32_t offset, uint8_t *dst, uint32_t requested, uint32_t *out_read)

Read bytes from an externally stored image pool.

Parameters

[in]	ctx	Caller context supplied to ra8_rabook_finalize_stream.
[in]	offset	Byte offset in the logical image pool.
[out]	dst	Destination for `requested` bytes.
[in]	requested	Exact number of bytes requested.
[out]	out_read	Receives the number of bytes actually copied.

Returns: Read status; callback-specific failures are propagated unchanged.

Precondition: Pointers are non-NULL and dst spans requested writable bytes.

Postcondition: On success *out_read <= requested; the finalizer rejects a short read.

Note: Not thread-safe unless the callback context is independently synchronized.

Since: 0.1.0

Definition at line 130 of file rabook_compile.h.

◆ ra8_rabook_write_fn

typedef ra8_err_t(* ra8_rabook_write_fn) (void *ctx, const uint8_t *src, uint32_t requested, uint32_t *out_written)

Append bytes to a streaming RABOOK1 destination.

Parameters

[in,out]	ctx	Caller context supplied to ra8_rabook_finalize_stream.
[in]	src	Source bytes to append.
[in]	requested	Exact number of bytes requested.
[out]	out_written	Receives the number of bytes actually appended.

Returns: Write status; callback-specific failures are propagated unchanged.

Precondition: Pointers are non-NULL and src spans requested readable bytes.

Postcondition: On success *out_written <= requested; the finalizer rejects a short write.

Note: Not thread-safe unless the callback context is independently synchronized.

Since: 0.1.0

Definition at line 148 of file rabook_compile.h.

Function Documentation

◆ ra8_rabook_add_chapter()

uint32_t ra8_rabook_add_chapter	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	title_off,
		uint32_t	href_off,
		uint32_t	root_node )

Append a spine chapter; return its chapter index.

Records one chapter-table entry pointing at its root DOM node plus the interned TOC label and spine href. Chapters are appended in spine (reading) order, so the returned index doubles as the chapter's position in the book.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	title_off	String-pool offset of the TOC label ("" if none).
[in]	href_off	String-pool offset of the spine href.
[in]	root_node	Node index of this chapter's root element.

Returns: The new chapter index, or k_book_nil on overflow / error.

Return values

k_book_nil ctx is NULL or the chapter arena is full.

Precondition: ctx was initialised.; One more chapter fits the chapter arena.

Postcondition: On success the chapter table gains one entry.; On overflow failed is set and no chapter is appended.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 291 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_buffers_t::chapter_cap, ra8_rabook_ctx_t::chapter_count, ra8_rabook_buffers_t::chapters, ra8_rabook_ctx_t::failed, book_chapter_t::href_off, k_book_nil, book_chapter_t::root_node, and book_chapter_t::title_off.

Referenced by internal_append_chapter(), and ra8_rabook_xml_parse_chapter().

◆ ra8_rabook_add_element()

uint32_t ra8_rabook_add_element	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	name_off,
		const book_attr_t *	attrs,
		uint16_t	attr_count )

Append an element node with its attributes; return its node index.

Writes a k_book_node_element node carrying name_off and appends attr_count attribute records contiguously, linking the node's first_attr / attr_count. Child / sibling links default to nil; set them with ra8_rabook_link_child / ra8_rabook_link_sibling.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	name_off	String-pool offset of the tag name.
[in]	attrs	Attribute records (may be NULL iff `attr_count` is 0).
[in]	attr_count	Number of attributes for this element.

Returns: The new node index, or k_book_nil on overflow / error.

Return values

k_book_nil ctx is NULL, the node/attr arena is full, or attrs is NULL with a non-zero attr_count.

Precondition: ctx was initialised.; Adding one node and attr_count attrs fits the node / attr arenas.

Postcondition: On success node name_off, attr_count and first_attr are set.; On overflow failed is set and no node / attr is appended.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 191 of file rabook_compile.c.

References ra8_rabook_buffers_t::attr_cap, book_node_t::attr_count, ra8_rabook_ctx_t::attr_count, ra8_rabook_ctx_t::buf, ra8_rabook_ctx_t::failed, book_node_t::first_attr, book_node_t::first_child, internal_append_attrs(), k_book_nil, k_book_node_element, book_node_t::kind, book_node_t::name_off, book_node_t::next_sibling, ra8_rabook_buffers_t::node_cap, ra8_rabook_ctx_t::node_count, ra8_rabook_buffers_t::nodes, and book_node_t::text_off.

Referenced by internal_append_chapter(), and internal_element().

◆ ra8_rabook_add_image()

uint32_t ra8_rabook_add_image	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	id_off,
		uint16_t	width,
		uint16_t	height,
		uint8_t	format,
		uint8_t	pixel_format,
		const uint8_t *	data,
		uint32_t	data_size )

Append an image descriptor and copy its pixel/SVG bytes into the pool.

Copies data_size bytes into the image pool and records a descriptor with data_off set to the bytes' pool offset and raw_size == data_size (the pool is uncompressed; the whole blob is DEFLATE-wrapped on disk).

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	id_off	String-pool offset of the source href / manifest id.
[in]	width	Pixel width (0 for SVG).
[in]	height	Pixel height (0 for SVG).
[in]	format	book_image_format_t (gray4 or svg).
[in]	pixel_format	book_image_pixfmt_t depth of a gray4-format raster (gray4 = 4bpp packed, gray8 = 8bpp); pass k_book_pixfmt_gray4 (0) for an SVG entry.
[in]	data	Pixel / SVG bytes to copy (non-NULL iff `data_size` > 0).
[in]	data_size	Byte length of `data`.

Returns: The new image index, or k_book_nil on overflow / error.

Return values

k_book_nil ctx is NULL, the image table or pool is full, or data is NULL with a non-zero data_size.

Precondition: ctx was initialised.; data_size bytes fit the remaining image-pool capacity.

Postcondition: On success the descriptor's data_off addresses the copied bytes and its pixel_format records pixel_format.; On overflow failed is set and no descriptor / bytes are appended.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 362 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_ctx_t::failed, ra8_rabook_buffers_t::image_cap, ra8_rabook_ctx_t::image_count, ra8_rabook_buffers_t::image_pool, ra8_rabook_buffers_t::image_pool_cap, ra8_rabook_ctx_t::image_pool_mode, ra8_rabook_ctx_t::image_pool_size, internal_append_image_descriptor(), k_book_nil, k_rabook_pool_external, k_rabook_pool_internal, and memcpy().

Referenced by internal_add_manifest_image(), and internal_transcode_image().

◆ ra8_rabook_add_image_external()

uint32_t ra8_rabook_add_image_external	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	id_off,
		uint16_t	width,
		uint16_t	height,
		uint8_t	format,
		uint8_t	pixel_format,
		uint32_t	data_size,
		uint32_t *	out_data_off )

Append an image descriptor whose bytes live in a caller-owned spool.

Reserves the next contiguous span of the logical image pool without copying bytes into ra8_rabook_buffers_t::image_pool. The caller stores exactly data_size bytes at the returned out_data_off and later supplies a matching read callback to ra8_rabook_finalize_stream. Internal and external non-empty images cannot be mixed in one context.

Parameters

[in,out]	ctx	Builder context.
[in]	id_off	Interned image identifier offset.
[in]	width	Image width in pixels.
[in]	height	Image height in pixels.
[in]	format	book_image_format_t value.
[in]	pixel_format	book_image_pixfmt_t value.
[in]	data_size	Reserved external byte count.
[out]	out_data_off	Receives the logical image-pool offset.

Returns: The new image index, or k_book_nil on error.

Return values

k_book_nil NULL arguments, image-table exhaustion, mixed storage modes, or a logical image-pool size overflow.

Precondition: ctx was initialized and out_data_off is writable.; data_size bytes are available in the caller's spool before finalize.

Postcondition: On success the descriptor references [out_data_off, out_data_off + data_size).; On failure the sticky builder failure is latched and no descriptor is appended.

Note: The builder does not own or write the external bytes.

Since: 0.1.0

Definition at line 413 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_ctx_t::failed, ra8_rabook_buffers_t::image_cap, ra8_rabook_ctx_t::image_count, ra8_rabook_ctx_t::image_pool_mode, ra8_rabook_ctx_t::image_pool_size, internal_append_image_descriptor(), k_book_nil, k_rabook_pool_external, and k_rabook_pool_internal.

Referenced by internal_store_image().

◆ ra8_rabook_add_stylesheet()

uint32_t ra8_rabook_add_stylesheet	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	source_off,
		uint32_t	scope_chapter )

Append a preserved stylesheet; return its stylesheet index.

Records one verbatim-CSS stylesheet entry in the stylesheet table. scope_chapter limits it to a single chapter, or k_book_nil applies it book-wide; the CSS text itself is interned in the string pool and referenced by source_off.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	source_off	String-pool offset of the verbatim CSS text.
[in]	scope_chapter	Chapter index it scopes to, or k_book_nil.

Returns: The new stylesheet index, or k_book_nil on overflow / error.

Return values

k_book_nil ctx is NULL or the stylesheet arena is full.

Precondition: ctx was initialised.; One more stylesheet fits the stylesheet arena.

Postcondition: On success the stylesheet table gains one entry.; On overflow failed is set and no stylesheet is appended.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 466 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_ctx_t::failed, k_book_nil, book_stylesheet_t::scope_chapter, book_stylesheet_t::source_off, ra8_rabook_buffers_t::stylesheet_cap, ra8_rabook_ctx_t::stylesheet_count, and ra8_rabook_buffers_t::stylesheets.

Referenced by internal_compile_stylesheets().

◆ ra8_rabook_add_text()

uint32_t ra8_rabook_add_text	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	text_off )

Append a text node carrying text_off; return its node index.

Writes a k_book_node_text node whose text_off is text_off; a text node has no attributes and no children. Sibling links default to nil; set them with ra8_rabook_link_sibling.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	text_off	String-pool offset of the text run.

Returns: The new node index, or k_book_nil on overflow / error.

Return values

k_book_nil ctx is NULL or the node arena is full.

Precondition: ctx was initialised.; One more node fits the node arena.

Postcondition: On success the node is a text node with text_off set.; On overflow failed is set and no node is appended.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 233 of file rabook_compile.c.

References book_node_t::attr_count, ra8_rabook_ctx_t::buf, ra8_rabook_ctx_t::failed, book_node_t::first_attr, book_node_t::first_child, k_book_nil, k_book_node_text, book_node_t::kind, book_node_t::name_off, book_node_t::next_sibling, ra8_rabook_buffers_t::node_cap, ra8_rabook_ctx_t::node_count, ra8_rabook_buffers_t::nodes, and book_node_t::text_off.

Referenced by internal_text().

◆ ra8_rabook_finalize()

ra8_err_t ra8_rabook_finalize	(	ra8_rabook_ctx_t *	ctx,
		const void **	out_blob,
		uint32_t *	out_len )

Lay out the tables and pools, fill the header, CRC, and emit the blob.

Copies the chapter, node, attr, stylesheet and image tables, then the string and image pools, into the output buffer at the contract offsets (see the file header), fills the 100-byte book_header_t (magic, version, all offsets / counts / sizes, metadata, total_size), and computes the body CRC-32 over every byte after the header. The result passes book_validate.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised, no overflow).
[out]	out_blob	Receives the blob base (= the output arena) (non-NULL).
[out]	out_len	Receives the blob length in bytes (non-NULL).

Returns: Error code.

Return values

k_ra8_ok	Blob emitted; `out_blob` / `out_len` set.
k_ra8_err_null_ptr	A required pointer argument is NULL.
k_ra8_err_no_mem	A prior builder call overflowed an arena.
k_ra8_err_invalid_size	The laid-out blob exceeds the output capacity.

Precondition: ctx was initialised and no builder call set the sticky failed flag.; The output arena holds the full blob (header + tables + pools).

Postcondition: On k_ra8_ok, out_blob[0..*out_len) is a valid RABOOK1 blob.; On error out_blob / out_len are untouched.

Note: Not thread-safe.

See also: book_validate()

Since: Version 0.1.0

Definition at line 693 of file ra8_rabook_finalize.c.

References ra8_rabook_ctx_t::buf, internal_memory_write(), internal_validate_memory_finalize(), k_ra8_ok, ra8_rabook_buffers_t::out, ra8_rabook_buffers_t::out_cap, and ra8_rabook_finalize_stream().

Referenced by internal_compile_to_blob().

◆ ra8_rabook_finalize_stream()

ra8_err_t ra8_rabook_finalize_stream	(	const ra8_rabook_ctx_t *	ctx,
		ra8_rabook_image_read_fn	image_read,
		void *	image_ctx,
		ra8_rabook_write_fn	write,
		void *	write_ctx,
		uint8_t *	scratch,
		uint32_t	scratch_cap,
		uint32_t *	out_len )

Stream a canonical flat RABOOK1 blob without a full output arena.

Computes the same canonical layout and CRC as ra8_rabook_finalize, then appends the header, tables, string pool, and image pool through write. Internal image pools are read directly. An external image pool is read twice through image_read: once for CRC and once for emission, in chunks no larger than scratch_cap.

Parameters

[in]	ctx	Completed builder context.
[in]	image_read	External image-pool reader; required only for an external non-empty pool.
[in,out]	image_ctx	Context passed to `image_read`.
[in]	write	Exact append callback.
[in,out]	write_ctx	Context passed to `write`.
[in,out]	scratch	External-pool transfer scratch; required only for an external non-empty pool.
[in]	scratch_cap	Writable bytes at `scratch`.
[out]	out_len	Receives the complete flat blob length.

Returns: Finalization status.

Return values

k_ra8_ok	Blob streamed completely and `out_len` set.
k_ra8_err_null_ptr	A required pointer or callback is NULL.
k_ra8_err_no_mem	A prior builder operation overflowed an arena.
k_ra8_err_invalid_size	Layout overflow, zero external scratch, or a short callback transfer.

Returns: Other callback failures are propagated unchanged.

Precondition: The external reader is repeatable and exposes the logical pool recorded by ra8_rabook_add_image_external.; write appends atomically or reports the exact short transfer.

Postcondition: On success exactly *out_len bytes were appended in canonical order.; On failure out_len is untouched; the destination may hold a prefix.

Note: Uses only caller storage and fixed stack state; performs no allocation.

Since: 0.1.0

Definition at line 573 of file ra8_rabook_finalize.c.

References internal_compute_layout(), internal_crc_body(), internal_make_header(), internal_segments(), internal_validate_stream_args(), internal_write_book(), k_ra8_ok, and k_rabook_segment_count.

Referenced by ra8_rabook_comic_finish(), and ra8_rabook_finalize().

◆ ra8_rabook_intern()

uint32_t ra8_rabook_intern	(	ra8_rabook_ctx_t *	ctx,
		const char *	str )

Intern a NUL-terminated UTF-8 string into the pool, de-duplicated.

Scans the existing pool string-by-string for an exact match; on a hit returns that offset, otherwise appends str plus its NUL and returns the new offset. Identical strings therefore share one offset (the first-interned occurrence), matching the desktop StringPool so a renderer can intern-compare tags by offset.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	str	NUL-terminated string to intern (non-NULL).

Returns: The string-pool byte offset, or k_book_nil on overflow / error.

Return values

k_book_nil ctx or str is NULL, or the pool is full.

Precondition: ctx was initialised by rabook_compile_init.; str is NUL-terminated; its length is measured with strlen. (Pool overflow is handled gracefully – see the

Return values

/

Postcondition: below – so it is not a caller precondition.); On success the returned offset addresses a NUL-terminated copy of str.; On overflow the sticky failed flag is set and the pool is unchanged.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 113 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_ctx_t::failed, k_book_nil, memcpy(), ra8_rabook_buffers_t::string_cap, ra8_rabook_buffers_t::string_pool, ra8_rabook_ctx_t::string_size, and strlen().

Referenced by internal_add_manifest_image(), internal_compile_metadata(), internal_compile_stylesheets(), internal_intern(), ra8_rabook_xml_parse_chapter(), and rabook_compile_init().

◆ ra8_rabook_link_child()

ra8_err_t ra8_rabook_link_child	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	parent,
		uint32_t	child )

Set parent's first child to child.

Records the head of parent's child sibling-chain. Call once per parent with the first child; chain the rest via ra8_rabook_link_sibling.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	parent	Node index of the parent element (valid, an element).
[in]	child	Node index of the first child (valid).

Returns: Error code.

Return values

k_ra8_ok	Link recorded.
k_ra8_err_null_ptr	`ctx` is NULL.
k_ra8_err_invalid_arg	`parent` or `child` is out of range.

Precondition: ctx was initialised.; parent and child are indices of nodes already appended.

Postcondition: On success nodes[parent].first_child == child.; On error the node table is unchanged.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 260 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, book_node_t::first_child, k_ra8_err_invalid_arg, k_ra8_ok, ra8_rabook_ctx_t::node_count, ra8_rabook_buffers_t::nodes, RA8_CHECK_NULL_PTR, ra8_log_error, and s_tag_rabook.

Referenced by internal_append_chapter(), and internal_link().

◆ ra8_rabook_link_sibling()

ra8_err_t ra8_rabook_link_sibling	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	previous_node,
		uint32_t	next_sibling )

Set previous_node's next sibling to next_sibling.

Extends a child sibling-chain by one. Walk a parent's children by reading first_child then each node's next_sibling.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	previous_node	Node index whose sibling is set (valid).
[in]	next_sibling	Node index of the next sibling (valid).

Returns: Error code.

Return values

k_ra8_ok	Link recorded.
k_ra8_err_null_ptr	`ctx` is NULL.
k_ra8_err_invalid_arg	`previous_node` or `next_sibling` is out of range.

Precondition: ctx was initialised.; previous_node and next_sibling are indices of nodes already appended.

Postcondition: On success nodes[previous_node].next_sibling == next_sibling.; On error the node table is unchanged.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 276 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, k_ra8_err_invalid_arg, k_ra8_ok, book_node_t::next_sibling, ra8_rabook_ctx_t::node_count, ra8_rabook_buffers_t::nodes, RA8_CHECK_NULL_PTR, ra8_log_error, and s_tag_rabook.

Referenced by internal_link().

◆ ra8_rabook_set_metadata()

ra8_err_t ra8_rabook_set_metadata	(	ra8_rabook_ctx_t *	ctx,
		uint32_t	title_off,
		uint32_t	author_off,
		uint32_t	language_off,
		uint32_t	identifier_off,
		uint32_t	cover_image_index )

Record the book metadata offsets that land in the blob header.

Stashes the title / author / language / identifier string-pool offsets plus the cover image index; ra8_rabook_finalize copies them into the fixed 100-byte RABOOK1 header. The strings must already be interned in this builder so the offsets stay valid through finalize. If the builder has already latched its sticky failed flag the call is a no-op that reports k_ra8_err_no_mem (the same way finalize does).

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised).
[in]	title_off	String-pool offset of the title.
[in]	author_off	String-pool offset of the author.
[in]	language_off	String-pool offset of the BCP-47 language.
[in]	identifier_off	String-pool offset of the unique id.
[in]	cover_image_index	Image index of the cover, or k_book_nil.

Returns: Error code.

Return values

k_ra8_ok	Metadata recorded.
k_ra8_err_null_ptr	`ctx` is NULL.
k_ra8_err_no_mem	A prior builder call overflowed an arena (sticky failed latched); the metadata is not recorded.

Precondition: ctx was initialised.; The offsets address strings already interned in this builder.

Postcondition: On success ra8_rabook_finalize writes these into the header.; On error the recorded metadata is unchanged.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 487 of file rabook_compile.c.

References ra8_rabook_ctx_t::author_off, ra8_rabook_ctx_t::cover_image_index, ra8_rabook_ctx_t::failed, ra8_rabook_ctx_t::identifier_off, k_ra8_err_no_mem, k_ra8_ok, ra8_rabook_ctx_t::language_off, RA8_CHECK_NULL_PTR, ra8_log_error, s_tag_rabook, and ra8_rabook_ctx_t::title_off.

Referenced by internal_compile_metadata(), and internal_set_metadata().

◆ rabook_compile_init()

ra8_err_t rabook_compile_init	(	ra8_rabook_ctx_t *	ctx,
		const ra8_rabook_buffers_t *	buf )

Bind a builder context to its caller-provided arenas.

Zero-inits the running counts and clears the sticky-fail flag. All metadata offsets default to 0 and the cover index to k_book_nil until ra8_rabook_set_metadata overrides them. String-pool offset 0 is reserved for the empty string – init interns "" first so offset 0 is the empty-string sentinel that text/element nodes store, matching the desktop StringPool.__init__ in tools/epub_compile/src/epub_compile.py.

Parameters

[out]	ctx	Builder context to initialise (non-NULL).
[in]	buf	Caller-owned arenas (non-NULL; all member pointers non-NULL).

Returns: Error code.

Return values

k_ra8_ok	Context bound and ready.
k_ra8_err_null_ptr	`ctx` or `buf` (or a member pointer) is NULL.

Precondition: buf's arenas each hold at least their declared _cap.; ctx is not aliased by another live builder.

Postcondition: On success every running count is 0 and failed is false.; On success the metadata offsets are 0 and the cover index is nil.; On success string-pool offset 0 holds the empty string (string_size == 1).

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 94 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_ctx_t::cover_image_index, internal_check_buffer_members(), k_book_nil, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_rabook_intern(), and s_tag_rabook.

Referenced by internal_compile_to_blob(), and ra8_rabook_comic_init().

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ra8_rabook_image_read_fn

◆ ra8_rabook_write_fn

Function Documentation

◆ ra8_rabook_add_chapter()

◆ ra8_rabook_add_element()

◆ ra8_rabook_add_image()

◆ ra8_rabook_add_image_external()

◆ ra8_rabook_add_stylesheet()

◆ ra8_rabook_add_text()

◆ ra8_rabook_finalize()

◆ ra8_rabook_finalize_stream()

◆ ra8_rabook_intern()

◆ ra8_rabook_link_child()

◆ ra8_rabook_link_sibling()

◆ ra8_rabook_set_metadata()

◆ rabook_compile_init()