Span Navigation

Functions for navigating and iterating through spans. More...

Functions
YATL_Result_t	YATL_doc_span (const YATL_Doc_t *doc, YATL_Span_t *out_span)
	Get a span covering the entire document.
YATL_Result_t	YATL_span_find_next (const YATL_Span_t *in_span, YATL_Cursor_t *cursor, YATL_Span_t *out_span)
	Find the next span within a boundary span.
YATL_Result_t	YATL_span_find_name (const YATL_Span_t *in_span, const char *name, YATL_Span_t *out_span)
	Find a table or key-value by name.
YATL_Result_t	YATL_span_find_next_by_name (const YATL_Span_t *in_span, const char *name, const YATL_Cursor_t *in_cursor, YATL_Cursor_t *out_cursor, YATL_Span_t *out_span)
	Find next table or key-value by name with cursor support.
YATL_Result_t	YATL_span_iter_line (const YATL_Span_t *span, YATL_Cursor_t *cursor, const char **out_text, size_t *out_len)
	Iterate over line segments within a span.
YATL_Result_t	YATL_cursor_move (YATL_Cursor_t *cursor, long npos)
	Move a cursor by a character offset.

Detailed Description

Functions for navigating and iterating through spans.

Function Documentation

YATL_cursor_move()

YATL_Result_t YATL_cursor_move	(	YATL_Cursor_t *	cursor,
		long	npos )

Move a cursor by a character offset.

Moves the cursor forward (positive) or backward (negative) by the specified number of characters, crossing line boundaries as needed.

Parameters

cursor	Cursor to move
npos	Number of positions to move (negative for backward)

Returns

YATL_OK if moved successfully

YATL_DONE if reached document boundary

YATL_ERR_INVALID_ARG if cursor is NULL/uninitialized

YATL_doc_span()

YATL_Result_t YATL_doc_span	(	const YATL_Doc_t *	doc,
		YATL_Span_t *	out_span )

Get a span covering the entire document.

Creates a span of type YATL_S_NONE that encompasses all lines in the document.

Parameters

doc	Pointer to document
out_span	Output span covering the document

Returns

YATL_OK on success

YATL_ERR_INVALID_ARG if doc or out_span is NULL

YATL_span_find_name()

YATL_Result_t YATL_span_find_name	(	const YATL_Span_t *	in_span,
		const char *	name,
		YATL_Span_t *	out_span )

Find a table or key-value by name.

Searches for the first TABLE, ARRAY_TABLE, or KEYVAL with the specified name within in_span.

Parameters

in_span	Span to search within
name	Name to search for (literal match, including dots)
out_span	Output span for the found element

Returns

YATL_OK if found

YATL_ERR_NOT_FOUND if no match

YATL_ERR_INVALID_ARG if any parameter is NULL/uninitialized

Note

Dotted table names like [server.http] are matched literally. Use "server.http", not nested searches.

YATL_span_find_next()

YATL_Result_t YATL_span_find_next	(	const YATL_Span_t *	in_span,
		YATL_Cursor_t *	cursor,
		YATL_Span_t *	out_span )

Find the next span within a boundary span.

Iterates through spans within in_span. Use with a cursor to iterate through all children of a span.

Parameters

in_span	Boundary span to search within
cursor	Cursor tracking iteration position (NULL to start from beginning). Initialize with YATL_cursor_create(). Advanced automatically.
out_span	Output span for the found element

Returns

YATL_OK if a span was found

YATL_DONE if no more spans (iteration complete)

YATL_ERR_NOT_FOUND if no spans exist

YATL_ERR_INVALID_ARG if in_span or out_span is NULL/uninitialized

YATL_Cursor_t cursor = YATL_cursor_create();
YATL_Span_t span;
while (YATL_span_find_next(&doc_span, &cursor, &span) == YATL_OK) {
    // Process span
}

YATL_span_find_next_by_name()

YATL_Result_t YATL_span_find_next_by_name	(	const YATL_Span_t *	in_span,
		const char *	name,
		const YATL_Cursor_t *	in_cursor,
		YATL_Cursor_t *	out_cursor,
		YATL_Span_t *	out_span )

Find next table or key-value by name with cursor support.

Like YATL_span_find_name() but supports iteration to find multiple elements with the same name (e.g., array of tables).

Parameters

in_span	Span to search within
name	Name to search for
in_cursor	Starting position (NULL to start from beginning)
out_cursor	Output cursor position after match (NULL to ignore)
out_span	Output span for the found element

Returns

YATL_OK if found

YATL_ERR_NOT_FOUND if no more matches

YATL_ERR_INVALID_ARG if required parameters are NULL/uninitialized

YATL_Cursor_t cursor = YATL_cursor_create();
YATL_Span_t span;
// Find all [[items]] sections
while (YATL_span_find_next_by_name(&doc_span, "items", &cursor, &cursor,
&span) == YATL_OK) {
    // Process each [[items]] section
}

YATL_span_iter_line()

YATL_Result_t YATL_span_iter_line	(	const YATL_Span_t *	span,
		YATL_Cursor_t *	cursor,
		const char **	out_text,
		size_t *	out_len )

Iterate over line segments within a span.

For multi-line spans, iterates through each line segment, returning the text portion within the span boundaries.

Parameters

span	Span to iterate
cursor	Cursor tracking iteration (initialize with YATL_cursor_create())
out_text	Output pointer to line text (not null-terminated)
out_len	Output length of line segment

Returns

YATL_OK for each line segment

YATL_DONE when iteration is complete

YATL_ERR_INVALID_ARG if any parameter is NULL/uninitialized

YATL_Cursor_t cursor = YATL_cursor_create();
const char *text;
size_t len;
while (YATL_span_iter_line(&span, &cursor, &text, &len) == YATL_OK) {
    printf("%.*s\n", (int)len, text);
}