cyaml v0.1.3 - API Reference

Types

`cyaml_type_t`

Node types

`CYAML_NONE = 0`	Invalid/uninitialized
`CYAML_NULL`	Null value (~, null)
`CYAML_SCALAR`	Scalar value
`CYAML_SEQ`	Sequence (array)
`CYAML_MAP`	Mapping (object)
`CYAML_ALIAS`	Alias (*anchor)

`cyaml_style_t`

Scalar styles

`CYAML_PLAIN = 0`	Plain (unquoted)
`CYAML_SINGLE`	Single-quoted
`CYAML_DOUBLE`	Double-quoted
`CYAML_LITERAL`	Literal block (\|)
`CYAML_FOLDED`	Folded block (>)

`cyaml_coll_t`

Collection styles

`CYAML_BLOCK = 0`	Block style (indented)
`CYAML_FLOW`	Flow style ({}, [])

`cyaml_chomp_t`

Chomping for block scalars

`CYAML_CLIP = 0`	Default: single trailing newline
`CYAML_STRIP`	Strip all trailing newlines (-)
`CYAML_KEEP`	Keep all trailing newlines (+)

`cyaml_spec_t`

YAML specification version

`CYAML_SPEC_AUTO = 0`	Auto-detect from %YAML directive (default: 1.2)
`CYAML_SPEC_1_1`	YAML 1.1
`CYAML_SPEC_1_2`	YAML 1.2
`CYAML_SPEC_1_3`	YAML 1.3

`cyaml_scalar_flags_t`

Scalar flags (bitmask)

`CYAML_SCALAR_NONE = 0`
`CYAML_SCALAR_EXPLICIT_EMPTY = 1 << 0`	Empty value that should NOT become null

`cyaml_scalar_kind_t`

Inferred scalar value kind (YAML Core Schema)

`CYAML_KIND_NULL`	null, ~, Null, NULL, or empty
`CYAML_KIND_BOOL`	true, false (case-insensitive)
`CYAML_KIND_INT`	Integer (decimal, 0x hex, 0o octal)
`CYAML_KIND_FLOAT`	Float (includes .inf, .nan)
`CYAML_KIND_STRING`	Unrecognized (treat as string)

Span (Atom)

`cyaml_span_t`

Span - a reference into source data with location info This is the core building block: no string copying during parse

`uint32_t off`	Byte offset into source
`uint32_t len`	Length in bytes
`uint32_t start_line`	1-based start line
`uint32_t start_col`	1-based start column
`uint32_t end_line`	1-based end line
`uint32_t end_col`	1-based end column

Node

`cyaml_pair_t`

Key-value pair for mappings

`cyaml_node_t* key`
`cyaml_node_t* val`

Document

`cyaml_pool_t`

`cyaml_node_t** chunks`	Array of chunk pointers (never moved once allocated)
`uint32_t chunk_count`	Number of allocated chunks
`uint32_t chunk_cap`	Capacity of chunks array
`uint32_t count`	Total nodes allocated

`cyaml_tag_directive_t`

`cyaml_span_t handle`	Tag handle (e.g., "!" or "!!" or "!yaml!")
`cyaml_span_t prefix`	Tag prefix (e.g., "tag:yaml.org,2002:")

`cyaml_doc_flags_t`

Document flags

`CYAML_DOC_START = 1 << 0`	Had explicit '---' marker
`CYAML_DOC_END = 1 << 1`	Had explicit '...' marker
`CYAML_HAS_DIRECTIVE = 1 << 2`	Had any directive (%YAML, %TAG, or reserved)
`CYAML_DOC_TAB_SEP = 1 << 3`	Tab separator after '---' marker

`cyaml_mode_t`

Document mode

`CYAML_PARSING`	Parsed document (source borrowed)
`CYAML_BUILDING`	Built document (source owned)

Stream

`cyaml_stream_t`

[9.2] Stream - contains one or more documents l-yaml-stream ::= l-document-prefix* l-any-document? ... Source is always borrowed - caller manages lifetime

`const char* src`	Source buffer (borrowed, must outlive stream)
`uint32_t src_len`	Source length
`cyaml_doc_t** docs`	Array of documents
`uint32_t count`	Number of documents
`uint32_t cap`	Capacity

