Public API

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

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

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. 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* need explicit cleanup calls at the end of program execution, even if you’ve never called any of their functions.

This method will make sure it calls their cleanup functions so that no memory leaks are reported in valgrind etc.

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_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_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

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.

Definition

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

Members

search_path

Search path when accessing files, seperate with ‘:’

flags

Configuration flags

userdata

Opaque user data pointer

diag

Optional diagnostic interface to use

Description

Argument to the fy_parser_create() method which perform parsing of YAML files.

enum fy_event_type

enum fy_event_type

Event types

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

FYET_STREAM_START

Stream start event

FYET_STREAM_END

Stream end event

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)

Return text of an event type

Parameters:

• type (enum fy_event_type) – The event type to get text from

Return

A pointer to a text, i.e for FYET_SCALAR “=VAL”.

enum fy_scalar_style

enum fy_scalar_style

Scalar styles supported by the parser/emitter

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. Lets the emitter to 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

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

doument start event data

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. information about the YAML version and configured tags)

implicit

True if the document started implicitly

struct fy_event_document_end_data

struct fy_event_document_end_data

doument end event data

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 definining this alias.

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 (cannot be NULL)

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

Event generated by the parser

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, it is valid when fy_event->type is enum FYET_STREAM_START

stream_end

Stream end information, it is valid when fy_event->type is enum FYET_STREAM_END

document_start

Document start information, it is valid when fy_event->type is enum FYET_DOCUMENT_START

document_end

Document end information, it is valid when fy_event->type is enum FYET_DOCUMENT_END

alias

Alias information, it is valid when fy_event->type is enum FYET_ALIAS

scalar

Scalar information, it is valid when fy_event->type is enum FYET_SCALAR

sequence_start

Sequence start information, it is valid when fy_event->type is enum FYET_SEQUENCE_START

sequence_end

Sequence end information, it is valid when fy_event->type is enum FYET_SEQUENCE_END

mapping_start

Mapping start information, it is valid when fy_event->type is enum FYET_MAPPING_START

mapping_end

Mapping end information, it is valid when fy_event->type is enum FYET_MAPPING_END

Description

This structure is generated by the parser by each call to fy_parser_parse() and release by fy_parser_event_free()

enum fy_event_part

enum fy_event_part

Select part of the event

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)

Get the event’s type

Parameters:

• fye (const struct fy_event*) – The event

Description

Return 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)

Get a pointer to the event data

Parameters:

• fye (struct fy_event*) – The event

Description

Some languages cough*golang*cough really don’t like unions, and anonymous unions in particular.

You should not have to use this in other language bindings.

Return

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

fy_library_version

const char *fy_library_version(void)

Return the library version string

Parameters:

• void – no arguments

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)

Return the error type from a string

Parameters:

• str (const char*) – The string to convert to an error type

Return

The error type if greater or equal to zero, FYET_MAX otherwise

fy_error_type_to_string

const char *fy_error_type_to_string(enum fy_error_type type)

Convert an error type to string

Parameters:

• type (enum fy_error_type) – The error type to convert

Return

The string value of the error type or the empty string “” on error

fy_string_to_error_module

enum fy_error_module fy_string_to_error_module(const char *str)

Return the error module from a string

Parameters:

• str (const char*) – The string to convert to an error module

Return

The error type if greater 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 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)

Check whether the given event is an implicit one

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)

Check whether the given document event is an implicit one

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.

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.

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().

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

Parameters:

• fyp (struct fy_parser*) – The parser to destroy

Description

Destroy a parser created earlier via fy_parser_create().

fy_parser_get_cfg

const struct fy_parse_cfg *fy_parser_get_cfg(struct fy_parser *fyp)

Get the configuration of a parser

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

Description

Return 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.

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

Parameters:

• fyp (struct fy_parser*) – The parser to replace the diagnostic object

• 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.

Return

0 if everything OK, -1 otherwise

fy_parser_reset

int fy_parser_reset(struct fy_parser *fyp)

Reset a parser completely

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.

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 to 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 will must be available.

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 to the given (NULL terminated) string. Note that while the parser is active the string must not go out of scope.

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.

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 to 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.

In case of an error the string is not freed.

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.

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

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.

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().

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.

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.

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

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. Parser must already be in a sequence state. Note that this uses backtracking so it might not be very efficient.

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.

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. Parser must already be in a mapping state. Note that this uses backtracking so it might not be very efficient.

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

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().

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

Parameters:

• fyp (struct fy_parser*) – The parser

Description

Retrieve the current mode of the parser, which indicates the YAML version or format being parsed (YAML 1.1, 1.2, 1.3, or JSON).

Return

The parser mode

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 parsers diagnostics printf style (va_arg)

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

Output a log on the parser diagnostic output

fy_parser_log

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

Log using the parsers 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

Output a report on the parser’s diagnostics

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 parsers diagnostics printf style and mark token (va_arg)

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

Output a report on the parser and indicate the token’s position

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 parsers diagnostics printf style and mark 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

Output a report on the parser and indicate the token’s position

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 to get it’s style. Note that a NULL token is a enum FYSS_PLAIN.

Return

The scalar style of the token, or FYSS_PLAIN on each other case

fy_token_scalar_is_null

bool fy_token_scalar_is_null(struct fy_token *fyt)

Test whether the scalar is null (content)

Parameters:

• fyt (struct fy_token*) – The scalar token to check for NULLity.

Description

Note that this is different than null of the YAML type system. It is null as in null content. It is also different than an empty scalar.

Return

true if is a null scalar, false otherwise

fy_token_get_text

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

Get text (and length of it) of a token

Parameters:

• fyt (struct fy_token*) – The token out of which the text pointer will be returned.

• 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 token along with the length of it. Note that this text is not NULL terminated. If you need a NULL terminated pointer use fy_token_get_text0().

In case that the token is ‘simple’ enough (i.e. a plain scalar) or something similar the returned pointer is a direct pointer to the space of the input that contains the token.

That means that the pointer is not guaranteed to be valid after the parser is destroyed.

If the token is ‘complex’ enough, then space shall be allocated, filled and returned.

Note that the concept of ‘simple’ and ‘complex’ is vague, and that’s on purpose.

Return

A pointer to the text representation of the token, while lenp will be 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 out of which the text pointer will be returned.

Description

This method will return a pointer to the text of a token which is zero terminated. It will allocate memory to hold it in the token structure so try to use fy_token_get_text() instead if possible.

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 length of the text of a token

Parameters:

• fyt (struct fy_token*) – The token

Description

This method will return the length of the text representation of a token.

Return

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

fy_token_get_utf8_length

size_t fy_token_get_utf8_length(struct fy_token *fyt)

Get length of the text of a token

Parameters:

• fyt (struct fy_token*) – The token

Description

This method will return the length of the text representation of a token as a utf8 string.

Return

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

enum fy_comment_placement

enum fy_comment_placement

Comment placement relative to token

Definition

enum fy_comment_placement {
    fycp_top,
    fycp_right,
    fycp_bottom
};

Constants

fycp_top

Comment on top of token

fycp_right

Comment to the right of the token

fycp_bottom

Comment to the bottom of the token

fy_token_get_comment

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

Get zero terminated comment of a token

Parameters:

• fyt (struct fy_token*) – The token out of which the comment text will be returned.

• buf (char*) – The buffer to be filled with the contents of the token

• maxsz (size_t) – The maximum size of the comment buffer

• which (enum fy_comment_placement) – The comment placement

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.

struct fy_iter_chunk

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.

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

Create an iterator for operating on the given token, or a generic iterator for use with fy_token_iter_start(). The iterator must be destroyed with a matching call to fy_token_iter_destroy().

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

Destroy the iterator created by fy_token_iter_create().

fy_token_iter_start

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

Start iterating over the contents of a token

Parameters:

• fyt (struct fy_token*) – The token to iterate over

• iter (struct fy_token_iter*) – The iterator to prepare.

Description

Prepare an iterator for operating on the given token. The iterator must be created via a previous call to fy_token_iter_create() for user level API access.

fy_token_iter_finish

void fy_token_iter_finish(struct fy_token_iter *iter)

Stop iterating over the contents of a token

Parameters:

• iter (struct fy_token_iter*) – The iterator.

Description

Stop the iteration operation.

fy_token_iter_peek_chunk

const struct fy_iter_chunk *fy_token_iter_peek_chunk(struct fy_token_iter *iter)

Peek at the next iterator chunk

Parameters:

• iter (struct fy_token_iter*) – The iterator.

Description

Peek at the next iterator chunk

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)

Get next iterator chunk

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

Get the next iterator chunk in sequence,

Return

A pointer to the next iterator chunk, or NULL in case there’s no other. When the return value is NULL, the errp variable will be filled with 0 for normal end, or -1 in case of an error.

fy_token_iter_advance

void fy_token_iter_advance(struct fy_token_iter *iter, size_t len)

Advance the iterator position

Parameters:

• iter (struct fy_token_iter*) – The iterator.

• len (size_t) – Number of bytes to advance the iterator position

Description

Advance the read pointer of the iterator. Note that 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.

fy_token_iter_read

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

Read a block from an iterator

Parameters:

• iter (struct fy_token_iter*) – The iterator.

• buf (void*) – Pointer to a block of memory to receive the data. Must be at least count bytes long.

• count (size_t) – Amount of bytes to read.

Description

Read a block from an iterator. Note than mixing calls of this and any of the ungetc methods leads to undefined behavior.

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)

Get a single character from an iterator

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. If any calls to ungetc have pushed a character in the iterator it shall return that.

Return

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

