xml_reader_internal.h File Reference

Private contracts for the bounded XML reader implementation. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "xml.h"

Include dependency graph for xml_reader_internal.h:

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

Go to the source code of this file.

Functions
static bool	internal_space (uint8_t c)
	Test whether one byte is XML spacing.
static bool	internal_ascii_letter (uint8_t c)
	Test whether one byte is an ASCII letter.
static bool	internal_name_start (uint8_t c)
	Test a supported ASCII NCName start byte.
static bool	internal_name_continue (uint8_t c)
	Test a supported later ASCII NCName byte.
static ra8_err_t	internal_attr_parse (const uint8_t *source, size_t source_len, uint32_t end, xml_attr_cursor_t *cursor, xml_attribute_t *out)
	Parse one attribute at a bounded tag cursor.
static bool	internal_attr_duplicate (const uint8_t *source, size_t source_len, const xml_event_t *event, const xml_attribute_t *current, uint16_t prior_count)
	Detect a duplicate attribute name.
static ra8_err_t	internal_markup_end (const uint8_t *source, size_t length, size_t start, size_t *out_end)
	Locate a markup closing byte while respecting quotes.
static ra8_err_t	internal_attributes (const uint8_t *source, size_t source_len, xml_event_t *event)
	Count and validate one start tag's attributes.
static ra8_err_t	internal_start (xml_reader_t *reader, size_t end, xml_event_t *event)
	Parse one start element and update nesting.
static ra8_err_t	internal_end (xml_reader_t *reader, size_t end, xml_event_t *event)
	Parse one close element and update nesting.
static ra8_err_t	internal_terminator (const uint8_t *source, size_t length, size_t start, const char *terminator, size_t *out_start)
	Locate a literal terminator in a bounded source.
static ra8_err_t	internal_comment (xml_reader_t *reader)
	Validate and skip one XML comment.
static bool	internal_xml_target (const uint8_t *source, size_t start, size_t end)
	Test for the reserved case-insensitive PI target XML.
static bool	internal_encoding (const uint8_t *source, xml_span_t value)
	Validate an XML declaration encoding name.
static bool	internal_declaration_attr (const uint8_t *source, size_t source_len, const xml_attribute_t *attribute, uint16_t ordinal, bool *saw_encoding, bool *saw_standalone)
	Validate one ordered XML-declaration pseudo-attribute.
static ra8_err_t	internal_declaration (xml_reader_t *reader, size_t target_end, size_t term)
	Validate and skip the leading XML declaration.
static ra8_err_t	internal_pi (xml_reader_t *reader)
	Validate and skip a PI or leading XML declaration.
static ra8_err_t	internal_cdata (xml_reader_t *reader, xml_event_t *event)
	Validate and emit one CDATA payload.
static ra8_err_t	internal_special (xml_reader_t *reader, xml_event_t *event, bool *out_emitted)
	Dispatch comment, CDATA, DOCTYPE, or processing instruction.
static ra8_err_t	internal_text (xml_reader_t *reader, xml_event_t *event)
	Validate and emit one text run.

Detailed Description

Private contracts for the bounded XML reader implementation.

Declares the file-local lexical and event helpers of xml.c so their contracts remain authoritative without inflating the implementation unit. The entity/UTF-8 decoding half of the reader lives in xml_decode.c and documents its helpers at their definitions. [Ring 3 / LIB] {World: NS}

Copyright

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

Definition in file xml_reader_internal.h.

Function Documentation

internal_ascii_letter()

bool internal_ascii_letter ( uint8_t c )

static

Test whether one byte is an ASCII letter.

Performs locale-independent XML-name classification.

Parameters

[in]

c

Byte to classify.

Returns

True for A-Z or a-z.

Return values

true	c is an ASCII letter.
false	c is outside both letter ranges.

Precondition

c is an unsigned source byte.

Locale-dependent ctype state is not consulted.

Postcondition

No memory is modified.

The result depends only on c.

Note

Pure and thread-safe.

Since

0.1.0

References RA8_INTERNAL.

internal_attr_duplicate()

bool internal_attr_duplicate ( const uint8_t * source, size_t source_len, const xml_event_t * event, const xml_attribute_t * current, uint16_t prior_count )

static

Detect a duplicate attribute name.

Replays prior source-order attributes and compares raw QName bytes.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact readable source extent.
[in]	event	Start event being validated.
[in]	current	Newly parsed attribute.
[in]	prior_count	Number of prior attributes to compare.

Returns

True for a duplicate or inconsistent prior traversal.

Return values

true	Duplicate or malformed prior attribute detected.
false	Current name is unique among prior attributes.

Precondition

Event/current spans lie within source_len.

prior_count does not exceed the event's parsed prefix.