Error

`cyaml_error_t`

`cyaml_err_t code`
`cyaml_span_t span`	Error location

`cyaml_err_t`

`CYAML_OK = 0`
`CYAML_ERR_NOMEM`
`CYAML_ERR_SYNTAX`
`CYAML_ERR_EOF`
`CYAML_ERR_INDENT`
`CYAML_ERR_ESCAPE`
`CYAML_ERR_ANCHOR`
`CYAML_ERR_ALIAS`
`CYAML_ERR_TAG`
`CYAML_ERR_DUP_KEY`
`CYAML_ERR_IO`

Parse Options

`cyaml_opts_t`

`bool dup_keys`	Allow duplicate keys (default: false)
`bool preserve_comments`	Preserve comments (default: false)
`uint32_t max_depth`	Max nesting depth (0 = unlimited)
`uint32_t max_size`	Max source size (0 = unlimited)
`cyaml_spec_t spec`	YAML spec version (default: auto-detect)

Emit Options

`cyaml_emit_opts_t`

`uint8_t indent`	Indentation (default: 2)
`uint8_t width`	Line width, 0 = no wrap (default: 80)
`bool doc_start`	Emit --- (default: false)
`bool doc_end`	Emit ... (default: false)
`bool preserve_comments`	Emit comments if available (default: false)
`bool preserve_style`	Preserve original node styles (default: false = convert flow to block)
`cyaml_style_t style`	Default scalar style
`cyaml_coll_t coll`	Default collection style

Parsing

`cyaml_doc_t * cyaml_parse(const char* src, size_t len, const cyaml_opts_t* opts, cyaml_error_t* err)`

Parse first document from YAML string

Parameters

src: Source buffer (must outlive returned doc)
len: Source length
opts: Parse options (NULL for defaults)
err: Error output (NULL to ignore)

Returns

Document or NULL on error

`void cyaml_free(cyaml_doc_t* doc)`

Free document and all nodes (does not free source buffer)

Parameters

doc: Document to free (NULL safe)

Stream Parsing

`cyaml_stream_t * cyaml_parse_stream(const char* src, size_t len, const cyaml_opts_t* opts, cyaml_error_t* err)`

Parse YAML stream containing multiple documents

Parameters

src: Source buffer (must outlive returned stream)
len: Source length
opts: Parse options (NULL for defaults)
err: Error output (NULL to ignore)

Returns

Stream or NULL on error

`void cyaml_stream_free(cyaml_stream_t* stream)`

Free stream and all documents (does not free source buffer)

Parameters

stream: Stream to free (NULL safe)

Span Utilities

`char * cyaml_span_dup(const cyaml_doc_t* doc, cyaml_span_t s)`

Duplicate span as null-terminated string

Parameters

doc: Document containing the span
s: Span to duplicate

Returns

Allocated string (caller must free) or NULL

`char * cyaml_scalar_str(const cyaml_doc_t* doc, const cyaml_node_t* n)`

Get scalar value as string with all YAML processing applied Handles escape sequences, line folding, and block scalar indent stripping.

Parameters

doc: Document containing the node
n: Scalar node

Returns

Allocated string (caller must free) or NULL

`bool cyaml_span_eq(const cyaml_doc_t* doc, cyaml_span_t s, const char* str)`

Compare span to string (case-sensitive)

Parameters

doc: Document containing the span
s: Span to compare
str: String to compare against

Returns

true if equal

`bool cyaml_span_ieq(const cyaml_doc_t* doc, cyaml_span_t s, const char* str)`

Compare span to string (case-insensitive)

Parameters

doc: Document containing the span
s: Span to compare
str: String to compare against

Returns

true if equal (ignoring case)

`bool cyaml_span_cmp(const cyaml_doc_t* doc, cyaml_span_t a, cyaml_span_t b)`

Compare two spans for equality

Parameters

doc: Document containing the spans
a: First span
b: Second span

Returns

true if equal

Scalar Value Extraction

`bool cyaml_as_int(const cyaml_doc_t* doc, const cyaml_node_t* n, int64_t* out)`

Parse scalar as signed integer Supports decimal, hex (0x), and octal (0o) formats.