fy_token_iter_ungetc

int fy_token_iter_ungetc(struct fy_token_iter *iter, int c)

Ungets a single character from an iterator

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. 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.

Return

The pushed back character given as argument, or -1 in case of an error. 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 single character from an iterator

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 in the iterator it shall return that. The character is not removed from the iterator stream.

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)

Get a single utf8 character from an iterator

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 in 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)

Ungets a single utf8 character from an iterator

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.

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)

Peeks at single utf8 character from an iterator

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 in the iterator it shall return that. 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)

Parse the next document from the parser stream

Parameters:

• fyp (struct fy_parser*) – The parser

Description

This method performs parsing on a parser stream and returns the next document. This means that for a compound document with multiple documents, each call will return the next document.

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)

Destroy a document created by fy_parse_load_document()

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)

Resolve anchors and merge keys

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 (<<)

Return

zero on success, -1 on error

fy_document_has_directives

bool fy_document_has_directives(const struct fy_document *fyd)

Document directive check

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)

Explicit document start check

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 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)

Explicit document end 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 document has an explicit document end marker, false if not

fy_node_document

struct fy_document *fy_node_document(struct fy_node *fyn)

Retreive the document the node belong to

Parameters:

• fyn (struct fy_node*) – The node to retreive it’s 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 member of a document.

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

Definition

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

fyewt_document_indicator

Output chunk is a document indicator

fyewt_tag_directive

Output chunk is a tag directive

fyewt_version_directive

Output chunk is a version directive

fyewt_indent

Output chunk is a document indicator

fyewt_indicator

Output chunk is an indicator

fyewt_whitespace

Output chunk is white space

fyewt_plain_scalar

Output chunk is a plain scalar

fyewt_single_quoted_scalar

Output chunk is a single quoted scalar

fyewt_double_quoted_scalar

Output chunk is a double quoted scalar

fyewt_literal_scalar

Output chunk is a literal block scalar

fyewt_folded_scalar

Output chunk is a folded block scalar

fyewt_anchor

Output chunk is an anchor

fyewt_tag

Output chunk is a tag

fyewt_linebreak

Output chunk is a linebreak

fyewt_alias

Output chunk is an alias

fyewt_terminating_zero

Output chunk is a terminating zero

fyewt_plain_scalar_key

Output chunk is an plain scalar key

fyewt_single_quoted_scalar_key

Output chunk is an single quoted scalar key

fyewt_double_quoted_scalar_key

Output chunk is an double quoted scalar key

fyewt_comment

Output chunk is a comment

fyewt_indicator_question_mark

? indicator

fyewt_indicator_colon

: indicator

fyewt_indicator_dash

• indicator

fyewt_indicator_left_bracket

[ indicator

fyewt_indicator_right_bracket

] indicator

fyewt_indicator_left_brace

{ indicator

fyewt_indicator_right_brace

} indicator

fyewt_indicator_comma

, indicator

fyewt_indicator_bar

indicator

fyewt_indicator_greater

> indicator

fyewt_indicator_single_quote_start

‘ indicator

fyewt_indicator_single_quote_end

‘ indicator

fyewt_indicator_double_quote_start

“ indicator

fyewt_indicator_double_quote_end

“ indicator

fyewt_indicator_ambersand

& indicator

fyewt_indicator_star

• indicator

fyewt_indicator_chomp

chomp indicator (- or +)

fyewt_indicator_explicit_indent

explicit indent indicator (0-9)

Description

Describes the kind of emitted output, which makes it possible to colorize the output, or do some other content related filtering.

enum fy_emitter_cfg_flags

enum fy_emitter_cfg_flags

Emitter configuration flags

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 key when emitting

FYECF_OUTPUT_COMMENTS

Output comments (experimental)

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

Do not output ending new line (useful for single line mode)

FYECF_STRIP_EMPTY_KV

Remove all keys with empty values from the output (not available in streaming mode)

FYECF_EXTENDED_CFG

Extend configuration, this config structure is 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

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 (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

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

Argument to the fy_emitter_create() method which is the way to convert a runtime document structure back to YAML.

enum fy_emitter_xcfg_flags

enum fy_emitter_xcfg_flags

Emitter extended configuration flags

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_VISIBLE_WS,
    FYEXCF_EXTENDED_INDICATORS
};

Constants

FYEXCF_COLOR_AUTO

Automatically colorize if on a terminal

FYEXCF_COLOR_NONE

Do not colorize output

FYEXCF_COLOR_FORCE

Force color generation

FYEXCF_OUTPUT_STDOUT

Output to stdout (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_VISIBLE_WS

Make white space visible

FYEXCF_EXTENDED_INDICATORS

Extend the indicators generated

Description

These flags control the operation of the emitter. If no extended configuration mode is enabled all the flags are assumed 0.

struct fy_emitter_xcfg

struct fy_emitter_xcfg

emitter extended configuration structure.

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;
    } ;
}

Members

cfg

The standard emitter configuration

xflags

Extra configuration flags

colors

ANSI color overrides for the default output method

{unnamed_union}

anonymous

output_fp

The output FILE *, FYEXCF_FILE_OUTPUT must be set

output_fd

The output file descriptor, FYEXCF_FD_OUTPUT must be set

Description

Argument to the fy_emitter create when FYECF_EXTENDED_CFG bit is set.

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 supplied configuration

Return

The newly created emitter or NULL on error.

fy_emitter_destroy

void fy_emitter_destroy(struct fy_emitter *emit)

Destroy an emitter

Parameters:

• emit (struct fy_emitter*) – The emitter to destroy

Description

Destroy an emitter previously created by fy_emitter_create()

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

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

Description

Return 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.

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

• diag (struct fy_diag*) – The emitter’s new diagnostic object, NULL for default

Description

Replace the emitters’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.

Return

0 if everything 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

• finalizer (void (*)(struct fy_emitter *emit)) – The finalizer callback

Description

Set a method callback to be called when the emitter is disposed of. If finalizer is NULL, then the method is removed.

struct fy_emitter_default_output_data

struct fy_emitter_default_output_data

emitter default output configuration

Definition

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

Members

fp

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)

Description

This is the argument to the default output method of the emitter.

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) – 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. Will be used when the output field of the emitter configuration is NULL.

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 the file points to a tty.

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

Queue and output using the emitter. This is the streaming output method which does not require creating a document.

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

Queue and output using the emitter. The format is identical to the one used in fy_emit_event_vcreate().

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

Queue and output using the emitter. The format is identical to the one used in fy_emit_event_create().

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

Queue and output using the emitter a scalar using a standard write interface.

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

Queue and output using the emitter a scalar using a standard vprintf interface.

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

Queue and output using the emitter a scalar using a standard printf interface.

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

Queue and output 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.

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.

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 document start using the emitter

Parameters:

• emit (struct fy_emitter*) – The emitter

• fyd (struct fy_document*) – The document to use for emitting it’s start

• fyn (struct fy_node*) – The root (or NULL for using the document’s root)

Description

Emits a document start using the emitter. This is used in case you need finer control over the emitting output.

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

Emits a document end using the emitter. This is used in case you need 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 a single node using the emitter. This is used in case you need finer control over the emitting output.

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 using the emitter. This is used in case 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 using the emitter. This is used in case you need finer control over the emitting output. No stream and document events will be generated at all.

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. … . Use this if you you need finer control over the emitting output.

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 an 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 from the root to the given file pointer.

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 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 given file. The file will be 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 given file descriptor

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 an document from the root to the given buffer. If the document does not fit, an error will be returned.

Return

A positive number, which is the size of the emitted document on 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 an document from the root to a string which will be dynamically allocated.

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 to the given buffer. If the document does not fit, an error will be returned.

Return

A positive number, which is the size of the emitted node on 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 to a string which will be dynamically allocated.

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 for buffer output. Calls to fy_emit_event() populate the buffer. The contents are retreived by 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 the emitter which was created by fy_emit_to_buffer() and populated using fy_emit_event() calls. The NULL terminated returned buffer is the same as the one used in the fy_emit_to_buffer() call and the sizep argument will be 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 for output to a dynamically allocated string. Calls to fy_emit_event() populate the buffer. The contents are retreived by 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 the emitter which was 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(). The sizep argument will be filled with the size of the buffer.

Return

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

fy_emitter_vlog

void fy_emitter_vlog(struct fy_emitter *emit, enum fy_error_type type, const char *fmt, va_list ap)

Log using the emitters diagnostics printf style (va_arg)

Parameters:

• emit (struct fy_emitter*) – The emitter

• type (enum fy_error_type) – The error type

• fmt (const char*) – The printf format string

• ap (va_list) – The argument list

Description

Output a log on the emitter diagnostic output

fy_emitter_log

void fy_emitter_log(struct fy_emitter *emit, enum fy_error_type type, const char *fmt, ...)

Log using the emitters diagnostics printf style

Parameters:

• emit (struct fy_emitter*) – The emitter

• type (enum fy_error_type) – The error type

• fmt (const char*) – The printf format string

• ellipsis (ellipsis) – The extra arguments

Description

Output a report on the emitter’s diagnostics

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

Make a deep copy of a node, associating the copy with the given document. Note that no content copying takes place as the contents of the nodes are reference counted. This means that the operation is relatively inexpensive.

Note that the copy includes all anchors contained in the subtree of the source, so this call will register them with the document.

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

Clone a document, by making a deep copy of the source. Note that no content copying takes place as the contents of the nodes are reference counted. This means that the operation is relatively inexpensive.

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 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.

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.

Return

0 on success, -1 on error

enum fy_node_type

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

