Package a downloaded chapter folder into a reader-openable container. More...

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

Include dependency graph for mdl_export.h:

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

Data Structures
struct	mdl_export_meta_t
	Rich series and chapter metadata for export containers (ComicInfo.xml, EPUB OPF). More...
struct	mdl_export_workspace
	Caller-owned bounded arena for all exporter scratch state. More...

Typedefs
typedef struct mdl_export_workspace	mdl_export_workspace_t
	Caller-owned bounded arena for all exporter scratch state.

Enumerations
enum	mdl_meta_size_t : uint16_t { k_mdl_meta_title_max = 256 , k_mdl_meta_summary_max = 1024 , k_mdl_meta_name_max = 128 , k_mdl_meta_url_max = 512 , k_mdl_meta_path_max = 1024 , k_mdl_meta_lang_max = 16 , k_mdl_meta_id_max = 96 , k_mdl_meta_date_max = 32 }
	Sizing constants for metadata fields. More...
enum	mdl_reading_direction_t : uint8_t { k_mdl_read_ltr = 0 , k_mdl_read_rtl = 1 }
	Logical page progression used by fixed-layout readers. More...

Functions
mdl_format_t	mdl_format_from_str (const char *s)
	Map a --format string to a container kind.
const char *	mdl_format_ext (mdl_format_t fmt)
	File extension (without dot) for a format, e.g.
bool	mdl_format_is_dir_output (mdl_format_t fmt)
	Whether fmt writes per-page sibling files rather than one container.
void	mdl_meta_init (mdl_export_meta_t *meta)
	Initialise a metadata struct to empty/default values.
ra8_err_t	mdl_meta_parse (mdl_export_meta_t meta, const char text)
	Parse metadata key-value lines or XML text into a metadata struct.
ra8_err_t	mdl_meta_load_dir (mdl_storage_t storage, mdl_export_meta_t meta, const char *dir)
	Load metadata from a directory by looking for metadata files.
ra8_err_t	mdl_export_build_comicinfo (const mdl_export_meta_t meta, char buf, size_t cap)
	Generate ComicInfo.xml content from metadata.
ra8_err_t	mdl_export_build_comicinfo_pages (const mdl_export_meta_t meta, size_t page_count, char buf, size_t cap)
	Generate ComicInfo.xml including page count and direction semantics.
void	mdl_export_workspace_init (mdl_export_workspace_t ws, void data, size_t cap)
	Bind an exporter arena without allocating memory.
void *	mdl_export_workspace_take (mdl_export_workspace_t *ws, size_t bytes, size_t alignment)
	Reserve aligned bytes from an exporter arena.
ra8_err_t	mdl_export_chapter_meta_ws (mdl_storage_t storage, mdl_format_t fmt, const char chapter_dir, const char out_path, const mdl_export_meta_t meta, mdl_export_workspace_t *ws)
	Package a chapter with explicit metadata and caller-owned workspace.
ra8_err_t	mdl_export_chapter_ws (mdl_storage_t storage, mdl_format_t fmt, const char chapter_dir, const char out_path, mdl_export_workspace_t ws)
	Package a chapter after auto-loading bounded local metadata.

Detailed Description

Package a downloaded chapter folder into a reader-openable container.

The currently supported writers are CBZ (ZIP), CBT (tar), gzip-wrapped CBT, EPUB, the native JOF tile atlas, and chunked RABOOK. They use in-tree implementations and caller-owned bounded storage so the host tool exercises the same no-heap constraints as portable reader code. CBR and xz-wrapped CBT remain reserved.

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

Definition in file mdl_export.h.

Typedef Documentation

◆ mdl_export_workspace_t

typedef struct mdl_export_workspace mdl_export_workspace_t

Caller-owned bounded arena for all exporter scratch state.

Enumeration Type Documentation

◆ mdl_meta_size_t

enum mdl_meta_size_t : uint16_t

Sizing constants for metadata fields.

Enumerator
k_mdl_meta_title_max	Title (series or chapter) buffer max bytes.
k_mdl_meta_summary_max	Summary description buffer max bytes.
k_mdl_meta_name_max	Person name (writer/artist) buffer max bytes.
k_mdl_meta_url_max	Absolute source URL max bytes, including NUL.
k_mdl_meta_path_max	Bounded host cover path, including NUL.
k_mdl_meta_lang_max	BCP-47 language tag buffer max bytes.
k_mdl_meta_id_max	Stable publication identifier max bytes.
k_mdl_meta_date_max	ISO-8601 modified timestamp max bytes.

