RABOOK1 builder implementation (see rabook_compile.h). More...

#include "rabook_compile.h"
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"

Include dependency graph for rabook_compile.c:

Enumerations
enum	ra8_rabook_buffer_ptr_count_t : uint8_t { k_rabook_buffer_ptr_count = 8U }
	Number of caller-owned arena pointers validated by init. More...
enum	ra8_rabook_pool_mode_t : uint8_t { k_rabook_pool_none = 0U , k_rabook_pool_internal = 1U , k_rabook_pool_external = 2U }
	Image-pool backing selected by the first non-empty image append. More...

Functions
static ra8_err_t	internal_check_buffer_members (const ra8_rabook_buffers_t *buf)
	Reject a buffers struct with any NULL arena pointer.
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.
static uint32_t	internal_append_attrs (ra8_rabook_ctx_t ctx, const book_attr_t attrs, uint16_t attr_count)
	Append `attr_count` attribute records to the attr table contiguously.
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.
static uint32_t	internal_append_image_descriptor (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_off, uint32_t data_size)
	Append one already-bounded image descriptor.
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.

Variables
static const char *const	s_tag_rabook = "rabook_compile"
	Component tag for log messages from this module.

Detailed Description

RABOOK1 builder implementation (see rabook_compile.h).

Zero-heap builder back-end of the #149 on-device EPUB -> .rabook compiler. Each builder call appends into a caller-provided arena and latches capacity failures in the context. The sibling finalizer module owns canonical layout, CRC-32, and output publication. Keeping construction separate from serialization makes the mutable builder lifecycle independent of its memory or streaming destination.

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

Since: 0.1.0

Definition in file rabook_compile.c.

Enumeration Type Documentation

◆ ra8_rabook_buffer_ptr_count_t

enum ra8_rabook_buffer_ptr_count_t : uint8_t

Number of caller-owned arena pointers validated by init.

Since: 0.1.0

Enumerator
k_rabook_buffer_ptr_count	chapters..out member pointers.

Definition at line 34 of file rabook_compile.c.

◆ ra8_rabook_pool_mode_t

enum ra8_rabook_pool_mode_t : uint8_t

Image-pool backing selected by the first non-empty image append.

Enumerator
k_rabook_pool_none	No non-empty image has selected storage.
k_rabook_pool_internal	Bytes live in buf.image_pool.
k_rabook_pool_external	Bytes live behind the read callback.

Definition at line 39 of file rabook_compile.c.

Function Documentation

◆ internal_append_attrs()

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

static

Append attr_count attribute records to the attr table contiguously.

Copies each record and advances ctx->attr_count. The caller must have already checked that attr_count attributes fit the remaining attr arena, so this helper never overflows and never sets failed.

Parameters

[in,out]	ctx	Builder context (non-NULL, capacity pre-checked).
[in]	attrs	Attribute records to copy (non-NULL iff `attr_count` > 0).
[in]	attr_count	Number of attribute records to append.

Returns: The index of the first appended attribute, or k_book_nil when attr_count is 0.

Return values

k_book_nil attr_count is 0 (no attributes appended).

Precondition: ctx and (when attr_count > 0) attrs are non-NULL.; attr_cap - attr_count >= attr_count for the incoming count.

Postcondition: On a non-zero count, ctx->attr_count grows by attr_count.; On a zero count, the attr table is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 177 of file rabook_compile.c.

References ra8_rabook_ctx_t::attr_count, ra8_rabook_buffers_t::attrs, ra8_rabook_ctx_t::buf, and k_book_nil.

Referenced by ra8_rabook_add_element().

◆ internal_append_image_descriptor()

uint32_t internal_append_image_descriptor	(	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_off,
		uint32_t	data_size )

static

Append one already-bounded image descriptor.

Initializes every wire field and advances the descriptor count; pool ownership and capacity checks remain with the public append APIs.

Parameters

[in,out]	ctx	Builder with descriptor capacity available.
[in]	id_off	Image identifier string offset.
[in]	width	Image width in pixels.
[in]	height	Image height in pixels.
[in]	format	Encoded image format.
[in]	pixel_format	Decoded pixel format.
[in]	data_off	Logical image-pool byte offset.
[in]	data_size	Encoded byte count.

Returns: Appended descriptor index.

Return values

uint32_t Valid image-table index.

Precondition: ctx is non-NULL and has image descriptor capacity.; data_off and data_size describe a reserved logical pool span.

Postcondition: The image count advances by one.; The descriptor raw size equals its encoded data size.

Note: Internal helper; performs no pool I/O.

Since: 0.1.0

Definition at line 338 of file rabook_compile.c.

References ra8_rabook_ctx_t::buf, book_image_t::data_off, book_image_t::data_size, book_image_t::format, book_image_t::height, book_image_t::id_off, ra8_rabook_ctx_t::image_count, ra8_rabook_buffers_t::images, book_image_t::pixel_format, book_image_t::raw_size, and book_image_t::width.

Referenced by ra8_rabook_add_image(), and ra8_rabook_add_image_external().

◆ internal_check_buffer_members()

ra8_err_t internal_check_buffer_members ( const ra8_rabook_buffers_t * buf )

static

Reject a buffers struct with any NULL arena pointer.

Validates buf then each of its k_rabook_buffer_ptr_count arena pointers in turn, naming the first NULL member in the log line. Keeps rabook_compile_init flat (one table-driven check instead of ten inline guards).

Parameters

[in] buf Caller-owned arenas to validate (checked for NULL).

Returns: Error code.

Return values

k_ra8_ok	`buf` and every member pointer are non-NULL.
k_ra8_err_null_ptr	`buf` or one of its member pointers is NULL.

Precondition: buf, if non-NULL, addresses a fully-constructed buffers struct.; The member pointers are stable for the duration of this call.

Postcondition: No field is modified (read-only validation).; On k_ra8_ok every arena pointer in buf is guaranteed non-NULL.

Note: Not thread-safe in the sense of shared state, but holds none; pure.

Since: 0.1.0

Definition at line 63 of file rabook_compile.c.

References ra8_rabook_buffers_t::attrs, ra8_rabook_buffers_t::chapters, ra8_rabook_buffers_t::image_pool, ra8_rabook_buffers_t::images, k_ra8_ok, k_rabook_buffer_ptr_count, ra8_rabook_buffers_t::nodes, ra8_rabook_buffers_t::out, RA8_CHECK_NULL_PTR, s_tag_rabook, ra8_rabook_buffers_t::string_pool, and ra8_rabook_buffers_t::stylesheets.

Referenced by rabook_compile_init().

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

Variable Documentation

◆ s_tag_rabook

const char* const s_tag_rabook = "rabook_compile"

static

Component tag for log messages from this module.

Definition at line 27 of file rabook_compile.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_rabook_buffer_ptr_count_t

◆ ra8_rabook_pool_mode_t

Function Documentation

◆ internal_append_attrs()

◆ internal_append_image_descriptor()

◆ internal_check_buffer_members()

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

◆ ra8_rabook_link_child()

◆ ra8_rabook_link_sibling()

◆ ra8_rabook_set_metadata()

◆ rabook_compile_init()

Variable Documentation

◆ s_tag_rabook