Public C API for parsing and manipulating PALS YAML lattices. More...

#include <stdbool.h>
#include <stddef.h>

Macros
#define	YAML_API __attribute__((visibility("default")))

#define	YAML_NULL_ID ((size_t)-1)

#define	END ((size_t)-1)

Typedefs
typedef void *	YAMLTreeHandle

typedef size_t	YAMLNodeId

Functions
struct lattices	get_lattices (const char filename, const char lattice_name)

YAMLTreeHandle	parse_file (const char *filename)

YAMLTreeHandle	parse_string (const char *yaml_str)

YAMLTreeHandle	create_empty_tree ()

void	delete_tree (YAMLTreeHandle tree)

void	remove_node (YAMLTreeHandle tree, YAMLNodeId parent, YAMLNodeId child)

YAMLNodeId	get_root (YAMLTreeHandle tree)

YAMLNodeId	get_parent (YAMLTreeHandle tree, YAMLNodeId node)

YAMLNodeId	get_child_by_key (YAMLTreeHandle tree, YAMLNodeId parent, const char *key)

YAMLNodeId	get_child_by_index (YAMLTreeHandle tree, YAMLNodeId parent, size_t index)

size_t	get_size (YAMLTreeHandle tree, YAMLNodeId node)

char *	get_node_key (YAMLTreeHandle tree, YAMLNodeId node)

bool	is_map (YAMLTreeHandle tree, YAMLNodeId node)

bool	is_sequence (YAMLTreeHandle tree, YAMLNodeId node)

bool	is_scalar (YAMLTreeHandle tree, YAMLNodeId node)

char *	as_string (YAMLTreeHandle tree, YAMLNodeId node)

YAMLNodeId	add_scalar (YAMLTreeHandle tree, YAMLNodeId parent, const char key, const char value, size_t index)

YAMLNodeId	add_map (YAMLTreeHandle tree, YAMLNodeId parent, const char *key, size_t index)

YAMLNodeId	add_sequence (YAMLTreeHandle tree, YAMLNodeId parent, const char *key, size_t index)

void	set_scalar (YAMLTreeHandle tree, YAMLNodeId node, const char *value)

void	set_node_key (YAMLTreeHandle tree, YAMLNodeId node, const char *key)

void	deep_copy_node (YAMLTreeHandle dst_tree, YAMLNodeId dst_node, YAMLTreeHandle src_tree, YAMLNodeId src_node)

void	deep_copy_children (YAMLTreeHandle dst_tree, YAMLNodeId dst_node, YAMLTreeHandle src_tree, YAMLNodeId src_node, size_t index)

char *	node_to_string (YAMLTreeHandle tree, YAMLNodeId node)

char *	tree_to_string (YAMLTreeHandle tree)

bool	write_file (YAMLTreeHandle tree, const char *filename)

void	yaml_free_string (char *str)

Detailed Description

Public C API for parsing and manipulating PALS YAML lattices.

Function Documentation

◆ add_map()

YAMLNodeId add_map	(	YAMLTreeHandle	tree,
		YAMLNodeId	parent,
		const char *	key,
		size_t	index
	)

Adds a new empty MAP child to an existing MAP or sequence.

Parameters

tree	Handle to the tree.
parent	Node ID of the parent MAP or sequence.
key	Key string when parent is a MAP. Pass NULL for sequence elements.
index	Insertion position among existing children. Pass END to append.

Returns: Node ID of the newly created MAP child, or YAML_NULL_ID on failure.

◆ add_scalar()

YAMLNodeId add_scalar	(	YAMLTreeHandle	tree,
		YAMLNodeId	parent,
		const char *	key,
		const char *	value,
		size_t	index
	)

Adds a scalar key-value child to a MAP, or a plain scalar to a sequence.

Parameters

tree	Handle to the tree.
parent	Node ID of the parent MAP or sequence.
key	Key string for MAP parents. Pass NULL for sequence elements.
value	Null-terminated scalar value string.
index	Insertion position among existing children. Pass END to append.

Returns: Node ID of the newly created child, or YAML_NULL_ID on failure.

◆ add_sequence()

YAMLNodeId add_sequence	(	YAMLTreeHandle	tree,
		YAMLNodeId	parent,
		const char *	key,
		size_t	index
	)

Adds a new empty sequence child to an existing MAP or sequence.

Parameters

tree	Handle to the tree.
parent	Node ID of the parent MAP or sequence.
key	Key string when parent is a MAP. Pass NULL for sequence elements.
index	Insertion position among existing children. Pass END to append.

Returns: Node ID of the newly created sequence child, or YAML_NULL_ID on failure.

◆ as_string()

char * as_string	(	YAMLTreeHandle	tree,
		YAMLNodeId	node
	)

Returns the scalar value of a node as a newly allocated null-terminated string.

Parameters

tree	Handle to the tree.
node	Node ID of a node that has a value.

Returns: Heap-allocated string containing the value. The caller must free it with yaml_free_string(). Returns NULL if node is YAML_NULL_ID or the node has no value (e.g. is a MAP or bare sequence).

◆ create_empty_tree()