Definition at line 75 of file mdl_export.h.

◆ mdl_reading_direction_t

enum mdl_reading_direction_t : uint8_t

Logical page progression used by fixed-layout readers.

Enumerator
k_mdl_read_ltr	Left-to-right page progression.
k_mdl_read_rtl	Right-to-left page progression.

Definition at line 87 of file mdl_export.h.

Function Documentation

◆ mdl_export_build_comicinfo()

ra8_err_t mdl_export_build_comicinfo	(	const mdl_export_meta_t *	meta,
		char *	buf,
		size_t	cap )

Generate ComicInfo.xml content from metadata.

Escapes user text and delegates to the page-aware generator with a zero page count for callers that only need a metadata document.

Parameters

[in]	meta	Metadata struct (or NULL for default metadata).
[out]	buf	Output buffer for XML string.
[in]	cap	Capacity of `buf`.

Returns: k_ra8_ok on success, error code if buffer too small or NULL arg.

Return values

k_ra8_ok	A complete NUL-terminated XML document was written.
k_ra8_err_invalid_arg	`buf` is NULL or `cap` is zero.
k_ra8_err_invalid_size	Escaped metadata does not fit `buf`.

Precondition: meta is NULL or points to a fully initialized metadata object.; buf addresses cap writable bytes when non-NULL.

Postcondition: Success leaves a complete NUL-terminated ComicInfo document.; Failure never reports a truncated document as successful.

Note: Thread-safe across distinct input and output objects.

Since: 0.1.0

Definition at line 997 of file mdl_export_meta.c.

References mdl_export_build_comicinfo_pages().

◆ mdl_export_build_comicinfo_pages()

ra8_err_t mdl_export_build_comicinfo_pages	(	const mdl_export_meta_t *	meta,
		size_t	page_count,
		char *	buf,
		size_t	cap )

Generate ComicInfo.xml including page count and direction semantics.

Emits escaped metadata, deterministic defaults, page count, manga direction, and a FrontCover page declaration when its index is valid.

Parameters

[in]	meta	Metadata to encode, or NULL for defaults.
[in]	page_count	Logical image count in the target comic archive.
[out]	buf	Destination for the NUL-terminated XML document.
[in]	cap	Writable capacity of `buf` in bytes.

Returns: XML generation status.

Return values

k_ra8_ok	A complete document was generated.
k_ra8_err_invalid_arg	`buf` is NULL or `cap` is zero.
k_ra8_err_invalid_size	Escaped output exceeds `cap`.

Precondition: meta is NULL or points to initialized bounded strings.; buf addresses cap writable bytes when non-NULL.

Postcondition: Success writes one complete NUL-terminated document.; Failure is explicit and never treated as a valid truncated document.

Note: Thread-safe across distinct metadata and output buffers.

Since: 0.1.0

Definition at line 947 of file mdl_export_meta.c.

References mdl_export_meta_t::chapter_number, mdl_export_meta_t::cover_index, internal_escape_comicinfo(), internal_render_comicinfo(), k_mdl_meta_url_max, k_meta_fragment_slack, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_meta_init(), priv_mdl_export_snprintf_fit(), priv_mdl_export_validate_source_url(), mdl_comicinfo_text_t::source, and mdl_export_meta_t::source_url.

Referenced by internal_build_tar(), internal_cbz_add_metadata(), and mdl_export_build_comicinfo().

◆ mdl_export_chapter_meta_ws()

ra8_err_t mdl_export_chapter_meta_ws	(	mdl_storage_t *	storage,
		mdl_format_t	fmt,
		const char *	chapter_dir,
		const char *	out_path,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	ws )

Package a chapter with explicit metadata and caller-owned workspace.

Enumerates bounded page names, derives deterministic timestamps, validates any external cover, independently verifies a borrowed transaction stage, and publishes out_path only after the selected writer succeeds. JOF publishes one validated sibling per page and therefore reports partial progress on a later-page failure.

Parameters

[in,out]	storage	Injected portable storage used for image classification.
[in]	fmt	Target output format.
[in]	chapter_dir	Directory containing verified page images.
[in]	out_path	Container path, or chapter directory for JOF output.
[in]	meta	Metadata to embed, or NULL for deterministic defaults.
[in,out]	ws	Exclusive bounded exporter workspace.

Returns: Export status.

Return values

