LIBFYAML-CORE(3)

💖 LIBFYAML-CORE(3) 💖

okay so this is the libfyaml core API page — like, the main character of the whole manual set. grab a strawberry drink 🍓 and let's get into it.

✨ NAME ✨

libfyaml-core — the libfyaml core API. that's it, that's the name, she's simple and she knows it 💅

🎀 CORE 🎀

okay so bestie, listen: this is the single top-level include for the entire libfyaml public API. like, one include and you get everything. including it pulls in all the subsystem headers, no cap:

Core YAML parser, document tree, emitter, and diagnostics (libfyaml/libfyaml-core.h)
General-purpose utilities and portability macros (libfyaml/libfyaml-util.h)
YAML path expression parser and executor (libfyaml/libfyaml-path-exec.h)
Document builder: event-stream to tree conversion (libfyaml/libfyaml-docbuild.h)
Document iterator: tree traversal and event replay (libfyaml/libfyaml-dociter.h)
Composer: callback-driven, path-aware event processing (libfyaml/libfyaml-composer.h)
Pluggable memory allocators (libfyaml/libfyaml-allocator.h)
Thread pool for parallel work (libfyaml/libfyaml-thread.h)
BLAKE3 cryptographic hashing (libfyaml/libfyaml-blake3.h)
Alignment macros and helpers (libfyaml/libfyaml-align.h)
Portable endian detection (libfyaml/libfyaml-endian.h)
Portable atomic operations (libfyaml/libfyaml-atomics.h)
Variable-length size encoding (libfyaml/libfyaml-vlsize.h)

but lowkey, for faster compilation you're allowed to include only the subsystem headers you actually need. slay, minimalism 🧚

and the naming tea ☕: all public symbols are prefixed with fy_ (functions/types) or FY_ (macros and constants). iykyk.

🌈 YAML PARSER, DOCUMENT AND EMITTER 🌈

this header provides the complete YAML 1.2 / JSON parser, document tree, and emitter API — literally the core of libfyaml. it's the biggest and most-used part of the public interface. main character energy fr fr 👑

three complementary APIs cover the full lifecycle of a YAML document:

Event-based parsing (fy_parser_*) — a streaming interface, similar to libyaml's. the parser produces a sequence of typed events (stream-start, document-start, scalar, sequence-start, …) without building an in-memory tree. ideal for large documents, filters, and transcoding pipelines. so efficient ✨

Document tree (fy_document_*, fy_node_*) — builds a fully navigable in-memory tree from a YAML or JSON source. nodes can be queried, modified, merged, and serialised. path-expression helpers (fy_document_scanf(), fy_document_insert_at(), …) give you XPath-like access into the tree 🦋

Emitter (fy_emitter_*) — serialises documents or raw event streams back to YAML or JSON with full control over formatting style, indentation, and quoting. supports streaming output to files, memory buffers, or user-supplied callbacks 🫶

Diagnostics (fy_diag_*) — a structured error-reporting subsystem that attributes messages to precise source locations and integrates with IDE/compiler toolchains via a standard file:line:col: level: text format 💀

all types are opaque pointers (struct fy_parser *, struct fy_document *, struct fy_node *, …) so the ABI is stable across minor releases. iconic behaviour honestly 👑

🌸 struct fy_version 🌸

`struct fy_version`

the YAML version ✨

Definition

struct fy_version {
    int major;
    int minor;
}

Members

