Parse, validate, and serialize portable publication metadata. More...

#include <ctype.h>
#include <errno.h>
#include <limits.h>
#include <math.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "mdl_export.h"
#include "mdl_export_internal.h"
#include "mdl_sanitize.h"
#include "mdl_url_guard.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_export_meta.c:

Data Structures
struct	mdl_meta_xml_field_t
	Destination descriptor for a simple metadata XML element. More...
struct	mdl_comicinfo_text_t
	Escaped text storage used while rendering ComicInfo. More...

Enumerations
enum	mdl_meta_text_bounds_t : uint16_t { k_decimal_radix = 10U , k_xml_amp_entity_len = 5U , k_meta_line_slack = 128U , k_meta_fragment_slack = 64U }
	Radices and bounded metadata text expansion sizes. More...

Functions
ra8_err_t	priv_mdl_export_validate_source_url (const char *url)
	Validate an optional bounded source-attribution URL.
bool	priv_mdl_export_snprintf_fit (int written, size_t cap)
	Test whether an snprintf result fully fit its buffer.
void	mdl_meta_init (mdl_export_meta_t *meta)
	Initialise a metadata struct to empty/default values.
static bool	internal_str_copy_trimmed (char dst, size_t cap, const char src)
	Copy trimmed text without truncating fixed metadata storage.
static bool	internal_parse_double_strict (const char text, double out)
	Parse one finite nonnegative decimal value strictly.
static bool	internal_parse_int_strict (const char text, int out)
	Parse one bounded decimal cover index strictly.
static bool	internal_xml_unescape (const char raw, char out, size_t cap)
	Decode the five XML entities accepted by metadata input.
static bool	internal_parse_xml_tag (const char xml, const char tag, char *out, size_t cap)
	Extract and unescape one bounded simple XML element.
static ra8_err_t	internal_parse_xml_field (const char text, const mdl_meta_xml_field_t field)
	Copy one optional XML field into fixed metadata storage.
static ra8_err_t	internal_parse_xml_semantics (mdl_export_meta_t meta, const char text)
	Apply XML fields that require semantic validation.
static ra8_err_t	internal_parse_xml (mdl_export_meta_t meta, const char text)
	Parse ComicInfo-style XML into bounded metadata.
static bool	internal_key_is (const char key, const char a, const char b, const char c, const char d, const char e)
	Compare one normalized metadata key with up to five aliases.
static bool	internal_find_descriptive_key (mdl_export_meta_t meta, const char key, char *dst, size_t cap)
	Resolve title and descriptive text aliases.
static bool	internal_find_publication_key (mdl_export_meta_t meta, const char key, char *dst, size_t cap)
	Resolve attribution and publication text aliases.
static ra8_err_t	internal_apply_text_key (mdl_export_meta_t meta, const char key, const char *value)
	Apply one text-valued metadata key.
static ra8_err_t	internal_apply_semantic_key (mdl_export_meta_t meta, const char key, const char *value)
	Apply one semantic metadata key.
static ra8_err_t	internal_parse_kv_line (mdl_export_meta_t meta, char line)
	Parse and apply one metadata descriptor line.
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.
static ra8_err_t	internal_meta_candidate_path (const char directory, const char candidate, bool parent, char *out, size_t capacity)
	Compose one metadata candidate without a traversal component.
static ra8_err_t	internal_meta_load_candidate (mdl_storage_t storage, const char dir, const char candidate, bool is_fallback, mdl_export_meta_t meta)
	Load and parse one metadata candidate file, if present.
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.
static ra8_err_t	internal_escape_comicinfo (const mdl_export_meta_t meta, mdl_comicinfo_text_t escaped)
	Escape metadata fields with the original fallback policy.
static ra8_err_t	internal_render_comicinfo (const mdl_export_meta_t meta, const mdl_comicinfo_text_t escaped, size_t page_count, const char web, const char number, const char pages, char buf, size_t cap)
	Render already-escaped ComicInfo fields into caller storage.
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.
ra8_err_t	mdl_export_build_comicinfo (const mdl_export_meta_t meta, char buf, size_t cap)
	Generate ComicInfo.xml content from metadata.

Detailed Description

Parse, validate, and serialize portable publication metadata.

Owns bounded key-value and ComicInfo parsing plus deterministic ComicInfo generation. It performs no archive-format selection.