k_ra8_ok	All requested output was completed.
k_ra8_err_invalid_arg	A pointer, workspace, or format is invalid.
k_ra8_err_invalid_size	A bound or workspace capacity was exceeded.
k_ra8_err_empty	No qualifying page image exists.
k_ra8_err_validation_failed	An external cover is not a recognized image.
k_ra8_err_not_supported	The reserved writer is unavailable.
k_ra8_fail	File or container writing failed.

Precondition: storage is initialized, exclusive, and all paths are canonical beneath it.; String arguments are NUL-terminated and stable for the call.; ws owns writable storage and is not shared concurrently.

Postcondition: Success leaves a complete validated container or all requested JOF siblings.; A pre-publication container failure preserves the prior destination.; A JOF failure preserves the failed and later siblings while earlier successfully published pages remain visible.

Note: Power-loss durability depends on the selected storage adapter's capabilities.; Not thread-safe for the same workspace or output path.

Since: 0.1.0

Definition at line 532 of file mdl_export.c.

References mdl_export_workspace::data, mdl_export_workspace::high_water, internal_export_transaction(), internal_list_pages(), internal_resolve_export_metadata(), k_max_pages, k_mdl_format_cbr, k_mdl_format_cbt_xz, k_mdl_format_invalid, k_mdl_format_jof, k_mdl_format_loose, k_mdl_format_rabook, k_name_max, k_ra8_err_empty, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_supported, k_ra8_ok, mdl_export_workspace_take(), priv_mdl_export_jof(), priv_mdl_export_rabook(), and mdl_export_workspace::used.

Referenced by internal_pack_combined_dir(), internal_pack_combined_dir_output(), internal_pack_dir_output(), mdl_export_chapter_ws(), and mdl_pack_one_meta().

◆ mdl_export_chapter_ws()

ra8_err_t mdl_export_chapter_ws	(	mdl_storage_t *	storage,
		mdl_format_t	fmt,
		const char *	chapter_dir,
		const char *	out_path,
		mdl_export_workspace_t *	ws )

Package a chapter after auto-loading bounded local metadata.

Loads the supported metadata files from chapter_dir and delegates to mdl_export_chapter_meta_ws with the same publication guarantees.

Parameters

[in,out]	storage	Injected portable storage used for image classification.
[in]	fmt	Target output format.
[in]	chapter_dir	Directory containing pages and optional metadata.
[in]	out_path	Container path, or chapter directory for JOF output.
[in,out]	ws	Exclusive bounded exporter workspace.

Returns: Metadata-load or export status.

Return values

k_ra8_ok	Output was completed.
k_ra8_err_invalid_arg	A pointer, workspace, or format is invalid.
k_ra8_err_invalid_size	Metadata or exporter bounds were exceeded.
k_ra8_err_empty	No qualifying pages exist.
k_ra8_fail	File or container writing failed.

Precondition: storage is initialized, exclusive, and all paths are canonical beneath it.; String arguments are NUL-terminated and stable for the call.; ws owns writable storage and is not shared concurrently.

Postcondition: Success leaves complete output for the selected format.; Failure does not publish a partial container.

Note: Not thread-safe for the same workspace or output path.

Since: 0.1.0

Definition at line 592 of file mdl_export.c.

References mdl_export_chapter_meta_ws(), mdl_meta_init(), and mdl_meta_load_dir().

Referenced by internal_pack_directory_output(), and internal_pack_file_output().

◆ mdl_export_workspace_init()

void mdl_export_workspace_init	(	mdl_export_workspace_t *	ws,
		void *	data,
		size_t	cap )

Bind an exporter arena without allocating memory.

Initializes the caller-owned bump arena and clears usage counters; a NULL data pointer produces a zero-capacity workspace.

Parameters

[out]	ws	Workspace descriptor to initialize, or NULL for no operation.
[in,out]	data	Caller-owned writable arena bytes, or NULL.
[in]	cap	Number of bytes available at `data`.

Precondition: ws is NULL or points to writable descriptor storage.; Non-NULL data remains alive while the workspace is used.

Postcondition: A non-NULL workspace has zero used and high-water counters.; Capacity is cap only when data is non-NULL, otherwise zero.

Note: Thread-safe across distinct workspaces; one workspace is not shareable.

Since: 0.1.0

Definition at line 19 of file mdl_export_workspace.c.

References mdl_export_workspace::cap, mdl_export_workspace::data, mdl_export_workspace::high_water, and mdl_export_workspace::used.

Referenced by internal_main_init().

◆ mdl_export_workspace_take()

void * mdl_export_workspace_take	(	mdl_export_workspace_t *	ws,
		size_t	bytes,
		size_t	alignment )