YAMLTreeHandle create_empty_tree ( )

Creates an empty tree with a MAP root node.

Useful as a destination for deep_copy_node() / deep_copy_children(), or for building a tree programmatically via add_map(), add_sequence(), and add_scalar().

Returns: A tree handle representing an empty MAP. Must be freed with delete_tree().

◆ deep_copy_children()

void deep_copy_children	(	YAMLTreeHandle	dst_tree,
		YAMLNodeId	dst_node,
		YAMLTreeHandle	src_tree,
		YAMLNodeId	src_node,
		size_t	index
	)

Deep-copies the children of a source node into a destination node, inserting them at the given position. Works across different trees.

Only the children are copied — the source node itself is not. Existing children of dst_node are preserved. Strings are duplicated into the destination tree's arena.

Parameters

dst_tree	Handle to the destination tree.
dst_node	Node ID in dst_tree to copy children into.
src_tree	Handle to the source tree (may be the same as dst_tree).
src_node	Node ID in src_tree whose children are copied.
index	Insertion position among dst_node's existing children. Pass END to append after all existing children, or 0 to prepend before all existing children. If either handle is NULL or either node is YAML_NULL_ID, this call is a no-op.

◆ deep_copy_node()

void deep_copy_node	(	YAMLTreeHandle	dst_tree,
		YAMLNodeId	dst_node,
		YAMLTreeHandle	src_tree,
		YAMLNodeId	src_node
	)

Deep-copies the contents of a source node into a destination node, overwriting whatever was previously there. Works across different trees.

Keys, values, type flags, and all descendants are copied. Strings are duplicated into the destination tree's arena so the source tree may be freed independently afterwards.

Parameters

dst_tree	Handle to the destination tree.
dst_node	Node ID in dst_tree to copy into.
src_tree	Handle to the source tree (may be the same as dst_tree).
src_node	Node ID in src_tree to copy from. If either handle is NULL or either node is YAML_NULL_ID, this call is a no-op.

◆ delete_tree()

void delete_tree ( YAMLTreeHandle tree )

Frees all memory associated with a tree handle.

Parameters

tree	Handle previously returned by parse_file(), parse_string(), create_empty_tree(), or get_lattices(). Passing NULL is safe and has no effect.

◆ get_child_by_index()

YAMLNodeId get_child_by_index	(	YAMLTreeHandle	tree,
		YAMLNodeId	parent,
		size_t	index
	)

Returns the nth child of a MAP or sequence node.

Parameters

tree	Handle to the tree.
parent	Node ID of a MAP or sequence node.
index	Zero-based child index.

Returns: Node ID of the child at position index, or YAML_NULL_ID if index is out of range or parent is neither a MAP nor a sequence.

◆ get_child_by_key()

YAMLNodeId get_child_by_key	(	YAMLTreeHandle	tree,
		YAMLNodeId	parent,
		const char *	key
	)

Finds a direct child of a MAP node by its key.

Parameters

tree	Handle to the tree.
parent	Node ID of a MAP node to search.
key	Null-terminated key string to look up.

Returns: Node ID of the matching child, or YAML_NULL_ID if not found or if parent is not a MAP.

◆ get_lattices()

struct lattices get_lattices	(	const char *	filename,
		const char *	lattice_name
	)

Builds and returns all three representations of a lattice file.

Parameters

filename	Path to the top-level YAML lattice file.
lattice_name	Name of the lattice to expand. If NULL or empty: expands the lattice named by the last "use" statement, or expands the last lattice defined in the file if no "use" is present.

Returns

A lattices struct containing three handles:

original: raw tree mapping each file (including includes) to its unparsed contents.
included: tree with all "include" directives resolved and spliced inline.
expanded: tree with the selected lattice fully expanded — scalars substituted, repeats unrolled, inherits merged, and forks resolved. All three handles must be freed individually with delete_tree().

◆ get_node_key()

char * get_node_key	(	YAMLTreeHandle	tree,
		YAMLNodeId	node
	)

Returns the key of a node as a newly allocated null-terminated string.

Parameters

tree	Handle to the tree.
node	Node ID of a keyed node.

Returns: Heap-allocated string containing the key. The caller must free it with yaml_free_string(). Returns NULL if node is YAML_NULL_ID or the node has no key.

◆ get_parent()

YAMLNodeId get_parent	(	YAMLTreeHandle	tree,
		YAMLNodeId	node
	)

Returns the parent of a given node.

Parameters

tree	Handle to the tree containing the node.
node	Node ID whose parent is requested.

Returns: Parent node ID, or YAML_NULL_ID if node is the root or has no parent.

◆ get_root()

YAMLNodeId get_root ( YAMLTreeHandle tree )

Returns the node ID of the tree's root node.

Parameters

tree	Handle to a parsed or constructed tree.

Returns: Root node ID, or YAML_NULL_ID if tree is NULL.

◆ get_size()

size_t get_size	(	YAMLTreeHandle	tree,
		YAMLNodeId	node
	)

Returns the number of direct children of a node.

Parameters

tree	Handle to the tree.
node	Node ID of a MAP or sequence node.