[Ring 4 / Domain] {World: NS}

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

Definition in file mdl_export_meta.c.

Enumeration Type Documentation

◆ mdl_meta_text_bounds_t

enum mdl_meta_text_bounds_t : uint16_t

Radices and bounded metadata text expansion sizes.

Enumerator
k_decimal_radix	Decimal integer parsing radix.
k_xml_amp_entity_len	Bytes in the XML entity "&".
k_meta_line_slack	Key/delimiter space beyond a path.
k_meta_fragment_slack	Fixed bytes around an XML fragment.

Definition at line 29 of file mdl_export_meta.c.

Function Documentation

◆ internal_apply_semantic_key()

ra8_err_t internal_apply_semantic_key	(	mdl_export_meta_t *	meta,
		const char *	key,
		const char *	value )

static

Apply one semantic metadata key.

Handles URL, chapter number, cover index, and reading direction.

Parameters

[in,out]	meta	Metadata destination.
[in]	key	Normalized key.
[in]	value	Raw value.

Returns: Semantic-field application status.

Return values

k_ra8_ok	The key was unknown or its value was accepted.
k_ra8_err_invalid_size	Temporary or destination storage overflowed.
k_ra8_err_invalid_arg	A semantic value was malformed.

Precondition: All pointers are non-NULL and strings are NUL-terminated.; meta is exclusively owned.

Postcondition: Recognized fields are updated only from complete values.; Invalid source URLs are cleared.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 593 of file mdl_export_meta.c.

References mdl_export_meta_t::chapter_number, mdl_export_meta_t::cover_index, internal_key_is(), internal_parse_double_strict(), internal_parse_int_strict(), internal_str_copy_trimmed(), k_mdl_read_ltr, k_mdl_read_rtl, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, priv_mdl_export_validate_source_url(), mdl_export_meta_t::reading_direction, mdl_export_meta_t::source_url, and strcmp().

Referenced by internal_parse_kv_line().

◆ internal_apply_text_key()

ra8_err_t internal_apply_text_key	(	mdl_export_meta_t *	meta,
		const char *	key,
		const char *	value )

static

Apply one text-valued metadata key.

Resolves aliases to one bounded destination and leaves unknown keys distinguishable for numeric handling.

Parameters

[in,out]	meta	Metadata destination.
[in]	key	Normalized key.
[in]	value	Raw value.

Returns: Text-field application status.

Return values

k_ra8_ok	A recognized text field was copied.
k_ra8_err_not_found	The key is not a text field.
k_ra8_err_invalid_size	The value did not fit.

Precondition: All pointers are non-NULL and strings are NUL-terminated.; meta is exclusively owned.

Postcondition: Recognized values are trimmed and NUL-terminated.; Unknown keys leave metadata unchanged.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 564 of file mdl_export_meta.c.

References internal_find_descriptive_key(), internal_find_publication_key(), internal_str_copy_trimmed(), k_ra8_err_invalid_size, k_ra8_err_not_found, and k_ra8_ok.

Referenced by internal_parse_kv_line().

◆ internal_escape_comicinfo()

ra8_err_t internal_escape_comicinfo	(	const mdl_export_meta_t *	meta,
		mdl_comicinfo_text_t *	escaped )

static

Escape metadata fields with the original fallback policy.

Builds escape comicinfo within caller-owned bounded workspace and reports capacity, encoding, or I/O failure without transferring workspace ownership.

Parameters

[in]	meta	Metadata record to read or update.
[in,out]	escaped	Caller-owned escaped metadata fields to populate.

Returns: Canonical downloader status.

Return values

k_ra8_ok	The operation completed.
other	Validation, capacity, network, or storage failed.

Precondition: Required pointer arguments remain valid for the call duration.; Supplied capacities cover their referenced bounded buffers.

Postcondition: No ownership of caller-provided storage is transferred.; Result status and outputs describe one completed synchronous attempt.

Note: The function performs no dynamic allocation and retains no caller pointer.

Since: 0.1.0

Definition at line 865 of file mdl_export_meta.c.