Postcondition

No argument memory is modified.

The result is deterministic for the source/event.

Note

Fail-closed on replay inconsistency.

Since

0.1.0

References RA8_INTERNAL.

internal_attr_parse()

ra8_err_t internal_attr_parse ( const uint8_t * source, size_t source_len, uint32_t end, xml_attr_cursor_t * cursor, xml_attribute_t * out )

static

Parse one attribute at a bounded tag cursor.

Validates QName, quoting, decoded value, and cursor progression.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact readable source extent.
[in]	end	Offset of the closing tag delimiter.
[in,out]	cursor	Attribute cursor.
[out]	out	Parsed source-aliasing attribute spans.

Returns

Repository error code.

Return values

k_ra8_ok	Attribute parsed and decoded value validated.
k_ra8_err_validation_failed	Syntax or value was invalid.

Precondition

end and cursor position lie within source_len.

Outputs are writable and source remains immutable.

Postcondition

Success advances cursor once and fills out.

Failure leaves source unchanged; cursor/output may be partial.

Note

Caller handles duplicate-name detection separately.

Since

0.1.0

References RA8_INTERNAL.

internal_attributes()

ra8_err_t internal_attributes ( const uint8_t * source, size_t source_len, xml_event_t * event )

static

Count and validate one start tag's attributes.

Enforces unique names, quoted decoded values, and exact tag tail.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact readable source extent.
[in,out]	event	Start event whose count is populated.

Returns

Repository error code.

Return values

k_ra8_ok	Attributes validated and counted.
k_ra8_err_validation_failed	Tag attributes were malformed.

Precondition

Event name/markup spans lie within source_len.

event is writable and source remains immutable.

Postcondition

Success sets the exact source-order attribute count.

Failure leaves source unchanged; event count is unspecified.

Note

Attribute count is bounded by UINT16_MAX.

Since

0.1.0

internal_cdata()

ra8_err_t internal_cdata ( xml_reader_t * reader, xml_event_t * event )

static

Validate and emit one CDATA payload.

CDATA is accepted only within a live element and aliases source.

Parameters

[in,out]	reader	Active reader positioned at <![CDATA[.
[out]	event	CDATA event to populate.

Returns

Repository error code.

Return values

k_ra8_ok	Payload validated and emitted.
k_ra8_err_validation_failed	Placement, bytes, or terminator was invalid.

Precondition

Reader source/position describe a complete bounded document.

event is writable and does not overlap reader/source.

Postcondition

Success advances after ]]> and returns a bounded payload span.

Failure leaves source unchanged; reader/event may be partial.

Note

Consumers may choose to ignore CDATA events.

Since

0.1.0

References RA8_INTERNAL.

internal_comment()

ra8_err_t internal_comment ( xml_reader_t * reader )

static

Validate and skip one XML comment.

Rejects internal double dash and a payload ending in dash.

Parameters

[in,out]

reader

Active reader positioned at <!--.

Returns

Repository error code.

Return values

k_ra8_ok	Comment validated and skipped.
k_ra8_err_validation_failed	Comment text or terminator was invalid.

Precondition

Reader source/position describe a complete bounded document.

Comment bytes begin at the current position.

Postcondition

Success advances after --> without emitting an event.

Failure leaves source unchanged; reader progress is unspecified.

Note

Comment contents are not retained.

Since

0.1.0

References RA8_INTERNAL.

internal_declaration()

ra8_err_t internal_declaration ( xml_reader_t * reader, size_t target_end, size_t term )

static

Validate and skip the leading XML declaration.

Enforces byte-zero/BOM-zero placement and ordered declaration grammar.

Parameters

[in,out]	reader	Active reader at the lowercase xml target.
[in]	target_end	One-past-last target byte.
[in]	term	First byte of ?>.

Returns

Repository error code.

Return values

k_ra8_ok	Declaration accepted and skipped.
k_ra8_err_validation_failed	Placement or grammar was invalid.

Precondition

Target/terminator offsets lie within the reader source.

Reader declaration/root state reflects all prior bytes.

Postcondition

Success marks the declaration seen and advances position.

Failure leaves source unchanged; reader scratch may be partial.

Note

Only XML 1.0 with absent or exact UTF-8 encoding is accepted.

Since

0.1.0

internal_declaration_attr()

bool internal_declaration_attr ( const uint8_t * source, size_t source_len, const xml_attribute_t * attribute, uint16_t ordinal, bool * saw_encoding, bool * saw_standalone )

static

Validate one ordered XML-declaration pseudo-attribute.

Enforces version first, then optional encoding and standalone.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact readable source extent.
[in]	attribute	Parsed pseudo-attribute.
[in]	ordinal	Zero-based declaration attribute index.
[in,out]	saw_encoding	Encoding-presence state.
[in,out]	saw_standalone	Standalone-presence state.