enum fy_node_style

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.

enum fy_node_walk_flags

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.

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. 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

Description

Compare a node for equality with a token. Both the node and the tokens must be a scalars.

Return

true if the node and the token are equal.

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 to use in the comparison

• text (const char*) – The raw C text to compare against

• len (size_t) – The length of the text (or -1 if ‘0’ terminated)

Description

Compare a node for equality with a raw C string. The node must be a scalar.

Return

true if the node and the text are equal.

fy_document_create

struct fy_document *fy_document_create(const struct fy_parse_cfg *cfg)

Create an empty document

Parameters:

• cfg (const struct fy_parse_cfg*) – The parse configuration to use or NULL for the default.

Description

Create an empty document using the provided parser configuration. If NULL use the default parse configuration.

Return

The 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

Destroy a document (along with all children documents)

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

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

Description

Return a pointer to the diagnostic object of a document object. Note that the returned diag object has a reference taken so you should fy_diag_unref() it when you’re done with it.

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 to replace the diagnostic object

• diag (struct fy_diag*) – The document’s new diagnostic object, NULL for default

Description

Replace the documents’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.

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

Parameters:

• fyd (struct fy_document*) – The parent document

• fyd_child (struct fy_document*) – The child document

Description

Set the parent of fyd_child document to be fyd

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

Create a document parsing the provided string as a YAML source.

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

Create a document parsing the provided string as a YAML source. The string is expected to have been allocated by malloc(3) and when the document is destroyed it will be automatically freed.

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

Create a document parsing the provided file as a YAML source.

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

Create a document parsing the provided file pointer as a YAML source.

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

Create a document parsing the provided string as a YAML source. The string is created by applying vprintf formatting.

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

Create a document parsing the provided string as a YAML source. The string is created by applying printf formatting.

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

Create a document parsing the provided string as a YAML source.

The document is a flow document, i.e. 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 is important because parsing stops at the end of it, and so can be placed in other non-yaml content.

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

Create a document parsing the provided string as a YAML source.

The document is a block document, and it terminates when indentation appears to do so.

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.

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

Set the root of a document. If the document was not empty the old root will be freed. 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

Retrieve the node type. It is one of FYNT_SCALAR, FYNT_SEQUENCE or FYNT_MAPPING. A NULL node argument is a FYNT_SCALAR.

Return

The node type

fy_node_get_style

enum fy_node_style fy_node_get_style(struct fy_node *fyn)

Get the node style

Parameters:

• fyn (struct fy_node*) – The node

Description

Retrieve the node rendering style. If the node is NULL then the style is FYNS_PLAIN.

Return

The node style

fy_node_get_start_token

struct fy_token *fy_node_get_start_token(struct fy_node *fyn)

Get the node start token

Parameters:

• fyn (struct fy_node*) – The node

Description

Retrieve the node start token.

For scalars, this is the same as the end token.

Return

The node start token

fy_node_get_end_token

struct fy_token *fy_node_get_end_token(struct fy_node *fyn)

Get the node end token

Parameters:

• fyn (struct fy_node*) – The node

Description

Retrieve the node end token.

For scalars, this is the same as the start token.

Return

The node end token

fy_node_is_scalar

bool fy_node_is_scalar(struct fy_node *fyn)

Check whether the node is a scalar

Parameters:

• fyn (struct fy_node*) – The node

Description

Convenience method for checking whether a node is a scalar.

Return

true if the node is a scalar, false otherwise

fy_node_is_sequence

bool fy_node_is_sequence(struct fy_node *fyn)

Check whether the node is a sequence

Parameters:

• fyn (struct fy_node*) – The node

Description

Convenience method for checking whether a node is a sequence.

Return

true if the node is a sequence, false otherwise

fy_node_is_mapping

bool fy_node_is_mapping(struct fy_node *fyn)

Check whether the node is a mapping

Parameters:

• fyn (struct fy_node*) – The node

Description

Convenience method for checking whether a node is a mapping.

Return

true if the node is a mapping, false otherwise

fy_node_is_alias

bool fy_node_is_alias(struct fy_node *fyn)

Check whether the node is an alias

Parameters:

• fyn (struct fy_node*) – The node

Description

Convenience method for checking whether a node is an alias.

Return

true if the node is an alias, false otherwise

fy_node_is_null

bool fy_node_is_null(struct fy_node *fyn)

Check whether the node is a NULL

Parameters:

• fyn (struct fy_node*) – The node

Description

Convenience method for checking whether a node is a NULL scalar.. Note that a NULL node argument returns true…

Return

true if the node is a NULL scalar, false otherwise

fy_node_is_attached

bool fy_node_is_attached(struct fy_node *fyn)

Check whether the node is attached

Parameters:

• fyn (struct fy_node*) – The node

Description

Checks whether a node is attached in a document structure. An attached node may not be freed, before being detached. Note that there is no method that explicitly detaches a node, since this is handled internaly by the sequence and mapping removal methods.

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)

Gets the tag token of a node (if it exists)

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

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)

Gets the scalar token of a node (if it exists)

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. Note that aliases are scalars, so if this call is issued on an alias node the return shall be of an alias token.

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)

Resolve an alias node

Parameters:

• fyn (struct fy_node*) – The alias node to be resolved

Description

Resolve an alias node, following any subsequent aliases until a non alias node has been found. This call performs cycle detection and excessive redirections checks so it’s safe to call in any context.

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)

Dereference a single alias node

Parameters:

• fyn (struct fy_node*) – The alias node to be dereferenced

Description

Dereference an alias node. This is different than resolution in that will only perform a single alias follow call and it will fail if the input is not an alias. This call 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)

Free a node

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.

This method will return an error if the node is attached, or if not NULL it is not a member of a document.

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

Create a node 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)

Create a node using the provided YAML source which was malloced.

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

Create a node parsing the provided string as a YAML source. The node created will be associated with the provided document. The string is expected to have been allocated by malloc(3) and when the document is destroyed it will be automatically freed.

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)

Create a node using the provided YAML file.

Parameters:

• fyd (struct fy_document*) – The document

• file (const char*) – The name of the file to parse

Description

Create a node 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)

Create a node using the provided file pointer.

Parameters:

• fyd (struct fy_document*) – The document

• fp (FILE*) – The file pointer

Description

Create a node 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

Create a node parsing the resulting string as a YAML source. The string is created by applying vprintf formatting.

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

Create a node parsing the resulting string as a YAML source. The string is created by applying printf formatting.

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

Description

This method will retrieve a node relative to the given node using the provided path spec.

Path specs are comprised of keys seperated by slashes ‘/’. Keys are either regular YAML expressions in flow format for traversing mappings, or indexes in brackets for traversing sequences. Path specs may start with ‘/’ which is silently ignored.

A few examples will make this clear:

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

Note that 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 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

Retrieve the given node’s path address relative to the document root. The address is dynamically allocated and should be freed 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’s of 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 than the regular parent in that a key’s root node of a mapping is not NULL, rather 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 and should be freed 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 it’s 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 and should be freed 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 nodes short path address relative to the closest anchor (either on this node, or its parent). If no such parent is found then 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 and should be freed 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 and should be freed 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 grand parent) 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 and should be freed 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 grand parent) 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.

fy_node_set_tag

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

Set the tag of node

Parameters:

• fyn (struct fy_node*) – The node to set it’s tag.

• 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.

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)

Remove the tag of node

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)

Get the tag of the node

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_scalar

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

Get the scalar content of the node

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)

Get the scalar content of the node

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 in returned in case of an error.

fy_node_get_scalar_length

size_t fy_node_get_scalar_length(struct fy_node *fyn)

Get the length of the scalar content

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)

Get the length of the scalar content in utf8 characters

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)

Iterate over a sequence node

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)

Iterate over a sequence node in reverse

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)

Return the item count of the sequence

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)

Check whether the sequence is empty

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)

Return a sequence item by index

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)

Append a node item to a sequence

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)

Append a node item to a sequence

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)

Insert a node item before another

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)

Insert a node item after another

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)

Remove an item from a sequence

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.

fy_node_mapping_iterate

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

Iterate over a mapping node

Parameters:

• fyn (struct fy_node*) – The mapping node

• prevp (void**) – The previous sequence iterator

Description

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

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

Return

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

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

Parameters:

• fyn (struct fy_node*) – The mapping node

• prevp (void**) – The previous sequence iterator

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.

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

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

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.

fy_node_mapping_is_empty

bool fy_node_mapping_is_empty(struct fy_node *fyn)

Check whether the mapping is empty

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

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.

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

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

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().

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

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

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

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

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…

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.

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

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

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

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

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.

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)

Lookup a node pair’s key matching the provided key

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.

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)

Return the node pair index in the mapping

Parameters:

• fyn (struct fy_node*) – The mapping node

• fynp (const struct fy_node_pair*) – The node pair

Description

This method will return the node pair index in the mapping of the given node pair argument.

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)

Return the key of a node pair

Parameters:

• fynp (struct fy_node_pair*) – The node pair

Description

This method will return the node pair’s key. Note that this may be NULL, which is returned also in case the node pair argument is NULL, so you should protect against such a case.

Return

The node pair key

fy_node_pair_value

struct fy_node *fy_node_pair_value(struct fy_node_pair *fynp)

Return the value of a node pair

Parameters:

• fynp (struct fy_node_pair*) – The node pair

Description

This method will return the node pair’s value. Note that this may be NULL, which is returned also in case the node pair argument is NULL, so you should protect against such a 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)

Sets the key of a node pair

Parameters:

• fynp (struct fy_node_pair*) – The node pair