References mdl_comicinfo_text_t::artist, mdl_export_meta_t::artist, mdl_export_meta_t::chapter_title, k_ra8_err_invalid_size, k_ra8_ok, mdl_comicinfo_text_t::language, mdl_export_meta_t::language, mdl_xml_escape(), RA8_INTERNAL, mdl_comicinfo_text_t::series, mdl_export_meta_t::series_title, mdl_comicinfo_text_t::source, mdl_export_meta_t::source_url, mdl_comicinfo_text_t::summary, mdl_export_meta_t::summary, mdl_comicinfo_text_t::title, mdl_comicinfo_text_t::writer, and mdl_export_meta_t::writer.

Referenced by mdl_export_build_comicinfo_pages().

◆ internal_find_descriptive_key()

bool internal_find_descriptive_key	(	mdl_export_meta_t *	meta,
		const char *	key,
		char **	dst,
		size_t *	cap )

static

Resolve title and descriptive text aliases.

Maps the supported title, series, and descriptive aliases.

Parameters

[in,out]	meta	Metadata destination.
[in]	key	Normalized key.
[out]	dst	Receives the selected metadata text buffer.
[out]	cap	Receives the selected buffer capacity in bytes.

Returns: Whether key names a supported descriptive field.

Return values

true	`dst` and `cap` identify the selected field.
false	`key` is not a descriptive alias.

Precondition: All pointers are non-NULL and strings are NUL-terminated.; meta is exclusively owned.

Postcondition: Recognized keys initialize both dst and cap.; Unknown keys leave metadata unchanged.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 474 of file mdl_export_meta.c.

References mdl_export_meta_t::chapter_title, internal_key_is(), mdl_export_meta_t::series_title, and mdl_export_meta_t::summary.

Referenced by internal_apply_text_key().

◆ internal_find_publication_key()

bool internal_find_publication_key	(	mdl_export_meta_t *	meta,
		const char *	key,
		char **	dst,
		size_t *	cap )

static

Resolve attribution and publication text aliases.

Maps supported creator, cover, language, identity, and date aliases.

Parameters

[in,out]	meta	Metadata destination owning the returned storage.
[in]	key	Normalized key.
[out]	dst	Resolved destination pointer.
[out]	cap	Resolved destination capacity.

Returns: Whether the key names a supported text destination.

Return values

true	Output parameters identify one metadata field.
false	The key is not handled by this resolver.

Precondition: All pointers are non-NULL.; key is NUL-terminated.

Postcondition: Success initializes both output parameters.; Failure leaves output parameters unchanged.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 514 of file mdl_export_meta.c.

References mdl_export_meta_t::artist, mdl_export_meta_t::cover_path, mdl_export_meta_t::identifier, internal_key_is(), mdl_export_meta_t::language, mdl_export_meta_t::modified, and mdl_export_meta_t::writer.

Referenced by internal_apply_text_key().

◆ internal_key_is()

bool internal_key_is	(	const char *	key,
		const char *	a,
		const char *	b,
		const char *	c,
		const char *	d,
		const char *	e )

static

Compare one normalized metadata key with up to five aliases.

NULL aliases are ignored.

Parameters

[in]	key	Normalized key.
[in]	a	First alias.
[in]	b	Second alias, or NULL.
[in]	c	Third alias, or NULL.
[in]	d	Fourth alias, or NULL.
[in]	e	Fifth alias, or NULL.

Returns: Whether any supplied alias matches.

Return values

true	One alias matched exactly.
false	No alias matched.

Precondition: key and a are non-NULL.; Every non-NULL alias is NUL-terminated.

Postcondition: Inputs are unchanged.; Matching is case-sensitive after normalization.

Note: Thread-safe and side-effect free.

Since: 0.1.0

Definition at line 444 of file mdl_export_meta.c.

References RA8_INTERNAL, and strcmp().

Referenced by internal_apply_semantic_key(), internal_find_descriptive_key(), and internal_find_publication_key().

◆ internal_meta_candidate_path()

ra8_err_t internal_meta_candidate_path	(	const char *	directory,
		const char *	candidate,
		bool	parent,
		char *	out,
		size_t	capacity )

static

Compose one metadata candidate without a traversal component.

Resolves the fixed candidate relative to the canonical chapter or its parent without emitting a traversal segment.

Parameters

[in]	directory	Canonical chapter directory.
[in]	candidate	Candidate leaf.
[in]	parent	Whether the candidate belongs in the parent directory.
[out]	out	Composed canonical path.
[in]	capacity	Destination capacity.

Returns: Canonical path construction status.

Return values

k_ra8_ok	The complete candidate path fits.
k_ra8_err_invalid_size	The bounded destination is insufficient.

Precondition: Inputs are non-null and NUL-terminated.; out is writable for capacity bytes.

Postcondition: Success never emits . or .. components.; Failure never claims a truncated candidate as valid.

Note: Thread-safe across distinct output buffers.

Since: 0.1.0

Definition at line 734 of file mdl_export_meta.c.

References k_fw_fs_path_cap, k_ra8_err_invalid_arg, memcpy(), priv_mdl_export_path_join(), RA8_INTERNAL, and strnlen().

Referenced by internal_meta_load_candidate().

◆ internal_meta_load_candidate()

ra8_err_t internal_meta_load_candidate	(	mdl_storage_t *	storage,
		const char *	dir,
		const char *	candidate,
		bool	is_fallback,
		mdl_export_meta_t *	meta )

static

Load and parse one metadata candidate file, if present.

Resolves the candidate path, stats it, and – when it exists as a regular nonempty file – slurps and parses it into meta.

Parameters

[in,out]	storage	Portable namespace binding.
[in]	dir	Canonical chapter directory.
[in]	candidate	Candidate file basename.
[in]	is_fallback	Whether `candidate` is the final fallback name.
[in,out]	meta	Accumulated metadata being filled in.

Returns: Candidate status.

Return values

k_ra8_ok	The candidate was absent, empty, or parsed successfully.
other	Path resolution, stat, read, or parse failed.

Precondition: storage and meta are non-NULL.; dir and candidate resolve under storage.

Postcondition: On success meta reflects the parsed candidate, if any was found.; No file under dir is created, modified, or removed.

Note: Not thread-safe with respect to concurrent mutation of storage.

Since: 0.1.0

Definition at line 778 of file mdl_export_meta.c.

References fw_fs_stat_t::exists, mdl_storage_t::fs, fw_fs_stat(), internal_meta_candidate_path(), k_fw_fs_node_file, k_fw_fs_path_cap, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_meta_parse(), fw_fs_t::names, priv_mdl_export_source_slurp(), RA8_INTERNAL, fw_fs_stat_t::size_bytes, and fw_fs_stat_t::type.

Referenced by mdl_meta_load_dir().

◆ internal_parse_double_strict()

bool internal_parse_double_strict	(	const char *	text,
		double *	out )

static

Parse one finite nonnegative decimal value strictly.

Requires the entire trimmed string to parse without range errors.

Parameters

[in]	text	NUL-terminated numeric text.
[out]	out	Parsed value on success.

Returns: Whether a valid value was parsed.

Return values

true	The complete input represents a finite nonnegative double.
false	Input is empty, malformed, negative, nonfinite, or out of range.

Precondition: text and out are non-NULL.; text is NUL-terminated.

Postcondition: Success stores the parsed value in out.; Input text is unchanged.

Note: Thread-safe subject to the C library strtod implementation.

Since: 0.1.0

Definition at line 157 of file mdl_export_meta.c.

References RA8_INTERNAL.

Referenced by internal_apply_semantic_key(), and internal_parse_xml_semantics().

◆ internal_parse_int_strict()

bool internal_parse_int_strict	(	const char *	text,
		int *	out )

static

Parse one bounded decimal cover index strictly.

Accepts minus one as the unset sentinel through INT_MAX and rejects trailing junk.

Parameters

[in]	text	NUL-terminated numeric text.
[out]	out	Parsed integer on success.

Returns: Whether a valid bounded index was parsed.

Return values

true	The complete input lies in the accepted range.
false	Input is malformed, below minus one, or above INT_MAX.

Precondition: text and out are non-NULL.; text is NUL-terminated.

Postcondition: Success stores the parsed integer in out.; Input text is unchanged.

Note: Thread-safe subject to the C library strtol implementation.

Since: 0.1.0

Definition at line 189 of file mdl_export_meta.c.

References k_decimal_radix, and RA8_INTERNAL.

Referenced by internal_apply_semantic_key().

◆ internal_parse_kv_line()

ra8_err_t internal_parse_kv_line	(	mdl_export_meta_t *	meta,
		char *	line )

static

Parse and apply one metadata descriptor line.

Ignores comments, blanks, malformed separators, and unknown keys.

Parameters