Reserve aligned bytes from an exporter arena.

Advances the caller-owned bump cursor only after overflow and capacity checks and records the largest successfully used offset.

Parameters

[in,out]	ws	Initialized exporter workspace.
[in]	bytes	Nonzero number of bytes to reserve.
[in]	alignment	Nonzero power-of-two alignment.

Returns: Pointer to aligned caller-owned bytes, or NULL on invalid input/exhaustion.

Return values

non-NULL	A complete aligned reservation was made.
NULL	Arguments were invalid or bounded capacity was exhausted.

Precondition: ws is non-NULL and was initialized by mdl_export_workspace_init.; alignment is a power of two.

Postcondition: Success advances used and may increase high_water.; Failure leaves all workspace counters unchanged.

Note: Thread-safe across distinct workspaces; one workspace is exclusive.

Since: 0.1.0

Definition at line 30 of file mdl_export_workspace.c.

References mdl_export_workspace::cap, mdl_export_workspace::data, mdl_export_workspace::high_water, memcpy(), and mdl_export_workspace::used.

Referenced by internal_allocate_builder(), internal_allocate_container(), internal_allocate_pipeline(), internal_epub_carve_workspace(), internal_jof_carve_webp(), internal_jof_load_source(), internal_jof_produce_page(), internal_list_pages_open_dir(), internal_zip_workspace_alloc(), mdl_export_chapter_meta_ws(), priv_mdl_export_tar_gzip(), and priv_mdl_verify_rabook().

◆ mdl_format_ext()

const char * mdl_format_ext ( mdl_format_t fmt )

File extension (without dot) for a format, e.g.

"cbz" / "cbt.xz".

Definition at line 58 of file mdl_export.c.

References k_mdl_format_cbr, k_mdl_format_cbt, k_mdl_format_cbt_gz, k_mdl_format_cbt_xz, k_mdl_format_cbz, k_mdl_format_epub, k_mdl_format_invalid, k_mdl_format_jof, k_mdl_format_loose, and k_mdl_format_rabook.

Referenced by internal_pack_combined_dir(), mdl_app_run_pack(), and mdl_pack_one_meta().

◆ mdl_format_from_str()

mdl_format_t mdl_format_from_str ( const char * s )

Map a --format string to a container kind.

Recognizes only formats the CLI may currently emit; NULL and the explicit loose token select loose pages, while reserved formats remain invalid until their writer and validator are available.

Parameters

[in] s Format name, or NULL (treated as "loose").

Returns: The matching kind, or k_mdl_format_invalid.

Return values

k_mdl_format_loose	`s` is NULL or names loose output.
k_mdl_format_rabook	`s` names the strict reader-native container.
k_mdl_format_invalid	`s` is an unknown or reserved format name.

Precondition: s is NULL or points to a NUL-terminated string.; The caller treats format names as case-sensitive CLI tokens.

Postcondition: No caller-owned memory is modified.; The return value is always a member of mdl_format_t.

Note: Thread-safe: this is a pure string classifier.

Since: 0.1.0

Definition at line 32 of file mdl_export.c.

References k_mdl_format_cbt, k_mdl_format_cbt_gz, k_mdl_format_cbz, k_mdl_format_epub, k_mdl_format_invalid, k_mdl_format_jof, k_mdl_format_loose, k_mdl_format_rabook, and strcmp().

Referenced by internal_prepare_run_policy().

◆ mdl_format_is_dir_output()

bool mdl_format_is_dir_output ( mdl_format_t fmt )

Whether fmt writes per-page sibling files rather than one container.

JOF is inherently per-page: ::mdl_export_chapter writes one .jof band atlas beside each source image inside the chapter directory, so a JOF "chapter" is a directory of atlases, not a single archive at out_path. Every other archive format produces exactly one file at out_path. Callers use this to report what was actually written – a success message must never name a container file that a directory-output format did not create.

Parameters

[in] fmt Format to classify.

Returns: Whether fmt produces per-page sibling files in the chapter dir.

Return values

true	`fmt` is k_mdl_format_jof (per-page .jof siblings).
false	`fmt` produces a single container file at out_path.

Precondition: fmt is a value of mdl_format_t.; The caller distinguishes directory output from writer availability.

Postcondition: No state is mutated (pure classifier).; Repeated calls with the same value return the same result.

Note: Thread-safe: pure function of its argument.

See also: mdl_export_chapter_ws()

Since: 0.1.0

Definition at line 84 of file mdl_export.c.

References k_mdl_format_jof.