Returns

True only for a supported name/value/order combination.

Return values

true	Attribute was accepted and state updated.
false	Attribute was invalid or out of order.

Precondition

Attribute spans lie within source_len.

State flags belong to this declaration pass.

Postcondition

Success advances only the matching presence flag.

Source bytes are unchanged on every result.

Note

Version is restricted to 1.0.

Since

0.1.0

References RA8_INTERNAL.

internal_encoding()

bool internal_encoding ( const uint8_t * source, xml_span_t value )

static

Validate an XML declaration encoding name.

Accepts exactly UTF-8 or utf-8 and no aliases.

Parameters

[in]	source	Immutable XML source.
[in]	value	Source-relative declared encoding span.

Returns

True only for the supported encoding spellings.

Return values

true	Encoding is supported.
false	Encoding is absent from the supported set.

Precondition

value lies within readable source.

Declaration attribute syntax was already validated.

Postcondition

No memory is modified.

The result depends only on the bounded span.

Note

The reader always interprets source bytes as UTF-8.

Since

0.1.0

References RA8_INTERNAL.

internal_end()

ra8_err_t internal_end ( xml_reader_t * reader, size_t end, xml_event_t * event )

static

Parse one close element and update nesting.

Allows trailing XML spacing and requires an exact open-name match.

Parameters

[in,out]	reader	Active pull reader positioned at a close tag.
[in]	end	Offset of its closing delimiter.
[out]	event	End event to populate.

Returns

Repository error code.

Return values

k_ra8_ok	Event emitted and top frame popped.
k_ra8_err_validation_failed	Close syntax or nesting mismatched.

Precondition

end is within the reader source.

Reader workspace contains every live open frame.

Postcondition

Success advances position and reduces nesting by one.

Failure leaves source unchanged; reader progress may be partial.

Note

Closing the root marks the document body complete.

Since

0.1.0

References RA8_INTERNAL.

internal_markup_end()

ra8_err_t internal_markup_end ( const uint8_t * source, size_t length, size_t start, size_t * out_end )

static

Locate a markup closing byte while respecting quotes.

Ignores greater-than bytes inside single or double quoted values.

Parameters

[in]	source	Immutable XML source.
[in]	length	Exact readable source extent.
[in]	start	Offset of the opening less-than byte.
[out]	out_end	Offset of the closing greater-than byte.

Returns

Repository error code.

Return values

k_ra8_ok	Closing byte located.
k_ra8_err_validation_failed	Markup was unterminated.

Precondition

source spans length bytes and start is in range.

out_end is writable and does not overlap source.

Postcondition

Success sets out_end within the source.

Failure leaves source unchanged and output unspecified.

Note

Lexical validation occurs in later helpers.

Since

0.1.0

References RA8_INTERNAL.

internal_name_continue()

bool internal_name_continue ( uint8_t c )

static

Test a supported later ASCII NCName byte.

Adds digits, dot, and dash to the start-byte set.

Parameters

[in]

c

Byte to classify.

Returns

True exactly for a supported continuation.

Return values

true	c can continue an NCName component.
false	c cannot continue one.

Precondition

c is an unsigned source byte.

The caller handles namespace colons separately.

Postcondition

No memory is modified.

The result depends only on c.

Note

Pure and thread-safe.

Since

0.1.0

References RA8_INTERNAL.

internal_name_start()

bool internal_name_start ( uint8_t c )

static

Test a supported ASCII NCName start byte.

Accepts an ASCII letter or underscore.

Parameters

[in]

c

Byte to classify.

Returns

True exactly for a supported component start.

Return values

true	c can begin an NCName component.
false	c cannot begin one.

Precondition

c is an unsigned source byte.

The caller applies the documented ASCII QName subset.

Postcondition

No memory is modified.

The result depends only on c.

Note

Pure and thread-safe.

Since

0.1.0

References RA8_INTERNAL.

internal_pi()

ra8_err_t internal_pi ( xml_reader_t * reader )

static

Validate and skip a PI or leading XML declaration.

QName-validates the target and reserves case-insensitive XML.

Parameters

[in,out]

reader

Active reader positioned at <?.

Returns

Repository error code.

Return values

k_ra8_ok	Instruction/declaration validated and skipped.
k_ra8_err_validation_failed	Target, data, or placement was invalid.

Precondition

Reader source/position describe a complete bounded document.

PI opener begins at the current position.

Postcondition

Success advances after ?> without emitting an event.

Failure leaves source unchanged; reader scratch may be partial.

Note

Non-XML processing instructions may appear wherever XML permits.

Since

0.1.0

References RA8_INTERNAL.

internal_space()

bool internal_space ( uint8_t c )

static

Test whether one byte is XML spacing.

Recognises only space, tab, carriage return, and line feed.

Parameters

[in]

c

Byte to classify.

Returns

True exactly for supported XML spacing.

Return values

true	c is XML spacing.
false	c is not XML spacing.

Precondition

c is an unsigned source byte.

Locale-independent ASCII classification is required.

Postcondition

No memory is modified.

The result depends only on c.

Note

Pure and thread-safe.

Since

0.1.0

References RA8_INTERNAL.

internal_special()

ra8_err_t internal_special ( xml_reader_t * reader, xml_event_t * event, bool * out_emitted )

static

Dispatch comment, CDATA, DOCTYPE, or processing instruction.

Fails closed for unsupported declarations and malformed openers.

Parameters

[in,out]	reader	Active reader positioned at special markup.
[out]	event	Optional semantic event storage.
[out]	out_emitted	Whether event contains CDATA.

Returns

Repository error code.

Return values

k_ra8_ok	Supported markup validated and consumed.
k_ra8_err_validation_failed	Unsupported or malformed markup.

Precondition

Reader source/position describe a complete bounded document.

Outputs are writable and do not overlap reader/source.

Postcondition

Success advances reader and accurately reports event emission.

Failure leaves source unchanged; output/reader scratch may be partial.

Note

DOCTYPE handling never fetches an external resource.

Since

0.1.0

internal_start()

ra8_err_t internal_start ( xml_reader_t * reader, size_t end, xml_event_t * event )

static

Parse one start element and update nesting.

Validates QName/attributes/root/depth before pushing a live frame.

Parameters

[in,out]	reader	Active pull reader positioned at a start tag.
[in]	end	Offset of its closing delimiter.
[out]	event	Start event to populate.

Returns

Repository error code.

Return values

k_ra8_ok	Event emitted and reader advanced.
k_ra8_err_validation_failed	Tag, root, or depth was invalid.

Precondition

end is within the reader source and was quote-aware scanned.

Reader workspace is exclusive and writable.

Postcondition

Success advances position and updates bounded nesting.

Failure leaves source unchanged; reader progress may be partial.

Note

Self-closing root elements close immediately.

Since

0.1.0

References RA8_INTERNAL.

internal_terminator()

ra8_err_t internal_terminator ( const uint8_t * source, size_t length, size_t start, const char * terminator, size_t * out_start )

static

Locate a literal terminator in a bounded source.

Performs a forward byte-exact search without sentinel reads.

Parameters

[in]	source	Immutable source bytes.
[in]	length	Exact readable extent.
[in]	start	First candidate byte.
[in]	terminator	NUL-terminated ASCII terminator.
[out]	out_start	First terminator byte.

Returns

Repository error code.

Return values

k_ra8_ok	Terminator found.
k_ra8_err_validation_failed	Terminator absent.

Precondition

start does not exceed length.

Output and literal are valid and do not overlap source mutation.

Postcondition

Success returns an in-range offset.

Failure leaves source and output storage unchanged.

Note

Pure with respect to source bytes.

Since

0.1.0

References RA8_INTERNAL.

internal_text()

ra8_err_t internal_text ( xml_reader_t * reader, xml_event_t * event )

static

Validate and emit one text run.

Validates UTF-8/entities, rejects raw ]]>, and enforces outer S.

Parameters

[in,out]	reader	Active reader positioned at text.
[out]	event	Text event to populate.

Returns

Repository error code.

Return values

k_ra8_ok	Text span validated and emitted.
k_ra8_err_validation_failed	Text bytes or document placement was invalid.

Precondition

Reader source/position describe a complete bounded document.

event is writable and does not overlap reader/source.

Postcondition

Success advances to markup/EOF and returns a bounded span.

Failure leaves source unchanged; reader/event may be partial.

Note

Inter-element whitespace is preserved as text events.

Since

0.1.0

References RA8_INTERNAL.

internal_xml_target()

bool internal_xml_target ( const uint8_t * source, size_t start, size_t end )

static

Test for the reserved case-insensitive PI target XML.

Compares exactly three bytes with ASCII case folding.

Parameters

[in]	source	Immutable source bytes.
[in]	start	First target byte.
[in]	end	One-past-last target byte.

Returns

True exactly for any ASCII case spelling of XML.

Return values

true	Reserved target matched.
false	Length or bytes differed.

Precondition

[start,end) lies in readable source.

start does not exceed end.

Postcondition

No memory is modified.

The result depends only on the bounded bytes.

Note

Exact lowercase handling is decided by the PI consumer.

Since

0.1.0

References RA8_INTERNAL.