[in,out]	meta	Metadata destination.
[in,out]	line	Writable NUL-terminated line.

Returns: Line application status.

Return values

k_ra8_ok	The line was ignored or applied.
k_ra8_err_invalid_size	A key or value exceeded a bound.
k_ra8_err_invalid_arg	A semantic value was malformed.

Precondition: Both pointers are non-NULL and line is writable.; meta is exclusively owned.

Postcondition: Recognized keys update exactly one field.; Unknown keys leave metadata unchanged.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 655 of file mdl_export_meta.c.

References internal_apply_semantic_key(), internal_apply_text_key(), internal_str_copy_trimmed(), k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_ok, RA8_INTERNAL, and strchr().

Referenced by mdl_meta_parse().

◆ internal_parse_xml()

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

static

Parse ComicInfo-style XML into bounded metadata.

Applies simple text fields through a table, then validates URL, number, and reading-direction fields with their semantic parsers.

Parameters

[in,out]	meta	Metadata destination.
[in]	text	XML document.

Returns: Metadata parsing status.

Return values

k_ra8_ok	Every present supported field was accepted.
k_ra8_err_invalid_size	A bounded field overflowed.
k_ra8_err_invalid_arg	A URL or number was invalid.

Precondition: Both pointers are non-NULL and text is NUL-terminated.; meta is exclusively owned.

Postcondition: Success applies every recognized field.; Source URL validation failure clears that field.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 407 of file mdl_export_meta.c.

References mdl_export_meta_t::artist, mdl_export_meta_t::chapter_title, mdl_export_meta_t::cover_path, internal_parse_xml_field(), internal_parse_xml_semantics(), k_ra8_ok, mdl_export_meta_t::language, RA8_INTERNAL, mdl_export_meta_t::series_title, mdl_export_meta_t::summary, and mdl_export_meta_t::writer.

Referenced by mdl_meta_parse().

◆ internal_parse_xml_field()

ra8_err_t internal_parse_xml_field	(	const char *	text,
		const mdl_meta_xml_field_t *	field )

static

Copy one optional XML field into fixed metadata storage.

Treats an absent or empty element as no update.

Parameters

[in]	text	XML document.
[in]	field	Destination descriptor.

Returns: Field parsing status.

Return values

k_ra8_ok	The field was absent, empty, or copied completely.
k_ra8_err_invalid_size	Raw, decoded, or trimmed text did not fit.

Precondition: text and field are non-NULL.; Descriptor members name live storage.

Postcondition: Success leaves the destination NUL-terminated.; Failure is reported without a truncated destination.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 324 of file mdl_export_meta.c.

References mdl_meta_xml_field_t::cap, mdl_meta_xml_field_t::dst, internal_parse_xml_tag(), internal_str_copy_trimmed(), k_mdl_meta_path_max, k_ra8_err_invalid_size, k_ra8_ok, RA8_INTERNAL, and mdl_meta_xml_field_t::tag.

Referenced by internal_parse_xml().

◆ internal_parse_xml_semantics()

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

static

Apply XML fields that require semantic validation.

Validates the source URL and parses number and reading direction.

Parameters

[in,out]	meta	Metadata destination.
[in]	text	XML document.

Returns: Metadata parsing status.

Return values

k_ra8_ok	Every present supported field was accepted.
k_ra8_err_invalid_size	A bounded field overflowed.
k_ra8_err_invalid_arg	A URL or number was invalid.

Precondition: Both pointers are non-NULL and text is NUL-terminated.; meta is exclusively owned.

Postcondition: Success applies every recognized field.; Source URL validation failure clears that field.

Note: Thread-safe across distinct metadata objects.

Since: 0.1.0

Definition at line 353 of file mdl_export_meta.c.

References mdl_export_meta_t::chapter_number, internal_parse_double_strict(), internal_parse_xml_tag(), internal_str_copy_trimmed(), k_mdl_meta_path_max, k_mdl_read_ltr, k_mdl_read_rtl, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, priv_mdl_export_validate_source_url(), RA8_INTERNAL, mdl_export_meta_t::reading_direction, mdl_export_meta_t::source_url, and strcmp().

Referenced by internal_parse_xml().

◆ internal_parse_xml_tag()

bool internal_parse_xml_tag	(	const char *	xml,
		const char *	tag,
		char *	out,
		size_t	cap )

