/* * libfyaml-core.h - libfyaml core API * Copyright (c) 2019-2026 Pantelis Antoniou * SPDX-License-Identifier: MIT */ #ifndef LIBFYAML_CORE_H #define LIBFYAML_CORE_H #include #include #include #include #include #include #include #include /* pull in common definitions and platform abstraction macros */ #include #ifdef __cplusplus extern "C" { #endif /* opaque types for the user */ struct fy_token; struct fy_document_state; struct fy_parser; struct fy_emitter; struct fy_document; struct fy_node; struct fy_node_pair; struct fy_anchor; struct fy_node_mapping_sort_ctx; struct fy_token_iter; struct fy_diag; struct fy_parser_checkpoint; /** * DOC: libfyaml public API * * 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. * * **Three complementary APIs** cover the full lifecycle of a YAML document: * * *Event-based parsing* (``fy_parser_*``): A streaming interface similar to * libyaml's. The parser produces a sequence of typed events * (stream-start, document-start, scalar, sequence-start, …) without * building an in-memory tree. Ideal for large documents, filters, and * transcoding pipelines. * * *Document tree* (``fy_document_*``, ``fy_node_*``): Builds a fully * navigable in-memory tree from a YAML or JSON source. Nodes can be * queried, modified, merged, and serialised. Path-expression helpers * (``fy_document_scanf()``, ``fy_document_insert_at()``, …) provide * XPath-like access into the tree. * * *Emitter* (``fy_emitter_*``): Serialises documents or raw event streams * back to YAML or JSON with full control over formatting style, indentation, * and quoting. Supports streaming output to files, memory buffers, or * user-supplied callbacks. * * **Diagnostics** (``fy_diag_*``): A structured error-reporting subsystem * that attributes messages to precise source locations and integrates with * IDE/compiler toolchains via a standard ``file:line:col: level: text`` * format. * * All types are opaque pointers (``struct fy_parser *``, ``struct * fy_document *``, ``struct fy_node *``, …) so the ABI is stable across * minor releases. */ /** * struct fy_version - The YAML version * * @major: Major version number * @minor: Major version number * * The parser fills it according to the \%YAML directive * found in the document. */ struct fy_version { int major; int minor; }; /* Build a fy_version * from the given major and minor */ #define fy_version_make(_maj, _min) (&(struct fy_version){ (_maj), (_min) }) /** * fy_version_compare() - Compare two yaml versions * * Compare the versions * * @va: The first version, if NULL use default version * @vb: The second version, if NULL use default version * * Returns: * 0 if versions are equal, > 0 if version va is higher than vb * < 0 if version va is lower than vb */ int fy_version_compare(const struct fy_version *va, const struct fy_version *vb) FY_EXPORT; /** * fy_version_default() - Get the default version of the library * * Return the default version of the library, i.e. the highest * stable version that is supported. * * Returns: * The default YAML version of this library */ const struct fy_version * fy_version_default(void) FY_EXPORT; /** * fy_version_is_supported() - Check if supported version * * Check if the given YAML version is supported. * * @vers: The version to check, NULL means default version. * * Returns: * true if version supported, false otherwise. */ bool fy_version_is_supported(const struct fy_version *vers) FY_EXPORT; /** * fy_version_supported_iterate() - Iterate over the supported YAML versions * * This method iterates over the supported YAML versions of this ibrary. * The start of the iteration is signalled by a NULL in \*prevp. * * @prevp: The previous version iterator * * Returns: * The next node in sequence or NULL at the end of the sequence. */ const struct fy_version * fy_version_supported_iterate(void **prevp) FY_EXPORT; /** * fy_shutdown() - Final cleanup before exit * * Some libraries *cough*libclang** need explicit cleanup calls * at the end of program execution, even if you've never called * any of their functions. * * This method will make sure it calls their cleanup functions * so that no memory leaks are reported in valgrind etc. */ void fy_shutdown(void) FY_EXPORT; /** * struct fy_tag - The YAML tag structure. * * @handle: Handle of the tag (i.e. `"!!"`) * @prefix: The prefix of the tag (i.e. `"tag:yaml.org,2002:"`) * The parser fills it according to the \%TAG directives * encountered during parsing. */ struct fy_tag { const char *handle; const char *prefix; }; /** * struct fy_mark - marker holding information about a location * in a &struct fy_input * * @input_pos: Position of the mark (from the start of the current input) * @line: Line position (0 index based) * @column: Column position (0 index based) */ struct fy_mark { size_t input_pos; int line; int column; }; /** * enum fy_error_type - The supported diagnostic/error types * * @FYET_DEBUG: Debug level (disabled if library is not compiled in debug mode) * @FYET_INFO: Informational level * @FYET_NOTICE: Notice level * @FYET_WARNING: Warning level * @FYET_ERROR: Error level - error reporting is using this level * @FYET_MAX: Non inclusive maximum fy_error_type value * */ enum fy_error_type { FYET_DEBUG, FYET_INFO, FYET_NOTICE, FYET_WARNING, FYET_ERROR, FYET_MAX, }; /** * enum fy_error_module - Module which generated the diagnostic/error * * @FYEM_UNKNOWN: Unknown, default if not specific * @FYEM_ATOM: Atom module, used by atom chunking * @FYEM_SCAN: Scanner module * @FYEM_PARSE: Parser module * @FYEM_DOC: Document module * @FYEM_BUILD: Build document module (after tree is constructed) * @FYEM_INTERNAL: Internal error/diagnostic module * @FYEM_SYSTEM: System error/diagnostic module * @FYEM_EMIT: Emitter module * @FYEM_TYPESET: Prepare types module (C reflection) * @FYEM_DECODE: Decode, serialization -> internal form module * @FYEM_ENCODE: Encode, internal form -> serialized form module * @FYEM_REFLECTION: Generic reflection module messages * @FYEM_MAX: Non inclusive maximum fy_error_module value */ enum fy_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, }; /* Shift amount of the default version */ #define FYPCF_DEFAULT_VERSION_SHIFT 9 /* Mask of the default version */ #define FYPCF_DEFAULT_VERSION_MASK ((1U << 5) - 1) /* Build a default version */ #define FYPCF_DEFAULT_VERSION(x) (((unsigned int)(x) & FYPCF_DEFAULT_VERSION_MASK) << FYPCF_DEFAULT_VERSION_SHIFT) /* Shift amount of the JSON input mode */ #define FYPCF_JSON_SHIFT 16 /* Mask of the JSON input mode */ #define FYPCF_JSON_MASK ((1U << 2) - 1) /* Build a JSON input mode option */ #define FYPCF_JSON(x) (((unsigned int)(x) & FYPCF_JSON_MASK) << FYPCF_JSON_SHIFT) /* guaranteed minimum depth limit for generated document */ /* the actual limit is larger depending on the platform */ #define FYPCF_GUARANTEED_MINIMUM_DEPTH_LIMIT 64 /** * enum fy_parse_cfg_flags - Parse configuration flags * * These flags control the operation of the parse and the debugging * output/error reporting via filling in the &fy_parse_cfg->flags member. * * @FYPCF_QUIET: Quiet, do not output any information messages * @FYPCF_COLLECT_DIAG: Collect diagnostic/error messages * @FYPCF_RESOLVE_DOCUMENT: When producing documents, automatically resolve them * @FYPCF_DISABLE_MMAP_OPT: Disable mmap optimization * @FYPCF_DISABLE_RECYCLING: Disable recycling optimization * @FYPCF_PARSE_COMMENTS: Enable parsing of comments (experimental) * @FYPCF_DISABLE_DEPTH_LIMIT: Disable depth limit check, use with enlarged stack * @FYPCF_DISABLE_ACCELERATORS: Disable use of access accelerators (saves memory) * @FYPCF_DISABLE_BUFFERING: Disable use of buffering where possible * @FYPCF_DEFAULT_VERSION_AUTO: Automatically use the most recent version the library supports * @FYPCF_DEFAULT_VERSION_1_1: Default version is YAML 1.1 * @FYPCF_DEFAULT_VERSION_1_2: Default version is YAML 1.2 * @FYPCF_DEFAULT_VERSION_1_3: Default version is YAML 1.3 (experimental) * @FYPCF_SLOPPY_FLOW_INDENTATION: Allow sloppy indentation in flow mode * @FYPCF_PREFER_RECURSIVE: Prefer recursive algorighms instead of iterative whenever possible * @FYPCF_JSON_AUTO: Automatically enable JSON mode (when extension is .json) * @FYPCF_JSON_NONE: Never enable JSON input mode * @FYPCF_JSON_FORCE: Force JSON mode always * @FYPCF_YPATH_ALIASES: Enable YPATH aliases mode * @FYPCF_ALLOW_DUPLICATE_KEYS: Allow duplicate keys on mappings */ enum fy_parse_cfg_flags { FYPCF_QUIET = FY_BIT(0), FYPCF_COLLECT_DIAG = FY_BIT(1), FYPCF_RESOLVE_DOCUMENT = FY_BIT(2), FYPCF_DISABLE_MMAP_OPT = FY_BIT(3), FYPCF_DISABLE_RECYCLING = FY_BIT(4), FYPCF_PARSE_COMMENTS = FY_BIT(5), FYPCF_DISABLE_DEPTH_LIMIT = FY_BIT(6), FYPCF_DISABLE_ACCELERATORS = FY_BIT(7), FYPCF_DISABLE_BUFFERING = FY_BIT(8), FYPCF_DEFAULT_VERSION_AUTO = FYPCF_DEFAULT_VERSION(0), FYPCF_DEFAULT_VERSION_1_1 = FYPCF_DEFAULT_VERSION(1), FYPCF_DEFAULT_VERSION_1_2 = FYPCF_DEFAULT_VERSION(2), FYPCF_DEFAULT_VERSION_1_3 = FYPCF_DEFAULT_VERSION(3), FYPCF_SLOPPY_FLOW_INDENTATION = FY_BIT(14), FYPCF_PREFER_RECURSIVE = FY_BIT(15), FYPCF_JSON_AUTO = FYPCF_JSON(0), FYPCF_JSON_NONE = FYPCF_JSON(1), FYPCF_JSON_FORCE = FYPCF_JSON(2), FYPCF_YPATH_ALIASES = FY_BIT(18), FYPCF_ALLOW_DUPLICATE_KEYS = FY_BIT(19), }; #define FYPCF_DEFAULT_PARSE (0) #define FYPCF_DEFAULT_DOC (FYPCF_QUIET | FYPCF_DEFAULT_PARSE) /** * struct fy_parse_cfg - parser configuration structure. * * Argument to the fy_parser_create() method which * perform parsing of YAML files. * * @search_path: Search path when accessing files, seperate with ':' * @flags: Configuration flags * @userdata: Opaque user data pointer * @diag: Optional diagnostic interface to use */ struct fy_parse_cfg { const char *search_path; enum fy_parse_cfg_flags flags; void *userdata; struct fy_diag *diag; }; /** * enum fy_event_type - Event types * * @FYET_NONE: No event * @FYET_STREAM_START: Stream start event * @FYET_STREAM_END: Stream end event * @FYET_DOCUMENT_START: Document start event * @FYET_DOCUMENT_END: Document end event * @FYET_MAPPING_START: YAML mapping start event * @FYET_MAPPING_END: YAML mapping end event * @FYET_SEQUENCE_START: YAML sequence start event * @FYET_SEQUENCE_END: YAML sequence end event * @FYET_SCALAR: YAML scalar event * @FYET_ALIAS: YAML alias event */ 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, }; /** * fy_event_type_get_text() - Return text of an event type * * @type: The event type to get text from * * Returns: * A pointer to a text, i.e for FYET_SCALAR "=VAL". */ const char * fy_event_type_get_text(enum fy_event_type type) FY_EXPORT; /** * enum fy_collection_style - Collection styles supported by the parser/emitter * * @FYCS_ANY: Any collection style, not generated by the parser. * Lets the emitter to choose * @FYCS_BLOCK: Block style (not {}[]) * @FYCS_FLOW: Flow style {}[] * @FYCS_MAX: marks end of scalar styles */ enum fy_collection_style { FYCS_ANY = -1, FYCS_BLOCK, FYCS_FLOW, FYCS_MAX, }; /** * enum fy_scalar_style - Scalar styles supported by the parser/emitter * * @FYSS_ANY: Any scalar style, not generated by the parser. * Lets the emitter to choose * @FYSS_PLAIN: Plain scalar style * @FYSS_SINGLE_QUOTED: Single quoted style * @FYSS_DOUBLE_QUOTED: Double quoted style * @FYSS_LITERAL: YAML literal block style * @FYSS_FOLDED: YAML folded block style * @FYSS_MAX: marks end of scalar styles */ enum fy_scalar_style { FYSS_ANY = -1, FYSS_PLAIN, FYSS_SINGLE_QUOTED, FYSS_DOUBLE_QUOTED, FYSS_LITERAL, FYSS_FOLDED, FYSS_MAX, }; /** * struct fy_event_stream_start_data - stream start event data * * @stream_start: The token that started the stream */ struct fy_event_stream_start_data { struct fy_token *stream_start; }; /** * struct fy_event_stream_end_data - stream end event data * * @stream_end: The token that ended the stream */ struct fy_event_stream_end_data { struct fy_token *stream_end; }; /** * struct fy_event_document_start_data - doument start event data * * @document_start: The token that started the document, or NULL if * the document was implicitly started. * @document_state: The state of the document (i.e. information about * the YAML version and configured tags) * @implicit: True if the document started implicitly */ struct fy_event_document_start_data { struct fy_token *document_start; struct fy_document_state *document_state; bool implicit; }; /** * struct fy_event_document_end_data - doument end event data * * @document_end: The token that ended the document, or NULL if the * document was implicitly ended * @implicit: True if the document ended implicitly */ struct fy_event_document_end_data { struct fy_token *document_end; bool implicit; }; /** * struct fy_event_alias_data - alias event data * * @anchor: The anchor token definining this alias. */ struct fy_event_alias_data { struct fy_token *anchor; }; /** * struct fy_event_scalar_data - scalar event data * * @anchor: anchor token or NULL * @tag: tag token or NULL * @value: scalar value token (cannot be NULL) * @tag_implicit: true if the tag was implicit or explicit */ struct fy_event_scalar_data { struct fy_token *anchor; struct fy_token *tag; struct fy_token *value; bool tag_implicit; }; /** * struct fy_event_sequence_start_data - sequence start event data * * @anchor: anchor token or NULL * @tag: tag token or NULL * @sequence_start: sequence start value token or NULL if the sequence * was started implicitly */ struct fy_event_sequence_start_data { struct fy_token *anchor; struct fy_token *tag; struct fy_token *sequence_start; }; /** * struct fy_event_sequence_end_data - sequence end event data * * @sequence_end: The token that ended the sequence, or NULL if * the sequence was implicitly ended */ struct fy_event_sequence_end_data { struct fy_token *sequence_end; }; /** * struct fy_event_mapping_start_data - mapping start event data * * @anchor: anchor token or NULL * @tag: tag token or NULL * @mapping_start: mapping start value token or NULL if the mapping * was started implicitly */ struct fy_event_mapping_start_data { struct fy_token *anchor; struct fy_token *tag; struct fy_token *mapping_start; }; /** * struct fy_event_mapping_end_data - mapping end event data * * @mapping_end: The token that ended the mapping, or NULL if * the mapping was implicitly ended */ struct fy_event_mapping_end_data { struct fy_token *mapping_end; }; /** * struct fy_event - Event generated by the parser * * This structure is generated by the parser by each call * to fy_parser_parse() and release by fy_parser_event_free() * * @type: Type of the event, see &enum fy_event_type * * @stream_start: Stream start information, it is valid when * &fy_event->type is &enum FYET_STREAM_START * @stream_end: Stream end information, it is valid when * &fy_event->type is &enum FYET_STREAM_END * @document_start: Document start information, it is valid when * &fy_event->type is &enum FYET_DOCUMENT_START * @document_end: Document end information, it is valid when * &fy_event->type is &enum FYET_DOCUMENT_END * @alias: Alias information, it is valid when * &fy_event->type is &enum FYET_ALIAS * @scalar: Scalar information, it is valid when * &fy_event->type is &enum FYET_SCALAR * @sequence_start: Sequence start information, it is valid when * &fy_event->type is &enum FYET_SEQUENCE_START * @sequence_end: Sequence end information, it is valid when * &fy_event->type is &enum FYET_SEQUENCE_END * @mapping_start: Mapping start information, it is valid when * &fy_event->type is &enum FYET_MAPPING_START * @mapping_end: Mapping end information, it is valid when * &fy_event->type is &enum FYET_MAPPING_END */ struct fy_event { enum fy_event_type type; /* anonymous union */ 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; }; }; /** * enum fy_event_part - Select part of the event * * @FYEP_VALUE: The value of the event (the main token) * @FYEP_TAG: The tag of the event * @FYEP_ANCHOR: The anchor of the event */ enum fy_event_part { FYEP_VALUE, FYEP_TAG, FYEP_ANCHOR, }; /** * fy_event_get_type() - Get the event's type * * Return the type of the event * * @fye: The event * * Returns: * The event type, or FYET_NONE when the event is invalid */ static inline enum fy_event_type fy_event_get_type(const struct fy_event *fye) { return fye ? fye->type : FYET_NONE; } /** * fy_event_data() - Get a pointer to the event data * * Some languages *cough*golang*cough* really don't like * unions, and anonymous unions in particular. * * You should not have to use this in other language bindings. * * @fye: The event * * Returns: * A pointer to the event data structure, or NULL if the * event is invalid */ static inline void * fy_event_data(struct fy_event *fye) { if (!fye) return NULL; /* note that the unions should all be laid out * at the same address, but play it straight and * hope the optimizer will figure this is all * the same... */ switch (fye->type) { case FYET_STREAM_START: return &fye->stream_start; case FYET_STREAM_END: return &fye->stream_end; case FYET_DOCUMENT_START: return &fye->document_start; case FYET_DOCUMENT_END: return &fye->document_end; case FYET_ALIAS: return &fye->alias; case FYET_SCALAR: return &fye->scalar; case FYET_SEQUENCE_START: return &fye->sequence_start; case FYET_SEQUENCE_END: return &fye->sequence_end; case FYET_MAPPING_START: return &fye->mapping_start; case FYET_MAPPING_END: return &fye->mapping_end; default: break; } return NULL; } /** * fy_library_version() - Return the library version string * * Returns: * A pointer to a version string of the form * .[[.][-EXTRA-VERSION-INFO]] */ const char * fy_library_version(void) FY_EXPORT; /** * fy_string_to_error_type() - Return the error type from a string * * @str: The string to convert to an error type * * Returns: * The error type if greater or equal to zero, FYET_MAX otherwise */ enum fy_error_type fy_string_to_error_type(const char *str) FY_EXPORT; /** * fy_error_type_to_string() - Convert an error type to string * * @type: The error type to convert * * Returns: * The string value of the error type or the empty string "" on error */ const char *fy_error_type_to_string(enum fy_error_type type) FY_EXPORT; /** * fy_string_to_error_module() - Return the error module from a string * * @str: The string to convert to an error module * * Returns: * The error type if greater or equal to zero, FYEM_MAX otherwise */ enum fy_error_module fy_string_to_error_module(const char *str) FY_EXPORT; /** * fy_error_module_to_string() - Convert an error module to string * * @module: The error module to convert * * Returns: * The string value of the error module or the empty string "" on error */ const char *fy_error_module_to_string(enum fy_error_module module) FY_EXPORT; /** * fy_event_is_implicit() - Check whether the given event is an implicit one * * @fye: A pointer to a &struct fy_event to check. * * Returns: * true if the event is an implicit one. */ bool fy_event_is_implicit(struct fy_event *fye) FY_EXPORT; /** * fy_document_event_is_implicit() - Check whether the given document event is an implicit one * * @fye: A pointer to a &struct fy_event to check. * It must be either a document start or document end event. * * Returns: * true if the event is an implicit one. */ bool fy_document_event_is_implicit(const struct fy_event *fye) FY_EXPORT; /** * fy_parser_create() - Create a parser. * * Creates a parser with its configuration @cfg * The parser may be destroyed by a corresponding call to * fy_parser_destroy(). * * @cfg: The configuration for the parser * * Returns: * A pointer to the parser or NULL in case of an error. */ struct fy_parser * fy_parser_create(const struct fy_parse_cfg *cfg) FY_EXPORT; /** * fy_parser_destroy() - Destroy the given parser * * Destroy a parser created earlier via fy_parser_create(). * * @fyp: The parser to destroy */ void fy_parser_destroy(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_get_cfg() - Get the configuration of a parser * * @fyp: The parser * * Returns: * The configuration of the parser */ const struct fy_parse_cfg * fy_parser_get_cfg(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_get_diag() - Get the diagnostic object of a parser * * Return a pointer to the diagnostic object of a parser object. * Note that the returned diag object has a reference taken so * you should fy_diag_unref() it when you're done with it. * * @fyp: The parser to get the diagnostic object * * Returns: * A pointer to a ref'ed diagnostic object or NULL in case of an * error. */ struct fy_diag * fy_parser_get_diag(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_set_diag() - Set the diagnostic object of a parser * * 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. * * @fyp: The parser to replace the diagnostic object * @diag: The parser's new diagnostic object, NULL for default * * Returns: * 0 if everything OK, -1 otherwise */ int fy_parser_set_diag(struct fy_parser *fyp, struct fy_diag *diag) FY_EXPORT; /** * fy_parser_reset() - Reset a parser completely * * Completely reset a parser, including after an error * that caused a parser error to be emitted. * * @fyp: The parser to reset * * Returns: * 0 if the reset was successful, -1 otherwise */ int fy_parser_reset(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_set_input_file() - Set the parser to process the given file * * Point the parser to the given @file for processing. The file * is located by honoring the search path of the configuration set * by the earlier call to fy_parser_create(). * While the parser is in use the file will must be available. * * @fyp: The parser * @file: The file to parse. * * Returns: * zero on success, -1 on error */ int fy_parser_set_input_file(struct fy_parser *fyp, const char *file) FY_EXPORT; /** * fy_parser_set_string() - Set the parser to process the given string. * * Point the parser to the given (NULL terminated) string. Note that * while the parser is active the string must not go out of scope. * * @fyp: The parser * @str: The YAML string to parse. * @len: The length of the string (or -1 if '\0' terminated) * * Returns: * zero on success, -1 on error */ int fy_parser_set_string(struct fy_parser *fyp, const char *str, size_t len) FY_EXPORT; /** * fy_parser_set_malloc_string() - Set the parser to process the given malloced string. * * Point the parser to the given (possible NULL terminated) string. Note that * the string is expected to be allocated via malloc(3) and ownership is transferred * to the created input. When the input is free'ed the memory will be automatically * freed. * * In case of an error the string is not freed. * * @fyp: The parser * @str: The YAML string to parse (allocated). * @len: The length of the string (or -1 if '\0' terminated) * * Returns: * zero on success, -1 on error */ int fy_parser_set_malloc_string(struct fy_parser *fyp, char *str, size_t len) FY_EXPORT; /** * fy_parser_set_input_fp() - Set the parser to process the given file * * Point the parser to use @fp for processing. * * @fyp: The parser * @name: The label of the stream * @fp: The FILE pointer, it must be open in read mode. * * Returns: * zero on success, -1 on error */ int fy_parser_set_input_fp(struct fy_parser *fyp, const char *name, FILE *fp) FY_EXPORT; /** * fy_parser_set_input_callback() - Set the parser to process via a callback * * Point the parser to use a callback for input. * * @fyp: The parser * @user: The user data pointer * @callback: The callback method to request data with * * Returns: * zero on success, -1 on error */ int fy_parser_set_input_callback(struct fy_parser *fyp, void *user, ssize_t (*callback)(void *user, void *buf, size_t count)) FY_EXPORT; /** * fy_parser_set_input_fd() - Set the parser to process the given file descriptor * * Point the parser to use @fd for processing. * * @fyp: The parser * @fd: The file descriptor to use * * Returns: * zero on success, -1 on error */ int fy_parser_set_input_fd(struct fy_parser *fyp, int fd) FY_EXPORT; /** * fy_parser_parse() - Parse and return the next event. * * Each call to fy_parser_parse() returns the next event from * the configured input of the parser, or NULL at the end of * the stream. The returned event must be released via * a matching call to fy_parser_event_free(). * * @fyp: The parser * * Returns: * The next event in the stream or NULL. */ struct fy_event * fy_parser_parse(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_parse_peek() - Parse and peek at the next event. * * It will return the next event that a call to fy_parser_parse * would generate, but as read-only. * * You must not free this event. * * @fyp: The parser * * Returns: * A peek at the next event in the stream or NULL. */ const struct fy_event * fy_parser_parse_peek(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_skip() - Skip the current scalar/collection * * Skips the current scalar or collection. * * @fyp: The parser * * Returns: * 0 on success, -1 on error */ int fy_parser_skip(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_count_sequence_items() - Count the sequence items * * 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. * * @fyp: The parser * * Returns: * The number of sequence items on success, -1 on error * Note if the number of items exceeds INT_MAX, INT_MAX will * be returned. */ int fy_parser_count_sequence_items(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_count_mapping_items() - Count the mapping items * * 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. * * @fyp: The parser * * Returns: * The number of mapping items on success, -1 on error * Note if the number of items exceeds INT_MAX, INT_MAX will * be returned. */ int fy_parser_count_mapping_items(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_event_free() - Free an event * * Free a previously returned event from fy_parser_parse(). * * @fyp: The parser * @fye: The event to free (may be NULL) */ void fy_parser_event_free(struct fy_parser *fyp, struct fy_event *fye) FY_EXPORT; /** * fy_parser_get_stream_error() - Check the parser for stream errors * * @fyp: The parser * * Returns: * true in case of a stream error, false otherwise. */ bool fy_parser_get_stream_error(struct fy_parser *fyp) FY_EXPORT; enum fy_parser_mode { fypm_invalid = -1, fypm_none, /* scanning for mode, not committed yet */ fypm_yaml_1_1, fypm_yaml_1_2, fypm_yaml_1_3, /* experimental */ fypm_json, }; static inline bool fy_parser_mode_is_yaml(enum fy_parser_mode mode) { return mode >= fypm_yaml_1_1 && mode <= fypm_yaml_1_3; } /** * fy_parser_get_mode() - Get the parser mode * * 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). * * @fyp: The parser * * Returns: * The parser mode */ enum fy_parser_mode fy_parser_get_mode(struct fy_parser *fyp) FY_EXPORT; static inline bool fy_parser_is_in_yaml_mode(struct fy_parser *fyp) { return fy_parser_mode_is_yaml(fy_parser_get_mode(fyp)); } static inline bool fy_parser_is_in_json_mode(struct fy_parser *fyp) { return fy_parser_get_mode(fyp) == fypm_json; } /** * fy_parser_vlog() - Log using the parsers diagnostics printf style (va_arg) * * Output a log on the parser diagnostic output * * @fyp: The parser * @type: The error type * @fmt: The printf format string * @ap: The argument list */ void fy_parser_vlog(struct fy_parser *fyp, enum fy_error_type type, const char *fmt, va_list ap) FY_EXPORT; /** * fy_parser_log() - Log using the parsers diagnostics printf style * * Output a report on the parser's diagnostics * * @fyp: The parser * @type: The error type * @fmt: The printf format string * @...: The extra arguments */ void fy_parser_log(struct fy_parser *fyp, enum fy_error_type type, const char *fmt, ...) FY_FORMAT(printf, 3, 4) FY_EXPORT; #ifndef NDEBUG #define fy_parser_debug(_fyp, _fmt, ...) \ fy_parser_log((_fyp), FYET_DEBUG, (_fmt) , ## __VA_ARGS__) #else #define fy_parser_debug(_fyp, _fmt, ...) \ do { } while(0) #endif #define fy_parser_info(_fyp, _fmt, ...) \ fy_parser_log((_fyp), FYET_INFO, (_fmt) , ## __VA_ARGS__) #define fy_parser_notice(_fyp, _fmt, ...) \ fy_parser_log((_fyp), FYET_NOTICE, (_fmt) , ## __VA_ARGS__) #define fy_parser_warning(_fyp, _fmt, ...) \ fy_parser_log((_fyp), FYET_WARNING, (_fmt) , ## __VA_ARGS__) #define fy_parser_error(_fyp, _fmt, ...) \ fy_parser_log((_fyp), FYET_ERROR, (_fmt) , ## __VA_ARGS__) /** * fy_parser_vreport() - Report using the parsers diagnostics printf style and mark token (va_arg) * * Output a report on the parser and indicate the token's position * * @fyp: The parser * @type: The error type * @fyt: The token * @fmt: The printf format string * @ap: The argument list */ void fy_parser_vreport(struct fy_parser *fyp, enum fy_error_type type, struct fy_token *fyt, const char *fmt, va_list ap) FY_EXPORT; /** * fy_parser_report() - Report using the parsers diagnostics printf style and mark token * * Output a report on the parser and indicate the token's position * * @fyp: The parser * @type: The error type * @fyt: The token * @fmt: The printf format string * @...: The extra arguments */ void fy_parser_report(struct fy_parser *fyp, enum fy_error_type type, struct fy_token *fyt, const char *fmt, ...) FY_FORMAT(printf, 4, 5) FY_EXPORT; #ifndef NDEBUG #define fy_parser_report_debug(_fyp, _fyt, _fmt, ...) \ fy_parser_report((_fyp), FYET_DEBUG, (_fyt), (_fmt) , ## __VA_ARGS__) #else #define fy_parser_report_debug(_fyp, _fyt, _fmt, ...) \ do { } while(0) #endif #define fy_parser_report_info(_fyp, _fyt, _fmt, ...) \ fy_parser_report((_fyp), FYET_INFO, (_fyt), (_fmt) , ## __VA_ARGS__) #define fy_parser_report_notice(_fyp, _fyt, _fmt, ...) \ fy_parser_report((_fyp), FYET_NOTICE, (_fyt), (_fmt) , ## __VA_ARGS__) #define fy_parser_report_warning(_fyp, _fyt, _fmt, ...) \ fy_parser_report((_fyp), FYET_WARNING, (_fyt), (_fmt) , ## __VA_ARGS__) #define fy_parser_report_error(_fyp, _fyt, _fmt, ...) \ fy_parser_report((_fyp), FYET_ERROR, (_fyt), (_fmt) , ## __VA_ARGS__) /** * fy_token_scalar_style() - Get the style of a scalar token * * @fyt: The scalar token to get it's style. Note that a NULL * token is a &enum FYSS_PLAIN. * * Returns: * The scalar style of the token, or FYSS_PLAIN on each other case */ enum fy_scalar_style fy_token_scalar_style(struct fy_token *fyt) FY_EXPORT; /** * fy_token_collection_style() - Get the style of a collection token * * @fyt: The collection token to get it's style. Note that a NULL * token is a &enum FYCS_ANY. * * Returns: * The collection style of the token, or FYCS_ANY */ enum fy_collection_style fy_token_collection_style(struct fy_token *fyt) FY_EXPORT; /** * fy_token_scalar_is_null() - Test whether the scalar is null (content) * * @fyt: The scalar token to check for NULLity. * * 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. * * Returns: * true if is a null scalar, false otherwise */ bool fy_token_scalar_is_null(struct fy_token *fyt) FY_EXPORT; /** * fy_token_get_text() - Get text (and length of it) of a token * * This method will return a pointer to the text of a token * along with the length of it. Note that this text is *not* * NULL terminated. If you need a NULL terminated pointer * use fy_token_get_text0(). * * In case that the token is 'simple' enough (i.e. a plain scalar) * or something similar the returned pointer is a direct pointer * to the space of the input that contains the token. * * That means that the pointer is *not* guaranteed to be valid * after the parser is destroyed. * * If the token is 'complex' enough, then space shall be allocated, * filled and returned. * * Note that the concept of 'simple' and 'complex' is vague, and * that's on purpose. * * @fyt: The token out of which the text pointer will be returned. * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the text representation of the token, while * @lenp will be assigned the character length of said representation. * NULL in case of an error. */ const char * fy_token_get_text(struct fy_token *fyt, size_t *lenp) FY_EXPORT; /** * fy_token_get_text0() - Get zero terminated text of a token * * This method will return a pointer to the text of a token * which is zero terminated. It will allocate memory to hold * it in the token structure so try to use fy_token_get_text() * instead if possible. * * @fyt: The token out of which the text pointer will be returned. * * Returns: * A pointer to a zero terminated text representation of the token. * NULL in case of an error. */ const char * fy_token_get_text0(struct fy_token *fyt) FY_EXPORT; /** * fy_token_get_text_length() - Get length of the text of a token * * This method will return the length of the text representation * of a token. * * @fyt: The token * * Returns: * 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. */ size_t fy_token_get_text_length(struct fy_token *fyt) FY_EXPORT; /** * enum fy_comment_placement - Comment placement relative to token * * @fycp_top: Comment on top of token * @fycp_right: Comment to the right of the token * @fycp_bottom: Comment to the bottom of the token */ enum fy_comment_placement { fycp_top, fycp_right, fycp_bottom }; #define fycp_max (fycp_bottom + 1) /** * fy_token_get_comment() - Get zero terminated comment of a token * * Get the comment that is attached at a token having the given * placement. * * @fyt: The token out of which the comment text will be returned. * @which: The comment placement * * Returns: * 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. */ const char * fy_token_get_comment(struct fy_token *fyt, enum fy_comment_placement which) FY_EXPORT; /** * fy_token_get_comments() - Get all comments of a token * * Get all the comments that are attached on a token * * @fyt: The token * * Returns: * 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. */ const char * fy_token_get_comments(struct fy_token *fyt) FY_EXPORT; /** * fy_token_set_comment() - Attach a comment to a token * * 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. * * @fyt: The token out of which the comment text will be attached * @which: The placement * @text: The text of the comment * @len: The length of the comment (FY_NT means the length of text) * * Returns: * 0 on success, -1 on failure. */ int fy_token_set_comment(struct fy_token *fyt, enum fy_comment_placement which, const char *text, size_t len) FY_EXPORT; /** * fy_event_get_comments() - Get all comments of an event * * @fye: The event * * Returns: * 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 free() */ const char * fy_event_get_comments(struct fy_event *fye) FY_EXPORT; /** * fy_node_get_comment() - Get comment of a node * * @fyn: The node * @which: The placement of the comment * * Returns: * 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. */ const char * fy_node_get_comment(struct fy_node *fyn, enum fy_comment_placement which) FY_EXPORT; /** * fy_node_get_comments() - Get all comments of a node * * @fyn: The node * * Returns: * 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. */ const char * fy_node_get_comments(struct fy_node *fyn) FY_EXPORT; /** * struct fy_iter_chunk - An iteration chunk * * @str: Pointer to the start of the chunk * @len: The size of the chunk * * The iterator produces a stream of chunks which * cover the whole object. */ struct fy_iter_chunk { const char *str; size_t len; }; /** * fy_token_iter_create() - Create a token iterator * * Create an iterator for operating on the given token, or * a generic iterator for use with fy_token_iter_start(). * The iterator must be destroyed with a matching call to * fy_token_iter_destroy(). * * @fyt: The token to iterate, or NULL. * * Returns: * A pointer to the newly created iterator, or NULL in case of * an error. */ struct fy_token_iter * fy_token_iter_create(struct fy_token *fyt) FY_EXPORT; /** * fy_token_iter_destroy() - Destroy the iterator * * Destroy the iterator created by fy_token_iter_create(). * * @iter: The iterator to destroy. */ void fy_token_iter_destroy(struct fy_token_iter *iter) FY_EXPORT; /** * fy_token_iter_start() - Start iterating over the contents of a token * * Prepare an iterator for operating on the given token. * The iterator must be created via a previous call to fy_token_iter_create() * for user level API access. * * @fyt: The token to iterate over * @iter: The iterator to prepare. */ void fy_token_iter_start(struct fy_token *fyt, struct fy_token_iter *iter) FY_EXPORT; /** * fy_token_iter_finish() - Stop iterating over the contents of a token * * Stop the iteration operation. * * @iter: The iterator. */ void fy_token_iter_finish(struct fy_token_iter *iter) FY_EXPORT; /** * fy_token_iter_peek_chunk() - Peek at the next iterator chunk * * Peek at the next iterator chunk * * @iter: The iterator. * * Returns: * A pointer to the next iterator chunk, or NULL in case there's * no other. */ const struct fy_iter_chunk * fy_token_iter_peek_chunk(struct fy_token_iter *iter) FY_EXPORT; /** * fy_token_iter_chunk_next() - Get next iterator chunk * * Get the next iterator chunk in sequence, * * @iter: The iterator. * @curr: The current chunk, or NULL for the first one. * @errp: Pointer to an error return value or NULL * * Returns: * 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. */ const struct fy_iter_chunk * fy_token_iter_chunk_next(struct fy_token_iter *iter, const struct fy_iter_chunk *curr, int *errp) FY_EXPORT; /** * fy_token_iter_advance() - Advance the iterator position * * Advance the read pointer of the iterator. * Note that mixing calls of this with any call of fy_token_iter_ungetc() / * fy_token_iter_utf8_unget() in a single iterator sequence leads * to undefined behavior. * * @iter: The iterator. * @len: Number of bytes to advance the iterator position */ void fy_token_iter_advance(struct fy_token_iter *iter, size_t len) FY_EXPORT; /** * fy_token_iter_read() - Read a block from an iterator * * Read a block from an iterator. Note than mixing calls of this * and any of the ungetc methods leads to undefined behavior. * * @iter: The iterator. * @buf: Pointer to a block of memory to receive the data. Must be at * least count bytes long. * @count: Amount of bytes to read. * * Returns: * The amount of data read, or -1 in case of an error. */ ssize_t fy_token_iter_read(struct fy_token_iter *iter, void *buf, size_t count) FY_EXPORT; /** * fy_token_iter_getc() - Get a single character from an iterator * * 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. * * @iter: The iterator. * * Returns: * The next character in the iterator, or -1 in case of an error, or * end of stream. */ int fy_token_iter_getc(struct fy_token_iter *iter) FY_EXPORT; /** * fy_token_iter_ungetc() - Ungets a single character from an iterator * * Pushes back a single character to an iterator stream. It will be * returned in subsequent calls of fy_token_iter_getc(). Currently * only a single character is allowed to be pushed back, and any * further calls to ungetc will return an error. * * @iter: The iterator. * @c: The character to push back, or -1 to reset the pushback buffer. * * Returns: * 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. */ int fy_token_iter_ungetc(struct fy_token_iter *iter, int c) FY_EXPORT; /** * fy_token_iter_peekc() - Peeks at single character from an iterator * * 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. * * @iter: The iterator. * * Returns: * The next character in the iterator, or -1 in case of an error, or end * of stream. */ int fy_token_iter_peekc(struct fy_token_iter *iter) FY_EXPORT; /** * fy_token_iter_utf8_get() - Get a single utf8 character from an iterator * * 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. * * @iter: The iterator. * * Returns: * The next utf8 character in the iterator, or -1 in case of an error, or end * of stream. */ int fy_token_iter_utf8_get(struct fy_token_iter *iter) FY_EXPORT; /** * fy_token_iter_utf8_unget() - Ungets a single utf8 character from an iterator * * Pushes back a single utf8 character to an iterator stream. It will be * returned in subsequent calls of fy_token_iter_utf8_getc(). Currently * only a single character is allowed to be pushed back, and any * further calls to ungetc will return an error. * * @iter: The iterator. * @c: The character to push back, or -1 to reset the pushback buffer. * * Returns: * 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. */ int fy_token_iter_utf8_unget(struct fy_token_iter *iter, int c) FY_EXPORT; /** * fy_token_iter_utf8_peek() - Peeks at single utf8 character from an iterator * * 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. * * @iter: The iterator. * * Returns: * The next utf8 character in the iterator, or -1 in case of an error, or end * of stream. */ int fy_token_iter_utf8_peek(struct fy_token_iter *iter) FY_EXPORT; /** * fy_parse_load_document() - Parse the next document from the parser stream * * 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. * * @fyp: The parser * * Returns: * The next document from the parser stream. */ struct fy_document * fy_parse_load_document(struct fy_parser *fyp) FY_EXPORT; /** * fy_parse_document_destroy() - Destroy a document created by fy_parse_load_document() * * @fyp: The parser * @fyd: The document to destroy */ void fy_parse_document_destroy(struct fy_parser *fyp, struct fy_document *fyd) FY_EXPORT; /** * fy_document_resolve() - Resolve anchors and merge keys * * This method performs resolution of the given document, * by replacing references to anchors with their contents * and handling merge keys (<<) * * @fyd: The document to resolve * * Returns: * zero on success, -1 on error */ int fy_document_resolve(struct fy_document *fyd) FY_EXPORT; /** * fy_document_has_directives() - Document directive check * * Checks whether the given document has any directives, i.e. * %TAG or %VERSION. * * @fyd: The document to check for directives existence * * Returns: * true if directives exist, false if not */ bool fy_document_has_directives(const struct fy_document *fyd) FY_EXPORT; /** * fy_document_has_explicit_document_start() - Explicit document start check * * Checks whether the given document has an explicit document start marker, * i.e. --- * * @fyd: The document to check for explicit start marker * * Returns: * true if document has an explicit document start marker, false if not */ bool fy_document_has_explicit_document_start(const struct fy_document *fyd) FY_EXPORT; /** * fy_document_has_explicit_document_end() - Explicit document end check * * Checks whether the given document has an explicit document end marker, * i.e. ... * * @fyd: The document to check for explicit end marker * * Returns: * true if document has an explicit document end marker, false if not */ bool fy_document_has_explicit_document_end(const struct fy_document *fyd) FY_EXPORT; /** * fy_node_document() - Retreive the document the node belong to * * 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. * * @fyn: The node to retreive it's document * * Returns: * The document of the node, or NULL in case of an error, or * when the node has no document attached. */ struct fy_document * fy_node_document(struct fy_node *fyn) FY_EXPORT; /** * enum fy_emitter_write_type - Type of the emitted output * * Describes the kind of emitted output, which makes it * possible to colorize the output, or do some other content related * filtering. * * @fyewt_document_indicator: Output chunk is a document indicator * @fyewt_tag_directive: Output chunk is a tag directive * @fyewt_version_directive: Output chunk is a version directive * @fyewt_indent: Output chunk is a document indicator * @fyewt_indicator: Output chunk is an indicator * @fyewt_whitespace: Output chunk is white space * @fyewt_plain_scalar: Output chunk is a plain scalar * @fyewt_single_quoted_scalar: Output chunk is a single quoted scalar * @fyewt_double_quoted_scalar: Output chunk is a double quoted scalar * @fyewt_literal_scalar: Output chunk is a literal block scalar * @fyewt_folded_scalar: Output chunk is a folded block scalar * @fyewt_anchor: Output chunk is an anchor * @fyewt_tag: Output chunk is a tag * @fyewt_linebreak: Output chunk is a linebreak * @fyewt_alias: Output chunk is an alias * @fyewt_terminating_zero: Output chunk is a terminating zero * @fyewt_plain_scalar_key: Output chunk is an plain scalar key * @fyewt_single_quoted_scalar_key: Output chunk is an single quoted scalar key * @fyewt_double_quoted_scalar_key: Output chunk is an double quoted scalar key * @fyewt_comment: Output chunk is a comment * @fyewt_indicator_question_mark: ? indicator * @fyewt_indicator_colon: : indicator * @fyewt_indicator_dash: - indicator * @fyewt_indicator_left_bracket: [ indicator * @fyewt_indicator_right_bracket: ] indicator * @fyewt_indicator_left_brace: { indicator * @fyewt_indicator_right_brace: } indicator * @fyewt_indicator_comma: , indicator * @fyewt_indicator_bar: | indicator * @fyewt_indicator_greater: > indicator * @fyewt_indicator_single_quote_start: ' indicator * @fyewt_indicator_single_quote_end: ' indicator * @fyewt_indicator_double_quote_start: " indicator * @fyewt_indicator_double_quote_end: " indicator * @fyewt_indicator_ambersand: & indicator * @fyewt_indicator_star: * indicator * @fyewt_indicator_chomp: chomp indicator (- or +) * @fyewt_indicator_explicit_indent: explicit indent indicator (0-9) */ 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, /* extended indicators */ 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, }; #define FYEWT_EXTENDED_INDICATORS_FIRST fyewt_indicator_question_mark #define FYEWT_EXTENDED_INDICATORS_LAST fyewt_indicator_explicit_indent #define FYEWT_EXTENDED_START fyewt_indicator_question_mark #define FYEWT_COUNT (fyewt_indicator_explicit_indent + 1) #define FYECF_INDENT_SHIFT 8 #define FYECF_INDENT_MASK 0xf #define FYECF_INDENT(x) (((x) & FYECF_INDENT_MASK) << FYECF_INDENT_SHIFT) #define FYECF_WIDTH_SHIFT 12 #define FYECF_WIDTH_MASK 0xff #define FYECF_WIDTH(x) (((x) & FYECF_WIDTH_MASK) << FYECF_WIDTH_SHIFT) #define FYECF_MODE_SHIFT 20 #define FYECF_MODE_MASK 0xf #define FYECF_MODE(x) (((x) & FYECF_MODE_MASK) << FYECF_MODE_SHIFT) #define FYECF_DOC_START_MARK_SHIFT 24 #define FYECF_DOC_START_MARK_MASK 0x3 #define FYECF_DOC_START_MARK(x) (((x) & FYECF_DOC_START_MARK_MASK) << FYECF_DOC_START_MARK_SHIFT) #define FYECF_DOC_END_MARK_SHIFT 26 #define FYECF_DOC_END_MARK_MASK 0x3 #define FYECF_DOC_END_MARK(x) (((x) & FYECF_DOC_END_MARK_MASK) << FYECF_DOC_END_MARK_SHIFT) #define FYECF_VERSION_DIR_SHIFT 28 #define FYECF_VERSION_DIR_MASK 0x3 #define FYECF_VERSION_DIR(x) (((x) & FYECF_VERSION_DIR_MASK) << FYECF_VERSION_DIR_SHIFT) #define FYECF_TAG_DIR_SHIFT 30 #define FYECF_TAG_DIR_MASK 0x3 #define FYECF_TAG_DIR(x) (((unsigned int)(x) & FYECF_TAG_DIR_MASK) << FYECF_TAG_DIR_SHIFT) /** * enum fy_emitter_cfg_flags - Emitter configuration flags * * These flags control the operation of the emitter * * @FYECF_SORT_KEYS: Sort key when emitting * @FYECF_OUTPUT_COMMENTS: Output comments (experimental) * @FYECF_STRIP_LABELS: Strip labels when emitting * @FYECF_STRIP_TAGS: Strip tags when emitting * @FYECF_STRIP_DOC: Strip document tags and markers when emitting * @FYECF_NO_ENDING_NEWLINE: Do not output ending new line (useful for single line mode) * @FYECF_STRIP_EMPTY_KV: Remove all keys with empty values from the output (not available in streaming mode) * @FYECF_EXTENDED_CFG: Extend configuration, this config structure is embedded in a fy_emitter_xcfg. * @FYECF_INDENT_DEFAULT: Default emit output indent * @FYECF_INDENT_1: Output indent is 1 * @FYECF_INDENT_2: Output indent is 2 * @FYECF_INDENT_3: Output indent is 3 * @FYECF_INDENT_4: Output indent is 4 * @FYECF_INDENT_5: Output indent is 5 * @FYECF_INDENT_6: Output indent is 6 * @FYECF_INDENT_7: Output indent is 7 * @FYECF_INDENT_8: Output indent is 8 * @FYECF_INDENT_9: Output indent is 9 * @FYECF_WIDTH_DEFAULT: Default emit output width * @FYECF_WIDTH_80: Output width is 80 * @FYECF_WIDTH_132: Output width is 132 * @FYECF_WIDTH_INF: Output width is infinite * @FYECF_MODE_ORIGINAL: Emit using the same flow mode as the original * @FYECF_MODE_BLOCK: Emit using only the block mode * @FYECF_MODE_FLOW: Emit using only the flow mode * @FYECF_MODE_FLOW_ONELINE: Emit using only the flow mode (in one line) * @FYECF_MODE_JSON: Emit using JSON mode (non type preserving) * @FYECF_MODE_JSON_TP: Emit using JSON mode (type preserving) * @FYECF_MODE_JSON_ONELINE: Emit using JSON mode (non type preserving, one line) * @FYECF_MODE_DEJSON: Emit YAML trying to pretify JSON * @FYECF_MODE_PRETTY: Emit YAML that tries to look good * @FYECF_MODE_MANUAL: Emit YAML respecting all manual style hints (reformats if needed) * @FYECF_MODE_FLOW_COMPACT: Emit using only the flow mode in as much as possible compact form * @FYECF_MODE_JSON_COMPACT: Emit using JSON compact form * @FYECF_DOC_START_MARK_AUTO: Automatically generate document start markers if required * @FYECF_DOC_START_MARK_OFF: Do not generate document start markers * @FYECF_DOC_START_MARK_ON: Always generate document start markers * @FYECF_DOC_END_MARK_AUTO: Automatically generate document end markers if required * @FYECF_DOC_END_MARK_OFF: Do not generate document end markers * @FYECF_DOC_END_MARK_ON: Always generate document end markers * @FYECF_VERSION_DIR_AUTO: Automatically generate version directive * @FYECF_VERSION_DIR_OFF: Never generate version directive * @FYECF_VERSION_DIR_ON: Always generate version directive * @FYECF_TAG_DIR_AUTO: Automatically generate tag directives * @FYECF_TAG_DIR_OFF: Never generate tag directives * @FYECF_TAG_DIR_ON: Always generate tag directives * @FYECF_DEFAULT: The default emitter configuration */ enum fy_emitter_cfg_flags { FYECF_SORT_KEYS = FY_BIT(0), FYECF_OUTPUT_COMMENTS = FY_BIT(1), FYECF_STRIP_LABELS = FY_BIT(2), FYECF_STRIP_TAGS = FY_BIT(3), FYECF_STRIP_DOC = FY_BIT(4), FYECF_NO_ENDING_NEWLINE = FY_BIT(5), FYECF_STRIP_EMPTY_KV = FY_BIT(6), FYECF_EXTENDED_CFG = FY_BIT(7), FYECF_INDENT_DEFAULT = FYECF_INDENT(0), FYECF_INDENT_1 = FYECF_INDENT(1), FYECF_INDENT_2 = FYECF_INDENT(2), FYECF_INDENT_3 = FYECF_INDENT(3), FYECF_INDENT_4 = FYECF_INDENT(4), FYECF_INDENT_5 = FYECF_INDENT(5), FYECF_INDENT_6 = FYECF_INDENT(6), FYECF_INDENT_7 = FYECF_INDENT(7), FYECF_INDENT_8 = FYECF_INDENT(8), FYECF_INDENT_9 = FYECF_INDENT(9), FYECF_WIDTH_DEFAULT = FYECF_WIDTH(80), FYECF_WIDTH_80 = FYECF_WIDTH(80), FYECF_WIDTH_132 = FYECF_WIDTH(132), FYECF_WIDTH_INF = FYECF_WIDTH(255), FYECF_MODE_ORIGINAL = FYECF_MODE(0), FYECF_MODE_BLOCK = FYECF_MODE(1), FYECF_MODE_FLOW = FYECF_MODE(2), FYECF_MODE_FLOW_ONELINE = FYECF_MODE(3), FYECF_MODE_JSON = FYECF_MODE(4), FYECF_MODE_JSON_TP = FYECF_MODE(5), FYECF_MODE_JSON_ONELINE = FYECF_MODE(6), FYECF_MODE_DEJSON = FYECF_MODE(7), FYECF_MODE_PRETTY = FYECF_MODE(8), FYECF_MODE_MANUAL = FYECF_MODE(9), FYECF_MODE_FLOW_COMPACT = FYECF_MODE(10), FYECF_MODE_JSON_COMPACT = FYECF_MODE(11), FYECF_DOC_START_MARK_AUTO = FYECF_DOC_START_MARK(0), FYECF_DOC_START_MARK_OFF = FYECF_DOC_START_MARK(1), FYECF_DOC_START_MARK_ON = FYECF_DOC_START_MARK(2), FYECF_DOC_END_MARK_AUTO = FYECF_DOC_END_MARK(0), FYECF_DOC_END_MARK_OFF = FYECF_DOC_END_MARK(1), FYECF_DOC_END_MARK_ON = FYECF_DOC_END_MARK(2), FYECF_VERSION_DIR_AUTO = FYECF_VERSION_DIR(0), FYECF_VERSION_DIR_OFF = FYECF_VERSION_DIR(1), FYECF_VERSION_DIR_ON = FYECF_VERSION_DIR(2), FYECF_TAG_DIR_AUTO = FYECF_TAG_DIR(0), FYECF_TAG_DIR_OFF = FYECF_TAG_DIR(1), FYECF_TAG_DIR_ON = FYECF_TAG_DIR(2), FYECF_DEFAULT = FYECF_WIDTH_INF | FYECF_MODE_ORIGINAL | FYECF_INDENT_DEFAULT, }; /** * struct fy_emitter_cfg - emitter configuration structure. * * Argument to the fy_emitter_create() method which * is the way to convert a runtime document structure back to YAML. * * @flags: Configuration flags * @output: Pointer to the method that will perform output. * @userdata: Opaque user data pointer * @diag: Diagnostic interface */ 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; }; /* Shift amount of the color settings */ #define FYEXCF_COLOR_SHIFT 0 /* Mask of the color */ #define FYEXCF_COLOR_MASK ((1U << 2) - 1) /* Build a color version */ #define FYEXCF_COLOR(x) (((unsigned int)(x) & FYEXCF_COLOR_MASK) << FYEXCF_COLOR_SHIFT) /* Shift amount of the output settings */ #define FYEXCF_OUTPUT_SHIFT 2 /* Mask of the output */ #define FYEXCF_OUTPUT_MASK ((1U << 3) - 1) /* Build an output */ #define FYEXCF_OUTPUT(x) (((unsigned int)(x) & FYEXCF_OUTPUT_MASK) << FYEXCF_OUTPUT_SHIFT) /** * enum fy_emitter_xcfg_flags - Emitter extended configuration flags * * These flags control the operation of the emitter. * If no extended configuration mode is enabled all the flags are assumed 0. * * @FYEXCF_COLOR_AUTO: Automatically colorize if on a terminal * @FYEXCF_COLOR_NONE: Do not colorize output * @FYEXCF_COLOR_FORCE: Force color generation * @FYEXCF_VISIBLE_WS: Make white space visible * @FYEXCF_EXTENDED_INDICATORS: Extend the indicators generated * @FYEXCF_INDENTED_SEQ_IN_MAP: Indent block sequences that are mapping values * @FYEXCF_PRESERVE_FLOW_LAYOUT: Preserve oneline flow collections in streaming mode * @FYEXCF_OUTPUT_STDOUT: Output to stdout (default) * @FYEXCF_OUTPUT_STDERR: Output to stderr, instead of stdout * @FYEXCF_OUTPUT_FILE: Output to the fp FILE pointer * @FYEXCF_OUTPUT_FD: Output to the fd file descriptor * @FYEXCF_NULL_OUTPUT: No output * @FYEXCF_OUTPUT_FILENAME: Output to the given filename */ enum fy_emitter_xcfg_flags { FYEXCF_COLOR_AUTO = FYEXCF_COLOR(0), FYEXCF_COLOR_NONE = FYEXCF_COLOR(1), FYEXCF_COLOR_FORCE = FYEXCF_COLOR(2), FYEXCF_OUTPUT_STDOUT = FYEXCF_OUTPUT(0), FYEXCF_OUTPUT_STDERR = FYEXCF_OUTPUT(1), FYEXCF_OUTPUT_FILE = FYEXCF_OUTPUT(2), FYEXCF_OUTPUT_FD = FYEXCF_OUTPUT(2), FYEXCF_NULL_OUTPUT = FYEXCF_OUTPUT(3), FYEXCF_OUTPUT_FILENAME = FYEXCF_OUTPUT(4), FYEXCF_VISIBLE_WS = FY_BIT(5), FYEXCF_EXTENDED_INDICATORS = FY_BIT(6), FYEXCF_INDENTED_SEQ_IN_MAP = FY_BIT(7), FYEXCF_PRESERVE_FLOW_LAYOUT = FY_BIT(8), }; /** * struct fy_emitter_xcfg - emitter extended configuration structure. * * Argument to the fy_emitter create when FYECF_EXTENDED_CFG bit is * set. * * @cfg: The standard emitter configuration * @xflags: Extra configuration flags * @colors: ANSI color overrides for the default output method * @output_fp: The output FILE \*, FYEXCF\_FILE\_OUTPUT must be set * @output_fd: The output file descriptor, FYEXCF\_FD\_OUTPUT must be set * @output_filename: The output filename, FYEXCF\_FILENAME\_OUTPUT must be set */ 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; }; }; /** * fy_emitter_create() - Create an emitter * * Creates an emitter using the supplied configuration * * @cfg: The emitter configuration * * Returns: * The newly created emitter or NULL on error. */ struct fy_emitter * fy_emitter_create(const struct fy_emitter_cfg *cfg) FY_EXPORT; /** * fy_emitter_destroy() - Destroy an emitter * * Destroy an emitter previously created by fy_emitter_create() * * @emit: The emitter to destroy */ void fy_emitter_destroy(struct fy_emitter *emit) FY_EXPORT; /** * fy_emitter_get_cfg() - Get the configuration of an emitter * * @emit: The emitter * * Returns: * The configuration of the emitter */ const struct fy_emitter_cfg * fy_emitter_get_cfg(struct fy_emitter *emit) FY_EXPORT; /** * fy_emitter_get_diag() - Get the diagnostic object of an emitter * * Return a pointer to the diagnostic object of an emitter object. * Note that the returned diag object has a reference taken so * you should fy_diag_unref() it when you're done with it. * * @emit: The emitter to get the diagnostic object * * Returns: * A pointer to a ref'ed diagnostic object or NULL in case of an * error. */ struct fy_diag * fy_emitter_get_diag(struct fy_emitter *emit) FY_EXPORT; /** * fy_emitter_set_diag() - Set the diagnostic object of an emitter * * 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. * * @emit: The emitter to replace the diagnostic object * @diag: The emitter's new diagnostic object, NULL for default * * Returns: * 0 if everything OK, -1 otherwise */ int fy_emitter_set_diag(struct fy_emitter *emit, struct fy_diag *diag) FY_EXPORT; /** * fy_emitter_set_finalizer() - Set emitter finalizer * * Set a method callback to be called when the emitter * is disposed of. If finalizer is NULL, then the method * is removed. * * @emit: The emitter to replace the diagnostic object * @finalizer: The finalizer callback */ void fy_emitter_set_finalizer(struct fy_emitter *emit, void (*finalizer)(struct fy_emitter *emit)) FY_EXPORT; /** * struct fy_emitter_default_output_data - emitter default output configuration * * This is the argument to the default output method of the emitter. * * @fp: File where the output is directed to * @colorize: Use ANSI color sequences to colorize the output * @visible: Make whitespace visible (requires a UTF8 capable terminal) */ struct fy_emitter_default_output_data { FILE *fp; bool colorize; bool visible; }; /** * fy_emitter_default_output() - The default colorizing output method * * This is the default colorizing output method. * Will be used when the output field of the emitter configuration is NULL. * * @fye: The emitter * @type: Type of the emitted output * @str: Pointer to the string to output * @len: Length of the string * @userdata: Must point to a fy_emitter_default_output_data structure * * Returns: * 0 on success, -1 on error */ int fy_emitter_default_output(struct fy_emitter *fye, enum fy_emitter_write_type type, const char *str, int len, void *userdata) FY_EXPORT; /** * fy_document_default_emit_to_fp() - Emit a document to a file, using defaults * * 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. * * @fyd: The document to emit * @fp: The file where the output is sent * * Returns: * 0 on success, -1 on error */ int fy_document_default_emit_to_fp(struct fy_document *fyd, FILE *fp) FY_EXPORT; /** * fy_emit_event() - Queue (and possibly emit) an event * * Queue and output using the emitter. This is the streaming * output method which does not require creating a document. * * @emit: The emitter to use * @fye: The event to queue for emission * * Returns: * 0 on success, -1 on error */ int fy_emit_event(struct fy_emitter *emit, struct fy_event *fye) FY_EXPORT; /** * fy_emit_vevent() - Queue (and possibly emit) an event using varargs * * Queue and output using the emitter. The format is identical to * the one used in fy_emit_event_vcreate(). * * @emit: The emitter to use * @type: The event type to create * @ap: The variable argument list pointer. * * Returns: * 0 on success, -1 on error */ int fy_emit_vevent(struct fy_emitter *emit, enum fy_event_type type, va_list ap) FY_EXPORT; /** * fy_emit_eventf() - Queue (and possibly emit) an event using variable args * * Queue and output using the emitter. The format is identical to * the one used in fy_emit_event_create(). * * @emit: The emitter to use * @type: The event type to create * @...: The optional extra arguments * * Returns: * 0 on success, -1 on error */ int fy_emit_eventf(struct fy_emitter *emit, enum fy_event_type type, ...) FY_EXPORT; /** * fy_emit_scalar_write() - Emit a scalar with write semantics * * Queue and output using the emitter a scalar using a standard * write interface. * * @fye: The emitter to use * @style: The scalar style to use * @anchor: The anchor or NULL * @tag: The tag or NULL * @buf: Pointer to the buffer * @count: The number of bytes to write * * Returns: * 0 on success, -1 on error */ int fy_emit_scalar_write(struct fy_emitter *fye, enum fy_scalar_style style, const char *anchor, const char *tag, const char *buf, size_t count) FY_EXPORT; /** * fy_emit_scalar_vprintf() - Emit a scalar with vprintf semantics * * Queue and output using the emitter a scalar using a standard * vprintf interface. * * @fye: The emitter to use * @style: The scalar style to use * @anchor: The anchor or NULL * @tag: The tag or NULL * @fmt: The printf like format string * @ap: The argument list * * Returns: * 0 on success, -1 on error */ int fy_emit_scalar_vprintf(struct fy_emitter *fye, enum fy_scalar_style style, const char *anchor, const char *tag, const char *fmt, va_list ap) FY_EXPORT; /** * fy_emit_scalar_printf() - Emit a scalar with printf semantics * * Queue and output using the emitter a scalar using a standard * printf interface. * * @fye: The emitter to use * @style: The scalar style to use * @anchor: The anchor or NULL * @tag: The tag or NULL * @fmt: The printf like format string * @...: The extra arguments * * Returns: * 0 on success, -1 on error */ int fy_emit_scalar_printf(struct fy_emitter *fye, enum fy_scalar_style style, const char *anchor, const char *tag, const char *fmt, ...) FY_FORMAT(printf, 5, 6) FY_EXPORT; /** * fy_emit_event_from_parser() - Queue (and possibly emit) an event * generated by the parser. * * Queue and output using the emitter. This is the streaming * output method which does not require creating a document. * Similar to fy_emit_event() but it is more efficient. * * @emit: The emitter to use * @fyp: The parser that generated the event * @fye: The event to queue for emission * * Returns: * 0 on success, -1 on error */ int fy_emit_event_from_parser(struct fy_emitter *emit, struct fy_parser *fyp, struct fy_event *fye) FY_EXPORT; /** * fy_emit_document() - Emit the document using the emitter * * Emits a document in YAML format using the emitter. * * @emit: The emitter * @fyd: The document to emit * * Returns: * 0 on success, -1 on error */ int fy_emit_document(struct fy_emitter *emit, struct fy_document *fyd) FY_EXPORT; /** * fy_emit_document_start() - Emit document start using the emitter * * Emits a document start using the emitter. This is used in case * you need finer control over the emitting output. * * @emit: The emitter * @fyd: The document to use for emitting it's start * @fyn: The root (or NULL for using the document's root) * * Returns: * 0 on success, -1 on error */ int fy_emit_document_start(struct fy_emitter *emit, struct fy_document *fyd, struct fy_node *fyn) FY_EXPORT; /** * fy_emit_document_end() - Emit document end using the emitter * * Emits a document end using the emitter. This is used in case * you need finer control over the emitting output. * * @emit: The emitter * * Returns: * 0 on success, -1 on error */ int fy_emit_document_end(struct fy_emitter *emit) FY_EXPORT; /** * fy_emit_node() - Emit a single node using the emitter * * Emits a single node using the emitter. This is used in case * you need finer control over the emitting output. * * @emit: The emitter * @fyn: The node to emit * * Returns: * 0 on success, -1 on error */ int fy_emit_node(struct fy_emitter *emit, struct fy_node *fyn) FY_EXPORT; /** * fy_emit_root_node() - Emit a single root node using the emitter * * Emits a single root node using the emitter. This is used in case * you need finer control over the emitting output. * * @emit: The emitter * @fyn: The root node to emit * * Returns: * 0 on success, -1 on error */ int fy_emit_root_node(struct fy_emitter *emit, struct fy_node *fyn) FY_EXPORT; /** * fy_emit_body_node() - Emit a single body node using the emitter * * 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. * * @emit: The emitter * @fyn: The body node to emit * * Returns: * 0 on success, -1 on error */ int fy_emit_body_node(struct fy_emitter *emit, struct fy_node *fyn) FY_EXPORT; /** * fy_emit_explicit_document_end() - Emit an explicit document end * * Emits an explicit document end, i.e. ... . Use this if you * you need finer control over the emitting output. * * @emit: The emitter * * Returns: * 0 on success, -1 on error */ int fy_emit_explicit_document_end(struct fy_emitter *emit) FY_EXPORT; /** * fy_emit_document_to_fp() - Emit a document to an file pointer * * Emits a document from the root to the given file pointer. * * @fyd: The document to emit * @flags: The emitter flags to use * @fp: The file pointer to output to * * Returns: * 0 on success, -1 on error */ int fy_emit_document_to_fp(struct fy_document *fyd, enum fy_emitter_cfg_flags flags, FILE *fp) FY_EXPORT; /** * fy_emit_document_to_file() - Emit a document to file * * Emits a document from the root to the given file. * The file will be fopen'ed using a "wa" mode. * * @fyd: The document to emit * @flags: The emitter flags to use * @filename: The filename to output to, or NULL for stdout * * Returns: * 0 on success, -1 on error */ int fy_emit_document_to_file(struct fy_document *fyd, enum fy_emitter_cfg_flags flags, const char *filename) FY_EXPORT; /** * fy_emit_document_to_fd() - Emit a document to a file descriptor * * Emits a document from the root to the given file descriptor * * @fyd: The document to emit * @flags: The emitter flags to use * @fd: The file descriptor to output to * * Returns: * 0 on success, -1 on error */ int fy_emit_document_to_fd(struct fy_document *fyd, enum fy_emitter_cfg_flags flags, int fd) FY_EXPORT; /** * fy_emit_document_to_buffer() - Emit a document to a buffer * * Emits an document from the root to the given buffer. * If the document does not fit, an error will be returned. * * @fyd: The document to emit * @flags: The emitter flags to use * @buf: Pointer to the buffer area to fill * @size: Size of the buffer * * Returns: * A positive number, which is the size of the emitted document * on the buffer on success, -1 on error */ int fy_emit_document_to_buffer(struct fy_document *fyd, enum fy_emitter_cfg_flags flags, char *buf, size_t size) FY_EXPORT; /** * fy_emit_document_to_string() - Emit a document to an allocated string * * Emits an document from the root to a string which will be dynamically * allocated. * * @fyd: The document to emit * @flags: The emitter flags to use * * Returns: * A pointer to the allocated string, or NULL in case of an error */ char * fy_emit_document_to_string(struct fy_document *fyd, enum fy_emitter_cfg_flags flags) FY_EXPORT; #define fy_emit_document_to_string_alloca(_fyd, _flags) \ FY_ALLOCA_COPY_FREE(fy_emit_document_to_string((_fyd), (_flags)), FY_NT) /** * fy_emit_node_to_buffer() - Emit a node (recursively) to a buffer * * Emits a node recursively to the given buffer. * If the document does not fit, an error will be returned. * * @fyn: The node to emit * @flags: The emitter flags to use * @buf: Pointer to the buffer area to fill * @size: Size of the buffer * * Returns: * A positive number, which is the size of the emitted node * on the buffer on success, -1 on error */ int fy_emit_node_to_buffer(struct fy_node *fyn, enum fy_emitter_cfg_flags flags, char *buf, size_t size) FY_EXPORT; /** * fy_emit_node_to_string() - Emit a node to an allocated string * * Emits a node recursively to a string which will be dynamically * allocated. * * @fyn: The node to emit * @flags: The emitter flags to use * * Returns: * A pointer to the allocated string, or NULL in case of an error */ char * fy_emit_node_to_string(struct fy_node *fyn, enum fy_emitter_cfg_flags flags) FY_EXPORT; #define fy_emit_node_to_string_alloca(_fyn, _flags) \ FY_ALLOCA_COPY_FREE(fy_emit_node_to_string((_fyn), (_flags)), FY_NT) /** * fy_emit_to_buffer() - Create an emitter for buffer output. * * Creates a special purpose emitter for buffer output. * Calls to fy_emit_event() populate the buffer. * The contents are retreived by a call to fy_emit_to_buffer_collect() * * @flags: The emitter flags to use * @buf: Pointer to the buffer area to fill * @size: Size of the buffer * * Returns: * The newly created emitter or NULL on error. */ struct fy_emitter * fy_emit_to_buffer(enum fy_emitter_cfg_flags flags, char *buf, size_t size) FY_EXPORT; /** * fy_emit_to_buffer_collect() - Collect the buffer emitter output * * Collects the output of the emitter which was created by * fy_emit_to_buffer() and populated using fy_emit_event() calls. * The NULL terminated returned buffer is the same as the one used in the * fy_emit_to_buffer() call and the sizep argument will be filled with * the size of the buffer. * * @emit: The emitter * @sizep: Pointer to the size to be filled * * Returns: * The buffer or NULL in case of an error. */ char * fy_emit_to_buffer_collect(struct fy_emitter *emit, size_t *sizep) FY_EXPORT; /** * fy_emit_to_string() - Create an emitter to create a dynamically * allocated string. * * Creates a special purpose emitter for output to a dynamically * allocated string. * Calls to fy_emit_event() populate the buffer. * The contents are retreived by a call to fy_emit_to_string_collect() * * @flags: The emitter flags to use * * Returns: * The newly created emitter or NULL on error. */ struct fy_emitter * fy_emit_to_string(enum fy_emitter_cfg_flags flags) FY_EXPORT; /** * fy_emit_to_string_collect() - Collect the string emitter output * * Collects the output of the emitter which was created by * fy_emit_to_string() and populated using fy_emit_event() calls. * The NULL terminated returned buffer is dynamically allocated * and must be freed via a call to free(). * The sizep argument will be filled with the size of the buffer. * * @emit: The emitter * @sizep: Pointer to the size to be filled * * Returns: * The dynamically allocated string or NULL in case of an error. */ char * fy_emit_to_string_collect(struct fy_emitter *emit, size_t *sizep) FY_EXPORT; /** * fy_node_copy() - Copy a node, associating the new node with the given document * * Make a deep copy of a node, associating the copy with the given document. * Note that no content copying takes place as the contents of the nodes * are reference counted. This means that the operation is relatively inexpensive. * * Note that the copy includes all anchors contained in the subtree of the * source, so this call will register them with the document. * * @fyd: The document which the resulting node will be associated with * @fyn_from: The source node to recursively copy * * Returns: * The copied node on success, NULL on error */ struct fy_node * fy_node_copy(struct fy_document *fyd, struct fy_node *fyn_from) FY_EXPORT; /** * fy_document_clone() - Clones a document * * 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. * * @fydsrc: The source document to clone * * Returns: * The newly created clone document, or NULL in case of an error */ struct fy_document * fy_document_clone(struct fy_document *fydsrc) FY_EXPORT; /** * fy_node_insert() - Insert a node to the given node * * Insert a node to another node. If @fyn_from is NULL then this * operation will delete the @fyn_to node. * * The operation varies according to the types of the arguments: * * from: scalar * * to: another-scalar -> scalar * to: { key: value } -> scalar * to: [ seq0, seq1 ] -> scalar * * from: [ seq2 ] * to: scalar -> [ seq2 ] * to: { key: value } -> [ seq2 ] * to: [ seq0, seq1 ] -> [ seq0, seq1, sec2 ] * * from: { another-key: another-value } * to: scalar -> { another-key: another-value } * to: { key: value } -> { key: value, another-key: another-value } * to: [ seq0, seq1 ] -> { another-key: another-value } * * from: { key: another-value } * to: scalar -> { key: another-value } * to: { key: value } -> { key: another-value } * to: [ seq0, seq1 ] -> { key: another-value } * * The rules are: * - If target node changes type, source ovewrites target. * - If source or target node are scalars, source it overwrites target. * - If target and source are sequences the items of the source sequence * are appended to the target sequence. * - If target and source are maps the key, value pairs of the source * are appended to the target map. If the target map contains a * key-value pair that is present in the source map, it is overwriten * by it. * * @fyn_to: The target node * @fyn_from: The source node * * Returns: * 0 on success, -1 on error */ int fy_node_insert(struct fy_node *fyn_to, struct fy_node *fyn_from) FY_EXPORT; /** * fy_node_delete() - Delete a node from a document * * Delete the given node. * If it's part of a sequence it will be removed from it. * If it's the value of a node key value pair, it will * be removed from the mapping. * * This is an alias for fy_document_insert_at(fyn, NULL) * * Note that it is expected this node is attached to a document. * Do not call this to free a node, because if it's part of * a collection it will not be properly removed. * * @fyn: The node to delete. * * Returns: * 0 on success, -1 on error */ int fy_node_delete(struct fy_node *fyn) FY_EXPORT; /** * fy_document_insert_at() - Insert a node to the given path in the document * * Insert a node to a given point in the document. If @fyn is NULL then this * operation will delete the target node. * * Please see fy_node_insert for details of operation. * * Note that in any case the fyn node will be unref'ed. * So if the operation fails, and the reference is 0 * the node will be freed. If you want it to stick around * take a reference before. * * @fyd: The document * @path: The path where the insert operation will target * @pathlen: The length of the path (or -1 if '\0' terminated) * @fyn: The source node * * Returns: * 0 on success, -1 on error */ int fy_document_insert_at(struct fy_document *fyd, const char *path, size_t pathlen, struct fy_node *fyn) FY_EXPORT; /** * enum fy_node_type - Node type * * Each node may be one of the following types * * @FYNT_SCALAR: Node is a scalar * @FYNT_SEQUENCE: Node is a sequence * @FYNT_MAPPING: Node is a mapping */ enum fy_node_type { FYNT_SCALAR, FYNT_SEQUENCE, FYNT_MAPPING, }; /** * enum fy_node_style - Node style * * A node may contain a hint of how it should be * rendered, encoded as a style. * * @FYNS_ANY: No hint, let the emitter decide * @FYNS_FLOW: Prefer flow style (for sequence/mappings) * @FYNS_BLOCK: Prefer block style (for sequence/mappings) * @FYNS_PLAIN: Plain style preferred * @FYNS_SINGLE_QUOTED: Single quoted style preferred * @FYNS_DOUBLE_QUOTED: Double quoted style preferred * @FYNS_LITERAL: Literal style preferred (valid in block context) * @FYNS_FOLDED: Folded style preferred (valid in block context) * @FYNS_ALIAS: It's an alias */ enum fy_node_style { FYNS_ANY = -1, FYNS_FLOW, FYNS_BLOCK, FYNS_PLAIN, FYNS_SINGLE_QUOTED, FYNS_DOUBLE_QUOTED, FYNS_LITERAL, FYNS_FOLDED, FYNS_ALIAS, }; /* maximum depth is 256 */ #define FYNWF_MAXDEPTH_SHIFT 4 #define FYNWF_MAXDEPTH_MASK 0xff #define FYNWF_MAXDEPTH(x) (((x) & FYNWF_MAXDEPTH_MASK) << FYNWF_MAXDEPTH_SHIFT) #define FYNWF_MARKER_SHIFT 12 #define FYNWF_MARKER_MASK 0x1f #define FYNWF_MARKER(x) (((x) & FYNWF_MARKER_MASK) << FYNWF_MARKER_SHIFT) #define FYNWF_PTR_SHIFT 16 #define FYNWF_PTR_MASK 0x03 #define FYNWF_PTR(x) (((x) & FYNWF_PTR_MASK) << FYNWF_PTR_SHIFT) /** * enum fy_node_walk_flags - Node walk flags * * @FYNWF_DONT_FOLLOW: Don't follow aliases during pathwalk * @FYNWF_FOLLOW: Follow aliases during pathwalk * @FYNWF_PTR_YAML: YAML pointer path walks * @FYNWF_PTR_JSON: JSON pointer path walks * @FYNWF_PTR_RELJSON: Relative JSON pointer path walks * @FYNWF_PTR_YPATH: YPATH pointer path walks * @FYNWF_URI_ENCODED: The path is URI encoded * @FYNWF_MAXDEPTH_DEFAULT: Max follow depth is automatically determined * @FYNWF_MARKER_DEFAULT: Default marker to use when scanning * @FYNWF_PTR_DEFAULT: Default path type */ enum fy_node_walk_flags { FYNWF_DONT_FOLLOW = 0, FYNWF_FOLLOW = FY_BIT(0), FYNWF_PTR_YAML = FYNWF_PTR(0), FYNWF_PTR_JSON = FYNWF_PTR(1), FYNWF_PTR_RELJSON = FYNWF_PTR(2), FYNWF_PTR_YPATH = FYNWF_PTR(3), FYNWF_URI_ENCODED = FY_BIT(18), FYNWF_MAXDEPTH_DEFAULT = FYNWF_MAXDEPTH(0), FYNWF_MARKER_DEFAULT = FYNWF_MARKER(0), FYNWF_PTR_DEFAULT = FYNWF_PTR(0), }; /* the maximum user marker */ #define FYNWF_MAX_USER_MARKER 24 /** * fy_node_style_from_scalar_style() - Convert from scalar to node style * * Convert a scalar style to a node style. * * @sstyle: The input scalar style * * Returns: * The matching node style */ static inline enum fy_node_style fy_node_style_from_scalar_style(enum fy_scalar_style sstyle) { if (sstyle == FYSS_ANY) return FYNS_ANY; return (enum fy_node_style)(FYNS_PLAIN + (sstyle - FYSS_PLAIN)); } /** * typedef fy_node_mapping_sort_fn - Mapping sorting method function * * @fynp_a: The first node_pair used in the comparison * @fynp_b: The second node_pair used in the comparison * @arg: The opaque user provided pointer to the sort operation * * Returns: * <0 if @fynp_a is less than @fynp_b * 0 if @fynp_a is equal to fynp_b * >0 if @fynp_a is greater than @fynp_b */ typedef int (*fy_node_mapping_sort_fn)(const struct fy_node_pair *fynp_a, const struct fy_node_pair *fynp_b, void *arg); /** * typedef fy_node_scalar_compare_fn - Node compare method function for scalars * * @fyn_a: The first scalar node used in the comparison * @fyn_b: The second scalar node used in the comparison * @arg: The opaque user provided pointer to the compare operation * * Returns: * <0 if @fyn_a is less than @fyn_b * 0 if @fyn_a is equal to fyn_b * >0 if @fyn_a is greater than @fyn_b */ typedef int (*fy_node_scalar_compare_fn)(struct fy_node *fyn_a, struct fy_node *fyn_b, void *arg); /** * fy_node_compare() - Compare two nodes for equality * * 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. * * @fyn1: The first node to use in the comparison * @fyn2: The second node to use in the comparison * * Returns: * true if the nodes contain the same content, false otherwise */ bool fy_node_compare(struct fy_node *fyn1, struct fy_node *fyn2) FY_EXPORT; /** * fy_node_compare_user() - Compare two nodes for equality using * user supplied sort and scalar compare methods * * 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. * * @fyn1: The first node to use in the comparison * @fyn2: The second node to use in the comparison * @sort_fn: The method to use for sorting maps, or NULL for the default * @sort_fn_arg: The extra user supplied argument to the @sort_fn * @cmp_fn: The method to use for comparing scalars, or NULL for the default * @cmp_fn_arg: The extra user supplied argument to the @cmp_fn * * Returns: * true if the nodes contain the same content, false otherwise */ bool fy_node_compare_user(struct fy_node *fyn1, struct fy_node *fyn2, fy_node_mapping_sort_fn sort_fn, void *sort_fn_arg, fy_node_scalar_compare_fn cmp_fn, void *cmp_fn_arg) FY_EXPORT; /** * fy_node_compare_string() - Compare a node for equality with a YAML string * * Compare a node for equality with a YAML string. * The comparison is performed using fy_node_compare() with the * first node supplied as an argument and the second being generated * by calling fy_document_build_from_string with the YAML string. * * @fyn: The node to use in the comparison * @str: The YAML string to compare against * @len: The length of the string (or -1 if '\0' terminated) * * Returns: * true if the node and the string are equal. */ bool fy_node_compare_string(struct fy_node *fyn, const char *str, size_t len) FY_EXPORT; /** * fy_node_compare_token() - Compare a node for equality against a token * * Compare a node for equality with a token. * Both the node and the tokens must be a scalars. * * @fyn: The node to use in the comparison * @fyt: The scalar token * * Returns: * true if the node and the token are equal. */ bool fy_node_compare_token(struct fy_node *fyn, struct fy_token *fyt) FY_EXPORT; /** * fy_node_compare_text() - Compare a node for equality with a raw C text * * Compare a node for equality with a raw C string. * The node must be a scalar. * * @fyn: The node to use in the comparison * @text: The raw C text to compare against * @len: The length of the text (or -1 if '\0' terminated) * * Returns: * true if the node and the text are equal. */ bool fy_node_compare_text(struct fy_node *fyn, const char *text, size_t len) FY_EXPORT; /** * fy_document_create() - Create an empty document * * Create an empty document using the provided parser configuration. * If NULL use the default parse configuration. * * @cfg: The parse configuration to use or NULL for the default. * * Returns: * The created empty document, or NULL on error. */ struct fy_document * fy_document_create(const struct fy_parse_cfg *cfg) FY_EXPORT; /** * fy_document_destroy() - Destroy a document previously created via * fy_document_create() * * Destroy a document (along with all children documents) * * @fyd: The document to destroy * */ void fy_document_destroy(struct fy_document *fyd) FY_EXPORT; /** * fy_document_get_cfg() - Get the configuration of a document * * @fyd: The document * * Returns: * The configuration of the document */ const struct fy_parse_cfg * fy_document_get_cfg(struct fy_document *fyd) FY_EXPORT; /** * fy_document_get_diag() - Get the diagnostic object of a document * * Return a pointer to the diagnostic object of a document object. * Note that the returned diag object has a reference taken so * you should fy_diag_unref() it when you're done with it. * * @fyd: The document to get the diagnostic object * * Returns: * A pointer to a ref'ed diagnostic object or NULL in case of an * error. */ struct fy_diag * fy_document_get_diag(struct fy_document *fyd) FY_EXPORT; /** * fy_document_set_diag() - Set the diagnostic object of a document * * 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. * * @fyd: The document to replace the diagnostic object * @diag: The document's new diagnostic object, NULL for default * * Returns: * 0 if everything OK, -1 otherwise */ int fy_document_set_diag(struct fy_document *fyd, struct fy_diag *diag) FY_EXPORT; /** * fy_document_set_parent() - Make a document a child of another * * Set the parent of @fyd_child document to be @fyd * * @fyd: The parent document * @fyd_child: The child document * * Returns: * 0 if all OK, -1 on error. */ int fy_document_set_parent(struct fy_document *fyd, struct fy_document *fyd_child) FY_EXPORT; /** * fy_document_build_from_string() - Create a document using the provided YAML source. * * Create a document parsing the provided string as a YAML source. * * @cfg: The parse configuration to use or NULL for the default. * @str: The YAML source to use. * @len: The length of the string (or -1 if '\0' terminated) * * Returns: * The created document, or NULL on error. */ struct fy_document * fy_document_build_from_string(const struct fy_parse_cfg *cfg, const char *str, size_t len) FY_EXPORT; /** * fy_document_build_from_malloc_string() - Create a document using the provided YAML source which was malloced. * * 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. * * @cfg: The parse configuration to use or NULL for the default. * @str: The YAML source to use. * @len: The length of the string (or -1 if '\0' terminated) * * Returns: * The created document, or NULL on error. */ struct fy_document * fy_document_build_from_malloc_string(const struct fy_parse_cfg *cfg, char *str, size_t len) FY_EXPORT; /** * fy_document_build_from_file() - Create a document parsing the given file * * Create a document parsing the provided file as a YAML source. * * @cfg: The parse configuration to use or NULL for the default. * @file: The name of the file to parse * * Returns: * The created document, or NULL on error. */ struct fy_document * fy_document_build_from_file(const struct fy_parse_cfg *cfg, const char *file) FY_EXPORT; /** * fy_document_build_from_fp() - Create a document parsing the given file pointer * * Create a document parsing the provided file pointer as a YAML source. * * @cfg: The parse configuration to use or NULL for the default. * @fp: The file pointer * * Returns: * The created document, or NULL on error. */ struct fy_document * fy_document_build_from_fp(const struct fy_parse_cfg *cfg, FILE *fp) FY_EXPORT; /** * fy_document_vbuildf() - Create a document using the provided YAML via vprintf formatting * * Create a document parsing the provided string as a YAML source. The string * is created by applying vprintf formatting. * * @cfg: The parse configuration to use or NULL for the default. * @fmt: The format string creating the YAML source to use. * @ap: The va_list argument pointer * * Returns: * The created document, or NULL on error. */ struct fy_document * fy_document_vbuildf(const struct fy_parse_cfg *cfg, const char *fmt, va_list ap) FY_EXPORT; /** * fy_document_buildf() - Create a document using the provided YAML source via printf formatting * * Create a document parsing the provided string as a YAML source. The string * is created by applying printf formatting. * * @cfg: The parse configuration to use or NULL for the default. * @fmt: The format string creating the YAML source to use. * @...: The printf arguments * * Returns: * The created document, or NULL on error. */ struct fy_document * fy_document_buildf(const struct fy_parse_cfg *cfg, const char *fmt, ...) FY_FORMAT(printf, 2, 3) FY_EXPORT; /** * fy_flow_document_build_from_string() - Create a document using the provided YAML source. * * Create a document parsing the provided string as a YAML source. * * The document is a flow document, i.e. does not contain any block content * and is usually laid out in a single line. * * Example of flow documents: * * plain-scalar * "double-quoted-scalar" * 'single-quoted-scalar' * { foo: bar } * [ 0, 1, 2 ] * * A flow document is important because parsing stops at the end * of it, and so can be placed in other non-yaml content. * * @cfg: The parse configuration to use or NULL for the default. * @str: The YAML source to use. * @len: The length of the string (or -1 if '\0' terminated) * @consumed: A pointer to the consumed amount * * Returns: * The created document, or NULL on error. */ struct fy_document * fy_flow_document_build_from_string(const struct fy_parse_cfg *cfg, const char *str, size_t len, size_t *consumed) FY_EXPORT; /** * fy_block_document_build_from_string() - Create a document using the provided YAML source. * * Create a document parsing the provided string as a YAML source. * * The document is a block document, and it terminates when indentation * appears to do so. * * Example of block documents:: * * this-is-yaml * foo: bar <- starts here * baz: [1, 2] * this-is-yaml-no-more * * @cfg: The parse configuration to use or NULL for the default. * @str: The YAML source to use. * @len: The length of the string (or -1 if '\0' terminated) * @consumed: A pointer to the consumed amount * * Returns: * The created document, or NULL on error. */ struct fy_document * fy_block_document_build_from_string(const struct fy_parse_cfg *cfg, const char *str, size_t len, size_t *consumed) FY_EXPORT; /** * fy_document_root() - Return the root node of the document * * Returns the root of the document. If the document is empty * NULL will be returned instead. * * @fyd: The document * * Returns: * The root of the document, or NULL if the document is empty. */ struct fy_node * fy_document_root(struct fy_document *fyd) FY_EXPORT; /** * fy_document_set_root() - Set the root of the document * * Set the root of a document. If the document was not empty * the old root will be freed. If @fyn is NULL then the * document is set to empty. * * @fyd: The document * @fyn: The new root of the document. * * Returns: * 0 on success, -1 on error */ int fy_document_set_root(struct fy_document *fyd, struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_type() - Get the node type * * Retrieve the node type. It is one of FYNT_SCALAR, FYNT_SEQUENCE * or FYNT_MAPPING. A NULL node argument is a FYNT_SCALAR. * * @fyn: The node * * Returns: * The node type */ enum fy_node_type fy_node_get_type(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_style() - Get the node style * * Retrieve the node rendering style. * If the node is NULL then the style is FYNS_PLAIN. * * @fyn: The node * * Returns: * The node style */ enum fy_node_style fy_node_get_style(struct fy_node *fyn) FY_EXPORT; /** * fy_node_set_style() - Set the node style * * 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. * * @fyn: The node * @style: The requested node rendering style * * Returns: * The final node style */ enum fy_node_style fy_node_set_style(struct fy_node *fyn, enum fy_node_style style) FY_EXPORT; /** * fy_node_get_start_token() - Get the node start token * * Retrieve the node start token. * * For scalars, this is the same as the end token. * * @fyn: The node * * Returns: * The node start token */ struct fy_token * fy_node_get_start_token(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_end_token() - Get the node end token * * Retrieve the node end token. * * For scalars, this is the same as the start token. * * @fyn: The node * * Returns: * The node end token */ struct fy_token * fy_node_get_end_token(struct fy_node *fyn) FY_EXPORT; /** * fy_node_is_scalar() - Check whether the node is a scalar * * Convenience method for checking whether a node is a scalar. * * @fyn: The node * * Returns: * true if the node is a scalar, false otherwise */ static inline bool fy_node_is_scalar(struct fy_node *fyn) { return fy_node_get_type(fyn) == FYNT_SCALAR; } /** * fy_node_is_sequence() - Check whether the node is a sequence * * Convenience method for checking whether a node is a sequence. * * @fyn: The node * * Returns: * true if the node is a sequence, false otherwise */ static inline bool fy_node_is_sequence(struct fy_node *fyn) { return fy_node_get_type(fyn) == FYNT_SEQUENCE; } /** * fy_node_is_mapping() - Check whether the node is a mapping * * Convenience method for checking whether a node is a mapping. * * @fyn: The node * * Returns: * true if the node is a mapping, false otherwise */ static inline bool fy_node_is_mapping(struct fy_node *fyn) { return fy_node_get_type(fyn) == FYNT_MAPPING; } /** * fy_node_is_alias() - Check whether the node is an alias * * Convenience method for checking whether a node is an alias. * * @fyn: The node * * Returns: * true if the node is an alias, false otherwise */ static inline bool fy_node_is_alias(struct fy_node *fyn) { return fy_node_get_type(fyn) == FYNT_SCALAR && fy_node_get_style(fyn) == FYNS_ALIAS; } /** * fy_node_is_null() - Check whether the node is a NULL * * Convenience method for checking whether a node is a NULL scalar.. * Note that a NULL node argument returns true... * * @fyn: The node * * Returns: * true if the node is a NULL scalar, false otherwise */ bool fy_node_is_null(struct fy_node *fyn) FY_EXPORT; /** * fy_node_is_attached() - Check whether the node is attached * * 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. * * @fyn: The node * * Returns: * true if the node is attached, false otherwise */ bool fy_node_is_attached(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_tag_token() - Gets the tag token of a node (if it exists) * * Gets the tag token of a node, if it exists * * @fyn: The node which has the tag token to be returned * * Returns: * The tag token of the given node, or NULL if the tag does not * exist. */ struct fy_token * fy_node_get_tag_token(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_scalar_token() - Gets the scalar token of a node (if it exists) * * 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. * * @fyn: The node which has the scalar token to be returned * * Returns: * The scalar token of the given node, or NULL if the node is not a scalar. */ struct fy_token * fy_node_get_scalar_token(struct fy_node *fyn) FY_EXPORT; /** * fy_node_resolve_alias() - Resolve an alias node * * 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. * * @fyn: The alias node to be resolved * * Returns: * The resolved alias node, or NULL if either fyn is not an alias, or * resolution fails due to a graph cycle. */ struct fy_node * fy_node_resolve_alias(struct fy_node *fyn) FY_EXPORT; /** * fy_node_dereference() - Dereference a single alias node * * 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. * * @fyn: The alias node to be dereferenced * * Returns: * The dereferenced alias node, or NULL if either fyn is not an alias, or * resolution fails due to a graph cycle. */ struct fy_node * fy_node_dereference(struct fy_node *fyn) FY_EXPORT; /** * fy_node_free() - Free a node * * Recursively frees the given node releasing the memory it uses, removing * any anchors on the document it contains, and releasing references * on the tokens it contains. * * This method will return an error if the node is attached, or * if not NULL it is not a member of a document. * * @fyn: The node to free * * Returns: * 0 on success, -1 on error. */ int fy_node_free(struct fy_node *fyn) FY_EXPORT; /** * fy_node_build_from_string() - Create a node using the provided YAML source. * * Create a node parsing the provided string as a YAML source. The * node created will be associated with the provided document. * * @fyd: The document * @str: The YAML source to use. * @len: The length of the string (or -1 if '\0' terminated) * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_build_from_string(struct fy_document *fyd, const char *str, size_t len) FY_EXPORT; /** * fy_node_build_from_malloc_string() - Create a node using the provided YAML source which was malloced. * * 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. * * @fyd: The document * @str: The YAML source to use. * @len: The length of the string (or -1 if '\0' terminated) * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_build_from_malloc_string(struct fy_document *fyd, char *str, size_t len) FY_EXPORT; /** * fy_node_build_from_file() - Create a node using the provided YAML file. * * Create a node parsing the provided file as a YAML source. The * node created will be associated with the provided document. * * @fyd: The document * @file: The name of the file to parse * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_build_from_file(struct fy_document *fyd, const char *file) FY_EXPORT; /** * fy_node_build_from_fp() - Create a node using the provided file pointer. * * Create a node parsing the provided file pointer as a YAML source. The * node created will be associated with the provided document. * * @fyd: The document * @fp: The file pointer * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_build_from_fp(struct fy_document *fyd, FILE *fp) FY_EXPORT; /** * fy_node_vbuildf() - Create a node using the provided YAML source via vprintf formatting * * Create a node parsing the resulting string as a YAML source. The string * is created by applying vprintf formatting. * * @fyd: The document * @fmt: The format string creating the YAML source to use. * @ap: The va_list argument pointer * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_vbuildf(struct fy_document *fyd, const char *fmt, va_list ap) FY_EXPORT; /** * fy_node_buildf() - Create a node using the provided YAML source via printf formatting * * Create a node parsing the resulting string as a YAML source. The string * is created by applying printf formatting. * * @fyd: The document * @fmt: The format string creating the YAML source to use. * @...: The printf arguments * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_buildf(struct fy_document *fyd, const char *fmt, ...) FY_FORMAT(printf, 2, 3) FY_EXPORT; /** * fy_node_by_path() - Retrieve a node using the provided path spec. * * This method will retrieve a node relative to the given node using * the provided path spec. * * Path specs are comprised of keys seperated by slashes '/'. * Keys are either regular YAML expressions in flow format for traversing * mappings, or indexes in brackets for traversing sequences. * Path specs may start with '/' which is silently ignored. * * A few examples will make this clear:: * * fyn = { foo: bar } - fy_node_by_path(fyn, "/foo") -> bar * fyn = [ foo, bar ] - fy_node_by_path(fyn, "1") -> bar * fyn = { { foo: bar }: baz } - fy_node_by_path(fyn, "{foo: bar}") -> baz * fyn = [ foo, { bar: baz } } - fy_node_by_path(fyn, "1/bar") -> baz * * Note that the special characters /{}[] are not escaped in plain style, * so you will not be able to use them as path traversal keys. * In that case you can easily use either the single, or double quoted forms:: * * fyn = { foo/bar: baz } - fy_node_by_path(fyn, "'foo/bar'") -> baz * * @fyn: The node to use as start of the traversal operation * @path: The path spec to use in the traversal operation * @len: The length of the path (or -1 if '\0' terminated) * @flags: The extra path walk flags * * Returns: * The retrieved node, or NULL if not possible to be found. */ struct fy_node * fy_node_by_path(struct fy_node *fyn, const char *path, size_t len, enum fy_node_walk_flags flags) FY_EXPORT; /** * fy_node_get_path() - Get the path of this node * * 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. * * @fyn: The node * * Returns: * The node's address, or NULL if fyn is the root. */ char * fy_node_get_path(struct fy_node *fyn) FY_EXPORT; #define fy_node_get_path_alloca(_fyn) \ FY_ALLOCA_COPY_FREE_NO_NULL(fy_node_get_path((_fyn)), FY_NT) /** * fy_node_get_parent() - Get the parent node of a node * * 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. * * @fyn: The node * * Returns: * The node's parent, or NULL if fyn is the root, or the root of a key mapping. */ struct fy_node * fy_node_get_parent(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_document_parent() - Get the document parent node of a node * * 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. * * @fyn: The node * * Returns: * The node's document parent, or NULL if fyn is the root */ struct fy_node * fy_node_get_document_parent(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_parent_address() - Get the path address of this node's parent * * Retrieve the given node's parent path address * The address is dynamically allocated and should be freed when * you're done with it. * * @fyn: The node * * Returns: * The parent's address, or NULL if fyn is the root. */ char * fy_node_get_parent_address(struct fy_node *fyn) FY_EXPORT; #define fy_node_get_parent_address_alloca(_fyn) \ FY_ALLOCA_COPY_FREE_NO_NULL(fy_node_get_parent_address((_fyn)), FY_NT) /** * fy_node_get_path_relative_to() - Get a path address of a node relative * to one of it's parents * * 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. * * @fyn_parent: The node parent/grandparent... * @fyn: The node * * Returns: * The relative address from the parent to the node */ char * fy_node_get_path_relative_to(struct fy_node *fyn_parent, struct fy_node *fyn) FY_EXPORT; #define fy_node_get_path_relative_to_alloca(_fynp, _fyn) \ FY_ALLOCA_COPY_FREE_NO_NULL(fy_node_get_path_relative_to((_fynp), (_fyn)), FY_NT) /** * fy_node_get_short_path() - Get a path address of a node in the shortest path possible * * Retrieve the given nodes short path address relative to the * closest anchor (either on this node, or its parent). * If no such parent is found then returns the absolute path * from the start of the document. * * Example:: * * --- &foo * foo: &bar * bar * baz * * - The short path of /foo is \*foo * - The short path of /foo/bar is \*bar * - The short path of /baz is \*foo/baz * * The address is dynamically allocated and should be freed when * you're done with it. * * @fyn: The node * * Returns: * The shortest path describing the node */ char * fy_node_get_short_path(struct fy_node *fyn) FY_EXPORT; #define fy_node_get_short_path_alloca(_fyn) \ FY_ALLOCA_COPY_FREE_NO_NULL(fy_node_get_short_path((_fyn)), FY_NT) /** * fy_node_get_reference() - Get a textual reference to a node * * Retrieve the given node's textual reference. If the node * contains an anchor the expression that references the anchor * will be returned, otherwise an absolute path reference relative * to the root of the document will be returned. * * The address is dynamically allocated and should be freed when * you're done with it. * * @fyn: The node * * Returns: * The node's text reference. */ char * fy_node_get_reference(struct fy_node *fyn) FY_EXPORT; #define fy_node_get_reference_alloca(_fyn) \ FY_ALLOCA_COPY_FREE_NO_NULL(fy_node_get_reference((_fyn)), FY_NT) /** * fy_node_create_reference() - Create an alias reference node * * 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. * * @fyn: The node * * Returns: * An alias node referencing the argument node */ struct fy_node * fy_node_create_reference(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_relative_reference() - Get a textual reference to a node * relative to a base node. * * Retrieve the given node's textual reference as generated using * another parent (or grand parent) as a base. * If the node contains an anchor the expression that references the anchor * will be returned. * If the base node contains an anchor the reference will be relative to it * otherwise an absolute path reference will be returned. * * The address is dynamically allocated and should be freed when * you're done with it. * * @fyn_base: The base node * @fyn: The node * * Returns: * The node's text reference. */ char * fy_node_get_relative_reference(struct fy_node *fyn_base, struct fy_node *fyn) FY_EXPORT; #define fy_node_get_relative_reference_alloca(_fynb, _fyn) \ FY_ALLOCA_COPY_FREE_NO_NULL(fy_node_get_relative_reference((_fynb), (_fyn)), FY_NT) /** * fy_node_create_relative_reference() - Create an alias reference node * * 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. * * @fyn_base: The base node * @fyn: The node * * Returns: * An alias node referencing the argument node relative to the base */ struct fy_node * fy_node_create_relative_reference(struct fy_node *fyn_base, struct fy_node *fyn) FY_EXPORT; /** * fy_node_create_scalar() - Create a scalar node. * * Create a scalar node using the provided memory area as input. * The input is expected to be regular utf8 encoded. It may contain * escaped characters in which case the style of the scalar will be * set to double quoted. * * Note that the data are not copied, merely a reference is taken, so * it must be available while the node is in use. * * @fyd: The document which the resulting node will be associated with * @data: Pointer to the data area * @size: Size of the data area, or (size_t)-1 for '\0' terminated data. * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_create_scalar(struct fy_document *fyd, const char *data, size_t size) FY_EXPORT; /** * fy_node_create_scalar_copy() - Create a scalar node copying the data. * * Create a scalar node using the provided memory area as input. * The input is expected to be regular utf8 encoded. It may contain * escaped characters in which case the style of the scalar will be * set to double quoted. * * A copy of the data will be made, so it is safe to free the data * after the call. * * @fyd: The document which the resulting node will be associated with * @data: Pointer to the data area * @size: Size of the data area, or (size_t)-1 for '\0' terminated data. * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_create_scalar_copy(struct fy_document *fyd, const char *data, size_t size) FY_EXPORT; /** * fy_node_create_vscalarf() - vprintf interface for creating scalars * * 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. * * @fyd: The document which the resulting node will be associated with * @fmt: The printf based format string * @ap: The va_list containing the arguments * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_create_vscalarf(struct fy_document *fyd, const char *fmt, va_list ap) FY_EXPORT; /** * fy_node_create_scalarf() - printf interface for creating scalars * * 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. * * @fyd: The document which the resulting node will be associated with * @fmt: The printf based format string * @...: The arguments * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_create_scalarf(struct fy_document *fyd, const char *fmt, ...) FY_FORMAT(printf, 2, 3) FY_EXPORT; /** * fy_node_create_sequence() - Create an empty sequence node. * * Create an empty sequence node associated with the given document. * * @fyd: The document which the resulting node will be associated with * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_create_sequence(struct fy_document *fyd) FY_EXPORT; /** * fy_node_create_mapping() - Create an empty mapping node. * * Create an empty mapping node associated with the given document. * * @fyd: The document which the resulting node will be associated with * * Returns: * The created node, or NULL on error. */ struct fy_node * fy_node_create_mapping(struct fy_document *fyd) FY_EXPORT; /** * fy_node_set_tag() - Set the tag of node * * Manually set the tag of a node. The tag must be a valid one for * the document the node belongs to. * * Note that the data are not copied, merely a reference is taken, so * it must be available while the node is in use. * * If the node already contains a tag it will be overwriten. * * @fyn: The node to set it's tag. * @data: Pointer to the tag data. * @len: Size of the tag data, or (size_t)-1 for '\0' terminated. * * Returns: * 0 on success, -1 on error. */ int fy_node_set_tag(struct fy_node *fyn, const char *data, size_t len) FY_EXPORT; /** * fy_node_remove_tag() - Remove the tag of node * * Remove the tag of a node. * * @fyn: The node to remove it's tag. * * Returns: * 0 on success, -1 on error. */ int fy_node_remove_tag(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_tag() - Get the tag of the node * * This method will return a pointer to the text of a tag * along with the length of it. Note that this text is *not* * NULL terminated. * * @fyn: The node * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the tag of the node, while @lenp will be assigned the * length of said tag. * A NULL will be returned in case of an error. */ const char * fy_node_get_tag(struct fy_node *fyn, size_t *lenp) FY_EXPORT; /** * fy_node_get_tag0() - Get the tag of the node * * This method will return a pointer to the text of a tag, * which will be NULL terminated. * * @fyn: The node * * Returns: * A pointer to the null terminated tag of the node. * A NULL will be returned in case of an error. */ const char * fy_node_get_tag0(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_tag_length() - Get the length of the tag of the node * * This method will return the size of the tag of the node. * If the node is not tagged it will return 0. * * @fyn: The tagged node * * Returns: * The size of the tag, or 0 if node is not tagged. */ size_t fy_node_get_tag_length(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_scalar() - Get the scalar content of the node * * This method will return a pointer to the text of the scalar * content of a node along with the length of it. * Note that this pointer is *not* NULL terminated. * * @fyn: The scalar node * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the scalar content of the node, while @lenp will be assigned the * length of said content. * A NULL will be returned in case of an error, i.e. the node is not * a scalar. */ const char * fy_node_get_scalar(struct fy_node *fyn, size_t *lenp) FY_EXPORT; /** * fy_node_get_scalar0() - Get the scalar content of the node * * This method will return a pointer to the text of the scalar * content of a node as a null terminated string. * Note that this call will allocate memory to hold the null terminated * string so if possible use fy_node_get_scalar() * * @fyn: The scalar node * * Returns: * A pointer to the scalar content of the node or NULL in returned in case of an error. */ const char * fy_node_get_scalar0(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_scalar_length() - Get the length of the scalar content * * This method will return the size of the scalar content of the node. * If the node is not a scalar it will return 0. * * @fyn: The scalar node * * Returns: * The size of the scalar content, or 0 if node is not scalar. */ size_t fy_node_get_scalar_length(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_scalar_utf8_length() - Get the length of the scalar content * in utf8 characters * * 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. * * @fyn: The scalar node * * Returns: * The size of the scalar content in utf8 characters, or 0 if node is not scalar. */ size_t fy_node_get_scalar_utf8_length(struct fy_node *fyn) FY_EXPORT; /** * fy_node_sequence_iterate() - Iterate over a sequence node * * This method iterates over all the item nodes in the sequence node. * The start of the iteration is signalled by a NULL in \*prevp. * * @fyn: The sequence node * @prevp: The previous sequence iterator * * Returns: * The next node in sequence or NULL at the end of the sequence. */ struct fy_node * fy_node_sequence_iterate(struct fy_node *fyn, void **prevp) FY_EXPORT; /** * fy_node_sequence_reverse_iterate() - Iterate over a sequence node in reverse * * 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. * * @fyn: The sequence node * @prevp: The previous sequence iterator * * Returns: * The next node in reverse sequence or NULL at the end of the sequence. */ struct fy_node * fy_node_sequence_reverse_iterate(struct fy_node *fyn, void **prevp) FY_EXPORT; /** * fy_node_sequence_item_count() - Return the item count of the sequence * * Get the item count of the sequence. * * @fyn: The sequence node * * Returns: * The count of items in the sequence or -1 in case of an error. */ int fy_node_sequence_item_count(struct fy_node *fyn) FY_EXPORT; /** * fy_node_sequence_is_empty() - Check whether the sequence is empty * * Check whether the sequence contains items. * * @fyn: The sequence node * * Returns: * true if the node is a sequence containing items, false otherwise */ bool fy_node_sequence_is_empty(struct fy_node *fyn) FY_EXPORT; /** * fy_node_sequence_get_by_index() - Return a sequence item by index * * 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. * * @fyn: The sequence node * @index: The index of the node to retrieve. * - >= 0 counting from the start * - < 0 counting from the end * * Returns: * The node at the specified index or NULL if no such item exist. */ struct fy_node * fy_node_sequence_get_by_index(struct fy_node *fyn, int index) FY_EXPORT; /** * fy_node_sequence_append() - Append a node item to a sequence * * Append a node item to a sequence. * * @fyn_seq: The sequence node * @fyn: The node item to append * * Returns: * 0 on success, -1 on error */ int fy_node_sequence_append(struct fy_node *fyn_seq, struct fy_node *fyn) FY_EXPORT; /** * fy_node_sequence_prepend() - Append a node item to a sequence * * Prepend a node item to a sequence. * * @fyn_seq: The sequence node * @fyn: The node item to prepend * * Returns: * 0 on success, -1 on error */ int fy_node_sequence_prepend(struct fy_node *fyn_seq, struct fy_node *fyn) FY_EXPORT; /** * fy_node_sequence_insert_before() - Insert a node item before another * * Insert a node item before another in the sequence. * * @fyn_seq: The sequence node * @fyn_mark: The node item which the node will be inserted before. * @fyn: The node item to insert in the sequence. * * Returns: * 0 on success, -1 on error */ int fy_node_sequence_insert_before(struct fy_node *fyn_seq, struct fy_node *fyn_mark, struct fy_node *fyn) FY_EXPORT; /** * fy_node_sequence_insert_after() - Insert a node item after another * * Insert a node item after another in the sequence. * * @fyn_seq: The sequence node * @fyn_mark: The node item which the node will be inserted after. * @fyn: The node item to insert in the sequence. * * Returns: * 0 on success, -1 on error */ int fy_node_sequence_insert_after(struct fy_node *fyn_seq, struct fy_node *fyn_mark, struct fy_node *fyn) FY_EXPORT; /** * fy_node_sequence_remove() - Remove an item from a sequence * * Remove a node item from a sequence and return it. * * @fyn_seq: The sequence node * @fyn: The node item to remove from the sequence. * * Returns: * The removed node item fyn, or NULL in case of an error. */ struct fy_node * fy_node_sequence_remove(struct fy_node *fyn_seq, struct fy_node *fyn) FY_EXPORT; /** * typedef fy_node_sequence_sort_fn - Sequence sorting method function * * @fyn_a: The first node used in the comparison * @fyn_b: The second node used in the comparison * @arg: The opaque user provided pointer to the sort operation * * Returns: * <0 if @fyn_a is less than @fyn_b * 0 if @fyn_a is equal to fyn_b * >0 if @fyn_a is greater than @fyn_b */ typedef int (*fy_node_sequence_sort_fn)(struct fy_node *fyn_a, struct fy_node *fyn_b, void *arg); /** * fy_node_sequence_sort() - Sort a sequence's items * * Sort the items of a sequence node using the given comparison method. * * @fyn_seq: The sequence node to sort * @cmp: The comparison method * @arg: An opaque user pointer for the comparison method * * Returns: * 0 on success, -1 on error */ int fy_node_sequence_sort(struct fy_node *fyn_seq, fy_node_sequence_sort_fn cmp, void *arg) FY_EXPORT; /** * fy_node_mapping_iterate() - Iterate over a mapping node * * This method iterates over all the node pairs in the mapping node. * The start of the iteration is signalled by a NULL in \*prevp. * * Note that while a mapping is an unordered collection of key/values * the order of which they are created is important for presentation * purposes. * * @fyn: The mapping node * @prevp: The previous sequence iterator * * Returns: * The next node pair in the mapping or NULL at the end of the mapping. */ struct fy_node_pair * fy_node_mapping_iterate(struct fy_node *fyn, void **prevp) FY_EXPORT; /** * fy_node_mapping_reverse_iterate() - Iterate over a mapping node in reverse * * This method iterates in reverse over all the node pairs in the mapping node. * The start of the iteration is signalled by a NULL in \*prevp. * * Note that while a mapping is an unordered collection of key/values * the order of which they are created is important for presentation * purposes. * * @fyn: The mapping node * @prevp: The previous sequence iterator * * Returns: * The next node pair in reverse sequence in the mapping or NULL at the end of the mapping. */ struct fy_node_pair * fy_node_mapping_reverse_iterate(struct fy_node *fyn, void **prevp) FY_EXPORT; /** * fy_node_mapping_item_count() - Return the node pair count of the mapping * * Get the count of the node pairs in the mapping. * * @fyn: The mapping node * * Returns: * The count of node pairs in the mapping or -1 in case of an error. */ int fy_node_mapping_item_count(struct fy_node *fyn) FY_EXPORT; /** * fy_node_mapping_is_empty() - Check whether the mapping is empty * * Check whether the mapping contains any node pairs. * * @fyn: The mapping node * * Returns: * true if the node is a mapping containing node pairs, false otherwise */ bool fy_node_mapping_is_empty(struct fy_node *fyn) FY_EXPORT; /** * fy_node_mapping_get_by_index() - Return a node pair by index * * 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. * * @fyn: The mapping node * @index: The index of the node pair to retrieve. * - >= 0 counting from the start * - < 0 counting from the end * * Returns: * The node pair at the specified index or NULL if no such item exist. */ struct fy_node_pair * fy_node_mapping_get_by_index(struct fy_node *fyn, int index) FY_EXPORT; /** * fy_node_mapping_lookup_pair_by_string() - Lookup a node pair in mapping by string * * This method will return the node pair that contains the same key * from the YAML node created from the @key argument. The comparison of the * node is using fy_node_compare() * * @fyn: The mapping node * @key: The YAML source to use as key * @len: The length of the key (or -1 if '\0' terminated) * * Returns: * The value matching the given key, or NULL if not found. */ struct fy_node_pair * fy_node_mapping_lookup_pair_by_string(struct fy_node *fyn, const char *key, size_t len) FY_EXPORT; /** * fy_node_mapping_lookup_by_string() - Lookup a node value in mapping by string * * This method will return the value of node pair that contains the same key * from the YAML node created from the @key argument. The comparison of the * node is using fy_node_compare() * * @fyn: The mapping node * @key: The YAML source to use as key * @len: The length of the key (or -1 if '\0' terminated) * * Returns: * The value matching the given key, or NULL if not found. */ struct fy_node * fy_node_mapping_lookup_by_string(struct fy_node *fyn, const char *key, size_t len) FY_EXPORT; /** * fy_node_mapping_lookup_value_by_string() - Lookup a node value in mapping by string * * This method will return the value of node pair that contains the same key * from the YAML node created from the @key argument. The comparison of the * node is using fy_node_compare() * * It is synonymous with fy_node_mapping_lookup_by_string(). * * @fyn: The mapping node * @key: The YAML source to use as key * @len: The length of the key (or -1 if '\0' terminated) * * Returns: * The value matching the given key, or NULL if not found. */ struct fy_node * fy_node_mapping_lookup_value_by_string(struct fy_node *fyn, const char *key, size_t len) FY_EXPORT; /** * fy_node_mapping_lookup_key_by_string() - Lookup a node key in mapping by string * * This method will return the key of node pair that contains the same key * from the YAML node created from the @key argument. The comparison of the * node is using fy_node_compare() * * @fyn: The mapping node * @key: The YAML source to use as key * @len: The length of the key (or -1 if '\0' terminated) * * Returns: * The key matching the given key, or NULL if not found. */ struct fy_node * fy_node_mapping_lookup_key_by_string(struct fy_node *fyn, const char *key, size_t len) FY_EXPORT; /** * fy_node_mapping_lookup_pair_by_simple_key() - Lookup a node pair in mapping by simple string * * This method will return the node pair that contains the same key * from the YAML node created from the @key argument. The comparison of the * node is using by comparing the strings for identity. * * @fyn: The mapping node * @key: The string to use as key * @len: The length of the key (or -1 if '\0' terminated) * * Returns: * The node pair matching the given key, or NULL if not found. */ struct fy_node_pair * fy_node_mapping_lookup_pair_by_simple_key(struct fy_node *fyn, const char *key, size_t len) FY_EXPORT; /** * fy_node_mapping_lookup_value_by_simple_key() - Lookup a node value in mapping by simple string * * This method will return the value of node pair that contains the same key * from the YAML node created from the @key argument. The comparison of the * node is using by comparing the strings for identity. * * @fyn: The mapping node * @key: The string to use as key * @len: The length of the key (or -1 if '\0' terminated) * * Returns: * The value matching the given key, or NULL if not found. */ struct fy_node * fy_node_mapping_lookup_value_by_simple_key(struct fy_node *fyn, const char *key, size_t len) FY_EXPORT; /** * fy_node_mapping_lookup_pair_by_null_key() - Lookup a node pair in mapping that has a NULL key * * 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... * * @fyn: The mapping node * * Returns: * The node pair with a NULL key, NULL otherwise */ struct fy_node_pair * fy_node_mapping_lookup_pair_by_null_key(struct fy_node *fyn) FY_EXPORT; /** * fy_node_mapping_lookup_value_by_null_key() - Lookup a node value with a NULL key. * * Return the value of a node pair that has a NULL key. * * @fyn: The mapping node * * Returns: * 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. */ struct fy_node * fy_node_mapping_lookup_value_by_null_key(struct fy_node *fyn) FY_EXPORT; /** * fy_node_mapping_lookup_scalar_by_simple_key() - Lookup a scalar in mapping by simple string * * This method will return the scalar contents that contains the same key * from the YAML node created from the @key argument. The comparison of the * node is using by comparing the strings for identity. * * @fyn: The mapping node * @lenp: Pointer to a variable that will hold the returned length * @key: The string to use as key * @keylen: The length of the key (or -1 if '\0' terminated) * * Returns: * The scalar contents matching the given key, or NULL if not found. */ const char * fy_node_mapping_lookup_scalar_by_simple_key(struct fy_node *fyn, size_t *lenp, const char *key, size_t keylen) FY_EXPORT; /** * fy_node_mapping_lookup_scalar0_by_simple_key() - Lookup a scalar in mapping by simple string * returning a '\0' terminated scalar * * This method will return the NUL terminated scalar contents that contains the same key * from the YAML node created from the @key argument. The comparison of the * node is using by comparing the strings for identity. * * @fyn: The mapping node * @key: The string to use as key * @keylen: The length of the key (or -1 if '\0' terminated) * * Returns: * The NUL terminated scalar contents matching the given key, or NULL if not found. */ const char * fy_node_mapping_lookup_scalar0_by_simple_key(struct fy_node *fyn, const char *key, size_t keylen) FY_EXPORT; /** * fy_node_mapping_lookup_pair() - Lookup a node pair matching the provided key * * This method will return the node pair that matches the provided @fyn_key * * @fyn: The mapping node * @fyn_key: The node to use as key * * Returns: * The node pair matching the given key, or NULL if not found. */ struct fy_node_pair * fy_node_mapping_lookup_pair(struct fy_node *fyn, struct fy_node *fyn_key) FY_EXPORT; /** * fy_node_mapping_lookup_value_by_key() - Lookup a node pair's value matching the provided key * * This method will return the node pair that matches the provided @fyn_key * The key may be collection and a content match check is performed recursively * in order to find the right key. * * @fyn: The mapping node * @fyn_key: The node to use as key * * Returns: * The node value matching the given key, or NULL if not found. */ struct fy_node * fy_node_mapping_lookup_value_by_key(struct fy_node *fyn, struct fy_node *fyn_key); /** * fy_node_mapping_lookup_key_by_key() - Lookup a node pair's key matching the provided key * * This method will return the node pair that matches the provided @fyn_key * The key may be collection and a content match check is performed recursively * in order to find the right key. * * @fyn: The mapping node * @fyn_key: The node to use as key * * Returns: * The node key matching the given key, or NULL if not found. */ struct fy_node * fy_node_mapping_lookup_key_by_key(struct fy_node *fyn, struct fy_node *fyn_key); /** * fy_node_mapping_get_pair_index() - Return the node pair index in the mapping * * This method will return the node pair index in the mapping of the given * node pair argument. * * @fyn: The mapping node * @fynp: The node pair * * Returns: * The index of the node pair in the mapping or -1 in case of an error. */ int fy_node_mapping_get_pair_index(struct fy_node *fyn, const struct fy_node_pair *fynp) FY_EXPORT; /** * fy_node_pair_key() - Return the key of a node pair * * 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. * * @fynp: The node pair * * Returns: * The node pair key */ struct fy_node * fy_node_pair_key(struct fy_node_pair *fynp) FY_EXPORT; /** * fy_node_pair_value() - Return the value of a node pair * * 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. * * @fynp: The node pair * * Returns: * The node pair value */ struct fy_node * fy_node_pair_value(struct fy_node_pair *fynp) FY_EXPORT; /** * fy_node_pair_set_key() - Sets the key of a node pair * * This method will set the key part of the node pair. * It will ovewrite any previous key. * * Note that no checks for duplicate keys are going to be * performed. * * @fynp: The node pair * @fyn: The key node * * Returns: * 0 on success, -1 on error */ int fy_node_pair_set_key(struct fy_node_pair *fynp, struct fy_node *fyn) FY_EXPORT; /** * fy_node_pair_set_value() - Sets the value of a node pair * * This method will set the value part of the node pair. * It will ovewrite any previous value. * * @fynp: The node pair * @fyn: The value node * * Returns: * 0 on success, -1 on error */ int fy_node_pair_set_value(struct fy_node_pair *fynp, struct fy_node *fyn) FY_EXPORT; /** * fy_node_mapping_append() - Append a node item to a mapping * * Append a node pair to a mapping. * * @fyn_map: The mapping node * @fyn_key: The node pair's key * @fyn_value: The node pair's value * * Returns: * 0 on success, -1 on error */ int fy_node_mapping_append(struct fy_node *fyn_map, struct fy_node *fyn_key, struct fy_node *fyn_value) FY_EXPORT; /** * fy_node_mapping_prepend() - Prepend a node item to a mapping * * Prepend a node pair to a mapping. * * @fyn_map: The mapping node * @fyn_key: The node pair's key * @fyn_value: The node pair's value * * Returns: * 0 on success, -1 on error */ int fy_node_mapping_prepend(struct fy_node *fyn_map, struct fy_node *fyn_key, struct fy_node *fyn_value) FY_EXPORT; /** * fy_node_mapping_remove() - Remove a node pair from a mapping * * Remove node pair from a mapping. * * @fyn_map: The mapping node * @fynp: The node pair to remove * * Returns: * 0 on success, -1 on failure. */ int fy_node_mapping_remove(struct fy_node *fyn_map, struct fy_node_pair *fynp) FY_EXPORT; /** * fy_node_mapping_sort() - Sort a single mapping's keys * * Sort the keys of a single mapping node using the given comparison method (if NULL use the default one). * Unlike fy_node_sort(), this does not recurse into child nodes. * * @fyn_map: The mapping node to sort * @key_cmp: The comparison method * @arg: An opaque user pointer for the comparison method * * Returns: * 0 on success, -1 on error */ int fy_node_mapping_sort(struct fy_node *fyn_map, fy_node_mapping_sort_fn key_cmp, void *arg) FY_EXPORT; /** * fy_node_mapping_remove_by_key() - Remove a node pair from a mapping returning the value * * Remove node pair from a mapping using the supplied key. * * @fyn_map: The mapping node * @fyn_key: The node pair's key * * Returns: * The value part of removed node pair, or NULL in case of an error. */ struct fy_node * fy_node_mapping_remove_by_key(struct fy_node *fyn_map, struct fy_node *fyn_key) FY_EXPORT; /** * fy_node_sort() - Recursively sort node * * Recursively sort all mappings of the given node, using the given * comparison method (if NULL use the default one). * * @fyn: The node to sort * @key_cmp: The comparison method * @arg: An opaque user pointer for the comparison method * * Returns: * 0 on success, -1 on error */ int fy_node_sort(struct fy_node *fyn, fy_node_mapping_sort_fn key_cmp, void *arg) FY_EXPORT; /** * fy_node_vscanf() - Retrieve data via vscanf * * This method easily retrieves data using a familiar vscanf interface. * The format string is a regular scanf format string with the following format. * * "pathspec %opt pathspec %opt..." * * Each pathspec is separated with space from the scanf option * * For example: * fyn = { foo: 3 } -> fy_node_scanf(fyn, "/foo %d", &var) -> var = 3 * * * @fyn: The node to use as a pathspec root * @fmt: The scanf based format string * @ap: The va_list containing the arguments * * Returns: * The number of scanned arguments, or -1 on error. */ int fy_node_vscanf(struct fy_node *fyn, const char *fmt, va_list ap); /** * fy_node_scanf() - Retrieve data via scanf * * This method easily retrieves data using a familiar vscanf interface. * The format string is a regular scanf format string with the following format. * * "pathspec %opt pathspec %opt..." * * Each pathspec is separated with space from the scanf option * * For example: * fyn = { foo: 3 } -> fy_node_scanf(fyn, "/foo %d", &var) -> var = 3 * * * @fyn: The node to use as a pathspec root * @fmt: The scanf based format string * @...: The arguments * * Returns: * The number of scanned arguments, or -1 on error. */ int fy_node_scanf(struct fy_node *fyn, const char *fmt, ...) FY_FORMAT(scanf, 2, 3) FY_EXPORT; /** * fy_document_vscanf() - Retrieve data via vscanf relative to document root * * This method easily retrieves data using a familiar vscanf interface. * The format string is a regular scanf format string with the following format. * * "pathspec %opt pathspec %opt..." * * Each pathspec is separated with space from the scanf option * * For example: * fyd = { foo: 3 } -> fy_document_scanf(fyd, "/foo %d", &var) -> var = 3 * * * @fyd: The document * @fmt: The scanf based format string * @ap: The va_list containing the arguments * * Returns: * The number of scanned arguments, or -1 on error. */ int fy_document_vscanf(struct fy_document *fyd, const char *fmt, va_list ap) FY_EXPORT; /** * fy_document_scanf() - Retrieve data via scanf relative to document root * * This method easily retrieves data using a familiar vscanf interface. * The format string is a regular scanf format string with the following format. * * "pathspec %opt pathspec %opt..." * * Each pathspec is separated with space from the scanf option * * For example: * fyn = { foo: 3 } -> fy_node_scanf(fyd, "/foo %d", &var) -> var = 3 * * * @fyd: The document * @fmt: The scanf based format string * @...: The arguments * * Returns: * The number of scanned arguments, or -1 on error. */ int fy_document_scanf(struct fy_document *fyd, const char *fmt, ...) FY_FORMAT(scanf, 2, 3) FY_EXPORT; /** * fy_document_tag_directive_iterate() - Iterate over a document's tag directives * * This method iterates over all the documents tag directives. * The start of the iteration is signalled by a NULL in \*prevp. * * @fyd: The document * @prevp: The previous state of the iterator * * Returns: * The next tag directive token in the document or NULL at the end of them. */ struct fy_token * fy_document_tag_directive_iterate(struct fy_document *fyd, void **prevp) FY_EXPORT; /** * fy_document_tag_directive_lookup() - Retreive a document's tag directive * * Retreives the matching tag directive token of the document matching the handle. * * @fyd: The document * @handle: The handle to look for * * Returns: * The tag directive token with the given handle or NULL if not found */ struct fy_token * fy_document_tag_directive_lookup(struct fy_document *fyd, const char *handle) FY_EXPORT; /** * fy_tag_directive_token_handle() - Get a tag directive handle * * Retreives the tag directives token handle value. Only valid on * tag directive tokens. * * @fyt: The tag directive token * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the tag directive's handle, while @lenp will be assigned the * length of said handle. * A NULL will be returned in case of an error. */ const char * fy_tag_directive_token_handle(struct fy_token *fyt, size_t *lenp) FY_EXPORT; /** * fy_tag_directive_token_prefix() - Get a tag directive prefix * * Retreives the tag directives token prefix value. Only valid on * tag directive tokens. * * @fyt: The tag directive token * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the tag directive's prefix, while @lenp will be assigned the * length of said prefix. * A NULL will be returned in case of an error. */ const char * fy_tag_directive_token_prefix(struct fy_token *fyt, size_t *lenp) FY_EXPORT; /** * fy_document_tag_directive_add() - Add a tag directive to a document * * Add tag directive to the document. * * @fyd: The document * @handle: The handle of the tag directive * @prefix: The prefix of the tag directive * * Returns: * 0 on success, -1 on error */ int fy_document_tag_directive_add(struct fy_document *fyd, const char *handle, const char *prefix) FY_EXPORT; /** * fy_document_tag_directive_remove() - Remove a tag directive * * Remove a tag directive from a document. * Note that removal is prohibited if any node is still using this tag directive. * * @fyd: The document * @handle: The handle of the tag directive to remove. * * Returns: * 0 on success, -1 on error */ int fy_document_tag_directive_remove(struct fy_document *fyd, const char *handle) FY_EXPORT; /** * fy_document_lookup_anchor() - Lookup an anchor * * Lookup for an anchor having the name provided * * @fyd: The document * @anchor: The anchor to look for * @len: The length of the anchor (or -1 if '\0' terminated) * * Returns: * The anchor if found, NULL otherwise */ struct fy_anchor * fy_document_lookup_anchor(struct fy_document *fyd, const char *anchor, size_t len) FY_EXPORT; /** * fy_document_lookup_anchor_by_token() - Lookup an anchor by token text * * Lookup for an anchor having the name provided from the text of the token * * @fyd: The document * @anchor: The token contains the anchor text to look for * * Returns: * The anchor if found, NULL otherwise */ struct fy_anchor * fy_document_lookup_anchor_by_token(struct fy_document *fyd, struct fy_token *anchor) FY_EXPORT; /** * fy_document_lookup_anchor_by_node() - Lookup an anchor by node * * Lookup for an anchor located in the given node * * @fyd: The document * @fyn: The node * * Returns: * The anchor if found, NULL otherwise */ struct fy_anchor * fy_document_lookup_anchor_by_node(struct fy_document *fyd, struct fy_node *fyn) FY_EXPORT; /** * fy_anchor_get_text() - Get the text of an anchor * * This method will return a pointer to the text of an anchor * along with the length of it. Note that this text is *not* * NULL terminated. * * @fya: The anchor * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the text of the anchor, while @lenp will be assigned the * length of said anchor. * A NULL will be returned in case of an error. */ const char * fy_anchor_get_text(struct fy_anchor *fya, size_t *lenp) FY_EXPORT; /** * fy_anchor_node() - Get the node of an anchor * * This method returns the node associated with the anchor. * * @fya: The anchor * * Returns: * The node of the anchor, or NULL in case of an error. */ struct fy_node * fy_anchor_node(struct fy_anchor *fya) FY_EXPORT; /** * fy_document_anchor_iterate() - Iterate over a document's anchors * * This method iterates over all the documents anchors. * The start of the iteration is signalled by a NULL in \*prevp. * * @fyd: The document * @prevp: The previous state of the iterator * * Returns: * The next anchor in the document or NULL at the end of them. */ struct fy_anchor * fy_document_anchor_iterate(struct fy_document *fyd, void **prevp) FY_EXPORT; /** * fy_document_set_anchor() - Place an anchor * * Places an anchor to the node with the give text name. * * Note that the data are not copied, merely a reference is taken, so * it must be available while the node is in use. * * Also not that this method is deprecated; use fy_node_set_anchor() * instead. * * @fyd: The document * @fyn: The node to set the anchor to * @text: Pointer to the anchor text * @len: Size of the anchor text, or (size_t)-1 for '\0' terminated. * * Returns: * 0 on success, -1 on error. */ int fy_document_set_anchor(struct fy_document *fyd, struct fy_node *fyn, const char *text, size_t len) FY_EXPORT FY_DEPRECATED; /** * fy_node_set_anchor() - Place an anchor to the node * * Places an anchor to the node with the give text name. * * Note that the data are not copied, merely a reference is taken, so * it must be available while the node is in use. * * This is similar to fy_document_set_anchor() with the document set * to the document of the @fyn node. * * @fyn: The node to set the anchor to * @text: Pointer to the anchor text * @len: Size of the anchor text, or (size_t)-1 for '\0' terminated. * * Returns: * 0 on success, -1 on error. */ int fy_node_set_anchor(struct fy_node *fyn, const char *text, size_t len) FY_EXPORT; /** * fy_node_set_anchor_copy() - Place an anchor to the node copying the text * * 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. * * @fyn: The node to set the anchor to * @text: Pointer to the anchor text * @len: Size of the anchor text, or (size_t)-1 for '\0' terminated. * * Returns: * 0 on success, -1 on error. */ int fy_node_set_anchor_copy(struct fy_node *fyn, const char *text, size_t len) FY_EXPORT; /** * fy_node_set_vanchorf() - Place an anchor to the node using a vprintf interface. * * Places an anchor to the node with the give text name as created * via vprintf'ing the arguments. * * @fyn: The node to set the anchor to * @fmt: Pointer to the anchor format string * @ap: The argument list. * * Returns: * 0 on success, -1 on error. */ int fy_node_set_vanchorf(struct fy_node *fyn, const char *fmt, va_list ap) FY_EXPORT; /** * fy_node_set_anchorf() - Place an anchor to the node using a printf interface. * * Places an anchor to the node with the give text name as created * via printf'ing the arguments. * * @fyn: The node to set the anchor to * @fmt: Pointer to the anchor format string * @...: The extra arguments. * * Returns: * 0 on success, -1 on error. */ int fy_node_set_anchorf(struct fy_node *fyn, const char *fmt, ...) FY_FORMAT(printf, 2, 3) FY_EXPORT; /** * fy_node_remove_anchor() - Remove an anchor * * Remove an anchor for the given node (if it exists) * * @fyn: The node to remove anchors from * * Returns: * 0 on success, -1 on error. */ int fy_node_remove_anchor(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_anchor() - Get the anchor of a node * * Retrieve the anchor of the given node (if it exists) * * @fyn: The node * * Returns: * The anchor if there's one at the node, or NULL otherwise */ struct fy_anchor * fy_node_get_anchor(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_nearest_anchor() - Get the nearest anchor of the node * * Retrieve the anchor of the nearest parent of the given node or * the given node if it has one. * * @fyn: The node * * Returns: * The nearest anchor if there's one, or NULL otherwise */ struct fy_anchor * fy_node_get_nearest_anchor(struct fy_node *fyn) FY_EXPORT; /** * fy_node_get_nearest_child_of() - Get the nearest node which is a * child of the base * * Retrieve the nearest node which is a child of fyn_base starting * at fyn and working upwards. * * @fyn_base: The base node * @fyn: The node to start from * * Returns: * The nearest child of the base if there's one, or NULL otherwise */ struct fy_node * fy_node_get_nearest_child_of(struct fy_node *fyn_base, struct fy_node *fyn) FY_EXPORT; /** * fy_node_create_alias() - Create an alias node * * Create an alias on the given document * * Note that the data are not copied, merely a reference is taken, so * it must be available while the node is in use. * * @fyd: The document * @alias: The alias text * @len: The length of the alias (or -1 if '\0' terminated) * * Returns: * The created alias node, or NULL in case of an error */ struct fy_node * fy_node_create_alias(struct fy_document *fyd, const char *alias, size_t len) FY_EXPORT; /** * fy_node_create_alias_copy() - Create an alias node copying the data * * Create an alias on the given document * * A copy of the data will be made, so it is safe to free the data * after the call. * * @fyd: The document * @alias: The alias text * @len: The length of the alias (or -1 if '\0' terminated) * * Returns: * The created alias node, or NULL in case of an error */ struct fy_node * fy_node_create_alias_copy(struct fy_document *fyd, const char *alias, size_t len) FY_EXPORT; /** * fy_node_get_meta() - Get the meta pointer of a node * * Return the meta pointer of a node. * * @fyn: The node to get meta data from * * Returns: * The stored meta data pointer */ void * fy_node_get_meta(struct fy_node *fyn) FY_EXPORT; /** * fy_node_set_meta() - Set the meta pointer of a node * * Set the meta pointer of a node. If @meta is NULL * then clear the meta data. * * @fyn: The node to set meta data * @meta: The meta data pointer * * Returns: * 0 on success, -1 on error */ int fy_node_set_meta(struct fy_node *fyn, void *meta) FY_EXPORT; /** * fy_node_clear_meta() - Clear the meta data of a node * * Clears the meta data of a node. * * @fyn: The node to clear meta data */ void fy_node_clear_meta(struct fy_node *fyn) FY_EXPORT; /** * typedef fy_node_meta_clear_fn - Meta data clear method * * This is the callback called when meta data are cleared. * * @fyn: The node which the meta data is being cleared * @meta: The meta data of the node assigned via fy_node_set_meta() * @user: The user pointer of fy_document_register_meta() * */ typedef void (*fy_node_meta_clear_fn)(struct fy_node *fyn, void *meta, void *user); /** * fy_document_register_meta() - Register a meta cleanup hook * * Register a meta data cleanup hook, to be called when * the node is freed via a final call to fy_node_free(). * The hook is active for all nodes belonging to the document. * * @fyd: The document which the hook is registered to * @clear_fn: The clear hook method * @user: Opaque user provided pointer to the clear method * * Returns: * 0 on success, -1 if another hook is already registered. */ int fy_document_register_meta(struct fy_document *fyd, fy_node_meta_clear_fn clear_fn, void *user) FY_EXPORT; /** * fy_document_unregister_meta() - Unregister a meta cleanup hook * * Unregister the currently active meta cleanup hook. * The previous cleanup hook will be called for every node in * the document. * * @fyd: The document to unregister it's meta cleanup hook. */ void fy_document_unregister_meta(struct fy_document *fyd) FY_EXPORT; /** * fy_node_set_marker() - Set a marker of a node * * 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. * * @fyn: The node * @marker: The marker to set * * Returns: * The previous value of the marker */ bool fy_node_set_marker(struct fy_node *fyn, unsigned int marker) FY_EXPORT; /** * fy_node_clear_marker() - Clear a marker of a node * * 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. * * @fyn: The node * @marker: The marker to clear * * Returns: * The previous value of the marker */ bool fy_node_clear_marker(struct fy_node *fyn, unsigned int marker) FY_EXPORT; /** * fy_node_is_marker_set() - Checks whether a marker is set * * Check the state of the given marker. * * @fyn: The node * @marker: The marker index (must be less that FYNWF_MAX_USER_MARKER) * * Returns: * The value of the marker (invalid markers return false) */ bool fy_node_is_marker_set(struct fy_node *fyn, unsigned int marker) FY_EXPORT; /** * fy_node_vreport() - Report about a node vprintf style * * Output a report about the given node via the specific * error type, and using the reporting configuration of the node's * document. * * @fyn: The node * @type: The error type * @fmt: The printf format string * @ap: The argument list */ void fy_node_vreport(struct fy_node *fyn, enum fy_error_type type, const char *fmt, va_list ap) FY_EXPORT; /** * fy_node_report() - Report about a node printf style * * Output a report about the given node via the specific * error type, and using the reporting configuration of the node's * document. * * @fyn: The node * @type: The error type * @fmt: The printf format string * @...: The extra arguments. */ void fy_node_report(struct fy_node *fyn, enum fy_error_type type, const char *fmt, ...) FY_FORMAT(printf, 3, 4) FY_EXPORT; /** * fy_node_override_vreport() - Report about a node vprintf style, * overriding file, line and column info * * Output a report about the given node via the specific * error type, and using the reporting configuration of the node's * document. This method will use the overrides provided in order * to massage the reporting information. * If @file is NULL, no file location will be reported. * If either @line or @column is negative no location will be reported. * * @fyn: The node * @type: The error type * @file: The file override * @line: The line override * @column: The column override * @fmt: The printf format string * @ap: The argument list */ void fy_node_override_vreport(struct fy_node *fyn, enum fy_error_type type, const char *file, int line, int column, const char *fmt, va_list ap) FY_EXPORT; /** * fy_node_override_report() - Report about a node printf style, * overriding file, line and column info * * Output a report about the given node via the specific * error type, and using the reporting configuration of the node's * document. This method will use the overrides provided in order * to massage the reporting information. * If @file is NULL, no file location will be reported. * If either @line or @column is negative no location will be reported. * * @fyn: The node * @type: The error type * @file: The file override * @line: The line override * @column: The column override * @fmt: The printf format string * @...: The extra arguments. */ void fy_node_override_report(struct fy_node *fyn, enum fy_error_type type, const char *file, int line, int column, const char *fmt, ...) FY_FORMAT(printf, 6, 7) FY_EXPORT; /** * fy_event_vreport() - Report about an event vprintf style * * Output a report about the given event via the specific * error type, focusing at the given event part. * * @fyp: The parser of which the event was generated from * @fye: The event * @fyep: The event part which the report is about * @type: The error type * @fmt: The printf format string * @ap: The argument list */ void fy_event_vreport(struct fy_parser *fyp, struct fy_event *fye, enum fy_event_part fyep, enum fy_error_type type, const char *fmt, va_list ap) FY_EXPORT; /** * fy_event_report() - Report about an event printf style * * Output a report about the given event via the specific * error type, focusing at the given event part. * * @fyp: The parser of which the event was generated from * @fye: The event * @fyep: The event part which the report is about * @type: The error type * @fmt: The printf format string * @...: The extra arguments. */ void fy_event_report(struct fy_parser *fyp, struct fy_event *fye, enum fy_event_part fyep, enum fy_error_type type, const char *fmt, ...) FY_FORMAT(printf, 5, 6) FY_EXPORT; typedef void (*fy_diag_output_fn)(struct fy_diag *diag, void *user, const char *buf, size_t len); /** * struct fy_diag_cfg - The diagnostics configuration * * @fp: File descriptor of the error output * @output_fn: Callback to use when fp is NULL * @user: User pointer to pass to the output_fn * @level: The minimum debugging level * @module_mask: A bitmask of the enabled modules * @colorize: true if output should be colorized using ANSI sequences * @show_source: true if source location should be displayed * @show_position: true if position should be displayed * @show_type: true if the type should be displayed * @show_module: true if the module should be displayed * @source_width: Width of the source field * @position_width: Width of the position field * @type_width: Width of the type field * @module_width: Width of the module field * * This structure contains the configuration of the * diagnostic object. */ 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; }; /** * struct fy_diag_error - A collected diagnostic error * * @type: Error type * @module: The module * @fyt: The token (may be NULL) * @msg: The message to be output alongside * @file: The file which contained the input * @line: The line at the error * @column: The column at the error * * This structure contains information about an error * being collected by the diagnostic object. */ 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; }; /** * fy_diag_create() - Create a diagnostic object * * Creates a diagnostic object using the provided configuration. * * @cfg: The configuration for the diagnostic object (NULL is default) * * Returns: * A pointer to the diagnostic object or NULL in case of an error. */ struct fy_diag * fy_diag_create(const struct fy_diag_cfg *cfg) FY_EXPORT; /** * fy_diag_destroy() - Destroy a diagnostic object * * 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. * * @diag: The diagnostic object to destroy */ void fy_diag_destroy(struct fy_diag *diag) FY_EXPORT; /** * fy_diag_get_cfg() - Get a diagnostic object's configuration * * Return the current configuration of a diagnostic object * * @diag: The diagnostic object * * Returns: * A const pointer to the diagnostic object configuration, or NULL * in case where diag is NULL */ const struct fy_diag_cfg * fy_diag_get_cfg(struct fy_diag *diag) FY_EXPORT; /** * fy_diag_set_cfg() - Set a diagnostic object's configuration * * Replace the current diagnostic configuration with the given * configuration passed as an argument. * * @diag: The diagnostic object * @cfg: The diagnostic configuration */ void fy_diag_set_cfg(struct fy_diag *diag, const struct fy_diag_cfg *cfg) FY_EXPORT; /** * fy_diag_set_level() - Set a diagnostic object's debug error level * * @diag: The diagnostic object * @level: The debugging level to set */ void fy_diag_set_level(struct fy_diag *diag, enum fy_error_type level); /** * fy_diag_set_colorize() - Set a diagnostic object's colorize option * * @diag: The diagnostic object * @colorize: The colorize option */ void fy_diag_set_colorize(struct fy_diag *diag, bool colorize); /** * fy_diag_ref() - Increment that reference counter of a diagnostic object * * Increment the reference. * * @diag: The diagnostic object to reference * * Returns: * Always returns the @diag argument */ struct fy_diag * fy_diag_ref(struct fy_diag *diag) FY_EXPORT; /** * fy_diag_unref() - Take away a ref from a diagnostic object * * Take away a reference, if it gets to 0, the diagnostic object * is freed. * * @diag: The diagnostic object to unref */ void fy_diag_unref(struct fy_diag *diag) FY_EXPORT; /** * fy_diag_got_error() - Test whether an error level diagnostic * has been produced * * Tests whether an error diagnostic has been produced. * * @diag: The diagnostic object * * Returns: * true if an error has been produced, false otherwise */ bool fy_diag_got_error(struct fy_diag *diag) FY_EXPORT; /** * fy_diag_set_error() - Sets the error produced state * * Sets the error produced state * * @diag: The diagnostic object * @on_error: The set error state */ void fy_diag_set_error(struct fy_diag *diag, bool on_error) FY_EXPORT; /** * fy_diag_reset_error() - Reset the error flag of * the diagnostic object * * Clears the error flag which was set by an output * of an error level diagnostic * * @diag: The diagnostic object */ void fy_diag_reset_error(struct fy_diag *diag) FY_EXPORT; /** * fy_diag_set_collect_errors() - Collect errors instead of outputting * * Set the collect errors mode. When true instead of outputting to * the diagnostic interface, errors are collected for later * retrieval. * * @diag: The diagnostic object * @collect_errors: The collect errors mode */ void fy_diag_set_collect_errors(struct fy_diag *diag, bool collect_errors) FY_EXPORT; /** * fy_diag_get_collect_errors() - Get collect errors state * * Get the collect errors mode. * * @diag: The diagnostic object * * Returns: * true collecting errors, false otherwise */ bool fy_diag_get_collect_errors(struct fy_diag *diag) FY_EXPORT; /** * fy_diag_cfg_default() - Fill in the configuration structure * with defaults * * Fills the configuration structure with defaults. The default * always associates the file descriptor to stderr. * * @cfg: The diagnostic configuration structure */ void fy_diag_cfg_default(struct fy_diag_cfg *cfg) FY_EXPORT; /** * fy_diag_cfg_from_parser_flags() - Fill partial diagnostic config * structure from parser config flags * * Fills in part of the configuration structure using parser flags. * Since the parser flags do not contain debugging flags anymore this * method is deprecated. * * @cfg: The diagnostic configuration structure * @pflags: The parser flags */ void fy_diag_cfg_from_parser_flags(struct fy_diag_cfg *cfg, enum fy_parse_cfg_flags pflags) FY_EXPORT FY_DEPRECATED; /** * fy_diag_vprintf() - vprintf raw interface to diagnostics * * 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. * * @diag: The diagnostic object to use * @fmt: The vprintf format string * @ap: The arguments * * Returns: * 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. */ int fy_diag_vprintf(struct fy_diag *diag, const char *fmt, va_list ap) FY_EXPORT; /** * fy_diag_printf() - printf raw interface to diagnostics * * 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. * * @diag: The diagnostic object to use * @fmt: The printf format string * @...: The arguments * * Returns: * 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. */ int fy_diag_printf(struct fy_diag *diag, const char *fmt, ...) FY_FORMAT(printf, 2, 3) FY_EXPORT; /** * struct fy_diag_ctx - The diagnostics context * * @level: The level of the diagnostic * @module: The module of the diagnostic * @source_func: The source function * @source_file: The source file * @source_line: The source line * @file: The file that caused the error * @line: The line where the diagnostic occured * @column: The column where the diagnostic occured * * This structure contains the diagnostic context */ 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; }; /** * fy_vdiag() - context aware diagnostic output like vprintf * * Context aware output to the diagnostic object using a standard * vprintf interface. * * @diag: The diagnostic object to use * @fydc: The diagnostic context * @fmt: The vprintf format string * @ap: The arguments * * Returns: * 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. */ int fy_vdiag(struct fy_diag *diag, const struct fy_diag_ctx *fydc, const char *fmt, va_list ap) FY_EXPORT; /** * fy_diagf() - context aware diagnostic output like printf * * Context aware output to the diagnostic object using a standard * printf interface. * * @diag: The diagnostic object to use * @fydc: The diagnostic context * @fmt: The vprintf format string * * Returns: * 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. */ int fy_diagf(struct fy_diag *diag, const struct fy_diag_ctx *fydc, const char *fmt, ...) FY_FORMAT(printf, 3, 4) FY_EXPORT; #ifdef _MSC_VER /* MSVC doesn't support GCC statement expressions, use do-while(0) instead */ #define fy_diag_diag(_diag, _level, _fmt, ...) \ do { \ struct fy_diag_ctx _ctx; \ memset(&_ctx, 0, sizeof(_ctx)); \ _ctx.level = (_level); \ _ctx.module = FYEM_UNKNOWN; \ _ctx.source_func = __func__; \ _ctx.source_file = __FILE__; \ _ctx.source_line = __LINE__; \ fy_diagf((_diag), &_ctx, (_fmt) , ## __VA_ARGS__); \ } while(0) #else #define fy_diag_diag(_diag, _level, _fmt, ...) \ ({ \ struct fy_diag_ctx _ctx = { \ .level = (_level), \ .module = FYEM_UNKNOWN, \ .source_func = __func__, \ .source_file = __FILE__, \ .source_line = __LINE__, \ .file = NULL, \ .line = 0, \ .column = 0, \ }; \ fy_diagf((_diag), &_ctx, (_fmt) , ## __VA_ARGS__); \ }) #endif #ifndef NDEBUG #define fy_debug(_diag, _fmt, ...) \ fy_diag_diag((_diag), FYET_DEBUG, (_fmt) , ## __VA_ARGS__) #else #define fy_debug(_diag, _fmt, ...) \ do { } while(0) #endif #define fy_info(_diag, _fmt, ...) \ fy_diag_diag((_diag), FYET_INFO, (_fmt) , ## __VA_ARGS__) #define fy_notice(_diag, _fmt, ...) \ fy_diag_diag((_diag), FYET_NOTICE, (_fmt) , ## __VA_ARGS__) #define fy_warning(_diag, _fmt, ...) \ fy_diag_diag((_diag), FYET_WARNING, (_fmt) , ## __VA_ARGS__) #define fy_error(_diag, _fmt, ...) \ fy_diag_diag((_diag), FYET_ERROR, (_fmt) , ## __VA_ARGS__) /** * fy_diag_token_vreport() - Report about a token vprintf style using * the given diagnostic object * * Output a report about the given token via the specific * error type, and using the reporting configuration of the token's * document. * * @diag: The diag object * @fyt: The token * @type: The error type * @fmt: The printf format string * @ap: The argument list */ void fy_diag_token_vreport(struct fy_diag *diag, struct fy_token *fyt, enum fy_error_type type, const char *fmt, va_list ap) FY_EXPORT; /** * fy_diag_token_report() - Report about a token printf style using * the given diagnostic object * * Output a report about the given token via the specific * error type, and using the reporting configuration of the token's * document. * * @diag: The diag object * @fye: The token * @type: The error type * @fmt: The printf format string * @...: The extra arguments. */ void fy_diag_token_report(struct fy_diag *diag, struct fy_token *fye, enum fy_error_type type, const char *fmt, ...) FY_FORMAT(printf, 4, 5) FY_EXPORT; /** * fy_diag_token_override_vreport() - Report about a token vprintf style, * overriding file, line and column info using * the given diagnostic object * * Output a report about the given token via the specific * error type, and using the reporting configuration of the token's * document. This method will use the overrides provided in order * to massage the reporting information. * If @file is NULL, no file location will be reported. * If either @line or @column is negative no location will be reported. * * @diag: The diag object * @fyt: The token * @type: The error type * @file: The file override * @line: The line override * @column: The column override * @fmt: The printf format string * @ap: The argument list */ void fy_diag_token_override_vreport(struct fy_diag *diag, struct fy_token *fyt, enum fy_error_type type, const char *file, int line, int column, const char *fmt, va_list ap) FY_EXPORT; /** * fy_diag_token_override_report() - Report about a token printf style, * overriding file, line and column info using * the given diagnostic object * * Output a report about the given token via the specific * error type, and using the reporting configuration of the token's * document. This method will use the overrides provided in order * to massage the reporting information. * If @file is NULL, no file location will be reported. * If either @line or @column is negative no location will be reported. * * @diag: The diag object * @fyt: The token * @type: The error type * @file: The file override * @line: The line override * @column: The column override * @fmt: The printf format string * @...: The extra arguments. */ void fy_diag_token_override_report(struct fy_diag *diag, struct fy_token *fyt, enum fy_error_type type, const char *file, int line, int column, const char *fmt, ...) FY_FORMAT(printf, 7, 8) FY_EXPORT; /** * fy_diag_node_vreport() - Report about a node vprintf style using * the given diagnostic object * * Output a report about the given node via the specific * error type, and using the reporting configuration of the node's * document. * * @diag: The diag object * @fyn: The node * @type: The error type * @fmt: The printf format string * @ap: The argument list */ void fy_diag_node_vreport(struct fy_diag *diag, struct fy_node *fyn, enum fy_error_type type, const char *fmt, va_list ap) FY_EXPORT; /** * fy_diag_node_report() - Report about a node printf style using * the given diagnostic object * * Output a report about the given node via the specific * error type, and using the reporting configuration of the node's * document. * * @diag: The diag object * @fyn: The node * @type: The error type * @fmt: The printf format string * @...: The extra arguments. */ void fy_diag_node_report(struct fy_diag *diag, struct fy_node *fyn, enum fy_error_type type, const char *fmt, ...) FY_FORMAT(printf, 4, 5) FY_EXPORT; /** * fy_diag_node_override_vreport() - Report about a node vprintf style, * overriding file, line and column info using * the given diagnostic object * * Output a report about the given node via the specific * error type, and using the reporting configuration of the node's * document. This method will use the overrides provided in order * to massage the reporting information. * If @file is NULL, no file location will be reported. * If either @line or @column is negative no location will be reported. * * @diag: The diag object * @fyn: The node * @type: The error type * @file: The file override * @line: The line override * @column: The column override * @fmt: The printf format string * @ap: The argument list */ void fy_diag_node_override_vreport(struct fy_diag *diag, struct fy_node *fyn, enum fy_error_type type, const char *file, int line, int column, const char *fmt, va_list ap) FY_EXPORT; /** * fy_diag_node_override_report() - Report about a node printf style, * overriding file, line and column info using * the given diagnostic object * * Output a report about the given node via the specific * error type, and using the reporting configuration of the node's * document. This method will use the overrides provided in order * to massage the reporting information. * If @file is NULL, no file location will be reported. * If either @line or @column is negative no location will be reported. * * @diag: The diag object * @fyn: The node * @type: The error type * @file: The file override * @line: The line override * @column: The column override * @fmt: The printf format string * @...: The extra arguments. */ void fy_diag_node_override_report(struct fy_diag *diag, struct fy_node *fyn, enum fy_error_type type, const char *file, int line, int column, const char *fmt, ...) FY_FORMAT(printf, 7, 8) FY_EXPORT; /** * fy_diag_event_vreport() - Report about an event vprintf style using * the given diagnostic object * * Output a report about the given event part via the specific * error type. * * @diag: The diag object * @fye: The event * @fyep: The event part * @type: The error type * @fmt: The printf format string * @ap: The argument list */ void fy_diag_event_vreport(struct fy_diag *diag, struct fy_event *fye, enum fy_event_part fyep, enum fy_error_type type, const char *fmt, va_list ap) FY_EXPORT; /** * fy_diag_event_report() - Report about a event printf style using * the given diagnostic object * * Output a report about the given event part via the specific * error type. * * @diag: The diag object * @fye: The event * @fyep: The event part * @type: The error type * @fmt: The printf format string * @...: The extra arguments. */ void fy_diag_event_report(struct fy_diag *diag, struct fy_event *fye, enum fy_event_part fyep, enum fy_error_type type, const char *fmt, ...) FY_FORMAT(printf, 5, 6) FY_EXPORT; /** * fy_diag_errors_iterate() - Iterate over the errors of a diagnostic object * * This method iterates over all the errors collected on the diagnostic object. * The start of the iteration is signalled by a NULL in \*prevp. * * @diag: The diagnostic object * @prevp: The previous result iterator * * Returns: * The next errors or NULL when there are not any more. */ struct fy_diag_error * fy_diag_errors_iterate(struct fy_diag *diag, void **prevp) FY_EXPORT; /** * fy_parser_checkpoint_create() - Create a parser checkpoint * * Create a checkpoint of the parser's current state. This allows you * to save the parser state and potentially roll back to it later using * fy_parser_rollback(). The checkpoint must be destroyed via * fy_parser_checkpoint_destroy() when no longer needed. * * @fyp: The parser * * Returns: * A pointer to the checkpoint, or NULL in case of an error */ struct fy_parser_checkpoint * fy_parser_checkpoint_create(struct fy_parser *fyp) FY_EXPORT; /** * fy_parser_checkpoint_destroy() - Destroy a parser checkpoint * * Destroy a checkpoint created earlier via fy_parser_checkpoint_create(). * * @fypchk: The checkpoint to destroy */ void fy_parser_checkpoint_destroy(struct fy_parser_checkpoint *fypchk) FY_EXPORT; /** * fy_parser_rollback() - Roll back the parser to a checkpoint * * Roll back the parser state to a previously created checkpoint. This allows * you to revert the parser to an earlier state and re-parse from that point. * The checkpoint remains valid after rollback and can be used again or * destroyed via fy_parser_checkpoint_destroy(). * * @fyp: The parser * @fypc: The checkpoint to roll back to * * Returns: * 0 on success, -1 on error */ int fy_parser_rollback(struct fy_parser *fyp, struct fy_parser_checkpoint *fypc) FY_EXPORT; /** * enum fy_token_type - Token types * * @FYTT_NONE: No token * @FYTT_STREAM_START: Stream start token * @FYTT_STREAM_END: Stream end token * @FYTT_VERSION_DIRECTIVE: Version directive token * @FYTT_TAG_DIRECTIVE: Tag directive token * @FYTT_DOCUMENT_START: Document start token * @FYTT_DOCUMENT_END: Document end token * @FYTT_BLOCK_SEQUENCE_START: Block sequence start token * @FYTT_BLOCK_MAPPING_START: Block mapping start token * @FYTT_BLOCK_END: Block end token * @FYTT_FLOW_SEQUENCE_START: Flow sequence start token * @FYTT_FLOW_SEQUENCE_END: Flow sequence end token * @FYTT_FLOW_MAPPING_START: Flow mapping start token * @FYTT_FLOW_MAPPING_END: Flow mapping end token * @FYTT_BLOCK_ENTRY: Block entry token * @FYTT_FLOW_ENTRY: Flow entry token * @FYTT_KEY: Key token * @FYTT_VALUE: Value token * @FYTT_ALIAS: Alias token * @FYTT_ANCHOR: Anchor token * @FYTT_TAG: Tag token * @FYTT_SCALAR: Scalar token * @FYTT_INPUT_MARKER: Input marker token * @FYTT_PE_SLASH: Path expression slash token * @FYTT_PE_ROOT: Path expression root token * @FYTT_PE_THIS: Path expression this token * @FYTT_PE_PARENT: Path expression parent token * @FYTT_PE_MAP_KEY: Path expression map key token * @FYTT_PE_SEQ_INDEX: Path expression sequence index token * @FYTT_PE_SEQ_SLICE: Path expression sequence slice token * @FYTT_PE_SCALAR_FILTER: Path expression scalar filter token * @FYTT_PE_COLLECTION_FILTER: Path expression collection filter token * @FYTT_PE_SEQ_FILTER: Path expression sequence filter token * @FYTT_PE_MAP_FILTER: Path expression map filter token * @FYTT_PE_UNIQUE_FILTER: Path expression unique filter token * @FYTT_PE_EVERY_CHILD: Path expression every child token * @FYTT_PE_EVERY_CHILD_R: Path expression every child recursive token * @FYTT_PE_ALIAS: Path expression alias token * @FYTT_PE_SIBLING: Path expression sibling token * @FYTT_PE_COMMA: Path expression comma token * @FYTT_PE_BARBAR: Path expression || token * @FYTT_PE_AMPAMP: Path expression && token * @FYTT_PE_LPAREN: Path expression ( token * @FYTT_PE_RPAREN: Path expression ) token * @FYTT_PE_EQEQ: Path expression == token * @FYTT_PE_NOTEQ: Path expression != token * @FYTT_PE_LT: Path expression < token * @FYTT_PE_GT: Path expression > token * @FYTT_PE_LTE: Path expression <= token * @FYTT_PE_GTE: Path expression >= token * @FYTT_SE_PLUS: Scalar expression + token * @FYTT_SE_MINUS: Scalar expression - token * @FYTT_SE_MULT: Scalar expression \* token * @FYTT_SE_DIV: Scalar expression / token * @FYTT_PE_METHOD: Path expression method token * @FYTT_SE_METHOD: Scalar expression method token * @FYTT_PE_BANG: Path expression ! token * @FYTT_PE_AT: Path expression \@ token */ enum fy_token_type { /* non-content token types */ FYTT_NONE, FYTT_STREAM_START, FYTT_STREAM_END, FYTT_VERSION_DIRECTIVE, FYTT_TAG_DIRECTIVE, FYTT_DOCUMENT_START, FYTT_DOCUMENT_END, /* content token types */ 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, /* special error reporting */ FYTT_INPUT_MARKER, /* path expression tokens */ 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, /* comparison operators */ FYTT_PE_EQEQ, FYTT_PE_NOTEQ, FYTT_PE_LT, FYTT_PE_GT, FYTT_PE_LTE, FYTT_PE_GTE, /* scalar expression tokens */ FYTT_SE_PLUS, FYTT_SE_MINUS, FYTT_SE_MULT, FYTT_SE_DIV, FYTT_PE_METHOD, FYTT_SE_METHOD, FYTT_PE_BANG, FYTT_PE_AT, }; /* The number of token types available */ #define FYTT_COUNT (FYTT_PE_AT+1) /** * fy_token_type_is_valid() - Check token type validity * * Check if argument token type is a valid one. * * @type: The token type * * Returns: * true if the token type is valid, false otherwise */ static inline bool fy_token_type_is_valid(enum fy_token_type type) { return type >= FYTT_NONE && type < FYTT_COUNT; } /** * fy_token_type_is_yaml() - Check if token type is valid for YAML * * Check if argument token type is a valid YAML one. * * @type: The token type * * Returns: * true if the token type is a valid YAML one, false otherwise */ static inline bool fy_token_type_is_yaml(enum fy_token_type type) { return type >= FYTT_STREAM_START && type <= FYTT_SCALAR; } /** * fy_token_type_is_content() - Check if token type is * valid for YAML content * * Check if argument token type is a valid YAML content one. * * @type: The token type * * Returns: * true if the token type is a valid YAML content one, false otherwise */ static inline bool fy_token_type_is_content(enum fy_token_type type) { return type >= FYTT_BLOCK_SEQUENCE_START && type <= FYTT_SCALAR; } /** * fy_token_type_is_path_expr() - Check if token type is * valid for a YPATH expression * * Check if argument token type is a valid YPATH parse expression token * * @type: The token type * * Returns: * true if the token type is a valid YPATH one, false otherwise */ static inline bool fy_token_type_is_path_expr(enum fy_token_type type) { return type >= FYTT_PE_SLASH && type <= FYTT_PE_GTE; } /** * fy_token_type_is_scalar_expr() - Check if token type is * valid for a YPATH scalar expression * * Check if argument token type is a valid YPATH parse scalar expression token * * @type: The token type * * Returns: * true if the token type is a valid YPATH scalar one, false otherwise */ static inline bool fy_token_type_is_scalar_expr(enum fy_token_type type) { return type >= FYTT_SE_PLUS && type <= FYTT_SE_DIV; } /** * fy_token_get_type() - Return the token's type * * Return the token's type; if NULL then FYTT_NONE is returned * * @fyt: The token * * Returns: * The token's type; FYTT_NONE if not a valid token (or NULL) */ enum fy_token_type fy_token_get_type(struct fy_token *fyt) FY_EXPORT; /** * fy_token_start_mark() - Get token's start marker * * 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. * * @fyt: The token to get its start marker * * Returns: * The token's start marker, NULL if not available. */ const struct fy_mark * fy_token_start_mark(struct fy_token *fyt) FY_EXPORT; /** * fy_token_end_mark() - Get token's end marker * * 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. * * @fyt: The token to get its end marker * * Returns: * The token's end marker, NULL if not available. */ const struct fy_mark * fy_token_end_mark(struct fy_token *fyt) FY_EXPORT; /** * fy_token_style_start_mark() - Get token's start marker (style) * * 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. * * @fyt: The token to get its style start marker * * Returns: * The token's style start marker, NULL if not available. */ const struct fy_mark * fy_token_style_start_mark(struct fy_token *fyt) FY_EXPORT; /** * fy_token_style_end_mark() - Get token's end marker (style * * 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. * * @fyt: The token to get its style end marker * * Returns: * The token's style end marker, NULL if not available. */ const struct fy_mark * fy_token_style_end_mark(struct fy_token *fyt) FY_EXPORT; /** * fy_scan() - Low level access to the scanner * * Return the next scanner token. Note this is a very * low level interface, intended for users that want/need * to implement their own YAML parser. The returned * token is expected to be disposed using fy_scan_token_free() * * @fyp: The parser to get the next token from. * * Returns: * The next token, or NULL if no more tokens are available. */ struct fy_token * fy_scan(struct fy_parser *fyp) FY_EXPORT; /** * fy_scan_token_free() - Free the token returned by fy_scan() * * Free the token returned by fy_scan(). * * @fyp: The parser of which the token was returned by fy_scan() * @fyt: The token to free */ void fy_scan_token_free(struct fy_parser *fyp, struct fy_token *fyt) FY_EXPORT; /** * fy_tag_directive_token_prefix0() - Get the prefix contained in the * tag directive token as zero terminated * string * * Retrieve the tag directive's prefix contents as a zero terminated string. * It is similar to fy_tag_directive_token_prefix(), with the difference * that the returned string is zero terminated and memory may be allocated * to hold it associated with the token. * * @fyt: The tag directive token out of which the prefix pointer * will be returned. * * Returns: * A pointer to the zero terminated text representation of the prefix token. * NULL in case of an error. */ const char * fy_tag_directive_token_prefix0(struct fy_token *fyt) FY_EXPORT; /** * fy_tag_directive_token_handle0() - Get the handle contained in the * tag directive token as zero terminated * string * * Retrieve the tag directive's handle contents as a zero terminated string. * It is similar to fy_tag_directive_token_handle(), with the difference * that the returned string is zero terminated and memory may be allocated * to hold it associated with the token. * * @fyt: The tag directive token out of which the handle pointer * will be returned. * * Returns: * A pointer to the zero terminated text representation of the handle token. * NULL in case of an error. */ const char * fy_tag_directive_token_handle0(struct fy_token *fyt) FY_EXPORT; /** * fy_tag_token_handle() - Get the handle contained in the * tag token * * Retrieve the tag handle contents. Will fail if * token is not a tag token, or if a memory error happens. * * @fyt: The tag token out of which the handle pointer * will be returned. * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the text representation of the handle token, while * @lenp will be assigned the character length of said representation. * NULL in case of an error. */ const char * fy_tag_token_handle(struct fy_token *fyt, size_t *lenp) FY_EXPORT; /** * fy_tag_token_suffix() - Get the suffix contained in the * tag token * * Retrieve the tag suffix contents. Will fail if * token is not a tag token, or if a memory error happens. * * @fyt: The tag token out of which the suffix pointer * will be returned. * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the text representation of the suffix token, while * @lenp will be assigned the character length of said representation. * NULL in case of an error. */ const char * fy_tag_token_suffix(struct fy_token *fyt, size_t *lenp) FY_EXPORT; /** * fy_tag_token_short() - Get the short tag of the tag token * * 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. * * @fyt: The tag token out of which the short pointer * will be returned. * @lenp: Pointer to a variable that will hold the returned length * * Returns: * A pointer to the text representation of the short tag, while * @lenp will be assigned the character length of said representation. * NULL in case of an error. */ const char * fy_tag_token_short(struct fy_token *fyt, size_t *lenp) FY_EXPORT; /** * fy_tag_token_handle0() - Get the handle contained in the * tag token as zero terminated string * * Retrieve the tag handle contents as a zero terminated string. * It is similar to fy_tag_token_handle(), with the difference * that the returned string is zero terminated and memory may be allocated * to hold it associated with the token. * * @fyt: The tag token out of which the handle pointer will be returned. * * Returns: * A pointer to the zero terminated text representation of the handle token. * NULL in case of an error. */ const char * fy_tag_token_handle0(struct fy_token *fyt) FY_EXPORT; /** * fy_tag_token_short0() - Get the short tag of the tag token as zero * terminated string. * * 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. * * @fyt: The tag token out of which the short pointer will be returned. * * Returns: * A pointer to the null terminated text representation of the short tag. * NULL in case of an error. */ const char * fy_tag_token_short0(struct fy_token *fyt) FY_EXPORT; /** * fy_tag_token_suffix0() - Get the suffix contained in the * tag token as zero terminated string * * Retrieve the tag suffix contents as a zero terminated string. * It is similar to fy_tag_token_suffix(), with the difference * that the returned string is zero terminated and memory may be allocated * to hold it associated with the token. * * @fyt: The tag token out of which the suffix pointer will be returned. * * Returns: * A pointer to the zero terminated text representation of the suffix token. * NULL in case of an error. */ const char * fy_tag_token_suffix0(struct fy_token *fyt) FY_EXPORT; /** * fy_version_directive_token_version() - Return the version of a version * directive token * * Retrieve the version stored in a version directive token. * * @fyt: The version directive token * * Returns: * 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. */ const struct fy_version * fy_version_directive_token_version(struct fy_token *fyt) FY_EXPORT; /** * fy_scalar_token_get_style() - Return the style of a scalar token * * Retrieve the style of a scalar token. * * @fyt: The scalar token * * Returns: * The scalar style of the token, or FYSS_ANY for an error */ enum fy_scalar_style fy_scalar_token_get_style(struct fy_token *fyt) FY_EXPORT; /** * fy_tag_token_tag() - Get tag of a tag token * * Retrieve the tag of a tag token. * * @fyt: The tag token * * Returns: * A pointer to the tag or NULL in case of an error */ const struct fy_tag * fy_tag_token_tag(struct fy_token *fyt) FY_EXPORT; /** * fy_tag_directive_token_tag() - Get tag of a tag directive token * * Retrieve the tag of a tag directive token. * * @fyt: The tag directive token * * Returns: * A pointer to the tag or NULL in case of an error */ const struct fy_tag * fy_tag_directive_token_tag(struct fy_token *fyt) FY_EXPORT; /** * fy_event_get_token() - Return the main token of an event * * 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. * * @fye: The event to get its main token * * Returns: * The main token if it exists, NULL otherwise or in case of an error */ struct fy_token * fy_event_get_token(struct fy_event *fye) FY_EXPORT; /** * fy_event_get_anchor_token() - Return the anchor token of an event * * Retrieve the anchor token if it exists. Only valid for * mapping/sequence start and scalar events. * * @fye: The event to get its anchor token * * Returns: * The anchor token if it exists, NULL otherwise or in case of an error */ struct fy_token * fy_event_get_anchor_token(struct fy_event *fye) FY_EXPORT; /** * fy_event_get_tag_token() - Return the tag token of an event * * Retrieve the tag token if it exists. Only valid for * mapping/sequence start and scalar events. * * @fye: The event to get its tag token * * Returns: * The tag token if it exists, NULL otherwise or in case of an error */ struct fy_token * fy_event_get_tag_token(struct fy_event *fye) FY_EXPORT; /** * fy_event_start_mark() - Get event's start marker * * Return the event's start marker if it exists. The * start marker is the one of the event's main token. * * @fye: The event to get its start marker * * Returns: * The event's start marker, NULL if not available. */ const struct fy_mark * fy_event_start_mark(struct fy_event *fye) FY_EXPORT; /** * fy_event_end_mark() - Get event's end marker * * Return the event's end marker if it exists. The * end marker is the one of the event's main token. * * @fye: The event to get its end marker * * Returns: * The event's end marker, NULL if not available. */ const struct fy_mark * fy_event_end_mark(struct fy_event *fye) FY_EXPORT; /** * fy_event_style_start_mark() - Get event's start marker (style) * * 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. * * @fye: The event to get its style start marker * * Returns: * The event's start marker, NULL if not available. */ const struct fy_mark * fy_event_style_start_mark(struct fy_event *fye) FY_EXPORT; /** * fy_event_style_end_mark() - Get event's end marker (style) * * Return the event's style end marker if it exists. The * end marker is the one of the event's main token. * * @fye: The event to get its end marker * * Returns: * The event's end marker, NULL if not available. */ const struct fy_mark * fy_event_style_end_mark(struct fy_event *fye) FY_EXPORT; /** * fy_event_get_node_style() - Get the node style of an event * * 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. * * @fye: The event to get it's node style * * Returns: * The event's end marker, NULL if not available. */ enum fy_node_style fy_event_get_node_style(struct fy_event *fye) FY_EXPORT; /** * fy_document_start_event_version() - Return the version of a document * start event * * Retrieve the version stored in a document start event * * @fye: The document start event * * Returns: * A pointer to the version, or NULL in case of an error, or the event * not being a document start event. */ const struct fy_version * fy_document_start_event_version(struct fy_event *fye) FY_EXPORT; /** * fy_document_state_version() - Return the version of a document state * object * * Retrieve the version stored in a document state object * * @fyds: The document state object * * Returns: * A pointer to the version, or NULL in case of an error */ const struct fy_version * fy_document_state_version(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_start_mark() - Get document state's start mark * * Return the document state's start mark (if it exists). * Note that purely synthetic documents do not contain one * * @fyds: The document state object * * Returns: * The document's start marker, NULL if not available. */ const struct fy_mark * fy_document_state_start_mark(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_end_mark() - Get document state's end mark * * Return the document state's end mark (if it exists). * Note that purely synthetic documents do not contain one * * @fyds: The document state object * * Returns: * The document's end marker, NULL if not available. */ const struct fy_mark * fy_document_state_end_mark(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_version_explicit() - Version explicit? * * Find out if a document state object's version was explicitly * set in the document. * Note that for synthetic documents this method returns false. * * @fyds: The document state object * * Returns: * true if version was set explicitly, false otherwise */ bool fy_document_state_version_explicit(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_tags_explicit() - Tags explicit? * * Find out if a document state object's tags were explicitly * set in the document. * Note that for synthetic documents this method returns false. * * @fyds: The document state object * * Returns: * true if document had tags set explicitly, false otherwise */ bool fy_document_state_tags_explicit(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_start_implicit() - Started implicitly? * * Find out if a document state object's document was * started implicitly. * Note that for synthetic documents this method returns false. * * @fyds: The document state object * * Returns: * true if document was started implicitly, false otherwise */ bool fy_document_state_start_implicit(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_end_implicit() - Started implicitly? * * Find out if a document state object's document was * ended implicitly. * Note that for synthetic documents this method returns false. * * @fyds: The document state object * * Returns: * true if document was ended implicitly, false otherwise */ bool fy_document_state_end_implicit(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_json_mode() - Input was JSON? * * Find out if a document state object's document was * created by a JSON input. * Note that for synthetic documents this method returns false. * * @fyds: The document state object * * Returns: * true if document was created in JSON mode, false otherwise */ bool fy_document_state_json_mode(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_tag_directive_iterate() - Iterate over the tag * directives of a document state * object * * 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. * * @fyds: The document state * @prevp: The previous iterator * * Returns: * The next tag or NULL at the end of the iteration sequence. */ const struct fy_tag * fy_document_state_tag_directive_iterate(struct fy_document_state *fyds, void **prevp) FY_EXPORT; /** * fy_document_state_tag_directives() - Get all the tag directives in a * malloc'ed array * * Return all the tag directives in a dynamically allocated area. * Must be free()'d when not in use. * * @fyds: The document state * * Returns: * An array of fy_tag pointer structures, terminated with a NULL pointer * NULL on error */ struct fy_tag ** fy_document_state_tag_directives(struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_state_tag_is_default() - Test whether the given tag is a default one * * Test whether a tag is a default (i.e. impliciticly set) * * @fyds: The document state * @tag: The tag to check * * Returns: * true in case that the tag is a default one, false otherwise */ bool fy_document_state_tag_is_default(struct fy_document_state *fyds, const struct fy_tag *tag) FY_EXPORT; /** * fy_parser_get_document_state() - Get the document state of a parser object * * Retrieve the document state object of a parser. Note that this is only * valid during parsing. * * @fyp: The parser * * Returns: * The active document state object of the parser, NULL otherwise */ struct fy_document_state * fy_parser_get_document_state(struct fy_parser *fyp) FY_EXPORT; /** * fy_document_get_document_state() - Get the document state of a document * * Retrieve the document state object of a document. * * @fyd: The document * * Returns: * The document state object of the document, NULL otherwise */ struct fy_document_state * fy_document_get_document_state(struct fy_document *fyd) FY_EXPORT; /** * fy_document_set_document_state() - Set the document state of a document * * Set the document state of a document * * @fyd: The document * @fyds: The document state to use, or NULL for default * * Returns: * 0 if set operation was successful, -1 otherwise */ int fy_document_set_document_state(struct fy_document *fyd, struct fy_document_state *fyds) FY_EXPORT; /** * fy_document_create_from_event() - Create an empty document using the event * * Create an empty document using the FYET_DOCUMENT_START event generated * by the parser. * * @fyp: The parser * @fye: The event * * Returns: * The created empty document, or NULL on error. */ struct fy_document * fy_document_create_from_event(struct fy_parser *fyp, struct fy_event *fye) FY_EXPORT; /** * fy_document_update_from_event() - Update the document with the event * * Update the document using the FYET_DOCUMENT_END event generated * by the parser. * * @fyd: The document * @fyp: The parser * @fye: The event * * Returns: * 0 on success, -1 on error */ int fy_document_update_from_event(struct fy_document *fyd, struct fy_parser *fyp, struct fy_event *fye) FY_EXPORT; /** * fy_node_create_from_event() - Create a node using the event * * Create a new node using the supplied event. * Allowed events are FYET_SCALAR, FYET_ALIAS, FYET_MAPPING_START & FYET_SEQUENCE_START * * @fyd: The document * @fyp: The parser * @fye: The event * * Returns: * The newly created node, or NULL on error */ struct fy_node * fy_node_create_from_event(struct fy_document *fyd, struct fy_parser *fyp, struct fy_event *fye) FY_EXPORT; /** * fy_node_update_from_event() - Update a node using the event * * Update information of node created using fy_node_create_from_event() * Allowed events are FYET_MAPPING_END & FYET_SEQUENCE_END * * @fyn: The node * @fyp: The parser * @fye: The event * * Returns: * 0 on success, -1 on error */ int fy_node_update_from_event(struct fy_node *fyn, struct fy_parser *fyp, struct fy_event *fye) FY_EXPORT; /** * fy_node_pair_create_with_key() - Create a new node pair and set it's key * * Create a new node pair using the supplied fyn_parent mapping and fyn node as * a key. Note that the nodes _must_ have been created by fy_node_create_from_event * and they are not interchangeable with other node pair methods. * * The node pair will be added to the fyn_parent mapping with a subsequent call * to fy_node_pair_update_with_value(). * * @fyd: The document * @fyn_parent: The mapping * @fyn: The node pair key * * Returns: * The newly created node pair, or NULL on error */ struct fy_node_pair * fy_node_pair_create_with_key(struct fy_document *fyd, struct fy_node *fyn_parent, struct fy_node *fyn) FY_EXPORT; /** * fy_node_pair_update_with_value() - Update a node pair with a value and add it to the parent mapping * * Update the node pair with the given value and add it to the parent mapping. * Note that the fyn node _must_ have been created by fy_node_create_from_event * and the node pair created by fy_node_pair_create_with_key(). * Do not intermix other node pair manipulation methods. * * @fynp: The node pair * @fyn: The node pair value * * Returns: * 0 on success, -1 on error */ int fy_node_pair_update_with_value(struct fy_node_pair *fynp, struct fy_node *fyn) FY_EXPORT; /** * fy_node_sequence_add_item() - Add an item node to a sequence node * * 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. * * @fyn_parent: The parent sequence node * @fyn: The node pair item * * Returns: * 0 on success, -1 on error */ int fy_node_sequence_add_item(struct fy_node *fyn_parent, struct fy_node *fyn) FY_EXPORT; /** * fy_emitter_get_document_state() - Get the document state of an emitter object * * Retrieve the document state object of an emitter. Note that this is only * valid during emitting. * * @emit: The emitter * * Returns: * The active document state object of the emitter, NULL otherwise */ struct fy_document_state * fy_emitter_get_document_state(struct fy_emitter *emit) FY_EXPORT; /** * fy_emit_event_create() - Create an emit event. * * Create an emit event to pass to fy_emit_event() * The extra arguments differ according to the event to be created * * FYET_STREAM_START: * - None * * FYET_STREAM_END: * - None * * FYET_DOCUMENT_START: * - int implicit * true if document start should be marked implicit * false if document start should not be marked implicit * - const struct fy_version \*vers * Pointer to version to use for the document, or NULL for default * - const struct fy_tag \* const \*tags * Pointer to a NULL terminated array of tag pointers (like argv) * NULL if no extra tags are to be used * * FYET_DOCUMENT_END: * - int implicit * true if document end should be marked implicit * false if document end should not be marked implicit * * FYET_MAPPING_START: * - enum fy_node_style style * Style of the mapping (one of FYNS_ANY, FYNS_BLOCK or FYNS_FLOW) * - const char \*anchor * Anchor to place at the mapping, or NULL for none * - const char \*tag * Tag to place at the mapping, or NULL for none * * FYET_MAPPING_END: * - None * * FYET_SEQUENCE_START: * - enum fy_node_style style * Style of the sequence (one of FYNS_ANY, FYNS_BLOCK or FYNS_FLOW) * - const char \*anchor * Anchor to place at the sequence, or NULL for none * - const char \*tag * Tag to place at the sequence, or NULL for none * * FYET_SEQUENCE_END: * - None * * FYET_SCALAR: * - enum fy_scalar_style style * Style of the scalar, any valid FYSS_* value * Note that certain styles may not be used according to the * contents of the data * - const char \*value * Pointer to the scalar contents. * - size_t len * Length of the scalar contents, of FY_NT (-1) for strlen(value) * - const char \*anchor * Anchor to place at the scalar, or NULL for none * - const char \*tag * Tag to place at the scalar, or NULL for none * * FYET_ALIAS: * - const char \*value * Pointer to the alias. * * @emit: The emitter * @type: The event type to create * @...: The optional extra arguments * * Returns: * The created event or NULL in case of an error */ struct fy_event * fy_emit_event_create(struct fy_emitter *emit, enum fy_event_type type, ...) FY_EXPORT; /** * fy_emit_event_vcreate() - Create an emit event using varargs. * * Create an emit event to pass to fy_emit_event() * The varargs analogous to fy_emit_event_create(). * * @emit: The emitter * @type: The event type to create * @ap: The variable argument list pointer. * * Returns: * The created event or NULL in case of an error */ struct fy_event * fy_emit_event_vcreate(struct fy_emitter *emit, enum fy_event_type type, va_list ap) FY_EXPORT; /** * fy_emit_event_free() - Free an event created via fy_emit_event_create() * * Free an event previously created via fy_emit_event_create(). Note * that usually you don't have to call this method since if you pass * the event to fy_emit_event() it shall be disposed properly. * Only use is error recovery and cleanup. * * @emit: The emitter * @fye: The event to free */ void fy_emit_event_free(struct fy_emitter *emit, struct fy_event *fye) FY_EXPORT; /** * fy_parse_event_create() - Create an emit event. * * See fy_emit_event_create()... * * @fyp: The parser * @type: The event type to create * * Returns: * The created event or NULL in case of an error */ struct fy_event * fy_parse_event_create(struct fy_parser *fyp, enum fy_event_type type, ...) FY_EXPORT; /** * fy_parse_event_vcreate() - Create an emit event using varargs. * * Create an emit event to pass to fy_emit_event() * The varargs analogous to fy_parse_event_create(). * * @fyp: The parser * @type: The event type to create * @ap: The variable argument list pointer. * * Returns: * The created event or NULL in case of an error */ struct fy_event * fy_parse_event_vcreate(struct fy_parser *fyp, enum fy_event_type type, va_list ap) FY_EXPORT; #ifdef __cplusplus } #endif #endif /* LIBFYAML_CORE_H */