Returns: Number of children, or 0 if node is YAML_NULL_ID or is a scalar.

◆ is_map()

bool is_map	(	YAMLTreeHandle	tree,
		YAMLNodeId	node
	)

Returns true if the node is a MAP (key-value container).

Parameters

tree	Handle to the tree.
node	Node ID to test.

Returns: true if the node is a MAP, false otherwise or if node is YAML_NULL_ID.

◆ is_scalar()

bool is_scalar	(	YAMLTreeHandle	tree,
		YAMLNodeId	node
	)

Returns true if the node is a scalar (plain value, no children).

Parameters

tree	Handle to the tree.
node	Node ID to test.

Returns: true if the node is a scalar, false otherwise or if node is YAML_NULL_ID.

◆ is_sequence()

bool is_sequence	(	YAMLTreeHandle	tree,
		YAMLNodeId	node
	)

Returns true if the node is a sequence (ordered list).

Parameters

tree	Handle to the tree.
node	Node ID to test.

Returns: true if the node is a sequence, false otherwise or if node is YAML_NULL_ID.

◆ node_to_string()

char * node_to_string	(	YAMLTreeHandle	tree,
		YAMLNodeId	node
	)

Emits a node and its descendants as a YAML string.

Parameters

tree	Handle to the tree.
node	Node ID to emit. If YAML_NULL_ID or out of range, returns NULL.

Returns: Heap-allocated null-terminated YAML string. The caller must free it with yaml_free_string().

◆ parse_file()

YAMLTreeHandle parse_file ( const char * filename )

Parses a YAML file from disk into an opaque tree handle.

The file is read into an internal buffer and parsed in-place; the buffer is owned by the returned handle and freed by delete_tree().

Parameters

filename Path to the YAML file to parse.

Returns: A tree handle on success, NULL if the file cannot be opened or if parsing fails.

◆ parse_string()

YAMLTreeHandle parse_string ( const char * yaml_str )

Parses a YAML string into an opaque tree handle.

The string is copied into an internal buffer and parsed in-place; the buffer is owned by the returned handle and freed by delete_tree().

Parameters

yaml_str Null-terminated YAML string to parse.

Returns: A tree handle on success, NULL if parsing fails.

◆ remove_node()

void remove_node	(	YAMLTreeHandle	tree,
		YAMLNodeId	parent,
		YAMLNodeId	child
	)

Removes a child node and all its descendants from the tree.

After removal the child's node ID is invalid and must not be used again. The parent parameter is accepted for API symmetry but is not used internally — the parent is inferred from the tree structure.

Parameters

tree	Handle to the tree containing the node.
parent	Node ID of the parent (unused, may be YAML_NULL_ID).
child	Node ID to remove. If YAML_NULL_ID, this call is a no-op.

◆ set_node_key()

void set_node_key	(	YAMLTreeHandle	tree,
		YAMLNodeId	node,
		const char *	key
	)

Sets or replaces the key of an existing node.

The key string is copied into the tree's internal arena.

Parameters

tree	Handle to the tree.
node	Node ID to update. If YAML_NULL_ID, this call is a no-op.
key	Null-terminated key string to set.

◆ set_scalar()

void set_scalar	(	YAMLTreeHandle	tree,
		YAMLNodeId	node,
		const char *	value
	)

Sets or replaces the scalar value of an existing node.

The value string is copied into the tree's internal arena.

Parameters

tree	Handle to the tree.
node	Node ID to update. If YAML_NULL_ID, this call is a no-op.
value	Null-terminated value string to set.

◆ tree_to_string()

char * tree_to_string ( YAMLTreeHandle tree )

Emits a tree as a YAML string. Same as node_to_string but defaulted to the root.

Parameters

tree	Handle to the tree.

Returns: Heap-allocated null-terminated YAML string. The caller must free it with yaml_free_string().

◆ write_file()

bool write_file	(	YAMLTreeHandle	tree,
		const char *	filename
	)

Writes the entire tree to a file as YAML.

Parameters

tree	Handle to the tree to serialize.
filename	Path to the output file. Created or truncated if it already exists.

Returns: true on success, false if the file could not be opened or if an error occurs during writing.

◆ yaml_free_string()

void yaml_free_string ( char * str )

Frees a string returned by get_node_key(), as_string(), or yaml_to_string().

Passing NULL is safe and has no effect.

Parameters

str	Pointer to the string to free.

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ add_map()

◆ add_scalar()

◆ add_sequence()

◆ as_string()

◆ create_empty_tree()

◆ deep_copy_children()

◆ deep_copy_node()

◆ delete_tree()

◆ get_child_by_index()

◆ get_child_by_key()

◆ get_lattices()

◆ get_node_key()

◆ get_parent()

◆ get_root()

◆ get_size()

◆ is_map()

◆ is_scalar()

◆ is_sequence()

◆ node_to_string()

◆ parse_file()

◆ parse_string()

◆ remove_node()

◆ set_node_key()

◆ set_scalar()

◆ tree_to_string()

◆ write_file()

◆ yaml_free_string()