static

Extract and unescape one bounded simple XML element.

Locates plain or attributed opening tags and decodes their body.

Parameters

[in]	xml	NUL-terminated XML document.
[in]	tag	NUL-terminated element name.
[out]	out	Destination text buffer.
[in]	cap	Writable destination capacity.

Returns: Whether extraction completed without overflow.

Return values

true	The tag was absent or its value fit.
false	Raw or decoded text exceeded a bound.

Precondition: All pointers are non-NULL and inputs are NUL-terminated.; out addresses cap writable bytes.

Postcondition: Accepted text is NUL-terminated.; Overflow remains visible.

Note: Thread-safe across distinct buffers.

Since: 0.1.0

Definition at line 273 of file mdl_export_meta.c.

References internal_xml_unescape(), k_mdl_meta_path_max, memcpy(), strchr(), strlen(), and strstr().

Referenced by internal_parse_xml_field(), and internal_parse_xml_semantics().

◆ internal_render_comicinfo()

ra8_err_t internal_render_comicinfo	(	const mdl_export_meta_t *	meta,
		const mdl_comicinfo_text_t *	escaped,
		size_t	page_count,
		const char *	web,
		const char *	number,
		const char *	pages,
		char *	buf,
		size_t	cap )

static

Render already-escaped ComicInfo fields into caller storage.

Builds render comicinfo within caller-owned bounded workspace and reports capacity, encoding, or I/O failure without transferring workspace ownership.

Parameters

[in]	meta	Metadata record to read or update.
[in]	escaped	Validated escaped metadata fields to render.
[in]	page_count	Number of pages represented in the archive.
[in]	web	Web-reader metadata value.
[in]	number	Chapter-number metadata value.
[in]	pages	Optional caller page metadata.
[out]	buf	Caller-provided bounded buffer.
[in]	cap	Capacity of the associated output buffer in bytes.

Returns: Canonical downloader status.

Return values

k_ra8_ok	The operation completed.
other	Validation, capacity, network, or storage failed.

Precondition: Required pointer arguments remain valid for the call duration.; Supplied capacities cover their referenced bounded buffers.

Postcondition: No ownership of caller-provided storage is transferred.; Result status and outputs describe one completed synchronous attempt.

Note: The function performs no dynamic allocation and retains no caller pointer.

Since: 0.1.0

Definition at line 913 of file mdl_export_meta.c.

References mdl_comicinfo_text_t::artist, k_mdl_read_rtl, k_ra8_err_invalid_size, k_ra8_ok, mdl_comicinfo_text_t::language, priv_mdl_export_snprintf_fit(), RA8_INTERNAL, mdl_export_meta_t::reading_direction, mdl_comicinfo_text_t::series, mdl_comicinfo_text_t::summary, mdl_comicinfo_text_t::title, and mdl_comicinfo_text_t::writer.

Referenced by mdl_export_build_comicinfo_pages().

◆ internal_str_copy_trimmed()

bool internal_str_copy_trimmed	(	char *	dst,
		size_t	cap,
		const char *	src )

static

Copy trimmed text without truncating fixed metadata storage.

Removes leading/trailing whitespace and fails if the complete text plus NUL cannot fit, leaving the destination unchanged on overflow.

Parameters

[out]	dst	Destination string buffer.
[in]	cap	Writable capacity of `dst`.
[in]	src	NUL-terminated source text.

Returns: Whether the complete trimmed text fit.

Return values

true	`dst` received a NUL-terminated copy.
false	Capacity is zero or the value is too long.

Precondition: dst and src are non-NULL and do not overlap.; src is NUL-terminated.

Postcondition: Success writes exactly the trimmed text.; Failure performs no partial copy.

Note: Thread-safe across distinct buffers.

Since: 0.1.0

Definition at line 124 of file mdl_export_meta.c.

References memcpy(), RA8_INTERNAL, and strlen().

Referenced by internal_apply_semantic_key(), internal_apply_text_key(), internal_parse_kv_line(), internal_parse_xml_field(), and internal_parse_xml_semantics().

◆ internal_xml_unescape()

bool internal_xml_unescape	(	const char *	raw,
		char *	out,
		size_t	cap )

static

Decode the five XML entities accepted by metadata input.

Copies one bounded raw element body and reports truncation.

Parameters

[in]	raw	NUL-terminated raw element body.
[out]	out	Destination text buffer.
[in]	cap	Writable destination capacity.

Returns: Whether the entire decoded value fit.

Return values

true	The decoded value is complete.
false	The destination was exhausted.

Precondition: All pointers are non-NULL and cap is nonzero.; raw is NUL-terminated.

Postcondition: out is NUL-terminated.; Failure never writes beyond cap.

Note: Thread-safe across distinct buffers.

Since: 0.1.0

Definition at line 221 of file mdl_export_meta.c.

References k_xml_amp_entity_len, RA8_INTERNAL, strlen(), and strncmp().

Referenced by internal_parse_xml_tag().

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

◆ priv_mdl_export_snprintf_fit()

bool priv_mdl_export_snprintf_fit	(	int	written,
		size_t	cap )

Test whether an snprintf result fully fit its buffer.

Report whether an snprintf result fit its destination.

Rejects encoding errors and results equal to capacity because the terminating NUL would not fit.

Parameters

[in]	written	Return value produced by snprintf.
[in]	cap	Destination capacity passed to snprintf.

Returns: Whether formatting completed without truncation.

Return values

true	`written` is nonnegative and below `cap`.
false	Formatting failed or truncated.

Precondition: cap matches the formatted destination.; written is the unmodified snprintf result.

Postcondition: No state is modified.; A true result permits safe use of the destination string.

Note: Thread-safe: this is a pure predicate.

Since: 0.1.0

Definition at line 90 of file mdl_export_meta.c.

References RA8_PRIV.

Referenced by internal_epub_add_external_cover(), internal_epub_add_page(), internal_epub_append_frags(), internal_epub_prepare_optional(), internal_epub_render_meta(), internal_epub_write_page_xhtml(), internal_render_comicinfo(), mdl_export_build_comicinfo_pages(), priv_mdl_export_jof(), and priv_mdl_export_prepare_cover().

◆ priv_mdl_export_validate_source_url()

ra8_err_t priv_mdl_export_validate_source_url ( const char * url )

Validate an optional bounded source-attribution URL.

Requires complete NUL termination, an HTTP(S) scheme, a nonempty authority, and no whitespace/control bytes while permitting XML metacharacters that the container emitters escape later.

Parameters

[in] url Fixed-capacity source URL field.

Returns: Source field validation status.

Return values

k_ra8_ok	The field is empty or a valid absolute HTTP(S) URL.
k_ra8_err_invalid_size	The fixed field lacks a terminating NUL.
k_ra8_err_invalid_arg	The nonempty URL has an invalid scheme, authority, whitespace, or control byte.

Precondition: url points to at least k_mdl_meta_url_max readable bytes.; The caller treats every non-ok result as a hard metadata failure.

Postcondition: url is not modified.; No allocation, network access, or filesystem access occurs.

Note: Thread-safe and allocation-free.

Since: 0.1.0

Definition at line 54 of file mdl_export_meta.c.

References k_mdl_meta_url_max, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_url_host(), mdl_url_scheme_allowed(), RA8_PRIV, and strnlen().

Referenced by internal_apply_semantic_key(), internal_parse_xml_semantics(), internal_resolve_export_metadata(), mdl_export_build_comicinfo_pages(), and priv_mdl_epub_add_meta().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_meta_text_bounds_t

Function Documentation

◆ internal_apply_semantic_key()

◆ internal_apply_text_key()

◆ internal_escape_comicinfo()

◆ internal_find_descriptive_key()

◆ internal_find_publication_key()

◆ internal_key_is()

◆ internal_meta_candidate_path()

◆ internal_meta_load_candidate()

◆ internal_parse_double_strict()

◆ internal_parse_int_strict()

◆ internal_parse_kv_line()

◆ internal_parse_xml()

◆ internal_parse_xml_field()

◆ internal_parse_xml_semantics()

◆ internal_parse_xml_tag()

◆ internal_render_comicinfo()

◆ internal_str_copy_trimmed()

◆ internal_xml_unescape()

◆ mdl_export_build_comicinfo()

◆ mdl_export_build_comicinfo_pages()

◆ mdl_meta_init()

◆ mdl_meta_load_dir()

◆ mdl_meta_parse()

◆ priv_mdl_export_snprintf_fit()

◆ priv_mdl_export_validate_source_url()