• fyn (struct fy_node*) – The key node

Description

This method will set the key part of the node pair. It will ovewrite any previous key.

Note that no checks for duplicate keys are going to be performed.

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)

Sets the value of a node pair

Parameters:

• fynp (struct fy_node_pair*) – The node pair

• fyn (struct fy_node*) – The value node

Description

This method will set the value part of the node pair. It will ovewrite any previous value.

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)

Append a node item to a mapping

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

Append a node pair to a mapping.

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)

Prepend a node item to a mapping

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

Prepend a node pair to a mapping.

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)

Remove a node pair from a mapping

Parameters:

• fyn_map (struct fy_node*) – The mapping node

• fynp (struct fy_node_pair*) – The node pair to remove

Description

Remove node pair from a mapping.

Return

0 on success, -1 on failure.

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)

Remove a node pair from a mapping returning the value

Parameters:

• fyn_map (struct fy_node*) – The mapping node

• fyn_key (struct fy_node*) – The node pair’s key

Description

Remove node pair from a mapping using the supplied key.

Return

The value part of 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)

Recursively sort node

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 sort all mappings of the given node, using the given comparison method (if NULL use the default one).

Return

0 on success, -1 on error

fy_node_vscanf

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

Retrieve data via vscanf

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 the following 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, ...)

Retrieve data via scanf

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 the following 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)

Retrieve data via vscanf relative to document root

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 the following 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, ...)

Retrieve data via scanf relative to document root

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 the following 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)

Iterate over a document’s tag directives

Parameters:

• fyd (struct fy_document*) – The document

• prevp (void**) – The previous state of the iterator

Description

This method iterates over all the documents tag directives. The start of the iteration is signalled by a NULL in *prevp.

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)

Retreive a document’s tag directive

Parameters:

• fyd (struct fy_document*) – The document

• handle (const char*) – The handle to look for

Description

Retreives the matching tag directive token of the document matching 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)

Get a tag directive handle

Parameters:

• fyt (struct fy_token*) – The tag directive token

• lenp (size_t*) – Pointer to a variable that will hold the returned length

Description

Retreives the tag directives token handle value. Only valid on tag directive tokens.

Return

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

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

Retreives the tag directives token prefix value. Only valid on tag directive tokens.

Return

A pointer to the tag directive’s prefix, while lenp will be assigned the length of said prefix. A NULL will be returned in case of 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

Add tag directive to the document.

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

Remove a tag directive from a document. Note that removal is prohibited if any node is still using this tag directive.

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

Lookup for an anchor having the name provided

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

Lookup for an anchor having the name provided from the text of the token

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

Lookup for an anchor located in the given node

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 will return a pointer to the text of an anchor along with the length of it. Note that this text is not NULL terminated.

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.

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 documents anchors. The start of the iteration is signalled by a NULL in *prevp.

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 give text name.

Note that the data are not copied, merely a reference is taken, so it must be available while the node is in use.

Also not that this method is deprecated; use fy_node_set_anchor() instead.

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 give text name.

Note that the data are not copied, merely a reference is taken, so it must be available while the node is in use.

This is similar to fy_document_set_anchor() with the document set to the document of the fyn node.

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 give text name, which will be copied, so it’s safe to dispose the text after the call.

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 give text name as created via vprintf’ing the arguments.

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 give text name as created via printf’ing the arguments.

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

Remove an anchor for the given node (if it exists)

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

Retrieve the anchor of the given node (if it exists)

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

Retrieve the anchor of the nearest parent of the given node or the given node if it has one.

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

Retrieve the nearest node which is a child of fyn_base starting at fyn and working upwards.

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

Create an alias on the given document

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 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

Create an alias on the given document

A copy of the data will be made, so it is safe to free the data after the call.

Return

The created alias node, or NULL in case of an error

fy_node_get_meta

void *fy_node_get_meta(struct fy_node *fyn)

Get the meta pointer of a node

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

fy_node_set_meta

int fy_node_set_meta(struct fy_node *fyn, void *meta)

Set the meta pointer of a node

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.

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

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

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.

fy_document_register_meta

int fy_document_register_meta(struct fy_document *fyd, fy_node_meta_clear_fn clear_fn, void *user)

Register a meta cleanup hook

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.

Return

0 on success, -1 if another hook is already registered.

fy_document_unregister_meta

void fy_document_unregister_meta(struct fy_document *fyd)

Unregister a meta cleanup 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.

fy_node_set_marker

bool fy_node_set_marker(struct fy_node *fyn, unsigned int marker)

Set a marker of a node

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.

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

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.

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

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)

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

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.

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

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

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.

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

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

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.

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

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.

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

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.

struct fy_diag_cfg

struct fy_diag_cfg

The diagnostics configuration

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.

struct fy_diag_error

struct fy_diag_error

A collected diagnostic error

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

Error type

module

The module

fyt

The token (may be NULL)

msg

The message to be output alongside

file

The file which contained the input

line

The line at the error

column

The column at the error

Description

This structure contains information about an error being collected by the diagnostic object.

fy_diag_create

struct fy_diag *fy_diag_create(const struct fy_diag_cfg *cfg)

Create a diagnostic object

Parameters:

• cfg (const struct fy_diag_cfg*) – The configuration for the diagnostic object (NULL is default)

Description

Creates a diagnostic object using the provided configuration.

Return

A pointer to the diagnostic object or NULL in case of an error.

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

Destroy a diagnostic object; note that the actual destruction only occurs when no more references to the object are present. However no output will be generated after this call.

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

Return the current configuration of a diagnostic object

Return

A const pointer to the diagnostic object configuration, or NULL in 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

Replace the current diagnostic configuration with the given configuration passed as an argument.

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 that reference counter of a diagnostic object

Parameters:

• diag (struct fy_diag*) – The diagnostic object to reference

Description

Increment the reference.

Return

Always returns the diag argument

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

Take away a reference, if it gets to 0, the diagnostic object is freed.

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.

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

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 which was set by an output of an error level diagnostic

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

Set the collect errors mode. When true instead of outputting to the diagnostic interface, errors are collected for later retrieval.

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.

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.

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.

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. Note that this is the lowest level interface, and as such is not recommended for use, 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

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

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.

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

Output a report about the given token via the specific error type, and using the reporting configuration of the token’s document.

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, ...)

Report about a token printf style using the given diagnostic object

Parameters:

• diag (struct fy_diag*) – The diag object

• fye (struct fy_token*) – The token

• 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 token via the specific error type, and using the reporting configuration of the token’s document.

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)

Report about a token vprintf style, overriding file, line and column info 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

• 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 token via the specific error type, and using the reporting configuration of the token’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.

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, ...)

Report about a token printf style, overriding file, line and column info 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

• 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

Output a report about the given token via the specific error type, and using the reporting configuration of the token’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.

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)

Report about a node vprintf style using the given diagnostic object

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

Output a report about the given node via the specific error type, and using 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, ...)

Report about a node printf style using the given diagnostic object

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

Output a report about the given node via the specific error type, and using 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)

Report about a node vprintf style, overriding file, line and column info using the given diagnostic object

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

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.

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, ...)

Report about a node printf style, overriding file, line and column info using the given diagnostic object

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

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.

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)

Report about an event vprintf style using the given diagnostic object

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

Output 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, ...)

Report about a event printf style using the given diagnostic object

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

Output a report about the given event part via the specific error type.

fy_diag_event_override_vreport

void fy_diag_event_override_vreport(struct fy_diag *diag, struct fy_event *fye, enum fy_event_part fyep, enum fy_error_type type, const char *file, int line, int column, const char *fmt, va_list ap)

Report about a token vprintf style, overriding file, line and column info using the given diagnostic object

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

• 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 event part via the specific error type. 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.

fy_diag_event_override_report

void fy_diag_event_override_report(struct fy_diag *diag, struct fy_token *fyt, enum fy_event_part fyep, enum fy_error_type type, const char *file, int line, int column, const char *fmt, ...)

Report about a token printf style, overriding file, line and column info using the given diagnostic object

Parameters:

• diag (struct fy_diag*) – The diag object

• fyt (struct fy_token*) – The event

• fyep (enum fy_event_part) – The event part

• 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

Output a report about the given event part via the specific error type. 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.

fy_diag_errors_iterate

struct fy_diag_error *fy_diag_errors_iterate(struct fy_diag *diag, void **prevp)

Iterate 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.

Return

The next errors or NULL when there are not any more.

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, do not output any information messages

FYPPCF_DISABLE_RECYCLING

Disable recycling optimization

FYPPCF_DISABLE_ACCELERATORS

Disable use of access accelerators (saves memory)

Description

These flags control the operation of the path parse

struct fy_path_parse_cfg

struct fy_path_parse_cfg

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

Argument to the fy_path_parser_create() method which performs parsing of a ypath expression

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

Destroy a path parser created earlier via fy_path_parser_create().

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 reset a path parser, including after an error that caused a parser error to be emitted.

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

Create a path expression from a string using the provided path parser.

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

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

Create 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

Free a previously returned expression from any of the path parser methods like fy_path_expr_build_from_string()

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.

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 useful for understanding what the expression evaluates to.

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

struct fy_path_exec_cfg

struct fy_path_exec_cfg

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

Argument to the fy_path_exec_create() method which 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().

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

Destroy ane executor created earlier via fy_path_exec_create().

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 reset an executor without releasing it.

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

Execute the expression starting at fyn_start. If execution is successful the results are available via fy_path_exec_results_iterate()

Note that it is illegal to modify the state of the document that the results reside between this call and the results collection.

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.

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.