Parameters

doc: Document containing the node
n: Scalar node to parse
out: Output value

Returns

true on success

`bool cyaml_as_uint(const cyaml_doc_t* doc, const cyaml_node_t* n, uint64_t* out)`

Parse scalar as unsigned integer Supports decimal, hex (0x), and octal (0o) formats.

Parameters

doc: Document containing the node
n: Scalar node to parse
out: Output value

Returns

true on success

`bool cyaml_as_float(const cyaml_doc_t* doc, const cyaml_node_t* n, double* out)`

Parse scalar as floating point Supports .inf, -.inf, and .nan special values.

Parameters

doc: Document containing the node
n: Scalar node to parse
out: Output value

Returns

true on success

`bool cyaml_as_bool(const cyaml_doc_t* doc, const cyaml_node_t* n, bool* out)`

Parse scalar as boolean Recognizes true/false (case-insensitive).

Parameters

doc: Document containing the node
n: Scalar node to parse
out: Output value

Returns

true on success

`bool cyaml_is_null_val(const cyaml_doc_t* doc, const cyaml_node_t* n)`

Check if scalar represents null Recognizes ~, null, Null, NULL, or empty value.

Parameters

doc: Document containing the node
n: Node to check

Returns

true if null

`cyaml_scalar_kind_t cyaml_scalar_kind(const cyaml_doc_t* doc, const cyaml_node_t* n)`

Infer scalar value kind using YAML Core Schema rules For plain scalars, determines if value is null, bool, int, float, or string. Quoted scalars are always treated as strings.

Parameters

doc: Document containing the node
n: Scalar node to analyze

Returns

Inferred kind (CYAML_KIND_STRING if not scalar or quoted)

Mapping Access

`cyaml_node_t * cyaml_get(const cyaml_doc_t* doc, const cyaml_node_t* n, const char* key)`

Get mapping value by string key

Parameters

doc: Document containing the node
n: Mapping node
key: Key to look up

Returns

Value node or NULL if not found

`bool cyaml_has(const cyaml_doc_t* doc, const cyaml_node_t* n, const char* key)`

Check if mapping contains key

Parameters

doc: Document containing the node
n: Mapping node
key: Key to check

Returns

true if key exists

Path Access

`cyaml_node_t * cyaml_path(const cyaml_doc_t* doc, const char* path)`

Navigate to node at YPATH Uses YPATH syntax: /store/books[0]/title, /users/*/name, etc. Absolute paths (starting with /) evaluate from document root.

Parameters

doc: Document to query
path: YPATH expression (e.g., "/users[0]/name", "/config/db/host")

Returns

First matching node or NULL if not found

Building

`cyaml_doc_t * cyaml_doc_new(void)`

Create empty document for building YAML programmatically

Returns

New document or NULL on allocation failure

`cyaml_node_t * cyaml_node_new(cyaml_doc_t* doc, cyaml_type_t type)`

Allocate node of specified type from document pool

Parameters

doc: Document to allocate from
type: Node type

Returns

New node or NULL on failure

`cyaml_node_t * cyaml_new_null(cyaml_doc_t* doc)`

Create null node

Parameters

doc: Document to allocate from

Returns

New null node or NULL on failure

`cyaml_node_t * cyaml_new_str(cyaml_doc_t* doc, const char* str, size_t len)`

Create scalar node from string with explicit length

Parameters

doc: Document to allocate from
str: String data (copied)
len: String length

Returns

New scalar node or NULL on failure

`cyaml_node_t * cyaml_new_cstr(cyaml_doc_t* doc, const char* str)`

Create scalar node from null-terminated string

Parameters

doc: Document to allocate from
str: Null-terminated string (copied)

Returns

New scalar node or NULL on failure

`cyaml_node_t * cyaml_new_int(cyaml_doc_t* doc, int64_t val)`

Create scalar node from signed integer

Parameters

doc: Document to allocate from
val: Integer value

Returns

New scalar node or NULL on failure

`cyaml_node_t * cyaml_new_uint(cyaml_doc_t* doc, uint64_t val)`

Create scalar node from unsigned integer

Parameters

doc: Document to allocate from
val: Unsigned value

Returns

New scalar node or NULL on failure

`cyaml_node_t * cyaml_new_float(cyaml_doc_t* doc, double val)`

Create scalar node from floating point

Parameters

doc: Document to allocate from
val: Float value

Returns

New scalar node or NULL on failure

`cyaml_node_t * cyaml_new_bool(cyaml_doc_t* doc, bool val)`

Create scalar node from boolean

Parameters

doc: Document to allocate from
val: Boolean value

Returns

New scalar node or NULL on failure

`cyaml_node_t * cyaml_new_seq(cyaml_doc_t* doc)`

Create empty sequence node

Parameters

doc: Document to allocate from

Returns

New sequence node or NULL on failure

`cyaml_node_t * cyaml_new_map(cyaml_doc_t* doc)`

Create empty mapping node

Parameters

doc: Document to allocate from

Returns

New mapping node or NULL on failure

`bool cyaml_seq_push(cyaml_node_t* seq, cyaml_node_t* item)`

Append item to sequence

Parameters

seq: Sequence node
item: Item to append

Returns

true on success

`bool cyaml_map_set(cyaml_doc_t* doc, cyaml_node_t* map, const char* key, cyaml_node_t* val)`

Set or update mapping key-value pair

Parameters

doc: Document containing the map
map: Mapping node
key: Key string (creates new scalar key)
val: Value node

Returns

true on success

Emitting

`char * cyaml_emit(const cyaml_doc_t* doc, const cyaml_emit_opts_t* opts, size_t* len)`

Emit document to newly allocated YAML string

Parameters

doc: Document to emit
opts: Emit options (NULL for defaults: 2-space indent, 80 char width)
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

`char * cyaml_emit_node(const cyaml_doc_t* doc, const cyaml_node_t* node, const cyaml_emit_opts_t* opts, size_t* len)`

Emit single node to newly allocated YAML string

Parameters

doc: Document containing the node
node: Node to emit
opts: Emit options (NULL for defaults)
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

`char * cyaml_stream_emit(const cyaml_stream_t* stream, size_t* len)`

Emit stream to YAML preserving original formatting

Parameters

stream: Stream to emit
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

Dump (Canonical Output)

`char * cyaml_dump(const cyaml_doc_t* doc, size_t* len)`

Dump document to canonical YAML format Uses yaml-test-suite out.yaml format conventions.

Parameters

doc: Document to dump
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

`char * cyaml_stream_dump(const cyaml_stream_t* stream, size_t* len)`

Dump stream to canonical YAML format (all documents)

Parameters

stream: Stream to dump
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

Event Stream

`char * cyaml_events(const cyaml_doc_t* doc, bool indent, size_t* len)`

Emit event stream for single document

Parameters

doc: Document to emit events for
indent: Add visual indentation (false for yaml-test-suite format)
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

`char * cyaml_stream_events(const cyaml_stream_t* stream, bool indent, size_t* len)`

Emit event stream for full stream (all documents)

Parameters

stream: Stream to emit events for
indent: Add visual indentation
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

JSON Output

`char * cyaml_json(const cyaml_doc_t* doc, int indent, size_t* len)`

Convert document to JSON

Parameters

doc: Document to convert
indent: Spaces per indent level (0 = compact)
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

`char * cyaml_stream_json(const cyaml_stream_t* stream, int indent, size_t* len)`

Convert stream to JSON Single document streams output the JSON value directly. Multi-document streams output as a JSON array.

Parameters

stream: Stream to convert
indent: Spaces per indent level (0 = compact)
len: Output length (NULL to ignore)

Returns

Allocated string (caller must free) or NULL on error

Anchor and Alias Management

`bool cyaml_set_anchor(cyaml_doc_t* doc, cyaml_node_t* node, const char* anchor)`

Set anchor name on a node

Parameters

doc: Document containing the node (must be in BUILDING mode)
node: Node to anchor
anchor: Anchor name (without &), NULL to clear

Returns

true on success

`cyaml_node_t * cyaml_new_alias(cyaml_doc_t* doc, cyaml_node_t* target)`

Create alias node pointing to an anchored node

Parameters

doc: Document to allocate in
target: Target node (must have anchor set)

Returns

New alias node or NULL on failure

`cyaml_node_t * cyaml_find_anchor(const cyaml_doc_t* doc, const char* anchor)`

Find node by anchor name (searches from root)

Parameters

doc: Document to search
anchor: Anchor name to find

Returns

Node with anchor or NULL if not found

`bool cyaml_resolve_aliases(cyaml_doc_t* doc)`

Resolve all aliases in document (replace with deep copies of targets)

Parameters

doc: Document to resolve

Returns

true on success, false if unresolved aliases remain

Node Copy and Merge

`cyaml_node_t * cyaml_node_copy(cyaml_doc_t* doc, const cyaml_doc_t* src, const cyaml_node_t* node)`

Deep copy a node into a document Copies node and all children. Scalar content is copied into target doc.

Parameters

doc: Target document to allocate into
src: Source document containing the node
node: Source node to copy

Returns

New node or NULL on failure

`bool cyaml_map_merge(cyaml_doc_t* doc, cyaml_node_t* dst, const cyaml_node_t* src)`

Deep merge src map into dst map For conflicting keys: scalars replaced, maps merged recursively, seqs replaced.

Parameters

doc: Document containing both nodes
dst: Destination map (modified in place)
src: Source map to merge from

Returns

true on success

Key Sorting

`bool cyaml_map_sort(const cyaml_doc_t* doc, cyaml_node_t* map, cyaml_key_cmp_t cmp)`

Sort mapping keys

Parameters

doc: Document containing the map
map: Mapping node to sort
cmp: Comparison function (NULL for default alphabetical)

Returns

true on success

`bool cyaml_map_sort_recursive(const cyaml_doc_t* doc, cyaml_node_t* node, cyaml_key_cmp_t cmp)`

Sort mapping keys recursively (all nested maps)

Parameters

doc: Document containing the node
node: Starting node (will recurse into children)
cmp: Comparison function (NULL for default alphabetical)

Returns

true on success

Path-based Scanf/Printf API

`int cyaml_scanf(const cyaml_doc_t* doc, const char* format, ...)`

Extract values using path-based scanf

Parameters

doc: Document to query
format: Path+format string (space-separated)

Returns

Number of successfully extracted values, -1 on format error

Examples

unsigned int port;
char host[256];
cyaml_scanf(doc, "/server/port %u /server/host %255s", &port, host);

`int cyaml_vscanf(const cyaml_doc_t* doc, const char* format, va_list ap)`

Extract values using path-based scanf (va_list version)

Parameters

doc: Document to query
format: Path+format string (space-separated)
ap: Variable argument list

Returns

Number of successfully extracted values, -1 on format error

`int cyaml_node_scanf(const cyaml_doc_t* doc, const cyaml_node_t* node, const char* format, ...)`

Extract values starting from a specific node Relative paths start from node, absolute paths (/) still use root.

Parameters

doc: Document containing the node
node: Starting node for relative paths (NULL = root)
format: Path+format string

Returns

Number of successfully extracted values

`int cyaml_node_vscanf(const cyaml_doc_t* doc, const cyaml_node_t* node, const char* format, va_list ap)`

Extract values starting from a specific node (va_list version)

Parameters

doc: Document containing the node
node: Starting node for relative paths (NULL = root)
format: Path+format string
ap: Variable argument list

Returns

Number of successfully extracted values

`cyaml_node_t * cyaml_buildf(cyaml_doc_t* doc, const char* format, ...)`

Build node from printf-style format string Creates nodes by substituting values into a YAML template. Formats: %d, %u, %ld, %lu, %lld, %llu, %f, %lf, %s, %b

Parameters

doc: Document to allocate in
format: YAML with format specifiers

Returns

New node or NULL on error

Examples

cyaml_buildf(doc, "port: %d", 8080)         // -> {port: 8080}

cyaml_buildf(doc, "- %s\n- %s", "a", "b")   // -> [a, b]

cyaml_buildf(doc, "%s", "hello")            // -> "hello"

`cyaml_node_t * cyaml_vbuildf(cyaml_doc_t* doc, const char* format, va_list ap)`

Build node from printf-style format string (va_list version)

Parameters

doc: Document to allocate in
format: YAML with format specifiers
ap: Variable argument list

Returns

New node or NULL on error

Path-based Modification

`bool cyaml_insert_at(cyaml_doc_t* doc, const char* path, cyaml_node_t* val)`

Insert or update node at path Creates intermediate maps as needed. For existing keys, replaces value. Path must resolve to a valid insertion point.

Parameters

doc: Document to modify (must be CYAML_BUILDING mode or parsed)
path: Target path (e.g., "/server/port", "/users/0/name")
val: Value node to insert (must be from same doc)

Returns

true on success

Examples

cyaml_insert_at(doc, "/server/timeout", cyaml_new_int(doc, 30));

`bool cyaml_insertf(cyaml_doc_t* doc, const char* path, const char* format, ...)`

Insert printf-built node at path (convenience) Equivalent to: cyaml_insert_at(doc, path, cyaml_buildf(doc, format, ...))

Parameters

doc: Document to modify
path: Target path
format: YAML format string

Returns

true on success

Examples

cyaml_insertf(doc, "/server", "timeout: %d", 30);

`bool cyaml_delete_at(cyaml_doc_t* doc, const char* path)`

Delete node at path Removes the node from its parent container.

Parameters

doc: Document to modify
path: Path to node to delete

Returns

true if deleted, false if not found

`bool cyaml_append_at(cyaml_doc_t* doc, const char* path, cyaml_node_t* val)`

Append to sequence at path Path must resolve to a sequence node.

Parameters

doc: Document to modify
path: Path to sequence
val: Value to append

Returns

true on success

`bool cyaml_appendf(cyaml_doc_t* doc, const char* path, const char* format, ...)`

Append printf-built node to sequence at path Path must resolve to a sequence node.

Parameters

doc: Document to modify
path: Path to sequence
format: YAML format string for new item

Returns

true on success

Node Comparison

`int cyaml_node_cmp_str(const cyaml_doc_t* doc, const cyaml_node_t* node, const char* str, size_t len)`

Compare scalar node value to string (like strcmp)

Parameters

doc: Document containing node
node: Node to compare (must be scalar)
str: String to compare against
len: String length (0 = use strlen)

Returns

0 if equal, <0 if node < str, >0 if node > str

`bool cyaml_node_eq_str(const cyaml_doc_t* doc, const cyaml_node_t* node, const char* str)`

Check if scalar node equals string

Parameters

doc: Document containing node
node: Node to compare
str: String to compare (null-terminated)

Returns

true if node value equals str

Utility

`const char * cyaml_strerror(cyaml_err_t err)`

Get human-readable error message

Parameters

err: Error code

Returns

Static error string

`const char * cyaml_version(void)`

Get library version string

Returns

Static version string (e.g., "0.1.0")

YPATH Query API

`cyaml_path_result_t`

Query result containing matched nodes or error info

`cyaml_node_t** nodes`	Array of pointers to matched nodes (owned by doc)
`uint32_t count`	Number of matched nodes
`const char* error`	Error message (NULL on success)
`uint32_t error_pos`	Position in path where error occurred

`cyaml_path_result_t cyaml_path_query(const cyaml_doc_t* doc, const cyaml_node_t* context, const char* path)`

Execute a YPATH query and return all matching nodes Nodes returned are pointers into the document - no data is copied.

Parameters

doc: Document to query
context: Context node for relative paths (NULL = use root)
path: YPATH expression (e.g., "/users[0]/name", "/items[?@.active]")

Returns

Result with matched nodes or error info

`void cyaml_path_result_free(cyaml_path_result_t* result)`

Free query result

Parameters

result: Result to free (NULL safe)

`cyaml_node_t * cyaml_path_first(const cyaml_doc_t* doc, const cyaml_node_t* context, const char* path)`

Get first matching node (convenience wrapper) Equivalent to cyaml_path_query + taking first result + free.

Parameters

doc: Document to query
context: Context node for relative paths (NULL = use root)
path: YPATH expression

Returns

First matching node or NULL on error/no match

`void cyaml_path_debug(const char* path)`

Debug: dump tokens and parsed AST to stdout

Parameters

path: YPATH expression to analyze