Referenced by internal_pack_combined_dir(), mdl_app_run_pack(), and mdl_pack_one_meta().

◆ mdl_meta_init()

void mdl_meta_init ( mdl_export_meta_t * meta )

Initialise a metadata struct to empty/default values.

Clears all textual fields, selects English left-to-right defaults, and marks the cover index as unset for deterministic later export.

Parameters

[out] meta Struct to clear (never NULL).

Precondition: meta points to writable storage for one mdl_export_meta_t.; No other thread accesses meta during initialization.

Postcondition: Every string field is NUL-terminated and initially empty except language.; Language is en, direction is LTR, and cover index is negative.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 95 of file mdl_export_meta.c.

References mdl_export_meta_t::cover_index, k_mdl_read_ltr, mdl_export_meta_t::language, memset(), mdl_export_meta_t::modified, and mdl_export_meta_t::reading_direction.

Referenced by internal_build_export_metadata(), internal_generate_uuid(), internal_resolve_export_metadata(), mdl_export_build_comicinfo_pages(), mdl_export_chapter_ws(), mdl_meta_load_dir(), and priv_mdl_epub_add_meta().

◆ mdl_meta_load_dir()

ra8_err_t mdl_meta_load_dir	(	mdl_storage_t *	storage,
		mdl_export_meta_t *	meta,
		const char *	dir )

Load metadata from a directory by looking for metadata files.

Initializes meta, then merges bounded recognized metadata files in deterministic candidate order and propagates parse overflow or semantic errors rather than accepting a truncated value.

Parameters

[in,out]	storage	Injected portable file reader.
[out]	meta	Metadata struct to fill.
[in]	dir	Directory path to inspect.

Returns: k_ra8_ok on success, error code on invalid arg.

Return values

k_ra8_ok	No file existed or all discovered files parsed successfully.
k_ra8_err_invalid_arg	A pointer or discovered semantic value is invalid.
k_ra8_err_invalid_size	A discovered field exceeds its fixed bound.

Precondition: dir is NUL-terminated when non-NULL.; meta points to writable exclusive storage.

Postcondition: meta contains defaults plus all successfully parsed fields.; A parse failure is reported instead of silently truncating metadata.

Note: Thread-safe across distinct metadata objects and stable directories.

Since: 0.1.0

Definition at line 816 of file mdl_export_meta.c.

References mdl_storage_t::fs, internal_meta_load_candidate(), k_ra8_err_invalid_arg, k_ra8_ok, and mdl_meta_init().

Referenced by internal_pack_metadata(), and mdl_export_chapter_ws().

◆ mdl_meta_parse()

ra8_err_t mdl_meta_parse	(	mdl_export_meta_t *	meta,
		const char *	text )

Parse metadata key-value lines or XML text into a metadata struct.

Accepts the documented aliases and ComicInfo fields, trims text, rejects malformed numeric/direction values, and refuses any field that would exceed its fixed destination instead of truncating it.

Parameters

[in,out]	meta	Metadata struct to populate.
[in]	text	Key-value string or XML document.

Returns: k_ra8_ok on success, k_ra8_err_invalid_arg if meta or text is NULL.

Return values

k_ra8_ok	Recognized fields were applied without truncation.
k_ra8_err_invalid_arg	A pointer or semantic field is invalid.
k_ra8_err_invalid_size	An input line or field exceeds a fixed bound.

Precondition: text is NUL-terminated when non-NULL.; meta is initialized and exclusively owned during the call.

Postcondition: On success all populated strings remain NUL-terminated.; On failure no out-of-bounds write or silent truncation occurs.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 684 of file mdl_export_meta.c.

References internal_parse_kv_line(), internal_parse_xml(), k_mdl_meta_path_max, k_meta_line_slack, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, memcpy(), strchr(), strlen(), and strstr().

Referenced by internal_meta_load_candidate().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ mdl_export_workspace_t

Enumeration Type Documentation

◆ mdl_meta_size_t

◆ mdl_reading_direction_t

Function Documentation

◆ mdl_export_build_comicinfo()

◆ mdl_export_build_comicinfo_pages()

◆ mdl_export_chapter_meta_ws()

◆ mdl_export_chapter_ws()

◆ mdl_export_workspace_init()

◆ mdl_export_workspace_take()

◆ mdl_format_ext()

◆ mdl_format_from_str()

◆ mdl_format_is_dir_output()

◆ mdl_meta_init()

◆ mdl_meta_load_dir()

◆ mdl_meta_parse()