enum fy_token_type

enum fy_token_type

Token types

Definition

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

FYTT_NONE

No token

FYTT_STREAM_START

Stream start token

FYTT_STREAM_END

Stream end token

FYTT_VERSION_DIRECTIVE

Version directive token

FYTT_TAG_DIRECTIVE

Tag directive token

FYTT_DOCUMENT_START

Document start token

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 comma 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)

Check token type validity

Parameters:

• type (enum fy_token_type) – The token type

Description

Check if argument token type 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)

Check if token type is valid for YAML

Parameters:

• type (enum fy_token_type) – The token type

Description

Check if argument token type is a valid YAML one.

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)

Check if token type is valid for YAML content

Parameters:

• type (enum fy_token_type) – The token type

Description

Check if argument 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)

Check if token type is valid for a YPATH expression

Parameters:

• type (enum fy_token_type) – The token type

Description

Check if argument 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)

Check if token type is valid for a YPATH scalar expression

Parameters:

• type (enum fy_token_type) – The token type

Description

Check if argument 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)

Return the token’s type

Parameters:

• fyt (struct fy_token*) – The token

Description

Return the token’s type; if NULL then FYTT_NONE is returned

Return

The token’s type; FYTT_NONE if not a valid token (or NULL)

fy_token_start_mark

const struct fy_mark *fy_token_start_mark(struct fy_token *fyt)

Get token’s start marker

Parameters:

• fyt (struct fy_token*) – The token to get its start marker

Description

Return the token’s start marker if it exists. Note it is permissable for some token types to have no start marker because they are without content.

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)

Get token’s end marker

Parameters:

• fyt (struct fy_token*) – The token to get its end marker

Description

Return the token’s end marker if it exists. Note it is permissable for some token types to have no end marker because they are without content.

Return

The token’s end marker, NULL if not available.

fy_scan

struct fy_token *fy_scan(struct fy_parser *fyp)

Low level access to the scanner

Parameters:

• fyp (struct fy_parser*) – The parser to get the next token from.

Description

Return the next scanner token. Note this is a very low level interface, intended for users that want/need to implement their own YAML parser. The returned token is expected to be disposed using fy_scan_token_free()

Return

The next token, or NULL if no more tokens are available.

fy_scan_token_free

void fy_scan_token_free(struct fy_parser *fyp, struct fy_token *fyt)

Free the token returned by fy_scan()

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

Free the token returned by fy_scan().

fy_tag_directive_token_prefix0

const char *fy_tag_directive_token_prefix0(struct fy_token *fyt)

Get the prefix contained in the tag directive token as zero terminated string

Parameters:

• fyt (struct fy_token*) – The tag directive token out of which the prefix pointer will be returned.

Description

Retrieve the tag directive’s prefix contents as a zero terminated string. It is similar to fy_tag_directive_token_prefix(), with the difference that the returned string is zero terminated and memory may be allocated to hold it associated with the token.

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 contained in the tag directive token as zero terminated string

Parameters:

• fyt (struct fy_token*) – The tag directive token out of which the handle pointer will be returned.

Description

Retrieve the tag directive’s handle contents as a zero terminated string. It is similar to fy_tag_directive_token_handle(), with the difference that the returned string is zero terminated and memory may be allocated to hold it associated with the token.

Return

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

fy_tag_token_handle

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

Get the handle contained in the tag token

Parameters:

• fyt (struct fy_token*) – The tag token out of which the handle pointer will be returned.

• lenp (size_t*) – Pointer to a variable that will hold the returned length

Description

Retrieve the tag handle contents. Will fail if token is not a tag token, or if a memory error happens.

Return

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

fy_tag_token_suffix

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

Get the suffix contained in the tag token

Parameters:

• fyt (struct fy_token*) – The tag token out of which the suffix pointer will be returned.

• lenp (size_t*) – Pointer to a variable that will hold the returned length

Description

Retrieve the tag suffix contents. Will fail if token is not a tag token, or if a memory error happens.

Return

A pointer to the text representation of the suffix token, while lenp will be assigned the character length of said 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 the tag token

Parameters:

• fyt (struct fy_token*) – The tag token out of which the short pointer will be returned.

• lenp (size_t*) – Pointer to a variable that will hold the returned length

Description

Retrieve the short tag contents. The short tag is the same one that will need to be emitted. Will fail if token is not a tag token, or if a memory error happens.

Return

A pointer to the text representation of the short tag, while lenp will be assigned the character length of said representation. NULL in case of an error.

fy_tag_token_handle0

const char *fy_tag_token_handle0(struct fy_token *fyt)

Get the handle contained in the tag token as zero terminated string

Parameters:

• fyt (struct fy_token*) – The tag token out of which the handle pointer will be returned.

Description

Retrieve the tag handle contents as a zero terminated string. It is similar to fy_tag_token_handle(), with the difference that the returned string is zero terminated and memory may be allocated to hold it associated with the token.

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 the tag token as zero terminated string.

Parameters:

• fyt (struct fy_token*) – The tag token out of which the short pointer will be returned.

Description

Retrieve the short tag contents. The short tag is the same one that will need to be emitted. Will fail if token is not 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 contained in the tag token as zero terminated string

Parameters:

• fyt (struct fy_token*) – The tag token out of which the suffix pointer will be returned.

Description

Retrieve the tag suffix contents as a zero terminated string. It is similar to fy_tag_token_suffix(), with the difference that the returned string is zero terminated and memory may be allocated to hold it associated with the token.

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

Retrieve the version stored in a version directive token.

Return

A pointer to the version stored in the version directive token, or NULL in case of an error, or the token not being a version directive token.

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

Retrieve the style of a scalar token.

Return

The scalar style of the token, or FYSS_ANY for an error

fy_tag_token_tag

const struct fy_tag *fy_tag_token_tag(struct fy_token *fyt)

Get tag of a tag token

Parameters:

• fyt (struct fy_token*) – The tag token

Description

Retrieve the tag of a tag token.

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 tag of a tag directive token

Parameters:

• fyt (struct fy_token*) – The tag directive token

Description

Retrieve the tag of a tag directive token.

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 to get its main token

Description

Retrieve the main token (i.e. not the tag or the anchor) of an event. It may be NULL in 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 to get its anchor token

Description

Retrieve the anchor token if it exists. Only valid for mapping/sequence start and scalar events.

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 to get its tag token

Description

Retrieve the tag token if it exists. Only valid for mapping/sequence start and scalar events.

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 event’s start marker

Parameters:

• fye (struct fy_event*) – The event to get its start marker

Description

Return the event’s start marker if it exists. The start marker is the one of the event’s main token.

Return

The event’s start marker, NULL if not available.

fy_event_end_mark

const struct fy_mark *fy_event_end_mark(struct fy_event *fye)

Get event’s end marker

Parameters:

• fye (struct fy_event*) – The event to get its end marker

Description

Return the event’s end marker if it exists. The end marker is the one of the event’s main token.

Return

The event’s end marker, NULL if 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 to get it’s node style

Description

Return the node style (FYNS_*) of an event. May return FYNS_ANY if the event is implicit. For collection start events the only possible values is FYNS_ANY, FYNS_FLOW, FYNS_BLOCK. A scalar event may return any.

Return

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

Retrieve the version stored in a document start event

Return

A pointer to the version, or NULL in case of an error, or the event not being 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

Retrieve the version stored in a document state object

Return

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

fy_document_state_start_mark

const struct fy_mark *fy_document_state_start_mark(struct fy_document_state *fyds)

Get document state’s start mark

Parameters:

• fyds (struct fy_document_state*) – The document state object

Description

Return the document state’s start mark (if it exists). Note that purely synthetic documents do not contain one

Return

The document’s start marker, NULL if not available.

fy_document_state_end_mark

const struct fy_mark *fy_document_state_end_mark(struct fy_document_state *fyds)

Get document state’s end mark

Parameters:

• fyds (struct fy_document_state*) – The document state object

Description

Return the document state’s end mark (if it exists). Note that purely synthetic documents do not contain one

Return

The document’s end marker, NULL if not available.

fy_document_state_version_explicit

bool fy_document_state_version_explicit(struct fy_document_state *fyds)

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.

Return

true if version was set explicitly, false otherwise

fy_document_state_tags_explicit

bool fy_document_state_tags_explicit(struct fy_document_state *fyds)

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. Note that for synthetic documents this method returns false.

Return

true if document had tags set explicitly, false otherwise

fy_document_state_start_implicit

bool fy_document_state_start_implicit(struct fy_document_state *fyds)

Started 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 document was started implicitly, false otherwise

fy_document_state_end_implicit

bool fy_document_state_end_implicit(struct fy_document_state *fyds)

Started 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 document was ended implicitly, false otherwise

fy_document_state_json_mode

bool fy_document_state_json_mode(struct fy_document_state *fyds)

Input was 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.

Return

true if 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 directives 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

Return all the tag directives in a dynamically allocated area. Must be free()‘d when not in use.

Return

An array of fy_tag pointer structures, terminated with a NULL pointer 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. impliciticly set)

Return

true in case that 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

Retrieve the document state object of a parser. Note that this is only valid during parsing.

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

Retrieve the document state object of a document.

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

Set the document state of a document

Return

0 if 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.

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. Allowed events are FYET_SCALAR, FYET_ALIAS, FYET_MAPPING_START & FYET_SEQUENCE_START

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 node created using fy_node_create_from_event() 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 it’s 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.

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.

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.

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.

Return

The active document state object of the emitter, NULL otherwise

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

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, of 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 analogous to fy_emit_event_create().

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. Only use is error recovery and cleanup.