major — Major version number
minor — Major version number 😭 (yes bestie, that's what it says — both of them say "Major". not me questioning the docs, periodt)

Description

the parser fills it according to the %YAML directive found in the document.

💜 fy_version_compare 💜

int fy_version_compare(const struct fy_version *va, const struct fy_version *vb)

compare two yaml versions 💅

Parameters

va (const struct fy_version*) – The first version, if NULL use default version
vb (const struct fy_version*) – The second version, if NULL use default version

Description

compare the versions. that's the whole bit.

Return

0 if versions are equal, > 0 if version va is higher than vb, < 0 if version va is lower than vb.

🎀 fy_version_default 🎀

const struct fy_version *fy_version_default(void)

get the default version of the library 🌸

Parameters

void – no arguments

Description

return the default version of the library, i.e. the highest stable version that is supported.

Return

the default YAML version of this library 🫶

🦋 fy_version_is_supported 🦋

bool fy_version_is_supported(const struct fy_version *vers)

check if supported version ⭐

Parameters

vers (const struct fy_version*) – The version to check, NULL means default version.

Description

check if the given YAML version is supported.

Return

true if version supported, false otherwise.

🔥 fy_version_supported_iterate 🔥

const struct fy_version *fy_version_supported_iterate(void **prevp)

iterate over the supported YAML versions 👑

Parameters

prevp (void**) – The previous version iterator

Description

this method iterates over the supported YAML versions of this ibrary (their typo, not mine, i'm obsessed 😭). the start of the iteration is signalled by a NULL in *prevp.

Return

the next node in sequence or NULL at the end of the sequence.

🧚 fy_shutdown 🧚

void fy_shutdown(void)

final cleanup before exit 💀

Parameters

void – no arguments

Description

some libraries — cough*libclang*cough — need explicit cleanup calls at the end of program execution, even if you've never called any of their functions. yes, really. rude, but true 🙈

this method will make sure it calls their cleanup functions so that no memory leaks are reported in valgrind etc. doing the emotional labour so you don't have to 💖

💅 struct fy_tag 💅

`struct fy_tag`

the YAML tag structure ✨

Definition

struct fy_tag {
    const char *handle;
    const char *prefix;
}

Members

handle — Handle of the tag (i.e. "!!")
prefix — The prefix of the tag (i.e. "tag:yaml.org,2002:"). The parser fills it according to the %TAG directives encountered during parsing.

🌈 struct fy_mark 🌈

`struct fy_mark`

marker holding information about a location in a struct fy_input 📍

Definition

struct fy_mark {
    size_t input_pos;
    int line;
    int column;
}

Members

input_pos — Position of the mark (from the start of the current input)
line — Line position (0 index based)
column — Column position (0 index based)

💜 enum fy_error_type 💜

`enum fy_error_type`

the supported diagnostic/error types 🚨

Definition

enum fy_error_type {
    FYET_DEBUG,
    FYET_INFO,
    FYET_NOTICE,
    FYET_WARNING,
    FYET_ERROR,
    FYET_MAX
};

Constants

FYET_DEBUG — Debug level (disabled if library is not compiled in debug mode)
FYET_INFO — Informational level
FYET_NOTICE — Notice level
FYET_WARNING — Warning level
FYET_ERROR — Error level - error reporting is using this level
FYET_MAX — Non inclusive maximum fy_error_type value

🎀 enum fy_error_module 🎀

`enum fy_error_module`

module which generated the diagnostic/error 🧐

Definition

enum fy_error_module {
    FYEM_UNKNOWN,
    FYEM_ATOM,
    FYEM_SCAN,
    FYEM_PARSE,
    FYEM_DOC,
    FYEM_BUILD,
    FYEM_INTERNAL,
    FYEM_SYSTEM,
    FYEM_EMIT,
    FYEM_TYPESET,
    FYEM_DECODE,
    FYEM_ENCODE,
    FYEM_REFLECTION,
    FYEM_MAX
};

Constants

FYEM_UNKNOWN — Unknown, default if not specific
FYEM_ATOM — Atom module, used by atom chunking
FYEM_SCAN — Scanner module
FYEM_PARSE — Parser module
FYEM_DOC — Document module
FYEM_BUILD — Build document module (after tree is constructed)
FYEM_INTERNAL — Internal error/diagnostic module
FYEM_SYSTEM — System error/diagnostic module
FYEM_EMIT — Emitter module
FYEM_TYPESET — Prepare types module (C reflection)
FYEM_DECODE — Decode, serialization -> internal form module
FYEM_ENCODE — Encode, internal form -> serialized form module
FYEM_REFLECTION — Generic reflection module messages
FYEM_MAX — Non inclusive maximum fy_error_module value

⭐ enum fy_parse_cfg_flags ⭐

`enum fy_parse_cfg_flags`

parse configuration flags 🚩

Definition

enum fy_parse_cfg_flags {
    FYPCF_QUIET,
    FYPCF_COLLECT_DIAG,
    FYPCF_RESOLVE_DOCUMENT,
    FYPCF_DISABLE_MMAP_OPT,
    FYPCF_DISABLE_RECYCLING,
    FYPCF_PARSE_COMMENTS,
    FYPCF_DISABLE_DEPTH_LIMIT,
    FYPCF_DISABLE_ACCELERATORS,
    FYPCF_DISABLE_BUFFERING,
    FYPCF_DEFAULT_VERSION_AUTO,
    FYPCF_DEFAULT_VERSION_1_1,
    FYPCF_DEFAULT_VERSION_1_2,
    FYPCF_DEFAULT_VERSION_1_3,
    FYPCF_SLOPPY_FLOW_INDENTATION,
    FYPCF_PREFER_RECURSIVE,
    FYPCF_JSON_AUTO,
    FYPCF_JSON_NONE,
    FYPCF_JSON_FORCE,
    FYPCF_YPATH_ALIASES,
    FYPCF_ALLOW_DUPLICATE_KEYS
};

Constants

FYPCF_QUIET — Quiet, do not output any information messages
FYPCF_COLLECT_DIAG — Collect diagnostic/error messages
FYPCF_RESOLVE_DOCUMENT — When producing documents, automatically resolve them
FYPCF_DISABLE_MMAP_OPT — Disable mmap optimization
FYPCF_DISABLE_RECYCLING — Disable recycling optimization
FYPCF_PARSE_COMMENTS — Enable parsing of comments (experimental)
FYPCF_DISABLE_DEPTH_LIMIT — Disable depth limit check, use with enlarged stack
FYPCF_DISABLE_ACCELERATORS — Disable use of access accelerators (saves memory)
FYPCF_DISABLE_BUFFERING — Disable use of buffering where possible
FYPCF_DEFAULT_VERSION_AUTO — Automatically use the most recent version the library supports
FYPCF_DEFAULT_VERSION_1_1 — Default version is YAML 1.1
FYPCF_DEFAULT_VERSION_1_2 — Default version is YAML 1.2
FYPCF_DEFAULT_VERSION_1_3 — Default version is YAML 1.3 (experimental)
FYPCF_SLOPPY_FLOW_INDENTATION — Allow sloppy indentation in flow mode
FYPCF_PREFER_RECURSIVE — Prefer recursive algorighms instead of iterative whenever possible (again with the typo, i can't 😭)
FYPCF_JSON_AUTO — Automatically enable JSON mode (when extension is .json)
FYPCF_JSON_NONE — Never enable JSON input mode
FYPCF_JSON_FORCE — Force JSON mode always
FYPCF_YPATH_ALIASES — Enable YPATH aliases mode
FYPCF_ALLOW_DUPLICATE_KEYS — Allow duplicate keys on mappings

Description

these flags control the operation of the parse and the debugging output/error reporting via filling in the fy_parse_cfg->flags member 💖

🍓 struct fy_parse_cfg 🍓

`struct fy_parse_cfg`

parser configuration structure. (and we're stopping right here because the page cuts off — more coming bestie, don't go anywhere 🫶)

Definition

struct fy_parse_cfg {
    const char *search_path;
    enum fy_parse_cfg_flags flags;
    void *userdata;
    struct fy_diag *diag;
}

Members 💅

search_path — the search path to use when you're opening files, separated by ':' (yes, like $PATH, bestie, same energy)
flags — the configuration flags, your whole vibe-setting situation
userdata — an opaque user data pointer, literally does not care what you put in there
diag — optional diagnostic interface to use, if you're feeling observant 🩺

Description

This is the argument you hand over to the fy_parser_create() method, which is the thing that actually does the parsing of YAML files. So like, this struct is the lil' permission slip your parser gets before it goes off and parses. 🎀

🌈 enum fy_event_type

enum fy_event_type

Event types, aka the whole cast of characters that can show up while you're parsing.

Definition

enum fy_event_type {
    FYET_NONE,
    FYET_STREAM_START,
    FYET_STREAM_END,
    FYET_DOCUMENT_START,
    FYET_DOCUMENT_END,
    FYET_MAPPING_START,
    FYET_MAPPING_END,
    FYET_SEQUENCE_START,
    FYET_SEQUENCE_END,
    FYET_SCALAR,
    FYET_ALIAS
};

Constants ✨

FYET_NONE — no event, the void, the nothing, the "leave me alone" state
FYET_STREAM_START — stream start event, the opening credits 🎬
FYET_STREAM_END — stream end event, roll credits
FYET_DOCUMENT_START — document start event
FYET_DOCUMENT_END — document end event
FYET_MAPPING_START — YAML mapping start event
FYET_MAPPING_END — YAML mapping end event
FYET_SEQUENCE_START — YAML sequence start event
FYET_SEQUENCE_END — YAML sequence end event
FYET_SCALAR — YAML scalar event
FYET_ALIAS — YAML alias event

🦋 fy_event_type_get_text

const char *fy_event_type_get_text(enum fy_event_type type)

Returns the text of an event type. Give it a type, get a string back, iconic trade.

Parameters

type (enum fy_event_type) — the event type you want the text from

Return

A pointer to a text — like, for FYET_SCALAR you get "=VAL". Slay. 💖

🧚 enum fy_collection_style

enum fy_collection_style

The collection styles that the parser/emitter supports, i.e. the two aesthetics a collection can serve.

Definition

enum fy_collection_style {
    FYCS_ANY,
    FYCS_BLOCK,
    FYCS_FLOW,
    FYCS_MAX
};

Constants

FYCS_ANY — any collection style. Note: the parser never generates this one — it just lets the emitter choose 👑
FYCS_BLOCK — block style (not {}[])
FYCS_FLOW — flow style {}[]
FYCS_MAX — marks end of scalar styles

🍓 enum fy_scalar_style

enum fy_scalar_style

The scalar styles supported by the parser/emitter — every way a scalar can dress itself.

Definition

enum fy_scalar_style {
    FYSS_ANY,
    FYSS_PLAIN,
    FYSS_SINGLE_QUOTED,
    FYSS_DOUBLE_QUOTED,
    FYSS_LITERAL,
    FYSS_FOLDED,
    FYSS_MAX
};

Constants

FYSS_ANY — any scalar style. Not generated by the parser — it lets the emitter choose 💅
FYSS_PLAIN — plain scalar style
FYSS_SINGLE_QUOTED — single quoted style
FYSS_DOUBLE_QUOTED — double quoted style
FYSS_LITERAL — YAML literal block style
FYSS_FOLDED — YAML folded block style
FYSS_MAX — marks end of scalar styles

🎀 struct fy_event_stream_start_data

struct fy_event_stream_start_data

Stream start event data, the little payload that rides along with a stream start.

Definition

struct fy_event_stream_start_data {
    struct fy_token *stream_start;
}

Members

stream_start — the token that started the stream 🫶

🎀 struct fy_event_stream_end_data

struct fy_event_stream_end_data

Stream end event data.

Definition

struct fy_event_stream_end_data {
    struct fy_token *stream_end;
}

Members

stream_end — the token that ended the stream

🎀 struct fy_event_document_start_data

struct fy_event_document_start_data

Document start event data (the manpage says "doument", we love a typo queen 😭).

Definition

struct fy_event_document_start_data {
    struct fy_token *document_start;
    struct fy_document_state *document_state;
    bool implicit;
}

Members

document_start — the token that started the document, or NULL if the document was implicitly started
document_state — the state of the document (i.e. info about the YAML version and the configured tags)
implicit — true if the document started implicitly

🎀 struct fy_event_document_end_data

struct fy_event_document_end_data

Document end event data (again with the "doument", we stan consistency 💀).

Definition

struct fy_event_document_end_data {
    struct fy_token *document_end;
    bool implicit;
}

Members

document_end — the token that ended the document, or NULL if the document was implicitly ended
implicit — true if the document ended implicitly

🎀 struct fy_event_alias_data

struct fy_event_alias_data

Alias event data.

Definition

struct fy_event_alias_data {
    struct fy_token *anchor;
}

Members

anchor — the anchor token defining this alias. It's giving "I know a guy" energy.

🎀 struct fy_event_scalar_data

struct fy_event_scalar_data

Scalar event data.

Definition

struct fy_event_scalar_data {
    struct fy_token *anchor;
    struct fy_token *tag;
    struct fy_token *value;
    bool tag_implicit;
}

Members

anchor — anchor token, or NULL
tag — tag token, or NULL
value — scalar value token (this one cannot be NULL, no cap)
tag_implicit — true if the tag was implicit or explicit

🎀 struct fy_event_sequence_start_data

struct fy_event_sequence_start_data

Sequence start event data.

Definition

struct fy_event_sequence_start_data {
    struct fy_token *anchor;
    struct fy_token *tag;
    struct fy_token *sequence_start;
}

Members

anchor — anchor token, or NULL
tag — tag token, or NULL
sequence_start — sequence start value token, or NULL if the sequence was started implicitly

🎀 struct fy_event_sequence_end_data

struct fy_event_sequence_end_data

Sequence end event data.

Definition

struct fy_event_sequence_end_data {
    struct fy_token *sequence_end;
}

Members

sequence_end — the token that ended the sequence, or NULL if the sequence was implicitly ended

🎀 struct fy_event_mapping_start_data

struct fy_event_mapping_start_data

Mapping start event data.

Definition

struct fy_event_mapping_start_data {
    struct fy_token *anchor;
    struct fy_token *tag;
    struct fy_token *mapping_start;
}

Members

anchor — anchor token, or NULL
tag — tag token, or NULL
mapping_start — mapping start value token, or NULL if the mapping was started implicitly

🎀 struct fy_event_mapping_end_data

struct fy_event_mapping_end_data

Mapping end event data.

Definition

struct fy_event_mapping_end_data {
    struct fy_token *mapping_end;
}

Members

mapping_end — the token that ended the mapping, or NULL if the mapping was implicitly ended

👑 struct fy_event

struct fy_event

The event generated by the parser — the main character of this whole section, honestly.

Definition

struct fy_event {
    enum fy_event_type type;
    union {
        struct fy_event_stream_start_data stream_start;
        struct fy_event_stream_end_data stream_end;
        struct fy_event_document_start_data document_start;
        struct fy_event_document_end_data document_end;
        struct fy_event_alias_data alias;
        struct fy_event_scalar_data scalar;
        struct fy_event_sequence_start_data sequence_start;
        struct fy_event_sequence_end_data sequence_end;
        struct fy_event_mapping_start_data mapping_start;
        struct fy_event_mapping_end_data mapping_end;
    } ;
}

Members

type — type of the event, see enum fy_event_type
{unnamed_union} — anonymous 👻
stream_start — stream start information, valid when fy_event->type is enum FYET_STREAM_START
stream_end — stream end information, valid when fy_event->type is enum FYET_STREAM_END
document_start — document start information, valid when fy_event->type is enum FYET_DOCUMENT_START
document_end — document end information, valid when fy_event->type is enum FYET_DOCUMENT_END
alias — alias information, valid when fy_event->type is enum FYET_ALIAS
scalar — scalar information, valid when fy_event->type is enum FYET_SCALAR
sequence_start — sequence start information, valid when fy_event->type is enum FYET_SEQUENCE_START
sequence_end — sequence end information, valid when fy_event->type is enum FYET_SEQUENCE_END
mapping_start — mapping start information, valid when fy_event->type is enum FYET_MAPPING_START
mapping_end — mapping end information, valid when fy_event->type is enum FYET_MAPPING_END

Description

The parser generates one of these bad boys on every single call to fy_parser_parse(), and you release it with fy_parser_event_free(). Yes bestie, every call — that's the whole cycle, don't forget the free or it's a leak situation 🙈

⭐ enum fy_event_part

enum fy_event_part

Lets you select a specific part of the event, like picking a track off an album.

Definition

enum fy_event_part {
    FYEP_VALUE,
    FYEP_TAG,
    FYEP_ANCHOR
};

Constants

FYEP_VALUE — the value of the event (the main token) 🌟
FYEP_TAG — the tag of the event
FYEP_ANCHOR — the anchor of the event

💜 fy_event_get_type

enum fy_event_type fy_event_get_type(const struct fy_event *fye)

Gets the event's type. Detective behaviour, love that.

Parameters

fye (const struct fy_event*) — the event

Description

Returns the type of the event.

Return

The event type, or FYET_NONE when the event is invalid.

💜 fy_event_data

void *fy_event_data(struct fy_event *fye)

Gets a pointer to the event data.

Parameters

fye (struct fy_event*) — the event

Description

So here's the tea: some languages (cough*golang*cough) really don't like unions, and anonymous unions in particular. Like, they'll literally refuse.

You should not have to use this in other language bindings. It's a workaround, not a lifestyle.

Return

A pointer to the event data structure, or NULL if the event is invalid.

🌸 fy_library_version

const char *fy_library_version(void)

Returns the library version string. Vibe check on the library itself.

Parameters

void — no arguments, she takes nothing 💅

Return

A pointer to a version string of the form <MAJOR>.<MINOR>[[.<PATCH>][-EXTRA-VERSION-INFO]]

🔥 fy_string_to_error_type

enum fy_error_type fy_string_to_error_type(const char *str)

Returns the error type from a string — hand it a string, get the matching error type back.

Parameters

…okay the parameter list is literally where this part of the page cuts off, hold on, next bit picks it right back up 🫶

str (const char*) — the string you want turned into an error type, bestie

Return

The error type if it's greater than or equal to zero, otherwise FYET_MAX (that's the "nope, didn't work" value, no cap) 💅

`fy_error_type_to_string`

const char *fy_error_type_to_string(enum fy_error_type type)

Turn an error type into a string. Like, giving the enum a little name tag ✨

Parameters

type (enum fy_error_type) — the error type you want converted

Return

The string value of the error type, or the empty string "" on error (yes, literally just an empty string, that's the whole mood) 😭

`fy_string_to_error_module`

enum fy_error_module fy_string_to_error_module(const char *str)

Give it a string, get back the error module. Reverse uno card 🃏

Parameters

str (const char*) — the string to convert to an error module

Return

The error type if it's greater than or equal to zero, FYEM_MAX otherwise

`fy_error_module_to_string`

const char *fy_error_module_to_string(enum fy_error_module module)

Convert an error module to a string 🎀

Parameters

module (enum fy_error_module) — the error module to convert

Return

The string value of the error module, or the empty string "" on error

`fy_event_is_implicit`

bool fy_event_is_implicit(struct fy_event *fye)

Vibe check on an event: is it an implicit one or not? 👀

Parameters

fye (struct fy_event*) — a pointer to a struct fy_event to check

Return

true if the event is an implicit one 💖

`fy_document_event_is_implicit`

bool fy_document_event_is_implicit(const struct fy_event *fye)

Same vibe check but specifically for a document event 🦋

Parameters

fye (const struct fy_event*) — a pointer to a struct fy_event to check. It must be either a document start or document end event. Like, that's the assignment, there's no negotiation here 🔥

Return

true if the event is an implicit one

`fy_parser_create`

struct fy_parser *fy_parser_create(const struct fy_parse_cfg *cfg)

Create a parser. Main character energy, honestly 👑

Parameters

cfg (const struct fy_parse_cfg*) — the configuration for the parser

Description

Creates a parser with its configuration cfg. The parser may be destroyed by a corresponding call to fy_parser_destroy(). Slay, and also clean up after yourself 💅

Return

A pointer to the parser, or NULL in case of an error

`fy_parser_destroy`

void fy_parser_destroy(struct fy_parser *fyp)

Destroy the given parser. It's not toxic, it's just over ✨

Parameters

fyp (struct fy_parser*) — the parser to destroy

Description

Destroy a parser you created earlier via fy_parser_create(). Closure, but make it C 🫶

`fy_parser_get_cfg`

const struct fy_parse_cfg *fy_parser_get_cfg(struct fy_parser *fyp)

Get the configuration of a parser. Receipts 👀

Parameters

fyp (struct fy_parser*) — the parser

Return

The configuration of the parser

`fy_parser_get_diag`

struct fy_diag *fy_parser_get_diag(struct fy_parser *fyp)

Get the diagnostic object of a parser 🩺

Parameters

fyp (struct fy_parser*) — the parser to get the diagnostic object from

Description

Returns a pointer to the diagnostic object of a parser object. Note that the returned diag object has a reference taken, so you should fy_diag_unref() it when you're done with it. Like, you can't just keep holding it forever, that's rude 🌸

Return

A pointer to a ref'ed diagnostic object, or NULL in case of an error

`fy_parser_set_diag`

int fy_parser_set_diag(struct fy_parser *fyp, struct fy_diag *diag)

Set the diagnostic object of a parser. Swapping out the whole personality fr fr 💜

Parameters

fyp (struct fy_parser*) — the parser to replace the diagnostic object of
diag (struct fy_diag*) — the parser's new diagnostic object, NULL for default

Description

Replace the parser's current diagnostic object with the one given as an argument. The previous diagnostic object will be unref'ed (and freed if its reference gets to 0). Also note that the diag argument shall take a reference too. Keep track of your refcounts bestie, that's the whole gig 🎀

Return

0 if everything OK, -1 otherwise

`fy_parser_reset`

int fy_parser_reset(struct fy_parser *fyp)

Reset a parser completely. Fresh start, healed era 🌈

Parameters

fyp (struct fy_parser*) — the parser to reset

Description

Completely reset a parser, including after an error that caused a parser error to be emitted. So even your messiest era is recoverable, iconic honestly.

Return

0 if the reset was successful, -1 otherwise

`fy_parser_set_input_file`

int fy_parser_set_input_file(struct fy_parser *fyp, const char *file)

Set the parser to process the given file 📂

Parameters

fyp (struct fy_parser*) — the parser
file (const char*) — the file to parse

Description

Point the parser at the given file for processing. The file is located by honoring the search path of the configuration set by the earlier call to fy_parser_create(). While the parser is in use the file must be available — like, don't go moving it mid-parse, that's chaos 😭 (the original literally says "the file will must be available", and honestly? same energy)

Return

Zero on success, -1 on error

`fy_parser_set_string`

int fy_parser_set_string(struct fy_parser *fyp, const char *str, size_t len)

Set the parser to process the given string ✨

Parameters

fyp (struct fy_parser*) — the parser
str (const char*) — the YAML string to parse
len (size_t) — the length of the string (or -1 if 0 terminated)

Description

Point the parser at the given (NULL terminated) string. Note that while the parser is active the string must not go out of scope. Do not let it wander off, bestie, that's undefined-behaviour territory 🙈

Return

Zero on success, -1 on error

`fy_parser_set_malloc_string`

int fy_parser_set_malloc_string(struct fy_parser *fyp, char *str, size_t len)

Set the parser to process the given malloced string. Handing over the keys 🗝️

Parameters

fyp (struct fy_parser*) — the parser
str (char*) — the YAML string to parse (allocated)
len (size_t) — the length of the string (or -1 if 0 terminated)

Description

Point the parser at the given (possible NULL terminated) string. Note that the string is expected to be allocated via malloc(3) and ownership is transferred to the created input. When the input is free'ed the memory will be automatically freed — cute little memory-management situationship 💖

In case of an error the string is not freed. So if it errors, that malloc is still yours to deal with, no take-backs 🫠

Return

Zero on success, -1 on error

`fy_parser_set_input_fp`

int fy_parser_set_input_fp(struct fy_parser *fyp, const char *name, FILE *fp)

Set the parser to process the given file 🌸

Parameters

fyp (struct fy_parser*) — the parser
name (const char*) — the label of the stream
fp (FILE*) — the FILE pointer, it must be open in read mode

Description

Point the parser to use fp for processing. Read mode only, we're not out here writing files by accident 💀

Return

Zero on success, -1 on error

`fy_parser_set_input_callback`

int fy_parser_set_input_callback(struct fy_parser *fyp, void *user, ssize_t (*callback)(void *user, void *buf, size_t count))

Set the parser to process via a callback. Very "you call me, I call you" of it 📞

Parameters

fyp (struct fy_parser*) — the parser
user (void*) — the user data pointer
callback (ssize_t (*)(void *user, void *buf, size_t count)) — the callback method to request data with

Description

Point the parser to use a callback for input.

Return

Zero on success, -1 on error

`fy_parser_set_input_fd`

int fy_parser_set_input_fd(struct fy_parser *fyp, int fd)

Set the parser to process the given file descriptor 🔢

Parameters

fyp (struct fy_parser*) — the parser
fd (int) — the file descriptor to use

Description

Point the parser to use fd for processing.

Return

Zero on success, -1 on error

`fy_parser_parse`

struct fy_event *fy_parser_parse(struct fy_parser *fyp)

Parse and return the next event. The moment we've all been waiting for ⭐

Parameters

fyp (struct fy_parser*) — the parser

Description

Each call to fy_parser_parse() returns the next event from the configured input of the parser, or NULL at the end of the stream. The returned event must be released via a matching call to fy_parser_event_free(). Like, every event you take, you give back, that's the rule 🤝

Return

The next event in the stream, or NULL

`fy_parser_parse_peek`

const struct fy_event *fy_parser_parse_peek(struct fy_parser *fyp)

Parse and peek at the next event. Looking respectfully 👀

Parameters

fyp (struct fy_parser*) — the parser

Description

It will return the next event that a call to fy_parser_parse would generate, but as read-only.

You must not free this event. Look, don't touch, don't free 🙅‍♀️

Return

A peek at the next event in the stream, or NULL

`fy_parser_skip`

int fy_parser_skip(struct fy_parser *fyp)

Skip the current scalar/collection. Leaving it on read, moving on 💨

Parameters

fyp (struct fy_parser*) — the parser

Description

Skips the current scalar or collection.

Return

0 on success, -1 on error

`fy_parser_count_sequence_items`

int fy_parser_count_sequence_items(struct fy_parser *fyp)

Count the sequence items 🔢✨

Parameters

fyp (struct fy_parser*) — the parser

Description

Counts the number of sequence items. The parser must already be in a sequence state. Note that this uses backtracking so it might not be very efficient — it's giving "doing the most", honestly 🫠

Return

The number of sequence items on success, -1 on error. Note: if the number of items exceeds INT_MAX, INT_MAX will be returned. (Yes, it just caps out and doesn't tell you, iykyk 💀)

`fy_parser_count_mapping_items`

int fy_parser_count_mapping_items(struct fy_parser *fyp)

Count the mapping items 🗺️

Parameters

fyp (struct fy_parser*) — the parser

Description

Counts the number of mapping items. The parser must already be in a mapping state. Note that this uses backtracking so it might not be very efficient — same energy as the sequence one, it's out here re-walking everything 😮‍💨

Return

The number of mapping items on success, -1 on error. Note: if the number of items exceeds INT_MAX, INT_MAX will be returned.

`fy_parser_event_free`

void fy_parser_event_free(struct fy_parser *fyp, struct fy_event *fye)

Free an event. The little cleanup ritual 🧹

Parameters

fyp (struct fy_parser*) — the parser
fye (struct fy_event*) — the event to free (may be NULL)

Description

Free a previously returned event from fy_parser_parse(). Give it back to the universe 💫

`fy_parser_get_stream_error`

bool fy_parser_get_stream_error(struct fy_parser *fyp)

Check the parser for stream errors 🚨

Parameters

fyp (struct fy_parser*) — the parser

Return

true in case of a stream error, false otherwise

`fy_parser_get_mode`

enum fy_parser_mode fy_parser_get_mode(struct fy_parser *fyp)

Get the parser mode 🎛️

So like, real quick before we keep going — this stretch is all about the parser's little diary entries (logs and reports) plus the token besties that hold all the text, styles, and comments. Buckle up, we're going in. 💅

the parser mode getter (yes, this one) ✨

Parameters

fyp (struct fy_parser *) — the parser, obviously.

Description

Grab the parser's current mode, i.e. which YAML version / format it's chewing through rn — YAML 1.1, 1.2, 1.3, or JSON. Iconic little identity check, no cap.

Return

The parser mode. Periodt.

`fy_parser_vlog` 🫶

void fy_parser_vlog(struct fy_parser *fyp, enum fy_error_type type,
                    const char *fmt, va_list ap)

Log using the parser's diagnostics, printf style, but with the va_arg flavour.

Parameters

fyp (struct fy_parser *) — the parser.
type (enum fy_error_type) — the error type.
fmt (const char *) — the printf format string.
ap (va_list) — the argument list.

Description

Drops a log entry onto the parser's diagnostic output. Lowkey the va_list sibling of fy_parser_log, iykyk.

`fy_parser_log` 🌸

void fy_parser_log(struct fy_parser *fyp, enum fy_error_type type,
                   const char *fmt, ...)

Log using the parser's diagnostics, printf style.

Parameters

fyp (struct fy_parser *) — the parser.
type (enum fy_error_type) — the error type.
fmt (const char *) — the printf format string.
ellipsis (ellipsis) — the extra arguments.

Description

Outputs a report on the parser's diagnostics. Same vibe as fy_parser_vlog, just the variadic main-character version 💅

`fy_parser_vreport` 🔥

void fy_parser_vreport(struct fy_parser *fyp, enum fy_error_type type,
                       struct fy_token *fyt, const char *fmt, va_list ap)

Report using the parser's diagnostics, printf style, and mark the token — va_arg edition.

Parameters

fyp (struct fy_parser *) — the parser.
type (enum fy_error_type) — the error type.
fyt (struct fy_token *) — the token.
fmt (const char *) — the printf format string.
ap (va_list) — the argument list.

Description

Outputs a report on the parser and points at the token's position while doing it. It's giving "here's the problem, and here's exactly where 👀".

`fy_parser_report` ⭐

void fy_parser_report(struct fy_parser *fyp, enum fy_error_type type,
                      struct fy_token *fyt, const char *fmt, ...)

Report using the parser's diagnostics, printf style, and mark the token.

Parameters

fyp (struct fy_parser *) — the parser.
type (enum fy_error_type) — the error type.
fyt (struct fy_token *) — the token.
fmt (const char *) — the printf format string.
ellipsis (ellipsis) — the extra arguments.

Description

Outputs a report on the parser and indicates the token's position. Fr the variadic twin of fy_parser_vreport 🎀

`fy_token_scalar_style` 🦋

enum fy_scalar_style fy_token_scalar_style(struct fy_token *fyt)

Get the style of a scalar token.

Parameters

fyt (struct fy_token *) — the scalar token whose style we're getting. Note: a NULL token counts as enum FYSS_PLAIN.

Return

The scalar style of the token, or FYSS_PLAIN in every other case. Soft launch, no drama 💜

`fy_token_collection_style` 🌈

enum fy_collection_style fy_token_collection_style(struct fy_token *fyt)

Get the style of a collection token.

Parameters

fyt (struct fy_token *) — the collection token whose style we're getting. Note: a NULL token counts as enum FYCS_ANY.

Return

The collection style of the token, or FYCS_ANY.

`fy_token_scalar_is_null` 🙈

bool fy_token_scalar_is_null(struct fy_token *fyt)

Test whether the scalar is null (as in, its content).

Parameters

fyt (struct fy_token *) — the scalar token to check for NULLity.

Description

Okay important distinction, bestie — this is not the same as null in the YAML type system. It's null as in null content. It's also different from an empty scalar. Three different things, three different vibes. Don't mix them up 😭

Return

true if it's a null scalar, false otherwise.

`fy_token_get_text` 👑

const char *fy_token_get_text(struct fy_token *fyt, size_t *lenp)

Get the text (and its length) of a token.

Parameters

fyt (struct fy_token *) — the token whose text pointer you want back.
lenp (size_t *) — pointer to a variable that will hold the returned length.

Description

Returns a pointer to the token's text along with its length. Heads up: this text is not NULL terminated — if you need a NULL terminated pointer, use fy_token_get_text0() instead.

If the token is "simple" enough (like a plain scalar) or something similar, the returned pointer is a direct pointer into the input space that holds the token. Which means the pointer is not guaranteed to be valid after the parser is destroyed 💀

If the token is "complex" enough, then space gets allocated, filled, and returned.

And yeah, the concept of "simple" vs "complex" is vague — that's on purpose. We said what we said 🫶

Return

A pointer to the text representation of the token, while lenp gets assigned the character length of said representation. NULL in case of an error.

`fy_token_get_text0` 🎀

const char *fy_token_get_text0(struct fy_token *fyt)

Get zero-terminated text of a token.

Parameters

fyt (struct fy_token *) — the token whose text pointer you want back.

Description

Returns a pointer to the token's text, and this time it is zero terminated. It allocates memory to hold it inside the token structure — so try to use fy_token_get_text() instead if you can, bestie. Your allocator will thank you 💖

Return

A pointer to a zero-terminated text representation of the token. NULL in case of an error.

`fy_token_get_text_length` 🍓

size_t fy_token_get_text_length(struct fy_token *fyt)

Get the length of the text of a token.

Parameters

fyt (struct fy_token *) — the token.

Description

Returns the length of the token's text representation. That's it, that's the whole job ✨

Return

The size of the text representation of a token, -1 in case of an error. Note that a NULL token returns a length of zero.

`enum fy_comment_placement` 💬

Comment placement relative to the token.

Definition

enum fy_comment_placement {
    fycp_top,
    fycp_right,
    fycp_bottom
};

Constants

fycp_top — comment on top of the token.
fycp_right — comment to the right of the token.
fycp_bottom — comment to the bottom of the token.

Three directions, three moods, all valid 🌸

`fy_token_get_comment` 🌼

const char *fy_token_get_comment(struct fy_token *fyt,
                                 enum fy_comment_placement which)

Get the zero-terminated comment of a token.

Parameters

fyt (struct fy_token *) — the token whose comment text you want back.
which (enum fy_comment_placement) — the comment placement.

Description

Grabs the comment attached to a token at the given placement. Very "which one, bestie, top, right, or bottom?" energy.

Return

A pointer to a zero-terminated text representation of the token comment. NULL in case of an error or if the token has no comment.

`fy_token_get_comments` 🧚

const char *fy_token_get_comments(struct fy_token *fyt)

Get all the comments of a token.

Parameters

fyt (struct fy_token *) — the token.

Description

Gets every comment attached to a token. All of them. The whole collection ✨

Return

A pointer to a zero-terminated text representation of all the comments — the comments from all the placements get concatenated and returned as one. NULL in case of an error or if the event has no comments.

`fy_token_set_comment` 💅

int fy_token_set_comment(struct fy_token *fyt, enum fy_comment_placement which,
                         const char *text, size_t len)

Attach a comment to a token.

Parameters

fyt (struct fy_token *) — the token the comment text gets attached to.
which (enum fy_comment_placement) — the placement.
text (const char *) — the text of the comment.
len (size_t) — the length of the comment (FY_NT means the length of text).

Description

Attaches the given comment onto the token at the specified placement. If another comment is already sitting there, it gets overridden — no warning, no sorry, just replaced. And if text is NULL, the comment is removed entirely 🫧

Return

0 on success, -1 on failure.

`fy_event_get_comments` 🔔

const char *fy_event_get_comments(struct fy_event *fye)

Get all the comments of an event.

Parameters

fye (struct fy_event *) — the event.

Return

A pointer to a zero-terminated text representation of all the comments — all placements concatenated into one. NULL in case of an error or if the event has no comments.

Careful, bestie: the pointer must be freed if it's not NULL, via a call to free(). Don't leave it hanging 😭

`fy_node_get_comment` 🌷

const char *fy_node_get_comment(struct fy_node *fyn,
                                enum fy_comment_placement which)

Get a comment of a node.

Parameters

fyn (struct fy_node *) — the node.
which (enum fy_comment_placement) — the placement of the comment.

Return

A pointer to a zero-terminated text representation of the comment. NULL in case of an error or if the event has no such comments.

`fy_node_get_comments` 🌻

const char *fy_node_get_comments(struct fy_node *fyn)

Get all the comments of a node.

Parameters

fyn (struct fy_node *) — the node.

Return

A pointer to a zero-terminated text representation of all the comments — every placement concatenated and returned as one. NULL in case of an error or if the event has no comments.

`struct fy_iter_chunk` 🧩

An iteration chunk.

Definition

struct fy_iter_chunk {
    const char *str;
    size_t len;
}

Members

str — pointer to the start of the chunk.
len — the size of the chunk.

Description

The iterator produces a stream of chunks which cover the whole object. Like little bite-sized pieces of the thing you're walking through 🍰

`fy_token_iter_create` 🦋

struct fy_token_iter *fy_token_iter_create(struct fy_token *fyt)

Create a token iterator.

Parameters

fyt (struct fy_token *) — the token to iterate, or NULL.

Description

Creates an iterator for operating on the given token — or, if you hand it NULL, a generic iterator for use with fy_token_iter_start(). The iterator must be destroyed with a matching call to fy_token_iter_destroy(). No ghost iterators, bestie 👻

Return

A pointer to the newly created iterator, or NULL in case of an error.

`fy_token_iter_destroy` 🫧

void fy_token_iter_destroy(struct fy_token_iter *iter)

Destroy the iterator.

Parameters

iter (struct fy_token_iter *) — the iterator to destroy.

Description

Destroys the iterator created by fy_token_iter_create(). Clean up after yourself, it's the least you can do 💜

`fy_token_iter_start`

void fy_token_iter_start(struct fy_token *fyt, struct fy_token_iter *iter)

Ok so bestie, this one starts the whole iteration vibe over the contents of a token. 🎀

Parameters

fyt (*struct fy_token**) — the token you're gonna iterate over, the main character of this operation
iter (*struct fy_token_iter**) — the iterator you're prepping for the journey

Description

It sets up an iterator so it's ready to operate on the given token. Important little detail: the iterator has to have been created by a previous call to fy_token_iter_create() if you want user level API access. No shortcutting that, iykyk. ✨

`fy_token_iter_finish`

void fy_token_iter_finish(struct fy_token_iter *iter)

The graceful exit. Stops iterating over the contents of a token — closing time, lights off. 💅

Parameters

iter (*struct fy_token_iter**) — the iterator in question

Description

Stops the iteration operation. That's it, that's the whole thing. Periodt.

`fy_token_iter_peek_chunk`

const struct fy_iter_chunk *fy_token_iter_peek_chunk(struct fy_token_iter *iter)

A little looky-loo 👀 at the next iterator chunk — no commitment, just peeking.

Parameters

iter (*struct fy_token_iter**) — the iterator

Description

Peeks at the next iterator chunk. That's the assignment, and it ate.

Return

A pointer to the next iterator chunk, or NULL in case there's no other. 🫶

`fy_token_iter_chunk_next`

const struct fy_iter_chunk *fy_token_iter_chunk_next(struct fy_token_iter *iter, const struct fy_iter_chunk *curr, int *errp)

Gets the next chunk in the sequence — like scrolling to the next slide in the deck. 🦋

Parameters

iter (*struct fy_token_iter**) — the iterator
curr (*const struct fy_iter_chunk**) — the current chunk, or NULL for the first one
errp (*int**) — pointer to an error return value, or NULL

Description

Gets the next iterator chunk in sequence. Lowkey straightforward, highkey essential.

Return

A pointer to the next iterator chunk, or NULL in case there's no other. And heads up: when the return value is NULL, the errp variable gets filled with 0 for a normal end, or -1 in case of an error. Big distinction, don't sleep on it. 💀

`fy_token_iter_advance`

void fy_token_iter_advance(struct fy_token_iter *iter, size_t len)

Moves the iterator position forward like you're skipping ahead in a group chat. ⭐

Parameters

iter (*struct fy_token_iter**) — the iterator
len (size_t*) — the number of bytes to advance the iterator position

Description

It advances the read pointer of the iterator. But listen: mixing calls of this with any call of fy_token_iter_ungetc() / fy_token_iter_utf8_unget() in a single iterator sequence leads to undefined behavior. Not a cute look, don't do it. 😭

`fy_token_iter_read`

ssize_t fy_token_iter_read(struct fy_token_iter *iter, void *buf, size_t count)

Reads a whole block from an iterator — the "give me a handful" option. 🍓

Parameters

iter (*struct fy_token_iter**) — the iterator
buf (*void**) — pointer to a block of memory to receive the data; it must be at least count bytes long
count (size_t*) — the amount of bytes to read

Description

Reads a block from an iterator. And same warning as before: mixing calls of this with any of the ungetc methods leads to undefined behavior. Fr fr, keep them separate.

Return

The amount of data read, or -1 in case of an error.

`fy_token_iter_getc`

int fy_token_iter_getc(struct fy_token_iter *iter)

One singular character, please and thank you. 💖

Parameters

iter (*struct fy_token_iter**) — the iterator

Description

Reads a single character from an iterator. If the iterator is finished, it will return -1. And if any calls to ungetc have pushed a character into the iterator, it shall return that one instead.

Return

The next character in the iterator, or -1 in case of an error, or end of stream. Very demure, very mindful.

`fy_token_iter_ungetc`

int fy_token_iter_ungetc(struct fy_token_iter *iter, int c)

The pushback move — putting a character back like you never took it. 🙈

Parameters

iter (*struct fy_token_iter**) — the iterator
c (int*) — the character to push back, or -1 to reset the pushback buffer

Description

Pushes back a single character to an iterator stream, and it will be returned in subsequent calls of fy_token_iter_getc(). Currently only a single character is allowed to be pushed back, and any further calls to ungetc will return an error. One at a time, bestie, we're not made of buffer space. 💅

Return

The pushed back character given as argument, or -1 in case of an error. And a lil plot twist: if the pushed back character was -1, then 0 will be returned. 🌸

`fy_token_iter_peekc`

int fy_token_iter_peekc(struct fy_token_iter *iter)

Peeks at a single character like checking who's typing before you reply. 👑

Parameters

iter (*struct fy_token_iter**) — the iterator

Description

Peeks at the next character to get from an iterator. If the iterator is finished, it will return -1. If any calls to ungetc have pushed a character into the iterator, it shall return that. Key detail: the character is not removed from the iterator stream. It stays. Iconic behavior, honestly.

Return

The next character in the iterator, or -1 in case of an error, or end of stream.

`fy_token_iter_utf8_get`

int fy_token_iter_utf8_get(struct fy_token_iter *iter)

Same energy as getc but ✨multibyte✨ — getting a single utf8 character. 🌈

Parameters

iter (*struct fy_token_iter**) — the iterator

Description

Reads a single utf8 character from an iterator. If the iterator is finished, it will return -1. If any calls to ungetc have pushed a character into the iterator, it shall return that.

Return

The next utf8 character in the iterator, or -1 in case of an error, or end of stream.

`fy_token_iter_utf8_unget`

int fy_token_iter_utf8_unget(struct fy_token_iter *iter, int c)

The utf8 pushback — putting a whole character back into the stream. 🧚

Parameters

iter (*struct fy_token_iter**) — the iterator
c (int*) — the character to push back, or -1 to reset the pushback buffer

Description

Pushes back a single utf8 character to an iterator stream. It will be returned in subsequent calls of fy_token_iter_utf8_getc(). Currently only a single character is allowed to be pushed back, and any further calls to ungetc will return an error. Same rule as the byte version, no cap.

Return

The pushed back utf8 character given as argument, or -1 in case of an error. If the pushed back utf8 character was -1, then 0 will be returned. 🫶

`fy_token_iter_utf8_peek`

int fy_token_iter_utf8_peek(struct fy_token_iter *iter)

Peeking, but make it utf8. 💜

Parameters

iter (*struct fy_token_iter**) — the iterator

Description

Peeks at the next utf8 character to get from an iterator. If the iterator is finished, it will return -1. If any calls to ungetc have pushed a character into the iterator, it shall return that. And again — the character is not removed from the iterator stream.

Return

The next utf8 character in the iterator, or -1 in case of an error, or end of stream.

`fy_parse_load_document`

struct fy_document *fy_parse_load_document(struct fy_parser *fyp)

Parses the next document off the parser stream — the actual main event. 🔥

Parameters

fyp (*struct fy_parser**) — the parser

Description

This method performs parsing on a parser stream and returns the next document. Which means for a compound document with multiple documents, each call will return the next one. Like flipping to the next page, one at a time. 📖

Return

The next document from the parser stream.

`fy_parse_document_destroy`

void fy_parse_document_destroy(struct fy_parser *fyp, struct fy_document *fyd)

Cleans up a document that came from fy_parse_load_document(). Closure, babes. 🎀

Parameters

fyp (*struct fy_parser**) — the parser
fyd (*struct fy_document**) — the document to destroy

`fy_document_resolve`

int fy_document_resolve(struct fy_document *fyd)

Resolves anchors and merge keys — tying up all the loose ends. ✨

Parameters

fyd (*struct fy_document**) — the document to resolve

Description

This method performs resolution of the given document by replacing references to anchors with their contents and handling merge keys (<<). Very "make it make sense" of it.

Return

zero on success, -1 on error.

`fy_document_has_directives`

bool fy_document_has_directives(const struct fy_document *fyd)

A lil vibe check for directives. 👀

Parameters

fyd (*const struct fy_document**) — the document to check for directives existence

Description

Checks whether the given document has any directives, i.e. TAG or VERSION.

Return

true if directives exist, false if not.

`fy_document_has_explicit_document_start`

bool fy_document_has_explicit_document_start(const struct fy_document *fyd)

Checking if the document rolled up with an explicit start marker. 🌟

Parameters

fyd (*const struct fy_document**) — the document to check for explicit start marker

Description

Checks whether the given document has an explicit document start marker, i.e. ---

Return

true if the document has an explicit document start marker, false if not.

`fy_document_has_explicit_document_end`

bool fy_document_has_explicit_document_end(const struct fy_document *fyd)

And now the end-marker equivalent — the "that's a wrap" check. 🎬

Parameters

fyd (*const struct fy_document**) — the document to check for explicit end marker

Description

Checks whether the given document has an explicit document end marker, i.e. ...

Return

true if the document has an explicit document end marker, false if not.

`fy_node_document`

struct fy_document *fy_node_document(struct fy_node *fyn)

Retrieves the document that the node belongs to — finding the node's home base. 🏠

Parameters

fyn (*struct fy_node**) — the node to retrieve its document

Description

Returns the document of the node. Note that while the node may not be reachable via a path expression, it may still be a member of a document. So don't count it out just because you can't path your way there. 💫

Return

The document of the node, or NULL in case of an error, or when the node has no document attached.

`enum fy_emitter_write_type`

enum fy_emitter_write_type

Type of the emitted output — and yes, this is exactly where things keep going, don't go anywhere. 💅

Definition

okay so this is the enum that tags every little chunk the emitter spits out — like each fragment gets a name badge so you know exactly what it is ✨

enum fy_emitter_write_type {
    fyewt_document_indicator,
    fyewt_tag_directive,
    fyewt_version_directive,
    fyewt_indent,
    fyewt_indicator,
    fyewt_whitespace,
    fyewt_plain_scalar,
    fyewt_single_quoted_scalar,
    fyewt_double_quoted_scalar,
    fyewt_literal_scalar,
    fyewt_folded_scalar,
    fyewt_anchor,
    fyewt_tag,
    fyewt_linebreak,
    fyewt_alias,
    fyewt_terminating_zero,
    fyewt_plain_scalar_key,
    fyewt_single_quoted_scalar_key,
    fyewt_double_quoted_scalar_key,
    fyewt_comment,
    fyewt_indicator_question_mark,
    fyewt_indicator_colon,
    fyewt_indicator_dash,
    fyewt_indicator_left_bracket,
    fyewt_indicator_right_bracket,
    fyewt_indicator_left_brace,
    fyewt_indicator_right_brace,
    fyewt_indicator_comma,
    fyewt_indicator_bar,
    fyewt_indicator_greater,
    fyewt_indicator_single_quote_start,
    fyewt_indicator_single_quote_end,
    fyewt_indicator_double_quote_start,
    fyewt_indicator_double_quote_end,
    fyewt_indicator_ambersand,
    fyewt_indicator_star,
    fyewt_indicator_chomp,
    fyewt_indicator_explicit_indent
};

🧚 Constants

so here's the whole cast, one by one 💅

fyewt_document_indicator — this chunk is a document indicator.
fyewt_tag_directive — this chunk is a tag directive.
fyewt_version_directive — this chunk is a version directive.
fyewt_indent — the manpage literally says "Output chunk is a document indicator" here too 😭 yes bestie, same sentence as above, I'm not making the rules, I'm just telling you what it says.
fyewt_indicator — this chunk is an indicator.
fyewt_whitespace — this chunk is white space.
fyewt_plain_scalar — this chunk is a plain scalar.
fyewt_single_quoted_scalar — this chunk is a single quoted scalar.
fyewt_double_quoted_scalar — this chunk is a double quoted scalar.
fyewt_literal_scalar — this chunk is a literal block scalar.
fyewt_folded_scalar — this chunk is a folded block scalar.
fyewt_anchor — this chunk is an anchor.
fyewt_tag — this chunk is a tag.
fyewt_linebreak — this chunk is a linebreak.
fyewt_alias — this chunk is an alias.
fyewt_terminating_zero — this chunk is a terminating zero.
fyewt_plain_scalar_key — this chunk is a plain scalar key.
fyewt_single_quoted_scalar_key — this chunk is a single quoted scalar key.
fyewt_double_quoted_scalar_key — this chunk is a double quoted scalar key.
fyewt_comment — this chunk is a comment.
fyewt_indicator_question_mark — the ? indicator.
fyewt_indicator_colon — the : indicator.
fyewt_indicator_dash — the - indicator.
fyewt_indicator_left_bracket — the [ indicator.
fyewt_indicator_right_bracket — the ] indicator.
fyewt_indicator_left_brace — the { indicator.
fyewt_indicator_right_brace — the } indicator.
fyewt_indicator_comma — the , indicator.
fyewt_indicator_bar — the | indicator.
fyewt_indicator_greater — the > indicator.
fyewt_indicator_single_quote_start — the ‘ indicator.
fyewt_indicator_single_quote_end — the ‘ indicator.
fyewt_indicator_double_quote_start — the “ indicator.
fyewt_indicator_double_quote_end — the “ indicator.
fyewt_indicator_ambersand — the & indicator. (yes, "ambersand", that's how it's spelled here, love that for us 💀)
fyewt_indicator_star — the * indicator.
fyewt_indicator_chomp — the chomp indicator (- or +).
fyewt_indicator_explicit_indent — the explicit indent indicator (0-9).

Description

it tells you the kind of emitted output, which means you can colorize the output, or do some other content related filtering. so cute, so useful, no cap 🎀

🦋 enum fy_emitter_cfg_flags

enum fy_emitter_cfg_flags — the emitter configuration flags, aka the big pile of switches that decides how your YAML comes out the other side.

Definition

enum fy_emitter_cfg_flags {
    FYECF_SORT_KEYS,
    FYECF_OUTPUT_COMMENTS,
    FYECF_STRIP_LABELS,
    FYECF_STRIP_TAGS,
    FYECF_STRIP_DOC,
    FYECF_NO_ENDING_NEWLINE,
    FYECF_STRIP_EMPTY_KV,
    FYECF_EXTENDED_CFG,
    FYECF_INDENT_DEFAULT,
    FYECF_INDENT_1,
    FYECF_INDENT_2,
    FYECF_INDENT_3,
    FYECF_INDENT_4,
    FYECF_INDENT_5,
    FYECF_INDENT_6,
    FYECF_INDENT_7,
    FYECF_INDENT_8,
    FYECF_INDENT_9,
    FYECF_WIDTH_DEFAULT,
    FYECF_WIDTH_80,
    FYECF_WIDTH_132,
    FYECF_WIDTH_INF,
    FYECF_MODE_ORIGINAL,
    FYECF_MODE_BLOCK,
    FYECF_MODE_FLOW,
    FYECF_MODE_FLOW_ONELINE,
    FYECF_MODE_JSON,
    FYECF_MODE_JSON_TP,
    FYECF_MODE_JSON_ONELINE,
    FYECF_MODE_DEJSON,
    FYECF_MODE_PRETTY,
    FYECF_MODE_MANUAL,
    FYECF_MODE_FLOW_COMPACT,
    FYECF_MODE_JSON_COMPACT,
    FYECF_DOC_START_MARK_AUTO,
    FYECF_DOC_START_MARK_OFF,
    FYECF_DOC_START_MARK_ON,
    FYECF_DOC_END_MARK_AUTO,
    FYECF_DOC_END_MARK_OFF,
    FYECF_DOC_END_MARK_ON,
    FYECF_VERSION_DIR_AUTO,
    FYECF_VERSION_DIR_OFF,
    FYECF_VERSION_DIR_ON,
    FYECF_TAG_DIR_AUTO,
    FYECF_TAG_DIR_OFF,
    FYECF_TAG_DIR_ON,
    FYECF_DEFAULT
};

✨ Constants

FYECF_SORT_KEYS — sort keys when emitting.
FYECF_OUTPUT_COMMENTS — output comments (experimental, bestie, so don't come for me if it's quirky 👀).
FYECF_STRIP_LABELS — strip labels when emitting.
FYECF_STRIP_TAGS — strip tags when emitting.
FYECF_STRIP_DOC — strip document tags and markers when emitting.
FYECF_NO_ENDING_NEWLINE — don't output the ending new line (super handy for single line mode).
FYECF_STRIP_EMPTY_KV — remove all keys with empty values from the output. heads up: not available in streaming mode 🫶
FYECF_EXTENDED_CFG — extend the configuration; this config structure gets embedded in a fy_emitter_xcfg.
FYECF_INDENT_DEFAULT — default emit output indent.
FYECF_INDENT_1 — output indent is 1.
FYECF_INDENT_2 — output indent is 2.
FYECF_INDENT_3 — output indent is 3.
FYECF_INDENT_4 — output indent is 4.
FYECF_INDENT_5 — output indent is 5.
FYECF_INDENT_6 — output indent is 6.
FYECF_INDENT_7 — output indent is 7.
FYECF_INDENT_8 — output indent is 8.
FYECF_INDENT_9 — output indent is 9.
FYECF_WIDTH_DEFAULT — default emit output width.
FYECF_WIDTH_80 — output width is 80.
FYECF_WIDTH_132 — output width is 132.
FYECF_WIDTH_INF — output width is infinite (no wrapping, live ur truth 🌈).
FYECF_MODE_ORIGINAL — emit using the same flow mode as the original.
FYECF_MODE_BLOCK — emit using only the block mode.
FYECF_MODE_FLOW — emit using only the flow mode.
FYECF_MODE_FLOW_ONELINE — emit using only the flow mode, all in one line.
FYECF_MODE_JSON — emit using JSON mode (non type preserving).
FYECF_MODE_JSON_TP — emit using JSON mode (type preserving).
FYECF_MODE_JSON_ONELINE — emit using JSON mode (non type preserving, one line).
FYECF_MODE_DEJSON — emit YAML trying to pretify JSON.
FYECF_MODE_PRETTY — emit YAML that tries to look good 💅.
FYECF_MODE_MANUAL — emit YAML respecting all manual style hints (reformats if needed).
FYECF_MODE_FLOW_COMPACT — emit using only the flow mode, in as much as possible compact form.
FYECF_MODE_JSON_COMPACT — emit using JSON compact form.
FYECF_DOC_START_MARK_AUTO — automatically generate document start markers if required.
FYECF_DOC_START_MARK_OFF — do not generate document start markers.
FYECF_DOC_START_MARK_ON — always generate document start markers.
FYECF_DOC_END_MARK_AUTO — automatically generate document end markers if required.
FYECF_DOC_END_MARK_OFF — do not generate document end markers.
FYECF_DOC_END_MARK_ON — always generate document end markers.
FYECF_VERSION_DIR_AUTO — automatically generate version directive.
FYECF_VERSION_DIR_OFF — never generate version directive.
FYECF_VERSION_DIR_ON — always generate version directive.
FYECF_TAG_DIR_AUTO — automatically generate tag directives.
FYECF_TAG_DIR_OFF — never generate tag directives.
FYECF_TAG_DIR_ON — always generate tag directives.
FYECF_DEFAULT — the default emitter configuration ⭐.

Description

these flags control the operation of the emitter. that's the whole vibe, they're the knobs, you turn them, things change 🎛️

🫶 struct fy_emitter_cfg

struct fy_emitter_cfg — emitter configuration structure.

Definition

struct fy_emitter_cfg {
    enum fy_emitter_cfg_flags flags;
    int (*output)(struct fy_emitter *emit, enum fy_emitter_write_type type, const char *str, int len, void *userdata);
    void *userdata;
    struct fy_diag *diag;
}

Members

flags — configuration flags.
output — pointer to the method that will perform output.
userdata — opaque user data pointer.
diag — diagnostic interface.

Description

this is the argument to the fy_emitter_create() method, which is literally the way to convert a runtime document structure back to YAML. icon behavior only 👑✨

🌸 enum fy_emitter_xcfg_flags

enum fy_emitter_xcfg_flags — emitter extended configuration flags. yes there's a whole extra layer, she's extra like that 💅

Definition

enum fy_emitter_xcfg_flags {
    FYEXCF_COLOR_AUTO,
    FYEXCF_COLOR_NONE,
    FYEXCF_COLOR_FORCE,
    FYEXCF_OUTPUT_STDOUT,
    FYEXCF_OUTPUT_STDERR,
    FYEXCF_OUTPUT_FILE,
    FYEXCF_OUTPUT_FD,
    FYEXCF_NULL_OUTPUT,
    FYEXCF_OUTPUT_FILENAME,
    FYEXCF_VISIBLE_WS,
    FYEXCF_EXTENDED_INDICATORS,
    FYEXCF_INDENTED_SEQ_IN_MAP,
    FYEXCF_PRESERVE_FLOW_LAYOUT
};

🎀 Constants

FYEXCF_COLOR_AUTO — automatically colorize if on a terminal.
FYEXCF_COLOR_NONE — do not colorize output.
FYEXCF_COLOR_FORCE — force color generation (yes even when you're piping it, she said what she said 🔥).
FYEXCF_OUTPUT_STDOUT — output to stdout (this is the default).
FYEXCF_OUTPUT_STDERR — output to stderr, instead of stdout.
FYEXCF_OUTPUT_FILE — output to the fp FILE pointer.
FYEXCF_OUTPUT_FD — output to the fd file descriptor.
FYEXCF_NULL_OUTPUT — no output.
FYEXCF_OUTPUT_FILENAME — output to the given filename.
FYEXCF_VISIBLE_WS — make white space visible 👀 (yes, the invisible becomes visible, spooky season)
FYEXCF_EXTENDED_INDICATORS — extends the indicators that get generated 💫
FYEXCF_INDENTED_SEQ_IN_MAP — indents block sequences that are mapping values (yes bestie, the pretty version) 🎀
FYEXCF_PRESERVE_FLOW_LAYOUT — preserves oneline flow collections when you're in streaming mode 🌊

Description

These flags are literally the remote control for how the emitter behaves. If no extended configuration mode is enabled, all the flags are assumed 0. No mode, no flags, no drama. 💅

struct fy_emitter_xcfg

struct fy_emitter_xcfg — the emitter's extended configuration structure. It's giving "main character struct" energy fr fr 👑

Definition

struct fy_emitter_xcfg {
    struct fy_emitter_cfg cfg;
    enum fy_emitter_xcfg_flags xflags;
    const char *colors[FYEWT_COUNT];
    union {
        FILE *output_fp;
        int output_fd;
        const char *output_filename;
    } ;
}

Members

cfg — the standard emitter configuration, the og setup 🫶
xflags — the extra configuration flags, aka the spicy add-ons 🌶️
colors — ANSI color overrides for the default output method 🌈
{unnamed_union} — anonymous (she has no name, mysterious icon behavior 🙈)
output_fp — the output FILE *; FYEXCF_FILE_OUTPUT must be set or it's not happening
output_fd — the output file descriptor; FYEXCF_FD_OUTPUT must be set
output_filename — the output filename; FYEXCF_FILENAME_OUTPUT must be set

Description

This is what you pass as the argument to the emitter create when the FYECF_EXTENDED_CFG bit is set. That's the whole vibe. ✨

fy_emitter_create

struct fy_emitter *fy_emitter_create(const struct fy_emitter_cfg *cfg)

Create an emitter 💖

Parameters

cfg (*const struct fy_emitter_cfg**) — the emitter configuration

Description

Creates an emitter using the config you handed it. Like, it makes the emitter. That's the tweet. 🐦

Return

The newly created emitter, or NULL on error. If you get NULL, something went wrong, no cap 😭

fy_emitter_destroy

void fy_emitter_destroy(struct fy_emitter *emit)

Destroy an emitter 💀

Parameters

emit (*struct fy_emitter**) — the emitter to destroy

Description

Destroys an emitter that was previously created by fy_emitter_create(). Cleanup era, we love to see it 🧹

fy_emitter_get_cfg

const struct fy_emitter_cfg *fy_emitter_get_cfg(struct fy_emitter *emit)

Get the configuration of an emitter 🎀

Parameters

emit (*struct fy_emitter**) — the emitter

Return

The configuration of the emitter. That's it, that's the whole function 🫶

fy_emitter_get_diag

struct fy_diag *fy_emitter_get_diag(struct fy_emitter *emit)

Get the diagnostic object of an emitter 🩺

Parameters

emit (*struct fy_emitter**) — the emitter to get the diagnostic object from

Description

Returns a pointer to the diagnostic object of an emitter object. Note that the returned diag object has a reference taken, so you should fy_diag_unref() it when you're done with it. Like please don't just ghost it, that's a leak bestie 😭

Return

A pointer to a ref'ed diagnostic object, or NULL in case of an error.

fy_emitter_set_diag

int fy_emitter_set_diag(struct fy_emitter *emit, struct fy_diag *diag)

Set the diagnostic object of an emitter 🩺✨

Parameters

emit (*struct fy_emitter**) — the emitter to replace the diagnostic object on
diag (*struct fy_diag**) — the emitter's new diagnostic object; NULL for default

Description

Swaps out the emitter's current diagnostic object for the one you pass in. The previous diagnostic object will be unref'ed (and freed if its reference gets to 0). Also note that the diag argument shall take a reference too — everybody's holding refs, it's a whole group chat 💅

Return

0 if everything's OK, -1 otherwise.

fy_emitter_set_finalizer

void fy_emitter_set_finalizer(struct fy_emitter *emit, void (*finalizer)(struct fy_emitter *emit))

Set emitter finalizer 🎬

Parameters

emit (*struct fy_emitter**) — the emitter to replace the diagnostic object on
finalizer (void (*)(struct fy_emitter *emit)) — the finalizer callback

Description

Sets a method callback that gets called when the emitter is disposed of. If finalizer is NULL, then the method is removed. Ghosted, gone, no more callback 🫥

struct fy_emitter_default_output_data

struct fy_emitter_default_output_data — the emitter's default output configuration, the starter pack of output settings 🍓

Definition

struct fy_emitter_default_output_data {
    FILE *fp;
    bool colorize;
    bool visible;
}

Members

fp — the file where the output is directed to 📁
colorize — use ANSI color sequences to colorize the output 🌈
visible — make whitespace visible (requires a UTF8 capable terminal, so check before you commit bestie) 👀

Description

This is the argument to the default output method of the emitter. That's its whole job 🫡

fy_emitter_default_output

int fy_emitter_default_output(struct fy_emitter *fye, enum fy_emitter_write_type type, const char *str, int len, void *userdata)

The default colorizing output method 🌈💖

Parameters

fye (*struct fy_emitter**) — the emitter
type (enum fy_emitter_write_type) — the type of the emitted output
str (*const char**) — pointer to the string to output
len (int) — length of the string
userdata (*void**) — must point to a fy_emitter_default_output_data structure

Description

This is the default colorizing output method. It will be used when the output field of the emitter configuration is NULL. Default behavior, but make it fashion ✨

Return

0 on success, -1 on error.

fy_document_default_emit_to_fp

int fy_document_default_emit_to_fp(struct fy_document *fyd, FILE *fp)

Emit a document to a file, using defaults 📄➡️📁

Parameters

fyd (*struct fy_document**) — the document to emit
fp (*FILE**) — the file where the output is sent

Description

Simple one-shot emitter to a file, using the default emitter output. The output will be colorized if the file points to a tty. Cute AND functional 🎀

Return

0 on success, -1 on error.

fy_emit_event

int fy_emit_event(struct fy_emitter *emit, struct fy_event *fye)

Queue (and possibly emit) an event 📨

Parameters

emit (*struct fy_emitter**) — the emitter to use
fye (*struct fy_event**) — the event to queue for emission

Description

Queues and outputs using the emitter. This is the streaming output method, which does not require creating a document. No document, no problem 💅

Return

0 on success, -1 on error.

fy_emit_vevent

int fy_emit_vevent(struct fy_emitter *emit, enum fy_event_type type, va_list ap)

Queue (and possibly emit) an event using varargs 🎁

Parameters

emit (*struct fy_emitter**) — the emitter to use
type (enum fy_event_type) — the event type to create
ap (va_list) — the variable argument list pointer

Description

Queues and outputs using the emitter. The format is identical to the one used in fy_emit_event_vcreate(). Same format, different entry point, iykyk 🫶

Return

0 on success, -1 on error.

fy_emit_eventf

int fy_emit_eventf(struct fy_emitter *emit, enum fy_event_type type, ...)

Queue (and possibly emit) an event using variable args ✨

Parameters

emit (*struct fy_emitter**) — the emitter to use
type (enum fy_event_type) — the event type to create
ellipsis (ellipsis) — the optional extra arguments

Description

Queues and outputs using the emitter. The format is identical to the one used in fy_emit_event_create(). Yes it's basically the same description, they're siblings, let them live 😌

Return

0 on success, -1 on error.

fy_emit_scalar_write

int fy_emit_scalar_write(struct fy_emitter *fye, enum fy_scalar_style style, const char *anchor, const char *tag, const char *buf, size_t count)

Emit a scalar with write semantics ✍️

Parameters

fye (*struct fy_emitter**) — the emitter to use
style (enum fy_scalar_style) — the scalar style to use
anchor (*const char**) — the anchor, or NULL
tag (*const char**) — the tag, or NULL
buf (*const char**) — pointer to the buffer
count (size_t) — the number of bytes to write

Description

Queues and outputs a scalar using the emitter, via a standard write interface. Bytes go in, YAML comes out 🌸

Return

0 on success, -1 on error.

fy_emit_scalar_vprintf

int fy_emit_scalar_vprintf(struct fy_emitter *fye, enum fy_scalar_style style, const char *anchor, const char *tag, const char *fmt, va_list ap)

Emit a scalar with vprintf semantics 🖨️

Parameters

fye (*struct fy_emitter**) — the emitter to use
style (enum fy_scalar_style) — the scalar style to use
anchor (*const char**) — the anchor, or NULL
tag (*const char**) — the tag, or NULL
fmt (*const char**) — the printf-like format string
ap (va_list) — the argument list

Description

Queues and outputs a scalar using the emitter, via a standard vprintf interface. Format strings but make it YAML 💅

Return

0 on success, -1 on error.

fy_emit_scalar_printf

int fy_emit_scalar_printf(struct fy_emitter *fye, enum fy_scalar_style style, const char *anchor, const char *tag, const char *fmt, ...)

Emit a scalar with printf semantics 🔥

Parameters

fye (*struct fy_emitter**) — the emitter to use
style (enum fy_scalar_style) — the scalar style to use
anchor (*const char**) — the anchor, or NULL
tag (*const char**) — the tag, or NULL
fmt (*const char**) — the printf-like format string
ellipsis (ellipsis) — the extra arguments

Description

Queues and outputs a scalar using the emitter, via a standard printf interface. The people's champion of scalar emission 👑

Return

0 on success, -1 on error.

fy_emit_event_from_parser

int fy_emit_event_from_parser(struct fy_emitter *emit, struct fy_parser *fyp, struct fy_event *fye)

Queue (and possibly emit) an event generated by the parser 🔄

Parameters

emit (*struct fy_emitter**) — the emitter to use
fyp (*struct fy_parser**) — the parser that generated the event
fye (*struct fy_event**) — the event to queue for emission

Description

Queues and outputs using the emitter. This is the streaming output method, which does not require creating a document. Similar to fy_emit_event() but it is more efficient. Same energy, better performance, we stan 💜

Return

0 on success, -1 on error.

fy_emit_document

int fy_emit_document(struct fy_emitter *emit, struct fy_document *fyd)

Emit the document using the emitter 📜✨

Parameters

emit (*struct fy_emitter**) — the emitter
fyd (*struct fy_document**) — the document to emit

Description

Emits a document in YAML format using the emitter. Whole document, one call, slay 💅

Return

0 on success, -1 on error 💖

`fy_emit_document_start`

int fy_emit_document_start(struct fy_emitter *emit, struct fy_document *fyd, struct fy_node *fyn)

Emit a document start using the emitter ✨

Parameters

emit (struct fy_emitter*) — the emitter
fyd (struct fy_document*) — the document to pull its start from for emitting
fyn (struct fy_node*) — the root, or NULL if you want to just use the document's root

Description

Drops a document start through the emitter. Bestie, this is the one you reach for when you need finer control over the emitting output — like, when you're hand-driving the whole thing instead of letting the library do it. 🎀

Return

0 on success, -1 on error

`fy_emit_document_end`

int fy_emit_document_end(struct fy_emitter *emit)

Emit document end using the emitter 🌸

Parameters

emit (struct fy_emitter*) — the emitter

Description

Drops a document end through the emitter. Same deal as above: this exists so you get finer control over the emitting output. 💅

Return

0 on success, -1 on error

`fy_emit_node`

int fy_emit_node(struct fy_emitter *emit, struct fy_node *fyn)

Emit a single node using the emitter 🦋

Parameters

emit (struct fy_emitter*) — the emitter
fyn (struct fy_node*) — the node to emit

Description

Emits one single node through the emitter. Again — finer control over the emitting output is the entire point, iykyk. ✨

Return

0 on success, -1 on error

`fy_emit_root_node`

int fy_emit_root_node(struct fy_emitter *emit, struct fy_node *fyn)

Emit a single root node using the emitter 👑

Parameters

emit (struct fy_emitter*) — the emitter
fyn (struct fy_node*) — the root node to emit

Description

Emits a single root node through the emitter. Main character energy only — and yes, it's for when you need finer control over the emitting output. 💜

Return

0 on success, -1 on error

`fy_emit_body_node`

int fy_emit_body_node(struct fy_emitter *emit, struct fy_node *fyn)

Emit a single body node using the emitter 🫶

Parameters

emit (struct fy_emitter*) — the emitter
fyn (struct fy_node*) — the body node to emit

Description

Emits a single body node through the emitter, for finer control over the emitting output. Important vibe check though: no stream and document events will be generated at all. Like, none. Zero. Not a single one. 😭

Return

0 on success, -1 on error

`fy_emit_explicit_document_end`

int fy_emit_explicit_document_end(struct fy_emitter *emit)

Emit an explicit document end ⭐

Parameters

emit (struct fy_emitter*) — the emitter

Description

Emits an explicit document end, i.e. ... — yes, literally the three dots, that's the whole flex. Use this if you need finer control over the emitting output. (Also, tiny thing, the original docs say "if you you need" and I'm choosing to believe that was a stylistic choice. Anyway. 💅)

Return

0 on success, -1 on error

`fy_emit_document_to_fp`

int fy_emit_document_to_fp(struct fy_document *fyd, enum fy_emitter_cfg_flags flags, FILE *fp)

Emit a document to a file pointer 🍓

Parameters

fyd (struct fy_document*) — the document to emit
flags (enum fy_emitter_cfg_flags) — the emitter flags to use
fp (FILE*) — the file pointer to output to

Description

Emits a document, starting from the root, straight out to the file pointer you handed it. 📤

Return

0 on success, -1 on error

`fy_emit_document_to_file`

int fy_emit_document_to_file(struct fy_document *fyd, enum fy_emitter_cfg_flags flags, const char *filename)

Emit a document to a file 🎀

Parameters

fyd (struct fy_document*) — the document to emit
flags (enum fy_emitter_cfg_flags) — the emitter flags to use
filename (const char*) — the filename to output to, or NULL for stdout

Description

Emits a document, from the root, to the file you named. Heads up: the file gets fopen'ed using a "wa" mode. 🗂️

Return

0 on success, -1 on error

`fy_emit_document_to_fd`

int fy_emit_document_to_fd(struct fy_document *fyd, enum fy_emitter_cfg_flags flags, int fd)

Emit a document to a file descriptor 🌈

Parameters

fyd (struct fy_document*) — the document to emit
flags (enum fy_emitter_cfg_flags) — the emitter flags to use
fd (int) — the file descriptor to output to

Description

Emits a document, from the root, to the file descriptor you gave it. 🧚

Return

0 on success, -1 on error

`fy_emit_document_to_buffer`

int fy_emit_document_to_buffer(struct fy_document *fyd, enum fy_emitter_cfg_flags flags, char *buf, size_t size)

Emit a document to a buffer 💖

Parameters

fyd (struct fy_document*) — the document to emit
flags (enum fy_emitter_cfg_flags) — the emitter flags to use
buf (char*) — pointer to the buffer area to fill
size (size_t) — size of the buffer

Description

Emits a document, from the root, into the buffer you provided. And ngl, if the document doesn't fit? an error will be returned. So size it right, bestie. 😭

Return

A positive number — the size of the emitted document sitting in the buffer — on success, -1 on error

`fy_emit_document_to_string`

char *fy_emit_document_to_string(struct fy_document *fyd, enum fy_emitter_cfg_flags flags)

Emit a document to an allocated string ✨

Parameters

fyd (struct fy_document*) — the document to emit
flags (enum fy_emitter_cfg_flags) — the emitter flags to use

Description

Emits a document, from the root, into a string which gets dynamically allocated for you. 🦋

Return

A pointer to the allocated string, or NULL in case of an error

`fy_emit_node_to_buffer`

int fy_emit_node_to_buffer(struct fy_node *fyn, enum fy_emitter_cfg_flags flags, char *buf, size_t size)

Emit a node (recursively) to a buffer 🎀

Parameters

fyn (struct fy_node*) — the node to emit
flags (enum fy_emitter_cfg_flags) — the emitter flags to use
buf (char*) — pointer to the buffer area to fill
size (size_t) — size of the buffer

Description

Emits a node recursively into the buffer you gave it. And again, if it doesn't fit, an error will be returned — no silent truncation, no drama, just an error. 🙈

Return

A positive number — the size of the emitted node in the buffer — on success, -1 on error

`fy_emit_node_to_string`

char *fy_emit_node_to_string(struct fy_node *fyn, enum fy_emitter_cfg_flags flags)

Emit a node to an allocated string 🌸

Parameters

fyn (struct fy_node*) — the node to emit
flags (enum fy_emitter_cfg_flags) — the emitter flags to use

Description

Emits a node recursively into a string which will be dynamically allocated. Obsessed, honestly. 💜

Return

A pointer to the allocated string, or NULL in case of an error

`fy_emit_to_buffer`

struct fy_emitter *fy_emit_to_buffer(enum fy_emitter_cfg_flags flags, char *buf, size_t size)

Create an emitter for buffer output 🔥

Parameters

flags (enum fy_emitter_cfg_flags) — the emitter flags to use
buf (char*) — pointer to the buffer area to fill
size (size_t) — size of the buffer

Description

Creates a special purpose emitter that outputs into a buffer. Your fy_emit_event() calls populate that buffer, and then you go grab the contents with a call to fy_emit_to_buffer_collect(). 🫶

Return

The newly created emitter, or NULL on error

`fy_emit_to_buffer_collect`

char *fy_emit_to_buffer_collect(struct fy_emitter *emit, size_t *sizep)

Collect the buffer emitter output 🧺

Parameters

emit (struct fy_emitter*) — the emitter
sizep (size_t*) — pointer to the size to be filled

Description

Collects the output of an emitter that was created by fy_emit_to_buffer() and then populated via fy_emit_event() calls. The returned buffer is NULL terminated, and it's the same one you passed into fy_emit_to_buffer() — no surprise copy, no plot twist. The sizep argument gets filled with the size of the buffer. ✨

Return

The buffer, or NULL in case of an error

`fy_emit_to_string`

struct fy_emitter *fy_emit_to_string(enum fy_emitter_cfg_flags flags)

Create an emitter to create a dynamically allocated string 💫

Parameters

flags (enum fy_emitter_cfg_flags) — the emitter flags to use

Description

Creates a special purpose emitter that outputs into a dynamically allocated string. Your fy_emit_event() calls populate the buffer, and you retrieve the contents with a call to fy_emit_to_string_collect(). 🌟

Return

The newly created emitter, or NULL on error

`fy_emit_to_string_collect`

char *fy_emit_to_string_collect(struct fy_emitter *emit, size_t *sizep)

Collect the string emitter output 🎀

Parameters

emit (struct fy_emitter*) — the emitter
sizep (size_t*) — pointer to the size to be filled

Description

Collects the output of an emitter created by fy_emit_to_string() and populated using fy_emit_event() calls. The NULL terminated returned buffer is dynamically allocated and must be freed via a call to free(). Ma'am, free your memory. The sizep argument gets filled with the size of the buffer. 💅

Return

The dynamically allocated string, or NULL in case of an error

`fy_node_copy`

struct fy_node *fy_node_copy(struct fy_document *fyd, struct fy_node *fyn_from)

Copy a node, associating the new node with the given document 🦋

Parameters

fyd (struct fy_document*) — the document which the resulting node will be associated with
fyn_from (struct fy_node*) — the source node to recursively copy

Description

Makes a deep copy of a node and associates that copy with the document you passed in. And here's the slay part: no content copying takes place because the contents of the nodes are reference counted — so this operation is relatively inexpensive. Literally so cheap. 💸

Also worth flagging: the copy includes all anchors contained in the subtree of the source, so this call will register them with the document. Don't say I didn't warn you. 🌸

Return

The copied node on success, NULL on error

`fy_document_clone`

struct fy_document *fy_document_clone(struct fy_document *fydsrc)

Clones a document 👑

Parameters

fydsrc (struct fy_document*) — the source document to clone

Description

okay so cloning a document is giving deep copy of the source, bestie. 🫶 And the cute part? No content copying takes place, because the contents of the nodes are reference counted. That means the operation is relatively inexpensive. Slay. 💅

Return

The newly created clone document, or NULL in case of an error.

🧩 `fy_node_insert`

int fy_node_insert(struct fy_node *fyn_to, struct fy_node *fyn_from)

Insert a node to the given node.

Parameters

fyn_to (struct fy_node*) — the target node.
fyn_from (struct fy_node*) — the source node.

Description

Insert a node to another node. If fyn_from is NULL, then this operation will delete the fyn_to node. 💀

🌸 The operation varies according to the types of the arguments

from: scalar

to: another-scalar -> scalar to: { key: value } -> scalar to: [ seq0,
seq1 ] -> scalar

from: [ seq2 ] to: scalar -> [ seq2 ] to: { key: value } -> [ seq2 ] to:
[ seq0, seq1 ] -> [ seq0, seq1, sec2 ]

from: { another-key: another-value } to: scalar -> { another-key:
another-value } to: { key: value } -> { key: value, another-key:
another-value } to: [ seq0, seq1 ] -> { another-key: another-value }

from: { key: another-value } to: scalar -> { key: another-value } to: {
key: value } -> { key: another-value } to: [ seq0, seq1 ] -> { key:
another-value }

💅 The rules are

If target node changes type, source ovewrites target.
If source or target node are scalars, source it overwrites target.
If target and source are sequences, the items of the source sequence are appended to the target sequence.
If target and source are maps, the key, value pairs of the source are appended to the target map. If the target map contains a key-value pair that is present in the source map, it is overwriten by it.

Return

0 on success, -1 on error.

🗑️ `fy_node_delete`

int fy_node_delete(struct fy_node *fyn)

Delete a node from a document.

Parameters

fyn (struct fy_node*) — the node to delete.

Description

Delete the given node. If it’s part of a sequence, it will be removed from it. If it’s the value of a node key value pair, it will be removed from the mapping.

This is literally an alias for fy_document_insert_at(fyn, NULL). 👀

Note that it is expected this node is attached to a document. Do not call this to free a node, because if it’s part of a collection it will not be properly removed. That’s a no-no, bestie. 🚫

Return

0 on success, -1 on error.

📌 `fy_document_insert_at`

int fy_document_insert_at(struct fy_document *fyd, const char *path,
    size_t pathlen, struct fy_node *fyn)

Insert a node to the given path in the document.

Parameters

fyd (struct fy_document*) — the document.
path (const char*) — the path where the insert operation will target.
pathlen (size_t) — the length of the path (or -1 if ‘0’ terminated).
fyn (struct fy_node*) — the source node.

Description

Insert a node to a given point in the document. If fyn is NULL, then this operation will delete the target node.

Please see fy_node_insert for details of operation. 🫶

Note that in any case the fyn node will be unref’ed. So if the operation fails, and the reference is 0, the node will be freed. If you want it to stick around, take a reference before. fr fr.

Return

0 on success, -1 on error.

🔢 `enum fy_node_type`

Node type.

Definition

enum fy_node_type {
    FYNT_SCALAR,
    FYNT_SEQUENCE,
    FYNT_MAPPING
};

Constants

FYNT_SCALAR — node is a scalar.
FYNT_SEQUENCE — node is a sequence.
FYNT_MAPPING — node is a mapping.

Description

Each node may be one of the following types. No cap. ✨

🎨 `enum fy_node_style`

Node style.

Definition

enum fy_node_style {
    FYNS_ANY,
    FYNS_FLOW,
    FYNS_BLOCK,
    FYNS_PLAIN,
    FYNS_SINGLE_QUOTED,
    FYNS_DOUBLE_QUOTED,
    FYNS_LITERAL,
    FYNS_FOLDED,
    FYNS_ALIAS
};

Constants

FYNS_ANY — no hint, let the emitter decide.
FYNS_FLOW — prefer flow style (for sequence/mappings).
FYNS_BLOCK — prefer block style (for sequence/mappings).
FYNS_PLAIN — plain style preferred.
FYNS_SINGLE_QUOTED — single quoted style preferred.
FYNS_DOUBLE_QUOTED — double quoted style preferred.
FYNS_LITERAL — literal style preferred (valid in block context).
FYNS_FOLDED — folded style preferred (valid in block context).
FYNS_ALIAS — it’s an alias.

Description

A node may contain a hint of how it should be rendered, encoded as a style. Obsessed with the aesthetic control here. 💅

🚶 `enum fy_node_walk_flags`

Node walk flags.

Definition

enum fy_node_walk_flags {
    FYNWF_DONT_FOLLOW,
    FYNWF_FOLLOW,
    FYNWF_PTR_YAML,
    FYNWF_PTR_JSON,
    FYNWF_PTR_RELJSON,
    FYNWF_PTR_YPATH,
    FYNWF_URI_ENCODED,
    FYNWF_MAXDEPTH_DEFAULT,
    FYNWF_MARKER_DEFAULT,
    FYNWF_PTR_DEFAULT
};

Constants

FYNWF_DONT_FOLLOW — don’t follow aliases during pathwalk.
FYNWF_FOLLOW — follow aliases during pathwalk.
FYNWF_PTR_YAML — YAML pointer path walks.
FYNWF_PTR_JSON — JSON pointer path walks.
FYNWF_PTR_RELJSON — relative JSON pointer path walks.
FYNWF_PTR_YPATH — YPATH pointer path walks.
FYNWF_URI_ENCODED — the path is URI encoded.
FYNWF_MAXDEPTH_DEFAULT — max follow depth is automatically determined.
FYNWF_MARKER_DEFAULT — default marker to use when scanning.
FYNWF_PTR_DEFAULT — default path type.

🎨 `fy_node_style_from_scalar_style`

enum fy_node_style fy_node_style_from_scalar_style(enum fy_scalar_style
    sstyle)

Convert from scalar to node style.

Parameters

sstyle (enum fy_scalar_style) — the input scalar style.

Description

Convert a scalar style to a node style.

Return

The matching node style.

🧮 `typedef fy_node_mapping_sort_fn`

int fy_node_mapping_sort_fn(const struct fy_node_pair *fynp_a, const
    struct fy_node_pair *fynp_b, void *arg)

Mapping sorting method function.

Parameters

fynp_a (const struct fy_node_pair*) — the first node_pair used in the comparison.
fynp_b (const struct fy_node_pair*) — the second node_pair used in the comparison.
arg (void*) — the opaque user provided pointer to the sort operation.

Return

<0 if fynp_a is less than fynp_b; 0 if fynp_a is equal to fynp_b; >0 if fynp_a is greater than fynp_b.

🔍 `typedef fy_node_scalar_compare_fn`

int fy_node_scalar_compare_fn(struct fy_node *fyn_a, struct fy_node
    *fyn_b, void *arg)

Node compare method function for scalars.

Parameters

fyn_a (struct fy_node*) — the first scalar node used in the comparison.
fyn_b (struct fy_node*) — the second scalar node used in the comparison.
arg (void*) — the opaque user provided pointer to the compare operation.

Return

<0 if fyn_a is less than fyn_b; 0 if fyn_a is equal to fyn_b; >0 if fyn_a is greater than fyn_b.

⚖️ `fy_node_compare`

bool fy_node_compare(struct fy_node *fyn1, struct fy_node *fyn2)

Compare two nodes for equality.

Parameters

fyn1 (struct fy_node*) — the first node to use in the comparison.
fyn2 (struct fy_node*) — the second node to use in the comparison.

Description

Compare two nodes for equality. The comparison is deep, i.e. it recurses in subnodes, and orders the keys of maps using default libc strcmp ordering. For scalar, the comparison is performed after any escaping, so it’s a true content comparison. periodt. 💖

Return

true if the nodes contain the same content, false otherwise.

🪄 `fy_node_compare_user`

bool fy_node_compare_user(struct fy_node *fyn1, struct fy_node *fyn2,
    fy_node_mapping_sort_fn sort_fn, void *sort_fn_arg,
    fy_node_scalar_compare_fn cmp_fn, void *cmp_fn_arg)

Compare two nodes for equality using user supplied sort and scalar compare methods.

Parameters

fyn1 (struct fy_node*) — the first node to use in the comparison.
fyn2 (struct fy_node*) — the second node to use in the comparison.
sort_fn (fy_node_mapping_sort_fn) — the method to use for sorting maps, or NULL for the default.
sort_fn_arg (void*) — the extra user supplied argument to the sort_fn.
cmp_fn (fy_node_scalar_compare_fn) — the method to use for comparing scalars, or NULL for the default.
cmp_fn_arg (void*) — the extra user supplied argument to the cmp_fn.

Description

Compare two nodes for equality using user supplied sot and scalar compare methods. Yes, that’s literally sot, bestie — not me, the page said it. 💀 The comparison is deep, i.e. it recurses in subnodes, and orders the keys of maps using the supplied mapping sort method for ordering. For scalars, the comparison is performed using the supplied scalar node compare methods.

Return

true if the nodes contain the same content, false otherwise.

🧵 `fy_node_compare_string`

bool fy_node_compare_string(struct fy_node *fyn, const char *str, size_t
    len)

Compare a node for equality with a YAML string.

Parameters

fyn (struct fy_node*) — the node to use in the comparison.
str (const char*) — the YAML string to compare against.
len (size_t) — the length of the string (or -1 if ‘0’ terminated).

Description

Compare a node for equality with a YAML string. The comparison is performed using fy_node_compare() with the first node supplied as an argument and the second being generated by calling fy_document_build_from_string with the YAML string.

Return

true if the node and the string are equal.

🔑 `fy_node_compare_token`

bool fy_node_compare_token(struct fy_node *fyn, struct fy_token *fyt)

Compare a node for equality against a token.

Parameters

fyn (struct fy_node*) — the node to use in the comparison.
fyt (struct fy_token*) — the scalar token.

So basically this one does an equality check between a node and a token — and listen, both of them have to be scalars, no exceptions, no vibes-based exceptions 💀

Return — true if the node and the token are equal. That's it, that's the whole reward.

`fy_node_compare_text`

bool fy_node_compare_text(struct fy_node *fyn, const char *text, size_t len)

Compare a node for equality with a raw C text ✨

Parameters

fyn (struct fy_node *) — the node you're putting in the comparison
text (const char *) — the raw C text you're comparing against
len (size_t) — how long that text is (or -1 if it's 0 terminated)

Description

Compares a node for equality with a raw C string. Soft requirement, hard requirement: the node must be a scalar. That's non-negotiable bestie 🎀

Return

true if the node and the text are equal. Iconic behaviour, no notes.

`fy_document_create`

struct fy_document *fy_document_create(const struct fy_parse_cfg *cfg)

Create an empty document 🫶 a blank canvas, a fresh start, main character energy

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default

Description

Makes you an empty document using whatever parser configuration you handed over. If it's NULL, it just uses the default parse configuration. Lowkey the easiest call in the whole library.

Return

The freshly created empty document, or NULL on error 😭

`fy_document_destroy`

void fy_document_destroy(struct fy_document *fyd)

Destroy a document previously created via fy_document_create() 💅

Parameters

fyd (struct fy_document *) — the document to destroy

Description

Destroys a document — and yes, along with all children documents. It's giving "take the whole friend group with you." Handle with care, bestie.

`fy_document_get_cfg`

const struct fy_parse_cfg *fy_document_get_cfg(struct fy_document *fyd)

Get the configuration of a document 🌸

Parameters

fyd (struct fy_document *) — the document

Return

The configuration of the document. Slay, now you know what rules it's playing by.

`fy_document_get_diag`

struct fy_diag *fy_document_get_diag(struct fy_document *fyd)

Get the diagnostic object of a document 🔍

Parameters

fyd (struct fy_document *) — the document to get the diagnostic object from

Description

Returns a pointer to the diagnostic object of a document object. Important, don't skip this: the returned diag object has a reference taken, so you should fy_diag_unref() it when you're done with it. Not me reminding you to clean up — okay yes, it's literally me reminding you 💀

Return

A pointer to a ref'ed diagnostic object, or NULL in case of an error.

`fy_document_set_diag`

int fy_document_set_diag(struct fy_document *fyd, struct fy_diag *diag)

Set the diagnostic object of a document 🎀

Parameters

fyd (struct fy_document *) — the document whose diagnostic object gets replaced
diag (struct fy_diag *) — the document's new diagnostic object, NULL for default

Description

Swaps the document's current diagnostic object out for the one you passed in. The previous diagnostic object gets unref'ed (and freed if its reference count hits 0). Also note that the diag argument shall take a reference too — yes, it's a whole two-way reference situation, keep up 🫶

Return

0 if everything OK, -1 otherwise.

`fy_document_set_parent`

int fy_document_set_parent(struct fy_document *fyd, struct fy_document *fyd_child)

Make a document a child of another 👑 found family arc

Parameters

fyd (struct fy_document *) — the parent document
fyd_child (struct fy_document *) — the child document

Description

Sets the parent of the fyd_child document to be fyd. Simple as that.

Return

0 if all OK, -1 on error.

`fy_document_build_from_string`

struct fy_document *fy_document_build_from_string(const struct fy_parse_cfg *cfg, const char *str, size_t len)

Create a document using the provided YAML source ✨

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default
str (const char *) — the YAML source to use
len (size_t) — the length of the string (or -1 if 0 terminated)

Description

Creates a document by parsing the string you gave it as a YAML source. Feed it text, get a document. Iconic.

Return

The created document, or NULL on error 😭

`fy_document_build_from_malloc_string`

struct fy_document *fy_document_build_from_malloc_string(const struct fy_parse_cfg *cfg, char *str, size_t len)

Create a document using the provided YAML source which was malloced 🧚

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default
str (char *) — the YAML source to use
len (size_t) — the length of the string (or -1 if 0 terminated)

Description

Creates a document by parsing the provided string as a YAML source. The twist: the string is expected to have been allocated by malloc(3), and when the document is destroyed it will be automatically freed. So like, don't go freeing it yourself afterward, that's not the vibe 🫶

Return

The created document, or NULL on error.

`fy_document_build_from_file`

struct fy_document *fy_document_build_from_file(const struct fy_parse_cfg *cfg, const char *file)

Create a document parsing the given file 📁

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default
file (const char *) — the name of the file to parse

Description

Creates a document by parsing the provided file as a YAML source. File girlies, this one's for you.

Return

The created document, or NULL on error.

`fy_document_build_from_fp`

struct fy_document *fy_document_build_from_fp(const struct fy_parse_cfg *cfg, FILE *fp)

Create a document parsing the given file pointer 🌈

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default
fp (FILE *) — the file pointer

Description

Creates a document by parsing the provided file pointer as a YAML source. Same energy as the file one, except you're already holding the FILE *.

Return

The created document, or NULL on error.

`fy_document_vbuildf`

struct fy_document *fy_document_vbuildf(const struct fy_parse_cfg *cfg, const char *fmt, va_list ap)

Create a document using the provided YAML via vprintf formatting 💅

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default
fmt (const char *) — the format string creating the YAML source to use
ap (va_list) — the va_list argument pointer

Description

Creates a document by parsing the provided string as a YAML source — except the string is created by applying vprintf formatting. Format string in, YAML document out, no cap.

Return

The created document, or NULL on error.

`fy_document_buildf`

struct fy_document *fy_document_buildf(const struct fy_parse_cfg *cfg, const char *fmt, ...)

Create a document using the provided YAML source via printf formatting ⭐

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default
fmt (const char *) — the format string creating the YAML source to use
ellipsis (ellipsis) — the printf arguments

Description

Creates a document by parsing the provided string as a YAML source, where the string is created by applying printf formatting. Yes it's the va_list one's louder sibling.

Return

The created document, or NULL on error.

`fy_flow_document_build_from_string`

struct fy_document *fy_flow_document_build_from_string(const struct fy_parse_cfg *cfg, const char *str, size_t len, size_t *consumed)

Create a document using the provided YAML source 🌸

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default
str (const char *) — the YAML source to use
len (size_t) — the length of the string (or -1 if 0 terminated)
consumed (size_t *) — a pointer to the consumed amount

Description

Creates a document by parsing the provided string as a YAML source.

The document is a flow document, i.e. it does not contain any block content and is usually laid out in a single line.

Example of flow documents

plain-scalar “double-quoted-scalar” ‘single-quoted-scalar’ { foo: bar } [ 0, 1, 2 ]

A flow document matters because parsing stops at the end of it, which means you can drop one inside other non-yaml content. That's the whole point, iykyk 🫶

Return

The created document, or NULL on error.

`fy_block_document_build_from_string`

struct fy_document *fy_block_document_build_from_string(const struct fy_parse_cfg *cfg, const char *str, size_t len, size_t *consumed)

Create a document using the provided YAML source 🦋

Parameters

cfg (const struct fy_parse_cfg *) — the parse configuration to use, or NULL for the default
str (const char *) — the YAML source to use
len (size_t) — the length of the string (or -1 if 0 terminated)
consumed (size_t *) — a pointer to the consumed amount

Description

Creates a document by parsing the provided string as a YAML source.

The document is a block document, and it terminates when indentation appears to do so. Indentation is basically the vibe check here 💀

Example of block documents:

   this-is-yaml
     foo: bar    <- starts here
     baz: [1, 2]
   this-is-yaml-no-more

Return

The created document, or NULL on error.

`fy_document_root`

struct fy_node *fy_document_root(struct fy_document *fyd)

Return the root node of the document 👑

Parameters

fyd (struct fy_document *) — the document

Description

Returns the root of the document. If the document is empty, NULL will be returned instead. Empty document, no root, no main character — tragic but correct.

Return

The root of the document, or NULL if the document is empty.

`fy_document_set_root`

int fy_document_set_root(struct fy_document *fyd, struct fy_node *fyn)

Set the root of the document 🎀

Parameters

fyd (struct fy_document *) — the document
fyn (struct fy_node *) — the new root of the document

Description

Sets the root of a document. If the document wasn't empty, the old root will be freed — so don't come crying to me holding a stale pointer, bestie 😭 If fyn is NULL, then the document is set to empty.

Return

0 on success, -1 on error.

`fy_node_get_type`

enum fy_node_type fy_node_get_type(struct fy_node *fyn)

Get the node type 🔥

Parameters

fyn (struct fy_node *) — the node

Description

Retrieves the node type. It is one of FYNT_SCALAR, FYNT_SEQUENCE or FYNT_MAPPING. And a fun little detail: a NULL node argument is a FYNT_SCALAR. Yes really, NULL counts as a scalar. That's the rule 💅

Return

The node type.

💅 `fy_node_get_style`

enum fy_node_style fy_node_get_style(struct fy_node *fyn);

Bestie, this one just tells you how a node likes to be rendered ✨ — like, what's its whole aesthetic.

Parameters

fyn (struct fy_node *) — the node in question 🎀

Description

Gets the node rendering style. And okay, plot twist: if the node is NULL then the style comes back as FYNS_PLAIN. So even a nothing node has a vibe, iconic.

Return

The node style 👑

🦋 `fy_node_set_style`

enum fy_node_style fy_node_set_style(struct fy_node *fyn, enum fy_node_style style);

Makeover time — you're requesting a new look for a node 💅.

Parameters

fyn (struct fy_node *) — the node
style (enum fy_node_style) — the requested node rendering style

Description

Tries to set the node rendering style. Notice the "tries" — because if the style is illegal for that node (classic example: you literally can't set an arbitrary scalar that contains zeroes to plain), then whatever style actually got set is what comes back at you. No cap, the function tells you the truth 🙈.

Return

The final node style — as in, the one that actually stuck 🔥

🧚 `fy_node_get_start_token`

struct fy_token *fy_node_get_start_token(struct fy_node *fyn);

Grabs the node's start token, like the opening credits of the node's whole era ⭐.

Parameters

fyn (struct fy_node *) — the node

Description

Retrieves the node start token. And for scalars? This is the exact same thing as the end token. Same token, different nickname, iykyk.

Return

The node start token 💖

🎀 `fy_node_get_end_token`

struct fy_token *fy_node_get_end_token(struct fy_node *fyn);

The mirror image bestie — the end token 🌸.

Parameters

fyn (struct fy_node *) — the node

Description

Retrieves the node end token. For scalars, this is the same as the start token. (Yeah, we just said that, it's a vibe both ways.)

Return

The node end token 💜

✨ `fy_node_is_scalar`

bool fy_node_is_scalar(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node

Description

A little convenience method that checks whether a node is a scalar. That's it, that's the whole thing 🫶.

Return

true if the node is a scalar, false otherwise

🌈 `fy_node_is_sequence`

bool fy_node_is_sequence(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node

Description

Convenience method for checking whether a node is a sequence. Short, sweet, slays.

Return

true if the node is a sequence, false otherwise

💫 `fy_node_is_mapping`

bool fy_node_is_mapping(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node

Description

Convenience method for checking whether a node is a mapping. Okay so it's giving "one job, does it well" 💅.

Return

true if the node is a mapping, false otherwise

🔗 `fy_node_is_alias`

bool fy_node_is_alias(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node

Description

Convenience method for checking whether a node is an alias. (Aliases are lowkey the main characters of YAML, ngl.)

Return

true if the node is an alias, false otherwise

🫧 `fy_node_is_null`

bool fy_node_is_null(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node

Description

Convenience method for checking whether a node is a NULL scalar. And here's the cute little gotcha: a NULL node argument returns true… yes, really 🙈.

Return

true if the node is a NULL scalar, false otherwise

🧷 `fy_node_is_attached`

bool fy_node_is_attached(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node

Description

Checks whether a node is attached in a document structure. Real talk: an attached node may not be freed before being detached, so don't even try it 💀. And yes, there is no method that explicitly detaches a node — that's handled internally by the sequence and mapping removal methods, so it's giving "the library handles it, stay out of it" energy.

Return

true if the node is attached, false otherwise

🏷️ `fy_node_get_tag_token`

struct fy_token *fy_node_get_tag_token(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node which has the tag token to be returned

Description

Gets the tag token of a node, if it exists. If it doesn't exist, no drama, you get nothing back.

Return

The tag token of the given node, or NULL if the tag does not exist 🍓

🌸 `fy_node_get_scalar_token`

struct fy_token *fy_node_get_scalar_token(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node which has the scalar token to be returned

Description

Gets the scalar token of a node, if it exists and the node is a valid scalar node. And heads up bestie: aliases are scalars, so if you call this on an alias node, what you get back shall be an alias token 👀. Plot twist handled.

Return

The scalar token of the given node, or NULL if the node is not a scalar 💜

🌀 `fy_node_resolve_alias`

struct fy_node *fy_node_resolve_alias(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the alias node to be resolved

Description

Resolves an alias node, following any subsequent aliases until a non-alias node has been found. Basically chasing the chain until someone's actually real 🦋. This call performs cycle detection and excessive redirections checks, so it's totally safe to call in any context. No infinite loop jump scare, we promise.

Return

The resolved alias node, or NULL if either fyn is not an alias, or resolution fails due to a graph cycle 💀

🪞 `fy_node_dereference`

struct fy_node *fy_node_dereference(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the alias node to be dereferenced

Description

Dereferences an alias node. And this is different from resolution, bestie — this one only performs a single alias follow call, and it will fail if the input is not an alias. One hop only, no chain-chasing 🌈. It also performs cycle detection and excessive redirections checks, so it's safe to call in any context.

Return

The dereferenced alias node, or NULL if either fyn is not an alias, or resolution fails due to a graph cycle

🗑️ `fy_node_free`

int fy_node_free(struct fy_node *fyn);

Parameters

fyn (struct fy_node *) — the node to free

Description

Recursively frees the given node, releasing the memory it uses, removing any anchors on the document it contains, and releasing references on the tokens it contains. Full cleanup, no crumbs 💅.

But — this method will return an error if the node is attached, or if it's not NULL and it isn't a member of a document. So, like, don't free attached nodes, we literally warned you 🙈.

Return

0 on success, -1 on error

🌱 `fy_node_build_from_string`

struct fy_node *fy_node_build_from_string(struct fy_document *fyd, const char *str, size_t len);

Create a node using the provided YAML source ✨.

Parameters

fyd (struct fy_document *) — the document
str (const char *) — the YAML source to use
len (size_t) — the length of the string (or -1 if '0' terminated)

Description

Creates a node by parsing the provided string as a YAML source. The node created will be associated with the provided document 🎀.

Return

The created node, or NULL on error

🧵 `fy_node_build_from_malloc_string`

struct fy_node *fy_node_build_from_malloc_string(struct fy_document *fyd, char *str, size_t len);

Same energy as above, except the string came from malloc and the library takes ownership of it 💅.

Parameters

fyd (struct fy_document *) — the document
str (char *) — the YAML source to use
len (size_t) — the length of the string (or -1 if '0' terminated)

Description

Creates a node by parsing the provided string as a YAML source, and the node created will be associated with the provided document. Key detail: the string is expected to have been allocated by malloc(3), and when the document is destroyed it will be automatically freed 🫶. So don't go freeing it yourself afterward, that's double-free territory, bestie.

Return

The created node, or NULL on error

📁 `fy_node_build_from_file`

struct fy_node *fy_node_build_from_file(struct fy_document *fyd, const char *file);

Parameters

fyd (struct fy_document *) — the document
file (const char *) — the name of the file to parse

Description

Creates a node by parsing the provided file as a YAML source. The node created will be associated with the provided document 🌸.

Return

The created node, or NULL on error

🖨️ `fy_node_build_from_fp`

struct fy_node *fy_node_build_from_fp(struct fy_document *fyd, FILE *fp);

Parameters

fyd (struct fy_document *) — the document
fp (FILE *) — the file pointer

Description

Creates a node by parsing the provided file pointer as a YAML source. The node created will be associated with the provided document ⭐.

Return

The created node, or NULL on error

🧪 `fy_node_vbuildf`

struct fy_node *fy_node_vbuildf(struct fy_document *fyd, const char *fmt, va_list ap);

Create a node using the provided YAML source via vprintf formatting 💜.

Parameters

fyd (struct fy_document *) — the document
fmt (const char *) — the format string creating the YAML source to use
ap (va_list) — the va_list argument pointer

Description

Creates a node by parsing the resulting string as a YAML source. The string is created by applying vprintf formatting. Format-string girlies, this one's for you 🎀.

Return

The created node, or NULL on error

🎨 `fy_node_buildf`

struct fy_node *fy_node_buildf(struct fy_document *fyd, const char *fmt, ...);

Create a node using the provided YAML source via printf formatting ✨.

Parameters

fyd (struct fy_document *) — the document
fmt (const char *) — the format string creating the YAML source to use
ellipsis (ellipsis) — the printf arguments

Description

Creates a node by parsing the resulting string as a YAML source. The string is created by applying printf formatting — the comfy varargs version, no va_list required 🫶.

Return

The created node, or NULL on error

🗺️ `fy_node_by_path`

struct fy_node *fy_node_by_path(struct fy_node *fyn, const char *path, size_t len, enum fy_node_walk_flags flags);

Retrieve a node using the provided path spec 🔍.

Parameters

fyn (struct fy_node *) — the node to use as start of the traversal operation
path (const char *) — the path spec to use in the traversal operation
len (size_t) — the length of the path (or -1 if '0' terminated)
flags (enum fy_node_walk_flags) — the extra path walk flags

No return value documented in this part — the page continues from here, so stay tuned bestie 🌈

Okay so this method pulls up a node relative to the one you hand it, using the path spec you give it. 💅

Path specs are just keys stitched together with slashes /. Keys are either regular YAML expressions in flow format (for walking mappings) or indexes in brackets (for walking sequences). A path spec can start with /, and that leading slash is silently ignored. ✨

A few examples make it click:

fyn = { foo: bar } - fy_node_by_path(fyn, "/foo") -> bar
fyn = [ foo, bar ] - fy_node_by_path(fyn, "1") -> bar
fyn = { { foo: bar }: baz } - fy_node_by_path(fyn, "{foo: bar}") -> baz
fyn = [ foo, { bar: baz } } - fy_node_by_path(fyn, "1/bar") -> baz

Heads up: the special characters /{}[] are not escaped in plain style, so you will not be able to use them as path traversal keys. In that case you can easily use either the single or double quoted forms:

fyn = { foo/bar: baz } - fy_node_by_path(fyn, "'foo/bar'") -> baz

Return: The retrieved node, or NULL if it’s not possible to be found. 😭

✨ `fy_node_get_path` ✨

char *fy_node_get_path(struct fy_node *fyn)

Get the path of this node

Parameters:

fyn (*struct fy_node**) — The node

Description: Grab the given node’s path address relative to the document root, bestie. This address is dynamically allocated, so free it when you’re done with it. 🫶

Return: The node’s address, or NULL if fyn is the root.

✨ `fy_node_get_parent` ✨

struct fy_node *fy_node_get_parent(struct fy_node *fyn)

Get the parent node of a node

Parameters:

fyn (*struct fy_node**) — The node

Description: Get the parent node of a node. The parent of a document’s root is NULL, and so is the parent of the root of a key node in a mapping. This is because the nodes of a key may not be addressed using a path expression. 💀

Return: The node’s parent, or NULL if fyn is the root, or the root of a key mapping.

✨ `fy_node_get_document_parent` ✨

struct fy_node *fy_node_get_document_parent(struct fy_node *fyn)

Get the document parent node of a node

Parameters:

fyn (*struct fy_node**) — The node

Description: Get the document parent node of a node. The document parent differs from the regular parent in that a key’s root node of a mapping is not NULL; instead it points to the actual node parent. 🌈

Return: The node’s document parent, or NULL if fyn is the root.

✨ `fy_node_get_parent_address` ✨

char *fy_node_get_parent_address(struct fy_node *fyn)

Get the path address of this node’s parent

Parameters:

fyn (*struct fy_node**) — The node

Description: Retrieve the given node’s parent path address. The address is dynamically allocated, so free it when you’re done with it. 🎀

Return: The parent’s address, or NULL if fyn is the root.

✨ `fy_node_get_path_relative_to` ✨

char *fy_node_get_path_relative_to(struct fy_node *fyn_parent, struct fy_node *fyn)

Get a path address of a node relative to one of its parents

Parameters:

fyn_parent (*struct fy_node**) — The node parent/grandparent…
fyn (*struct fy_node**) — The node

Description: Retrieve the given node’s path address relative to an arbitrary parent in the tree. The address is dynamically allocated, so free it when you’re done with it. 💖

Return: The relative address from the parent to the node.

✨ `fy_node_get_short_path` ✨

char *fy_node_get_short_path(struct fy_node *fyn)

Get a path address of a node in the shortest path possible

Parameters:

fyn (*struct fy_node**) — The node

Description: Retrieve the given node’s short path address relative to the closest anchor — either on this node or its parent. If no such parent is found, it returns the absolute path from the start of the document. 🦋

Example:

--- &foo
foo: &bar
    bar
baz

The short path of /foo is \*foo
The short path of /foo/bar is \*bar
The short path of /baz is \*foo/baz

The address is dynamically allocated, so free it when you’re done with it.

Return: The shortest path describing the node.

✨ `fy_node_get_reference` ✨

char *fy_node_get_reference(struct fy_node *fyn)

Get a textual reference to a node

Parameters:

fyn (*struct fy_node**) — The node

Description: Retrieve the given node’s textual reference. If the node contains an anchor, the expression that references the anchor will be returned; otherwise an absolute path reference relative to the root of the document will be returned. The address is dynamically allocated, so free it when you’re done with it. 🌸

Return: The node’s text reference.

✨ `fy_node_create_reference` ✨

struct fy_node *fy_node_create_reference(struct fy_node *fyn)

Create an alias reference node

Parameters:

fyn (*struct fy_node**) — The node

Description: Create an alias node reference. If the node contains an anchor, the expression that references the alias will use the anchor; otherwise an absolute path reference relative to the root of the document will be created. 👑

Return: An alias node referencing the argument node.

✨ `fy_node_get_relative_reference` ✨

char *fy_node_get_relative_reference(struct fy_node *fyn_base, struct fy_node *fyn)

Get a textual reference to a node relative to a base node.

Parameters:

fyn_base (*struct fy_node**) — The base node
fyn (*struct fy_node**) — The node

Description: Retrieve the given node’s textual reference as generated using another parent (or grandparent) as a base. If the node contains an anchor, the expression that references the anchor will be returned. If the base node contains an anchor, the reference will be relative to it; otherwise an absolute path reference will be returned. The address is dynamically allocated, so free it when you’re done with it. ⭐

Return: The node’s text reference.

✨ `fy_node_create_relative_reference` ✨

struct fy_node *fy_node_create_relative_reference(struct fy_node *fyn_base, struct fy_node *fyn)

Create an alias reference node

Parameters:

fyn_base (*struct fy_node**) — The base node
fyn (*struct fy_node**) — The node

Description: Create a relative alias node reference using another parent (or grandparent) as a base. If the node contains an anchor, the alias will reference the anchor. If the base node contains an anchor, the alias will be relative to it; otherwise an absolute path reference will be created. 🔥

Return: An alias node referencing the argument node relative to the base.

✨ `fy_node_create_scalar` ✨

struct fy_node *fy_node_create_scalar(struct fy_document *fyd, const char *data, size_t size)

Create a scalar node.

Parameters:

fyd (*struct fy_document**) — The document which the resulting node will be associated with
data (*const char**) — Pointer to the data area
size (*size_t**) — Size of the data area, or (size_t)-1 for '0' terminated data.

Description: Create a scalar node using the provided memory area as input. The input is expected to be regular utf8 encoded. It may contain escaped characters, in which case the style of the scalar will be set to double quoted. Note that the data are not copied — merely a reference is taken — so it must be available while the node is in use. 🙈

Return: The created node, or NULL on error.

✨ `fy_node_create_scalar_copy` ✨

struct fy_node *fy_node_create_scalar_copy(struct fy_document *fyd, const char *data, size_t size)

Create a scalar node copying the data.

Parameters:

fyd (*struct fy_document**) — The document which the resulting node will be associated with
data (*const char**) — Pointer to the data area
size (*size_t**) — Size of the data area, or (size_t)-1 for '0' terminated data.

Description: Create a scalar node using the provided memory area as input. The input is expected to be regular utf8 encoded. It may contain escaped characters, in which case the style of the scalar will be set to double quoted. A copy of the data will be made, so it is safe to free the data after the call. 💜

Return: The created node, or NULL on error.

✨ `fy_node_create_vscalarf` ✨

struct fy_node *fy_node_create_vscalarf(struct fy_document *fyd, const char *fmt, va_list ap)

vprintf interface for creating scalars

Parameters:

fyd (*struct fy_document**) — The document which the resulting node will be associated with
fmt (*const char**) — The printf based format string
ap (*va_list**) — The va_list containing the arguments

Description: Create a scalar node using a vprintf interface. The input is expected to be regular utf8 encoded. It may contain escaped characters, in which case the style of the scalar will be set to double quoted. 🧚

Return: The created node, or NULL on error.

✨ `fy_node_create_scalarf` ✨

struct fy_node *fy_node_create_scalarf(struct fy_document *fyd, const char *fmt, ...)

printf interface for creating scalars

Parameters:

fyd (*struct fy_document**) — The document which the resulting node will be associated with
fmt (*const char**) — The printf based format string
ellipsis (*ellipsis**) — The arguments

Description: Create a scalar node using a printf interface. The input is expected to be regular utf8 encoded. It may contain escaped characters, in which case the style of the scalar will be set to double quoted. 🍓

Return: The created node, or NULL on error.

✨ `fy_node_create_sequence` ✨

struct fy_node *fy_node_create_sequence(struct fy_document *fyd)

Create an empty sequence node.

Parameters:

fyd (*struct fy_document**) — The document which the resulting node will be associated with

Description: Create an empty sequence node associated with the given document.

Return: The created node, or NULL on error.

✨ `fy_node_create_mapping` ✨

struct fy_node *fy_node_create_mapping(struct fy_document *fyd)

Create an empty mapping node.

Parameters:

fyd (*struct fy_document**) — The document which the resulting node will be associated with

Description: Create an empty mapping node associated with the given document.

🌸 Return 🌸

The created node, or NULL on error. That's the vibe check for the previous function — success hands you a node, failure hands you NULL, periodt.

💖 `fy_node_set_tag` 💖

int fy_node_set_tag(struct fy_node *fyn, const char *data, size_t len)

Okay so bestie, this one manually sets the tag of a node.

Parameters

fyn (struct fy_node*) — the node to set it’s tag. Yes, that apostrophe is in the original, we’re keeping the energy.
data (const char*) — pointer to the tag data.
len (size_t) — size of the tag data, or (size_t)-1 for '0' terminated.

Description

Manually set the tag of a node. The tag must be a valid one for the document the node belongs to.

⚠️ Note that the data are not copied — merely a reference is taken, so it must be available while the node is in use. No cap, that buffer has to stay alive as long as the node does.

If the node already contains a tag it will be overwriten.

Return

0 on success, -1 on error.

🎀 `fy_node_remove_tag` 🎀

int fy_node_remove_tag(struct fy_node *fyn)

Removes the tag from a node. Poof, gone, no tag era.

Parameters

fyn (struct fy_node*) — the node to remove it’s tag.

Description

Remove the tag of a node.

Return

0 on success, -1 on error.

🦋 `fy_node_get_tag` 🦋

const char *fy_node_get_tag(struct fy_node *fyn, size_t *lenp)

Gets you a pointer to the tag text, plus the length. Lowkey important: this text is not NULL terminated.

Parameters

fyn (struct fy_node*) — the node.
lenp (size_t*) — pointer to a variable that will hold the returned length.

Description

This method will return a pointer to the text of a tag along with the length of it. Note that this text is not NULL terminated.

Return

A pointer to the tag of the node, while lenp will be assigned the length of said tag. A NULL will be returned in case of an error.

🌸 `fy_node_get_tag0` 🌸

const char *fy_node_get_tag0(struct fy_node *fyn)

Same tag-getting mission, but this one is NULL terminated. Very demure, very convenient.

Parameters

fyn (struct fy_node*) — the node.

Description

This method will return a pointer to the text of a tag, which will be NULL terminated.

Return

A pointer to the null terminated tag of the node. A NULL will be returned in case of an error.

✨ `fy_node_get_tag_length` ✨

size_t fy_node_get_tag_length(struct fy_node *fyn)

Just the length of the node’s tag. If there’s no tag, it’s giving 0.

Parameters

fyn (struct fy_node*) — the tagged node.

Description

This method will return the size of the tag of the node. If the node is not tagged it will return 0.

Return

The size of the tag, or 0 if node is not tagged.

💜 `fy_node_get_scalar` 💜

const char *fy_node_get_scalar(struct fy_node *fyn, size_t *lenp)

Gets the scalar content of a node, with length. Heads up bestie: this pointer is not NULL terminated.

Parameters

fyn (struct fy_node*) — the scalar node.
lenp (size_t*) — pointer to a variable that will hold the returned length.

Description

This method will return a pointer to the text of the scalar content of a node along with the length of it. Note that this pointer is not NULL terminated.

Return

A pointer to the scalar content of the node, while lenp will be assigned the length of said content. A NULL will be returned in case of an error, i.e. the node is not a scalar.

🍓 `fy_node_get_scalar0` 🍓

const char *fy_node_get_scalar0(struct fy_node *fyn)

Same scalar energy, but returns a NULL terminated string. Plot twist: it allocates memory to make that happen.

Parameters

fyn (struct fy_node*) — the scalar node.

Description

This method will return a pointer to the text of the scalar content of a node as a null terminated string. Note that this call will allocate memory to hold the null terminated string so if possible use fy_node_get_scalar().

Return

A pointer to the scalar content of the node or NULL is returned in case of an error.

🧚 `fy_node_get_scalar_length` 🧚

size_t fy_node_get_scalar_length(struct fy_node *fyn)

The size of the scalar content. Not a scalar? Then it’s 0, no drama.

Parameters

fyn (struct fy_node*) — the scalar node.

Description

This method will return the size of the scalar content of the node. If the node is not a scalar it will return 0.

Return

The size of the scalar content, or 0 if node is not scalar.

🌈 `fy_node_get_scalar_utf8_length` 🌈

size_t fy_node_get_scalar_utf8_length(struct fy_node *fyn)

Same size check, but counted in utf8 characters. If it’s not a scalar, you get 0.

Parameters

fyn (struct fy_node*) — the scalar node.

Description

This method will return the size of the scalar content of the node in utf8 characters. If the node is not a scalar it will return 0.

Return

The size of the scalar content in utf8 characters, or 0 if node is not scalar.

🫶 `fy_node_sequence_iterate` 🫶

struct fy_node *fy_node_sequence_iterate(struct fy_node *fyn, void **prevp)

Iterates over all the item nodes in a sequence node. Start of the iteration is signalled by a NULL in *prevp.

Parameters

fyn (struct fy_node*) — the sequence node.
prevp (void**) — the previous sequence iterator.

Description

This method iterates over all the item nodes in the sequence node. The start of the iteration is signalled by a NULL in *prevp.

Return

The next node in sequence or NULL at the end of the sequence.

🔥 `fy_node_sequence_reverse_iterate` 🔥

struct fy_node *fy_node_sequence_reverse_iterate(struct fy_node *fyn, void **prevp)

Same as above but backwards. Main character energy: entering the sequence from the end.

Parameters

fyn (struct fy_node*) — the sequence node.
prevp (void**) — the previous sequence iterator.

Description

This method iterates in reverse over all the item nodes in the sequence node. The start of the iteration is signalled by a NULL in *prevp.

Return

The next node in reverse sequence or NULL at the end of the sequence.

👑 `fy_node_sequence_item_count` 👑

int fy_node_sequence_item_count(struct fy_node *fyn)

Gets the item count of the sequence. If something’s wrong, you get -1.

Parameters

fyn (struct fy_node*) — the sequence node.

Description

Get the item count of the sequence.

Return

The count of items in the sequence or -1 in case of an error.

💅 `fy_node_sequence_is_empty` 💅

bool fy_node_sequence_is_empty(struct fy_node *fyn)

Checks whether the sequence contains items. That’s what the description says, bestie.

Parameters

fyn (struct fy_node*) — the sequence node.

Description

Check whether the sequence contains items.

Return

true if the node is a sequence containing items, false otherwise.

🎀 `fy_node_sequence_get_by_index` 🎀

struct fy_node *fy_node_sequence_get_by_index(struct fy_node *fyn, int index)

Grabs a sequence item by index. Positive or zero counts from the start, negative counts from the end — so -1 is literally the last item.

Parameters

fyn (struct fy_node*) — the sequence node.
index (int) — the index of the node to retrieve.
- >= 0 counting from the start
- < 0 counting from the end

Description

Retrieve a node in the sequence using it’s index. If index is positive or zero the count is from the start of the sequence, while if negative from the end. I.e. -1 returns the last item in the sequence.

Return

The node at the specified index or NULL if no such item exist.

🌟 `fy_node_sequence_append` 🌟

int fy_node_sequence_append(struct fy_node *fyn_seq, struct fy_node *fyn)

Appends a node item to a sequence. Adding to the end, very last-slot-of-the-group-chat energy.

Parameters

fyn_seq (struct fy_node*) — the sequence node.
fyn (struct fy_node*) — the node item to append.

Description

Append a node item to a sequence.

Return

0 on success, -1 on error.

🦋 `fy_node_sequence_prepend` 🦋

int fy_node_sequence_prepend(struct fy_node *fyn_seq, struct fy_node *fyn)

The original one-liner says “Append a node item to a sequence” — yes, really — but the description is prepend. We’re keeping both because fidelity is the moment.

Parameters

fyn_seq (struct fy_node*) — the sequence node.
fyn (struct fy_node*) — the node item to prepend.

Description

Prepend a node item to a sequence.

Return

0 on success, -1 on error.

💖 `fy_node_sequence_insert_before` 💖

int fy_node_sequence_insert_before(struct fy_node *fyn_seq, struct fy_node *fyn_mark, struct fy_node *fyn)

Inserts a node item before another one in the sequence. It’s giving “excuse me, I’m cutting the line.”

Parameters

fyn_seq (struct fy_node*) — the sequence node.
fyn_mark (struct fy_node*) — the node item which the node will be inserted before.
fyn (struct fy_node*) — the node item to insert in the sequence.

Description

Insert a node item before another in the sequence.

Return

0 on success, -1 on error.

💜 `fy_node_sequence_insert_after` 💜

int fy_node_sequence_insert_after(struct fy_node *fyn_seq, struct fy_node *fyn_mark, struct fy_node *fyn)

Same insert situation, but after the mark instead of before.

Parameters

fyn_seq (struct fy_node*) — the sequence node.
fyn_mark (struct fy_node*) — the node item which the node will be inserted after.
fyn (struct fy_node*) — the node item to insert in the sequence.

Description

Insert a node item after another in the sequence.

Return

0 on success, -1 on error.

🍓 `fy_node_sequence_remove` 🍓

struct fy_node *fy_node_sequence_remove(struct fy_node *fyn_seq, struct fy_node *fyn)

Removes an item from a sequence and returns it. You get the node back — take it, it’s yours.

Parameters

fyn_seq (struct fy_node*) — the sequence node.
fyn (struct fy_node*) — the node item to remove from the sequence.

Description

Remove a node item from a sequence and return it.

Return

The removed node item fyn, or NULL in case of an error.

🌈 typedef `fy_node_sequence_sort_fn` 🌈

int fy_node_sequence_sort_fn(struct fy_node *fyn_a, struct fy_node *fyn_b, void *arg)

The comparison method used when sorting a sequence. It returns less-than/equal/greater-than vibes.

Parameters

fyn_a (struct fy_node*) — the first node used in the comparison.
fyn_b (struct fy_node*) — the second node used in the comparison.
arg (void*) — the opaque user provided pointer to the sort operation.

Return

< 0 if fyn_a is less than fyn_b
0 if fyn_a is equal to fyn_b
> 0 if fyn_a is greater than fyn_b

✨ `fy_node_sequence_sort` ✨

int fy_node_sequence_sort(struct fy_node *fyn_seq, fy_node_sequence_sort_fn cmp, void *arg)

Sorts a sequence’s items using your comparison method. Put it in order, bestie.

Parameters

fyn_seq (struct fy_node*) — the sequence node to sort.
cmp (fy_node_sequence_sort_fn) — the comparison method.
arg (void*) — an opaque user pointer for the comparison method.

Description

Sort the items of a sequence node using the given comparison method.

Return

0 on success, -1 on error.

🧚 `fy_node_mapping_iterate` 🧚

struct fy_node_pair *fy_node_mapping_iterate(struct fy_node *fyn, void **prevp)

Iterate over a mapping node. That’s the brief — this part of the page stops right here, so no params are listed yet.

fyn (struct fy_node*) — the mapping node 💅
prevp (void**) — the previous sequence iterator (yeah, it literally says sequence on a mapping function — not me, that's the source 😭)

Description

okay so this one iterates over, like, all the node pairs in the mapping node. The start of the iteration is signalled by a NULL in *prevp — that's your little green flag to begin ✨

note that while a mapping is an unordered collection of key/values, the order of which they are created is important for presentation purposes. periodt.

Return

The next node pair in the mapping, or NULL at the end of the mapping. iykyk 🎀

`fy_node_mapping_reverse_iterate`

struct fy_node_pair *fy_node_mapping_reverse_iterate(struct fy_node *fyn, void **prevp)

Iterate over a mapping node in reverse — walking backwards like it's a comeback era 💀

Parameters

fyn (struct fy_node*) — the mapping node
prevp (void**) — the previous sequence iterator (again with the "sequence", we stay unbothered 🫶)

Description

This method iterates in reverse over all the node pairs in the mapping node. The start of the iteration is signalled by a NULL in *prevp.

same energy as before: while a mapping is an unordered collection of key/values, the order of which they are created is important for presentation purposes. no cap.

Return

The next node pair in reverse sequence in the mapping, or NULL at the end of the mapping. 💖

`fy_node_mapping_item_count`

int fy_node_mapping_item_count(struct fy_node *fyn)

Return the node pair count of the mapping — literally just counting, bestie 🔢

Parameters

fyn (struct fy_node*) — the mapping node

Description

Get the count of the node pairs in the mapping.

Return

The count of node pairs in the mapping, or -1 in case of an error. (yes, -1 is the "something went wrong" vibe check 🚩)

`fy_node_mapping_is_empty`

bool fy_node_mapping_is_empty(struct fy_node *fyn)

Check whether the mapping is empty — the "is this group chat dead" check 🙈

Parameters

fyn (struct fy_node*) — the mapping node

Description

Check whether the mapping contains any node pairs.

Return

true if the node is a mapping containing node pairs, false otherwise.

`fy_node_mapping_get_by_index`

struct fy_node_pair *fy_node_mapping_get_by_index(struct fy_node *fyn, int index)

Return a node pair by index — pick your fave by number 🎯

Parameters

fyn (struct fy_node*) — the mapping node
index (int) — the index of the node pair to retrieve
- >= 0 counting from the start
- < 0 counting from the end

Description

Retrieve a node pair in the mapping using its index. If index is positive or zero the count is from the start of the sequence, while if negative from the end. I.e. -1 returns the last node pair in the mapping. main character behaviour, honestly 👑

Return

The node pair at the specified index, or NULL if no such item exist.

`fy_node_mapping_lookup_pair_by_string`

struct fy_node_pair *fy_node_mapping_lookup_pair_by_string(struct fy_node *fyn, const char *key, size_t len)

Lookup a node pair in mapping by string 🔍

Parameters

fyn (struct fy_node*) — the mapping node
key (const char*) — the YAML source to use as key
len (size_t) — the length of the key (or -1 if '0' terminated)

Description

This method will return the node pair that contains the same key from the YAML node created from the key argument. The comparison of the node is using fy_node_compare().

Return

The value matching the given key, or NULL if not found. 💜

`fy_node_mapping_lookup_by_string`

struct fy_node *fy_node_mapping_lookup_by_string(struct fy_node *fyn, const char *key, size_t len)

Lookup a node value in mapping by string — yes, the name says "lookup" and the summary says "value", we're just built different 🦋

Parameters

fyn (struct fy_node*) — the mapping node
key (const char*) — the YAML source to use as key
len (size_t) — the length of the key (or -1 if '0' terminated)

Description

This method will return the value of node pair that contains the same key from the YAML node created from the key argument. The comparison of the node is using fy_node_compare().

Return

The value matching the given key, or NULL if not found.

`fy_node_mapping_lookup_value_by_string`

struct fy_node *fy_node_mapping_lookup_value_by_string(struct fy_node *fyn, const char *key, size_t len)

Lookup a node value in mapping by string — the explicit version, for the girlies who like to be very clear about their intentions 💅

Parameters

fyn (struct fy_node*) — the mapping node
key (const char*) — the YAML source to use as key
len (size_t) — the length of the key (or -1 if '0' terminated)

Description

This method will return the value of node pair that contains the same key from the YAML node created from the key argument. The comparison of the node is using fy_node_compare().

It is synonymous with fy_node_mapping_lookup_by_string(). literally the same girl, different name ✨

Return

The value matching the given key, or NULL if not found.

`fy_node_mapping_lookup_key_by_string`

struct fy_node *fy_node_mapping_lookup_key_by_string(struct fy_node *fyn, const char *key, size_t len)

Lookup a node key in mapping by string — the flip side, we want the key itself this time 🔑

Parameters

fyn (struct fy_node*) — the mapping node
key (const char*) — the YAML source to use as key
len (size_t) — the length of the key (or -1 if '0' terminated)

Description

This method will return the key of node pair that contains the same key from the YAML node created from the key argument. The comparison of the node is using fy_node_compare().

Return

The key matching the given key, or NULL if not found.

`fy_node_mapping_lookup_pair_by_simple_key`

struct fy_node_pair *fy_node_mapping_lookup_pair_by_simple_key(struct fy_node *fyn, const char *key, size_t len)

Lookup a node pair in mapping by simple string — no YAML parsing arc, we're keeping it simple 🧚

Parameters

fyn (struct fy_node*) — the mapping node
key (const char*) — the string to use as key
len (size_t) — the length of the key (or -1 if '0' terminated)

Description

This method will return the node pair that contains the same key from the YAML node created from the key argument. The comparison of the node is using by comparing the strings for identity.

Return

The node pair matching the given key, or NULL if not found. 🌸

`fy_node_mapping_lookup_value_by_simple_key`

struct fy_node *fy_node_mapping_lookup_value_by_simple_key(struct fy_node *fyn, const char *key, size_t len)

Lookup a node value in mapping by simple string — same simplicity, but gimme the value 🎀

Parameters

fyn (struct fy_node*) — the mapping node
key (const char*) — the string to use as key
len (size_t) — the length of the key (or -1 if '0' terminated)

Description

This method will return the value of node pair that contains the same key from the YAML node created from the key argument. The comparison of the node is using by comparing the strings for identity.

Return

The value matching the given key, or NULL if not found.

`fy_node_mapping_lookup_pair_by_null_key`

struct fy_node_pair *fy_node_mapping_lookup_pair_by_null_key(struct fy_node *fyn)

Lookup a node pair in mapping that has a NULL key — the chaotic one 🫠

Parameters

fyn (struct fy_node*) — the mapping node

Description

This method will return the node pair that has a NULL key. Note this method is not using the mapping accelerator and arguably NULL keys should not exist. Alas…

"Alas…" is doing so much emotional labour in that sentence and honestly? felt 😭

Return

The node pair with a NULL key, NULL otherwise.

`fy_node_mapping_lookup_value_by_null_key`

struct fy_node *fy_node_mapping_lookup_value_by_null_key(struct fy_node *fyn)

Lookup a node value with a NULL key. bestie we're in the void now 💀

Parameters

fyn (struct fy_node*) — the mapping node

Description

Return the value of a node pair that has a NULL key.

Return

The value matching the null key, NULL otherwise. Note that the value may be NULL too, but for that pathological case use the node pair method instead. 🙈

`fy_node_mapping_lookup_scalar_by_simple_key`

const char *fy_node_mapping_lookup_scalar_by_simple_key(struct fy_node *fyn, size_t *lenp, const char *key, size_t keylen)

Lookup a scalar in mapping by simple string — we're going straight for the raw scalar contents now ✨

Parameters

fyn (struct fy_node*) — the mapping node
lenp (size_t*) — pointer to a variable that will hold the returned length
key (const char*) — the string to use as key
keylen (size_t) — the length of the key (or -1 if '0' terminated)

Description

This method will return the scalar contents that contains the same key from the YAML node created from the key argument. The comparison of the node is using by comparing the strings for identity.

Return

The scalar contents matching the given key, or NULL if not found. 💜

`fy_node_mapping_lookup_scalar0_by_simple_key`

const char *fy_node_mapping_lookup_scalar0_by_simple_key(struct fy_node *fyn, const char *key, size_t keylen)

Lookup a scalar in mapping by simple string returning a '0' terminated scalar — the one with the NUL happily attached 🌈

Parameters

fyn (struct fy_node*) — the mapping node
key (const char*) — the string to use as key
keylen (size_t) — the length of the key (or -1 if '0' terminated)

Description

This method will return the NUL terminated scalar contents that contains the same key from the YAML node created from the key argument. The comparison of the node is using by comparing the strings for identity.

Return

The NUL terminated scalar contents matching the given key, or NULL if not found. 🦋

`fy_node_mapping_lookup_pair`

struct fy_node_pair *fy_node_mapping_lookup_pair(struct fy_node *fyn, struct fy_node *fyn_key)

Lookup a node pair matching the provided key — you bring your own node as the key, we love a self-sufficient queen 👑

Parameters

fyn (struct fy_node*) — the mapping node
fyn_key (struct fy_node*) — the node to use as key

Description

This method will return the node pair that matches the provided fyn_key.

Return

The node pair matching the given key, or NULL if not found.

`fy_node_mapping_lookup_value_by_key`

struct fy_node *fy_node_mapping_lookup_value_by_key(struct fy_node *fyn, struct fy_node *fyn_key)

Lookup a node pair's value matching the provided key — node-in, value-out, the classic trade 🔥

Parameters

fyn (struct fy_node*) — the mapping node
fyn_key (struct fy_node*) — the node to use as key

Description

This method will return the node pair that matches the provided fyn_key. The key may be collection and a content match check is performed recursively in order to find the right key. so it goes deep, recursively, until it finds its match — obsessed 💅

Return: The node value matching the given key, or NULL if not found. 🫶

🌸 `fy_node_mapping_lookup_key_by_key` 🌸

struct fy_node *fy_node_mapping_lookup_key_by_key(struct fy_node *fyn, struct fy_node *fyn_key)

Parameters

fyn (struct fy_node*) — The mapping node
fyn_key (struct fy_node*) — The node to use as key

Description Okay so this one hunts down the node pair that matches the fyn_key you hand it. The key can be a collection, and a content-match check gets performed recursively to find the right key. Recursive key matching is giving main character energy fr.

Return The node key matching the given key, or NULL if not found.

⭐ `fy_node_mapping_get_pair_index` ⭐

int fy_node_mapping_get_pair_index(struct fy_node *fyn, const struct fy_node_pair *fynp)

Parameters

fyn (struct fy_node*) — The mapping node
fynp (const struct fy_node_pair*) — The node pair

Description Returns the node pair index in the mapping for the node pair you passed in. If it can’t find it, you get -1, no cap. 💅

Return The index of the node pair in the mapping or -1 in case of an error.

🎀 `fy_node_pair_key` 🎀

struct fy_node *fy_node_pair_key(struct fy_node_pair *fynp)

Parameters

fynp (struct fy_node_pair*) — The node pair

Description Grabs the node pair’s key. Heads up bestie: this can be NULL, and it also returns NULL when the node pair argument itself is NULL, so protect against that case. 🫶

Return The node pair key

🦋 `fy_node_pair_value` 🦋

struct fy_node *fy_node_pair_value(struct fy_node_pair *fynp)

Parameters

fynp (struct fy_node_pair*) — The node pair

Description Grabs the node pair’s value. Same warning as its key twin: this may be NULL, and it’s also returned when the node pair argument is NULL, so please protect against that case.

Return The node pair value

🔥 `fy_node_pair_set_key` 🔥

int fy_node_pair_set_key(struct fy_node_pair *fynp, struct fy_node *fyn)

Parameters

fynp (struct fy_node_pair*) — The node pair
fyn (struct fy_node*) — The key node

Description Sets the key part of the node pair. It overwrites any previous key. Note that no checks for duplicate keys are going to be performed — so if you’re out here making dupes, that’s on you. 💀

Return 0 on success, -1 on error

💜 `fy_node_pair_set_value` 💜

int fy_node_pair_set_value(struct fy_node_pair *fynp, struct fy_node *fyn)

Parameters

fynp (struct fy_node_pair*) — The node pair
fyn (struct fy_node*) — The value node

Description Sets the value part of the node pair. It overwrites any previous value. Simple, clean, iconic.

Return 0 on success, -1 on error

✨ `fy_node_mapping_append` ✨

int fy_node_mapping_append(struct fy_node *fyn_map, struct fy_node *fyn_key, struct fy_node *fyn_value)

Parameters

fyn_map (struct fy_node*) — The mapping node
fyn_key (struct fy_node*) — The node pair’s key
fyn_value (struct fy_node*) — The node pair’s value

Description Appends a node pair to a mapping. Adding to the end of the mapping lineup, periodt.

Return 0 on success, -1 on error

🌈 `fy_node_mapping_prepend` 🌈

int fy_node_mapping_prepend(struct fy_node *fyn_map, struct fy_node *fyn_key, struct fy_node *fyn_value)

Parameters

fyn_map (struct fy_node*) — The mapping node
fyn_key (struct fy_node*) — The node pair’s key
fyn_value (struct fy_node*) — The node pair’s value

Description Prepends a node pair to a mapping. It’s giving “front of the line” behavior. 👑

Return 0 on success, -1 on error

🧚 `fy_node_mapping_remove` 🧚

int fy_node_mapping_remove(struct fy_node *fyn_map, struct fy_node_pair *fynp)

Parameters

fyn_map (struct fy_node*) — The mapping node
fynp (struct fy_node_pair*) — The node pair to remove

Description Removes the node pair from a mapping. Bye bestie 👋

Return 0 on success, -1 on failure.

🌸 `fy_node_mapping_sort` 🌸

int fy_node_mapping_sort(struct fy_node *fyn_map, fy_node_mapping_sort_fn key_cmp, void *arg)

Parameters

fyn_map (struct fy_node*) — The mapping node to sort
key_cmp (fy_node_mapping_sort_fn) — The comparison method
arg (void*) — An opaque user pointer for the comparison method

Description Sorts the keys of a single mapping node using the comparison method you pass. If key_cmp is NULL, it uses the default one. Unlike fy_node_sort(), this does not recurse into child nodes — it stays in its lane. 💅

Return 0 on success, -1 on error

🍓 `fy_node_mapping_remove_by_key` 🍓

struct fy_node *fy_node_mapping_remove_by_key(struct fy_node *fyn_map, struct fy_node *fyn_key)

Parameters

fyn_map (struct fy_node*) — The mapping node
fyn_key (struct fy_node*) — The node pair’s key

Description Removes the node pair from the mapping using the supplied key. It’s a remove-and-return-the-value situation.

Return The value part of the removed node pair, or NULL in case of an error.

🦋 `fy_node_sort` 🦋

int fy_node_sort(struct fy_node *fyn, fy_node_mapping_sort_fn key_cmp, void *arg)

Parameters

fyn (struct fy_node*) — The node to sort
key_cmp (fy_node_mapping_sort_fn) — The comparison method
arg (void*) — An opaque user pointer for the comparison method

Description Recursively sorts all mappings of the given node, using the comparison method you pass — and if that’s NULL, the default one. This one does go down into the child nodes, bestie. Recursive sorting ate. 🔥

Return 0 on success, -1 on error

💖 `fy_node_vscanf` 💖

int fy_node_vscanf(struct fy_node *fyn, const char *fmt, va_list ap)

Parameters

fyn (struct fy_node*) — The node to use as a pathspec root
fmt (const char*) — The scanf based format string
ap (va_list) — The va_list containing the arguments

Description This method easily retrieves data using a familiar vscanf interface. The format string is a regular scanf format string with this format:

“pathspec opt pathspec opt…”

Each pathspec is separated with space from the scanf option.

For example

fyn = { foo: 3 } -> fy_node_scanf(fyn, “/foo d“, struct var) -> var = 3

Return The number of scanned arguments, or -1 on error.

🌟 `fy_node_scanf` 🌟

int fy_node_scanf(struct fy_node *fyn, const char *fmt, ...)

Parameters

fyn (struct fy_node*) — The node to use as a pathspec root
fmt (const char*) — The scanf based format string
ellipsis (ellipsis) — The arguments

Description This method easily retrieves data using a familiar vscanf interface. The format string is a regular scanf format string with this format:

“pathspec opt pathspec opt…”

Each pathspec is separated with space from the scanf option.

For example

fyn = { foo: 3 } -> fy_node_scanf(fyn, “/foo d“, struct var) -> var = 3

Return The number of scanned arguments, or -1 on error.

🎀 `fy_document_vscanf` 🎀

int fy_document_vscanf(struct fy_document *fyd, const char *fmt, va_list ap)

Parameters

fyd (struct fy_document*) — The document
fmt (const char*) — The scanf based format string
ap (va_list) — The va_list containing the arguments

Description This method easily retrieves data using a familiar vscanf interface. The format string is a regular scanf format string with this format:

“pathspec opt pathspec opt…”

Each pathspec is separated with space from the scanf option.

For example

fyd = { foo: 3 } -> fy_document_scanf(fyd, “/foo d“, struct var) -> var = 3

Return The number of scanned arguments, or -1 on error.

🫶 `fy_document_scanf` 🫶

int fy_document_scanf(struct fy_document *fyd, const char *fmt, ...)

Parameters

fyd (struct fy_document*) — The document
fmt (const char*) — The scanf based format string
ellipsis (ellipsis) — The arguments

Description This method easily retrieves data using a familiar vscanf interface. The format string is a regular scanf format string with this format:

“pathspec opt pathspec opt…”

Each pathspec is separated with space from the scanf option.

For example

fyn = { foo: 3 } -> fy_node_scanf(fyd, “/foo d“, struct var) -> var = 3

Return The number of scanned arguments, or -1 on error.

🧚 `fy_document_tag_directive_iterate` 🧚

struct fy_token *fy_document_tag_directive_iterate(struct fy_document *fyd, void **prevp)

Parameters

fyd (struct fy_document*) — The document
prevp (void**) — The previous state of the iterator

Description This method iterates over all the document’s tag directives. The start of the iteration is signalled by a NULL in *prevp. It’s a little iterator situation, very demure.

Return The next tag directive token in the document or NULL at the end of them.

💜 `fy_document_tag_directive_lookup` 💜

struct fy_token *fy_document_tag_directive_lookup(struct fy_document *fyd, const char *handle)

Parameters

fyd (struct fy_document*) — The document
handle (const char*) — The handle to look for

Description Retrieves the matching tag directive token of the document that matches the handle.

Return The tag directive token with the given handle or NULL if not found

🌸 `fy_tag_directive_token_handle` 🌸

const char *fy_tag_directive_token_handle(struct fy_token *fyt, size_t *lenp)

Parameters

fyt (struct fy_token*) — The tag directive token
lenp (size_t*) — Pointer to a variable that will hold the returned length

Description

Bestie, this one retrieves the tag directive token's handle value. It's only valid on tag directive tokens, okay? Don't try it on anything else. 💅

Return

You get a pointer to the tag directive's handle, and lenp gets assigned the length of that handle. If something goes wrong, you get a NULL back. 😭

`fy_tag_directive_token_prefix`

const char *fy_tag_directive_token_prefix(struct fy_token *fyt, size_t *lenp)

Get a tag directive prefix ✨

Parameters

fyt (struct fy_token*) – The tag directive token.
lenp (size_t*) – Pointer to a variable that will hold the returned length.

Description

This one retrieves the tag directive token's prefix value. Again, only valid on tag directive tokens! 🎀

Return

You get a pointer to the tag directive's prefix, and lenp gets assigned the length of that prefix. A NULL comes back if there's an error. 🙈

`fy_document_tag_directive_add`

int fy_document_tag_directive_add(struct fy_document *fyd, const char *handle, const char *prefix)

Add a tag directive to a document 🎀

Parameters

fyd (struct fy_document*) – The document.
handle (const char*) – The handle of the tag directive.
prefix (const char*) – The prefix of the tag directive.

Description

Adds a tag directive to the document. Slay. ✨

Return

0 on success, -1 on error.

`fy_document_tag_directive_remove`

int fy_document_tag_directive_remove(struct fy_document *fyd, const char *handle)

Remove a tag directive 💀

Parameters

fyd (struct fy_document*) – The document.
handle (const char*) – The handle of the tag directive to remove.

Description

Removes a tag directive from a document. But bestie, removal is prohibited if any node is still using this tag directive. Don't even try it. 🚫

Return

0 on success, -1 on error.

`fy_document_lookup_anchor`

struct fy_anchor *fy_document_lookup_anchor(struct fy_document *fyd, const char *anchor, size_t len)

Lookup an anchor 🔍

Parameters

fyd (struct fy_document*) – The document.
anchor (const char*) – The anchor to look for.
len (size_t) – The length of the anchor (or -1 if '0' terminated).

Description

Looks for an anchor having the name you provided. It's giving detective energy. 🕵️‍♀️

Return

The anchor if found, NULL otherwise.

`fy_document_lookup_anchor_by_token`

struct fy_anchor *fy_document_lookup_anchor_by_token(struct fy_document *fyd, struct fy_token *anchor)

Lookup an anchor by token text 🔍

Parameters

fyd (struct fy_document*) – The document.
anchor (struct fy_token*) – The token contains the anchor text to look for.

Description

Looks for an anchor having the name provided from the text of the token. Token vibes. 🎟️

Return

The anchor if found, NULL otherwise.

`fy_document_lookup_anchor_by_node`

struct fy_anchor *fy_document_lookup_anchor_by_node(struct fy_document *fyd, struct fy_node *fyn)

Lookup an anchor by node 🔍

Parameters

fyd (struct fy_document*) – The document.
fyn (struct fy_node*) – The node.

Description

Looks for an anchor located in the given node. Node-based search, iykyk. 🌳

Return

The anchor if found, NULL otherwise.

`fy_anchor_get_text`

const char *fy_anchor_get_text(struct fy_anchor *fya, size_t *lenp)

Get the text of an anchor 📝

Parameters

fya (struct fy_anchor*) – The anchor.
lenp (size_t*) – Pointer to a variable that will hold the returned length.

Description

This method returns a pointer to the text of an anchor along with the length of it. Note: this text is not NULL terminated. So don't treat it like a C string, bestie. 🙅‍♀️

Return

A pointer to the text of the anchor, while lenp will be assigned the length of said anchor. A NULL will be returned in case of an error.

`fy_anchor_node`

struct fy_node *fy_anchor_node(struct fy_anchor *fya)

Get the node of an anchor 🌳

Parameters

fya (struct fy_anchor*) – The anchor.

Description

This method returns the node associated with the anchor. Simple. ✨

Return

The node of the anchor, or NULL in case of an error.

`fy_document_anchor_iterate`

struct fy_anchor *fy_document_anchor_iterate(struct fy_document *fyd, void **prevp)

Iterate over a document's anchors 🔁

Parameters

fyd (struct fy_document*) – The document.
prevp (void**) – The previous state of the iterator.

Description

This method iterates over all the document's anchors. The start of the iteration is signalled by a NULL in *prevp. So set *prevp to NULL to begin. 🚦

Return

The next anchor in the document or NULL at the end of them.

`fy_document_set_anchor`

int fy_document_set_anchor(struct fy_document *fyd, struct fy_node *fyn, const char *text, size_t len)

Place an anchor ⚓

Parameters

fyd (struct fy_document*) – The document.
fyn (struct fy_node*) – The node to set the anchor to.
text (const char*) – Pointer to the anchor text.
len (size_t) – Size of the anchor text, or (size_t)-1 for '0' terminated.

Description

Places an anchor to the node with the given text name.

Note: the data are not copied, merely a reference is taken, so it must be available while the node is in use. Don't let it go out of scope! 😬

Also note that this method is deprecated; use fy_node_set_anchor() instead. Periodt. 💅

Return

0 on success, -1 on error.

`fy_node_set_anchor`

int fy_node_set_anchor(struct fy_node *fyn, const char *text, size_t len)

Place an anchor to the node ⚓

Parameters

fyn (struct fy_node*) – The node to set the anchor to.
text (const char*) – Pointer to the anchor text.
len (size_t) – Size of the anchor text, or (size_t)-1 for '0' terminated.

Description

Places an anchor to the node with the given text name.

Note: the data are not copied, merely a reference is taken, so it must be available while the node is in use. Same warning as before. ⚠️

This is similar to fy_document_set_anchor() with the document set to the document of the fyn node. So it's the glow-up version. ✨

Return

0 on success, -1 on error.

`fy_node_set_anchor_copy`

int fy_node_set_anchor_copy(struct fy_node *fyn, const char *text, size_t len)

Place an anchor to the node copying the text 📋

Parameters

fyn (struct fy_node*) – The node to set the anchor to.
text (const char*) – Pointer to the anchor text.
len (size_t) – Size of the anchor text, or (size_t)-1 for '0' terminated.

Description

Places an anchor to the node with the given text name, which will be copied, so it's safe to dispose the text after the call. No take-backs, it's yours now. 🫶

Return

0 on success, -1 on error.

`fy_node_set_vanchorf`

int fy_node_set_vanchorf(struct fy_node *fyn, const char *fmt, va_list ap)

Place an anchor to the node using a vprintf interface 🖨️

Parameters

fyn (struct fy_node*) – The node to set the anchor to.
fmt (const char*) – Pointer to the anchor format string.
ap (va_list) – The argument list.

Description

Places an anchor to the node with the given text name as created via vprintf'ing the arguments. So you can format it all fancy. 💅

Return

0 on success, -1 on error.

`fy_node_set_anchorf`

int fy_node_set_anchorf(struct fy_node *fyn, const char *fmt, ...)

Place an anchor to the node using a printf interface 🖨️

Parameters

fyn (struct fy_node*) – The node to set the anchor to.
fmt (const char*) – Pointer to the anchor format string.
ellipsis (ellipsis) – The extra arguments.

Description

Places an anchor to the node with the given text name as created via printf'ing the arguments. Variadic vibes. ✨

Return

0 on success, -1 on error.

`fy_node_remove_anchor`

int fy_node_remove_anchor(struct fy_node *fyn)

Remove an anchor 💀

Parameters

fyn (struct fy_node*) – The node to remove anchors from.

Description

Removes an anchor for the given node (if it exists). If it doesn't exist, no biggie. 🤷‍♀️

Return

0 on success, -1 on error.

`fy_node_get_anchor`

struct fy_anchor *fy_node_get_anchor(struct fy_node *fyn)

Get the anchor of a node 🔍

Parameters

fyn (struct fy_node*) – The node.

Description

Retrieves the anchor of the given node (if it exists). It's giving "do you have a moment to talk about our lord and savior, the anchor?" 😇

Return

The anchor if there's one at the node, or NULL otherwise.

`fy_node_get_nearest_anchor`

struct fy_anchor *fy_node_get_nearest_anchor(struct fy_node *fyn)

Get the nearest anchor of the node 🧭

Parameters

fyn (struct fy_node*) – The node.

Description

Retrieves the anchor of the nearest parent of the given node or the given node if it has one. So it climbs up the tree until it finds an anchor. 🌳⬆️

Return

The nearest anchor if there's one, or NULL otherwise.

`fy_node_get_nearest_child_of`

struct fy_node *fy_node_get_nearest_child_of(struct fy_node *fyn_base, struct fy_node *fyn)

Get the nearest node which is a child of the base 🧬

Parameters

fyn_base (struct fy_node*) – The base node.
fyn (struct fy_node*) – The node to start from.

Description

Retrieves the nearest node which is a child of fyn_base starting at fyn and working upwards. So you're climbing the tree from fyn up until you find a node that is a child of fyn_base. Family reunion vibes. 👨‍👩‍👧‍👦

Return

The nearest child of the base if there's one, or NULL otherwise.

`fy_node_create_alias`

struct fy_node *fy_node_create_alias(struct fy_document *fyd, const char *alias, size_t len)

Create an alias node 🎭

Parameters

fyd (struct fy_document*) – The document.
alias (const char*) – The alias text.
len (size_t) – The length of the alias (or -1 if '0' terminated).

Description

Creates an alias on the given document.

Note: the data are not copied, merely a reference is taken, so it must be available while the node is in use. Same warning again, bestie. 🫠

Return

The created alias node, or NULL in case of an error.

`fy_node_create_alias_copy`

struct fy_node *fy_node_create_alias_copy(struct fy_document *fyd, const char *alias, size_t len)

Create an alias node copying the data 📋

Parameters

fyd (struct fy_document*) – The document.
alias (const char*) – The alias text.
len (size_t) – The length of the alias (or -1 if '0' terminated).

Description

Creates an alias on the given document. (This one copies the data, so you don't have to worry about lifetime.) 🫶

Okay okay, picking up mid-thought because we love a seamless transition: a copy of the data will be made, so it is safe to free the data after the call. The return value? The created alias node, or NULL in case of an error. No cap. 💅

`fy_node_get_meta`

void *fy_node_get_meta(struct fy_node *fyn)

Get the meta pointer of a node. Bestie, it literally does what it says on the tin. 🎀

Parameters:

fyn (struct fy_node*) — The node to get meta data from

Description:

Return the meta pointer of a node.

Return:

The stored meta data pointer. Slay.

`fy_node_set_meta`

int fy_node_set_meta(struct fy_node *fyn, void *meta)

Set the meta pointer of a node. Very demure, very mindful pointer assignment. ✨

Parameters:

fyn (struct fy_node*) — The node to set meta data
meta (void*) — The meta data pointer

Description:

Set the meta pointer of a node. If meta is NULL then clear the meta data. That’s the vibe check: NULL means wipe it. 🫶

Return:

0 on success, -1 on error.

`fy_node_clear_meta`

void fy_node_clear_meta(struct fy_node *fyn)

Clear the meta data of a node. Poof, gone, iconic. 💨

Parameters:

fyn (struct fy_node*) — The node to clear meta data

Description:

Clears the meta data of a node.

`typedef fy_node_meta_clear_fn`

void fy_node_meta_clear_fn(struct fy_node *fyn, void *meta, void *user)

Meta data clear method. This is the callback energy we need. 🌸

Parameters:

fyn (struct fy_node*) — The node which the meta data is being cleared
meta (void*) — The meta data of the node assigned via fy_node_set_meta()
user (void*) — The user pointer of fy_document_register_meta()

Description:

This is the callback called when meta data are cleared. Yep, it’s giving cleanup crew. 🧹

`fy_document_register_meta`

int fy_document_register_meta(struct fy_document *fyd,
                              fy_node_meta_clear_fn clear_fn,
                              void *user)

Parameters:

fyd (struct fy_document*) — The document which the hook is registered to
clear_fn (fy_node_meta_clear_fn) — The clear hook method
user (void*) — Opaque user provided pointer to the clear method

Description:

Register a meta data cleanup hook, to be called when the node is freed via a final call to fy_node_free(). The hook is active for all nodes belonging to the document. So like, every node in the doc gets the same energy. 🌈

Return:

0 on success, -1 if another hook is already registered. One hook at a time, bestie — we’re not running a circus. 🎪

`fy_document_unregister_meta`

void fy_document_unregister_meta(struct fy_document *fyd)

Unregister a meta cleanup hook. Bye-bye, hook. 💅

Parameters:

fyd (struct fy_document*) — The document to unregister it’s meta cleanup hook.

Description:

Unregister the currently active meta cleanup hook. The previous cleanup hook will be called for every node in the document. That part matters — the old hook still gets its moment. 🎬

`fy_node_set_marker`

bool fy_node_set_marker(struct fy_node *fyn, unsigned int marker)

Set a marker of a node. Marking your territory, but make it YAML. 🖍️

Parameters:

fyn (struct fy_node*) — The node
marker (unsigned int) — The marker to set

Description:

Sets the marker of the given node, while returning the previous state of the marker. Note that the markers use the same space as the node follow markers. Important detail, don’t forget it. ⭐

Return:

The previous value of the marker.

`fy_node_clear_marker`

bool fy_node_clear_marker(struct fy_node *fyn, unsigned int marker)

Clear a marker of a node. Un-marking, but still returning the old state because we’re thorough. 🦋

Parameters:

fyn (struct fy_node*) — The node
marker (unsigned int) — The marker to clear

Description:

Clears the marker of the given node, while returning the previous state of the marker. Note that the markers use the same space as the node follow markers. Same rule, same space. 🫶

Return:

The previous value of the marker.

`fy_node_is_marker_set`

bool fy_node_is_marker_set(struct fy_node *fyn, unsigned int marker)

Checks whether a marker is set. The vibe check for markers. 🔍

Parameters:

fyn (struct fy_node*) — The node
marker (unsigned int) — The marker index (must be less that FYNWF_MAX_USER_MARKER)

Description:

Check the state of the given marker.

Return:

The value of the marker (invalid markers return false). So if you pass nonsense, it’s a no from the marker. 💀

`fy_node_vreport`

void fy_node_vreport(struct fy_node *fyn, enum fy_error_type type,
                     const char *fmt, va_list ap)

Report about a node vprintf style. Diagnostic drama, but make it formatted. 😭

Parameters:

fyn (struct fy_node*) — The node
type (enum fy_error_type) — The error type
fmt (const char*) — The printf format string
ap (va_list) — The argument list

Description:

Output a report about the given node via the specific error type, and using the reporting configuration of the node’s document. It’s giving structured complaints. 📢

`fy_node_report`

void fy_node_report(struct fy_node *fyn, enum fy_error_type type,
                    const char *fmt, ...)

Report about a node printf style. Same energy, but with the ... varargs flex. ✨

Parameters:

fyn (struct fy_node*) — The node
type (enum fy_error_type) — The error type
fmt (const char*) — The printf format string
ellipsis (ellipsis) — The extra arguments.

Description:

Output a report about the given node via the specific error type, and using the reporting configuration of the node’s document.

`fy_node_override_vreport`

void fy_node_override_vreport(struct fy_node *fyn, enum fy_error_type type,
                              const char *file, int line, int column,
                              const char *fmt, va_list ap)

Report about a node vprintf style, overriding file, line and column info. Custom location, custom chaos. 🗺️

Parameters:

fyn (struct fy_node*) — The node
type (enum fy_error_type) — The error type
file (const char*) — The file override
line (int) — The line override
column (int) — The column override
fmt (const char*) — The printf format string
ap (va_list) — The argument list

Description:

Output a report about the given node via the specific error type, and using the reporting configuration of the node’s document. This method will use the overrides provided in order to massage the reporting information. If file is NULL, no file location will be reported. If either line or column is negative no location will be reported. So negative numbers mean “location? never heard of her.” 🙈

`fy_node_override_report`

void fy_node_override_report(struct fy_node *fyn, enum fy_error_type type,
                             const char *file, int line, int column,
                             const char *fmt, ...)

Report about a node printf style, overriding file, line and column info. The varargs version of “make the location say what I want.” 💅

Parameters:

fyn (struct fy_node*) — The node
type (enum fy_error_type) — The error type
file (const char*) — The file override
line (int) — The line override
column (int) — The column override
fmt (const char*) — The printf format string
ellipsis (ellipsis) — The extra arguments.

Description:

`fy_event_vreport`

void fy_event_vreport(struct fy_parser *fyp, struct fy_event *fye,
                      enum fy_event_part fyep, enum fy_error_type type,
                      const char *fmt, va_list ap)

Report about an event vprintf style. Event gossip, but official. 👀

Parameters:

fyp (struct fy_parser*) — The parser of which the event was generated from
fye (struct fy_event*) — The event
fyep (enum fy_event_part) — The event part which the report is about
type (enum fy_error_type) — The error type
fmt (const char*) — The printf format string
ap (va_list) — The argument list

Description:

Output a report about the given event via the specific error type, focusing at the given event part. Focused. Intentional. Iconic. 🎯

`fy_event_report`

void fy_event_report(struct fy_parser *fyp, struct fy_event *fye,
                     enum fy_event_part fyep, enum fy_error_type type,
                     const char *fmt, ...)

Report about an event printf style. Now with extra arguments and main character energy. 🌟

Parameters:

fyp (struct fy_parser*) — The parser of which the event was generated from
fye (struct fy_event*) — The event
fyep (enum fy_event_part) — The event part which the report is about
type (enum fy_error_type) — The error type
fmt (const char*) — The printf format string
ellipsis (ellipsis) — The extra arguments.

Description:

Output a report about the given event via the specific error type, focusing at the given event part. Same focus, same event, just printf style. 💖

`struct fy_diag_cfg`

struct fy_diag_cfg

The diagnostics configuration. This is the control room for how diagnostics look and behave. 🎛️

Definition:

struct fy_diag_cfg {
    FILE *fp;
    fy_diag_output_fn output_fn;
    void *user;
    enum fy_error_type level;
    unsigned int module_mask;
    bool colorize : 1;
    bool show_source : 1;
    bool show_position : 1;
    bool show_type : 1;
    bool show_module : 1;
    int source_width;
    int position_width;
    int type_width;
    int module_width;
}

Members:

fp — File descriptor of the error output
output_fn — Callback to use when fp is NULL
user — User pointer to pass to the output_fn
level — The minimum debugging level
module_mask — A bitmask of the enabled modules
colorize — true if output should be colorized using ANSI sequences
show_source — true if source location should be displayed
show_position — true if position should be displayed
show_type — true if the type should be displayed
show_module — true if the module should be displayed
source_width — Width of the source field
position_width — Width of the position field
type_width — Width of the type field
module_width — Width of the module field

Description:

This structure contains the configuration of the diagnostic object. Basically the settings screen for your diagnostics. 🎀

`struct fy_diag_error`

struct fy_diag_error

A collected diagnostic error. Yes, an error that got collected. We love a documented problem. 📝

Definition

struct fy_diag_error {
    enum fy_error_type type;
    enum fy_error_module module;
    struct fy_token *fyt;
    const char *msg;
    const char *file;
    int line;
    int column;
}

Members

type — the error type, bestie ✨
module — which module it came from
fyt — the token, and yes it might be NULL so pls check 🫶
msg — the message that gets output right alongside it
file — the file that held the input
line — the line where the error is sitting
column — the column where the error is sitting

Description

Okay so this struct is literally just a little info packet about an error that the diagnostic object is collecting. That's it, that's the vibe 💅

`fy_diag_create`

struct fy_diag *fy_diag_create(const struct fy_diag_cfg *cfg)

Create a diagnostic object, iconic behaviour honestly 👑

Parameters

cfg (const struct fy_diag_cfg*) — the configuration for the diagnostic object (NULL is default)

Description

Makes you a diagnostic object using the config you handed over.

Return

A pointer to the diagnostic object, or NULL if something went wrong 😭

`fy_diag_destroy`

void fy_diag_destroy(struct fy_diag *diag)

Destroy a diagnostic object.

Parameters

diag (struct fy_diag*) — the diagnostic object to destroy

Description

Destroys a diagnostic object — but heads up, the actual destruction only happens once there are no more references left to it. However, no output will be generated after this call. So it's giving "I'm leaving the group chat but I'm still lurking" 💀

`fy_diag_get_cfg`

const struct fy_diag_cfg *fy_diag_get_cfg(struct fy_diag *diag)

Get a diagnostic object's configuration.

Parameters

diag (struct fy_diag*) — the diagnostic object

Description

Returns the current configuration of a diagnostic object.

Return

A const pointer to the diagnostic object configuration, or NULL in the case where diag is NULL.

`fy_diag_set_cfg`

void fy_diag_set_cfg(struct fy_diag *diag, const struct fy_diag_cfg *cfg)

Set a diagnostic object's configuration.

Parameters

diag (struct fy_diag*) — the diagnostic object
cfg (const struct fy_diag_cfg*) — the diagnostic configuration

Description

Swaps out the current diagnostic config for the one you passed in. Out with the old, in with the new 🦋

`fy_diag_set_level`

void fy_diag_set_level(struct fy_diag *diag, enum fy_error_type level)

Set a diagnostic object's debug error level.

Parameters

diag (struct fy_diag*) — the diagnostic object
level (enum fy_error_type) — the debugging level to set

`fy_diag_set_colorize`

void fy_diag_set_colorize(struct fy_diag *diag, bool colorize)

Set a diagnostic object's colorize option ✨🌈

Parameters

diag (struct fy_diag*) — the diagnostic object
colorize (bool) — the colorize option

`fy_diag_ref`

struct fy_diag *fy_diag_ref(struct fy_diag *diag)

Increment the reference counter of a diagnostic object.

Parameters

diag (struct fy_diag*) — the diagnostic object to reference

Description

Increments the reference. Keeping it alive, holding space for it 🫶

Return

Always returns the diag argument — it literally hands it right back to you.

`fy_diag_unref`

void fy_diag_unref(struct fy_diag *diag)

Take away a ref from a diagnostic object.

Parameters

diag (struct fy_diag*) — the diagnostic object to unref

Description

Takes away a reference, and if it hits 0, the diagnostic object gets freed. Last one out, turn off the lights 💅

`fy_diag_got_error`

bool fy_diag_got_error(struct fy_diag *diag)

Test whether an error level diagnostic has been produced.

Parameters

diag (struct fy_diag*) — the diagnostic object

Description

Tests whether an error diagnostic has been produced. Like a vibe check but for errors.

Return

true if an error has been produced, false otherwise.

`fy_diag_set_error`

void fy_diag_set_error(struct fy_diag *diag, bool on_error)

Sets the error produced state.

Parameters

diag (struct fy_diag*) — the diagnostic object
on_error (bool) — the set error state

Description

Sets the error produced state. Yeah, it says it twice, I'm just relaying the message fr fr.

`fy_diag_reset_error`

void fy_diag_reset_error(struct fy_diag *diag)

Reset the error flag of the diagnostic object.

Parameters

diag (struct fy_diag*) — the diagnostic object

Description

Clears the error flag that got set by an output of an error level diagnostic. Fresh start energy 🌸

`fy_diag_set_collect_errors`

void fy_diag_set_collect_errors(struct fy_diag *diag, bool collect_errors)

Collect errors instead of outputting.

Parameters

diag (struct fy_diag*) — the diagnostic object
collect_errors (bool) — the collect errors mode

Description

Sets the collect errors mode. When it's true, instead of outputting to the diagnostic interface, the errors get collected so you can come back for them later. Little error scrapbook, iykyk 🎀

`fy_diag_get_collect_errors`

bool fy_diag_get_collect_errors(struct fy_diag *diag)

Get collect errors state.

Parameters

diag (struct fy_diag*) — the diagnostic object

Description

Gets the collect errors mode.

Return

true if it's collecting errors, false otherwise.

`fy_diag_cfg_default`

void fy_diag_cfg_default(struct fy_diag_cfg *cfg)

Fill in the configuration structure with defaults ⭐

Parameters

cfg (struct fy_diag_cfg*) — the diagnostic configuration structure

Description

Fills the configuration structure with defaults. The default always associates the file descriptor to stderr — that's just how it is, no notes.

`fy_diag_cfg_from_parser_flags`

void fy_diag_cfg_from_parser_flags(struct fy_diag_cfg *cfg, enum fy_parse_cfg_flags pflags)

Fill partial diagnostic config structure from parser config flags.

Parameters

cfg (struct fy_diag_cfg*) — the diagnostic configuration structure
pflags (enum fy_parse_cfg_flags) — the parser flags

Description

Fills in part of the configuration structure using parser flags. Since the parser flags do not contain debugging flags anymore, this method is deprecated — it's giving legacy era, don't @ me 🙈

`fy_diag_vprintf`

int fy_diag_vprintf(struct fy_diag *diag, const char *fmt, va_list ap)

vprintf raw interface to diagnostics.

Parameters

diag (struct fy_diag*) — the diagnostic object to use
fmt (const char*) — the vprintf format string
ap (va_list) — the arguments

Description

Raw output to the diagnostic object using a standard vprintf interface. Note that this is the lowest level interface, and as such is not recommended for use, since no formatting or coloring will take place. You're rawdogging the output, essentially 💀

Return

The number of characters output, or -1 in case of an error. Note that 0 shall be returned if the diagnostic object has been destroyed but not yet freed.

`fy_diag_printf`

int fy_diag_printf(struct fy_diag *diag, const char *fmt, ...)

printf raw interface to diagnostics.

Parameters

diag (struct fy_diag*) — the diagnostic object to use
fmt (const char*) — the printf format string
ellipsis (ellipsis) — the arguments

Description

Raw output to the diagnostic object using a standard printf interface. Same warning as its vprintf sibling: this is the lowest level interface, so it's not recommended, since no formatting or coloring will take place.

Return

The number of characters output, or -1 in case of an error. Note that 0 shall be returned if the diagnostic object has been destroyed but not yet freed.

`struct fy_diag_ctx`

struct fy_diag_ctx

The diagnostics context. It's giving main character context packet 👑

Definition

struct fy_diag_ctx {
    enum fy_error_type level;
    enum fy_error_module module;
    const char *source_func;
    const char *source_file;
    int source_line;
    const char *file;
    int line;
    int column;
}

Members

level — the level of the diagnostic
module — the module of the diagnostic
source_func — the source function
source_file — the source file
source_line — the source line
file — the file that caused the error
line — the line where the diagnostic occured
column — the column where the diagnostic occured

Description

This structure contains the diagnostic context. That's the whole lore 🌸

`fy_vdiag`

int fy_vdiag(struct fy_diag *diag, const struct fy_diag_ctx *fydc, const char *fmt, va_list ap)

Context aware diagnostic output, like vprintf.

Parameters

diag (struct fy_diag*) — the diagnostic object to use
fydc (const struct fy_diag_ctx*) — the diagnostic context
fmt (const char*) — the vprintf format string
ap (va_list) — the arguments

Description

Context aware output to the diagnostic object using a standard vprintf interface. Now with ✨context✨.

Return

The number of characters output, or -1 in case of an error. Note that 0 shall be returned if the diagnostic object has been destroyed but not yet freed.

`fy_diagf`

int fy_diagf(struct fy_diag *diag, const struct fy_diag_ctx *fydc, const char *fmt, ...)

Context aware diagnostic output, like printf.

Parameters

diag (struct fy_diag*) — the diagnostic object to use
fydc (const struct fy_diag_ctx*) — the diagnostic context
fmt (const char*) — the vprintf format string
ellipsis (ellipsis) — variable arguments

Description

Context aware output to the diagnostic object using a standard printf interface.

Return

The number of characters output, or -1 in case of an error. Note that 0 shall be returned if the diagnostic object has been destroyed but not yet freed.

`fy_diag_token_vreport`

void fy_diag_token_vreport(struct fy_diag *diag, struct fy_token *fyt, enum fy_error_type type, const char *fmt, va_list ap)

Report about a token, vprintf style, using the given diagnostic object 🔥

Parameters

diag (struct fy_diag*) — the diag object
fyt (struct fy_token*) — the token
type (enum fy_error_type) — the error type
fmt (const char*) — the printf format string
ap (va_list) — the argument list

Description

Outputs a report about the given token via the specific error type, and using the reporting configuration of the token's document. It's a whole relay situation — the token's document calls the shots 🎀

`fy_diag_token_report`

void fy_diag_token_report(struct fy_diag *diag, struct fy_token *fye,
       enum fy_error_type type, const char *fmt, ...)

okay so this one is literally just "tell me about this token, printf style" 🎀 it reports about a token using the diag object you hand it.

Parameters

diag (struct fy_diag *) — the diag object, your reporter bestie
fye (struct fy_token *) — the token in question
type (enum fy_error_type) — the error type
fmt (const char *) — the printf format string
ellipsis (ellipsis) — the extra arguments

Description

Outputs a report about the given token via the specific error type, and uses the reporting configuration of the token's document 💅 so the token's doc decides how it gets dressed up.

`fy_diag_token_override_vreport`

void fy_diag_token_override_vreport(struct fy_diag *diag, struct
       fy_token *fyt, enum fy_error_type type, const char *file, int line, int
       column, const char *fmt, va_list ap)

the va_list twin of the override-y token reporter ✨ vprintf style, and it lets you override the file, line and column info.

Parameters

diag (struct fy_diag *) — the diag object
fyt (struct fy_token *) — the token
type (enum fy_error_type) — the error type
file (const char *) — the file override
line (int) — the line override
column (int) — the column override
fmt (const char *) — the printf format string
ap (va_list) — the argument list

Description

Outputs a report about the given token via the specific error type, using the reporting configuration of the token's document. This method uses the overrides you provide in order to massage the reporting information 🫶

fr fr: if file is NULL, no file location will be reported. And if either line or column is negative, no location will be reported either. no cap.

`fy_diag_token_override_report`

void fy_diag_token_override_report(struct fy_diag *diag, struct fy_token
       *fyt, enum fy_error_type type, const char *file, int line, int column,
       const char *fmt, ...)

same energy as the last one but printf style with an ellipsis instead of a va_list 💖

Parameters

diag (struct fy_diag *) — the diag object
fyt (struct fy_token *) — the token
type (enum fy_error_type) — the error type
file (const char *) — the file override
line (int) — the line override
column (int) — the column override
fmt (const char *) — the printf format string
ellipsis (ellipsis) — the extra arguments

Description

Outputs a report about the given token via the specific error type, and uses the reporting configuration of the token's document. This method will use the overrides provided in order to massage the reporting information.

again, because it matters: file being NULL means no file location gets reported, and a negative line or column means no location gets reported. iconic consistency 🌸

`fy_diag_node_vreport`

void fy_diag_node_vreport(struct fy_diag *diag, struct fy_node *fyn,
       enum fy_error_type type, const char *fmt, va_list ap)

token who? we're on nodes now 🦋 report about a node, vprintf style.

Parameters

diag (struct fy_diag *) — the diag object
fyn (struct fy_node *) — the node
type (enum fy_error_type) — the error type
fmt (const char *) — the printf format string
ap (va_list) — the argument list

Description

Outputs a report about the given node via the specific error type, and uses the reporting configuration of the node's document 💜

`fy_diag_node_report`

void fy_diag_node_report(struct fy_diag *diag, struct fy_node *fyn, enum
       fy_error_type type, const char *fmt, ...)

the printf version for nodes, and yes she ate 💅

Parameters

diag (struct fy_diag *) — the diag object
fyn (struct fy_node *) — the node
type (enum fy_error_type) — the error type
fmt (const char *) — the printf format string
ellipsis (ellipsis) — the extra arguments

Description

Outputs a report about the given node via the specific error type, and uses the reporting configuration of the node's document ✨

`fy_diag_node_override_vreport`

void fy_diag_node_override_vreport(struct fy_diag *diag, struct fy_node
       *fyn, enum fy_error_type type, const char *file, int line, int column,
       const char *fmt, va_list ap)

node report, vprintf style, but with the file/line/column glow-up overrides 🎀

Parameters

diag (struct fy_diag *) — the diag object
fyn (struct fy_node *) — the node
type (enum fy_error_type) — the error type
file (const char *) — the file override
line (int) — the line override
column (int) — the column override
fmt (const char *) — the printf format string
ap (va_list) — the argument list

Description

Outputs a report about the given node via the specific error type, and uses the reporting configuration of the node's document. This method will use the overrides provided in order to massage the reporting information.

bestie, remember the rule: file NULL → no file location reported. line or column negative → no location reported. periodt 💀

`fy_diag_node_override_report`

void fy_diag_node_override_report(struct fy_diag *diag, struct fy_node
       *fyn, enum fy_error_type type, const char *file, int line, int column,
       const char *fmt, ...)

and the printf-style version of the node override reporter, completing the set 🔥

Parameters

diag (struct fy_diag *) — the diag object
fyn (struct fy_node *) — the node
type (enum fy_error_type) — the error type
file (const char *) — the file override
line (int) — the line override
column (int) — the column override
fmt (const char *) — the printf format string
ellipsis (ellipsis) — the extra arguments

Description

file is NULL → no file location reported. Negative line or column → no location reported. same as her sisters 🫶

`fy_diag_event_vreport`

void fy_diag_event_vreport(struct fy_diag *diag, struct fy_event *fye,
       enum fy_event_part fyep, enum fy_error_type type, const char *fmt,
       va_list ap)

events have entered the chat 😭 vprintf style, and note the extra fyep — you're reporting about a specific event part not the whole event.

Parameters

diag (struct fy_diag *) — the diag object
fye (struct fy_event *) — the event
fyep (enum fy_event_part) — the event part
type (enum fy_error_type) — the error type
fmt (const char *) — the printf format string
ap (va_list) — the argument list

Description

Outputs a report about the given event part via the specific error type ⭐

`fy_diag_event_report`

void fy_diag_event_report(struct fy_diag *diag, struct fy_event *fye,
       enum fy_event_part fyep, enum fy_error_type type, const char *fmt, ...)

the printf-style event-part reporter, same trio of vibes, different signature 💖

Parameters

diag (struct fy_diag *) — the diag object
fye (struct fy_event *) — the event
fyep (enum fy_event_part) — the event part
type (enum fy_error_type) — the error type
fmt (const char *) — the printf format string
ellipsis (ellipsis) — the extra arguments

Description

Outputs a report about the given event part via the specific error type 🌈

`fy_diag_errors_iterate`

struct fy_diag_error *fy_diag_errors_iterate(struct fy_diag *diag, void
       **prevp)

okay this one's a little iterator icon 👑 it walks over the errors of a diagnostic object.

Parameters

diag (struct fy_diag *) — the diagnostic object
prevp (void **) — the previous result iterator

Description

This method iterates over all the errors collected on the diagnostic object. The start of the iteration is signalled by a NULL in *prevp — that's your "go" signal, no cap 💅

Return

The next errors, or NULL when there are not any more 🎀

`fy_parser_checkpoint_create`

struct fy_parser_checkpoint *fy_parser_checkpoint_create(struct
       fy_parser *fyp)

save point!! 🎮 this creates a checkpoint of the parser's current state, so you can stash where you're at and potentially roll back to it later using fy_parser_rollback(). it's giving "quicksave before the boss fight" energy fr fr.

important: the checkpoint must be destroyed via fy_parser_checkpoint_destroy() when it's no longer needed. don't just leave it lying around 🙈

Parameters

fyp (struct fy_parser *) — the parser

Return

A pointer to the checkpoint, or NULL in case of an error 😭

`fy_parser_checkpoint_destroy`

void fy_parser_checkpoint_destroy(struct fy_parser_checkpoint *fypchk)

the cleanup crew 🧹 destroys a checkpoint you created earlier via fy_parser_checkpoint_create().

Parameters

fypchk (struct fy_parser_checkpoint *) — the checkpoint to destroy

Description

Destroys a checkpoint created earlier via fy_parser_checkpoint_create() ✨

`fy_parser_rollback`

int fy_parser_rollback(struct fy_parser *fyp, struct
       fy_parser_checkpoint *fypc)

the actual rewind button ⏪ rolls the parser state back to a previously created checkpoint, so you can revert to an earlier state and re-parse from that point.

the checkpoint remains valid after rollback 🫶 so you can use it again, or destroy it via fy_parser_checkpoint_destroy(). reusable, we love to see it.

Parameters

fyp (struct fy_parser *) — the parser
fypc (struct fy_parser_checkpoint *) — the checkpoint to roll back to

Return

0 on success, -1 on error 💀

`enum fy_token_type`

enum fy_token_type

Token types 🎀 — the roster of what a token can be.

Definition

okay bestie, this is the big enum that holds every token type fyaml knows about — YAML tokens, path-expression (YPATH) tokens, scalar-expression tokens, all of it. yes, it's long. no, we're not skipping any. every single one gets its moment 💅

enum fy_token_type {
    FYTT_NONE,
    FYTT_STREAM_START,
    FYTT_STREAM_END,
    FYTT_VERSION_DIRECTIVE,
    FYTT_TAG_DIRECTIVE,
    FYTT_DOCUMENT_START,
    FYTT_DOCUMENT_END,
    FYTT_BLOCK_SEQUENCE_START,
    FYTT_BLOCK_MAPPING_START,
    FYTT_BLOCK_END,
    FYTT_FLOW_SEQUENCE_START,
    FYTT_FLOW_SEQUENCE_END,
    FYTT_FLOW_MAPPING_START,
    FYTT_FLOW_MAPPING_END,
    FYTT_BLOCK_ENTRY,
    FYTT_FLOW_ENTRY,
    FYTT_KEY,
    FYTT_VALUE,
    FYTT_ALIAS,
    FYTT_ANCHOR,
    FYTT_TAG,
    FYTT_SCALAR,
    FYTT_INPUT_MARKER,
    FYTT_PE_SLASH,
    FYTT_PE_ROOT,
    FYTT_PE_THIS,
    FYTT_PE_PARENT,
    FYTT_PE_MAP_KEY,
    FYTT_PE_SEQ_INDEX,
    FYTT_PE_SEQ_SLICE,
    FYTT_PE_SCALAR_FILTER,
    FYTT_PE_COLLECTION_FILTER,
    FYTT_PE_SEQ_FILTER,
    FYTT_PE_MAP_FILTER,
    FYTT_PE_UNIQUE_FILTER,
    FYTT_PE_EVERY_CHILD,
    FYTT_PE_EVERY_CHILD_R,
    FYTT_PE_ALIAS,
    FYTT_PE_SIBLING,
    FYTT_PE_COMMA,
    FYTT_PE_BARBAR,
    FYTT_PE_AMPAMP,
    FYTT_PE_LPAREN,
    FYTT_PE_RPAREN,
    FYTT_PE_EQEQ,
    FYTT_PE_NOTEQ,
    FYTT_PE_LT,
    FYTT_PE_GT,
    FYTT_PE_LTE,
    FYTT_PE_GTE,
    FYTT_SE_PLUS,
    FYTT_SE_MINUS,
    FYTT_SE_MULT,
    FYTT_SE_DIV,
    FYTT_PE_METHOD,
    FYTT_SE_METHOD,
    FYTT_PE_BANG,
    FYTT_PE_AT
};

Constants

welcome to the token zoo 🦋 — every resident gets a lil intro, no cap:

FYTT_NONE — no token. the void. the "there is literally nothing here" token 💀
FYTT_STREAM_START — stream start token ✨
FYTT_STREAM_END — stream end token, the wrap-up 🎀
FYTT_VERSION_DIRECTIVE — version directive token
FYTT_TAG_DIRECTIVE — tag directive token
FYTT_DOCUMENT_START — document start token, main character energy 👑
FYTT_DOCUMENT_END — document end token
FYTT_BLOCK_SEQUENCE_START — block sequence start token
FYTT_BLOCK_MAPPING_START — block mapping start token
FYTT_BLOCK_END — block end token
FYTT_FLOW_SEQUENCE_START — flow sequence start token
FYTT_FLOW_SEQUENCE_END — flow sequence end token
FYTT_FLOW_MAPPING_START — flow mapping start token
FYTT_FLOW_MAPPING_END — flow mapping end token
FYTT_BLOCK_ENTRY — block entry token
FYTT_FLOW_ENTRY — flow entry token
FYTT_KEY — key token 🔑
FYTT_VALUE — value token
FYTT_ALIAS — alias token
FYTT_ANCHOR — anchor token ⚓
FYTT_TAG — tag token
FYTT_SCALAR — scalar token
FYTT_INPUT_MARKER — input marker token
FYTT_PE_SLASH — path expression slash token
FYTT_PE_ROOT — path expression root token
FYTT_PE_THIS — path expression this token
FYTT_PE_PARENT — path expression parent token
FYTT_PE_MAP_KEY — path expression map key token
FYTT_PE_SEQ_INDEX — path expression sequence index token
FYTT_PE_SEQ_SLICE — path expression sequence slice token
FYTT_PE_SCALAR_FILTER — path expression scalar filter token
FYTT_PE_COLLECTION_FILTER — path expression collection filter token
FYTT_PE_SEQ_FILTER — path expression sequence filter token
FYTT_PE_MAP_FILTER — path expression map filter token
FYTT_PE_UNIQUE_FILTER — path expression unique filter token
FYTT_PE_EVERY_CHILD — path expression every child token
FYTT_PE_EVERY_CHILD_R — path expression every child recursive token
FYTT_PE_ALIAS — path expression alias token
FYTT_PE_SIBLING — path expression sibling token
FYTT_PE_COMMA — path expression , token
FYTT_PE_BARBAR — path expression || token
FYTT_PE_AMPAMP — path expression && token
FYTT_PE_LPAREN — path expression ( token
FYTT_PE_RPAREN — path expression ) token
FYTT_PE_EQEQ — path expression == token
FYTT_PE_NOTEQ — path expression != token
FYTT_PE_LT — path expression < token
FYTT_PE_GT — path expression > token
FYTT_PE_LTE — path expression <= token
FYTT_PE_GTE — path expression >= token
FYTT_SE_PLUS — scalar expression + token
FYTT_SE_MINUS — scalar expression - token
FYTT_SE_MULT — scalar expression * token
FYTT_SE_DIV — scalar expression / token
FYTT_PE_METHOD — path expression method token
FYTT_SE_METHOD — scalar expression method token
FYTT_PE_BANG — path expression ! token
FYTT_PE_AT — path expression @ token

fy_token_type_is_valid

bool fy_token_type_is_valid(enum fy_token_type type)

so this one does a vibe check on a token type — is it even valid, yes or no? 🫶

Parameters

type (enum fy_token_type) — the token type in question

Description

literally just checks whether the token type you handed it is a valid one.

Return

true if the token type is valid, false otherwise.

fy_token_type_is_yaml

bool fy_token_type_is_yaml(enum fy_token_type type)

same energy, but the question is "is this a YAML token type?" 🌸

Parameters

type (enum fy_token_type) — the token type

Description

checks if the thing you passed in is a valid YAML token type.

Return

true if the token type is a valid YAML one, false otherwise.

fy_token_type_is_content

bool fy_token_type_is_content(enum fy_token_type type)

and now: is it a content token type? iykyk ✨

Parameters

type (enum fy_token_type) — the token type

Description

checks if the token type is a valid YAML content one.

Return

true if the token type is a valid YAML content one, false otherwise.

fy_token_type_is_path_expr

bool fy_token_type_is_path_expr(enum fy_token_type type)

YPATH check incoming 🦋

Parameters

type (enum fy_token_type) — the token type

Description

checks if the token type is a valid YPATH parse expression token.

Return

true if the token type is a valid YPATH one, false otherwise.

fy_token_type_is_scalar_expr

bool fy_token_type_is_scalar_expr(enum fy_token_type type)

same but for the scalar-expression side of YPATH 💜

Parameters

type (enum fy_token_type) — the token type

Description

checks if the token type is a valid YPATH parse scalar expression token.

Return

true if the token type is a valid YPATH scalar one, false otherwise.

fy_token_get_type

enum fy_token_type fy_token_get_type(struct fy_token *fyt)

gimme the type, bestie 👀

Parameters

fyt (struct fy_token *) — the token

Description

returns the token's type — and if it's NULL, you get FYTT_NONE back. no crash, no drama, just the void token 💀

Return

the token's type; FYTT_NONE if it's not a valid token (or it's NULL).

fy_token_start_mark

const struct fy_mark *fy_token_start_mark(struct fy_token *fyt)

where does this token start? 📍

Parameters

fyt (struct fy_token *) — the token to get its start marker

Description

returns the token's start marker if it exists. and ngl, it is permissible for some token types to have no start marker, because they're without content. so don't come for it if you get NULL 🎀

Return

the token's start marker, NULL if not available.

fy_token_end_mark

const struct fy_mark *fy_token_end_mark(struct fy_token *fyt)

and where does it end? 📍

Parameters

fyt (struct fy_token *) — the token to get its end marker

Description

returns the token's end marker if it exists. same deal as before: it is permissible for some token types to have no end marker because they're without content.

Return

the token's end marker, NULL if not available.

fy_token_style_start_mark

const struct fy_mark *fy_token_style_start_mark(struct fy_token *fyt)

this one is the start marker with style — it includes the style indicators 💅

Parameters

fyt (struct fy_token *) — the token to get its style start marker

Description

returns the token's start marker if it exists, including the style indicators. and yeah, again, it's permissible for some token types to have no start marker because they're without content.

Return

the token's style start marker, NULL if not available.

fy_token_style_end_mark

const struct fy_mark *fy_token_style_end_mark(struct fy_token *fyt)

the matching style end marker — the other half of the fit ✨

Parameters

fyt (struct fy_token *) — the token to get its style end marker

Description

returns the token's end marker if it exists, including the style indicators. and once more for the people in the back: it's permissible for some token types to have no end marker because they're without content.

Return

the token's style end marker, NULL if not available.

fy_scan

struct fy_token *fy_scan(struct fy_parser *fyp)

okay this one is low key iconic — it's the raw scanner door 🔥

Parameters

fyp (struct fy_parser *) — the parser to get the next token from

Description

returns the next scanner token. heads up though: this is a very low level interface — it's meant for users who want or need to implement their own YAML parser. so if that's not you, bestie, maybe step back 😭

⚠️ the token you get back is expected to be disposed of using fy_scan_token_free(). do not just leave it lying around.

Return

the next token, or NULL if there are no more tokens available.

fy_scan_token_free

void fy_scan_token_free(struct fy_parser *fyp, struct fy_token *fyt)

clean up your mess 💖 (respectfully)

Parameters

fyp (struct fy_parser *) — the parser of which the token was returned by fy_scan()
fyt (struct fy_token *) — the token to free

Description

frees the token that came back from fy_scan(). that's it, that's the whole job 🫶

fy_tag_directive_token_prefix0

const char *fy_tag_directive_token_prefix0(struct fy_token *fyt)

grab the tag directive prefix as a nice zero-terminated string 🎀

Parameters

fyt (struct fy_token *) — the tag directive token out of which the prefix pointer will be returned

Description

pulls out the tag directive's prefix contents as a zero terminated string. it's similar to fy_tag_directive_token_prefix(), except the string you get back is zero terminated — and memory may be allocated to hold it, associated with the token. so it's the ✨glowed-up✨ version.

Return

a pointer to the zero terminated text representation of the prefix token. NULL in case of an error. 🙈

`fy_tag_directive_token_handle0`

const char *fy_tag_directive_token_handle0(struct fy_token *fyt)

Get the handle chillin' inside a tag directive token, but make it a zero terminated string ✨

Parameters

fyt (struct fy_token*) – the tag directive token you're pulling the handle pointer out of.

Description

Okay so this one grabs the tag directive's handle contents and hands them to you as a zero terminated string 💅. It's basically fy_tag_directive_token_handle()'s sibling — the difference being that what comes back is zero terminated, and memory may get allocated to hold it, and that memory is associated with the token. So like, it's the same vibe but null-safe at the end, iykyk.

Return

A pointer to the zero terminated text representation of the handle token 🎀. NULL if something went wrong.

`fy_tag_token_handle`

const char *fy_tag_token_handle(struct fy_token *fyt, size_t *lenp)

Get the handle that's inside a tag token 🏷️

Parameters

fyt (struct fy_token*) – the tag token the handle pointer comes out of.
lenp (size_t*) – pointer to a variable that'll hold the returned length.

Description

Retrieves the tag handle contents fr fr. It will fail if the token isn't actually a tag token, or if a memory error happens 😭. No cap, those are the two ways it goes sideways.

Return

A pointer to the text representation of the handle token, and lenp gets assigned the character length of said representation. NULL if there's an error.

`fy_tag_token_suffix`

const char *fy_tag_token_suffix(struct fy_token *fyt, size_t *lenp)

Get the suffix out of a tag token 💖

Parameters

fyt (struct fy_token*) – the tag token you're grabbing the suffix pointer from.
lenp (size_t*) – pointer to a variable that'll hold the returned length.

Description

Retrieves the tag suffix contents ✨. Fails if the token isn't a tag token, or if a memory error decides to show up 😭.

Return

A pointer to the text representation of the suffix token, with lenp assigned the character length of that representation. NULL in case of an error.

`fy_tag_token_short`

const char *fy_tag_token_short(struct fy_token *fyt, size_t *lenp)

Get the short tag of a tag token, bestie 🎀

Parameters

fyt (struct fy_token*) – the tag token the short pointer comes out of.
lenp (size_t*) – pointer to a variable that'll hold the returned length.

Description

Retrieves the short tag contents. And like — the short tag is literally the same one you'll need to emit, so it's giving main character energy 🔥. Fails if the token isn't a tag token, or if a memory error happens.

Return

A pointer to the text representation of the short tag, and lenp gets the character length of that representation. NULL in case of an error.

`fy_tag_token_handle0`

const char *fy_tag_token_handle0(struct fy_token *fyt)

Get the handle inside a tag token, zero terminated edition 🌸

Parameters

fyt (struct fy_token*) – the tag token from which the handle pointer will be returned.

Description

Retrieves the tag handle contents as a zero terminated string 💜. It's similar to fy_tag_token_handle(), except the returned string is zero terminated and memory may be allocated to hold it, associated with the token. Same energy, just null-terminated at the end, slay.

Return

A pointer to the zero terminated text representation of the handle token. NULL in case of an error.

`fy_tag_token_short0`

const char *fy_tag_token_short0(struct fy_token *fyt)

Get the short tag of a tag token as a zero terminated string 🦋

Parameters

fyt (struct fy_token*) – the tag token the short pointer comes out of.

Description

Retrieves the short tag contents — and again, the short tag is the exact same one that needs to be emitted 👑. Will fail if the token isn't a tag token, or if a memory error happens.

Return

A pointer to the null terminated text representation of the short tag. NULL in case of an error.

`fy_tag_token_suffix0`

const char *fy_tag_token_suffix0(struct fy_token *fyt)

Get the suffix inside a tag token as a zero terminated string 🍓

Parameters

fyt (struct fy_token*) – the tag token the suffix pointer comes out of.

Description

Retrieves the tag suffix contents as a zero terminated string ✨. Just like fy_tag_token_suffix(), except — you guessed it — the returned string is zero terminated and memory may be allocated to hold it, associated with the token. Consistent queen behavior.

Return

A pointer to the zero terminated text representation of the suffix token. NULL in case of an error.

`fy_version_directive_token_version`

const struct fy_version *fy_version_directive_token_version(struct fy_token *fyt)

Return the version of a version directive token 🌈

Parameters

fyt (struct fy_token*) – the version directive token.

Description

Retrieves the version stored in a version directive token. Simple as that, no notes 💅.

Return

A pointer to the version stored in the version directive token, or NULL if there's an error, or if the token isn't a version directive token. (Rude, but fair.)

`fy_scalar_token_get_style`

enum fy_scalar_style fy_scalar_token_get_style(struct fy_token *fyt)

Return the style of a scalar token 🎀

Parameters

fyt (struct fy_token*) – the scalar token.

Description

Retrieves the style of a scalar token. That's the whole assignment ✨.

Return

The scalar style of the token, or FYSS_ANY if there's an error. So yeah, FYSS_ANY is doing double duty as the error signal here — just so you know 💀.

`fy_tag_token_tag`

const struct fy_tag *fy_tag_token_tag(struct fy_token *fyt)

Get the tag of a tag token 🏷️

Parameters

fyt (struct fy_token*) – the tag token.

Description

Retrieves the tag of a tag token. Iconic, lowkey self-explanatory.

Return

A pointer to the tag, or NULL in case of an error.

`fy_tag_directive_token_tag`

const struct fy_tag *fy_tag_directive_token_tag(struct fy_token *fyt)

Get the tag of a tag directive token 💖

Parameters

fyt (struct fy_token*) – the tag directive token.

Description

Retrieves the tag of a tag directive token. Same vibe, different token type 🫶.

Return

A pointer to the tag, or NULL in case of an error.

`fy_event_get_token`

struct fy_token *fy_event_get_token(struct fy_event *fye)

Return the main token of an event ⭐

Parameters

fye (struct fy_event*) – the event you want the main token of.

Description

Retrieves the main token of an event — and like, to be clear, that's the main token, not the tag or the anchor 🙈. It may be NULL in the case of an implicit event.

Return

The main token if it exists, NULL otherwise or in case of an error.

`fy_event_get_anchor_token`

struct fy_token *fy_event_get_anchor_token(struct fy_event *fye)

Return the anchor token of an event 🦋

Parameters

fye (struct fy_event*) – the event you want the anchor token of.

Description

Retrieves the anchor token if it exists ✨. Heads up bestie — this is only valid for mapping/sequence start events and scalar events. Don't come for other event types, it's not giving.

Return

The anchor token if it exists, NULL otherwise or in case of an error.

`fy_event_get_tag_token`

struct fy_token *fy_event_get_tag_token(struct fy_event *fye)

Return the tag token of an event 🎀

Parameters

fye (struct fy_event*) – the event you want the tag token of.

Description

Retrieves the tag token if it exists. Same rule as the anchor one — only valid for mapping/sequence start events and scalar events, got it? 💅

Return

The tag token if it exists, NULL otherwise or in case of an error.

`fy_event_start_mark`

const struct fy_mark *fy_event_start_mark(struct fy_event *fye)

Get the event's start marker 📍

Parameters

fye (struct fy_event*) – the event you want the start marker of.

Description

Returns the event's start marker if it exists ✨. The start marker is the one belonging to the event's main token, fyi.

Return

The event's start marker, NULL if it's not available.

`fy_event_end_mark`

const struct fy_mark *fy_event_end_mark(struct fy_event *fye)

Get the event's end marker 📍

Parameters

fye (struct fy_event*) – the event you want the end marker of.

Description

Returns the event's end marker if it exists 💖. The end marker is the one belonging to the event's main token.

Return

The event's end marker, NULL if it's not available.

`fy_event_style_start_mark`

const struct fy_mark *fy_event_style_start_mark(struct fy_event *fye)

Get the event's start marker — style edition 💅

Parameters

fye (struct fy_event*) – the event you want the style start marker of.

Description

Returns the event's style start marker if it exists ✨. The start marker is the one of the event's main token, including the style marks. But — plot twist — if the event contains a tag, then the start mark is the start of the tag token 👀. So it's giving slightly different energy depending on what's in the event.

Return

The event's start marker, NULL if it's not available.

`fy_event_style_end_mark`

const struct fy_mark *fy_event_style_end_mark(struct fy_event *fye)

Get the event's end marker — style edition 🎀

Parameters

fye (struct fy_event*) – the event you want the end marker of.

Description

Returns the event's style end marker if it exists. The end marker is the one belonging to the event's main token 🌸.

Return

The event's end marker, NULL if it's not available.

`fy_event_get_node_style`

enum fy_node_style fy_event_get_node_style(struct fy_event *fye)

Get the node style of an event 🦋

Parameters

fye (struct fy_event*) – the event you want the node style of.

Description

Returns the node style (FYNS_*) of an event ✨. It may return FYNS_ANY if the event is implicit. And, important detail: for collection start events, the only possible values are FYNS_ANY, FYNS_FLOW, and FYNS_BLOCK 💅. A scalar event, on the other hand, may return any of them. So like, know your event type, bestie.

Return

Hmm — the docs say this returns "the event's end marker, NULL if not available," which is lowkey a copy-paste glitch on their end 😭, but we're reporting it faithfully: that's what it says. (Editor's note: the text literally says "The event's end marker, NULL if not available.")

`fy_document_start_event_version`

const struct fy_version *fy_document_start_event_version(struct fy_event *fye)

Return the version of a document start event 🫶

Parameters

fye (struct fy_event*) – the document start event.

Description

Retrieves the version stored in a document start event ✨.

Return

A pointer to the version, or NULL if there's an error, or if the event isn't a document start event.

`fy_document_state_version`

const struct fy_version *fy_document_state_version(struct fy_document_state *fyds)

Return the version of a document state object 💜

Parameters

fyds (struct fy_document_state*) – the document state object.

Description

Retrieves the version stored in a document state object. Yeah, that's it — she's straightforward and we respect it 🌸.

Return

A pointer to the version, or NULL if something went sideways 😭

`fy_document_state_start_mark`

const struct fy_mark *fy_document_state_start_mark(struct fy_document_state *fyds)

Get the document state's start mark ✨

Parameters

fyds (struct fy_document_state*) — the document state object

Description

Returns the document state's start mark (if it even has one, bestie). Heads up: purely synthetic documents don't contain one, so don't come for me when you get NULL 💅

Return

The document's start marker, or NULL if it's not available.

`fy_document_state_end_mark`

const struct fy_mark *fy_document_state_end_mark(struct fy_document_state *fyds)

Get the document state's end mark 🎀

Parameters

fyds (struct fy_document_state*) — the document state object

Description

Returns the document state's end mark (if it exists). Same deal as before: purely synthetic documents do not contain one, no cap 🫶

Return

The document's end marker, or NULL if it's not available.

`fy_document_state_version_explicit`

bool fy_document_state_version_explicit(struct fy_document_state *fyds)

Was the version explicit? 👀

Parameters

fyds (struct fy_document_state*) — the document state object

Description

Find out if a document state object's version was explicitly set in the document. Note that for synthetic documents this method returns false, periodt.

Return

true if the version was set explicitly, false otherwise

`fy_document_state_tags_explicit`

bool fy_document_state_tags_explicit(struct fy_document_state *fyds)

Were the tags explicit? 🏷️

Parameters

fyds (struct fy_document_state*) — the document state object

Description

Find out if a document state object's tags were explicitly set in the document. And yeah, for synthetic documents this method returns false, iykyk.

Return

true if the document had tags set explicitly, false otherwise

`fy_document_state_start_implicit`

bool fy_document_state_start_implicit(struct fy_document_state *fyds)

Did it start implicitly? 🌸

Parameters

fyds (struct fy_document_state*) — the document state object

Description

Find out if a document state object's document was started implicitly. Note that for synthetic documents this method returns false 💜

Return

true if the document was started implicitly, false otherwise

`fy_document_state_end_implicit`

bool fy_document_state_end_implicit(struct fy_document_state *fyds)

Did it end implicitly? 🦋

Parameters

fyds (struct fy_document_state*) — the document state object

Description

Find out if a document state object's document was ended implicitly. Note that for synthetic documents this method returns false 😌

Return

true if the document was ended implicitly, false otherwise

`fy_document_state_json_mode`

bool fy_document_state_json_mode(struct fy_document_state *fyds)

Was the input JSON? 🔥

Parameters

fyds (struct fy_document_state*) — the document state object

Description

Find out if a document state object's document was created by a JSON input. Note that for synthetic documents this method returns false — say it with me now 📣

Return

true if the document was created in JSON mode, false otherwise

`fy_document_state_tag_directive_iterate`

const struct fy_tag *fy_document_state_tag_directive_iterate(struct fy_document_state *fyds, void **prevp)

Iterate over the tag directives of a document state object 🔁

Parameters

fyds (struct fy_document_state*) — the document state
prevp (void**) — the previous iterator

Description

This method iterates over all the tag directive nodes in the document state object. The start of the iteration is signalled by a NULL in *prevp 💫

Return

The next tag, or NULL at the end of the iteration sequence.

`fy_document_state_tag_directives`

struct fy_tag **fy_document_state_tag_directives(struct fy_document_state *fyds)

Get all the tag directives in a malloc'ed array 🧺

Parameters

fyds (struct fy_document_state*) — the document state

Description

Returns all the tag directives in a dynamically allocated area. Must be free()'d when you're not using it anymore — like, actually free it, bestie, don't just vibe and forget 🙈

Return

An array of fy_tag pointer structures, terminated with a NULL pointer, and NULL on error.

`fy_document_state_tag_is_default`

bool fy_document_state_tag_is_default(struct fy_document_state *fyds, const struct fy_tag *tag)

Test whether the given tag is a default one 🎯

Parameters

fyds (struct fy_document_state*) — the document state
tag (const struct fy_tag*) — the tag to check

Description

Test whether a tag is a default (i.e. implicitly set) one.

Return

true if the tag is a default one, false otherwise

`fy_parser_get_document_state`

struct fy_document_state *fy_parser_get_document_state(struct fy_parser *fyp)

Get the document state of a parser object 🔍

Parameters

fyp (struct fy_parser*) — the parser

Description

Retrieves the document state object of a parser. Note that this is only valid during parsing — like, only while the party's happening 🎉

Return

The active document state object of the parser, NULL otherwise

`fy_document_get_document_state`

struct fy_document_state *fy_document_get_document_state(struct fy_document *fyd)

Get the document state of a document 📄

Parameters

fyd (struct fy_document*) — the document

Description

Retrieves the document state object of a document. Simple as that 💅

Return

The document state object of the document, NULL otherwise

`fy_document_set_document_state`

int fy_document_set_document_state(struct fy_document *fyd, struct fy_document_state *fyds)

Set the document state of a document 🛠️

Parameters

fyd (struct fy_document*) — the document
fyds (struct fy_document_state*) — the document state to use, or NULL for default

Description

Sets the document state of a document. That's the whole gig 🫡

Return

0 if the set operation was successful, -1 otherwise

`fy_document_create_from_event`

struct fy_document *fy_document_create_from_event(struct fy_parser *fyp, struct fy_event *fye)

Create an empty document using the event ✨

Parameters

fyp (struct fy_parser*) — the parser
fye (struct fy_event*) — the event

Description

Create an empty document using the FYET_DOCUMENT_START event generated by the parser. Literally what it says 👑

Return

The created empty document, or NULL on error.

`fy_document_update_from_event`

int fy_document_update_from_event(struct fy_document *fyd, struct fy_parser *fyp, struct fy_event *fye)

Update the document with the event 🔄

Parameters

fyd (struct fy_document*) — the document
fyp (struct fy_parser*) — the parser
fye (struct fy_event*) — the event

Description

Update the document using the FYET_DOCUMENT_END event generated by the parser 🌈

Return

0 on success, -1 on error

`fy_node_create_from_event`

struct fy_node *fy_node_create_from_event(struct fy_document *fyd, struct fy_parser *fyp, struct fy_event *fye)

Create a node using the event 🌱

Parameters

fyd (struct fy_document*) — the document
fyp (struct fy_parser*) — the parser
fye (struct fy_event*) — the event

Description

Create a new node using the supplied event. The allowed events are FYET_SCALAR, FYET_ALIAS, FYET_MAPPING_START & FYET_SEQUENCE_START — anything else is a no 💀

Return

The newly created node, or NULL on error

`fy_node_update_from_event`

int fy_node_update_from_event(struct fy_node *fyn, struct fy_parser *fyp, struct fy_event *fye)

Update a node using the event 🧚

Parameters

fyn (struct fy_node*) — the node
fyp (struct fy_parser*) — the parser
fye (struct fy_event*) — the event

Description

Update information of a node created using fy_node_create_from_event(). The allowed events are FYET_MAPPING_END & FYET_SEQUENCE_END 🎀

Return

0 on success, -1 on error

`fy_node_pair_create_with_key`

struct fy_node_pair *fy_node_pair_create_with_key(struct fy_document *fyd, struct fy_node *fyn_parent, struct fy_node *fyn)

Create a new node pair and set its key 🔑

Parameters

fyd (struct fy_document*) — the document
fyn_parent (struct fy_node*) — the mapping
fyn (struct fy_node*) — the node pair key

Description

Create a new node pair using the supplied fyn_parent mapping and fyn node as a key. Note that the nodes _must_ have been created by fy_node_create_from_event and they are not interchangeable with other node pair methods — like, do not mix them, fr fr 🙅‍♀️

The node pair will be added to the fyn_parent mapping with a subsequent call to fy_node_pair_update_with_value().

Return

The newly created node pair, or NULL on error

`fy_node_pair_update_with_value`

int fy_node_pair_update_with_value(struct fy_node_pair *fynp, struct fy_node *fyn)

Update a node pair with a value and add it to the parent mapping 💖

Parameters

fynp (struct fy_node_pair*) — the node pair
fyn (struct fy_node*) — the node pair value

Description

Update the node pair with the given value and add it to the parent mapping. Note that the fyn node _must_ have been created by fy_node_create_from_event and the node pair created by fy_node_pair_create_with_key(). Do not intermix other node pair manipulation methods, bestie — I'm begging 😭

Return

0 on success, -1 on error

`fy_node_sequence_add_item`

int fy_node_sequence_add_item(struct fy_node *fyn_parent, struct fy_node *fyn)

Add an item node to a sequence node 🧵

Parameters

fyn_parent (struct fy_node*) — the parent sequence node
fyn (struct fy_node*) — the node pair item

Description

Add an item to the end of the sequence node fyn_parent. Note that the fyn_parent and fyn nodes _must_ have been created by fy_node_create_from_event. Do not intermix other sequence node manipulation methods — same rule as before, no exceptions 💅

Return

0 on success, -1 on error

`fy_emitter_get_document_state`

struct fy_document_state *fy_emitter_get_document_state(struct fy_emitter *emit)

Get the document state of an emitter object 📤

Parameters

emit (struct fy_emitter*) — the emitter

Description — Retrieve the document state object of an emitter. Note that this is only valid during emitting, bestie.

Return — The active document state object of the emitter, NULL otherwise.

⚠️ Emitting only. Outside that window? Not it. 💀

`fy_emit_event_create`

struct fy_event *fy_emit_event_create(struct fy_emitter *emit, enum fy_event_type type, ...)

Create an emit event. ✨

Parameters

emit (struct fy_emitter*) — The emitter.
type (enum fy_event_type) — The event type to create.
ellipsis (ellipsis) — The optional extra arguments.

Description — Create an emit event to pass to fy_emit_event(). The extra arguments differ according to the event to be created. So yeah, the varargs are giving “choose your own adventure,” but with YAML event types. 🎀

The extra args go like this, depending on the event:

FYET_STREAM_START
- None.
FYET_STREAM_END
- None.
FYET_DOCUMENT_START
- int implicit — true if document start should be marked implicit, false if document start should not be marked implicit.
- const struct fy_version *vers — Pointer to version to use for the document, or NULL for default.
- const struct fy_tag * const *tags — Pointer to a NULL terminated array of tag pointers (like argv), NULL if no extra tags are to be used.
FYET_DOCUMENT_END
- int implicit — true if document end should be marked implicit, false if document end should not be marked implicit.
FYET_MAPPING_START
- enum fy_node_style style — Style of the mapping (one of FYNS_ANY, FYNS_BLOCK or FYNS_FLOW).
- const char *anchor — Anchor to place at the mapping, or NULL for none.
- const char *tag — Tag to place at the mapping, or NULL for none.
FYET_MAPPING_END
- None.
FYET_SEQUENCE_START
- enum fy_node_style style — Style of the sequence (one of FYNS_ANY, FYNS_BLOCK or FYNS_FLOW).
- const char *anchor — Anchor to place at the sequence, or NULL for none.
- const char *tag — Tag to place at the sequence, or NULL for none.
FYET_SEQUENCE_END
- None.
FYET_SCALAR
- enum fy_scalar_style style — Style of the scalar, any valid FYSS_* value. Note that certain styles may not be used according to the contents of the data.
- const char *value — Pointer to the scalar contents.
- size_t len — Length of the scalar contents, or FY_NT (-1) for strlen(value).
- const char *anchor — Anchor to place at the scalar, or NULL for none.
- const char *tag — Tag to place at the scalar, or NULL for none.
FYET_ALIAS
- const char *value — Pointer to the alias.

Return — The created event or NULL in case of an error.

`fy_emit_event_vcreate`

struct fy_event *fy_emit_event_vcreate(struct fy_emitter *emit, enum fy_event_type type, va_list ap)

Create an emit event using varargs. 🌸

Parameters

emit (struct fy_emitter*) — The emitter.
type (enum fy_event_type) — The event type to create.
ap (va_list) — The variable argument list pointer.

Description — Create an emit event to pass to fy_emit_event(). The varargs are analogous to fy_emit_event_create(). Same energy, just handed a va_list. 🫶

Return — The created event or NULL in case of an error.

`fy_emit_event_free`

void fy_emit_event_free(struct fy_emitter *emit, struct fy_event *fye)

Free an event created via fy_emit_event_create(). 🧹

Parameters

emit (struct fy_emitter*) — The emitter.
fye (struct fy_event*) — The event to free.

Description — Free an event previously created via fy_emit_event_create(). Note that usually you don’t have to call this method since if you pass the event to fy_emit_event() it shall be disposed properly. Its only use is error recovery and cleanup. So like, don’t make freeing your whole personality — it’s an emergency-cleanup kind of function. 💅

`fy_parse_event_create`

struct fy_event *fy_parse_event_create(struct fy_parser *fyp, enum fy_event_type type, ...)

Create an emit event. Yes, that’s literally the one-liner. 👑

Parameters

fyp (struct fy_parser*) — The parser.
type (enum fy_event_type) — The event type to create.
ellipsis (ellipsis) — variable arguments.

Description — See fy_emit_event_create()… 👀

Return — The created event or NULL in case of an error.

`fy_parse_event_vcreate`

struct fy_event *fy_parse_event_vcreate(struct fy_parser *fyp, enum fy_event_type type, va_list ap)

Create an emit event using varargs. ⭐

Parameters

fyp (struct fy_parser*) — The parser.
type (enum fy_event_type) — The event type to create.
ap (va_list) — The variable argument list pointer.

Description — Create an emit event to pass to fy_emit_event(). The varargs are analogous to fy_parse_event_create(). 🦋

Return — The created event or NULL in case of an error.

🌸 PATH EXECUTION 🌸

okay so this header is where it gets fun — it gives you the ypath subsystem, which is basically a JSONPath / XPath-style query language for navigating your YAML document trees 🦋. iykyk, it's a whole vibe.

A ypath expression like /servers/0/host gets parsed first into a compiled struct fy_path_expr, and then it's executed against a starting node in any struct fy_document to produce a result set of matching nodes. Filter predicates and wildcards are also supported — slay 💅.

Typical workflow, bestie, follow along:

// 1. Create a path parser
struct fy_path_parser *fypp = fy_path_parser_create(NULL);

// 2. Compile an expression
struct fy_path_expr *expr =
    fy_path_parse_expr_from_string(fypp, "/servers/0/host", -1);

// 3. Create an executor and run the expression
struct fy_path_exec *fypx = fy_path_exec_create(NULL);
fy_path_exec_execute(fypx, expr, fy_document_root(fyd));

// 4. Iterate results
void *iter = NULL;
struct fy_node *fyn;
while ((fyn = fy_path_exec_results_iterate(fypx, &iter)) != NULL)
    process(fyn);

// 5. Cleanup
fy_path_exec_destroy(fypx);
fy_path_expr_free(expr);
fy_path_parser_destroy(fypp);

For one-shot use, fy_path_expr_build_from_string() wraps steps 1 and 2 into a single call — so convenient, honestly 🫶.

The executor can be reset and re-used for multiple executions against the same or different documents. The compiled expression is independent of any document and may be executed repeatedly. no cap, it's reusable like that ✨.

🎀 enum fy_path_parse_cfg_flags 🎀

enum fy_path_parse_cfg_flags — Path parse configuration flags 💖

Definition

enum fy_path_parse_cfg_flags {
    FYPPCF_QUIET,
    FYPPCF_DISABLE_RECYCLING,
    FYPPCF_DISABLE_ACCELERATORS
};

Constants

FYPPCF_QUIET — Quiet mode, so it doesn't output any information messages 🤫
FYPPCF_DISABLE_RECYCLING — Disable the recycling optimization ♻️
FYPPCF_DISABLE_ACCELERATORS — Disable use of access accelerators (this one saves memory 💾)

Description

These flags control the operation of the path parse. periodt.

🌈 struct fy_path_parse_cfg 🌈

struct fy_path_parse_cfg — the path parser configuration structure 👑

Definition

struct fy_path_parse_cfg {
    enum fy_path_parse_cfg_flags flags;
    void *userdata;
    struct fy_diag *diag;
}

Members

flags — Configuration flags ✨
userdata — Opaque user data pointer 🫧
diag — Optional diagnostic interface to use 🩺

Description

This is the argument to the fy_path_parser_create() method, which is what performs parsing of a ypath expression. it's giving config-central 💅.

💜 fy_path_parser_create 💜

struct fy_path_parser *fy_path_parser_create(const struct fy_path_parse_cfg *cfg)

Create a ypath parser 🌟

Parameters

cfg (*const struct fy_path_parse_cfg**) — The configuration for the path parser

Description

Creates a path parser with its configuration cfg. The path parser may be destroyed by a corresponding call to fy_path_parser_destroy(). If cfg is NULL a default yaml parser is created 🎀.

Return

A pointer to the path parser, or NULL in case of an error 😭.

🦋 fy_path_parser_destroy 🦋

void fy_path_parser_destroy(struct fy_path_parser *fypp)

Destroy the given path parser 💀

Parameters

fypp (*struct fy_path_parser**) — The path parser to destroy

Description

Destroys a path parser that you created earlier via fy_path_parser_create(). clean up after yourself bestie 🧹.

⭐ fy_path_parser_reset ⭐

int fy_path_parser_reset(struct fy_path_parser *fypp)

Reset a path parser completely 🔄

Parameters

fypp (*struct fy_path_parser**) — The path parser to reset

Description

Completely resets a path parser — including after an error that caused a parser error to be emitted. like a fresh start, we love that for you 🌸.

Return

0 if the reset was successful, -1 otherwise.

🍓 fy_path_parse_expr_from_string 🍓

struct fy_path_expr *fy_path_parse_expr_from_string(struct fy_path_parser *fypp, const char *str, size_t len)

Parse an expression from a given string ✍️

Parameters

fypp (*struct fy_path_parser**) — The path parser to use
str (*const char**) — The ypath source to use.
len (size_t) — The length of the string (or -1 if '0' terminated)

Description

Creates a path expression from a string, using the path parser you hand it 🫶.

Return

The created path expression, or NULL on error 😭.

🧚 fy_path_expr_build_from_string 🧚

struct fy_path_expr *fy_path_expr_build_from_string(const struct fy_path_parse_cfg *pcfg, const char *str, size_t len)

Parse an expression from a given string (the one-shot version, icon behavior) ✨

Parameters

pcfg (*const struct fy_path_parse_cfg**) — The path parser configuration to use, or NULL for default
str (*const char**) — The ypath source to use.
len (size_t) — The length of the string (or -1 if '0' terminated)

Description

Creates a path expression from a string using the provided path parser configuration 🎀.

Return

The created path expression, or NULL on error 😭.

🌸 fy_path_expr_free 🌸

void fy_path_expr_free(struct fy_path_expr *expr)

Free a path expression 🗑️

Parameters

expr (*struct fy_path_expr**) — The expression to free (may be NULL)

Description

Frees a previously returned expression from any of the path parser methods, like fy_path_expr_build_from_string(). and yes, NULL is fine, it handles it 💅.

👑 fy_path_expr_dump 👑

void fy_path_expr_dump(struct fy_path_expr *expr, struct fy_diag *diag, enum fy_error_type errlevel, int level, const char *banner)

Dump the contents of a path expression to the diagnostic object 📜

Parameters

expr (*struct fy_path_expr**) — The expression to dump
diag (*struct fy_diag**) — The diagnostic object to use
errlevel (enum fy_error_type) — The error level which the diagnostic will use
level (int) — The nest level; should be set to 0
banner (*const char**) — The banner to display on level 0

Description

Dumps the expression using the provided error level. perfect for when you're like "what is this even doing" 🙈.

🔥 fy_path_expr_to_document 🔥

struct fy_document *fy_path_expr_to_document(struct fy_path_expr *expr)

Converts the path expression to a YAML document 📄

Parameters

expr (*struct fy_path_expr**) — The expression to convert to a document

Description

Converts the expression to a YAML document, which is genuinely so useful for understanding what the expression evaluates to 👀. it's giving debug mode.

Return

The document of the expression, or NULL on error 😭.

🎀 enum fy_path_exec_cfg_flags 🎀

enum fy_path_exec_cfg_flags — Path executor configuration flags 💖

Definition

enum fy_path_exec_cfg_flags {
    FYPXCF_QUIET,
    FYPXCF_DISABLE_RECYCLING,
    FYPXCF_DISABLE_ACCELERATORS
};

Constants

FYPXCF_QUIET — Quiet, do not output any information messages 🤫
FYPXCF_DISABLE_RECYCLING — Disable recycling optimization ♻️
FYPXCF_DISABLE_ACCELERATORS — Disable use of access accelerators (saves memory 💾)

Description

These flags control the operation of the path expression executor. periodt.

🌈 struct fy_path_exec_cfg 🌈

struct fy_path_exec_cfg — the path expression executor configuration structure 👑

Definition

struct fy_path_exec_cfg {
    enum fy_path_exec_cfg_flags flags;
    void *userdata;
    struct fy_diag *diag;
}

Members

flags — Configuration flags ✨
userdata — Opaque user data pointer 🫧
diag — Optional diagnostic interface to use 🩺

Description

This is the argument to the fy_path_exec_create() method, which is what performs execution of a ypath expression 💅.

💜 fy_path_exec_create 💜

struct fy_path_exec *fy_path_exec_create(const struct fy_path_exec_cfg *xcfg)

Create a ypath expression executor 🌟

Parameters

xcfg (*const struct fy_path_exec_cfg**) — The configuration for the executor

Description

Creates a ypath expression parser with its configuration cfg. The executor may be destroyed by a corresponding call to fy_path_exec_destroy(). (yes the manpage says cfg here even though the param is xcfg — we don't make the rules, we just report them 🙈)

Return

A pointer to the executor, or NULL in case of an error 😭.

🦋 fy_path_exec_destroy 🦋

void fy_path_exec_destroy(struct fy_path_exec *fypx)

Destroy the given path expression executor 💀

Parameters

fypx (*struct fy_path_exec**) — The path parser to destroy

Description

Destroys an executor created earlier via fy_path_exec_create(). (the manpage literally says "Destroy ane executor" — typo and all, we keep it, that's the lore 🫶)

⭐ fy_path_exec_reset ⭐

int fy_path_exec_reset(struct fy_path_exec *fypx)

Reset an executor 🔄

Parameters

fypx (*struct fy_path_exec**) — The executor to reset

Description

Completely resets an executor, without releasing it. reuse szn 💅.

Return

0 if the reset was successful, -1 otherwise.

🍓 fy_path_exec_execute 🍓

int fy_path_exec_execute(struct fy_path_exec *fypx, struct fy_path_expr *expr, struct fy_node *fyn_start)

Execute a path expression starting at the given start node 🚀

Parameters

fypx (*struct fy_path_exec**) — The executor to use
expr (*struct fy_path_expr**) — The expression to use
fyn_start (*struct fy_node**) — The node on which the expression will begin.

Description

Executes the expression starting at fyn_start. If execution is successful, the results are available via fy_path_exec_results_iterate() ✨.

⚠️ heads up bestie: it is illegal to modify the state of the document that the results reside in between this call and the results collection. like, do not touch it. seriously. 💀

Return

0 if the execution was successful, -1 otherwise.

Note that the execution may be successful but no results were produced, in which case the iterator will return NULL 🙈. (successful but empty, we've all been there)

🧚 fy_path_exec_results_iterate 🧚

struct fy_node *fy_path_exec_results_iterate(struct fy_path_exec *fypx, void **prevp)

Iterate over the results of execution 🔁

Parameters

fypx (*struct fy_path_exec**) — The executor
prevp (void**) — The previous result iterator

Description

This method iterates over all the results in the executor. The start of the iteration is signalled by a NULL in *prevp 🎀.

Return

The next node in the result set, or NULL at the end of the results 🏁.

🦋 DOCUMENT ITERATION 🦋

okay so this header provides struct fy_document_iterator, which traverses a document tree depth-first without using system stack recursion — no stack overflow era, we love to see it 🙌. Two usage modes are supported:

Node iteration — visit every node in a subtree in document order:

struct fy_document_iterator *fydi = fy_document_iterator_create();
fy_document_iterator_node_start(fydi, fy_document_root(fyd));
struct fy_node *fyn;
while ((fyn = fy_document_iterator_node_next(fydi)) != NULL)
    process(fyn);
fy_document_iterator_destroy(fydi);

Event replay — regenerate the YAML event stream that produced the document, suitable for feeding into a parser, emitter, or composer:

struct fy_document_iterator *fydi =
    fy_document_iterator_create_on_document(fyd);
struct fy_event *fye;
while ((fye = fy_document_iterator_generate_next(fydi)) != NULL) {
    process_event(fye);
    fy_document_iterator_event_free(fydi, fye);
}
fy_document_iterator_destroy(fydi);

The iterator can also be attached to a struct fy_parser via fy_parser_set_document_iterator(), making a parser transparently replay the events of an existing document rather than parsing fresh input. obsessed with the convenience, honestly 💅

Events emitted by the iterator are in the same order as those that originally created the document, so round-trip fidelity is preserved. no cap, the round-trip stays iconic ✨

🎀 `enum fy_document_iterator_cfg_flags`

Document iterator configuration flags 🫶

📌 Definition

enum fy_document_iterator_cfg_flags {
    FYDICF_WANT_BODY_EVENTS,
    FYDICF_WANT_DOCUMENT_BODY_EVENTS,
    FYDICF_WANT_STREAM_DOCUMENT_BODY_EVENTS
};

🌈 Constants

FYDICF_WANT_BODY_EVENTS — Generate body events
FYDICF_WANT_DOCUMENT_BODY_EVENTS — Generate document and body events
FYDICF_WANT_STREAM_DOCUMENT_BODY_EVENTS — Generate stream, document and body events

💬 Description

These flags control the operation of the document iterator. tiny flags, big main-character energy 👑

🧚 `struct fy_document_iterator_cfg`

document iterator configuration structure. 🫶

📌 Definition

struct fy_document_iterator_cfg {
    enum fy_document_iterator_cfg_flags flags;
    struct fy_document *fyd;
    struct fy_node *iterate_root;
}

🧩 Members

flags — The document iterator flags
fyd — The document to iterate on (or NULL if iterate_root is set)
iterate_root — The root of iteration (NULL when fyd is not NULL)

💬 Description

Argument to the fy_document_iterator_create_cfg() method. it's giving config struct realness 💜

🦋 `fy_document_iterator_create`

struct fy_document_iterator *fy_document_iterator_create(void)

Create a document iterator 💖

🎯 Parameters

void — no arguments

💬 Description

Creates a document iterator, that can trawl through a document without using recursion. no recursion, just vibes ✨

🔁 Return

The newly created document iterator or NULL on error

🌸 `fy_document_iterator_create_cfg`

struct fy_document_iterator *fy_document_iterator_create_cfg(const struct fy_document_iterator_cfg *cfg)

Create a document iterator using config 🎀

🎯 Parameters

cfg (const struct fy_document_iterator_cfg*) — The document iterator to destroy

not me side-eyeing that parameter description 💀 but yes, that is genuinely what it says.

💬 Description

Creates a document iterator, that can trawl through a document without using recursion. The iterator will generate all the events that created the given document starting at iterator root. it literally replays the lore of the document 🫶

🔁 Return

The newly created document iterator or NULL on error

🦋 `fy_document_iterator_create_on_document`

struct fy_document_iterator *fy_document_iterator_create_on_document(struct fy_document *fyd)

Create a document iterator on document ✨

🎯 Parameters

fyd (struct fy_document*) — The document to iterate on

💬 Description

Creates a document iterator, starting at the root of the given document. root node first, obviously 💅

🔁 Return

The newly created document iterator or NULL on error

🌈 `fy_document_iterator_create_on_node`

struct fy_document_iterator *fy_document_iterator_create_on_node(struct fy_node *fyn)

Create a document iterator on node 🦋

🎯 Parameters

fyn (struct fy_node*) — The node to iterate on

💬 Description

Creates a document iterator, starting at the given node. pick your starting point, bestie 🎯

🔁 Return

The newly created document iterator or NULL on error

💅 `fy_document_iterator_destroy`

void fy_document_iterator_destroy(struct fy_document_iterator *fydi)

Destroy the given document iterator 💀

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to destroy

💬 Description

Destroy a document iterator created earlier via fy_document_iterator_create(). cleanup era, we love to see it 🧹

🎀 `fy_document_iterator_event_free`

void fy_document_iterator_event_free(struct fy_document_iterator *fydi, struct fy_event *fye)

Free an event that was created by a document iterator 🫶

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator that created the event
fye (struct fy_event*) — The event

💬 Description

Free (possibly recycling) an event that was created by a document iterator. recycling? we love sustainability ♻️

⭐ `fy_document_iterator_stream_start`

struct fy_event *fy_document_iterator_stream_start(struct fy_document_iterator *fydi)

Create a stream start event using the iterator 🌟

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to create the event

💬 Description

Creates a stream start event on the document iterator and advances the internal state of it accordingly. state machine go brrr ⚙️

🔁 Return

The newly created stream start event, or NULL on error.

🌟 `fy_document_iterator_stream_end`

struct fy_event *fy_document_iterator_stream_end(struct fy_document_iterator *fydi)

Create a stream end event using the iterator 🌈

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to create the event

💬 Description

Creates a stream end event on the document iterator and advances the internal state of it accordingly. wrap it up, stream edition 🎬

🔁 Return

The newly created stream end event, or NULL on error.

🧚 `fy_document_iterator_document_start`

struct fy_event *fy_document_iterator_document_start(struct fy_document_iterator *fydi, struct fy_document *fyd)

Create a document start event using the iterator 📄

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to create the event
fyd (struct fy_document*) — The document containing the document state that is used in the event

💬 Description

Creates a document start event on the document iterator and advances the internal state of it accordingly. The document must not be released until an error, cleanup or a call to fy_document_iterator_document_end(). do not release it early, bestie — that's a whole mess 😭

🔁 Return

The newly created document start event, or NULL on error.

🎬 `fy_document_iterator_document_end`

struct fy_event *fy_document_iterator_document_end(struct fy_document_iterator *fydi)

Create a document end event using the iterator 🏁

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to create the event

💬 Description

Creates a document end event on the document iterator and advances the internal state of it accordingly. The document that was used earlier in the call of fy_document_iterator_document_start() can now be released. okay NOW you may release it, periodt 💅

🔁 Return

The newly created document end event, or NULL on error.

🍓 `fy_document_iterator_body_next`

struct fy_event *fy_document_iterator_body_next(struct fy_document_iterator *fydi)

Create document body events until the end 🍓

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to create the event

💬 Description

Creates the next document body, depth first until the end of the document. The events are created depth first and are in same exact sequence that the original events that created the document.

That means that the finite event stream that generated the document is losslesly preserved in such a way that the document tree representation is functionally equivalent. the lore is preserved, fr fr 📚

Repeated calls to this function will generate a stream of SCALAR, ALIAS, SEQUENCE START, SEQUENCE END, MAPPING START and MAPPING END events, returning NULL at the end of the body event stream.

🔁 Return

The newly created document body event or NULL at an error, or an end of the event stream. Use fy_document_iterator_get_error() to check if an error occured. vibe check the error state if something smells off 👀

🦋 `fy_document_iterator_node_start`

void fy_document_iterator_node_start(struct fy_document_iterator *fydi, struct fy_node *fyn)

Start a document node iteration run using a starting point 🎯

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to run with
fyn (struct fy_node*) — The iterator root for the iteration

💬 Description

Starts an iteration run starting at the given node. set the starting point and let it cook 🍳

🌈 `fy_document_iterator_node_next`

struct fy_node *fy_document_iterator_node_next(struct fy_document_iterator *fydi)

Return the next node in the iteration sequence 🧚

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to use for the iteration

💬 Description

Returns a pointer to the next node iterating using as a start the node given at fy_document_iterator_node_start(). The first node returned will be that, followed by all the remaing nodes in the subtree. first the root, then the whole subtree — iconic traversal behavior 🌳

🔁 Return

The next node in the iteration sequence or NULL at the end, or if an error occured.

⭐ `fy_document_iterator_generate_next`

struct fy_event *fy_document_iterator_generate_next(struct fy_document_iterator *fydi)

Create events from document iterator ✨

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to create the event

💬 Description

This is a method that will handle the complex state of generating stream, document and body events on the given iterator. the multitasking icon of this API 👑

When generation is complete a NULL event will be generated.

🔁 Return

The newly created event or NULL at an error, or an end of the event stream. Use fy_document_iterator_get_error() to check if an error occured. again: check the error state, bestie 🔍

💜 `fy_document_iterator_get_error`

bool fy_document_iterator_get_error(struct fy_document_iterator *fydi)

Get the error state of the document iterator 🚨

🎯 Parameters

fydi (struct fy_document_iterator*) — The document iterator to use for checking it’s error state.

💬 Description

Returns the error state of the iterator. If it’s in error state, return true and reset the iterator to the state just after creation. error state detected? reset and pretend it never happened, main character move 💅

🔁 Return

true if it was in an error state, false otherwise. 💖

🌟 `enum fy_parser_event_generator_flags` 🌟

ok so this enum is literally just a vibe check for which events the generator should make. three options, no notes 💅

enum fy_parser_event_generator_flags {
    FYPEGF_GENERATE_DOCUMENT_EVENTS,
    FYPEGF_GENERATE_STREAM_EVENTS,
    FYPEGF_GENERATE_ALL_EVENTS
};

the constants 🎀

FYPEGF_GENERATE_DOCUMENT_EVENTS — generate document events
FYPEGF_GENERATE_STREAM_EVENTS — generate stream events
FYPEGF_GENERATE_ALL_EVENTS — generate all events

🛠️ `fy_parser_set_document_iterator`

int fy_parser_set_document_iterator(struct fy_parser *fyp, enum fy_parser_event_generator_flags flags, struct fy_document_iterator *fydi)

Associate a parser with a document iterator

Parameters 🌸

fyp (struct fy_parser*) — The parser
flags (enum fy_parser_event_generator_flags) — The event generation flags
fydi (struct fy_document_iterator*) — The document iterator to associate

Description 💖

okay so you're basically setting up a situationship between a parser and a document iterator — instead of the parser doing the parsing itself, the events get generated by the document iterator instead. iconic delegation, ngl.

Return ✨

0 on success, -1 on error

📦 DOCUMENT BUILDER 📦

This header provides struct fy_document_builder, which accumulates YAML parser events and assembles them into a struct fy_document tree. it's giving arts-and-crafts but for YAML 🎨

The builder supports two operating modes:

Pull mode — the builder drives a parser internally:

struct fy_document_builder *fydb =
    fy_document_builder_create_on_parser(fyp);
struct fy_document *fyd;
while ((fyd = fy_document_builder_load_document(fydb, fyp)) != NULL) {
    process(fyd);
    fy_document_destroy(fyd);
}
fy_document_builder_destroy(fydb);

Push mode — the caller feeds events one at a time and takes ownership when the document is complete:

fy_document_builder_set_in_stream(fydb);
struct fy_event *fye;
while ((fye = get_next_event()) != NULL) {
    fy_document_builder_process_event(fydb, fye);
    if (fy_document_builder_is_document_complete(fydb)) {
        struct fy_document *fyd =
            fy_document_builder_take_document(fydb);
        process(fyd);
        fy_document_destroy(fyd);
    }
}

Push mode is the move when events arrive asynchronously or from a source other than a libfyaml parser — like a document iterator or a network stream. main character energy for sure 🦋

fy_parse_load_document_with_builder() provides the simplest interface: literally one single call that returns the next complete document from a parser. ate and left no crumbs 💅

🧱 `struct fy_document_builder_cfg`

document builder configuration structure.

Definition

struct fy_document_builder_cfg {
    struct fy_parse_cfg parse_cfg;
    void *userdata;
    struct fy_diag *diag;
}

Members 👑

parse_cfg — Parser configuration
userdata — Opaque user data pointer
diag — Optional diagnostic interface to use

Description 💜

Argument to the fy_document_builder_create() method

🐣 `fy_document_builder_create`

struct fy_document_builder *fy_document_builder_create(const struct fy_document_builder_cfg *cfg)

Create a document builder

Parameters 🌈

cfg (const struct fy_document_builder_cfg*) — The configuration for the document builder

Description ✨

Creates a document builder with its configuration cfg. The document builder may be destroyed by a corresponding call to fy_document_builder_destroy().

Return 🫶

A pointer to the document builder or NULL in case of an error.

🧚 `fy_document_builder_create_on_parser`

struct fy_document_builder *fy_document_builder_create_on_parser(struct fy_parser *fyp)

Create a document builder pulling state from the parser

Parameters 💫

fyp (struct fy_parser*) — The parser to associate with

Description 🌸

Creates a document builder pulling state from the given parser

Return ⭐

A pointer to the document builder or NULL in case of an error.

🔄 `fy_document_builder_reset`

void fy_document_builder_reset(struct fy_document_builder *fydb)

Reset a document builder

Parameters 🎀

fydb (struct fy_document_builder*) — The document builder

Description 💅

Resets a document builder without destroying it — a little factory reset, but it keeps the builder alive. we love a soft launch.

💀 `fy_document_builder_destroy`

void fy_document_builder_destroy(struct fy_document_builder *fydb)

Destroy a document builder

Parameters 😭

fydb (struct fy_document_builder*) — The document builder

Description 🔥

Destroy a document builder. it's over bestie, say bye.

📄 `fy_document_builder_get_document`

struct fy_document *fy_document_builder_get_document(struct fy_document_builder *fydb)

Get the document of a builder

Parameters 🦋

fydb (struct fy_document_builder*) — The document builder

Description 🌟

Retrieve the document of a document builder. heads up though — this document may be incomplete. If you need to take ownership use fy_document_builder_take_document(). don't be out here acting like it's finished, it's not 😤

Return 💖

The document that the builder built, or NULL in case of an error

🌊 `fy_document_builder_is_in_stream`

bool fy_document_builder_is_in_stream(struct fy_document_builder *fydb)

Test document builder in stream

Parameters 🧵

fydb (struct fy_document_builder*) — The document builder

Description ✨

Find out if the document builder is in 'stream' state — i.e. after stream start but before stream end events are generated. the in-between era, the liminal space, the "we're so back but also not yet" moment.

Return 🫶

true if in stream, false otherwise

📑 `fy_document_builder_is_in_document`

bool fy_document_builder_is_in_document(struct fy_document_builder *fydb)

Test document builder in document

Parameters 💜

fydb (struct fy_document_builder*) — The document builder

Description 🌸

Find out if the document builder is in 'document' state — i.e. after document start but before document end events are generated.

Return ⭐

true if in document, false otherwise

✅ `fy_document_builder_is_document_complete`

bool fy_document_builder_is_document_complete(struct fy_document_builder *fydb)

Test document builder complete

Parameters 🎀

fydb (struct fy_document_builder*) — The document builder

Description 💫

Find out if the document of the builder is complete. and if it is complete, then a call to fy_document_builder_take_document() will transfer ownership of the document to the caller. that's the glow-up moment right there.

Return 🌈

true if document complete, false otherwise

🫴 `fy_document_builder_take_document`

struct fy_document *fy_document_builder_take_document(struct fy_document_builder *fydb)

Take ownership the document of a builder

Parameters 👑

fydb (struct fy_document_builder*) — The document builder

Description 💖

Take ownership of the document of a document builder. the document builder's document must be complete — like, non-negotiable, fr fr.

Return ✨

The document that the builder built, or NULL in case of an error

👀 `fy_document_builder_peek_document`

struct fy_document *fy_document_builder_peek_document(struct fy_document_builder *fydb)

Peek at the document of a builder

Parameters 🌸

fydb (struct fy_document_builder*) — The document builder

Description 🦋

Peek at the document of a document builder. Ownership still remains with the builder — so like, look, don't touch 💅

Return 🎀

A peek to the document that the builder built, or NULL in case of an error

🌊 `fy_document_builder_set_in_stream`

void fy_document_builder_set_in_stream(struct fy_document_builder *fydb)

Set the builders state in 'stream'

Parameters 🧚

fydb (struct fy_document_builder*) — The document builder

Description 💫

Set the document builders state to in 'stream'

📑 `fy_document_builder_set_in_document`

int fy_document_builder_set_in_document(struct fy_document_builder *fydb, struct fy_document_state *fyds, bool single)

Set the builders state in 'document'

Parameters 🌟

fydb (struct fy_document_builder*) — The document builder
fyds (struct fy_document_state*) — The document state
single (bool) — Single document mode

Description 🔥

Set the document builders state to in 'document'

Return ⭐

0 on success, -1 on error

📥 `fy_document_builder_load_document`

struct fy_document *fy_document_builder_load_document(struct fy_document_builder *fydb, struct fy_parser *fyp)

Create a document from parser events

Parameters 💜

fydb (struct fy_document_builder*) — The document builder
fyp (struct fy_parser*) — The parser

Description 🌈

Load a document by pumping the parser for events and then processing them with the builder. pump it, process it, slay it.

Return 🫶

The document that results from the parser, or NULL in case of an error (or EOF)

🏗️ `fy_parse_load_document_with_builder`

struct fy_document *fy_parse_load_document_with_builder(struct fy_parser *fyp)

Parse a document via built-in builder

Parameters ✨

fyp (struct fy_parser*) — The parser

Description 🌸

Load a document by pumping the parser for events and then processing them with the in-parser builder. the builder's already in there, you don't gotta bring your own 💅

Return 🎀

The document that results from the parser, or NULL in case of an error (or EOF)

⚡ `fy_document_builder_process_event`

int fy_document_builder_process_event(struct fy_document_builder *fydb, struct fy_event *fye)

Process an event with a builder

Parameters 🦋

fydb (struct fy_document_builder*) — The document builder
fye (struct fy_event*) — The event

Description 💫

Pump an event to a document builder for processing.

Return ⭐

0 on success, -1 on error

🎼 COMPOSER 🎼

This header provides two complementary interfaces for processing YAML event streams with awareness of the current position in the document hierarchy — and the best part? no commitment to building a full in-memory tree required. we're just vibing through the events, not moving in 🧚

Simple callback interface — fy_parse_compose() calls a user function for each event, passing both the event and the current struct fy_path so the callback can make intelligent decisions without maintaining its own path stack:

enum fy_composer_return my_cb(struct fy_parser *fyp,
                              struct fy_event *fye,
                              struct fy_path *path,
                              void *userdata)
{
    if (fy_path_depth(path) > 3)
        return FYCR_OK_START_SKIP;
    process(fye);
    return FYCR_OK_CONTINUE;
}
fy_parse_compose(fyp, my_cb, ctx);

Object-based interface — struct fy_composer is literally the same mechanism but wrapped in a reusable object, bestie 💅. It's got ops callbacks, optional document builder integration, and helpers for navigating the path hierarchy. Same energy, cuter packaging.

Path inspection helpers — functions like fy_path_in_mapping(), fy_path_depth(), fy_path_component_is_sequence(), plus those user-data attach/retrieve pairs, let your callbacks annotate and query the live path stack with zero external bookkeeping. No mental notes app needed, we love to see it 🫶.

Callbacks control event processing by returning one of:

FYCR_OK_CONTINUE — consume the event and continue
FYCR_OK_STOP — consume the event and stop
FYCR_OK_START_SKIP — start skipping the current subtree
FYCR_OK_STOP_SKIP — stop an active skip and resume processing
FYCR_ERROR — abort with an error

🎀 `enum fy_composer_return`

enum fy_composer_return — the returns of the composer callback, aka the vibe check for your whole event loop ✨

Definition

enum fy_composer_return {
    FYCR_OK_CONTINUE,
    FYCR_OK_STOP,
    FYCR_OK_START_SKIP,
    FYCR_OK_STOP_SKIP,
    FYCR_ERROR
};

Constants

FYCR_OK_CONTINUE — continue processing, event processed 💖
FYCR_OK_STOP — stop processing, event processed
FYCR_OK_START_SKIP — start skip object(s), event processed
FYCR_OK_STOP_SKIP — stop skipping of objects, event processed
FYCR_ERROR — error, stop processing 💀

🌸 `fy_composer_return_is_ok`

bool fy_composer_return_is_ok(enum fy_composer_return ret)

Check if the return code is OK. Literally just "is this fine or not" 🧚

Parameters

ret (enum fy_composer_return) – the composer return to check

Description

Convenience method for checking if it's OK to continue.

Return

true if non error or skip condition.

🦋 `typedef fy_parse_composer_cb`

enum fy_composer_return fy_parse_composer_cb(struct fy_parser *fyp,
                                             struct fy_event *fye,
                                             struct fy_path *path,
                                             void *userdata)

Composer callback method — the main character of this whole section, no cap 👑

Parameters

fyp (struct fy_parser*) – The parser
fye (struct fy_event*) – The event
path (struct fy_path*) – The path that the parser is processing
userdata (void*) – The user data of the fy_parse_compose() method

Description

This method is called by the fy_parse_compose() method when an event must be processed.

Return

fy_composer_return code telling the parser what to do.

🌈 `fy_parse_compose`

int fy_parse_compose(struct fy_parser *fyp, fy_parse_composer_cb cb,
                     void *userdata)

Parse using a compose callback. It's giving ✨ alternative timeline ✨.

Parameters

fyp (struct fy_parser*) – The parser
cb (fy_parse_composer_cb) – The callback that will be called
userdata (void*) – user pointer to pass to the callback

Description

Alternative parsing method using a composer callback.

The parser will construct a path argument that is used by the callback to make intelligent decisions about creating a document and/or DOM. Big brain behavior fr fr 🧠

Return

0 if no error occured, -1 on error.

💜 `fy_path_component_is_mapping`

bool fy_path_component_is_mapping(struct fy_path_component *fypc)

Check if the component is a mapping 🔍

Parameters

fypc (struct fy_path_component*) – The path component to check

Return

true if the path component is a mapping, false otherwise.

⭐ `fy_path_component_is_sequence`

bool fy_path_component_is_sequence(struct fy_path_component *fypc)

Check if the component is a sequence 🌟

Parameters

fypc (struct fy_path_component*) – The path component to check

Return

true if the path component is a sequence, false otherwise.

🍓 `fy_path_component_sequence_get_index`

int fy_path_component_sequence_get_index(struct fy_path_component *fypc)

Get the index of sequence path component — like, which slot are we in, bestie? 🔢

Parameters

fypc (struct fy_path_component*) – The sequence path component to return it's index value

Return

>= 0 the sequence index, -1 if the component is either not in the proper mode, or not a sequence.

🎀 `fy_path_component_mapping_get_scalar_key`

struct fy_token *fy_path_component_mapping_get_scalar_key(struct fy_path_component *fypc)

Get the scalar key of a mapping 🔑

Parameters

fypc (struct fy_path_component*) – The mapping path component to return it's scalar key

Return

a non NULL scalar or alias token if the mapping contains a scalar key, NULL in case of an error, or if the component has a complex key.

🌸 `fy_path_component_mapping_get_scalar_key_tag`

struct fy_token *fy_path_component_mapping_get_scalar_key_tag(struct fy_path_component *fypc)

Get the scalar key's tag of a mapping 🏷️

Parameters

fypc (struct fy_path_component*) – The mapping path component to return it's scalar key's tag

Return

a non NULL tag token if the mapping contains a scalar key with a tag or NULL in case of an error, or if the component has a complex key.

🦋 `fy_path_component_mapping_get_complex_key`

struct fy_document *fy_path_component_mapping_get_complex_key(struct fy_path_component *fypc)

Get the complex key of a mapping — this is the fancy one, iykyk 💅

Parameters

fypc (struct fy_path_component*) – The mapping path component to return it's complex key

Return

a non NULL document if the mapping contains a complex key, NULL in case of an error, or if the component has a simple key.

✨ `fy_path_component_get_text`

char *fy_path_component_get_text(struct fy_path_component *fypc)

Get the textual representation of a path component 📝

Parameters

fypc (struct fy_path_component*) – The path component to get it's textual representation

Description

Given a path component, return a malloc'ed string which contains the textual representation of it.

Note that this method will only return fully completed components and not ones that are in the building process. Mid-build components are not invited to the group chat 🙈

Return

The textual representation of the path component, NULL on error, or if the component has not been completely built during the composition of a complex key. The string must be free'ed using free.

⚠️ Yes bestie, you own that memory — free it or it's a leak, and leaks are not the vibe.

🔥 `fy_path_depth`

int fy_path_depth(struct fy_path *fypp)

Get the depth of a path — how deep are we in this YAML rabbit hole 🕳️

Parameters

fypp (struct fy_path*) – The path to query

Return

The depth of the path, or -1 on error.

🌈 `fy_path_parent`

struct fy_path *fy_path_parent(struct fy_path *fypp)

Get the parent of a path 👩‍👧

Parameters

fypp (struct fy_path*) – The path to return it's parent

Description

Paths may contain parents when traversing complex keys. This method returns the immediate parent.

Return

The path parent or NULL on error, if it doesn't exist.

💖 `fy_path_get_text`

char *fy_path_get_text(struct fy_path *fypp)

Get the textual representation of a path ✍️

Parameters

fypp (struct fy_path*) – The path to get it's textual representation

Description

Given a path, return a malloc'ed string which contains the textual representation of it.

Note that during processing, complex key paths are simply indicative and not to be used for addressing. Like, they're decorative, not functional, okay? 🎀

Return

The textual representation of the path, NULL on error. The string must be free'ed using free.

🌟 `fy_path_in_root`

bool fy_path_in_root(struct fy_path *fypp)

Check if the path is in the root of the document 🌱

Parameters

fypp (struct fy_path*) – The path

Return

true if the path is located within the root of the document.

🎀 `fy_path_in_mapping`

bool fy_path_in_mapping(struct fy_path *fypp)

Check if the path is in a mapping 🗺️

Parameters

fypp (struct fy_path*) – The path

Return

true if the path is located within a mapping.

🦋 `fy_path_in_sequence`

bool fy_path_in_sequence(struct fy_path *fypp)

Check if the path is in a sequence 📋

Parameters

fypp (struct fy_path*) – The path

Return

true if the path is located within a sequence.

🔑 `fy_path_in_mapping_key`

bool fy_path_in_mapping_key(struct fy_path *fypp)

Check if the path is in a mapping key state 🔍

Parameters

fypp (struct fy_path*) – The path

Return

true if the path is located within a mapping key state.

💎 `fy_path_in_mapping_value`

bool fy_path_in_mapping_value(struct fy_path *fypp)

Check if the path is in a mapping value state 🎁

Parameters

fypp (struct fy_path*) – The path

Return

true if the path is located within a mapping value state.

🌸 `fy_path_in_collection_root`

bool fy_path_in_collection_root(struct fy_path *fypp)

Check if the path is in a collection root 🏛️

Parameters

fypp (struct fy_path*) – The path

Description

A collection root state is when the path points to a sequence or mapping but the state does not allow setting keys, values or adding items.

This occurs on MAPPING/SEQUENCE START/END events.

Return

true if the path is located within a collection root state.

🫶 `fy_path_get_root_user_data`

void *fy_path_get_root_user_data(struct fy_path *fypp)

Return the userdata associated with the path root 📦

Parameters

fypp (struct fy_path*) – The path

Return

The user data associated with the root of the path, or NULL if no path.

💜 `fy_path_set_root_user_data`

void fy_path_set_root_user_data(struct fy_path *fypp, void *data)

Set the user data associated with the root 🧸

Parameters

fypp (struct fy_path*) – The path
data (void*) – The data to set as root data

Description

Note, no error condition if not a path. Chill, it just doesn't do anything 💅

🍓 `fy_path_component_get_mapping_user_data`

void *fy_path_component_get_mapping_user_data(struct fy_path_component *fypc)

Return the userdata associated with the mapping 📬

Parameters

fypc (struct fy_path_component*) – The path component

Return — the user data that's chillin' with that mapping, or NULL if it's not a mapping at all, or if the user data itself is NULL 🫶

✨ `fy_path_component_get_mapping_key_user_data` ✨

void *fy_path_component_get_mapping_key_user_data(struct fy_path_component *fypc)

Returns the userdata that's attached to the mapping key, bestie 🔑

Parameters

fypc (struct fy_path_component *) — the path component

Return — the user data hanging out with the mapping key, or NULL if it's not a mapping or the user data is NULL 💅

🎀 `fy_path_component_get_sequence_user_data` 🎀

void *fy_path_component_get_sequence_user_data(struct fy_path_component *fypc)

Returns the userdata that's attached to the sequence 🌸

Parameters

fypc (struct fy_path_component *) — the path component

Return — the user data chilling with the sequence, or NULL if it's not a sequence or the user data is NULL ✨

🦋 `fy_path_component_set_mapping_user_data` 🦋

void fy_path_component_set_mapping_user_data(struct fy_path_component *fypc, void *data)

Sets the user data associated with a mapping 💖

Parameters

fypc (struct fy_path_component *) — the path component
data (void *) — the data to set as mapping data

Description

Heads up: there's no error condition if it's not a mapping. It just... does its thing 🙈

🔥 `fy_path_component_set_mapping_key_user_data` 🔥

void fy_path_component_set_mapping_key_user_data(struct fy_path_component *fypc, void *data)

Sets the user data associated with a mapping key 🔑

Parameters

fypc (struct fy_path_component *) — the path component
data (void *) — the data to set as mapping key data

Description

Again, no error condition if you're not in a mapping key state. Zero drama, zero complaints 💅

🌈 `fy_path_component_set_sequence_user_data` 🌈

void fy_path_component_set_sequence_user_data(struct fy_path_component *fypc, void *data)

Sets the user data associated with a sequence 🌸

Parameters

fypc (struct fy_path_component *) — the path component
data (void *) — the data to set as sequence data

Description

Same deal: no error condition if it's not a sequence 🫶

⭐ `fy_path_get_parent_user_data` ⭐

void *fy_path_get_parent_user_data(struct fy_path *path)

Returns the userdata of the parent collection 👑

Parameters

path (struct fy_path *) — the path

Return — the user data belonging to the parent collection of the path, or NULL if there's no path 😭

💜 `fy_path_set_parent_user_data` 💜

void fy_path_set_parent_user_data(struct fy_path *path, void *data)

Sets the user data associated with the parent collection 🎀

Parameters

path (struct fy_path *) — the path
data (void *) — the data to set as parent collection data

Description

And yeah — no error condition if there's no path. It's giving "unbothered" ✨

🍓 `fy_path_get_last_user_data` 🍓

void *fy_path_get_last_user_data(struct fy_path *path)

Returns the userdata of the last collection 🔥

Parameters

path (struct fy_path *) — the path

Return — the user data belonging to the last collection of the path, or NULL if there's no path 💀

🧚 `fy_path_set_last_user_data` 🧚

void fy_path_set_last_user_data(struct fy_path *path, void *data)

Sets the user data associated with the last collection 💖

Parameters

path (struct fy_path *) — the path
data (void *) — the data to set as last collection data

Description

Once more for the people in the back: no error condition if there's no path 🙈

👑 `fy_path_last_component` 👑

struct fy_path_component *fy_path_last_component(struct fy_path *fypp)

Gets the very last component of a path — like, the final girl of the path hierarchy 💅

Parameters

fypp (struct fy_path *) — the path

Description

Returns the last component of a path.

Return — the last path component (which, yes, may be a collection root component), or NULL if it doesn't exist 😭

🦋 `fy_path_last_not_collection_root_component` 🦋

struct fy_path_component *fy_path_last_not_collection_root_component(struct fy_path *fypp)

Gets the last non collection root component of a path 🌸

Parameters

fypp (struct fy_path *) — the path

Description

Returns the last non collection root component of a path. And heads up — this may not be the last component that fy_path_last_component() hands you 👀

The difference shows up on MAPPING/SEQUENCE START/END events, where the last component is present but not usable as an object parent. Awkward, but that's the vibe 💀

Return — the last non collection root component, or NULL if it doesn't exist ✨

🎀 `struct fy_composer_ops` 🎀

struct fy_composer_ops — the composer operation callbacks, i.e. the main character energy of the composer 👑

Definition

struct fy_composer_ops {
    enum fy_composer_return (*process_event)(struct fy_composer *fyc, struct fy_path *path, struct fy_event *fye);
    struct fy_document_builder *(*create_document_builder)(struct fy_composer *fyc);
}

Members

process_event — callback for processing a single YAML event with path context 🔥
create_document_builder — callback for creating a document builder instance 🛠️

Description

These are the callbacks the composer uses to process events and create document builders 💖

🦋 `struct fy_composer_cfg` 🦋

struct fy_composer_cfg — the composer configuration structure, the whole setup ✨

Definition

struct fy_composer_cfg {
    const struct fy_composer_ops *ops;
    void *userdata;
    struct fy_diag *diag;
}

Members

ops — pointer to composer operation callbacks 🎀
userdata — opaque user data pointer that gets passed to callbacks 💫
diag — optional diagnostic interface to use; NULL means default 🌸

Description

Configuration structure for creating a composer instance. Iconic, honestly 💅

⭐ `fy_composer_create` ⭐

struct fy_composer *fy_composer_create(struct fy_composer_cfg *cfg)

Creates a composer ✨

Parameters

cfg (struct fy_composer_cfg *) — the configuration for the composer

Description

Creates a composer with the given configuration. The composer processes YAML events using callback methods and keeps path information around so it can do intelligent document composition 🧠✨ The composer may be destroyed by a corresponding call to fy_composer_destroy().

Return — a pointer to the composer, or NULL in case of an error 😭

💀 `fy_composer_destroy` 💀

void fy_composer_destroy(struct fy_composer *fyc)

Destroys the given composer 🫶

Parameters

fyc (struct fy_composer *) — the composer to destroy

Description

Destroys a composer that you created earlier via fy_composer_create(). Closure, bestie 💅

🔥 `fy_composer_process_event` 🔥

enum fy_composer_return fy_composer_process_event(struct fy_composer *fyc, struct fy_event *fye)

Runs a YAML event through the composer 🎬

Parameters

fyc (struct fy_composer *) — the composer
fye (struct fy_event *) — the event to process

Description

Processes a YAML event by calling the configured process_event callback with path context. The composer maintains the current path and hands it to the callback so it can make intelligent processing decisions 👑

Return — a fy_composer_return code saying how to proceed (continue, stop, skip, or error) 💫

🌸 `fy_composer_get_cfg` 🌸

struct fy_composer_cfg *fy_composer_get_cfg(struct fy_composer *fyc)

Gets the configuration of a composer 🎀

Parameters

fyc (struct fy_composer *) — the composer

Return — the configuration of the composer ✨

💜 `fy_composer_get_cfg_userdata` 💜

void *fy_composer_get_cfg_userdata(struct fy_composer *fyc)

Gets the userdata from the composer configuration 🫶

Parameters

fyc (struct fy_composer *) — the composer

Description

Retrieves that opaque userdata pointer from the composer's configuration 💫

Return — the userdata pointer from the configuration ⭐

🧚 `fy_composer_get_diag` 🧚

struct fy_diag *fy_composer_get_diag(struct fy_composer *fyc)

Gets the diagnostic object of a composer 🩺

Parameters

fyc (struct fy_composer *) — the composer to get the diagnostic object

Description

Returns a pointer to the diagnostic object of a composer object. Important though: the returned diag object has a reference taken, so you should fy_diag_unref() it when you're done with it. Don't leave it hanging, that's a leak and it's not cute 🙈

Return — a pointer to a ref'ed diagnostic object, or NULL in case of an error 😭

🌈 `fy_composer_get_path` 🌈

struct fy_path *fy_composer_get_path(struct fy_composer *fyc)

Gets the current path of the composer 📍

Parameters

fyc (struct fy_composer *) — the composer

Description

Retrieves the current path being processed by the composer. The path represents the location in the YAML document structure where the composer is currently positioned — like a little "you are here" map 🗺️

Return — the current path, or NULL if no path is active 💀

🍓 `fy_composer_get_root_path` 🍓

struct fy_path *fy_composer_get_root_path(struct fy_composer *fyc)

Gets the root path of the composer 👑

Parameters

fyc (struct fy_composer *) — the composer

Description

Retrieves the root path of the composer's path hierarchy — the origin story 🌱

Return — the root path, or NULL if no root exists 😭

🎀 `fy_composer_get_next_path` 🎀

struct fy_path *fy_composer_get_next_path(struct fy_composer *fyc, struct fy_path *fypp)

Gets the next path in the composer's path list ➡️

Parameters

fyc (struct fy_composer *) — the composer
fypp (struct fy_path *) — the previous path, or NULL to get the first path

Description

Iterates through the composer's path list. Pass NULL to get the first path, or pass the previous path to get the next one. It's a whole scroll session, fr fr 💅

Return — the next path in the list, or NULL if no more paths exist 💀

📜 COPYRIGHT 📜

2019-2026, Pantelis Antoniou — respect the author, no cap 👑💖

and that's a wrap on LIBFYAML-CORE(3) bestie!! 🎉 this was the Mar 15, 2026 edition of the page, go forth and compose your YAML with main character energy 🦋✨💅

📦 where this page comes from

nixpkgs unstable: libfyaml 0.9.6
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms