.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "LIBFYAML-CORE" "3" "Mar 15, 2026" "" "libfyaml" .SH NAME libfyaml-core \- libfyaml core API .SH CORE .sp This is the single top\-level include for the entire libfyaml public API. Including it pulls in all subsystem headers: .INDENT 0.0 .IP \(bu 2 Core YAML parser, document tree, emitter, and diagnostics (\fBlibfyaml/libfyaml\-core.h\fP) .IP \(bu 2 General\-purpose utilities and portability macros (\fBlibfyaml/libfyaml\-util.h\fP) .IP \(bu 2 YAML path expression parser and executor (\fBlibfyaml/libfyaml\-path\-exec.h\fP) .IP \(bu 2 Document builder: event\-stream to tree conversion (\fBlibfyaml/libfyaml\-docbuild.h\fP) .IP \(bu 2 Document iterator: tree traversal and event replay (\fBlibfyaml/libfyaml\-dociter.h\fP) .IP \(bu 2 Composer: callback\-driven, path\-aware event processing (\fBlibfyaml/libfyaml\-composer.h\fP) .IP \(bu 2 Pluggable memory allocators (\fBlibfyaml/libfyaml\-allocator.h\fP) .IP \(bu 2 Thread pool for parallel work (\fBlibfyaml/libfyaml\-thread.h\fP) .IP \(bu 2 BLAKE3 cryptographic hashing (\fBlibfyaml/libfyaml\-blake3.h\fP) .IP \(bu 2 Alignment macros and helpers (\fBlibfyaml/libfyaml\-align.h\fP) .IP \(bu 2 Portable endian detection (\fBlibfyaml/libfyaml\-endian.h\fP) .IP \(bu 2 Portable atomic operations (\fBlibfyaml/libfyaml\-atomics.h\fP) .IP \(bu 2 Variable\-length size encoding (\fBlibfyaml/libfyaml\-vlsize.h\fP) .UNINDENT .sp For faster compilation you may include only the subsystem headers you need. All public symbols are prefixed with \fBfy_\fP (functions/types) or \fBFY_\fP (macros and constants). .SH YAML PARSER, DOCUMENT AND EMITTER .sp This header provides the complete YAML 1.2 / JSON parser, document tree, and emitter API — the core of libfyaml. It is the largest and most frequently used part of the public interface. .sp \fBThree complementary APIs\fP cover the full lifecycle of a YAML document: .sp \fIEvent\-based parsing\fP (\fBfy_parser_*\fP): A streaming interface similar to libyaml’s. The parser produces a sequence of typed events (stream\-start, document\-start, scalar, sequence\-start, …) without building an in\-memory tree. Ideal for large documents, filters, and transcoding pipelines. .sp \fIDocument tree\fP (\fBfy_document_*\fP, \fBfy_node_*\fP): Builds a fully navigable in\-memory tree from a YAML or JSON source. Nodes can be queried, modified, merged, and serialised. Path\-expression helpers (\fBfy_document_scanf()\fP, \fBfy_document_insert_at()\fP, …) provide XPath\-like access into the tree. .sp \fIEmitter\fP (\fBfy_emitter_*\fP): Serialises documents or raw event streams back to YAML or JSON with full control over formatting style, indentation, and quoting. Supports streaming output to files, memory buffers, or user\-supplied callbacks. .sp \fBDiagnostics\fP (\fBfy_diag_*\fP): A structured error\-reporting subsystem that attributes messages to precise source locations and integrates with IDE/compiler toolchains via a standard \fBfile:line:col: level: text\fP format. .sp All types are opaque pointers (\fBstruct fy_parser *\fP, \fBstruct fy_document *\fP, \fBstruct fy_node *\fP, …) so the ABI is stable across minor releases. .SS struct fy_version .INDENT 0.0 .TP .B struct fy_version The YAML version .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_version { int major; int minor; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B major Major version number .TP .B minor Major version number .UNINDENT .SS Description .sp The parser fills it according to the %YAML directive found in the document. .SS fy_version_compare .INDENT 0.0 .TP .B int fy_version_compare(const struct \fI\%fy_version\fP *va, const struct \fI\%fy_version\fP *vb) Compare two yaml versions .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBva\fP (const struct \fI\%fy_version\fP*) – The first version, if NULL use default version .IP \(bu 2 \fBvb\fP (const struct \fI\%fy_version\fP*) – The second version, if NULL use default version .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Compare the versions .SS Return .sp 0 if versions are equal, > 0 if version va is higher than vb < 0 if version va is lower than vb .SS fy_version_default .INDENT 0.0 .TP .B const struct \fI\%fy_version\fP *fy_version_default(void) Get the default version of the library .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvoid\fP – no arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the default version of the library, i.e. the highest stable version that is supported. .SS Return .sp The default YAML version of this library .SS fy_version_is_supported .INDENT 0.0 .TP .B bool fy_version_is_supported(const struct \fI\%fy_version\fP *vers) Check if supported version .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvers\fP (const struct \fI\%fy_version\fP*) – The version to check, NULL means default version. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check if the given YAML version is supported. .SS Return .sp true if version supported, false otherwise. .SS fy_version_supported_iterate .INDENT 0.0 .TP .B const struct \fI\%fy_version\fP *fy_version_supported_iterate(void **prevp) Iterate over the supported YAML versions .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBprevp\fP (void**) – The previous version iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method iterates over the supported YAML versions of this ibrary. The start of the iteration is signalled by a NULL in *prevp. .SS Return .sp The next node in sequence or NULL at the end of the sequence. .SS fy_shutdown .INDENT 0.0 .TP .B void fy_shutdown(void) Final cleanup before exit .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvoid\fP – no arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Some libraries \fIcough*libclang*\fP need explicit cleanup calls at the end of program execution, even if you’ve never called any of their functions. .sp This method will make sure it calls their cleanup functions so that no memory leaks are reported in valgrind etc. .SS struct fy_tag .INDENT 0.0 .TP .B struct fy_tag The YAML tag structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_tag { const char *handle; const char *prefix; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B handle Handle of the tag (i.e. \fI“!!”\fP) .TP .B prefix The prefix of the tag (i.e. \fI“tag:yaml.org,2002:”\fP) The parser fills it according to the %TAG directives encountered during parsing. .UNINDENT .SS struct fy_mark .INDENT 0.0 .TP .B struct fy_mark marker holding information about a location in a \fBstruct fy_input\fP .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_mark { size_t input_pos; int line; int column; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B input_pos Position of the mark (from the start of the current input) .TP .B line Line position (0 index based) .TP .B column Column position (0 index based) .UNINDENT .SS enum fy_error_type .INDENT 0.0 .TP .B enum fy_error_type The supported diagnostic/error types .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_error_type { FYET_DEBUG, FYET_INFO, FYET_NOTICE, FYET_WARNING, FYET_ERROR, FYET_MAX }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYET_DEBUG Debug level (disabled if library is not compiled in debug mode) .TP .B FYET_INFO Informational level .TP .B FYET_NOTICE Notice level .TP .B FYET_WARNING Warning level .TP .B FYET_ERROR Error level \- error reporting is using this level .TP .B FYET_MAX Non inclusive maximum fy_error_type value .UNINDENT .SS enum fy_error_module .INDENT 0.0 .TP .B enum fy_error_module Module which generated the diagnostic/error .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_error_module { FYEM_UNKNOWN, FYEM_ATOM, FYEM_SCAN, FYEM_PARSE, FYEM_DOC, FYEM_BUILD, FYEM_INTERNAL, FYEM_SYSTEM, FYEM_EMIT, FYEM_TYPESET, FYEM_DECODE, FYEM_ENCODE, FYEM_REFLECTION, FYEM_MAX }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYEM_UNKNOWN Unknown, default if not specific .TP .B FYEM_ATOM Atom module, used by atom chunking .TP .B FYEM_SCAN Scanner module .TP .B FYEM_PARSE Parser module .TP .B FYEM_DOC Document module .TP .B FYEM_BUILD Build document module (after tree is constructed) .TP .B FYEM_INTERNAL Internal error/diagnostic module .TP .B FYEM_SYSTEM System error/diagnostic module .TP .B FYEM_EMIT Emitter module .TP .B FYEM_TYPESET Prepare types module (C reflection) .TP .B FYEM_DECODE Decode, serialization \-> internal form module .TP .B FYEM_ENCODE Encode, internal form \-> serialized form module .TP .B FYEM_REFLECTION Generic reflection module messages .TP .B FYEM_MAX Non inclusive maximum fy_error_module value .UNINDENT .SS enum fy_parse_cfg_flags .INDENT 0.0 .TP .B enum fy_parse_cfg_flags Parse configuration flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYPCF_QUIET Quiet, do not output any information messages .TP .B FYPCF_COLLECT_DIAG Collect diagnostic/error messages .TP .B FYPCF_RESOLVE_DOCUMENT When producing documents, automatically resolve them .TP .B FYPCF_DISABLE_MMAP_OPT Disable mmap optimization .TP .B FYPCF_DISABLE_RECYCLING Disable recycling optimization .TP .B FYPCF_PARSE_COMMENTS Enable parsing of comments (experimental) .TP .B FYPCF_DISABLE_DEPTH_LIMIT Disable depth limit check, use with enlarged stack .TP .B FYPCF_DISABLE_ACCELERATORS Disable use of access accelerators (saves memory) .TP .B FYPCF_DISABLE_BUFFERING Disable use of buffering where possible .TP .B FYPCF_DEFAULT_VERSION_AUTO Automatically use the most recent version the library supports .TP .B FYPCF_DEFAULT_VERSION_1_1 Default version is YAML 1.1 .TP .B FYPCF_DEFAULT_VERSION_1_2 Default version is YAML 1.2 .TP .B FYPCF_DEFAULT_VERSION_1_3 Default version is YAML 1.3 (experimental) .TP .B FYPCF_SLOPPY_FLOW_INDENTATION Allow sloppy indentation in flow mode .TP .B FYPCF_PREFER_RECURSIVE Prefer recursive algorighms instead of iterative whenever possible .TP .B FYPCF_JSON_AUTO Automatically enable JSON mode (when extension is .json) .TP .B FYPCF_JSON_NONE Never enable JSON input mode .TP .B FYPCF_JSON_FORCE Force JSON mode always .TP .B FYPCF_YPATH_ALIASES Enable YPATH aliases mode .TP .B FYPCF_ALLOW_DUPLICATE_KEYS Allow duplicate keys on mappings .UNINDENT .SS Description .sp These flags control the operation of the parse and the debugging output/error reporting via filling in the \fI\%fy_parse_cfg\->flags\fP member. .SS struct fy_parse_cfg .INDENT 0.0 .TP .B struct fy_parse_cfg parser configuration structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_parse_cfg { const char *search_path; enum fy_parse_cfg_flags flags; void *userdata; struct fy_diag *diag; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B search_path Search path when accessing files, seperate with ‘:’ .TP .B flags Configuration flags .TP .B userdata Opaque user data pointer .TP .B diag Optional diagnostic interface to use .UNINDENT .SS Description .sp Argument to the \fI\%fy_parser_create()\fP method which perform parsing of YAML files. .SS enum fy_event_type .INDENT 0.0 .TP .B enum fy_event_type Event types .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYET_NONE No event .TP .B FYET_STREAM_START Stream start event .TP .B FYET_STREAM_END Stream end event .TP .B FYET_DOCUMENT_START Document start event .TP .B FYET_DOCUMENT_END Document end event .TP .B FYET_MAPPING_START YAML mapping start event .TP .B FYET_MAPPING_END YAML mapping end event .TP .B FYET_SEQUENCE_START YAML sequence start event .TP .B FYET_SEQUENCE_END YAML sequence end event .TP .B FYET_SCALAR YAML scalar event .TP .B FYET_ALIAS YAML alias event .UNINDENT .SS fy_event_type_get_text .INDENT 0.0 .TP .B const char *fy_event_type_get_text(enum \fI\%fy_event_type\fP type) Return text of an event type .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (enum \fI\%fy_event_type\fP) – The event type to get text from .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A pointer to a text, i.e for FYET_SCALAR “=VAL”. .SS enum fy_collection_style .INDENT 0.0 .TP .B enum fy_collection_style Collection styles supported by the parser/emitter .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_collection_style { FYCS_ANY, FYCS_BLOCK, FYCS_FLOW, FYCS_MAX }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYCS_ANY Any collection style, not generated by the parser. Lets the emitter to choose .TP .B FYCS_BLOCK Block style (not {}[]) .TP .B FYCS_FLOW Flow style {}[] .TP .B FYCS_MAX marks end of scalar styles .UNINDENT .SS enum fy_scalar_style .INDENT 0.0 .TP .B enum fy_scalar_style Scalar styles supported by the parser/emitter .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_scalar_style { FYSS_ANY, FYSS_PLAIN, FYSS_SINGLE_QUOTED, FYSS_DOUBLE_QUOTED, FYSS_LITERAL, FYSS_FOLDED, FYSS_MAX }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYSS_ANY Any scalar style, not generated by the parser. Lets the emitter to choose .TP .B FYSS_PLAIN Plain scalar style .TP .B FYSS_SINGLE_QUOTED Single quoted style .TP .B FYSS_DOUBLE_QUOTED Double quoted style .TP .B FYSS_LITERAL YAML literal block style .TP .B FYSS_FOLDED YAML folded block style .TP .B FYSS_MAX marks end of scalar styles .UNINDENT .SS struct fy_event_stream_start_data .INDENT 0.0 .TP .B struct fy_event_stream_start_data stream start event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_stream_start_data { struct fy_token *stream_start; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B stream_start The token that started the stream .UNINDENT .SS struct fy_event_stream_end_data .INDENT 0.0 .TP .B struct fy_event_stream_end_data stream end event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_stream_end_data { struct fy_token *stream_end; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B stream_end The token that ended the stream .UNINDENT .SS struct fy_event_document_start_data .INDENT 0.0 .TP .B struct fy_event_document_start_data doument start event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_document_start_data { struct fy_token *document_start; struct fy_document_state *document_state; bool implicit; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B document_start The token that started the document, or NULL if the document was implicitly started. .TP .B document_state The state of the document (i.e. information about the YAML version and configured tags) .TP .B implicit True if the document started implicitly .UNINDENT .SS struct fy_event_document_end_data .INDENT 0.0 .TP .B struct fy_event_document_end_data doument end event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_document_end_data { struct fy_token *document_end; bool implicit; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B document_end The token that ended the document, or NULL if the document was implicitly ended .TP .B implicit True if the document ended implicitly .UNINDENT .SS struct fy_event_alias_data .INDENT 0.0 .TP .B struct fy_event_alias_data alias event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_alias_data { struct fy_token *anchor; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B anchor The anchor token definining this alias. .UNINDENT .SS struct fy_event_scalar_data .INDENT 0.0 .TP .B struct fy_event_scalar_data scalar event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_scalar_data { struct fy_token *anchor; struct fy_token *tag; struct fy_token *value; bool tag_implicit; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B anchor anchor token or NULL .TP .B tag tag token or NULL .TP .B value scalar value token (cannot be NULL) .TP .B tag_implicit true if the tag was implicit or explicit .UNINDENT .SS struct fy_event_sequence_start_data .INDENT 0.0 .TP .B struct fy_event_sequence_start_data sequence start event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_sequence_start_data { struct fy_token *anchor; struct fy_token *tag; struct fy_token *sequence_start; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B anchor anchor token or NULL .TP .B tag tag token or NULL .TP .B sequence_start sequence start value token or NULL if the sequence was started implicitly .UNINDENT .SS struct fy_event_sequence_end_data .INDENT 0.0 .TP .B struct fy_event_sequence_end_data sequence end event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_sequence_end_data { struct fy_token *sequence_end; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B sequence_end The token that ended the sequence, or NULL if the sequence was implicitly ended .UNINDENT .SS struct fy_event_mapping_start_data .INDENT 0.0 .TP .B struct fy_event_mapping_start_data mapping start event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_mapping_start_data { struct fy_token *anchor; struct fy_token *tag; struct fy_token *mapping_start; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B anchor anchor token or NULL .TP .B tag tag token or NULL .TP .B mapping_start mapping start value token or NULL if the mapping was started implicitly .UNINDENT .SS struct fy_event_mapping_end_data .INDENT 0.0 .TP .B struct fy_event_mapping_end_data mapping end event data .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_event_mapping_end_data { struct fy_token *mapping_end; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B mapping_end The token that ended the mapping, or NULL if the mapping was implicitly ended .UNINDENT .SS struct fy_event .INDENT 0.0 .TP .B struct fy_event Event generated by the parser .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } ; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B type Type of the event, see \fI\%enum fy_event_type\fP .TP .B {unnamed_union} anonymous .TP .B stream_start Stream start information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_STREAM_START\fP .TP .B stream_end Stream end information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_STREAM_END\fP .TP .B document_start Document start information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_DOCUMENT_START\fP .TP .B document_end Document end information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_DOCUMENT_END\fP .TP .B alias Alias information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_ALIAS\fP .TP .B scalar Scalar information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_SCALAR\fP .TP .B sequence_start Sequence start information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_SEQUENCE_START\fP .TP .B sequence_end Sequence end information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_SEQUENCE_END\fP .TP .B mapping_start Mapping start information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_MAPPING_START\fP .TP .B mapping_end Mapping end information, it is valid when \fI\%fy_event\->type\fP is \fBenum FYET_MAPPING_END\fP .UNINDENT .SS Description .sp This structure is generated by the parser by each call to \fI\%fy_parser_parse()\fP and release by \fI\%fy_parser_event_free()\fP .SS enum fy_event_part .INDENT 0.0 .TP .B enum fy_event_part Select part of the event .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_event_part { FYEP_VALUE, FYEP_TAG, FYEP_ANCHOR }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYEP_VALUE The value of the event (the main token) .TP .B FYEP_TAG The tag of the event .TP .B FYEP_ANCHOR The anchor of the event .UNINDENT .SS fy_event_get_type .INDENT 0.0 .TP .B enum \fI\%fy_event_type\fP fy_event_get_type(const struct \fI\%fy_event\fP *fye) Get the event’s type .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (const struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the type of the event .SS Return .sp The event type, or FYET_NONE when the event is invalid .SS fy_event_data .INDENT 0.0 .TP .B void *fy_event_data(struct \fI\%fy_event\fP *fye) Get a pointer to the event data .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Some languages \fIcough*golang*cough\fP really don’t like unions, and anonymous unions in particular. .sp You should not have to use this in other language bindings. .SS Return .sp A pointer to the event data structure, or NULL if the event is invalid .SS fy_library_version .INDENT 0.0 .TP .B const char *fy_library_version(void) Return the library version string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvoid\fP – no arguments .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A pointer to a version string of the form .[[.][\-EXTRA\-VERSION\-INFO]] .SS fy_string_to_error_type .INDENT 0.0 .TP .B enum \fI\%fy_error_type\fP fy_string_to_error_type(const char *str) Return the error type from a string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstr\fP (const char*) – The string to convert to an error type .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The error type if greater or equal to zero, FYET_MAX otherwise .SS fy_error_type_to_string .INDENT 0.0 .TP .B const char *fy_error_type_to_string(enum \fI\%fy_error_type\fP type) Convert an error type to string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type to convert .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The string value of the error type or the empty string “” on error .SS fy_string_to_error_module .INDENT 0.0 .TP .B enum \fI\%fy_error_module\fP fy_string_to_error_module(const char *str) Return the error module from a string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstr\fP (const char*) – The string to convert to an error module .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The error type if greater or equal to zero, FYEM_MAX otherwise .SS fy_error_module_to_string .INDENT 0.0 .TP .B const char *fy_error_module_to_string(enum \fI\%fy_error_module\fP module) Convert an error module to string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmodule\fP (enum \fI\%fy_error_module\fP) – The error module to convert .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The string value of the error module or the empty string “” on error .SS fy_event_is_implicit .INDENT 0.0 .TP .B bool fy_event_is_implicit(struct \fI\%fy_event\fP *fye) Check whether the given event is an implicit one .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – A pointer to a \fI\%struct fy_event\fP to check. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the event is an implicit one. .SS fy_document_event_is_implicit .INDENT 0.0 .TP .B bool fy_document_event_is_implicit(const struct \fI\%fy_event\fP *fye) Check whether the given document event is an implicit one .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (const struct \fI\%fy_event\fP*) – A pointer to a \fI\%struct fy_event\fP to check. It must be either a document start or document end event. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the event is an implicit one. .SS fy_parser_create .INDENT 0.0 .TP .B struct fy_parser *fy_parser_create(const struct \fI\%fy_parse_cfg\fP *cfg) Create a parser. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The configuration for the parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a parser with its configuration \fBcfg\fP The parser may be destroyed by a corresponding call to \fI\%fy_parser_destroy()\fP\&. .SS Return .sp A pointer to the parser or NULL in case of an error. .SS fy_parser_destroy .INDENT 0.0 .TP .B void fy_parser_destroy(struct fy_parser *fyp) Destroy the given parser .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy a parser created earlier via \fI\%fy_parser_create()\fP\&. .SS fy_parser_get_cfg .INDENT 0.0 .TP .B const struct \fI\%fy_parse_cfg\fP *fy_parser_get_cfg(struct fy_parser *fyp) Get the configuration of a parser .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The configuration of the parser .SS fy_parser_get_diag .INDENT 0.0 .TP .B struct fy_diag *fy_parser_get_diag(struct fy_parser *fyp) Get the diagnostic object of a parser .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser to get the diagnostic object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return a pointer to the diagnostic object of a parser object. Note that the returned diag object has a reference taken so you should \fI\%fy_diag_unref()\fP it when you’re done with it. .SS Return .sp A pointer to a ref’ed diagnostic object or NULL in case of an error. .SS fy_parser_set_diag .INDENT 0.0 .TP .B int fy_parser_set_diag(struct fy_parser *fyp, struct fy_diag *diag) Set the diagnostic object of a parser .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser to replace the diagnostic object .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The parser’s new diagnostic object, NULL for default .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 0 if everything OK, \-1 otherwise .SS fy_parser_reset .INDENT 0.0 .TP .B int fy_parser_reset(struct fy_parser *fyp) Reset a parser completely .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser to reset .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Completely reset a parser, including after an error that caused a parser error to be emitted. .SS Return .sp 0 if the reset was successful, \-1 otherwise .SS fy_parser_set_input_file .INDENT 0.0 .TP .B int fy_parser_set_input_file(struct fy_parser *fyp, const char *file) Set the parser to process the given file .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfile\fP (const char*) – The file to parse. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Point the parser to the given \fBfile\fP for processing. The file is located by honoring the search path of the configuration set by the earlier call to \fI\%fy_parser_create()\fP\&. While the parser is in use the file will must be available. .SS Return .sp zero on success, \-1 on error .SS fy_parser_set_string .INDENT 0.0 .TP .B int fy_parser_set_string(struct fy_parser *fyp, const char *str, size_t len) Set the parser to process the given string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBstr\fP (const char*) – The YAML string to parse. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Point the parser to the given (NULL terminated) string. Note that while the parser is active the string must not go out of scope. .SS Return .sp zero on success, \-1 on error .SS fy_parser_set_malloc_string .INDENT 0.0 .TP .B int fy_parser_set_malloc_string(struct fy_parser *fyp, char *str, size_t len) Set the parser to process the given malloced string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBstr\fP (char*) – The YAML string to parse (allocated). .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp In case of an error the string is not freed. .SS Return .sp zero on success, \-1 on error .SS fy_parser_set_input_fp .INDENT 0.0 .TP .B int fy_parser_set_input_fp(struct fy_parser *fyp, const char *name, FILE *fp) Set the parser to process the given file .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBname\fP (const char*) – The label of the stream .IP \(bu 2 \fBfp\fP (FILE*) – The FILE pointer, it must be open in read mode. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Point the parser to use \fBfp\fP for processing. .SS Return .sp zero on success, \-1 on error .SS fy_parser_set_input_callback .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBuser\fP (void*) – The user data pointer .IP \(bu 2 \fBcallback\fP (ssize_t (*)(void *user, void *buf, size_t count)) – The callback method to request data with .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Point the parser to use a callback for input. .SS Return .sp zero on success, \-1 on error .SS fy_parser_set_input_fd .INDENT 0.0 .TP .B int fy_parser_set_input_fd(struct fy_parser *fyp, int fd) Set the parser to process the given file descriptor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfd\fP (int) – The file descriptor to use .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Point the parser to use \fBfd\fP for processing. .SS Return .sp zero on success, \-1 on error .SS fy_parser_parse .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_parser_parse(struct fy_parser *fyp) Parse and return the next event. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Each call to \fI\%fy_parser_parse()\fP 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 \fI\%fy_parser_event_free()\fP\&. .SS Return .sp The next event in the stream or NULL. .SS fy_parser_parse_peek .INDENT 0.0 .TP .B const struct \fI\%fy_event\fP *fy_parser_parse_peek(struct fy_parser *fyp) Parse and peek at the next event. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp It will return the next event that a call to fy_parser_parse would generate, but as read\-only. .sp You must not free this event. .SS Return .sp A peek at the next event in the stream or NULL. .SS fy_parser_skip .INDENT 0.0 .TP .B int fy_parser_skip(struct fy_parser *fyp) Skip the current scalar/collection .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Skips the current scalar or collection. .SS Return .sp 0 on success, \-1 on error .SS fy_parser_count_sequence_items .INDENT 0.0 .TP .B int fy_parser_count_sequence_items(struct fy_parser *fyp) Count the sequence items .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The number of sequence items on success, \-1 on error Note if the number of items exceeds INT_MAX, INT_MAX will be returned. .SS fy_parser_count_mapping_items .INDENT 0.0 .TP .B int fy_parser_count_mapping_items(struct fy_parser *fyp) Count the mapping items .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The number of mapping items on success, \-1 on error Note if the number of items exceeds INT_MAX, INT_MAX will be returned. .SS fy_parser_event_free .INDENT 0.0 .TP .B void fy_parser_event_free(struct fy_parser *fyp, struct \fI\%fy_event\fP *fye) Free an event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to free (may be NULL) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Free a previously returned event from \fI\%fy_parser_parse()\fP\&. .SS fy_parser_get_stream_error .INDENT 0.0 .TP .B bool fy_parser_get_stream_error(struct fy_parser *fyp) Check the parser for stream errors .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true in case of a stream error, false otherwise. .SS fy_parser_get_mode .INDENT 0.0 .TP .B enum fy_parser_mode fy_parser_get_mode(struct fy_parser *fyp) Get the parser mode .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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). .SS Return .sp The parser mode .SS fy_parser_vlog .INDENT 0.0 .TP .B void fy_parser_vlog(struct fy_parser *fyp, enum \fI\%fy_error_type\fP type, const char *fmt, va_list ap) Log using the parsers diagnostics printf style (va_arg) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a log on the parser diagnostic output .SS fy_parser_log .INDENT 0.0 .TP .B void fy_parser_log(struct fy_parser *fyp, enum \fI\%fy_error_type\fP type, const char *fmt, \&...) Log using the parsers diagnostics printf style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report on the parser’s diagnostics .SS fy_parser_vreport .INDENT 0.0 .TP .B void fy_parser_vreport(struct fy_parser *fyp, enum \fI\%fy_error_type\fP type, struct fy_token *fyt, const char *fmt, va_list ap) Report using the parsers diagnostics printf style and mark token (va_arg) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report on the parser and indicate the token’s position .SS fy_parser_report .INDENT 0.0 .TP .B void fy_parser_report(struct fy_parser *fyp, enum \fI\%fy_error_type\fP type, struct fy_token *fyt, const char *fmt, \&...) Report using the parsers diagnostics printf style and mark token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report on the parser and indicate the token’s position .SS fy_token_scalar_style .INDENT 0.0 .TP .B enum \fI\%fy_scalar_style\fP fy_token_scalar_style(struct fy_token *fyt) Get the style of a scalar token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The scalar token to get it’s style. Note that a NULL token is a \fBenum FYSS_PLAIN\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The scalar style of the token, or FYSS_PLAIN on each other case .SS fy_token_collection_style .INDENT 0.0 .TP .B enum \fI\%fy_collection_style\fP fy_token_collection_style(struct fy_token *fyt) Get the style of a collection token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The collection token to get it’s style. Note that a NULL token is a \fBenum FYCS_ANY\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The collection style of the token, or FYCS_ANY .SS fy_token_scalar_is_null .INDENT 0.0 .TP .B bool fy_token_scalar_is_null(struct fy_token *fyt) Test whether the scalar is null (content) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The scalar token to check for NULLity. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp true if is a null scalar, false otherwise .SS fy_token_get_text .INDENT 0.0 .TP .B const char *fy_token_get_text(struct fy_token *fyt, size_t *lenp) Get text (and length of it) of a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token out of which the text pointer will be returned. .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return a pointer to the text of a token along with the length of it. Note that this text is \fInot\fP NULL terminated. If you need a NULL terminated pointer use \fI\%fy_token_get_text0()\fP\&. .sp 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. .sp That means that the pointer is \fInot\fP guaranteed to be valid after the parser is destroyed. .sp If the token is ‘complex’ enough, then space shall be allocated, filled and returned. .sp Note that the concept of ‘simple’ and ‘complex’ is vague, and that’s on purpose. .SS Return .sp A pointer to the text representation of the token, while \fBlenp\fP will be assigned the character length of said representation. NULL in case of an error. .SS fy_token_get_text0 .INDENT 0.0 .TP .B const char *fy_token_get_text0(struct fy_token *fyt) Get zero terminated text of a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token out of which the text pointer will be returned. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_token_get_text()\fP instead if possible. .SS Return .sp A pointer to a zero terminated text representation of the token. NULL in case of an error. .SS fy_token_get_text_length .INDENT 0.0 .TP .B size_t fy_token_get_text_length(struct fy_token *fyt) Get length of the text of a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the length of the text representation of a token. .SS Return .sp 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. .SS enum fy_comment_placement .INDENT 0.0 .TP .B enum fy_comment_placement Comment placement relative to token .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_comment_placement { fycp_top, fycp_right, fycp_bottom }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B fycp_top Comment on top of token .TP .B fycp_right Comment to the right of the token .TP .B fycp_bottom Comment to the bottom of the token .UNINDENT .SS fy_token_get_comment .INDENT 0.0 .TP .B const char *fy_token_get_comment(struct fy_token *fyt, enum \fI\%fy_comment_placement\fP which) Get zero terminated comment of a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token out of which the comment text will be returned. .IP \(bu 2 \fBwhich\fP (enum \fI\%fy_comment_placement\fP) – The comment placement .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Get the comment that is attached at a token having the given placement. .SS Return .sp 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. .SS fy_token_get_comments .INDENT 0.0 .TP .B const char *fy_token_get_comments(struct fy_token *fyt) Get all comments of a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Get all the comments that are attached on a token .SS Return .sp A pointer to a zero terminated text representation of all the comments. The comments of all the placements are concatenated and returned as one. NULL in case of an error or if the event has no comments. .SS fy_token_set_comment .INDENT 0.0 .TP .B int fy_token_set_comment(struct fy_token *fyt, enum \fI\%fy_comment_placement\fP which, const char *text, size_t len) Attach a comment to a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token out of which the comment text will be attached .IP \(bu 2 \fBwhich\fP (enum \fI\%fy_comment_placement\fP) – The placement .IP \(bu 2 \fBtext\fP (const char*) – The text of the comment .IP \(bu 2 \fBlen\fP (size_t) – The length of the comment (FY_NT means the length of text) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Attach the given comment on the token at the specified placement. If another comment is already present it will be overriden. If text is NULL the comment is removed. .SS Return .sp 0 on success, \-1 on failure. .SS fy_event_get_comments .INDENT 0.0 .TP .B const char *fy_event_get_comments(struct \fI\%fy_event\fP *fye) Get all comments of an event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A pointer to a zero terminated text representation of all the comments. The comments of all the placements are concatenated and returned as one. NULL in case of an error or if the event has no comments. The pointer must be free’ed if it’s not NULL via a call to \fBfree()\fP .SS fy_node_get_comment .INDENT 0.0 .TP .B const char *fy_node_get_comment(struct fy_node *fyn, enum \fI\%fy_comment_placement\fP which) Get comment of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBwhich\fP (enum \fI\%fy_comment_placement\fP) – The placement of the comment .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A pointer to a zero terminated text representation of the comment. NULL in case of an error or if the event has no such comments. .SS fy_node_get_comments .INDENT 0.0 .TP .B const char *fy_node_get_comments(struct fy_node *fyn) Get all comments of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A pointer to a zero terminated text representation of all the comments. The comments of all the placements are concatenated and returned as one. NULL in case of an error or if the event has no comments. .SS struct fy_iter_chunk .INDENT 0.0 .TP .B struct fy_iter_chunk An iteration chunk .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_iter_chunk { const char *str; size_t len; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B str Pointer to the start of the chunk .TP .B len The size of the chunk .UNINDENT .SS Description .sp The iterator produces a stream of chunks which cover the whole object. .SS fy_token_iter_create .INDENT 0.0 .TP .B struct fy_token_iter *fy_token_iter_create(struct fy_token *fyt) Create a token iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token to iterate, or NULL. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an iterator for operating on the given token, or a generic iterator for use with \fI\%fy_token_iter_start()\fP\&. The iterator must be destroyed with a matching call to \fI\%fy_token_iter_destroy()\fP\&. .SS Return .sp A pointer to the newly created iterator, or NULL in case of an error. .SS fy_token_iter_destroy .INDENT 0.0 .TP .B void fy_token_iter_destroy(struct fy_token_iter *iter) Destroy the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator to destroy. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy the iterator created by \fI\%fy_token_iter_create()\fP\&. .SS fy_token_iter_start .INDENT 0.0 .TP .B void fy_token_iter_start(struct fy_token *fyt, struct fy_token_iter *iter) Start iterating over the contents of a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token to iterate over .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator to prepare. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Prepare an iterator for operating on the given token. The iterator must be created via a previous call to \fI\%fy_token_iter_create()\fP for user level API access. .SS fy_token_iter_finish .INDENT 0.0 .TP .B void fy_token_iter_finish(struct fy_token_iter *iter) Stop iterating over the contents of a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Stop the iteration operation. .SS fy_token_iter_peek_chunk .INDENT 0.0 .TP .B const struct \fI\%fy_iter_chunk\fP *fy_token_iter_peek_chunk(struct fy_token_iter *iter) Peek at the next iterator chunk .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Peek at the next iterator chunk .SS Return .sp A pointer to the next iterator chunk, or NULL in case there’s no other. .SS fy_token_iter_chunk_next .INDENT 0.0 .TP .B const struct \fI\%fy_iter_chunk\fP *fy_token_iter_chunk_next(struct fy_token_iter *iter, const struct \fI\%fy_iter_chunk\fP *curr, int *errp) Get next iterator chunk .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .IP \(bu 2 \fBcurr\fP (const struct \fI\%fy_iter_chunk\fP*) – The current chunk, or NULL for the first one. .IP \(bu 2 \fBerrp\fP (int*) – Pointer to an error return value or NULL .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Get the next iterator chunk in sequence, .SS Return .sp 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. .SS fy_token_iter_advance .INDENT 0.0 .TP .B void fy_token_iter_advance(struct fy_token_iter *iter, size_t len) Advance the iterator position .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .IP \(bu 2 \fBlen\fP (size_t) – Number of bytes to advance the iterator position .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Advance the read pointer of the iterator. Note that mixing calls of this with any call of \fI\%fy_token_iter_ungetc()\fP / \fI\%fy_token_iter_utf8_unget()\fP in a single iterator sequence leads to undefined behavior. .SS fy_token_iter_read .INDENT 0.0 .TP .B ssize_t fy_token_iter_read(struct fy_token_iter *iter, void *buf, size_t count) Read a block from an iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .IP \(bu 2 \fBbuf\fP (void*) – Pointer to a block of memory to receive the data. Must be at least count bytes long. .IP \(bu 2 \fBcount\fP (size_t) – Amount of bytes to read. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Read a block from an iterator. Note than mixing calls of this and any of the ungetc methods leads to undefined behavior. .SS Return .sp The amount of data read, or \-1 in case of an error. .SS fy_token_iter_getc .INDENT 0.0 .TP .B int fy_token_iter_getc(struct fy_token_iter *iter) Get a single character from an iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The next character in the iterator, or \-1 in case of an error, or end of stream. .SS fy_token_iter_ungetc .INDENT 0.0 .TP .B int fy_token_iter_ungetc(struct fy_token_iter *iter, int c) Ungets a single character from an iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .IP \(bu 2 \fBc\fP (int) – The character to push back, or \-1 to reset the pushback buffer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Pushes back a single character to an iterator stream. It will be returned in subsequent calls of \fI\%fy_token_iter_getc()\fP\&. Currently only a single character is allowed to be pushed back, and any further calls to ungetc will return an error. .SS Return .sp 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. .SS fy_token_iter_peekc .INDENT 0.0 .TP .B int fy_token_iter_peekc(struct fy_token_iter *iter) Peeks at single character from an iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The next character in the iterator, or \-1 in case of an error, or end of stream. .SS fy_token_iter_utf8_get .INDENT 0.0 .TP .B int fy_token_iter_utf8_get(struct fy_token_iter *iter) Get a single utf8 character from an iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The next utf8 character in the iterator, or \-1 in case of an error, or end of stream. .SS fy_token_iter_utf8_unget .INDENT 0.0 .TP .B int fy_token_iter_utf8_unget(struct fy_token_iter *iter, int c) Ungets a single utf8 character from an iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .IP \(bu 2 \fBc\fP (int) – The character to push back, or \-1 to reset the pushback buffer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Pushes back a single utf8 character to an iterator stream. It will be returned in subsequent calls of \fBfy_token_iter_utf8_getc()\fP\&. Currently only a single character is allowed to be pushed back, and any further calls to ungetc will return an error. .SS Return .sp 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. .SS fy_token_iter_utf8_peek .INDENT 0.0 .TP .B int fy_token_iter_utf8_peek(struct fy_token_iter *iter) Peeks at single utf8 character from an iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBiter\fP (struct fy_token_iter*) – The iterator. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The next utf8 character in the iterator, or \-1 in case of an error, or end of stream. .SS fy_parse_load_document .INDENT 0.0 .TP .B struct fy_document *fy_parse_load_document(struct fy_parser *fyp) Parse the next document from the parser stream .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The next document from the parser stream. .SS fy_parse_document_destroy .INDENT 0.0 .TP .B void fy_parse_document_destroy(struct fy_parser *fyp, struct fy_document *fyd) Destroy a document created by \fI\%fy_parse_load_document()\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to destroy .UNINDENT .UNINDENT .UNINDENT .SS fy_document_resolve .INDENT 0.0 .TP .B int fy_document_resolve(struct fy_document *fyd) Resolve anchors and merge keys .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to resolve .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method performs resolution of the given document, by replacing references to anchors with their contents and handling merge keys (<<) .SS Return .sp zero on success, \-1 on error .SS fy_document_has_directives .INDENT 0.0 .TP .B bool fy_document_has_directives(const struct fy_document *fyd) Document directive check .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (const struct fy_document*) – The document to check for directives existence .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks whether the given document has any directives, i.e. \fBTAG\fP or \fBVERSION\fP\&. .SS Return .sp true if directives exist, false if not .SS fy_document_has_explicit_document_start .INDENT 0.0 .TP .B bool fy_document_has_explicit_document_start(const struct fy_document *fyd) Explicit document start check .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (const struct fy_document*) – The document to check for explicit start marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks whether the given document has an explicit document start marker, i.e. — .SS Return .sp true if document has an explicit document start marker, false if not .SS fy_document_has_explicit_document_end .INDENT 0.0 .TP .B bool fy_document_has_explicit_document_end(const struct fy_document *fyd) Explicit document end check .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (const struct fy_document*) – The document to check for explicit end marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks whether the given document has an explicit document end marker, i.e. … .SS Return .sp true if document has an explicit document end marker, false if not .SS fy_node_document .INDENT 0.0 .TP .B struct fy_document *fy_node_document(struct fy_node *fyn) Retreive the document the node belong to .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to retreive it’s document .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The document of the node, or NULL in case of an error, or when the node has no document attached. .SS enum fy_emitter_write_type .INDENT 0.0 .TP .B enum fy_emitter_write_type Type of the emitted output .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B fyewt_document_indicator Output chunk is a document indicator .TP .B fyewt_tag_directive Output chunk is a tag directive .TP .B fyewt_version_directive Output chunk is a version directive .TP .B fyewt_indent Output chunk is a document indicator .TP .B fyewt_indicator Output chunk is an indicator .TP .B fyewt_whitespace Output chunk is white space .TP .B fyewt_plain_scalar Output chunk is a plain scalar .TP .B fyewt_single_quoted_scalar Output chunk is a single quoted scalar .TP .B fyewt_double_quoted_scalar Output chunk is a double quoted scalar .TP .B fyewt_literal_scalar Output chunk is a literal block scalar .TP .B fyewt_folded_scalar Output chunk is a folded block scalar .TP .B fyewt_anchor Output chunk is an anchor .TP .B fyewt_tag Output chunk is a tag .TP .B fyewt_linebreak Output chunk is a linebreak .TP .B fyewt_alias Output chunk is an alias .TP .B fyewt_terminating_zero Output chunk is a terminating zero .TP .B fyewt_plain_scalar_key Output chunk is an plain scalar key .TP .B fyewt_single_quoted_scalar_key Output chunk is an single quoted scalar key .TP .B fyewt_double_quoted_scalar_key Output chunk is an double quoted scalar key .TP .B fyewt_comment Output chunk is a comment .TP .B fyewt_indicator_question_mark ? indicator .TP .B fyewt_indicator_colon : indicator .TP .B fyewt_indicator_dash .INDENT 7.0 .IP \(bu 2 indicator .UNINDENT .TP .B fyewt_indicator_left_bracket [ indicator .TP .B fyewt_indicator_right_bracket ] indicator .TP .B fyewt_indicator_left_brace { indicator .TP .B fyewt_indicator_right_brace } indicator .TP .B fyewt_indicator_comma , indicator .TP .B fyewt_indicator_bar .nf indicator .fi .sp .TP .B fyewt_indicator_greater > indicator .TP .B fyewt_indicator_single_quote_start ‘ indicator .TP .B fyewt_indicator_single_quote_end ‘ indicator .TP .B fyewt_indicator_double_quote_start “ indicator .TP .B fyewt_indicator_double_quote_end “ indicator .TP .B fyewt_indicator_ambersand & indicator .TP .B fyewt_indicator_star .INDENT 7.0 .IP \(bu 2 indicator .UNINDENT .TP .B fyewt_indicator_chomp chomp indicator (\- or +) .TP .B fyewt_indicator_explicit_indent explicit indent indicator (0\-9) .UNINDENT .SS Description .sp Describes the kind of emitted output, which makes it possible to colorize the output, or do some other content related filtering. .SS enum fy_emitter_cfg_flags .INDENT 0.0 .TP .B enum fy_emitter_cfg_flags Emitter configuration flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYECF_SORT_KEYS Sort key when emitting .TP .B FYECF_OUTPUT_COMMENTS Output comments (experimental) .TP .B FYECF_STRIP_LABELS Strip labels when emitting .TP .B FYECF_STRIP_TAGS Strip tags when emitting .TP .B FYECF_STRIP_DOC Strip document tags and markers when emitting .TP .B FYECF_NO_ENDING_NEWLINE Do not output ending new line (useful for single line mode) .TP .B FYECF_STRIP_EMPTY_KV Remove all keys with empty values from the output (not available in streaming mode) .TP .B FYECF_EXTENDED_CFG Extend configuration, this config structure is embedded in a fy_emitter_xcfg. .TP .B FYECF_INDENT_DEFAULT Default emit output indent .TP .B FYECF_INDENT_1 Output indent is 1 .TP .B FYECF_INDENT_2 Output indent is 2 .TP .B FYECF_INDENT_3 Output indent is 3 .TP .B FYECF_INDENT_4 Output indent is 4 .TP .B FYECF_INDENT_5 Output indent is 5 .TP .B FYECF_INDENT_6 Output indent is 6 .TP .B FYECF_INDENT_7 Output indent is 7 .TP .B FYECF_INDENT_8 Output indent is 8 .TP .B FYECF_INDENT_9 Output indent is 9 .TP .B FYECF_WIDTH_DEFAULT Default emit output width .TP .B FYECF_WIDTH_80 Output width is 80 .TP .B FYECF_WIDTH_132 Output width is 132 .TP .B FYECF_WIDTH_INF Output width is infinite .TP .B FYECF_MODE_ORIGINAL Emit using the same flow mode as the original .TP .B FYECF_MODE_BLOCK Emit using only the block mode .TP .B FYECF_MODE_FLOW Emit using only the flow mode .TP .B FYECF_MODE_FLOW_ONELINE Emit using only the flow mode (in one line) .TP .B FYECF_MODE_JSON Emit using JSON mode (non type preserving) .TP .B FYECF_MODE_JSON_TP Emit using JSON mode (type preserving) .TP .B FYECF_MODE_JSON_ONELINE Emit using JSON mode (non type preserving, one line) .TP .B FYECF_MODE_DEJSON Emit YAML trying to pretify JSON .TP .B FYECF_MODE_PRETTY Emit YAML that tries to look good .TP .B FYECF_MODE_MANUAL Emit YAML respecting all manual style hints (reformats if needed) .TP .B FYECF_MODE_FLOW_COMPACT Emit using only the flow mode in as much as possible compact form .TP .B FYECF_MODE_JSON_COMPACT Emit using JSON compact form .TP .B FYECF_DOC_START_MARK_AUTO Automatically generate document start markers if required .TP .B FYECF_DOC_START_MARK_OFF Do not generate document start markers .TP .B FYECF_DOC_START_MARK_ON Always generate document start markers .TP .B FYECF_DOC_END_MARK_AUTO Automatically generate document end markers if required .TP .B FYECF_DOC_END_MARK_OFF Do not generate document end markers .TP .B FYECF_DOC_END_MARK_ON Always generate document end markers .TP .B FYECF_VERSION_DIR_AUTO Automatically generate version directive .TP .B FYECF_VERSION_DIR_OFF Never generate version directive .TP .B FYECF_VERSION_DIR_ON Always generate version directive .TP .B FYECF_TAG_DIR_AUTO Automatically generate tag directives .TP .B FYECF_TAG_DIR_OFF Never generate tag directives .TP .B FYECF_TAG_DIR_ON Always generate tag directives .TP .B FYECF_DEFAULT The default emitter configuration .UNINDENT .SS Description .sp These flags control the operation of the emitter .SS struct fy_emitter_cfg .INDENT 0.0 .TP .B struct fy_emitter_cfg emitter configuration structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B flags Configuration flags .TP .B output Pointer to the method that will perform output. .TP .B userdata Opaque user data pointer .TP .B diag Diagnostic interface .UNINDENT .SS Description .sp Argument to the \fI\%fy_emitter_create()\fP method which is the way to convert a runtime document structure back to YAML. .SS enum fy_emitter_xcfg_flags .INDENT 0.0 .TP .B enum fy_emitter_xcfg_flags Emitter extended configuration flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_emitter_xcfg_flags { FYEXCF_COLOR_AUTO, FYEXCF_COLOR_NONE, FYEXCF_COLOR_FORCE, FYEXCF_OUTPUT_STDOUT, FYEXCF_OUTPUT_STDERR, FYEXCF_OUTPUT_FILE, FYEXCF_OUTPUT_FD, FYEXCF_NULL_OUTPUT, FYEXCF_OUTPUT_FILENAME, FYEXCF_VISIBLE_WS, FYEXCF_EXTENDED_INDICATORS, FYEXCF_INDENTED_SEQ_IN_MAP, FYEXCF_PRESERVE_FLOW_LAYOUT }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYEXCF_COLOR_AUTO Automatically colorize if on a terminal .TP .B FYEXCF_COLOR_NONE Do not colorize output .TP .B FYEXCF_COLOR_FORCE Force color generation .TP .B FYEXCF_OUTPUT_STDOUT Output to stdout (default) .TP .B FYEXCF_OUTPUT_STDERR Output to stderr, instead of stdout .TP .B FYEXCF_OUTPUT_FILE Output to the fp FILE pointer .TP .B FYEXCF_OUTPUT_FD Output to the fd file descriptor .TP .B FYEXCF_NULL_OUTPUT No output .TP .B FYEXCF_OUTPUT_FILENAME Output to the given filename .TP .B FYEXCF_VISIBLE_WS Make white space visible .TP .B FYEXCF_EXTENDED_INDICATORS Extend the indicators generated .TP .B FYEXCF_INDENTED_SEQ_IN_MAP Indent block sequences that are mapping values .TP .B FYEXCF_PRESERVE_FLOW_LAYOUT Preserve oneline flow collections in streaming mode .UNINDENT .SS Description .sp These flags control the operation of the emitter. If no extended configuration mode is enabled all the flags are assumed 0. .SS struct fy_emitter_xcfg .INDENT 0.0 .TP .B struct fy_emitter_xcfg emitter extended configuration structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_emitter_xcfg { struct fy_emitter_cfg cfg; enum fy_emitter_xcfg_flags xflags; const char *colors[FYEWT_COUNT]; union { FILE *output_fp; int output_fd; const char *output_filename; } ; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B cfg The standard emitter configuration .TP .B xflags Extra configuration flags .TP .B colors ANSI color overrides for the default output method .TP .B {unnamed_union} anonymous .TP .B output_fp The output FILE *, FYEXCF_FILE_OUTPUT must be set .TP .B output_fd The output file descriptor, FYEXCF_FD_OUTPUT must be set .TP .B output_filename The output filename, FYEXCF_FILENAME_OUTPUT must be set .UNINDENT .SS Description .sp Argument to the fy_emitter create when FYECF_EXTENDED_CFG bit is set. .SS fy_emitter_create .INDENT 0.0 .TP .B struct fy_emitter *fy_emitter_create(const struct \fI\%fy_emitter_cfg\fP *cfg) Create an emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_emitter_cfg\fP*) – The emitter configuration .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates an emitter using the supplied configuration .SS Return .sp The newly created emitter or NULL on error. .SS fy_emitter_destroy .INDENT 0.0 .TP .B void fy_emitter_destroy(struct fy_emitter *emit) Destroy an emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy an emitter previously created by \fI\%fy_emitter_create()\fP .SS fy_emitter_get_cfg .INDENT 0.0 .TP .B const struct \fI\%fy_emitter_cfg\fP *fy_emitter_get_cfg(struct fy_emitter *emit) Get the configuration of an emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The configuration of the emitter .SS fy_emitter_get_diag .INDENT 0.0 .TP .B struct fy_diag *fy_emitter_get_diag(struct fy_emitter *emit) Get the diagnostic object of an emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter to get the diagnostic object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return a pointer to the diagnostic object of an emitter object. Note that the returned diag object has a reference taken so you should \fI\%fy_diag_unref()\fP it when you’re done with it. .SS Return .sp A pointer to a ref’ed diagnostic object or NULL in case of an error. .SS fy_emitter_set_diag .INDENT 0.0 .TP .B int fy_emitter_set_diag(struct fy_emitter *emit, struct fy_diag *diag) Set the diagnostic object of an emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter to replace the diagnostic object .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The emitter’s new diagnostic object, NULL for default .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 0 if everything OK, \-1 otherwise .SS fy_emitter_set_finalizer .INDENT 0.0 .TP .B void fy_emitter_set_finalizer(struct fy_emitter *emit, void (*finalizer)(struct fy_emitter *emit)) Set emitter finalizer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter to replace the diagnostic object .IP \(bu 2 \fBfinalizer\fP (void (*)(struct fy_emitter *emit)) – The finalizer callback .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Set a method callback to be called when the emitter is disposed of. If finalizer is NULL, then the method is removed. .SS struct fy_emitter_default_output_data .INDENT 0.0 .TP .B struct fy_emitter_default_output_data emitter default output configuration .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_emitter_default_output_data { FILE *fp; bool colorize; bool visible; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B fp File where the output is directed to .TP .B colorize Use ANSI color sequences to colorize the output .TP .B visible Make whitespace visible (requires a UTF8 capable terminal) .UNINDENT .SS Description .sp This is the argument to the default output method of the emitter. .SS fy_emitter_default_output .INDENT 0.0 .TP .B int fy_emitter_default_output(struct fy_emitter *fye, enum \fI\%fy_emitter_write_type\fP type, const char *str, int len, void *userdata) The default colorizing output method .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBtype\fP (enum \fI\%fy_emitter_write_type\fP) – Type of the emitted output .IP \(bu 2 \fBstr\fP (const char*) – Pointer to the string to output .IP \(bu 2 \fBlen\fP (int) – Length of the string .IP \(bu 2 \fBuserdata\fP (void*) – Must point to a fy_emitter_default_output_data structure .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This is the default colorizing output method. Will be used when the output field of the emitter configuration is NULL. .SS Return .sp 0 on success, \-1 on error .SS fy_document_default_emit_to_fp .INDENT 0.0 .TP .B int fy_document_default_emit_to_fp(struct fy_document *fyd, FILE *fp) Emit a document to a file, using defaults .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to emit .IP \(bu 2 \fBfp\fP (FILE*) – The file where the output is sent .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_event .INDENT 0.0 .TP .B int fy_emit_event(struct fy_emitter *emit, struct \fI\%fy_event\fP *fye) Queue (and possibly emit) an event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter to use .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to queue for emission .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Queue and output using the emitter. This is the streaming output method which does not require creating a document. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_vevent .INDENT 0.0 .TP .B int fy_emit_vevent(struct fy_emitter *emit, enum \fI\%fy_event_type\fP type, va_list ap) Queue (and possibly emit) an event using varargs .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter to use .IP \(bu 2 \fBtype\fP (enum \fI\%fy_event_type\fP) – The event type to create .IP \(bu 2 \fBap\fP (va_list) – The variable argument list pointer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Queue and output using the emitter. The format is identical to the one used in \fI\%fy_emit_event_vcreate()\fP\&. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_eventf .INDENT 0.0 .TP .B int fy_emit_eventf(struct fy_emitter *emit, enum \fI\%fy_event_type\fP type, \&...) Queue (and possibly emit) an event using variable args .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter to use .IP \(bu 2 \fBtype\fP (enum \fI\%fy_event_type\fP) – The event type to create .IP \(bu 2 \fBellipsis\fP (ellipsis) – The optional extra arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Queue and output using the emitter. The format is identical to the one used in \fI\%fy_emit_event_create()\fP\&. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_scalar_write .INDENT 0.0 .TP .B int fy_emit_scalar_write(struct fy_emitter *fye, enum \fI\%fy_scalar_style\fP style, const char *anchor, const char *tag, const char *buf, size_t count) Emit a scalar with write semantics .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct fy_emitter*) – The emitter to use .IP \(bu 2 \fBstyle\fP (enum \fI\%fy_scalar_style\fP) – The scalar style to use .IP \(bu 2 \fBanchor\fP (const char*) – The anchor or NULL .IP \(bu 2 \fBtag\fP (const char*) – The tag or NULL .IP \(bu 2 \fBbuf\fP (const char*) – Pointer to the buffer .IP \(bu 2 \fBcount\fP (size_t) – The number of bytes to write .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Queue and output using the emitter a scalar using a standard write interface. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_scalar_vprintf .INDENT 0.0 .TP .B int fy_emit_scalar_vprintf(struct fy_emitter *fye, enum \fI\%fy_scalar_style\fP style, const char *anchor, const char *tag, const char *fmt, va_list ap) Emit a scalar with vprintf semantics .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct fy_emitter*) – The emitter to use .IP \(bu 2 \fBstyle\fP (enum \fI\%fy_scalar_style\fP) – The scalar style to use .IP \(bu 2 \fBanchor\fP (const char*) – The anchor or NULL .IP \(bu 2 \fBtag\fP (const char*) – The tag or NULL .IP \(bu 2 \fBfmt\fP (const char*) – The printf like format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Queue and output using the emitter a scalar using a standard vprintf interface. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_scalar_printf .INDENT 0.0 .TP .B int fy_emit_scalar_printf(struct fy_emitter *fye, enum \fI\%fy_scalar_style\fP style, const char *anchor, const char *tag, const char *fmt, \&...) Emit a scalar with printf semantics .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct fy_emitter*) – The emitter to use .IP \(bu 2 \fBstyle\fP (enum \fI\%fy_scalar_style\fP) – The scalar style to use .IP \(bu 2 \fBanchor\fP (const char*) – The anchor or NULL .IP \(bu 2 \fBtag\fP (const char*) – The tag or NULL .IP \(bu 2 \fBfmt\fP (const char*) – The printf like format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Queue and output using the emitter a scalar using a standard printf interface. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_event_from_parser .INDENT 0.0 .TP .B int fy_emit_event_from_parser(struct fy_emitter *emit, struct fy_parser *fyp, struct \fI\%fy_event\fP *fye) Queue (and possibly emit) an event generated by the parser. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter to use .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser that generated the event .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to queue for emission .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Queue and output using the emitter. This is the streaming output method which does not require creating a document. Similar to \fI\%fy_emit_event()\fP but it is more efficient. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_document .INDENT 0.0 .TP .B int fy_emit_document(struct fy_emitter *emit, struct fy_document *fyd) Emit the document using the emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to emit .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a document in YAML format using the emitter. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_document_start .INDENT 0.0 .TP .B int fy_emit_document_start(struct fy_emitter *emit, struct fy_document *fyd, struct fy_node *fyn) Emit document start using the emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to use for emitting it’s start .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The root (or NULL for using the document’s root) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a document start using the emitter. This is used in case you need finer control over the emitting output. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_document_end .INDENT 0.0 .TP .B int fy_emit_document_end(struct fy_emitter *emit) Emit document end using the emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a document end using the emitter. This is used in case you need finer control over the emitting output. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_node .INDENT 0.0 .TP .B int fy_emit_node(struct fy_emitter *emit, struct fy_node *fyn) Emit a single node using the emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to emit .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a single node using the emitter. This is used in case you need finer control over the emitting output. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_root_node .INDENT 0.0 .TP .B int fy_emit_root_node(struct fy_emitter *emit, struct fy_node *fyn) Emit a single root node using the emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The root node to emit .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a single root node using the emitter. This is used in case you need finer control over the emitting output. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_body_node .INDENT 0.0 .TP .B int fy_emit_body_node(struct fy_emitter *emit, struct fy_node *fyn) Emit a single body node using the emitter .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The body node to emit .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_explicit_document_end .INDENT 0.0 .TP .B int fy_emit_explicit_document_end(struct fy_emitter *emit) Emit an explicit document end .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits an explicit document end, i.e. … . Use this if you you need finer control over the emitting output. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_document_to_fp .INDENT 0.0 .TP .B int fy_emit_document_to_fp(struct fy_document *fyd, enum \fI\%fy_emitter_cfg_flags\fP flags, FILE *fp) Emit a document to an file pointer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to emit .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .IP \(bu 2 \fBfp\fP (FILE*) – The file pointer to output to .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a document from the root to the given file pointer. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_document_to_file .INDENT 0.0 .TP .B int fy_emit_document_to_file(struct fy_document *fyd, enum \fI\%fy_emitter_cfg_flags\fP flags, const char *filename) Emit a document to file .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to emit .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .IP \(bu 2 \fBfilename\fP (const char*) – The filename to output to, or NULL for stdout .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a document from the root to the given file. The file will be fopen’ed using a “wa” mode. .SS Return .sp 0 on success, \-1 on error .SS fy_emit_document_to_fd .INDENT 0.0 .TP .B int fy_emit_document_to_fd(struct fy_document *fyd, enum \fI\%fy_emitter_cfg_flags\fP flags, int fd) Emit a document to a file descriptor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to emit .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .IP \(bu 2 \fBfd\fP (int) – The file descriptor to output to .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a document from the root to the given file descriptor .SS Return .sp 0 on success, \-1 on error .SS fy_emit_document_to_buffer .INDENT 0.0 .TP .B int fy_emit_document_to_buffer(struct fy_document *fyd, enum \fI\%fy_emitter_cfg_flags\fP flags, char *buf, size_t size) Emit a document to a buffer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to emit .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .IP \(bu 2 \fBbuf\fP (char*) – Pointer to the buffer area to fill .IP \(bu 2 \fBsize\fP (size_t) – Size of the buffer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits an document from the root to the given buffer. If the document does not fit, an error will be returned. .SS Return .sp A positive number, which is the size of the emitted document on the buffer on success, \-1 on error .SS fy_emit_document_to_string .INDENT 0.0 .TP .B char *fy_emit_document_to_string(struct fy_document *fyd, enum \fI\%fy_emitter_cfg_flags\fP flags) Emit a document to an allocated string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to emit .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits an document from the root to a string which will be dynamically allocated. .SS Return .sp A pointer to the allocated string, or NULL in case of an error .SS fy_emit_node_to_buffer .INDENT 0.0 .TP .B int fy_emit_node_to_buffer(struct fy_node *fyn, enum \fI\%fy_emitter_cfg_flags\fP flags, char *buf, size_t size) Emit a node (recursively) to a buffer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to emit .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .IP \(bu 2 \fBbuf\fP (char*) – Pointer to the buffer area to fill .IP \(bu 2 \fBsize\fP (size_t) – Size of the buffer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a node recursively to the given buffer. If the document does not fit, an error will be returned. .SS Return .sp A positive number, which is the size of the emitted node on the buffer on success, \-1 on error .SS fy_emit_node_to_string .INDENT 0.0 .TP .B char *fy_emit_node_to_string(struct fy_node *fyn, enum \fI\%fy_emitter_cfg_flags\fP flags) Emit a node to an allocated string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to emit .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Emits a node recursively to a string which will be dynamically allocated. .SS Return .sp A pointer to the allocated string, or NULL in case of an error .SS fy_emit_to_buffer .INDENT 0.0 .TP .B struct fy_emitter *fy_emit_to_buffer(enum \fI\%fy_emitter_cfg_flags\fP flags, char *buf, size_t size) Create an emitter for buffer output. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .IP \(bu 2 \fBbuf\fP (char*) – Pointer to the buffer area to fill .IP \(bu 2 \fBsize\fP (size_t) – Size of the buffer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a special purpose emitter for buffer output. Calls to \fI\%fy_emit_event()\fP populate the buffer. The contents are retreived by a call to \fI\%fy_emit_to_buffer_collect()\fP .SS Return .sp The newly created emitter or NULL on error. .SS fy_emit_to_buffer_collect .INDENT 0.0 .TP .B char *fy_emit_to_buffer_collect(struct fy_emitter *emit, size_t *sizep) Collect the buffer emitter output .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBsizep\fP (size_t*) – Pointer to the size to be filled .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Collects the output of the emitter which was created by \fI\%fy_emit_to_buffer()\fP and populated using \fI\%fy_emit_event()\fP calls. The NULL terminated returned buffer is the same as the one used in the \fI\%fy_emit_to_buffer()\fP call and the sizep argument will be filled with the size of the buffer. .SS Return .sp The buffer or NULL in case of an error. .SS fy_emit_to_string .INDENT 0.0 .TP .B struct fy_emitter *fy_emit_to_string(enum \fI\%fy_emitter_cfg_flags\fP flags) Create an emitter to create a dynamically allocated string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBflags\fP (enum \fI\%fy_emitter_cfg_flags\fP) – The emitter flags to use .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a special purpose emitter for output to a dynamically allocated string. Calls to \fI\%fy_emit_event()\fP populate the buffer. The contents are retreived by a call to \fI\%fy_emit_to_string_collect()\fP .SS Return .sp The newly created emitter or NULL on error. .SS fy_emit_to_string_collect .INDENT 0.0 .TP .B char *fy_emit_to_string_collect(struct fy_emitter *emit, size_t *sizep) Collect the string emitter output .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBsizep\fP (size_t*) – Pointer to the size to be filled .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Collects the output of the emitter which was created by \fI\%fy_emit_to_string()\fP and populated using \fI\%fy_emit_event()\fP calls. The NULL terminated returned buffer is dynamically allocated and must be freed via a call to \fBfree()\fP\&. The sizep argument will be filled with the size of the buffer. .SS Return .sp The dynamically allocated string or NULL in case of an error. .SS fy_node_copy .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document which the resulting node will be associated with .IP \(bu 2 \fBfyn_from\fP (struct fy_node*) – The source node to recursively copy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp Note that the copy includes all anchors contained in the subtree of the source, so this call will register them with the document. .SS Return .sp The copied node on success, NULL on error .SS fy_document_clone .INDENT 0.0 .TP .B struct fy_document *fy_document_clone(struct fy_document *fydsrc) Clones a document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydsrc\fP (struct fy_document*) – The source document to clone .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The newly created clone document, or NULL in case of an error .SS fy_node_insert .INDENT 0.0 .TP .B int fy_node_insert(struct fy_node *fyn_to, struct fy_node *fyn_from) Insert a node to the given node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_to\fP (struct fy_node*) – The target node .IP \(bu 2 \fBfyn_from\fP (struct fy_node*) – The source node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Insert a node to another node. If \fBfyn_from\fP is NULL then this operation will delete the \fBfyn_to\fP node. .SS The operation varies according to the types of the arguments .sp from: scalar .sp to: another\-scalar \-> scalar to: { key: value } \-> scalar to: [ seq0, seq1 ] \-> scalar .sp from: [ seq2 ] to: scalar \-> [ seq2 ] to: { key: value } \-> [ seq2 ] to: [ seq0, seq1 ] \-> [ seq0, seq1, sec2 ] .sp 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 } .sp from: { key: another\-value } to: scalar \-> { key: another\-value } to: { key: value } \-> { key: another\-value } to: [ seq0, seq1 ] \-> { key: another\-value } .SS The rules are .INDENT 0.0 .IP \(bu 2 If target node changes type, source ovewrites target. .IP \(bu 2 If source or target node are scalars, source it overwrites target. .IP \(bu 2 If target and source are sequences the items of the source sequence are appended to the target sequence. .IP \(bu 2 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. .UNINDENT .SS Return .sp 0 on success, \-1 on error .SS fy_node_delete .INDENT 0.0 .TP .B int fy_node_delete(struct fy_node *fyn) Delete a node from a document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to delete. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp This is an alias for fy_document_insert_at(fyn, NULL) .sp 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. .SS Return .sp 0 on success, \-1 on error .SS fy_document_insert_at .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBpath\fP (const char*) – The path where the insert operation will target .IP \(bu 2 \fBpathlen\fP (size_t) – The length of the path (or \-1 if ‘0’ terminated) .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The source node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Insert a node to a given point in the document. If \fBfyn\fP is NULL then this operation will delete the target node. .sp Please see fy_node_insert for details of operation. .sp 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. .SS Return .sp 0 on success, \-1 on error .SS enum fy_node_type .INDENT 0.0 .TP .B enum fy_node_type Node type .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_node_type { FYNT_SCALAR, FYNT_SEQUENCE, FYNT_MAPPING }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYNT_SCALAR Node is a scalar .TP .B FYNT_SEQUENCE Node is a sequence .TP .B FYNT_MAPPING Node is a mapping .UNINDENT .SS Description .sp Each node may be one of the following types .SS enum fy_node_style .INDENT 0.0 .TP .B enum fy_node_style Node style .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_node_style { FYNS_ANY, FYNS_FLOW, FYNS_BLOCK, FYNS_PLAIN, FYNS_SINGLE_QUOTED, FYNS_DOUBLE_QUOTED, FYNS_LITERAL, FYNS_FOLDED, FYNS_ALIAS }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYNS_ANY No hint, let the emitter decide .TP .B FYNS_FLOW Prefer flow style (for sequence/mappings) .TP .B FYNS_BLOCK Prefer block style (for sequence/mappings) .TP .B FYNS_PLAIN Plain style preferred .TP .B FYNS_SINGLE_QUOTED Single quoted style preferred .TP .B FYNS_DOUBLE_QUOTED Double quoted style preferred .TP .B FYNS_LITERAL Literal style preferred (valid in block context) .TP .B FYNS_FOLDED Folded style preferred (valid in block context) .TP .B FYNS_ALIAS It’s an alias .UNINDENT .SS Description .sp A node may contain a hint of how it should be rendered, encoded as a style. .SS enum fy_node_walk_flags .INDENT 0.0 .TP .B enum fy_node_walk_flags Node walk flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYNWF_DONT_FOLLOW Don’t follow aliases during pathwalk .TP .B FYNWF_FOLLOW Follow aliases during pathwalk .TP .B FYNWF_PTR_YAML YAML pointer path walks .TP .B FYNWF_PTR_JSON JSON pointer path walks .TP .B FYNWF_PTR_RELJSON Relative JSON pointer path walks .TP .B FYNWF_PTR_YPATH YPATH pointer path walks .TP .B FYNWF_URI_ENCODED The path is URI encoded .TP .B FYNWF_MAXDEPTH_DEFAULT Max follow depth is automatically determined .TP .B FYNWF_MARKER_DEFAULT Default marker to use when scanning .TP .B FYNWF_PTR_DEFAULT Default path type .UNINDENT .SS fy_node_style_from_scalar_style .INDENT 0.0 .TP .B enum \fI\%fy_node_style\fP fy_node_style_from_scalar_style(enum \fI\%fy_scalar_style\fP sstyle) Convert from scalar to node style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsstyle\fP (enum \fI\%fy_scalar_style\fP) – The input scalar style .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convert a scalar style to a node style. .SS Return .sp The matching node style .SS typedef fy_node_mapping_sort_fn .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfynp_a\fP (const struct fy_node_pair*) – The first node_pair used in the comparison .IP \(bu 2 \fBfynp_b\fP (const struct fy_node_pair*) – The second node_pair used in the comparison .IP \(bu 2 \fBarg\fP (void*) – The opaque user provided pointer to the sort operation .UNINDENT .UNINDENT .UNINDENT .SS Return .sp <0 if \fBfynp_a\fP is less than \fBfynp_b\fP 0 if \fBfynp_a\fP is equal to fynp_b >0 if \fBfynp_a\fP is greater than \fBfynp_b\fP .SS typedef fy_node_scalar_compare_fn .INDENT 0.0 .TP .B int fy_node_scalar_compare_fn(struct fy_node *fyn_a, struct fy_node *fyn_b, void *arg) Node compare method function for scalars .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_a\fP (struct fy_node*) – The first scalar node used in the comparison .IP \(bu 2 \fBfyn_b\fP (struct fy_node*) – The second scalar node used in the comparison .IP \(bu 2 \fBarg\fP (void*) – The opaque user provided pointer to the compare operation .UNINDENT .UNINDENT .UNINDENT .SS Return .sp <0 if \fBfyn_a\fP is less than \fBfyn_b\fP 0 if \fBfyn_a\fP is equal to fyn_b >0 if \fBfyn_a\fP is greater than \fBfyn_b\fP .SS fy_node_compare .INDENT 0.0 .TP .B bool fy_node_compare(struct fy_node *fyn1, struct fy_node *fyn2) Compare two nodes for equality .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn1\fP (struct fy_node*) – The first node to use in the comparison .IP \(bu 2 \fBfyn2\fP (struct fy_node*) – The second node to use in the comparison .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp true if the nodes contain the same content, false otherwise .SS fy_node_compare_user .INDENT 0.0 .TP .B bool fy_node_compare_user(struct fy_node *fyn1, struct fy_node *fyn2, \fI\%fy_node_mapping_sort_fn\fP sort_fn, void *sort_fn_arg, \fI\%fy_node_scalar_compare_fn\fP cmp_fn, void *cmp_fn_arg) Compare two nodes for equality using user supplied sort and scalar compare methods .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn1\fP (struct fy_node*) – The first node to use in the comparison .IP \(bu 2 \fBfyn2\fP (struct fy_node*) – The second node to use in the comparison .IP \(bu 2 \fBsort_fn\fP (\fI\%fy_node_mapping_sort_fn\fP) – The method to use for sorting maps, or NULL for the default .IP \(bu 2 \fBsort_fn_arg\fP (void*) – The extra user supplied argument to the \fBsort_fn\fP .IP \(bu 2 \fBcmp_fn\fP (\fI\%fy_node_scalar_compare_fn\fP) – The method to use for comparing scalars, or NULL for the default .IP \(bu 2 \fBcmp_fn_arg\fP (void*) – The extra user supplied argument to the \fBcmp_fn\fP .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp true if the nodes contain the same content, false otherwise .SS fy_node_compare_string .INDENT 0.0 .TP .B bool fy_node_compare_string(struct fy_node *fyn, const char *str, size_t len) Compare a node for equality with a YAML string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to use in the comparison .IP \(bu 2 \fBstr\fP (const char*) – The YAML string to compare against .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Compare a node for equality with a YAML string. The comparison is performed using \fI\%fy_node_compare()\fP with the first node supplied as an argument and the second being generated by calling fy_document_build_from_string with the YAML string. .SS Return .sp true if the node and the string are equal. .SS fy_node_compare_token .INDENT 0.0 .TP .B bool fy_node_compare_token(struct fy_node *fyn, struct fy_token *fyt) Compare a node for equality against a token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to use in the comparison .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The scalar token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Compare a node for equality with a token. Both the node and the tokens must be a scalars. .SS Return .sp true if the node and the token are equal. .SS fy_node_compare_text .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to use in the comparison .IP \(bu 2 \fBtext\fP (const char*) – The raw C text to compare against .IP \(bu 2 \fBlen\fP (size_t) – The length of the text (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Compare a node for equality with a raw C string. The node must be a scalar. .SS Return .sp true if the node and the text are equal. .SS fy_document_create .INDENT 0.0 .TP .B struct fy_document *fy_document_create(const struct \fI\%fy_parse_cfg\fP *cfg) Create an empty document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an empty document using the provided parser configuration. If NULL use the default parse configuration. .SS Return .sp The created empty document, or NULL on error. .SS fy_document_destroy .INDENT 0.0 .TP .B void fy_document_destroy(struct fy_document *fyd) Destroy a document previously created via \fI\%fy_document_create()\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy a document (along with all children documents) .SS fy_document_get_cfg .INDENT 0.0 .TP .B const struct \fI\%fy_parse_cfg\fP *fy_document_get_cfg(struct fy_document *fyd) Get the configuration of a document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The configuration of the document .SS fy_document_get_diag .INDENT 0.0 .TP .B struct fy_diag *fy_document_get_diag(struct fy_document *fyd) Get the diagnostic object of a document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to get the diagnostic object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return a pointer to the diagnostic object of a document object. Note that the returned diag object has a reference taken so you should \fI\%fy_diag_unref()\fP it when you’re done with it. .SS Return .sp A pointer to a ref’ed diagnostic object or NULL in case of an error. .SS fy_document_set_diag .INDENT 0.0 .TP .B int fy_document_set_diag(struct fy_document *fyd, struct fy_diag *diag) Set the diagnostic object of a document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to replace the diagnostic object .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The document’s new diagnostic object, NULL for default .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 0 if everything OK, \-1 otherwise .SS fy_document_set_parent .INDENT 0.0 .TP .B int fy_document_set_parent(struct fy_document *fyd, struct fy_document *fyd_child) Make a document a child of another .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The parent document .IP \(bu 2 \fBfyd_child\fP (struct fy_document*) – The child document .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Set the parent of \fBfyd_child\fP document to be \fBfyd\fP .SS Return .sp 0 if all OK, \-1 on error. .SS fy_document_build_from_string .INDENT 0.0 .TP .B struct fy_document *fy_document_build_from_string(const struct \fI\%fy_parse_cfg\fP *cfg, const char *str, size_t len) Create a document using the provided YAML source. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .IP \(bu 2 \fBstr\fP (const char*) – The YAML source to use. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a document parsing the provided string as a YAML source. .SS Return .sp The created document, or NULL on error. .SS fy_document_build_from_malloc_string .INDENT 0.0 .TP .B struct fy_document *fy_document_build_from_malloc_string(const struct \fI\%fy_parse_cfg\fP *cfg, char *str, size_t len) Create a document using the provided YAML source which was malloced. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .IP \(bu 2 \fBstr\fP (char*) – The YAML source to use. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The created document, or NULL on error. .SS fy_document_build_from_file .INDENT 0.0 .TP .B struct fy_document *fy_document_build_from_file(const struct \fI\%fy_parse_cfg\fP *cfg, const char *file) Create a document parsing the given file .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .IP \(bu 2 \fBfile\fP (const char*) – The name of the file to parse .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a document parsing the provided file as a YAML source. .SS Return .sp The created document, or NULL on error. .SS fy_document_build_from_fp .INDENT 0.0 .TP .B struct fy_document *fy_document_build_from_fp(const struct \fI\%fy_parse_cfg\fP *cfg, FILE *fp) Create a document parsing the given file pointer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .IP \(bu 2 \fBfp\fP (FILE*) – The file pointer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a document parsing the provided file pointer as a YAML source. .SS Return .sp The created document, or NULL on error. .SS fy_document_vbuildf .INDENT 0.0 .TP .B struct fy_document *fy_document_vbuildf(const struct \fI\%fy_parse_cfg\fP *cfg, const char *fmt, va_list ap) Create a document using the provided YAML via vprintf formatting .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .IP \(bu 2 \fBfmt\fP (const char*) – The format string creating the YAML source to use. .IP \(bu 2 \fBap\fP (va_list) – The va_list argument pointer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a document parsing the provided string as a YAML source. The string is created by applying vprintf formatting. .SS Return .sp The created document, or NULL on error. .SS fy_document_buildf .INDENT 0.0 .TP .B struct fy_document *fy_document_buildf(const struct \fI\%fy_parse_cfg\fP *cfg, const char *fmt, \&...) Create a document using the provided YAML source via printf formatting .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .IP \(bu 2 \fBfmt\fP (const char*) – The format string creating the YAML source to use. .IP \(bu 2 \fBellipsis\fP (ellipsis) – The printf arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a document parsing the provided string as a YAML source. The string is created by applying printf formatting. .SS Return .sp The created document, or NULL on error. .SS fy_flow_document_build_from_string .INDENT 0.0 .TP .B struct fy_document *fy_flow_document_build_from_string(const struct \fI\%fy_parse_cfg\fP *cfg, const char *str, size_t len, size_t *consumed) Create a document using the provided YAML source. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .IP \(bu 2 \fBstr\fP (const char*) – The YAML source to use. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .IP \(bu 2 \fBconsumed\fP (size_t*) – A pointer to the consumed amount .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a document parsing the provided string as a YAML source. .sp The document is a flow document, i.e. does not contain any block content and is usually laid out in a single line. .SS Example of flow documents .sp plain\-scalar “double\-quoted\-scalar” ‘single\-quoted\-scalar’ { foo: bar } [ 0, 1, 2 ] .sp A flow document is important because parsing stops at the end of it, and so can be placed in other non\-yaml content. .SS Return .sp The created document, or NULL on error. .SS fy_block_document_build_from_string .INDENT 0.0 .TP .B struct fy_document *fy_block_document_build_from_string(const struct \fI\%fy_parse_cfg\fP *cfg, const char *str, size_t len, size_t *consumed) Create a document using the provided YAML source. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_parse_cfg\fP*) – The parse configuration to use or NULL for the default. .IP \(bu 2 \fBstr\fP (const char*) – The YAML source to use. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .IP \(bu 2 \fBconsumed\fP (size_t*) – A pointer to the consumed amount .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a document parsing the provided string as a YAML source. .sp The document is a block document, and it terminates when indentation appears to do so. .sp Example of block documents: .INDENT 0.0 .INDENT 3.5 .sp .EX this\-is\-yaml foo: bar <\- starts here baz: [1, 2] this\-is\-yaml\-no\-more .EE .UNINDENT .UNINDENT .SS Return .sp The created document, or NULL on error. .SS fy_document_root .INDENT 0.0 .TP .B struct fy_node *fy_document_root(struct fy_document *fyd) Return the root node of the document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns the root of the document. If the document is empty NULL will be returned instead. .SS Return .sp The root of the document, or NULL if the document is empty. .SS fy_document_set_root .INDENT 0.0 .TP .B int fy_document_set_root(struct fy_document *fyd, struct fy_node *fyn) Set the root of the document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The new root of the document. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Set the root of a document. If the document was not empty the old root will be freed. If \fBfyn\fP is NULL then the document is set to empty. .SS Return .sp 0 on success, \-1 on error .SS fy_node_get_type .INDENT 0.0 .TP .B enum \fI\%fy_node_type\fP fy_node_get_type(struct fy_node *fyn) Get the node type .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the node type. It is one of FYNT_SCALAR, FYNT_SEQUENCE or FYNT_MAPPING. A NULL node argument is a FYNT_SCALAR. .SS Return .sp The node type .SS fy_node_get_style .INDENT 0.0 .TP .B enum \fI\%fy_node_style\fP fy_node_get_style(struct fy_node *fyn) Get the node style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the node rendering style. If the node is NULL then the style is FYNS_PLAIN. .SS Return .sp The node style .SS fy_node_set_style .INDENT 0.0 .TP .B enum \fI\%fy_node_style\fP fy_node_set_style(struct fy_node *fyn, enum \fI\%fy_node_style\fP style) Set the node style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBstyle\fP (enum \fI\%fy_node_style\fP) – The requested node rendering style .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Try to set the node rendering style of a node. If the style of node is illegal (for example you can’t set an arbitrary scalar that contains zeroes to plain) then the actual style that was set will be returned. .SS Return .sp The final node style .SS fy_node_get_start_token .INDENT 0.0 .TP .B struct fy_token *fy_node_get_start_token(struct fy_node *fyn) Get the node start token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the node start token. .sp For scalars, this is the same as the end token. .SS Return .sp The node start token .SS fy_node_get_end_token .INDENT 0.0 .TP .B struct fy_token *fy_node_get_end_token(struct fy_node *fyn) Get the node end token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the node end token. .sp For scalars, this is the same as the start token. .SS Return .sp The node end token .SS fy_node_is_scalar .INDENT 0.0 .TP .B bool fy_node_is_scalar(struct fy_node *fyn) Check whether the node is a scalar .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convenience method for checking whether a node is a scalar. .SS Return .sp true if the node is a scalar, false otherwise .SS fy_node_is_sequence .INDENT 0.0 .TP .B bool fy_node_is_sequence(struct fy_node *fyn) Check whether the node is a sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convenience method for checking whether a node is a sequence. .SS Return .sp true if the node is a sequence, false otherwise .SS fy_node_is_mapping .INDENT 0.0 .TP .B bool fy_node_is_mapping(struct fy_node *fyn) Check whether the node is a mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convenience method for checking whether a node is a mapping. .SS Return .sp true if the node is a mapping, false otherwise .SS fy_node_is_alias .INDENT 0.0 .TP .B bool fy_node_is_alias(struct fy_node *fyn) Check whether the node is an alias .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convenience method for checking whether a node is an alias. .SS Return .sp true if the node is an alias, false otherwise .SS fy_node_is_null .INDENT 0.0 .TP .B bool fy_node_is_null(struct fy_node *fyn) Check whether the node is a NULL .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convenience method for checking whether a node is a NULL scalar.. Note that a NULL node argument returns true… .SS Return .sp true if the node is a NULL scalar, false otherwise .SS fy_node_is_attached .INDENT 0.0 .TP .B bool fy_node_is_attached(struct fy_node *fyn) Check whether the node is attached .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp true if the node is attached, false otherwise .SS fy_node_get_tag_token .INDENT 0.0 .TP .B struct fy_token *fy_node_get_tag_token(struct fy_node *fyn) Gets the tag token of a node (if it exists) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node which has the tag token to be returned .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Gets the tag token of a node, if it exists .SS Return .sp The tag token of the given node, or NULL if the tag does not exist. .SS fy_node_get_scalar_token .INDENT 0.0 .TP .B struct fy_token *fy_node_get_scalar_token(struct fy_node *fyn) Gets the scalar token of a node (if it exists) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node which has the scalar token to be returned .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The scalar token of the given node, or NULL if the node is not a scalar. .SS fy_node_resolve_alias .INDENT 0.0 .TP .B struct fy_node *fy_node_resolve_alias(struct fy_node *fyn) Resolve an alias node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The alias node to be resolved .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The resolved alias node, or NULL if either fyn is not an alias, or resolution fails due to a graph cycle. .SS fy_node_dereference .INDENT 0.0 .TP .B struct fy_node *fy_node_dereference(struct fy_node *fyn) Dereference a single alias node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The alias node to be dereferenced .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The dereferenced alias node, or NULL if either fyn is not an alias, or resolution fails due to a graph cycle. .SS fy_node_free .INDENT 0.0 .TP .B int fy_node_free(struct fy_node *fyn) Free a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to free .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp This method will return an error if the node is attached, or if not NULL it is not a member of a document. .SS Return .sp 0 on success, \-1 on error. .SS fy_node_build_from_string .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBstr\fP (const char*) – The YAML source to use. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a node parsing the provided string as a YAML source. The node created will be associated with the provided document. .SS Return .sp The created node, or NULL on error. .SS fy_node_build_from_malloc_string .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBstr\fP (char*) – The YAML source to use. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The created node, or NULL on error. .SS fy_node_build_from_file .INDENT 0.0 .TP .B struct fy_node *fy_node_build_from_file(struct fy_document *fyd, const char *file) Create a node using the provided YAML file. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfile\fP (const char*) – The name of the file to parse .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a node parsing the provided file as a YAML source. The node created will be associated with the provided document. .SS Return .sp The created node, or NULL on error. .SS fy_node_build_from_fp .INDENT 0.0 .TP .B struct fy_node *fy_node_build_from_fp(struct fy_document *fyd, FILE *fp) Create a node using the provided file pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfp\fP (FILE*) – The file pointer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a node parsing the provided file pointer as a YAML source. The node created will be associated with the provided document. .SS Return .sp The created node, or NULL on error. .SS fy_node_vbuildf .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfmt\fP (const char*) – The format string creating the YAML source to use. .IP \(bu 2 \fBap\fP (va_list) – The va_list argument pointer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a node parsing the resulting string as a YAML source. The string is created by applying vprintf formatting. .SS Return .sp The created node, or NULL on error. .SS fy_node_buildf .INDENT 0.0 .TP .B struct fy_node *fy_node_buildf(struct fy_document *fyd, const char *fmt, \&...) Create a node using the provided YAML source via printf formatting .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfmt\fP (const char*) – The format string creating the YAML source to use. .IP \(bu 2 \fBellipsis\fP (ellipsis) – The printf arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a node parsing the resulting string as a YAML source. The string is created by applying printf formatting. .SS Return .sp The created node, or NULL on error. .SS fy_node_by_path .INDENT 0.0 .TP .B struct fy_node *fy_node_by_path(struct fy_node *fyn, const char *path, size_t len, enum \fI\%fy_node_walk_flags\fP flags) Retrieve a node using the provided path spec. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to use as start of the traversal operation .IP \(bu 2 \fBpath\fP (const char*) – The path spec to use in the traversal operation .IP \(bu 2 \fBlen\fP (size_t) – The length of the path (or \-1 if ‘0’ terminated) .IP \(bu 2 \fBflags\fP (enum \fI\%fy_node_walk_flags\fP) – The extra path walk flags .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will retrieve a node relative to the given node using the provided path spec. .sp 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. .sp A few examples will make this clear: .INDENT 0.0 .INDENT 3.5 .sp .EX fyn = { foo: bar } \- fy_node_by_path(fyn, \(dq/foo\(dq) \-> bar fyn = [ foo, bar ] \- fy_node_by_path(fyn, \(dq1\(dq) \-> bar fyn = { { foo: bar }: baz } \- fy_node_by_path(fyn, \(dq{foo: bar}\(dq) \-> baz fyn = [ foo, { bar: baz } } \- fy_node_by_path(fyn, \(dq1/bar\(dq) \-> baz .EE .UNINDENT .UNINDENT .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX fyn = { foo/bar: baz } \- fy_node_by_path(fyn, \(dq\(aqfoo/bar\(aq\(dq) \-> baz .EE .UNINDENT .UNINDENT .SS Return .sp The retrieved node, or NULL if not possible to be found. .SS fy_node_get_path .INDENT 0.0 .TP .B char *fy_node_get_path(struct fy_node *fyn) Get the path of this node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The node’s address, or NULL if fyn is the root. .SS fy_node_get_parent .INDENT 0.0 .TP .B struct fy_node *fy_node_get_parent(struct fy_node *fyn) Get the parent node of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The node’s parent, or NULL if fyn is the root, or the root of a key mapping. .SS fy_node_get_document_parent .INDENT 0.0 .TP .B struct fy_node *fy_node_get_document_parent(struct fy_node *fyn) Get the document parent node of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The node’s document parent, or NULL if fyn is the root .SS fy_node_get_parent_address .INDENT 0.0 .TP .B char *fy_node_get_parent_address(struct fy_node *fyn) Get the path address of this node’s parent .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the given node’s parent path address The address is dynamically allocated and should be freed when you’re done with it. .SS Return .sp The parent’s address, or NULL if fyn is the root. .SS fy_node_get_path_relative_to .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_parent\fP (struct fy_node*) – The node parent/grandparent… .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The relative address from the parent to the node .SS fy_node_get_short_path .INDENT 0.0 .TP .B char *fy_node_get_short_path(struct fy_node *fyn) Get a path address of a node in the shortest path possible .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .EX \-\-\- &foo foo: &bar bar baz \- The short path of /foo is \e*foo \- The short path of /foo/bar is \e*bar \- The short path of /baz is \e*foo/baz .EE .UNINDENT .UNINDENT .sp The address is dynamically allocated and should be freed when you’re done with it. .SS Return .sp The shortest path describing the node .SS fy_node_get_reference .INDENT 0.0 .TP .B char *fy_node_get_reference(struct fy_node *fyn) Get a textual reference to a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp The address is dynamically allocated and should be freed when you’re done with it. .SS Return .sp The node’s text reference. .SS fy_node_create_reference .INDENT 0.0 .TP .B struct fy_node *fy_node_create_reference(struct fy_node *fyn) Create an alias reference node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp An alias node referencing the argument node .SS fy_node_get_relative_reference .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_base\fP (struct fy_node*) – The base node .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp The address is dynamically allocated and should be freed when you’re done with it. .SS Return .sp The node’s text reference. .SS fy_node_create_relative_reference .INDENT 0.0 .TP .B struct fy_node *fy_node_create_relative_reference(struct fy_node *fyn_base, struct fy_node *fyn) Create an alias reference node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_base\fP (struct fy_node*) – The base node .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp An alias node referencing the argument node relative to the base .SS fy_node_create_scalar .INDENT 0.0 .TP .B struct fy_node *fy_node_create_scalar(struct fy_document *fyd, const char *data, size_t size) Create a scalar node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document which the resulting node will be associated with .IP \(bu 2 \fBdata\fP (const char*) – Pointer to the data area .IP \(bu 2 \fBsize\fP (size_t) – Size of the data area, or (size_t)\-1 for ‘0’ terminated data. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp Note that the data are not copied, merely a reference is taken, so it must be available while the node is in use. .SS Return .sp The created node, or NULL on error. .SS fy_node_create_scalar_copy .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document which the resulting node will be associated with .IP \(bu 2 \fBdata\fP (const char*) – Pointer to the data area .IP \(bu 2 \fBsize\fP (size_t) – Size of the data area, or (size_t)\-1 for ‘0’ terminated data. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp A copy of the data will be made, so it is safe to free the data after the call. .SS Return .sp The created node, or NULL on error. .SS fy_node_create_vscalarf .INDENT 0.0 .TP .B struct fy_node *fy_node_create_vscalarf(struct fy_document *fyd, const char *fmt, va_list ap) vprintf interface for creating scalars .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document which the resulting node will be associated with .IP \(bu 2 \fBfmt\fP (const char*) – The printf based format string .IP \(bu 2 \fBap\fP (va_list) – The va_list containing the arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The created node, or NULL on error. .SS fy_node_create_scalarf .INDENT 0.0 .TP .B struct fy_node *fy_node_create_scalarf(struct fy_document *fyd, const char *fmt, \&...) printf interface for creating scalars .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document which the resulting node will be associated with .IP \(bu 2 \fBfmt\fP (const char*) – The printf based format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The created node, or NULL on error. .SS fy_node_create_sequence .INDENT 0.0 .TP .B struct fy_node *fy_node_create_sequence(struct fy_document *fyd) Create an empty sequence node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document which the resulting node will be associated with .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an empty sequence node associated with the given document. .SS Return .sp The created node, or NULL on error. .SS fy_node_create_mapping .INDENT 0.0 .TP .B struct fy_node *fy_node_create_mapping(struct fy_document *fyd) Create an empty mapping node. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document which the resulting node will be associated with .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an empty mapping node associated with the given document. .SS Return .sp The created node, or NULL on error. .SS fy_node_set_tag .INDENT 0.0 .TP .B int fy_node_set_tag(struct fy_node *fyn, const char *data, size_t len) Set the tag of node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to set it’s tag. .IP \(bu 2 \fBdata\fP (const char*) – Pointer to the tag data. .IP \(bu 2 \fBlen\fP (size_t) – Size of the tag data, or (size_t)\-1 for ‘0’ terminated. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Manually set the tag of a node. The tag must be a valid one for the document the node belongs to. .sp Note that the data are not copied, merely a reference is taken, so it must be available while the node is in use. .sp If the node already contains a tag it will be overwriten. .SS Return .sp 0 on success, \-1 on error. .SS fy_node_remove_tag .INDENT 0.0 .TP .B int fy_node_remove_tag(struct fy_node *fyn) Remove the tag of node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to remove it’s tag. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Remove the tag of a node. .SS Return .sp 0 on success, \-1 on error. .SS fy_node_get_tag .INDENT 0.0 .TP .B const char *fy_node_get_tag(struct fy_node *fyn, size_t *lenp) Get the tag of the node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return a pointer to the text of a tag along with the length of it. Note that this text is \fInot\fP NULL terminated. .SS Return .sp A pointer to the tag of the node, while \fBlenp\fP will be assigned the length of said tag. A NULL will be returned in case of an error. .SS fy_node_get_tag0 .INDENT 0.0 .TP .B const char *fy_node_get_tag0(struct fy_node *fyn) Get the tag of the node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return a pointer to the text of a tag, which will be NULL terminated. .SS Return .sp A pointer to the null terminated tag of the node. A NULL will be returned in case of an error. .SS fy_node_get_tag_length .INDENT 0.0 .TP .B size_t fy_node_get_tag_length(struct fy_node *fyn) Get the length of the tag of the node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The tagged node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the size of the tag of the node. If the node is not tagged it will return 0. .SS Return .sp The size of the tag, or 0 if node is not tagged. .SS fy_node_get_scalar .INDENT 0.0 .TP .B const char *fy_node_get_scalar(struct fy_node *fyn, size_t *lenp) Get the scalar content of the node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The scalar node .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fInot\fP NULL terminated. .SS Return .sp A pointer to the scalar content of the node, while \fBlenp\fP 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. .SS fy_node_get_scalar0 .INDENT 0.0 .TP .B const char *fy_node_get_scalar0(struct fy_node *fyn) Get the scalar content of the node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The scalar node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_node_get_scalar()\fP .SS Return .sp A pointer to the scalar content of the node or NULL in returned in case of an error. .SS fy_node_get_scalar_length .INDENT 0.0 .TP .B size_t fy_node_get_scalar_length(struct fy_node *fyn) Get the length of the scalar content .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The scalar node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the size of the scalar content of the node. If the node is not a scalar it will return 0. .SS Return .sp The size of the scalar content, or 0 if node is not scalar. .SS fy_node_get_scalar_utf8_length .INDENT 0.0 .TP .B size_t fy_node_get_scalar_utf8_length(struct fy_node *fyn) Get the length of the scalar content in utf8 characters .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The scalar node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The size of the scalar content in utf8 characters, or 0 if node is not scalar. .SS fy_node_sequence_iterate .INDENT 0.0 .TP .B struct fy_node *fy_node_sequence_iterate(struct fy_node *fyn, void **prevp) Iterate over a sequence node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The sequence node .IP \(bu 2 \fBprevp\fP (void**) – The previous sequence iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method iterates over all the item nodes in the sequence node. The start of the iteration is signalled by a NULL in *prevp. .SS Return .sp The next node in sequence or NULL at the end of the sequence. .SS fy_node_sequence_reverse_iterate .INDENT 0.0 .TP .B struct fy_node *fy_node_sequence_reverse_iterate(struct fy_node *fyn, void **prevp) Iterate over a sequence node in reverse .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The sequence node .IP \(bu 2 \fBprevp\fP (void**) – The previous sequence iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The next node in reverse sequence or NULL at the end of the sequence. .SS fy_node_sequence_item_count .INDENT 0.0 .TP .B int fy_node_sequence_item_count(struct fy_node *fyn) Return the item count of the sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The sequence node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Get the item count of the sequence. .SS Return .sp The count of items in the sequence or \-1 in case of an error. .SS fy_node_sequence_is_empty .INDENT 0.0 .TP .B bool fy_node_sequence_is_empty(struct fy_node *fyn) Check whether the sequence is empty .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The sequence node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check whether the sequence contains items. .SS Return .sp true if the node is a sequence containing items, false otherwise .SS fy_node_sequence_get_by_index .INDENT 0.0 .TP .B struct fy_node *fy_node_sequence_get_by_index(struct fy_node *fyn, int index) Return a sequence item by index .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The sequence node .IP \(bu 2 \fBindex\fP (int) – The index of the node to retrieve. \- >= 0 counting from the start \- < 0 counting from the end .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The node at the specified index or NULL if no such item exist. .SS fy_node_sequence_append .INDENT 0.0 .TP .B int fy_node_sequence_append(struct fy_node *fyn_seq, struct fy_node *fyn) Append a node item to a sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_seq\fP (struct fy_node*) – The sequence node .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node item to append .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Append a node item to a sequence. .SS Return .sp 0 on success, \-1 on error .SS fy_node_sequence_prepend .INDENT 0.0 .TP .B int fy_node_sequence_prepend(struct fy_node *fyn_seq, struct fy_node *fyn) Append a node item to a sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_seq\fP (struct fy_node*) – The sequence node .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node item to prepend .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Prepend a node item to a sequence. .SS Return .sp 0 on success, \-1 on error .SS fy_node_sequence_insert_before .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_seq\fP (struct fy_node*) – The sequence node .IP \(bu 2 \fBfyn_mark\fP (struct fy_node*) – The node item which the node will be inserted before. .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node item to insert in the sequence. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Insert a node item before another in the sequence. .SS Return .sp 0 on success, \-1 on error .SS fy_node_sequence_insert_after .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_seq\fP (struct fy_node*) – The sequence node .IP \(bu 2 \fBfyn_mark\fP (struct fy_node*) – The node item which the node will be inserted after. .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node item to insert in the sequence. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Insert a node item after another in the sequence. .SS Return .sp 0 on success, \-1 on error .SS fy_node_sequence_remove .INDENT 0.0 .TP .B struct fy_node *fy_node_sequence_remove(struct fy_node *fyn_seq, struct fy_node *fyn) Remove an item from a sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_seq\fP (struct fy_node*) – The sequence node .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node item to remove from the sequence. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Remove a node item from a sequence and return it. .SS Return .sp The removed node item fyn, or NULL in case of an error. .SS typedef fy_node_sequence_sort_fn .INDENT 0.0 .TP .B int fy_node_sequence_sort_fn(struct fy_node *fyn_a, struct fy_node *fyn_b, void *arg) Sequence sorting method function .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_a\fP (struct fy_node*) – The first node used in the comparison .IP \(bu 2 \fBfyn_b\fP (struct fy_node*) – The second node used in the comparison .IP \(bu 2 \fBarg\fP (void*) – The opaque user provided pointer to the sort operation .UNINDENT .UNINDENT .UNINDENT .SS Return .sp <0 if \fBfyn_a\fP is less than \fBfyn_b\fP 0 if \fBfyn_a\fP is equal to fyn_b >0 if \fBfyn_a\fP is greater than \fBfyn_b\fP .SS fy_node_sequence_sort .INDENT 0.0 .TP .B int fy_node_sequence_sort(struct fy_node *fyn_seq, \fI\%fy_node_sequence_sort_fn\fP cmp, void *arg) Sort a sequence’s items .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_seq\fP (struct fy_node*) – The sequence node to sort .IP \(bu 2 \fBcmp\fP (\fI\%fy_node_sequence_sort_fn\fP) – The comparison method .IP \(bu 2 \fBarg\fP (void*) – An opaque user pointer for the comparison method .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Sort the items of a sequence node using the given comparison method. .SS Return .sp 0 on success, \-1 on error .SS fy_node_mapping_iterate .INDENT 0.0 .TP .B struct fy_node_pair *fy_node_mapping_iterate(struct fy_node *fyn, void **prevp) Iterate over a mapping node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBprevp\fP (void**) – The previous sequence iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method iterates over all the node pairs in the mapping node. The start of the iteration is signalled by a NULL in *prevp. .sp Note that while a mapping is an unordered collection of key/values the order of which they are created is important for presentation purposes. .SS Return .sp The next node pair in the mapping or NULL at the end of the mapping. .SS fy_node_mapping_reverse_iterate .INDENT 0.0 .TP .B struct fy_node_pair *fy_node_mapping_reverse_iterate(struct fy_node *fyn, void **prevp) Iterate over a mapping node in reverse .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBprevp\fP (void**) – The previous sequence iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp Note that while a mapping is an unordered collection of key/values the order of which they are created is important for presentation purposes. .SS Return .sp The next node pair in reverse sequence in the mapping or NULL at the end of the mapping. .SS fy_node_mapping_item_count .INDENT 0.0 .TP .B int fy_node_mapping_item_count(struct fy_node *fyn) Return the node pair count of the mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Get the count of the node pairs in the mapping. .SS Return .sp The count of node pairs in the mapping or \-1 in case of an error. .SS fy_node_mapping_is_empty .INDENT 0.0 .TP .B bool fy_node_mapping_is_empty(struct fy_node *fyn) Check whether the mapping is empty .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check whether the mapping contains any node pairs. .SS Return .sp true if the node is a mapping containing node pairs, false otherwise .SS fy_node_mapping_get_by_index .INDENT 0.0 .TP .B struct fy_node_pair *fy_node_mapping_get_by_index(struct fy_node *fyn, int index) Return a node pair by index .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBindex\fP (int) – The index of the node pair to retrieve. \- >= 0 counting from the start \- < 0 counting from the end .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The node pair at the specified index or NULL if no such item exist. .SS fy_node_mapping_lookup_pair_by_string .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBkey\fP (const char*) – The YAML source to use as key .IP \(bu 2 \fBlen\fP (size_t) – The length of the key (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the node pair that contains the same key from the YAML node created from the \fBkey\fP argument. The comparison of the node is using \fI\%fy_node_compare()\fP .SS Return .sp The value matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_by_string .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBkey\fP (const char*) – The YAML source to use as key .IP \(bu 2 \fBlen\fP (size_t) – The length of the key (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the value of node pair that contains the same key from the YAML node created from the \fBkey\fP argument. The comparison of the node is using \fI\%fy_node_compare()\fP .SS Return .sp The value matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_value_by_string .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBkey\fP (const char*) – The YAML source to use as key .IP \(bu 2 \fBlen\fP (size_t) – The length of the key (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the value of node pair that contains the same key from the YAML node created from the \fBkey\fP argument. The comparison of the node is using \fI\%fy_node_compare()\fP .sp It is synonymous with \fI\%fy_node_mapping_lookup_by_string()\fP\&. .SS Return .sp The value matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_key_by_string .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBkey\fP (const char*) – The YAML source to use as key .IP \(bu 2 \fBlen\fP (size_t) – The length of the key (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the key of node pair that contains the same key from the YAML node created from the \fBkey\fP argument. The comparison of the node is using \fI\%fy_node_compare()\fP .SS Return .sp The key matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_pair_by_simple_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBkey\fP (const char*) – The string to use as key .IP \(bu 2 \fBlen\fP (size_t) – The length of the key (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the node pair that contains the same key from the YAML node created from the \fBkey\fP argument. The comparison of the node is using by comparing the strings for identity. .SS Return .sp The node pair matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_value_by_simple_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBkey\fP (const char*) – The string to use as key .IP \(bu 2 \fBlen\fP (size_t) – The length of the key (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the value of node pair that contains the same key from the YAML node created from the \fBkey\fP argument. The comparison of the node is using by comparing the strings for identity. .SS Return .sp The value matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_pair_by_null_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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… .SS Return .sp The node pair with a NULL key, NULL otherwise .SS fy_node_mapping_lookup_value_by_null_key .INDENT 0.0 .TP .B struct fy_node *fy_node_mapping_lookup_value_by_null_key(struct fy_node *fyn) Lookup a node value with a NULL key. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the value of a node pair that has a NULL key. .SS Return .sp 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. .SS fy_node_mapping_lookup_scalar_by_simple_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .IP \(bu 2 \fBkey\fP (const char*) – The string to use as key .IP \(bu 2 \fBkeylen\fP (size_t) – The length of the key (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the scalar contents that contains the same key from the YAML node created from the \fBkey\fP argument. The comparison of the node is using by comparing the strings for identity. .SS Return .sp The scalar contents matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_scalar0_by_simple_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBkey\fP (const char*) – The string to use as key .IP \(bu 2 \fBkeylen\fP (size_t) – The length of the key (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the NUL terminated scalar contents that contains the same key from the YAML node created from the \fBkey\fP argument. The comparison of the node is using by comparing the strings for identity. .SS Return .sp The NUL terminated scalar contents matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_pair .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBfyn_key\fP (struct fy_node*) – The node to use as key .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the node pair that matches the provided \fBfyn_key\fP .SS Return .sp The node pair matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_value_by_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBfyn_key\fP (struct fy_node*) – The node to use as key .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the node pair that matches the provided \fBfyn_key\fP The key may be collection and a content match check is performed recursively in order to find the right key. .SS Return .sp The node value matching the given key, or NULL if not found. .SS fy_node_mapping_lookup_key_by_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBfyn_key\fP (struct fy_node*) – The node to use as key .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the node pair that matches the provided \fBfyn_key\fP The key may be collection and a content match check is performed recursively in order to find the right key. .SS Return .sp The node key matching the given key, or NULL if not found. .SS fy_node_mapping_get_pair_index .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBfynp\fP (const struct fy_node_pair*) – The node pair .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return the node pair index in the mapping of the given node pair argument. .SS Return .sp The index of the node pair in the mapping or \-1 in case of an error. .SS fy_node_pair_key .INDENT 0.0 .TP .B struct fy_node *fy_node_pair_key(struct fy_node_pair *fynp) Return the key of a node pair .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfynp\fP (struct fy_node_pair*) – The node pair .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The node pair key .SS fy_node_pair_value .INDENT 0.0 .TP .B struct fy_node *fy_node_pair_value(struct fy_node_pair *fynp) Return the value of a node pair .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfynp\fP (struct fy_node_pair*) – The node pair .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The node pair value .SS fy_node_pair_set_key .INDENT 0.0 .TP .B int fy_node_pair_set_key(struct fy_node_pair *fynp, struct fy_node *fyn) Sets the key of a node pair .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfynp\fP (struct fy_node_pair*) – The node pair .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The key node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will set the key part of the node pair. It will ovewrite any previous key. .sp Note that no checks for duplicate keys are going to be performed. .SS Return .sp 0 on success, \-1 on error .SS fy_node_pair_set_value .INDENT 0.0 .TP .B int fy_node_pair_set_value(struct fy_node_pair *fynp, struct fy_node *fyn) Sets the value of a node pair .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfynp\fP (struct fy_node_pair*) – The node pair .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The value node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will set the value part of the node pair. It will ovewrite any previous value. .SS Return .sp 0 on success, \-1 on error .SS fy_node_mapping_append .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_map\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBfyn_key\fP (struct fy_node*) – The node pair’s key .IP \(bu 2 \fBfyn_value\fP (struct fy_node*) – The node pair’s value .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Append a node pair to a mapping. .SS Return .sp 0 on success, \-1 on error .SS fy_node_mapping_prepend .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_map\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBfyn_key\fP (struct fy_node*) – The node pair’s key .IP \(bu 2 \fBfyn_value\fP (struct fy_node*) – The node pair’s value .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Prepend a node pair to a mapping. .SS Return .sp 0 on success, \-1 on error .SS fy_node_mapping_remove .INDENT 0.0 .TP .B int fy_node_mapping_remove(struct fy_node *fyn_map, struct fy_node_pair *fynp) Remove a node pair from a mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_map\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBfynp\fP (struct fy_node_pair*) – The node pair to remove .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Remove node pair from a mapping. .SS Return .sp 0 on success, \-1 on failure. .SS fy_node_mapping_sort .INDENT 0.0 .TP .B int fy_node_mapping_sort(struct fy_node *fyn_map, \fI\%fy_node_mapping_sort_fn\fP key_cmp, void *arg) Sort a single mapping’s keys .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_map\fP (struct fy_node*) – The mapping node to sort .IP \(bu 2 \fBkey_cmp\fP (\fI\%fy_node_mapping_sort_fn\fP) – The comparison method .IP \(bu 2 \fBarg\fP (void*) – An opaque user pointer for the comparison method .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Sort the keys of a single mapping node using the given comparison method (if NULL use the default one). Unlike \fI\%fy_node_sort()\fP, this does not recurse into child nodes. .SS Return .sp 0 on success, \-1 on error .SS fy_node_mapping_remove_by_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_map\fP (struct fy_node*) – The mapping node .IP \(bu 2 \fBfyn_key\fP (struct fy_node*) – The node pair’s key .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Remove node pair from a mapping using the supplied key. .SS Return .sp The value part of removed node pair, or NULL in case of an error. .SS fy_node_sort .INDENT 0.0 .TP .B int fy_node_sort(struct fy_node *fyn, \fI\%fy_node_mapping_sort_fn\fP key_cmp, void *arg) Recursively sort node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to sort .IP \(bu 2 \fBkey_cmp\fP (\fI\%fy_node_mapping_sort_fn\fP) – The comparison method .IP \(bu 2 \fBarg\fP (void*) – An opaque user pointer for the comparison method .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Recursively sort all mappings of the given node, using the given comparison method (if NULL use the default one). .SS Return .sp 0 on success, \-1 on error .SS fy_node_vscanf .INDENT 0.0 .TP .B int fy_node_vscanf(struct fy_node *fyn, const char *fmt, va_list ap) Retrieve data via vscanf .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to use as a pathspec root .IP \(bu 2 \fBfmt\fP (const char*) – The scanf based format string .IP \(bu 2 \fBap\fP (va_list) – The va_list containing the arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method easily retrieves data using a familiar vscanf interface. The format string is a regular scanf format string with the following format. .INDENT 0.0 .INDENT 3.5 “pathspec \fBopt\fP pathspec \fBopt\fP…” .UNINDENT .UNINDENT .sp Each pathspec is separated with space from the scanf option .SS For example .sp fyn = { foo: 3 } \-> fy_node_scanf(fyn, “/foo \fBd\fP“, \fBstruct var\fP) \-> var = 3 .SS Return .sp The number of scanned arguments, or \-1 on error. .SS fy_node_scanf .INDENT 0.0 .TP .B int fy_node_scanf(struct fy_node *fyn, const char *fmt, \&...) Retrieve data via scanf .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to use as a pathspec root .IP \(bu 2 \fBfmt\fP (const char*) – The scanf based format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method easily retrieves data using a familiar vscanf interface. The format string is a regular scanf format string with the following format. .INDENT 0.0 .INDENT 3.5 “pathspec \fBopt\fP pathspec \fBopt\fP…” .UNINDENT .UNINDENT .sp Each pathspec is separated with space from the scanf option .SS For example .sp fyn = { foo: 3 } \-> fy_node_scanf(fyn, “/foo \fBd\fP“, \fBstruct var\fP) \-> var = 3 .SS Return .sp The number of scanned arguments, or \-1 on error. .SS fy_document_vscanf .INDENT 0.0 .TP .B int fy_document_vscanf(struct fy_document *fyd, const char *fmt, va_list ap) Retrieve data via vscanf relative to document root .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfmt\fP (const char*) – The scanf based format string .IP \(bu 2 \fBap\fP (va_list) – The va_list containing the arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method easily retrieves data using a familiar vscanf interface. The format string is a regular scanf format string with the following format. .INDENT 0.0 .INDENT 3.5 “pathspec \fBopt\fP pathspec \fBopt\fP…” .UNINDENT .UNINDENT .sp Each pathspec is separated with space from the scanf option .SS For example .sp fyd = { foo: 3 } \-> fy_document_scanf(fyd, “/foo \fBd\fP“, \fBstruct var\fP) \-> var = 3 .SS Return .sp The number of scanned arguments, or \-1 on error. .SS fy_document_scanf .INDENT 0.0 .TP .B int fy_document_scanf(struct fy_document *fyd, const char *fmt, \&...) Retrieve data via scanf relative to document root .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfmt\fP (const char*) – The scanf based format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method easily retrieves data using a familiar vscanf interface. The format string is a regular scanf format string with the following format. .INDENT 0.0 .INDENT 3.5 “pathspec \fBopt\fP pathspec \fBopt\fP…” .UNINDENT .UNINDENT .sp Each pathspec is separated with space from the scanf option .SS For example .sp fyn = { foo: 3 } \-> fy_node_scanf(fyd, “/foo \fBd\fP“, \fBstruct var\fP) \-> var = 3 .SS Return .sp The number of scanned arguments, or \-1 on error. .SS fy_document_tag_directive_iterate .INDENT 0.0 .TP .B struct fy_token *fy_document_tag_directive_iterate(struct fy_document *fyd, void **prevp) Iterate over a document’s tag directives .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBprevp\fP (void**) – The previous state of the iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method iterates over all the documents tag directives. The start of the iteration is signalled by a NULL in *prevp. .SS Return .sp The next tag directive token in the document or NULL at the end of them. .SS fy_document_tag_directive_lookup .INDENT 0.0 .TP .B struct fy_token *fy_document_tag_directive_lookup(struct fy_document *fyd, const char *handle) Retreive a document’s tag directive .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBhandle\fP (const char*) – The handle to look for .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retreives the matching tag directive token of the document matching the handle. .SS Return .sp The tag directive token with the given handle or NULL if not found .SS fy_tag_directive_token_handle .INDENT 0.0 .TP .B const char *fy_tag_directive_token_handle(struct fy_token *fyt, size_t *lenp) Get a tag directive handle .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag directive token .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retreives the tag directives token handle value. Only valid on tag directive tokens. .SS Return .sp A pointer to the tag directive’s handle, while \fBlenp\fP will be assigned the length of said handle. A NULL will be returned in case of an error. .SS fy_tag_directive_token_prefix .INDENT 0.0 .TP .B const char *fy_tag_directive_token_prefix(struct fy_token *fyt, size_t *lenp) Get a tag directive prefix .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag directive token .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retreives the tag directives token prefix value. Only valid on tag directive tokens. .SS Return .sp A pointer to the tag directive’s prefix, while \fBlenp\fP will be assigned the length of said prefix. A NULL will be returned in case of an error. .SS fy_document_tag_directive_add .INDENT 0.0 .TP .B int fy_document_tag_directive_add(struct fy_document *fyd, const char *handle, const char *prefix) Add a tag directive to a document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBhandle\fP (const char*) – The handle of the tag directive .IP \(bu 2 \fBprefix\fP (const char*) – The prefix of the tag directive .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Add tag directive to the document. .SS Return .sp 0 on success, \-1 on error .SS fy_document_tag_directive_remove .INDENT 0.0 .TP .B int fy_document_tag_directive_remove(struct fy_document *fyd, const char *handle) Remove a tag directive .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBhandle\fP (const char*) – The handle of the tag directive to remove. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Remove a tag directive from a document. Note that removal is prohibited if any node is still using this tag directive. .SS Return .sp 0 on success, \-1 on error .SS fy_document_lookup_anchor .INDENT 0.0 .TP .B struct fy_anchor *fy_document_lookup_anchor(struct fy_document *fyd, const char *anchor, size_t len) Lookup an anchor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBanchor\fP (const char*) – The anchor to look for .IP \(bu 2 \fBlen\fP (size_t) – The length of the anchor (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Lookup for an anchor having the name provided .SS Return .sp The anchor if found, NULL otherwise .SS fy_document_lookup_anchor_by_token .INDENT 0.0 .TP .B struct fy_anchor *fy_document_lookup_anchor_by_token(struct fy_document *fyd, struct fy_token *anchor) Lookup an anchor by token text .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBanchor\fP (struct fy_token*) – The token contains the anchor text to look for .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Lookup for an anchor having the name provided from the text of the token .SS Return .sp The anchor if found, NULL otherwise .SS fy_document_lookup_anchor_by_node .INDENT 0.0 .TP .B struct fy_anchor *fy_document_lookup_anchor_by_node(struct fy_document *fyd, struct fy_node *fyn) Lookup an anchor by node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Lookup for an anchor located in the given node .SS Return .sp The anchor if found, NULL otherwise .SS fy_anchor_get_text .INDENT 0.0 .TP .B const char *fy_anchor_get_text(struct fy_anchor *fya, size_t *lenp) Get the text of an anchor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfya\fP (struct fy_anchor*) – The anchor .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method will return a pointer to the text of an anchor along with the length of it. Note that this text is \fInot\fP NULL terminated. .SS Return .sp A pointer to the text of the anchor, while \fBlenp\fP will be assigned the length of said anchor. A NULL will be returned in case of an error. .SS fy_anchor_node .INDENT 0.0 .TP .B struct fy_node *fy_anchor_node(struct fy_anchor *fya) Get the node of an anchor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfya\fP (struct fy_anchor*) – The anchor .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method returns the node associated with the anchor. .SS Return .sp The node of the anchor, or NULL in case of an error. .SS fy_document_anchor_iterate .INDENT 0.0 .TP .B struct fy_anchor *fy_document_anchor_iterate(struct fy_document *fyd, void **prevp) Iterate over a document’s anchors .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBprevp\fP (void**) – The previous state of the iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method iterates over all the documents anchors. The start of the iteration is signalled by a NULL in *prevp. .SS Return .sp The next anchor in the document or NULL at the end of them. .SS fy_document_set_anchor .INDENT 0.0 .TP .B int fy_document_set_anchor(struct fy_document *fyd, struct fy_node *fyn, const char *text, size_t len) Place an anchor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to set the anchor to .IP \(bu 2 \fBtext\fP (const char*) – Pointer to the anchor text .IP \(bu 2 \fBlen\fP (size_t) – Size of the anchor text, or (size_t)\-1 for ‘0’ terminated. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Places an anchor to the node with the give text name. .sp Note that the data are not copied, merely a reference is taken, so it must be available while the node is in use. .sp Also not that this method is deprecated; use \fI\%fy_node_set_anchor()\fP instead. .SS Return .sp 0 on success, \-1 on error. .SS fy_node_set_anchor .INDENT 0.0 .TP .B int fy_node_set_anchor(struct fy_node *fyn, const char *text, size_t len) Place an anchor to the node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to set the anchor to .IP \(bu 2 \fBtext\fP (const char*) – Pointer to the anchor text .IP \(bu 2 \fBlen\fP (size_t) – Size of the anchor text, or (size_t)\-1 for ‘0’ terminated. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Places an anchor to the node with the give text name. .sp Note that the data are not copied, merely a reference is taken, so it must be available while the node is in use. .sp This is similar to \fI\%fy_document_set_anchor()\fP with the document set to the document of the \fBfyn\fP node. .SS Return .sp 0 on success, \-1 on error. .SS fy_node_set_anchor_copy .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to set the anchor to .IP \(bu 2 \fBtext\fP (const char*) – Pointer to the anchor text .IP \(bu 2 \fBlen\fP (size_t) – Size of the anchor text, or (size_t)\-1 for ‘0’ terminated. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 0 on success, \-1 on error. .SS fy_node_set_vanchorf .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to set the anchor to .IP \(bu 2 \fBfmt\fP (const char*) – Pointer to the anchor format string .IP \(bu 2 \fBap\fP (va_list) – The argument list. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Places an anchor to the node with the give text name as created via vprintf’ing the arguments. .SS Return .sp 0 on success, \-1 on error. .SS fy_node_set_anchorf .INDENT 0.0 .TP .B int fy_node_set_anchorf(struct fy_node *fyn, const char *fmt, \&...) Place an anchor to the node using a printf interface. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to set the anchor to .IP \(bu 2 \fBfmt\fP (const char*) – Pointer to the anchor format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Places an anchor to the node with the give text name as created via printf’ing the arguments. .SS Return .sp 0 on success, \-1 on error. .SS fy_node_remove_anchor .INDENT 0.0 .TP .B int fy_node_remove_anchor(struct fy_node *fyn) Remove an anchor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to remove anchors from .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Remove an anchor for the given node (if it exists) .SS Return .sp 0 on success, \-1 on error. .SS fy_node_get_anchor .INDENT 0.0 .TP .B struct fy_anchor *fy_node_get_anchor(struct fy_node *fyn) Get the anchor of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the anchor of the given node (if it exists) .SS Return .sp The anchor if there’s one at the node, or NULL otherwise .SS fy_node_get_nearest_anchor .INDENT 0.0 .TP .B struct fy_anchor *fy_node_get_nearest_anchor(struct fy_node *fyn) Get the nearest anchor of the node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the anchor of the nearest parent of the given node or the given node if it has one. .SS Return .sp The nearest anchor if there’s one, or NULL otherwise .SS fy_node_get_nearest_child_of .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_base\fP (struct fy_node*) – The base node .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to start from .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the nearest node which is a child of fyn_base starting at fyn and working upwards. .SS Return .sp The nearest child of the base if there’s one, or NULL otherwise .SS fy_node_create_alias .INDENT 0.0 .TP .B struct fy_node *fy_node_create_alias(struct fy_document *fyd, const char *alias, size_t len) Create an alias node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBalias\fP (const char*) – The alias text .IP \(bu 2 \fBlen\fP (size_t) – The length of the alias (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an alias on the given document .sp Note that the data are not copied, merely a reference is taken, so it must be available while the node is in use. .SS Return .sp The created alias node, or NULL in case of an error .SS fy_node_create_alias_copy .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBalias\fP (const char*) – The alias text .IP \(bu 2 \fBlen\fP (size_t) – The length of the alias (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an alias on the given document .sp A copy of the data will be made, so it is safe to free the data after the call. .SS Return .sp The created alias node, or NULL in case of an error .SS fy_node_get_meta .INDENT 0.0 .TP .B void *fy_node_get_meta(struct fy_node *fyn) Get the meta pointer of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to get meta data from .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the meta pointer of a node. .SS Return .sp The stored meta data pointer .SS fy_node_set_meta .INDENT 0.0 .TP .B int fy_node_set_meta(struct fy_node *fyn, void *meta) Set the meta pointer of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to set meta data .IP \(bu 2 \fBmeta\fP (void*) – The meta data pointer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Set the meta pointer of a node. If \fBmeta\fP is NULL then clear the meta data. .SS Return .sp 0 on success, \-1 on error .SS fy_node_clear_meta .INDENT 0.0 .TP .B void fy_node_clear_meta(struct fy_node *fyn) Clear the meta data of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to clear meta data .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Clears the meta data of a node. .SS typedef fy_node_meta_clear_fn .INDENT 0.0 .TP .B void fy_node_meta_clear_fn(struct fy_node *fyn, void *meta, void *user) Meta data clear method .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node which the meta data is being cleared .IP \(bu 2 \fBmeta\fP (void*) – The meta data of the node assigned via \fI\%fy_node_set_meta()\fP .IP \(bu 2 \fBuser\fP (void*) – The user pointer of \fI\%fy_document_register_meta()\fP .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This is the callback called when meta data are cleared. .SS fy_document_register_meta .INDENT 0.0 .TP .B int fy_document_register_meta(struct fy_document *fyd, \fI\%fy_node_meta_clear_fn\fP clear_fn, void *user) Register a meta cleanup hook .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document which the hook is registered to .IP \(bu 2 \fBclear_fn\fP (\fI\%fy_node_meta_clear_fn\fP) – The clear hook method .IP \(bu 2 \fBuser\fP (void*) – Opaque user provided pointer to the clear method .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Register a meta data cleanup hook, to be called when the node is freed via a final call to \fI\%fy_node_free()\fP\&. The hook is active for all nodes belonging to the document. .SS Return .sp 0 on success, \-1 if another hook is already registered. .SS fy_document_unregister_meta .INDENT 0.0 .TP .B void fy_document_unregister_meta(struct fy_document *fyd) Unregister a meta cleanup hook .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to unregister it’s meta cleanup hook. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Unregister the currently active meta cleanup hook. The previous cleanup hook will be called for every node in the document. .SS fy_node_set_marker .INDENT 0.0 .TP .B bool fy_node_set_marker(struct fy_node *fyn, unsigned int marker) Set a marker of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBmarker\fP (unsigned int) – The marker to set .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The previous value of the marker .SS fy_node_clear_marker .INDENT 0.0 .TP .B bool fy_node_clear_marker(struct fy_node *fyn, unsigned int marker) Clear a marker of a node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBmarker\fP (unsigned int) – The marker to clear .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The previous value of the marker .SS fy_node_is_marker_set .INDENT 0.0 .TP .B bool fy_node_is_marker_set(struct fy_node *fyn, unsigned int marker) Checks whether a marker is set .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBmarker\fP (unsigned int) – The marker index (must be less that FYNWF_MAX_USER_MARKER) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check the state of the given marker. .SS Return .sp The value of the marker (invalid markers return false) .SS fy_node_vreport .INDENT 0.0 .TP .B void fy_node_vreport(struct fy_node *fyn, enum \fI\%fy_error_type\fP type, const char *fmt, va_list ap) Report about a node vprintf style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given node via the specific error type, and using the reporting configuration of the node’s document. .SS fy_node_report .INDENT 0.0 .TP .B void fy_node_report(struct fy_node *fyn, enum \fI\%fy_error_type\fP type, const char *fmt, \&...) Report about a node printf style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given node via the specific error type, and using the reporting configuration of the node’s document. .SS fy_node_override_vreport .INDENT 0.0 .TP .B void fy_node_override_vreport(struct fy_node *fyn, enum \fI\%fy_error_type\fP 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfile\fP (const char*) – The file override .IP \(bu 2 \fBline\fP (int) – The line override .IP \(bu 2 \fBcolumn\fP (int) – The column override .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfile\fP is NULL, no file location will be reported. If either \fBline\fP or \fBcolumn\fP is negative no location will be reported. .SS fy_node_override_report .INDENT 0.0 .TP .B void fy_node_override_report(struct fy_node *fyn, enum \fI\%fy_error_type\fP type, const char *file, int line, int column, const char *fmt, \&...) Report about a node printf style, overriding file, line and column info .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfile\fP (const char*) – The file override .IP \(bu 2 \fBline\fP (int) – The line override .IP \(bu 2 \fBcolumn\fP (int) – The column override .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfile\fP is NULL, no file location will be reported. If either \fBline\fP or \fBcolumn\fP is negative no location will be reported. .SS fy_event_vreport .INDENT 0.0 .TP .B void fy_event_vreport(struct fy_parser *fyp, struct \fI\%fy_event\fP *fye, enum \fI\%fy_event_part\fP fyep, enum \fI\%fy_error_type\fP type, const char *fmt, va_list ap) Report about an event vprintf style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser of which the event was generated from .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .IP \(bu 2 \fBfyep\fP (enum \fI\%fy_event_part\fP) – The event part which the report is about .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given event via the specific error type, focusing at the given event part. .SS fy_event_report .INDENT 0.0 .TP .B void fy_event_report(struct fy_parser *fyp, struct \fI\%fy_event\fP *fye, enum \fI\%fy_event_part\fP fyep, enum \fI\%fy_error_type\fP type, const char *fmt, \&...) Report about an event printf style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser of which the event was generated from .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .IP \(bu 2 \fBfyep\fP (enum \fI\%fy_event_part\fP) – The event part which the report is about .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given event via the specific error type, focusing at the given event part. .SS struct fy_diag_cfg .INDENT 0.0 .TP .B struct fy_diag_cfg The diagnostics configuration .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B fp File descriptor of the error output .TP .B output_fn Callback to use when fp is NULL .TP .B user User pointer to pass to the output_fn .TP .B level The minimum debugging level .TP .B module_mask A bitmask of the enabled modules .TP .B colorize true if output should be colorized using ANSI sequences .TP .B show_source true if source location should be displayed .TP .B show_position true if position should be displayed .TP .B show_type true if the type should be displayed .TP .B show_module true if the module should be displayed .TP .B source_width Width of the source field .TP .B position_width Width of the position field .TP .B type_width Width of the type field .TP .B module_width Width of the module field .UNINDENT .SS Description .sp This structure contains the configuration of the diagnostic object. .SS struct fy_diag_error .INDENT 0.0 .TP .B struct fy_diag_error A collected diagnostic error .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B type Error type .TP .B module The module .TP .B fyt The token (may be NULL) .TP .B msg The message to be output alongside .TP .B file The file which contained the input .TP .B line The line at the error .TP .B column The column at the error .UNINDENT .SS Description .sp This structure contains information about an error being collected by the diagnostic object. .SS fy_diag_create .INDENT 0.0 .TP .B struct fy_diag *fy_diag_create(const struct \fI\%fy_diag_cfg\fP *cfg) Create a diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_diag_cfg\fP*) – The configuration for the diagnostic object (NULL is default) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a diagnostic object using the provided configuration. .SS Return .sp A pointer to the diagnostic object or NULL in case of an error. .SS fy_diag_destroy .INDENT 0.0 .TP .B void fy_diag_destroy(struct fy_diag *diag) Destroy a diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS fy_diag_get_cfg .INDENT 0.0 .TP .B const struct \fI\%fy_diag_cfg\fP *fy_diag_get_cfg(struct fy_diag *diag) Get a diagnostic object’s configuration .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the current configuration of a diagnostic object .SS Return .sp A const pointer to the diagnostic object configuration, or NULL in case where diag is NULL .SS fy_diag_set_cfg .INDENT 0.0 .TP .B void fy_diag_set_cfg(struct fy_diag *diag, const struct \fI\%fy_diag_cfg\fP *cfg) Set a diagnostic object’s configuration .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_diag_cfg\fP*) – The diagnostic configuration .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Replace the current diagnostic configuration with the given configuration passed as an argument. .SS fy_diag_set_level .INDENT 0.0 .TP .B void fy_diag_set_level(struct fy_diag *diag, enum \fI\%fy_error_type\fP level) Set a diagnostic object’s debug error level .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .IP \(bu 2 \fBlevel\fP (enum \fI\%fy_error_type\fP) – The debugging level to set .UNINDENT .UNINDENT .UNINDENT .SS fy_diag_set_colorize .INDENT 0.0 .TP .B void fy_diag_set_colorize(struct fy_diag *diag, bool colorize) Set a diagnostic object’s colorize option .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .IP \(bu 2 \fBcolorize\fP (bool) – The colorize option .UNINDENT .UNINDENT .UNINDENT .SS fy_diag_ref .INDENT 0.0 .TP .B struct fy_diag *fy_diag_ref(struct fy_diag *diag) Increment that reference counter of a diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object to reference .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Increment the reference. .SS Return .sp Always returns the \fBdiag\fP argument .SS fy_diag_unref .INDENT 0.0 .TP .B void fy_diag_unref(struct fy_diag *diag) Take away a ref from a diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object to unref .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Take away a reference, if it gets to 0, the diagnostic object is freed. .SS fy_diag_got_error .INDENT 0.0 .TP .B bool fy_diag_got_error(struct fy_diag *diag) Test whether an error level diagnostic has been produced .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Tests whether an error diagnostic has been produced. .SS Return .sp true if an error has been produced, false otherwise .SS fy_diag_set_error .INDENT 0.0 .TP .B void fy_diag_set_error(struct fy_diag *diag, bool on_error) Sets the error produced state .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .IP \(bu 2 \fBon_error\fP (bool) – The set error state .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Sets the error produced state .SS fy_diag_reset_error .INDENT 0.0 .TP .B void fy_diag_reset_error(struct fy_diag *diag) Reset the error flag of the diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Clears the error flag which was set by an output of an error level diagnostic .SS fy_diag_set_collect_errors .INDENT 0.0 .TP .B void fy_diag_set_collect_errors(struct fy_diag *diag, bool collect_errors) Collect errors instead of outputting .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .IP \(bu 2 \fBcollect_errors\fP (bool) – The collect errors mode .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Set the collect errors mode. When true instead of outputting to the diagnostic interface, errors are collected for later retrieval. .SS fy_diag_get_collect_errors .INDENT 0.0 .TP .B bool fy_diag_get_collect_errors(struct fy_diag *diag) Get collect errors state .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Get the collect errors mode. .SS Return .sp true collecting errors, false otherwise .SS fy_diag_cfg_default .INDENT 0.0 .TP .B void fy_diag_cfg_default(struct \fI\%fy_diag_cfg\fP *cfg) Fill in the configuration structure with defaults .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (struct \fI\%fy_diag_cfg\fP*) – The diagnostic configuration structure .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Fills the configuration structure with defaults. The default always associates the file descriptor to stderr. .SS fy_diag_cfg_from_parser_flags .INDENT 0.0 .TP .B void fy_diag_cfg_from_parser_flags(struct \fI\%fy_diag_cfg\fP *cfg, enum \fI\%fy_parse_cfg_flags\fP pflags) Fill partial diagnostic config structure from parser config flags .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (struct \fI\%fy_diag_cfg\fP*) – The diagnostic configuration structure .IP \(bu 2 \fBpflags\fP (enum \fI\%fy_parse_cfg_flags\fP) – The parser flags .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Fills in part of the configuration structure using parser flags. Since the parser flags do not contain debugging flags anymore this method is deprecated. .SS fy_diag_vprintf .INDENT 0.0 .TP .B int fy_diag_vprintf(struct fy_diag *diag, const char *fmt, va_list ap) vprintf raw interface to diagnostics .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object to use .IP \(bu 2 \fBfmt\fP (const char*) – The vprintf format string .IP \(bu 2 \fBap\fP (va_list) – The arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 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. .SS fy_diag_printf .INDENT 0.0 .TP .B int fy_diag_printf(struct fy_diag *diag, const char *fmt, \&...) printf raw interface to diagnostics .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object to use .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 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. .SS struct fy_diag_ctx .INDENT 0.0 .TP .B struct fy_diag_ctx The diagnostics context .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B level The level of the diagnostic .TP .B module The module of the diagnostic .TP .B source_func The source function .TP .B source_file The source file .TP .B source_line The source line .TP .B file The file that caused the error .TP .B line The line where the diagnostic occured .TP .B column The column where the diagnostic occured .UNINDENT .SS Description .sp This structure contains the diagnostic context .SS fy_vdiag .INDENT 0.0 .TP .B int fy_vdiag(struct fy_diag *diag, const struct \fI\%fy_diag_ctx\fP *fydc, const char *fmt, va_list ap) context aware diagnostic output like vprintf .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object to use .IP \(bu 2 \fBfydc\fP (const struct \fI\%fy_diag_ctx\fP*) – The diagnostic context .IP \(bu 2 \fBfmt\fP (const char*) – The vprintf format string .IP \(bu 2 \fBap\fP (va_list) – The arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Context aware output to the diagnostic object using a standard vprintf interface. .SS Return .sp 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. .SS fy_diagf .INDENT 0.0 .TP .B int fy_diagf(struct fy_diag *diag, const struct \fI\%fy_diag_ctx\fP *fydc, const char *fmt, \&...) context aware diagnostic output like printf .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object to use .IP \(bu 2 \fBfydc\fP (const struct \fI\%fy_diag_ctx\fP*) – The diagnostic context .IP \(bu 2 \fBfmt\fP (const char*) – The vprintf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – variable arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Context aware output to the diagnostic object using a standard printf interface. .SS Return .sp 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. .SS fy_diag_token_vreport .INDENT 0.0 .TP .B void fy_diag_token_vreport(struct fy_diag *diag, struct fy_token *fyt, enum \fI\%fy_error_type\fP type, const char *fmt, va_list ap) Report about a token vprintf style using the given diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given token via the specific error type, and using the reporting configuration of the token’s document. .SS fy_diag_token_report .INDENT 0.0 .TP .B void fy_diag_token_report(struct fy_diag *diag, struct fy_token *fye, enum \fI\%fy_error_type\fP type, const char *fmt, \&...) Report about a token printf style using the given diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfye\fP (struct fy_token*) – The token .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given token via the specific error type, and using the reporting configuration of the token’s document. .SS fy_diag_token_override_vreport .INDENT 0.0 .TP .B void fy_diag_token_override_vreport(struct fy_diag *diag, struct fy_token *fyt, enum \fI\%fy_error_type\fP 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfile\fP (const char*) – The file override .IP \(bu 2 \fBline\fP (int) – The line override .IP \(bu 2 \fBcolumn\fP (int) – The column override .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfile\fP is NULL, no file location will be reported. If either \fBline\fP or \fBcolumn\fP is negative no location will be reported. .SS fy_diag_token_override_report .INDENT 0.0 .TP .B void fy_diag_token_override_report(struct fy_diag *diag, struct fy_token *fyt, enum \fI\%fy_error_type\fP 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfile\fP (const char*) – The file override .IP \(bu 2 \fBline\fP (int) – The line override .IP \(bu 2 \fBcolumn\fP (int) – The column override .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfile\fP is NULL, no file location will be reported. If either \fBline\fP or \fBcolumn\fP is negative no location will be reported. .SS fy_diag_node_vreport .INDENT 0.0 .TP .B void fy_diag_node_vreport(struct fy_diag *diag, struct fy_node *fyn, enum \fI\%fy_error_type\fP type, const char *fmt, va_list ap) Report about a node vprintf style using the given diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given node via the specific error type, and using the reporting configuration of the node’s document. .SS fy_diag_node_report .INDENT 0.0 .TP .B void fy_diag_node_report(struct fy_diag *diag, struct fy_node *fyn, enum \fI\%fy_error_type\fP type, const char *fmt, \&...) Report about a node printf style using the given diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given node via the specific error type, and using the reporting configuration of the node’s document. .SS fy_diag_node_override_vreport .INDENT 0.0 .TP .B void fy_diag_node_override_vreport(struct fy_diag *diag, struct fy_node *fyn, enum \fI\%fy_error_type\fP 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfile\fP (const char*) – The file override .IP \(bu 2 \fBline\fP (int) – The line override .IP \(bu 2 \fBcolumn\fP (int) – The column override .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfile\fP is NULL, no file location will be reported. If either \fBline\fP or \fBcolumn\fP is negative no location will be reported. .SS fy_diag_node_override_report .INDENT 0.0 .TP .B void fy_diag_node_override_report(struct fy_diag *diag, struct fy_node *fyn, enum \fI\%fy_error_type\fP 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfile\fP (const char*) – The file override .IP \(bu 2 \fBline\fP (int) – The line override .IP \(bu 2 \fBcolumn\fP (int) – The column override .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfile\fP is NULL, no file location will be reported. If either \fBline\fP or \fBcolumn\fP is negative no location will be reported. .SS fy_diag_event_vreport .INDENT 0.0 .TP .B void fy_diag_event_vreport(struct fy_diag *diag, struct \fI\%fy_event\fP *fye, enum \fI\%fy_event_part\fP fyep, enum \fI\%fy_error_type\fP type, const char *fmt, va_list ap) Report about an event vprintf style using the given diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .IP \(bu 2 \fBfyep\fP (enum \fI\%fy_event_part\fP) – The event part .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBap\fP (va_list) – The argument list .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given event part via the specific error type. .SS fy_diag_event_report .INDENT 0.0 .TP .B void fy_diag_event_report(struct fy_diag *diag, struct \fI\%fy_event\fP *fye, enum \fI\%fy_event_part\fP fyep, enum \fI\%fy_error_type\fP type, const char *fmt, \&...) Report about a event printf style using the given diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diag object .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .IP \(bu 2 \fBfyep\fP (enum \fI\%fy_event_part\fP) – The event part .IP \(bu 2 \fBtype\fP (enum \fI\%fy_error_type\fP) – The error type .IP \(bu 2 \fBfmt\fP (const char*) – The printf format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – The extra arguments. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Output a report about the given event part via the specific error type. .SS fy_diag_errors_iterate .INDENT 0.0 .TP .B struct \fI\%fy_diag_error\fP *fy_diag_errors_iterate(struct fy_diag *diag, void **prevp) Iterate over the errors of a diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object .IP \(bu 2 \fBprevp\fP (void**) – The previous result iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method iterates over all the errors collected on the diagnostic object. The start of the iteration is signalled by a NULL in *prevp. .SS Return .sp The next errors or NULL when there are not any more. .SS fy_parser_checkpoint_create .INDENT 0.0 .TP .B struct fy_parser_checkpoint *fy_parser_checkpoint_create(struct fy_parser *fyp) Create a parser checkpoint .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_parser_rollback()\fP\&. The checkpoint must be destroyed via \fI\%fy_parser_checkpoint_destroy()\fP when no longer needed. .SS Return .sp A pointer to the checkpoint, or NULL in case of an error .SS fy_parser_checkpoint_destroy .INDENT 0.0 .TP .B void fy_parser_checkpoint_destroy(struct fy_parser_checkpoint *fypchk) Destroy a parser checkpoint .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypchk\fP (struct fy_parser_checkpoint*) – The checkpoint to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy a checkpoint created earlier via \fI\%fy_parser_checkpoint_create()\fP\&. .SS fy_parser_rollback .INDENT 0.0 .TP .B int fy_parser_rollback(struct fy_parser *fyp, struct fy_parser_checkpoint *fypc) Roll back the parser to a checkpoint .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfypc\fP (struct fy_parser_checkpoint*) – The checkpoint to roll back to .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_parser_checkpoint_destroy()\fP\&. .SS Return .sp 0 on success, \-1 on error .SS enum fy_token_type .INDENT 0.0 .TP .B enum fy_token_type Token types .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYTT_NONE No token .TP .B FYTT_STREAM_START Stream start token .TP .B FYTT_STREAM_END Stream end token .TP .B FYTT_VERSION_DIRECTIVE Version directive token .TP .B FYTT_TAG_DIRECTIVE Tag directive token .TP .B FYTT_DOCUMENT_START Document start token .TP .B FYTT_DOCUMENT_END Document end token .TP .B FYTT_BLOCK_SEQUENCE_START Block sequence start token .TP .B FYTT_BLOCK_MAPPING_START Block mapping start token .TP .B FYTT_BLOCK_END Block end token .TP .B FYTT_FLOW_SEQUENCE_START Flow sequence start token .TP .B FYTT_FLOW_SEQUENCE_END Flow sequence end token .TP .B FYTT_FLOW_MAPPING_START Flow mapping start token .TP .B FYTT_FLOW_MAPPING_END Flow mapping end token .TP .B FYTT_BLOCK_ENTRY Block entry token .TP .B FYTT_FLOW_ENTRY Flow entry token .TP .B FYTT_KEY Key token .TP .B FYTT_VALUE Value token .TP .B FYTT_ALIAS Alias token .TP .B FYTT_ANCHOR Anchor token .TP .B FYTT_TAG Tag token .TP .B FYTT_SCALAR Scalar token .TP .B FYTT_INPUT_MARKER Input marker token .TP .B FYTT_PE_SLASH Path expression slash token .TP .B FYTT_PE_ROOT Path expression root token .TP .B FYTT_PE_THIS Path expression this token .TP .B FYTT_PE_PARENT Path expression parent token .TP .B FYTT_PE_MAP_KEY Path expression map key token .TP .B FYTT_PE_SEQ_INDEX Path expression sequence index token .TP .B FYTT_PE_SEQ_SLICE Path expression sequence slice token .TP .B FYTT_PE_SCALAR_FILTER Path expression scalar filter token .TP .B FYTT_PE_COLLECTION_FILTER Path expression collection filter token .TP .B FYTT_PE_SEQ_FILTER Path expression sequence filter token .TP .B FYTT_PE_MAP_FILTER Path expression map filter token .TP .B FYTT_PE_UNIQUE_FILTER Path expression unique filter token .TP .B FYTT_PE_EVERY_CHILD Path expression every child token .TP .B FYTT_PE_EVERY_CHILD_R Path expression every child recursive token .TP .B FYTT_PE_ALIAS Path expression alias token .TP .B FYTT_PE_SIBLING Path expression sibling token .TP .B FYTT_PE_COMMA Path expression comma token .TP .B FYTT_PE_BARBAR Path expression || token .TP .B FYTT_PE_AMPAMP Path expression && token .TP .B FYTT_PE_LPAREN Path expression ( token .TP .B FYTT_PE_RPAREN Path expression ) token .TP .B FYTT_PE_EQEQ Path expression == token .TP .B FYTT_PE_NOTEQ Path expression != token .TP .B FYTT_PE_LT Path expression < token .TP .B FYTT_PE_GT Path expression > token .TP .B FYTT_PE_LTE Path expression <= token .TP .B FYTT_PE_GTE Path expression >= token .TP .B FYTT_SE_PLUS Scalar expression + token .TP .B FYTT_SE_MINUS Scalar expression \- token .TP .B FYTT_SE_MULT Scalar expression * token .TP .B FYTT_SE_DIV Scalar expression / token .TP .B FYTT_PE_METHOD Path expression method token .TP .B FYTT_SE_METHOD Scalar expression method token .TP .B FYTT_PE_BANG Path expression ! token .TP .B FYTT_PE_AT Path expression @ token .UNINDENT .SS fy_token_type_is_valid .INDENT 0.0 .TP .B bool fy_token_type_is_valid(enum \fI\%fy_token_type\fP type) Check token type validity .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (enum \fI\%fy_token_type\fP) – The token type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check if argument token type is a valid one. .SS Return .sp true if the token type is valid, false otherwise .SS fy_token_type_is_yaml .INDENT 0.0 .TP .B bool fy_token_type_is_yaml(enum \fI\%fy_token_type\fP type) Check if token type is valid for YAML .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (enum \fI\%fy_token_type\fP) – The token type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check if argument token type is a valid YAML one. .SS Return .sp true if the token type is a valid YAML one, false otherwise .SS fy_token_type_is_content .INDENT 0.0 .TP .B bool fy_token_type_is_content(enum \fI\%fy_token_type\fP type) Check if token type is valid for YAML content .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (enum \fI\%fy_token_type\fP) – The token type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check if argument token type is a valid YAML content one. .SS Return .sp true if the token type is a valid YAML content one, false otherwise .SS fy_token_type_is_path_expr .INDENT 0.0 .TP .B bool fy_token_type_is_path_expr(enum \fI\%fy_token_type\fP type) Check if token type is valid for a YPATH expression .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (enum \fI\%fy_token_type\fP) – The token type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check if argument token type is a valid YPATH parse expression token .SS Return .sp true if the token type is a valid YPATH one, false otherwise .SS fy_token_type_is_scalar_expr .INDENT 0.0 .TP .B bool fy_token_type_is_scalar_expr(enum \fI\%fy_token_type\fP type) Check if token type is valid for a YPATH scalar expression .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (enum \fI\%fy_token_type\fP) – The token type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Check if argument token type is a valid YPATH parse scalar expression token .SS Return .sp true if the token type is a valid YPATH scalar one, false otherwise .SS fy_token_get_type .INDENT 0.0 .TP .B enum \fI\%fy_token_type\fP fy_token_get_type(struct fy_token *fyt) Return the token’s type .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the token’s type; if NULL then FYTT_NONE is returned .SS Return .sp The token’s type; FYTT_NONE if not a valid token (or NULL) .SS fy_token_start_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_token_start_mark(struct fy_token *fyt) Get token’s start marker .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token to get its start marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The token’s start marker, NULL if not available. .SS fy_token_end_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_token_end_mark(struct fy_token *fyt) Get token’s end marker .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token to get its end marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The token’s end marker, NULL if not available. .SS fy_token_style_start_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_token_style_start_mark(struct fy_token *fyt) Get token’s start marker (style) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token to get its style start marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the token’s start marker if it exists, including the style indicators. Note it is permissable for some token types to have no start marker because they are without content. .SS Return .sp The token’s style start marker, NULL if not available. .SS fy_token_style_end_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_token_style_end_mark(struct fy_token *fyt) Get token’s end marker (style .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token to get its style end marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the token’s end marker if it exists, including the style indicators. Note it is permissable for some token types to have no end marker because they are without content. .SS Return .sp The token’s style end marker, NULL if not available. .SS fy_scan .INDENT 0.0 .TP .B struct fy_token *fy_scan(struct fy_parser *fyp) Low level access to the scanner .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser to get the next token from. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_scan_token_free()\fP .SS Return .sp The next token, or NULL if no more tokens are available. .SS fy_scan_token_free .INDENT 0.0 .TP .B void fy_scan_token_free(struct fy_parser *fyp, struct fy_token *fyt) Free the token returned by \fI\%fy_scan()\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser of which the token was returned by \fI\%fy_scan()\fP .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The token to free .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Free the token returned by \fI\%fy_scan()\fP\&. .SS fy_tag_directive_token_prefix0 .INDENT 0.0 .TP .B const char *fy_tag_directive_token_prefix0(struct fy_token *fyt) Get the prefix contained in the tag directive token as zero terminated string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag directive token out of which the prefix pointer will be returned. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag directive’s prefix contents as a zero terminated string. It is similar to \fI\%fy_tag_directive_token_prefix()\fP, with the difference that the returned string is zero terminated and memory may be allocated to hold it associated with the token. .SS Return .sp A pointer to the zero terminated text representation of the prefix token. NULL in case of an error. .SS fy_tag_directive_token_handle0 .INDENT 0.0 .TP .B const char *fy_tag_directive_token_handle0(struct fy_token *fyt) Get the handle contained in the tag directive token as zero terminated string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag directive token out of which the handle pointer will be returned. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag directive’s handle contents as a zero terminated string. It is similar to \fI\%fy_tag_directive_token_handle()\fP, with the difference that the returned string is zero terminated and memory may be allocated to hold it associated with the token. .SS Return .sp A pointer to the zero terminated text representation of the handle token. NULL in case of an error. .SS fy_tag_token_handle .INDENT 0.0 .TP .B const char *fy_tag_token_handle(struct fy_token *fyt, size_t *lenp) Get the handle contained in the tag token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag token out of which the handle pointer will be returned. .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag handle contents. Will fail if token is not a tag token, or if a memory error happens. .SS Return .sp A pointer to the text representation of the handle token, while \fBlenp\fP will be assigned the character length of said representation. NULL in case of an error. .SS fy_tag_token_suffix .INDENT 0.0 .TP .B const char *fy_tag_token_suffix(struct fy_token *fyt, size_t *lenp) Get the suffix contained in the tag token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag token out of which the suffix pointer will be returned. .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag suffix contents. Will fail if token is not a tag token, or if a memory error happens. .SS Return .sp A pointer to the text representation of the suffix token, while \fBlenp\fP will be assigned the character length of said representation. NULL in case of an error. .SS fy_tag_token_short .INDENT 0.0 .TP .B const char *fy_tag_token_short(struct fy_token *fyt, size_t *lenp) Get the short tag of the tag token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag token out of which the short pointer will be returned. .IP \(bu 2 \fBlenp\fP (size_t*) – Pointer to a variable that will hold the returned length .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp A pointer to the text representation of the short tag, while \fBlenp\fP will be assigned the character length of said representation. NULL in case of an error. .SS fy_tag_token_handle0 .INDENT 0.0 .TP .B const char *fy_tag_token_handle0(struct fy_token *fyt) Get the handle contained in the tag token as zero terminated string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag token out of which the handle pointer will be returned. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag handle contents as a zero terminated string. It is similar to \fI\%fy_tag_token_handle()\fP, with the difference that the returned string is zero terminated and memory may be allocated to hold it associated with the token. .SS Return .sp A pointer to the zero terminated text representation of the handle token. NULL in case of an error. .SS fy_tag_token_short0 .INDENT 0.0 .TP .B const char *fy_tag_token_short0(struct fy_token *fyt) Get the short tag of the tag token as zero terminated string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag token out of which the short pointer will be returned. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp A pointer to the null terminated text representation of the short tag. NULL in case of an error. .SS fy_tag_token_suffix0 .INDENT 0.0 .TP .B const char *fy_tag_token_suffix0(struct fy_token *fyt) Get the suffix contained in the tag token as zero terminated string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag token out of which the suffix pointer will be returned. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag suffix contents as a zero terminated string. It is similar to \fI\%fy_tag_token_suffix()\fP, with the difference that the returned string is zero terminated and memory may be allocated to hold it associated with the token. .SS Return .sp A pointer to the zero terminated text representation of the suffix token. NULL in case of an error. .SS fy_version_directive_token_version .INDENT 0.0 .TP .B const struct \fI\%fy_version\fP *fy_version_directive_token_version(struct fy_token *fyt) Return the version of a version directive token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The version directive token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the version stored in a version directive token. .SS Return .sp 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. .SS fy_scalar_token_get_style .INDENT 0.0 .TP .B enum \fI\%fy_scalar_style\fP fy_scalar_token_get_style(struct fy_token *fyt) Return the style of a scalar token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The scalar token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the style of a scalar token. .SS Return .sp The scalar style of the token, or FYSS_ANY for an error .SS fy_tag_token_tag .INDENT 0.0 .TP .B const struct \fI\%fy_tag\fP *fy_tag_token_tag(struct fy_token *fyt) Get tag of a tag token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag of a tag token. .SS Return .sp A pointer to the tag or NULL in case of an error .SS fy_tag_directive_token_tag .INDENT 0.0 .TP .B const struct \fI\%fy_tag\fP *fy_tag_directive_token_tag(struct fy_token *fyt) Get tag of a tag directive token .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyt\fP (struct fy_token*) – The tag directive token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag of a tag directive token. .SS Return .sp A pointer to the tag or NULL in case of an error .SS fy_event_get_token .INDENT 0.0 .TP .B struct fy_token *fy_event_get_token(struct \fI\%fy_event\fP *fye) Return the main token of an event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to get its main token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The main token if it exists, NULL otherwise or in case of an error .SS fy_event_get_anchor_token .INDENT 0.0 .TP .B struct fy_token *fy_event_get_anchor_token(struct \fI\%fy_event\fP *fye) Return the anchor token of an event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to get its anchor token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the anchor token if it exists. Only valid for mapping/sequence start and scalar events. .SS Return .sp The anchor token if it exists, NULL otherwise or in case of an error .SS fy_event_get_tag_token .INDENT 0.0 .TP .B struct fy_token *fy_event_get_tag_token(struct \fI\%fy_event\fP *fye) Return the tag token of an event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to get its tag token .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the tag token if it exists. Only valid for mapping/sequence start and scalar events. .SS Return .sp The tag token if it exists, NULL otherwise or in case of an error .SS fy_event_start_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_event_start_mark(struct \fI\%fy_event\fP *fye) Get event’s start marker .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to get its start marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the event’s start marker if it exists. The start marker is the one of the event’s main token. .SS Return .sp The event’s start marker, NULL if not available. .SS fy_event_end_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_event_end_mark(struct \fI\%fy_event\fP *fye) Get event’s end marker .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to get its end marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the event’s end marker if it exists. The end marker is the one of the event’s main token. .SS Return .sp The event’s end marker, NULL if not available. .SS fy_event_style_start_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_event_style_start_mark(struct \fI\%fy_event\fP *fye) Get event’s start marker (style) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to get its style start marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the event’s style start marker if it exists. The start marker is the one of the event’s main token, including the style marks. But if the event contains a tag then the start mark is the start of the tag token. .SS Return .sp The event’s start marker, NULL if not available. .SS fy_event_style_end_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_event_style_end_mark(struct \fI\%fy_event\fP *fye) Get event’s end marker (style) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to get its end marker .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the event’s style end marker if it exists. The end marker is the one of the event’s main token. .SS Return .sp The event’s end marker, NULL if not available. .SS fy_event_get_node_style .INDENT 0.0 .TP .B enum \fI\%fy_node_style\fP fy_event_get_node_style(struct \fI\%fy_event\fP *fye) Get the node style of an event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to get it’s node style .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The event’s end marker, NULL if not available. .SS fy_document_start_event_version .INDENT 0.0 .TP .B const struct \fI\%fy_version\fP *fy_document_start_event_version(struct \fI\%fy_event\fP *fye) Return the version of a document start event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The document start event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the version stored in a document start event .SS Return .sp A pointer to the version, or NULL in case of an error, or the event not being a document start event. .SS fy_document_state_version .INDENT 0.0 .TP .B const struct \fI\%fy_version\fP *fy_document_state_version(struct fy_document_state *fyds) Return the version of a document state object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the version stored in a document state object .SS Return .sp A pointer to the version, or NULL in case of an error .SS fy_document_state_start_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_document_state_start_mark(struct fy_document_state *fyds) Get document state’s start mark .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the document state’s start mark (if it exists). Note that purely synthetic documents do not contain one .SS Return .sp The document’s start marker, NULL if not available. .SS fy_document_state_end_mark .INDENT 0.0 .TP .B const struct \fI\%fy_mark\fP *fy_document_state_end_mark(struct fy_document_state *fyds) Get document state’s end mark .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return the document state’s end mark (if it exists). Note that purely synthetic documents do not contain one .SS Return .sp The document’s end marker, NULL if not available. .SS fy_document_state_version_explicit .INDENT 0.0 .TP .B bool fy_document_state_version_explicit(struct fy_document_state *fyds) Version explicit? .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Find out if a document state object’s version was explicitly set in the document. Note that for synthetic documents this method returns false. .SS Return .sp true if version was set explicitly, false otherwise .SS fy_document_state_tags_explicit .INDENT 0.0 .TP .B bool fy_document_state_tags_explicit(struct fy_document_state *fyds) Tags explicit? .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Find out if a document state object’s tags were explicitly set in the document. Note that for synthetic documents this method returns false. .SS Return .sp true if document had tags set explicitly, false otherwise .SS fy_document_state_start_implicit .INDENT 0.0 .TP .B bool fy_document_state_start_implicit(struct fy_document_state *fyds) Started implicitly? .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Find out if a document state object’s document was started implicitly. Note that for synthetic documents this method returns false. .SS Return .sp true if document was started implicitly, false otherwise .SS fy_document_state_end_implicit .INDENT 0.0 .TP .B bool fy_document_state_end_implicit(struct fy_document_state *fyds) Started implicitly? .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Find out if a document state object’s document was ended implicitly. Note that for synthetic documents this method returns false. .SS Return .sp true if document was ended implicitly, false otherwise .SS fy_document_state_json_mode .INDENT 0.0 .TP .B bool fy_document_state_json_mode(struct fy_document_state *fyds) Input was JSON? .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Find out if a document state object’s document was created by a JSON input. Note that for synthetic documents this method returns false. .SS Return .sp true if document was created in JSON mode, false otherwise .SS fy_document_state_tag_directive_iterate .INDENT 0.0 .TP .B const struct \fI\%fy_tag\fP *fy_document_state_tag_directive_iterate(struct fy_document_state *fyds, void **prevp) Iterate over the tag directives of a document state object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state .IP \(bu 2 \fBprevp\fP (void**) – The previous iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The next tag or NULL at the end of the iteration sequence. .SS fy_document_state_tag_directives .INDENT 0.0 .TP .B struct \fI\%fy_tag\fP **fy_document_state_tag_directives(struct fy_document_state *fyds) Get all the tag directives in a malloc’ed array .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return all the tag directives in a dynamically allocated area. Must be \fBfree()\fP‘d when not in use. .SS Return .sp An array of fy_tag pointer structures, terminated with a NULL pointer NULL on error .SS fy_document_state_tag_is_default .INDENT 0.0 .TP .B bool fy_document_state_tag_is_default(struct fy_document_state *fyds, const struct \fI\%fy_tag\fP *tag) Test whether the given tag is a default one .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state .IP \(bu 2 \fBtag\fP (const struct \fI\%fy_tag\fP*) – The tag to check .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Test whether a tag is a default (i.e. impliciticly set) .SS Return .sp true in case that the tag is a default one, false otherwise .SS fy_parser_get_document_state .INDENT 0.0 .TP .B struct fy_document_state *fy_parser_get_document_state(struct fy_parser *fyp) Get the document state of a parser object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the document state object of a parser. Note that this is only valid during parsing. .SS Return .sp The active document state object of the parser, NULL otherwise .SS fy_document_get_document_state .INDENT 0.0 .TP .B struct fy_document_state *fy_document_get_document_state(struct fy_document *fyd) Get the document state of a document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the document state object of a document. .SS Return .sp The document state object of the document, NULL otherwise .SS fy_document_set_document_state .INDENT 0.0 .TP .B int fy_document_set_document_state(struct fy_document *fyd, struct fy_document_state *fyds) Set the document state of a document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state to use, or NULL for default .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Set the document state of a document .SS Return .sp 0 if set operation was successful, \-1 otherwise .SS fy_document_create_from_event .INDENT 0.0 .TP .B struct fy_document *fy_document_create_from_event(struct fy_parser *fyp, struct \fI\%fy_event\fP *fye) Create an empty document using the event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an empty document using the FYET_DOCUMENT_START event generated by the parser. .SS Return .sp The created empty document, or NULL on error. .SS fy_document_update_from_event .INDENT 0.0 .TP .B int fy_document_update_from_event(struct fy_document *fyd, struct fy_parser *fyp, struct \fI\%fy_event\fP *fye) Update the document with the event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Update the document using the FYET_DOCUMENT_END event generated by the parser. .SS Return .sp 0 on success, \-1 on error .SS fy_node_create_from_event .INDENT 0.0 .TP .B struct fy_node *fy_node_create_from_event(struct fy_document *fyd, struct fy_parser *fyp, struct \fI\%fy_event\fP *fye) Create a node using the event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a new node using the supplied event. Allowed events are FYET_SCALAR, FYET_ALIAS, FYET_MAPPING_START & FYET_SEQUENCE_START .SS Return .sp The newly created node, or NULL on error .SS fy_node_update_from_event .INDENT 0.0 .TP .B int fy_node_update_from_event(struct fy_node *fyn, struct fy_parser *fyp, struct \fI\%fy_event\fP *fye) Update a node using the event .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Update information of node created using \fI\%fy_node_create_from_event()\fP Allowed events are FYET_MAPPING_END & FYET_SEQUENCE_END .SS Return .sp 0 on success, \-1 on error .SS fy_node_pair_create_with_key .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document .IP \(bu 2 \fBfyn_parent\fP (struct fy_node*) – The mapping .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node pair key .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp The node pair will be added to the fyn_parent mapping with a subsequent call to \fI\%fy_node_pair_update_with_value()\fP\&. .SS Return .sp The newly created node pair, or NULL on error .SS fy_node_pair_update_with_value .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfynp\fP (struct fy_node_pair*) – The node pair .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node pair value .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_node_pair_create_with_key()\fP\&. Do not intermix other node pair manipulation methods. .SS Return .sp 0 on success, \-1 on error .SS fy_node_sequence_add_item .INDENT 0.0 .TP .B int fy_node_sequence_add_item(struct fy_node *fyn_parent, struct fy_node *fyn) Add an item node to a sequence node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn_parent\fP (struct fy_node*) – The parent sequence node .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node pair item .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp 0 on success, \-1 on error .SS fy_emitter_get_document_state .INDENT 0.0 .TP .B struct fy_document_state *fy_emitter_get_document_state(struct fy_emitter *emit) Get the document state of an emitter object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the document state object of an emitter. Note that this is only valid during emitting. .SS Return .sp The active document state object of the emitter, NULL otherwise .SS fy_emit_event_create .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_emit_event_create(struct fy_emitter *emit, enum \fI\%fy_event_type\fP type, \&...) Create an emit event. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBtype\fP (enum \fI\%fy_event_type\fP) – The event type to create .IP \(bu 2 \fBellipsis\fP (ellipsis) – The optional extra arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an emit event to pass to \fI\%fy_emit_event()\fP The extra arguments differ according to the event to be created .SS FYET_STREAM_START .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 None .UNINDENT .UNINDENT .UNINDENT .SS FYET_STREAM_END .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 None .UNINDENT .UNINDENT .UNINDENT .SS FYET_DOCUMENT_START .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B int implicit true if document start should be marked implicit false if document start should not be marked implicit .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B const struct fy_version *vers Pointer to version to use for the document, or NULL for default .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B 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 .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS FYET_DOCUMENT_END .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B int implicit true if document end should be marked implicit false if document end should not be marked implicit .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS FYET_MAPPING_START .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B enum fy_node_style style Style of the mapping (one of FYNS_ANY, FYNS_BLOCK or FYNS_FLOW) .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B const char *anchor Anchor to place at the mapping, or NULL for none .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B const char *tag Tag to place at the mapping, or NULL for none .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS FYET_MAPPING_END .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 None .UNINDENT .UNINDENT .UNINDENT .SS FYET_SEQUENCE_START .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B enum fy_node_style style Style of the sequence (one of FYNS_ANY, FYNS_BLOCK or FYNS_FLOW) .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B const char *anchor Anchor to place at the sequence, or NULL for none .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B const char *tag Tag to place at the sequence, or NULL for none .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS FYET_SEQUENCE_END .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 None .UNINDENT .UNINDENT .UNINDENT .SS FYET_SCALAR .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B 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 .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B const char *value Pointer to the scalar contents. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B size_t len Length of the scalar contents, of FY_NT (\-1) for strlen(value) .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B const char *anchor Anchor to place at the scalar, or NULL for none .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B const char *tag Tag to place at the scalar, or NULL for none .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS FYET_ALIAS .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B const char *value Pointer to the alias. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The created event or NULL in case of an error .SS fy_emit_event_vcreate .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_emit_event_vcreate(struct fy_emitter *emit, enum \fI\%fy_event_type\fP type, va_list ap) Create an emit event using varargs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBtype\fP (enum \fI\%fy_event_type\fP) – The event type to create .IP \(bu 2 \fBap\fP (va_list) – The variable argument list pointer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an emit event to pass to \fI\%fy_emit_event()\fP The varargs analogous to \fI\%fy_emit_event_create()\fP\&. .SS Return .sp The created event or NULL in case of an error .SS fy_emit_event_free .INDENT 0.0 .TP .B void fy_emit_event_free(struct fy_emitter *emit, struct \fI\%fy_event\fP *fye) Free an event created via \fI\%fy_emit_event_create()\fP .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBemit\fP (struct fy_emitter*) – The emitter .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to free .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Free an event previously created via \fI\%fy_emit_event_create()\fP\&. Note that usually you don’t have to call this method since if you pass the event to \fI\%fy_emit_event()\fP it shall be disposed properly. Only use is error recovery and cleanup. .SS fy_parse_event_create .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_parse_event_create(struct fy_parser *fyp, enum \fI\%fy_event_type\fP type, \&...) Create an emit event. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBtype\fP (enum \fI\%fy_event_type\fP) – The event type to create .IP \(bu 2 \fBellipsis\fP (ellipsis) – variable arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp See \fI\%fy_emit_event_create()\fP… .SS Return .sp The created event or NULL in case of an error .SS fy_parse_event_vcreate .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_parse_event_vcreate(struct fy_parser *fyp, enum \fI\%fy_event_type\fP type, va_list ap) Create an emit event using varargs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBtype\fP (enum \fI\%fy_event_type\fP) – The event type to create .IP \(bu 2 \fBap\fP (va_list) – The variable argument list pointer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create an emit event to pass to \fI\%fy_emit_event()\fP The varargs analogous to \fI\%fy_parse_event_create()\fP\&. .SS Return .sp The created event or NULL in case of an error .SH PATH EXECUTION .sp This header provides the ypath subsystem — a JSONPath / XPath\-like query language for navigating YAML document trees. .sp A ypath expression such as \fB/servers/0/host\fP is first \fIparsed\fP into a compiled \fBstruct fy_path_expr\fP and then \fIexecuted\fP against a starting node in any \fBstruct fy_document\fP to produce a result set of matching nodes. Filter predicates and wildcards are also supported. .sp \fBTypical workflow\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX // 1. Create a path parser struct fy_path_parser *fypp = fy_path_parser_create(NULL); // 2. Compile an expression struct fy_path_expr *expr = fy_path_parse_expr_from_string(fypp, \(dq/servers/0/host\(dq, \-1); // 3. Create an executor and run the expression struct fy_path_exec *fypx = fy_path_exec_create(NULL); fy_path_exec_execute(fypx, expr, fy_document_root(fyd)); // 4. Iterate results void *iter = NULL; struct fy_node *fyn; while ((fyn = fy_path_exec_results_iterate(fypx, &iter)) != NULL) process(fyn); // 5. Cleanup fy_path_exec_destroy(fypx); fy_path_expr_free(expr); fy_path_parser_destroy(fypp); .EE .UNINDENT .UNINDENT .sp For one\-shot use, \fBfy_path_expr_build_from_string()\fP wraps steps 1 and 2 into a single call. .sp The executor can be reset and re\-used for multiple executions against the same or different documents. The compiled expression is independent of any document and may be executed repeatedly. .SS enum fy_path_parse_cfg_flags .INDENT 0.0 .TP .B enum fy_path_parse_cfg_flags Path parse configuration flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_path_parse_cfg_flags { FYPPCF_QUIET, FYPPCF_DISABLE_RECYCLING, FYPPCF_DISABLE_ACCELERATORS }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYPPCF_QUIET Quiet, do not output any information messages .TP .B FYPPCF_DISABLE_RECYCLING Disable recycling optimization .TP .B FYPPCF_DISABLE_ACCELERATORS Disable use of access accelerators (saves memory) .UNINDENT .SS Description .sp These flags control the operation of the path parse .SS struct fy_path_parse_cfg .INDENT 0.0 .TP .B struct fy_path_parse_cfg path parser configuration structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_path_parse_cfg { enum fy_path_parse_cfg_flags flags; void *userdata; struct fy_diag *diag; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B flags Configuration flags .TP .B userdata Opaque user data pointer .TP .B diag Optional diagnostic interface to use .UNINDENT .SS Description .sp Argument to the \fI\%fy_path_parser_create()\fP method which performs parsing of a ypath expression .SS fy_path_parser_create .INDENT 0.0 .TP .B struct fy_path_parser *fy_path_parser_create(const struct \fI\%fy_path_parse_cfg\fP *cfg) Create a ypath parser. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_path_parse_cfg\fP*) – The configuration for the path parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a path parser with its configuration \fBcfg\fP The path parser may be destroyed by a corresponding call to \fI\%fy_path_parser_destroy()\fP\&. If \fBcfg\fP is NULL a default yaml parser is created. .SS Return .sp A pointer to the path parser or NULL in case of an error. .SS fy_path_parser_destroy .INDENT 0.0 .TP .B void fy_path_parser_destroy(struct fy_path_parser *fypp) Destroy the given path parser .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path_parser*) – The path parser to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy a path parser created earlier via \fI\%fy_path_parser_create()\fP\&. .SS fy_path_parser_reset .INDENT 0.0 .TP .B int fy_path_parser_reset(struct fy_path_parser *fypp) Reset a path parser completely .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path_parser*) – The path parser to reset .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Completely reset a path parser, including after an error that caused a parser error to be emitted. .SS Return .sp 0 if the reset was successful, \-1 otherwise .SS fy_path_parse_expr_from_string .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path_parser*) – The path parser to use .IP \(bu 2 \fBstr\fP (const char*) – The ypath source to use. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a path expression from a string using the provided path parser. .SS Return .sp The created path expression or NULL on error. .SS fy_path_expr_build_from_string .INDENT 0.0 .TP .B struct fy_path_expr *fy_path_expr_build_from_string(const struct \fI\%fy_path_parse_cfg\fP *pcfg, const char *str, size_t len) Parse an expression from a given string .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpcfg\fP (const struct \fI\%fy_path_parse_cfg\fP*) – The path parser configuration to use, or NULL for default .IP \(bu 2 \fBstr\fP (const char*) – The ypath source to use. .IP \(bu 2 \fBlen\fP (size_t) – The length of the string (or \-1 if ‘0’ terminated) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Create a path expression from a string using the provided path parser configuration. .SS Return .sp The created path expression or NULL on error. .SS fy_path_expr_free .INDENT 0.0 .TP .B void fy_path_expr_free(struct fy_path_expr *expr) Free a path expression .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBexpr\fP (struct fy_path_expr*) – The expression to free (may be NULL) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Free a previously returned expression from any of the path parser methods like \fI\%fy_path_expr_build_from_string()\fP .SS fy_path_expr_dump .INDENT 0.0 .TP .B void fy_path_expr_dump(struct fy_path_expr *expr, struct fy_diag *diag, enum \fI\%fy_error_type\fP errlevel, int level, const char *banner) Dump the contents of a path expression to the diagnostic object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBexpr\fP (struct fy_path_expr*) – The expression to dump .IP \(bu 2 \fBdiag\fP (struct fy_diag*) – The diagnostic object to use .IP \(bu 2 \fBerrlevel\fP (enum \fI\%fy_error_type\fP) – The error level which the diagnostic will use .IP \(bu 2 \fBlevel\fP (int) – The nest level; should be set to 0 .IP \(bu 2 \fBbanner\fP (const char*) – The banner to display on level 0 .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dumps the expression using the provided error level. .SS fy_path_expr_to_document .INDENT 0.0 .TP .B struct fy_document *fy_path_expr_to_document(struct fy_path_expr *expr) Converts the path expression to a YAML document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBexpr\fP (struct fy_path_expr*) – The expression to convert to a document .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Converts the expression to a YAML document which is useful for understanding what the expression evaluates to. .SS Return .sp The document of the expression or NULL on error. .SS enum fy_path_exec_cfg_flags .INDENT 0.0 .TP .B enum fy_path_exec_cfg_flags Path executor configuration flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_path_exec_cfg_flags { FYPXCF_QUIET, FYPXCF_DISABLE_RECYCLING, FYPXCF_DISABLE_ACCELERATORS }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYPXCF_QUIET Quiet, do not output any information messages .TP .B FYPXCF_DISABLE_RECYCLING Disable recycling optimization .TP .B FYPXCF_DISABLE_ACCELERATORS Disable use of access accelerators (saves memory) .UNINDENT .SS Description .sp These flags control the operation of the path expression executor .SS struct fy_path_exec_cfg .INDENT 0.0 .TP .B struct fy_path_exec_cfg path expression executor configuration structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_path_exec_cfg { enum fy_path_exec_cfg_flags flags; void *userdata; struct fy_diag *diag; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B flags Configuration flags .TP .B userdata Opaque user data pointer .TP .B diag Optional diagnostic interface to use .UNINDENT .SS Description .sp Argument to the \fI\%fy_path_exec_create()\fP method which performs execution of a ypath expression .SS fy_path_exec_create .INDENT 0.0 .TP .B struct fy_path_exec *fy_path_exec_create(const struct \fI\%fy_path_exec_cfg\fP *xcfg) Create a ypath expression executor. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBxcfg\fP (const struct \fI\%fy_path_exec_cfg\fP*) – The configuration for the executor .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a ypath expression parser with its configuration \fBcfg\fP The executor may be destroyed by a corresponding call to \fI\%fy_path_exec_destroy()\fP\&. .SS Return .sp A pointer to the executor or NULL in case of an error. .SS fy_path_exec_destroy .INDENT 0.0 .TP .B void fy_path_exec_destroy(struct fy_path_exec *fypx) Destroy the given path expression executor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypx\fP (struct fy_path_exec*) – The path parser to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy ane executor created earlier via \fI\%fy_path_exec_create()\fP\&. .SS fy_path_exec_reset .INDENT 0.0 .TP .B int fy_path_exec_reset(struct fy_path_exec *fypx) Reset an executor .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypx\fP (struct fy_path_exec*) – The executor to reset .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Completely reset an executor without releasing it. .SS Return .sp 0 if the reset was successful, \-1 otherwise .SS fy_path_exec_execute .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypx\fP (struct fy_path_exec*) – The executor to use .IP \(bu 2 \fBexpr\fP (struct fy_path_expr*) – The expression to use .IP \(bu 2 \fBfyn_start\fP (struct fy_node*) – The node on which the expression will begin. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Execute the expression starting at fyn_start. If execution is successful the results are available via \fI\%fy_path_exec_results_iterate()\fP .sp Note that it is illegal to modify the state of the document that the results reside between this call and the results collection. .SS Return .sp 0 if the execution was successful, \-1 otherwise .sp Note that the execution may be successful but no results were produced, in which case the iterator will return NULL. .SS fy_path_exec_results_iterate .INDENT 0.0 .TP .B struct fy_node *fy_path_exec_results_iterate(struct fy_path_exec *fypx, void **prevp) Iterate over the results of execution .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypx\fP (struct fy_path_exec*) – The executor .IP \(bu 2 \fBprevp\fP (void**) – The previous result iterator .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method iterates over all the results in the executor. The start of the iteration is signalled by a NULL in *prevp. .SS Return .sp The next node in the result set or NULL at the end of the results. .SH DOCUMENT ITERATION .sp This header provides \fBstruct fy_document_iterator\fP, which traverses a document tree depth\-first without using system stack recursion. Two usage modes are supported: .sp \fBNode iteration\fP — visit every node in a subtree in document order: .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_document_iterator *fydi = fy_document_iterator_create(); fy_document_iterator_node_start(fydi, fy_document_root(fyd)); struct fy_node *fyn; while ((fyn = fy_document_iterator_node_next(fydi)) != NULL) process(fyn); fy_document_iterator_destroy(fydi); .EE .UNINDENT .UNINDENT .sp \fBEvent replay\fP — regenerate the YAML event stream that produced the document, suitable for feeding into a parser, emitter, or composer: .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_document_iterator *fydi = fy_document_iterator_create_on_document(fyd); struct fy_event *fye; while ((fye = fy_document_iterator_generate_next(fydi)) != NULL) { process_event(fye); fy_document_iterator_event_free(fydi, fye); } fy_document_iterator_destroy(fydi); .EE .UNINDENT .UNINDENT .sp The iterator can also be attached to a \fBstruct fy_parser\fP via \fBfy_parser_set_document_iterator()\fP, making a parser transparently replay the events of an existing document rather than parsing fresh input. .sp Events emitted by the iterator are in the same order as those that originally created the document, so round\-trip fidelity is preserved. .SS enum fy_document_iterator_cfg_flags .INDENT 0.0 .TP .B enum fy_document_iterator_cfg_flags Document iterator configuration flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_document_iterator_cfg_flags { FYDICF_WANT_BODY_EVENTS, FYDICF_WANT_DOCUMENT_BODY_EVENTS, FYDICF_WANT_STREAM_DOCUMENT_BODY_EVENTS }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYDICF_WANT_BODY_EVENTS Generate body events .TP .B FYDICF_WANT_DOCUMENT_BODY_EVENTS Generate document and body events .TP .B FYDICF_WANT_STREAM_DOCUMENT_BODY_EVENTS Generate stream, document and body events .UNINDENT .SS Description .sp These flags control the operation of the document iterator .SS struct fy_document_iterator_cfg .INDENT 0.0 .TP .B struct fy_document_iterator_cfg document iterator configuration structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_document_iterator_cfg { enum fy_document_iterator_cfg_flags flags; struct fy_document *fyd; struct fy_node *iterate_root; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B flags The document iterator flags .TP .B fyd The document to iterate on (or NULL if iterate_root is set) .TP .B iterate_root The root of iteration (NULL when fyd is not NULL) .UNINDENT .SS Description .sp Argument to the \fI\%fy_document_iterator_create_cfg()\fP method. .SS fy_document_iterator_create .INDENT 0.0 .TP .B struct fy_document_iterator *fy_document_iterator_create(void) Create a document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvoid\fP – no arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a document iterator, that can trawl through a document without using recursion. .SS Return .sp The newly created document iterator or NULL on error .SS fy_document_iterator_create_cfg .INDENT 0.0 .TP .B struct fy_document_iterator *fy_document_iterator_create_cfg(const struct \fI\%fy_document_iterator_cfg\fP *cfg) Create a document iterator using config .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_document_iterator_cfg\fP*) – The document iterator to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The newly created document iterator or NULL on error .SS fy_document_iterator_create_on_document .INDENT 0.0 .TP .B struct fy_document_iterator *fy_document_iterator_create_on_document(struct fy_document *fyd) Create a document iterator on document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document to iterate on .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a document iterator, starting at the root of the given document. .SS Return .sp The newly created document iterator or NULL on error .SS fy_document_iterator_create_on_node .INDENT 0.0 .TP .B struct fy_document_iterator *fy_document_iterator_create_on_node(struct fy_node *fyn) Create a document iterator on node .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The node to iterate on .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a document iterator, starting at the given node .SS Return .sp The newly created document iterator or NULL on error .SS fy_document_iterator_destroy .INDENT 0.0 .TP .B void fy_document_iterator_destroy(struct fy_document_iterator *fydi) Destroy the given document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy a document iterator created earlier via \fI\%fy_document_iterator_create()\fP\&. .SS fy_document_iterator_event_free .INDENT 0.0 .TP .B void fy_document_iterator_event_free(struct fy_document_iterator *fydi, struct \fI\%fy_event\fP *fye) Free an event that was created by a document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator that created the event .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Free (possibly recycling) an event that was created by a document iterator. .SS fy_document_iterator_stream_start .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_document_iterator_stream_start(struct fy_document_iterator *fydi) Create a stream start event using the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a stream start event on the document iterator and advances the internal state of it accordingly. .SS Return .sp The newly created stream start event, or NULL on error. .SS fy_document_iterator_stream_end .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_document_iterator_stream_end(struct fy_document_iterator *fydi) Create a stream end event using the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a stream end event on the document iterator and advances the internal state of it accordingly. .SS Return .sp The newly created stream end event, or NULL on error. .SS fy_document_iterator_document_start .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_document_iterator_document_start(struct fy_document_iterator *fydi, struct fy_document *fyd) Create a document start event using the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to create the event .IP \(bu 2 \fBfyd\fP (struct fy_document*) – The document containing the document state that is used in the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_document_iterator_document_end()\fP\&. .SS Return .sp The newly created document start event, or NULL on error. .SS fy_document_iterator_document_end .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_document_iterator_document_end(struct fy_document_iterator *fydi) Create a document end event using the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_document_iterator_document_start()\fP can now be released. .SS Return .sp The newly created document end event, or NULL on error. .SS fy_document_iterator_body_next .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_document_iterator_body_next(struct fy_document_iterator *fydi) Create document body events until the end .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp 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. .sp 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. .SS Return .sp The newly created document body event or NULL at an error, or an end of the event stream. Use \fI\%fy_document_iterator_get_error()\fP to check if an error occured. .SS fy_document_iterator_node_start .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to run with .IP \(bu 2 \fBfyn\fP (struct fy_node*) – The iterator root for the iteration .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Starts an iteration run starting at the given node. .SS fy_document_iterator_node_next .INDENT 0.0 .TP .B struct fy_node *fy_document_iterator_node_next(struct fy_document_iterator *fydi) Return the next node in the iteration sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to use for the iteration .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns a pointer to the next node iterating using as a start the node given at \fI\%fy_document_iterator_node_start()\fP\&. The first node returned will be that, followed by all the remaing nodes in the subtree. .SS Return .sp The next node in the iteration sequence or NULL at the end, or if an error occured. .SS fy_document_iterator_generate_next .INDENT 0.0 .TP .B struct \fI\%fy_event\fP *fy_document_iterator_generate_next(struct fy_document_iterator *fydi) Create events from document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This is a method that will handle the complex state of generating stream, document and body events on the given iterator. .sp When generation is complete a NULL event will be generated. .SS Return .sp The newly created event or NULL at an error, or an end of the event stream. Use \fI\%fy_document_iterator_get_error()\fP to check if an error occured. .SS fy_document_iterator_get_error .INDENT 0.0 .TP .B bool fy_document_iterator_get_error(struct fy_document_iterator *fydi) Get the error state of the document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to use for checking it’s error state. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp true if it was in an error state, false otherwise. .SS enum fy_parser_event_generator_flags .INDENT 0.0 .TP .B enum fy_parser_event_generator_flags The parser event generator flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_parser_event_generator_flags { FYPEGF_GENERATE_DOCUMENT_EVENTS, FYPEGF_GENERATE_STREAM_EVENTS, FYPEGF_GENERATE_ALL_EVENTS }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYPEGF_GENERATE_DOCUMENT_EVENTS generate document events .TP .B FYPEGF_GENERATE_STREAM_EVENTS generate stream events .TP .B FYPEGF_GENERATE_ALL_EVENTS generate all events .UNINDENT .SS fy_parser_set_document_iterator .INDENT 0.0 .TP .B int fy_parser_set_document_iterator(struct fy_parser *fyp, enum \fI\%fy_parser_event_generator_flags\fP flags, struct fy_document_iterator *fydi) Associate a parser with a document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBflags\fP (enum \fI\%fy_parser_event_generator_flags\fP) – The event generation flags .IP \(bu 2 \fBfydi\fP (struct fy_document_iterator*) – The document iterator to associate .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Associate a parser with a document iterator, that is instead of parsing the events will be generated by the document iterator. .SS Return .sp 0 on success, \-1 on error .SH DOCUMENT BUILDER .sp This header provides \fBstruct fy_document_builder\fP, which accumulates YAML parser events and assembles them into a \fBstruct fy_document\fP tree. .sp The builder supports two operating modes: .sp \fBPull mode\fP — the builder drives a parser internally: .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_document_builder *fydb = fy_document_builder_create_on_parser(fyp); struct fy_document *fyd; while ((fyd = fy_document_builder_load_document(fydb, fyp)) != NULL) { process(fyd); fy_document_destroy(fyd); } fy_document_builder_destroy(fydb); .EE .UNINDENT .UNINDENT .sp \fBPush mode\fP — the caller feeds events one at a time and takes ownership when the document is complete: .INDENT 0.0 .INDENT 3.5 .sp .EX fy_document_builder_set_in_stream(fydb); struct fy_event *fye; while ((fye = get_next_event()) != NULL) { fy_document_builder_process_event(fydb, fye); if (fy_document_builder_is_document_complete(fydb)) { struct fy_document *fyd = fy_document_builder_take_document(fydb); process(fyd); fy_document_destroy(fyd); } } .EE .UNINDENT .UNINDENT .sp Push mode is useful when events arrive asynchronously or from a source other than a libfyaml parser, such as a document iterator or a network stream. .sp \fBfy_parse_load_document_with_builder()\fP provides the simplest interface: a single call that returns the next complete document from a parser. .SS struct fy_document_builder_cfg .INDENT 0.0 .TP .B struct fy_document_builder_cfg document builder configuration structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_document_builder_cfg { struct fy_parse_cfg parse_cfg; void *userdata; struct fy_diag *diag; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B parse_cfg Parser configuration .TP .B userdata Opaque user data pointer .TP .B diag Optional diagnostic interface to use .UNINDENT .SS Description .sp Argument to the \fI\%fy_document_builder_create()\fP method .SS fy_document_builder_create .INDENT 0.0 .TP .B struct fy_document_builder *fy_document_builder_create(const struct \fI\%fy_document_builder_cfg\fP *cfg) Create a document builder .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct \fI\%fy_document_builder_cfg\fP*) – The configuration for the document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a document builder with its configuration \fBcfg\fP The document builder may be destroyed by a corresponding call to \fI\%fy_document_builder_destroy()\fP\&. .SS Return .sp A pointer to the document builder or NULL in case of an error. .SS fy_document_builder_create_on_parser .INDENT 0.0 .TP .B struct fy_document_builder *fy_document_builder_create_on_parser(struct fy_parser *fyp) Create a document builder pulling state from the parser .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser to associate with .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a document builder pulling state from the given parser .SS Return .sp A pointer to the document builder or NULL in case of an error. .SS fy_document_builder_reset .INDENT 0.0 .TP .B void fy_document_builder_reset(struct fy_document_builder *fydb) Reset a document builder .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Resets a document builder without destroying it .SS fy_document_builder_destroy .INDENT 0.0 .TP .B void fy_document_builder_destroy(struct fy_document_builder *fydb) Destroy a document builder .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy a document builder .SS fy_document_builder_get_document .INDENT 0.0 .TP .B struct fy_document *fy_document_builder_get_document(struct fy_document_builder *fydb) Get the document of a builder .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the document of a document builder. This document may be incomplete. If you need to take ownership use \fI\%fy_document_builder_take_document()\fP\&. .SS Return .sp The document that the builder built, or NULL in case of an error .SS fy_document_builder_is_in_stream .INDENT 0.0 .TP .B bool fy_document_builder_is_in_stream(struct fy_document_builder *fydb) Test document builder in stream .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Find out if the document builder is in ‘stream’ state, i.e. after stream start but before stream end events are generated. .SS Return .sp true if in stream, false otherwise .SS fy_document_builder_is_in_document .INDENT 0.0 .TP .B bool fy_document_builder_is_in_document(struct fy_document_builder *fydb) Test document builder in document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Find out if the document builder is in ‘document’ state, i.e. after document start but before document end events are generated. .SS Return .sp true if in document, false otherwise .SS fy_document_builder_is_document_complete .INDENT 0.0 .TP .B bool fy_document_builder_is_document_complete(struct fy_document_builder *fydb) Test document builder complete .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Find out if the document of the builder is complete. If it is complete then a call to \fI\%fy_document_builder_take_document()\fP will transfer ownership of the document to the caller. .SS Return .sp true if document complete, false otherwise .SS fy_document_builder_take_document .INDENT 0.0 .TP .B struct fy_document *fy_document_builder_take_document(struct fy_document_builder *fydb) Take ownership the document of a builder .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Take ownership of the document of a document builder. The document builder’s document must be complete. .SS Return .sp The document that the builder built, or NULL in case of an error .SS fy_document_builder_peek_document .INDENT 0.0 .TP .B struct fy_document *fy_document_builder_peek_document(struct fy_document_builder *fydb) Peek at the document of a builder .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Peek at the document of a document builder. Ownership still remains with the builder. .SS Return .sp A peek to the document that the builder built, or NULL in case of an error .SS fy_document_builder_set_in_stream .INDENT 0.0 .TP .B void fy_document_builder_set_in_stream(struct fy_document_builder *fydb) Set the builders state in ‘stream’ .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Set the document builders state to in ‘stream’ .SS fy_document_builder_set_in_document .INDENT 0.0 .TP .B 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’ .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The document state .IP \(bu 2 \fBsingle\fP (bool) – Single document mode .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Set the document builders state to in ‘document’ .SS Return .sp 0 on success, \-1 on error .SS fy_document_builder_load_document .INDENT 0.0 .TP .B struct fy_document *fy_document_builder_load_document(struct fy_document_builder *fydb, struct fy_parser *fyp) Create a document from parser events .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Load a document by pumping the parser for events and then processing them with the builder. .SS Return .sp The document that results from the parser, or NULL in case of an error (or EOF) .SS fy_parse_load_document_with_builder .INDENT 0.0 .TP .B struct fy_document *fy_parse_load_document_with_builder(struct fy_parser *fyp) Parse a document via built\-in builder .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Load a document by pumping the parser for events and then processing them with the in\-parser builder. .SS Return .sp The document that results from the parser, or NULL in case of an error (or EOF) .SS fy_document_builder_process_event .INDENT 0.0 .TP .B int fy_document_builder_process_event(struct fy_document_builder *fydb, struct \fI\%fy_event\fP *fye) Process an event with a builder .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfydb\fP (struct fy_document_builder*) – The document builder .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Pump an event to a document builder for processing. .SS Return .sp 0 on success, \-1 on error .SH COMPOSER .sp This header provides two complementary interfaces for processing YAML event streams with awareness of the current position in the document hierarchy, without committing to building a full in\-memory tree. .sp \fBSimple callback interface\fP — \fBfy_parse_compose()\fP calls a user function for each event, passing both the event and the current \fBstruct fy_path\fP so the callback can make intelligent decisions without maintaining its own path stack: .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_composer_return my_cb(struct fy_parser *fyp, struct fy_event *fye, struct fy_path *path, void *userdata) { if (fy_path_depth(path) > 3) return FYCR_OK_START_SKIP; process(fye); return FYCR_OK_CONTINUE; } fy_parse_compose(fyp, my_cb, ctx); .EE .UNINDENT .UNINDENT .sp \fBObject\-based interface\fP — \fBstruct fy_composer\fP wraps the same mechanism in a reusable object with ops callbacks, optional document builder integration, and helpers for navigating the path hierarchy. .sp \fBPath inspection helpers\fP — functions such as \fBfy_path_in_mapping()\fP, \fBfy_path_depth()\fP, \fBfy_path_component_is_sequence()\fP, and the user\-data attach/retrieve pairs let callbacks annotate and query the live path stack without any external bookkeeping. .sp Callbacks control event processing by returning one of: .INDENT 0.0 .IP \(bu 2 \fBFYCR_OK_CONTINUE\fP — consume the event and continue .IP \(bu 2 \fBFYCR_OK_STOP\fP — consume the event and stop .IP \(bu 2 \fBFYCR_OK_START_SKIP\fP — start skipping the current subtree .IP \(bu 2 \fBFYCR_OK_STOP_SKIP\fP — stop an active skip and resume processing .IP \(bu 2 \fBFYCR_ERROR\fP — abort with an error .UNINDENT .SS enum fy_composer_return .INDENT 0.0 .TP .B enum fy_composer_return The returns of the composer callback .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_composer_return { FYCR_OK_CONTINUE, FYCR_OK_STOP, FYCR_OK_START_SKIP, FYCR_OK_STOP_SKIP, FYCR_ERROR }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYCR_OK_CONTINUE continue processing, event processed .TP .B FYCR_OK_STOP stop processing, event processed .TP .B FYCR_OK_START_SKIP start skip object(s), event processed .TP .B FYCR_OK_STOP_SKIP stop skipping of objects, event processed .TP .B FYCR_ERROR error, stop processing .UNINDENT .SS fy_composer_return_is_ok .INDENT 0.0 .TP .B bool fy_composer_return_is_ok(enum \fI\%fy_composer_return\fP ret) Check if the return code is OK .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBret\fP (enum \fI\%fy_composer_return\fP) – the composer return to check .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convenience method for checking if it’s OK to continue .SS Return .sp true if non error or skip condition .SS typedef fy_parse_composer_cb .INDENT 0.0 .TP .B enum \fI\%fy_composer_return\fP fy_parse_composer_cb(struct fy_parser *fyp, struct \fI\%fy_event\fP *fye, struct fy_path *path, void *userdata) composer callback method .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event .IP \(bu 2 \fBpath\fP (struct fy_path*) – The path that the parser is processing .IP \(bu 2 \fBuserdata\fP (void*) – The user data of the \fI\%fy_parse_compose()\fP method .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This method is called by the \fI\%fy_parse_compose()\fP method when an event must be processed. .SS Return .sp fy_composer_return code telling the parser what to do .SS fy_parse_compose .INDENT 0.0 .TP .B int fy_parse_compose(struct fy_parser *fyp, \fI\%fy_parse_composer_cb\fP cb, void *userdata) Parse using a compose callback .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBcb\fP (\fI\%fy_parse_composer_cb\fP) – The callback that will be called .IP \(bu 2 \fBuserdata\fP (void*) – user pointer to pass to the callback .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Alternative parsing method using a composer callback. .sp The parser will construct a path argument that is used by the callback to make intelligent decisions about creating a document and/or DOM. .SS Return .sp 0 if no error occured \-1 on error .SS fy_path_component_is_mapping .INDENT 0.0 .TP .B bool fy_path_component_is_mapping(struct fy_path_component *fypc) Check if the component is a mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component to check .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the path component is a mapping, false otherwise .SS fy_path_component_is_sequence .INDENT 0.0 .TP .B bool fy_path_component_is_sequence(struct fy_path_component *fypc) Check if the component is a sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component to check .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the path component is a sequence, false otherwise .SS fy_path_component_sequence_get_index .INDENT 0.0 .TP .B int fy_path_component_sequence_get_index(struct fy_path_component *fypc) Get the index of sequence path component .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The sequence path component to return it’s index value .UNINDENT .UNINDENT .UNINDENT .SS Return .sp >= 0 the sequence index \-1 if the component is either not in the proper mode, or not a sequence .SS fy_path_component_mapping_get_scalar_key .INDENT 0.0 .TP .B struct fy_token *fy_path_component_mapping_get_scalar_key(struct fy_path_component *fypc) Get the scalar key of a mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The mapping path component to return it’s scalar key .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 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 .SS fy_path_component_mapping_get_scalar_key_tag .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The mapping path component to return it’s scalar key’s tag .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 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 .SS fy_path_component_mapping_get_complex_key .INDENT 0.0 .TP .B struct fy_document *fy_path_component_mapping_get_complex_key(struct fy_path_component *fypc) Get the complex key of a mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The mapping path component to return it’s complex key .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 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 .SS fy_path_component_get_text .INDENT 0.0 .TP .B char *fy_path_component_get_text(struct fy_path_component *fypc) Get the textual representation of a path component .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component to get it’s textual representation .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Given a path component, return a malloc’ed string which contains the textual representation of it. .sp Note that this method will only return fully completed components and not ones that are in the building process. .SS Return .sp 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. .SS fy_path_depth .INDENT 0.0 .TP .B int fy_path_depth(struct fy_path *fypp) Get the depth of a path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path to query .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The depth of the path, or \-1 on error .SS fy_path_parent .INDENT 0.0 .TP .B struct fy_path *fy_path_parent(struct fy_path *fypp) Get the parent of a path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path to return it’s parent .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Paths may contain parents when traversing complex keys. This method returns the immediate parent. .SS Return .sp The path parent or NULL on error, if it doesn’t exist .SS fy_path_get_text .INDENT 0.0 .TP .B char *fy_path_get_text(struct fy_path *fypp) Get the textual representation of a path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path to get it’s textual representation .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Given a path, return a malloc’ed string which contains the textual representation of it. .sp Note that during processing, complex key paths are simply indicative and not to be used for addressing. .SS Return .sp The textual representation of the path, NULL on error. The string must be free’ed using free. .SS fy_path_in_root .INDENT 0.0 .TP .B bool fy_path_in_root(struct fy_path *fypp) Check if the path is in the root of the document .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the path is located within the root of the document .SS fy_path_in_mapping .INDENT 0.0 .TP .B bool fy_path_in_mapping(struct fy_path *fypp) Check if the path is in a mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the path is located within a mapping .SS fy_path_in_sequence .INDENT 0.0 .TP .B bool fy_path_in_sequence(struct fy_path *fypp) Check if the path is in a sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the path is located within a sequence .SS fy_path_in_mapping_key .INDENT 0.0 .TP .B bool fy_path_in_mapping_key(struct fy_path *fypp) Check if the path is in a mapping key state .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the path is located within a mapping key state .SS fy_path_in_mapping_value .INDENT 0.0 .TP .B bool fy_path_in_mapping_value(struct fy_path *fypp) Check if the path is in a mapping value state .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the path is located within a mapping value state .SS fy_path_in_collection_root .INDENT 0.0 .TP .B bool fy_path_in_collection_root(struct fy_path *fypp) Check if the path is in a collection root .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp This occurs on MAPPING/SEQUENCE START/END events. .SS Return .sp true if the path is located within a collectin root state .SS fy_path_get_root_user_data .INDENT 0.0 .TP .B void *fy_path_get_root_user_data(struct fy_path *fypp) Return the userdata associated with the path root .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The user data associated with the root of the path, or NULL if no path .SS fy_path_set_root_user_data .INDENT 0.0 .TP .B void fy_path_set_root_user_data(struct fy_path *fypp, void *data) Set the user data associated with the root .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .IP \(bu 2 \fBdata\fP (void*) – The data to set as root data .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Note, no error condition if not a path .SS fy_path_component_get_mapping_user_data .INDENT 0.0 .TP .B void *fy_path_component_get_mapping_user_data(struct fy_path_component *fypc) Return the userdata associated with the mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The user data associated with the mapping, or NULL if not a mapping or the user data are NULL .SS fy_path_component_get_mapping_key_user_data .INDENT 0.0 .TP .B void *fy_path_component_get_mapping_key_user_data(struct fy_path_component *fypc) Return the userdata associated with the mapping key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The user data associated with the mapping key, or NULL if not a mapping or the user data are NULL .SS fy_path_component_get_sequence_user_data .INDENT 0.0 .TP .B void *fy_path_component_get_sequence_user_data(struct fy_path_component *fypc) Return the userdata associated with the sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The user data associated with the sequence, or NULL if not a sequence or the user data are NULL .SS fy_path_component_set_mapping_user_data .INDENT 0.0 .TP .B void fy_path_component_set_mapping_user_data(struct fy_path_component *fypc, void *data) Set the user data associated with a mapping .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component .IP \(bu 2 \fBdata\fP (void*) – The data to set as mapping data .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Note, no error condition if not a mapping .SS fy_path_component_set_mapping_key_user_data .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component .IP \(bu 2 \fBdata\fP (void*) – The data to set as mapping key data .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Note, no error condition if not in a mapping key state .SS fy_path_component_set_sequence_user_data .INDENT 0.0 .TP .B void fy_path_component_set_sequence_user_data(struct fy_path_component *fypc, void *data) Set the user data associated with a sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypc\fP (struct fy_path_component*) – The path component .IP \(bu 2 \fBdata\fP (void*) – The data to set as sequence data .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Note, no error condition if not a sequence .SS fy_path_get_parent_user_data .INDENT 0.0 .TP .B void *fy_path_get_parent_user_data(struct fy_path *path) Return the userdata of the parent collection .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The user data associated with the parent collection of the path, or NULL if no path .SS fy_path_set_parent_user_data .INDENT 0.0 .TP .B void fy_path_set_parent_user_data(struct fy_path *path, void *data) Set the user data associated with the parent collection .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (struct fy_path*) – The path .IP \(bu 2 \fBdata\fP (void*) – The data to set as parent collection data .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Note, no error condition if not a path .SS fy_path_get_last_user_data .INDENT 0.0 .TP .B void *fy_path_get_last_user_data(struct fy_path *path) Return the userdata of the last collection .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The user data associated with the last collection of the path, or NULL if no path .SS fy_path_set_last_user_data .INDENT 0.0 .TP .B void fy_path_set_last_user_data(struct fy_path *path, void *data) Set the user data associated with the last collection .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (struct fy_path*) – The path .IP \(bu 2 \fBdata\fP (void*) – The data to set as last collection data .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Note, no error condition if not a path .SS fy_path_last_component .INDENT 0.0 .TP .B struct fy_path_component *fy_path_last_component(struct fy_path *fypp) Get the very last component of a path .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns the last component of a path. .SS Return .sp The last path component (which may be a collection root component), or NULL if it does not exist .SS fy_path_last_not_collection_root_component .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The path .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns the last non collection root component of a path. This may not be the last component that is returned by \fI\%fy_path_last_component()\fP\&. .sp The difference is present on MAPPING/SEQUENCE START/END events where the last component is present but not usuable as a object parent. .SS Return .sp The last non collection root component, or NULL if it does not exist .SS struct fy_composer_ops .INDENT 0.0 .TP .B struct fy_composer_ops Composer operation callbacks .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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); } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B process_event Callback for processing a single YAML event with path context .TP .B create_document_builder Callback for creating a document builder instance .UNINDENT .SS Description .sp Callbacks used by the composer to process events and create document builders. .SS struct fy_composer_cfg .INDENT 0.0 .TP .B struct fy_composer_cfg Composer configuration structure .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_composer_cfg { const struct fy_composer_ops *ops; void *userdata; struct fy_diag *diag; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B ops Pointer to composer operation callbacks .TP .B userdata Opaque user data pointer passed to callbacks .TP .B diag Optional diagnostic interface to use, NULL for default .UNINDENT .SS Description .sp Configuration structure for creating a composer instance. .SS fy_composer_create .INDENT 0.0 .TP .B struct fy_composer *fy_composer_create(struct \fI\%fy_composer_cfg\fP *cfg) Create a composer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (struct \fI\%fy_composer_cfg\fP*) – The configuration for the composer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fI\%fy_composer_destroy()\fP\&. .SS Return .sp A pointer to the composer or NULL in case of an error. .SS fy_composer_destroy .INDENT 0.0 .TP .B void fy_composer_destroy(struct fy_composer *fyc) Destroy the given composer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyc\fP (struct fy_composer*) – The composer to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy a composer created earlier via \fI\%fy_composer_create()\fP\&. .SS fy_composer_process_event .INDENT 0.0 .TP .B enum \fI\%fy_composer_return\fP fy_composer_process_event(struct fy_composer *fyc, struct \fI\%fy_event\fP *fye) Process a YAML event through the composer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyc\fP (struct fy_composer*) – The composer .IP \(bu 2 \fBfye\fP (struct \fI\%fy_event\fP*) – The event to process .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp A fy_composer_return code indicating how to proceed (continue, stop, skip, or error) .SS fy_composer_get_cfg .INDENT 0.0 .TP .B struct \fI\%fy_composer_cfg\fP *fy_composer_get_cfg(struct fy_composer *fyc) Get the configuration of a composer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyc\fP (struct fy_composer*) – The composer .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The configuration of the composer .SS fy_composer_get_cfg_userdata .INDENT 0.0 .TP .B void *fy_composer_get_cfg_userdata(struct fy_composer *fyc) Get the userdata from composer configuration .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyc\fP (struct fy_composer*) – The composer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the opaque userdata pointer from the composer’s configuration. .SS Return .sp The userdata pointer from the configuration .SS fy_composer_get_diag .INDENT 0.0 .TP .B struct fy_diag *fy_composer_get_diag(struct fy_composer *fyc) Get the diagnostic object of a composer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyc\fP (struct fy_composer*) – The composer to get the diagnostic object .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Return a pointer to the diagnostic object of a composer object. Note that the returned diag object has a reference taken so you should \fI\%fy_diag_unref()\fP it when you’re done with it. .SS Return .sp A pointer to a ref’ed diagnostic object or NULL in case of an error. .SS fy_composer_get_path .INDENT 0.0 .TP .B struct fy_path *fy_composer_get_path(struct fy_composer *fyc) Get the current path of the composer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyc\fP (struct fy_composer*) – The composer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The current path, or NULL if no path is active .SS fy_composer_get_root_path .INDENT 0.0 .TP .B struct fy_path *fy_composer_get_root_path(struct fy_composer *fyc) Get the root path of the composer .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyc\fP (struct fy_composer*) – The composer .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Retrieve the root path of the composer’s path hierarchy. .SS Return .sp The root path, or NULL if no root exists .SS fy_composer_get_next_path .INDENT 0.0 .TP .B 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 .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyc\fP (struct fy_composer*) – The composer .IP \(bu 2 \fBfypp\fP (struct fy_path*) – The previous path, or NULL to get the first path .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Iterate through the composer’s path list. Pass NULL to get the first path, or pass the previous path to get the next one. .SS Return .sp The next path in the list, or NULL if no more paths exist .SH COPYRIGHT 2019-2026, Pantelis Antoniou .\" Generated by docutils manpage writer. .