fy_parse_event_create

struct fy_event *fy_parse_event_create(struct fy_parser *fyp, enum fy_event_type type, ...)

Create an emit event.

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 analogous to fy_parse_event_create().

Return

The created event or NULL in case of an error

enum fy_composer_return

enum fy_composer_return

The returns of the composer callback

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

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

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

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.

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

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

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.

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.

fy_path_depth

int fy_path_depth(struct fy_path *fypp)

Get the depth of a path

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.

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 collectin 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

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 associated with the mapping, or NULL if not a mapping or the user data are NULL

fy_path_component_get_mapping_key_user_data

void *fy_path_component_get_mapping_key_user_data(struct fy_path_component *fypc)

Return the userdata associated with the mapping key

Parameters:

• fypc (struct fy_path_component*) – The path component

Return

The user data associated with the mapping key, or NULL if not a mapping or the user data are NULL

fy_path_component_get_sequence_user_data

void *fy_path_component_get_sequence_user_data(struct fy_path_component *fypc)

Return the userdata associated with the sequence

Parameters:

• fypc (struct fy_path_component*) – The path component

Return

The user data associated with the sequence, or NULL if not a sequence or the user data are NULL

fy_path_component_set_mapping_user_data

void fy_path_component_set_mapping_user_data(struct fy_path_component *fypc, void *data)

Set 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

Note, no error condition if not a mapping

fy_path_component_set_mapping_key_user_data

void fy_path_component_set_mapping_key_user_data(struct fy_path_component *fypc, void *data)

Set 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

Note, no error condition if not in a mapping key state

fy_path_component_set_sequence_user_data

void fy_path_component_set_sequence_user_data(struct fy_path_component *fypc, void *data)

Set 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

Note, no error condition if not a sequence

fy_path_get_parent_user_data

void *fy_path_get_parent_user_data(struct fy_path *path)

Return the userdata of the parent collection

Parameters:

• path (struct fy_path*) – The path

Return

The user data associated with the parent collection of the path, or NULL if no path

fy_path_set_parent_user_data

void fy_path_set_parent_user_data(struct fy_path *path, void *data)

Set 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

Note, no error condition if not a path

fy_path_get_last_user_data

void *fy_path_get_last_user_data(struct fy_path *path)

Return the userdata of the last collection

Parameters:

• path (struct fy_path*) – The path

Return

The user data associated with the last collection of the path, or NULL if no path

fy_path_set_last_user_data

void fy_path_set_last_user_data(struct fy_path *path, void *data)

Set 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

Note, no error condition if not a path

fy_path_last_component

struct fy_path_component *fy_path_last_component(struct fy_path *fypp)

Get the very last component of a path

Parameters:

• fypp (struct fy_path*) – The path

Description

Returns the last component of a path.

Return

The last path component (which may be a collection root component), or NULL if it does not exist

fy_path_last_not_collection_root_component

struct fy_path_component *fy_path_last_not_collection_root_component(struct fy_path *fypp)

Get 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. This may not be the last component that is returned by fy_path_last_component().

The difference is present on MAPPING/SEQUENCE START/END events where the last component is present but not usuable as a object parent.

Return

The last non collection root component, or NULL if it does not exist

struct fy_composer_ops

struct fy_composer_ops

Composer operation callbacks

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

Callbacks used by the composer to process events and create document builders.

struct fy_composer_cfg

struct fy_composer_cfg

Composer configuration structure

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 passed to callbacks

diag

Optional diagnostic interface to use, NULL for default

Description

Configuration structure for creating a composer instance.

fy_composer_create

struct fy_composer *fy_composer_create(struct fy_composer_cfg *cfg)

Create 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 maintains path information for 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)

Destroy the given composer

Parameters:

• fyc (struct fy_composer*) – The composer to destroy

Description

Destroy a composer created earlier via fy_composer_create().

fy_composer_process_event

enum fy_composer_return fy_composer_process_event(struct fy_composer *fyc, struct fy_event *fye)

Process a YAML event through the composer

Parameters:

• fyc (struct fy_composer*) – The composer

• fye (struct fy_event*) – The event to process

Description

Process a YAML event by calling the configured process_event callback with path context. The composer maintains the current path and provides it to the callback for intelligent processing decisions.

Return

A fy_composer_return code indicating how to proceed (continue, stop, skip, or error)

fy_composer_get_cfg

struct fy_composer_cfg *fy_composer_get_cfg(struct fy_composer *fyc)

Get 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)

Get the userdata from composer configuration

Parameters:

• fyc (struct fy_composer*) – The composer

Description

Retrieve the 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)

Get the diagnostic object of a composer

Parameters:

• fyc (struct fy_composer*) – The composer to get the diagnostic object

Description

Return a pointer to the diagnostic object of a composer object. Note that the returned diag object has a reference taken so you should fy_diag_unref() it when you’re done with it.

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)

Get the current path of the composer

Parameters:

• fyc (struct fy_composer*) – The composer

Description

Retrieve the current path being processed by the composer. The path represents the location in the YAML document structure where the composer is currently positioned.

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)

Get the root path of the composer

Parameters:

• fyc (struct fy_composer*) – The composer

Description

Retrieve the root path of the composer’s path hierarchy.

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)

Get 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

Iterate through the composer’s path list. Pass NULL to get the first path, or pass the previous path to get the next one.

Return

The next path in the list, or NULL if no more paths exist

enum fy_document_iterator_cfg_flags

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

struct fy_document_iterator_cfg

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.

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.

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

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.

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.

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

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().

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.

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.

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.

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().

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.

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.

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.

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.

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.

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.

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.

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.

Return

true if it was in an error state, false otherwise.

struct fy_document_builder_cfg

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

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

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. This document may be incomplete. If you need to take ownership use fy_document_builder_take_document().

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.

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. If it is complete then a call to fy_document_builder_take_document() will transfer ownership of the document to the caller.

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.

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.

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.

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.

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

enum fy_parser_event_generator_flags

enum fy_parser_event_generator_flags

The parser event generator flags

Definition

enum fy_parser_event_generator_flags {
    FYPEGF_GENERATE_DOCUMENT_EVENTS,
    FYPEGF_GENERATE_STREAM_EVENTS,
    FYPEGF_GENERATE_ALL_EVENTS
};

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

Associate a parser with a document iterator, that is instead of parsing the events will be generated by the document iterator.

Return

0 on success, -1 on error

typedef fy_work_exec_fn

void fy_work_exec_fn(void *arg)

Work exec function

Parameters:

• arg (void*) – The argument to the method

Description

The callback executed on work submission

typedef fy_work_check_fn

bool fy_work_check_fn(const void *arg)

Work check function

Parameters:

• arg (const void*) – The argument to the method

Description

Work checker function to decide if it’s worth to offload to a thread.

Return

true if it should offload to thread, false otherwise

struct fy_thread_work

struct fy_thread_work

Work submitted to a thread for execution

Definition

struct fy_thread_work {
    fy_work_exec_fn fn;
    void *arg;
    struct fy_work_pool *wp;
}

Members

fn

The execution function for this work

arg

The argument to the fn

wp

Used internally, must be set to NULL on entry

Description

This is the structure describing the work submitted to a thread for execution.

enum fy_thread_pool_cfg_flags

enum fy_thread_pool_cfg_flags

Thread pool configuration flags

Definition

enum fy_thread_pool_cfg_flags {
    FYTPCF_STEAL_MODE
};

Constants

FYTPCF_STEAL_MODE

Enable steal mode for the thread pool

Description

These flags control the operation of the thread pool. For now only the steal mode flag is defined.

struct fy_thread_pool_cfg

struct fy_thread_pool_cfg

thread pool configuration structure.

Definition

struct fy_thread_pool_cfg {
    enum fy_thread_pool_cfg_flags flags;
    unsigned int num_threads;
    void *userdata;
}

Members

flags

Thread pool configuration flags

num_threads

Number of threads, if 0 == online CPUs

userdata

A userdata pointer

Description

Argument to the fy_thread_pool_create() method.

fy_thread_pool_create

struct fy_thread_pool *fy_thread_pool_create(const struct fy_thread_pool_cfg *cfg)

Create a thread pool

Parameters:

• cfg (const struct fy_thread_pool_cfg*) – The configuration for the thread pool

Description

Creates a thread pool with its configuration cfg The thread pool may be destroyed by a corresponding call to fy_thread_pool_destroy().

Return

A pointer to the thread pool or NULL in case of an error.

fy_thread_pool_destroy

void fy_thread_pool_destroy(struct fy_thread_pool *tp)

Destroy the given thread pool

Parameters:

• tp (struct fy_thread_pool*) – The thread pool to destroy

Description

Destroy a thread pool created earlier via fy_thread_pool_create(). Note that this function will block until all threads of the pool are destroyed.

fy_thread_pool_get_num_threads

int fy_thread_pool_get_num_threads(struct fy_thread_pool *tp)

Get the number of threads

Parameters:

• tp (struct fy_thread_pool*) – The thread pool

Description

Returns the actual number of created threads.

Return

> 0 for the number of actual threads created, -1 on error

fy_thread_pool_get_cfg

const struct fy_thread_pool_cfg *fy_thread_pool_get_cfg(struct fy_thread_pool *tp)

Get the configuration of a thread pool

Parameters:

• tp (struct fy_thread_pool*) – The thread pool

Return

The configuration of the thread pool

fy_thread_reserve

struct fy_thread *fy_thread_reserve(struct fy_thread_pool *tp)

Reserve a thread from the pool.

Parameters:

• tp (struct fy_thread_pool*) – The thread pool

Description

Reserve a thread from the pool and return it. Note this is only valid for a non-work stealing thread pool. You release the thread again via a call to fy_thread_unreserve.

Return

A reserved thread if not NULL, NULL if no threads are available.

fy_thread_unreserve

void fy_thread_unreserve(struct fy_thread *t)

Unreserve a previously reserved thread

Parameters:

• t (struct fy_thread*) – The thread

Description

Unreserve a thread previously reserved via a call to fy_thread_reserve() Note this is only valid for a non-work stealing thread pool.

fy_thread_submit_work

int fy_thread_submit_work(struct fy_thread *t, struct fy_thread_work *work)

Submit work for execution

Parameters:

• t (struct fy_thread*) – The thread

• work (struct fy_thread_work*) – The work

Description

Submit work for execution. If successful the thread will start executing the work in parallel with the calling thread. You can wait for the thread to terminate via a call to fy_thread_wait_work(). The thread must have been reserved earlier via fy_thread_reserve()

Note this is only valid for a non-work stealing thread pool.

Return

0 if work has been submitted, -1 otherwise.

fy_thread_wait_work

int fy_thread_wait_work(struct fy_thread *t)

Wait for completion of submitted work

Parameters:

• t (struct fy_thread*) – The thread

Description

Wait until submitted work to the thread has finished. Note this is only valid for a non-work stealing thread pool.

Return

0 if work finished, -1 on error.

fy_thread_work_join

void fy_thread_work_join(struct fy_thread_pool *tp, struct fy_thread_work *works, size_t work_count, fy_work_check_fn check_fn)

Submit works for execution and wait

Parameters:

• tp (struct fy_thread_pool*) – The thread pool

• works (struct fy_thread_work*) – Pointer to an array of works sized work_count

• work_count (size_t) – The size of the works array

• check_fn (fy_work_check_fn) – Pointer to a check function, or NULL for no checks

Description

Submit works for possible parallel execution. If no offloading is possible at the time execute in the current context. It is possible to use in both stealing and non-stealing mode with the difference being that stealing mode is about 30% faster.

fy_thread_args_join

void fy_thread_args_join(struct fy_thread_pool *tp, fy_work_exec_fn fn, fy_work_check_fn check_fn, void **args, size_t count)

Execute function in parallel using arguments as pointers

Parameters:

• tp (struct fy_thread_pool*) – The thread pool

• fn (fy_work_exec_fn) – The function to execute in parallel

• check_fn (fy_work_check_fn) – Pointer to a check function, or NULL for no checks

• args (void**) – An args array sized count of argument pointers

• count (size_t) – The count of the args array items

Description

Execute fn possibly in parallel using the threads in the thread pool. The arguments of the function are provided by the args array.

fy_thread_arg_array_join

void fy_thread_arg_array_join(struct fy_thread_pool *tp, fy_work_exec_fn fn, fy_work_check_fn check_fn, void *args, size_t argsize, size_t count)

Execute function in parallel using argument array

Parameters:

• tp (struct fy_thread_pool*) – The thread pool

• fn (fy_work_exec_fn) – The function to execute in parallel

• check_fn (fy_work_check_fn) – Pointer to a check function, or NULL for no checks

• args (void*) – An args array of argsize items

• argsize (size_t) – The size of each argument array item

• count (size_t) – The count of the args array items

Description

Execute fn possibly in parallel using the threads in the thread pool. The arguments of the function are provided by the args array.

fy_thread_arg_join

void fy_thread_arg_join(struct fy_thread_pool *tp, fy_work_exec_fn fn, fy_work_check_fn check_fn, void *arg, size_t count)

Execute function in parallel with the same argument

Parameters:

• tp (struct fy_thread_pool*) – The thread pool

• fn (fy_work_exec_fn) – The function to execute in parallel

• check_fn (fy_work_check_fn) – Pointer to a check function, or NULL for no checks

• arg (void*) – The common argument

• count (size_t) – The count of executions

Description

Execute fn possibly in parallel using the threads in the thread pool. The argument of the functions is the same.

fy_blake3_backend_iterate

const char *fy_blake3_backend_iterate(const char **prevp)

Iterate over the supported BLAKE3 backends

Parameters:

• prevp (const char**) – The previous backend pointer, or NULL at start

Description

This method iterates over the supported BLAKE3 backends. The start of the iteration is signalled by a NULL in *prevp.

The default backend is always the last in sequence, so for example if the order is [ “portable”, “sse2”, NULL ] the default is “sse2”.

Return

The next backend or NULL at the end.

struct fy_blake3_hasher_cfg

struct fy_blake3_hasher_cfg

BLAKE3 hasher configuration

Definition

struct fy_blake3_hasher_cfg {
    const char *backend;
    size_t file_buffer;
    size_t mmap_min_chunk;
    size_t mmap_max_chunk;
    bool no_mmap;
    const uint8_t *key;
    const void *context;
    size_t context_len;
    struct fy_thread_pool *tp;
    int num_threads;
}

Members

backend

NULL for default, or a specific backend name

file_buffer

Use this amount of buffer for buffering, zero for default

mmap_min_chunk

Minimum chunk size for mmap case

mmap_max_chunk

Maximum chunk size for mmap case

no_mmap

Disable mmap for file access

key

pointer to a FY_BLAKE3_KEY_LEN area when in keyed mode. NULL otherwise.

context

pointer to a context when in key derivation mode. NULL otherwise.

context_len

The size of the context when in key derivation mode. 0 otherwise.

tp

The thread pool to use, if NULL, create a private one

num_threads

Number of threads to use - 0 means default: NUM_CPUS * 3 / 2 - > 0 specific number of threads - -1 disable threading entirely

Description

Argument to the fy_blake3_hasher_create() method which is the fyaml’s user facing BLAKE3 API. It is very minimal, on purpose, since it’s meant to be exposing a full blown BLAKE3 API.

fy_blake3_hasher_create

struct fy_blake3_hasher *fy_blake3_hasher_create(const struct fy_blake3_hasher_cfg *cfg)

Create a BLAKE3 hasher object.

Parameters:

• cfg (const struct fy_blake3_hasher_cfg*) – The configuration for the BLAKE3 hasher

Description

Creates a BLAKE3 hasher with its configuration cfg The hasher may be destroyed by a corresponding call to fy_blake3_hasher_destroy().

Return

A pointer to the BLAKE3 hasher or NULL in case of an error.

fy_blake3_hasher_destroy

void fy_blake3_hasher_destroy(struct fy_blake3_hasher *fyh)

Destroy the given BLAKE3 hasher

Parameters:

• fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher to destroy

Description

Destroy a BLAKE3 hasher created earlier via fy_blake3_hasher_create().

fy_blake3_hasher_update

void fy_blake3_hasher_update(struct fy_blake3_hasher *fyh, const void *input, size_t input_len)

Update the BLAKE3 hasher state with the given input

Parameters:

• fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

• input (const void*) – Pointer to the input

• input_len (size_t) – Size of the input in bytes

Description

Updates the BLAKE3 hasher state by hashing the given input.

fy_blake3_hasher_finalize

const uint8_t *fy_blake3_hasher_finalize(struct fy_blake3_hasher *fyh)

Finalize the hash and get output

Parameters:

• fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

Description

Finalizes the BLAKE3 hasher and returns the output

Return

A pointer to the BLAKE3 output (sized FY_BLAKE3_OUT_LEN), or NULL in case of an error.

fy_blake3_hasher_reset

void fy_blake3_hasher_reset(struct fy_blake3_hasher *fyh)

Resets the hasher

Parameters:

• fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

Description

Resets the hasher for re-use

fy_blake3_hash

const uint8_t *fy_blake3_hash(struct fy_blake3_hasher *fyh, const void *mem, size_t size)

BLAKE3 hash a memory area

Parameters:

• fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

• mem (const void*) – Pointer to the memory to use

• size (size_t) – The size of the memory in bytes

Description

Hash a memory area and return the BLAKE3 output.

Return

A pointer to the BLAKE3 output (sized FY_BLAKE3_OUT_LEN), or NULL in case of an error.

fy_blake3_hash_file

const uint8_t *fy_blake3_hash_file(struct fy_blake3_hasher *fyh, const char *filename)

BLAKE3 hash a file.

Parameters:

• fyh (struct fy_blake3_hasher*) – The BLAKE3 hasher

• filename (const char*) – The filename

Description

Hash the given file (possibly using mmap)

Return

A pointer to the BLAKE3 output (sized FY_BLAKE3_OUT_LEN), or NULL in case of an error.

fy_allocator_iterate

const char *fy_allocator_iterate(const char **prevp)

Iterate over available allocator names

Parameters:

• prevp (const char**) – The previous allocator iterator pointer

Description

This method iterates over all the available allocator names. The start of the iteration is signalled by a NULL in *prevp.

Return

The next allocator name in sequence or NULL at the end.

fy_allocator_is_available

bool fy_allocator_is_available(const char *name)

Check if an allocator is available

Parameters:

• name (const char*) – The name of the allocator to check

Description

Check if the named allocator is available.

Return

true if the allocator is available, false otherwise

fy_allocator_create

struct fy_allocator *fy_allocator_create(const char *name, const void *cfg)

Create an allocator.

Parameters:

• name (const char*) – The name of the allocator

• cfg (const void*) – The type specific configuration for the allocator, or NULL for the default.

Description

Creates an allocator of the given type, using the configuration argument provided. The allocator may be destroyed by a corresponding call to fy_allocator_destroy().

You can retrieve the names of available allocators with the fy_allocator_get_names() method.

Return

A pointer to the allocator or NULL in case of an error.

fy_allocator_destroy

void fy_allocator_destroy(struct fy_allocator *a)

Destroy the given allocator

Parameters:

• a (struct fy_allocator*) – The allocator to destroy

Description

Destroy an allocator created earlier via fy_allocator_create(). Tracking allocators will release all memory allocated using them.

fy_allocator_get_tag

int fy_allocator_get_tag(struct fy_allocator *a)

Get a tag from an allocator

Parameters:

• a (struct fy_allocator*) – The allocator

Description

The allocator interface requires all allocation to belong to a tag. This call creates a tag and returns its value, or an error if not available.

If an allocator only provides a single tag (like the linear allocator for instance), the same tag number, usually 0, is returned.

Return

The created tag or -1 in case of an error.

fy_allocator_release_tag

void fy_allocator_release_tag(struct fy_allocator *a, int tag)

Release a tag from an allocator

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag to release

Description

Releases a tag from an allocator and frees all memory it allocated (if such an operation is provided by the allocator).

fy_allocator_trim_tag

void fy_allocator_trim_tag(struct fy_allocator *a, int tag)

Trim a tag

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag to trim

Description

Trim a tag, that is free any excess memory it allocator, fitting it to the size of the content it carries. Allocators that cannot perform this operation treat it as a NOP.

fy_allocator_reset_tag

void fy_allocator_reset_tag(struct fy_allocator *a, int tag)

Reset a tag

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag to reset

Description

Reset a tag, that is free any content it carries, but do not release the tag.

fy_allocator_alloc

void *fy_allocator_alloc(struct fy_allocator *a, int tag, size_t size, size_t align)

Allocate memory from an allocator

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag to allocate from

• size (size_t) – The size of the memory to allocate

• align (size_t) – The alignment of the object

Description

Allocate memory from the given allocator tag, satisfying the size and align restrictions.

Return

A pointer to the allocated memory or NULL

fy_allocator_free

void fy_allocator_free(struct fy_allocator *a, int tag, void *ptr)

Free memory allocated from an allocator

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag used to allocate the memory

• ptr (void*) – The pointer to the memory to free

Description

Attempt to free the memory allocated previously by fy_allocator_alloc() Note that non per object tracking allocators treat this as a NOP

fy_allocator_store

const void *fy_allocator_store(struct fy_allocator *a, int tag, const void *data, size_t size, size_t align)

Store an object to an allocator

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag used to allocate the memory

• data (const void*) – The pointer to object to store

• size (size_t) – The size of the object

• align (size_t) – The alignment restriction of the object

Description

Store an object to an allocator and return a pointer to the location it was stored. When using a deduplicating allocator no new allocation will take place and a pointer to the object already stored will be returned.

The return pointer must not be modified, the objects stored are idempotent.

Return

A constant pointer to the object stored, or NULL in case of an error

fy_allocator_storev

const void *fy_allocator_storev(struct fy_allocator *a, int tag, const struct iovec *iov, int iovcnt, size_t align)

Store an object to an allocator (scatter gather)

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag used to allocate the memory from

• iov (const struct iovec*) – The I/O scatter gather vector

• iovcnt (int) – The number of vectors

• align (size_t) – The alignment restriction of the object

Description

Store an object to an allocator and return a pointer to the location it was stored. When using a deduplicating allocator no new allocation will take place and a pointer to the object already stored will be returned.

The object is created linearly from the scatter gather io vector provided.

The return pointer must not be modified, the objects stored are idempotent.

Return

A constant pointer to the object stored, or NULL in case of an error

fy_allocator_dump

void fy_allocator_dump(struct fy_allocator *a)

Dump internal allocator state

Parameters:

• a (struct fy_allocator*) – The allocator

fy_allocator_get_tag_linear_size

ssize_t fy_allocator_get_tag_linear_size(struct fy_allocator *a, int tag)

Get the linear size of an allocator tag

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag

Description

Retrieve the linear size of the content of a tag. That is the size of a buffer if one was to copy the content of the tag in that buffer in a linear manner.

Return

The linear size of the content stored in the tag or -1 in case of an error.

fy_allocator_get_tag_single_linear

const void *fy_allocator_get_tag_single_linear(struct fy_allocator *a, int tag, size_t *sizep)

Get the linear extend of a tag

Parameters:

• a (struct fy_allocator*) – The allocator

• tag (int) – The tag

• sizep (size_t*) – Pointer to a variable that will be filled with the size.

Description

If a tag stores it’s content in a single linear buffer, retrieve it directly. This is possible only under careful arrangement of allocator configuration, but it is an important optimization case.

Return

A pointer to the linear content of the tag, or NULL if othersize.

struct fy_linear_allocator_cfg

struct fy_linear_allocator_cfg

linear allocator configuration

Definition

struct fy_linear_allocator_cfg {
    void *buf;
    size_t size;
}

Members

buf

A pointer to a buffer that will be used, or NULL in order to allocate

size

Size of the buffer in bytes

enum fy_mremap_arena_type

enum fy_mremap_arena_type

The mremap allocator arena types

Definition

enum fy_mremap_arena_type {
    FYMRAT_DEFAULT,
    FYMRAT_MALLOC,
    FYMRAT_MMAP
};

Constants

FYMRAT_DEFAULT

Use what’s optimal for this platform

FYMRAT_MALLOC

Use malloc/realloc arena type (not recommended)

FYMRAT_MMAP

Use mmap/mremap arena type

struct fy_mremap_allocator_cfg

struct fy_mremap_allocator_cfg

mremap allocator configuration

Definition

struct fy_mremap_allocator_cfg {
    size_t big_alloc_threshold;
    size_t empty_threshold;
    size_t minimum_arena_size;
    float grow_ratio;
    float balloon_ratio;
    enum fy_mremap_arena_type arena_type;
}

Members

big_alloc_threshold

Threshold for immediately creating a new arena.

empty_threshold

The threshold under which an arena is moved to the full list.

minimum_arena_size

The minimum (and starting size) of an arena.

grow_ratio

The ratio which an arena will try to grow if full (>1.0)

balloon_ratio

The multiplier for the vm area first allocation

arena_type

The arena type

Description

If any of the fields is zero, then the system will provide (somewhat) reasonable defaults.

struct fy_dedup_allocator_cfg

struct fy_dedup_allocator_cfg

dedup allocator configuration

Definition

struct fy_dedup_allocator_cfg {
    struct fy_allocator *parent_allocator;
    unsigned int bloom_filter_bits;
    unsigned int bucket_count_bits;
    size_t dedup_threshold;
    unsigned int chain_length_grow_trigger;
    size_t estimated_content_size;
}

Members

parent_allocator

The parent allocator (required)

bloom_filter_bits

Number of bits of the bloom filter (or 0 for default)

bucket_count_bits

Number of bits for the bucket count (or 0 for default)

dedup_threshold

Number of bytes over which dedup takes place (default 0=always)

chain_length_grow_trigger

Chain length of a bucket over which a grow takes place (or 0 for auto)

estimated_content_size

Estimated content size (or 0 for don’t know)

enum fy_auto_allocator_scenario_type

enum fy_auto_allocator_scenario_type

auto allocator scenario type

Definition

enum fy_auto_allocator_scenario_type {
    FYAST_PER_TAG_FREE,
    FYAST_PER_TAG_FREE_DEDUP,
    FYAST_PER_OBJ_FREE,
    FYAST_PER_OBJ_FREE_DEDUP,
    FYAST_SINGLE_LINEAR_RANGE,
    FYAST_SINGLE_LINEAR_RANGE_DEDUP
};

Constants

FYAST_PER_TAG_FREE

only per tag freeing, no individual obj free

FYAST_PER_TAG_FREE_DEDUP

per tag freeing, dedup obj store

FYAST_PER_OBJ_FREE

object freeing allowed, tag freeing still works

FYAST_PER_OBJ_FREE_DEDUP

per obj freeing, dedup obj store

FYAST_SINGLE_LINEAR_RANGE

just a single linear range, no frees at all

FYAST_SINGLE_LINEAR_RANGE_DEDUP

single linear range, with dedup

struct fy_auto_allocator_cfg

struct fy_auto_allocator_cfg

auto allocator configuration

Definition

struct fy_auto_allocator_cfg {
    enum fy_auto_allocator_scenario_type scenario;
    size_t estimated_max_size;
}

Members

scenario

Auto allocator scenario

estimated_max_size

Estimated max content size (or 0 for don’t know)

fy_parser_checkpoint_create

struct fy_parser_checkpoint *fy_parser_checkpoint_create(struct fy_parser *fyp)

Create a parser checkpoint

Parameters:

• fyp (struct fy_parser*) – The parser

Description

Create a checkpoint of the parser’s current state. This allows you to save the parser state and potentially roll back to it later using fy_parser_rollback(). The checkpoint must be destroyed via fy_parser_checkpoint_destroy() when no longer needed.

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)

Destroy a parser checkpoint

Parameters:

• fypchk (struct fy_parser_checkpoint*) – The checkpoint to destroy

Description

Destroy 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)

Roll back the parser to a checkpoint

Parameters:

• fyp (struct fy_parser*) – The parser

• fypc (struct fy_parser_checkpoint*) – The checkpoint to roll back to

Description

Roll back the parser state to a previously created checkpoint. This allows you to revert the parser to an earlier state and re-parse from that point. The checkpoint remains valid after rollback and can be used again or destroyed via fy_parser_checkpoint_destroy().

Return

0 on success, -1 on error