/***************************************************************************** * Public Interface for LibYAML * * Copyright (c) 2006 Kirill Simonov * * LibYAML is free software; you can use, modify and/or redistribute it under * the terms of the MIT license; see the file LICENCE for more details. *****************************************************************************/ /* * General guidelines. * * Naming conventions: all functions exported by LibYAML starts with the `yaml_` prefix; * types starts with `yaml_` and ends with `_t`; macros and enumerations starts * with `YAML_`. * * FIXME: Calling conventions. * FIXME: Memory allocation. * FIXME: Errors and exceptions. * FIXME: And so on, and so forth. */ #ifndef YAML_H #define YAML_H #ifdef __cplusplus extern "C" { #endif #include #include #include /***************************************************************************** * Export Definitions *****************************************************************************/ /* * Public API declarations. * * The following definitions are relevant only for the Win32 platform. If you * are building LibYAML as a static library or linking your application against * LibYAML compiled as a static library, define the macro * `YAML_DECLARE_STATIC`. If you are building LibYAML as a dynamic library * (DLL), you need to define `YAML_DECLARE_EXPORT`. You don't need to define * any macros in case you are linking your application against LibYAML compiled * as DLL. * * There is no need to define any macros if you use LibYAML on non-Win32 * platform. */ #ifdef WIN32 # if defined(YAML_DECLARE_STATIC) # define YAML_DECLARE(type) type # elif defined(YAML_DECLARE_EXPORT) # define YAML_DECLARE(type) __declspec(dllexport) type # else # define YAML_DECLARE(type) __declspec(dllimport) type # endif #else # define YAML_DECLARE(type) type #endif /***************************************************************************** * Version Information *****************************************************************************/ /* * The major, minor and patch version numbers of LibYAML. */ #define YAML_VERSION_MAJOR 0 #define YAML_VERSION_MINOR 2 #define YAML_VERSION_PATCH 0 /* * The version of LibYAML as a string. */ #define YAML_VERSION_STRING "0.2.0" /* * Get the library version numbers at runtime. * * Arguments: * * - `major`: a pointer to store the major version number. * * - `minor`: a pointer to store the minor version number. * * - `patch`: a pointer to store the patch version number. */ YAML_DECLARE(void) yaml_get_version(int *major, int *minor, int *patch); /* * Get the library version as a string at runtime. * * Returns: the version of LibYAML as a static string. */ YAML_DECLARE(const char *) yaml_get_version_string(void); /***************************************************************************** * Error Handling *****************************************************************************/ /* * The type of the error. * * The YAML parser and emitter reports any error details using the * `yaml_error_t` structure. The error type shows what subsystem generated the * error and what additional information about the error is available. */ typedef enum yaml_error_type_e { /* No error was produced. */ YAML_NO_ERROR, /* Cannot allocate or reallocate a block of memory. */ YAML_MEMORY_ERROR, /* Cannot read from the input stream. */ YAML_READER_ERROR, /* Cannot decode a character in the input stream. */ YAML_DECODER_ERROR, /* Cannot scan a YAML token. */ YAML_SCANNER_ERROR, /* Cannot parse a YAML event. */ YAML_PARSER_ERROR, /* Cannot compose a YAML document. */ YAML_COMPOSER_ERROR, /* Cannot write into the output stream. */ YAML_WRITER_ERROR, /* Cannot emit a YAML event. */ YAML_EMITTER_ERROR, /* Cannot serialize a YAML document. */ YAML_SERIALIZER_ERROR, /* Cannot resolve an implicit YAML node tag. */ YAML_RESOLVER_ERROR } yaml_error_type_t; /* * Position in the input stream. * * Marks are used to indicate the position of YAML tokens, events and documents * in the input stream as well as to point to the place where a parser error has * occured. */ typedef struct yaml_mark_s { /* The number of the character in the input stream (starting from zero). */ size_t index; /* The line in the input stream (starting from zero). */ size_t line; /* The column in the input stream (starting from zero). */ size_t column; } yaml_mark_t; /* * Error details. * * The structure gives detailed information on any problem that occured during * parsing or emitting. */ typedef struct yaml_error_s { /* The error type. */ yaml_error_type_t type; /* The specific information for each error type. */ union { /* * A problem occured while reading the input stream (relevant for * `YAML_READER_ERROR` and `YAML_DECODER_ERROR`). */ struct { /* The problem description. */ const char *problem; /* The position in the input stream, in bytes. */ size_t offset; /* The problematic octet or character (`-1` if not applicable). */ int value; } reading; /* * A problem occured while loading YAML data from the input stream * (relevant for `YAML_SCANNER_ERROR`, `YAML_PARSER_ERROR`, and * `YAML_COMPOSER_ERROR`). */ struct { /* The description of the context in which the problem occured (`NULL` if not applicable). */ const char *context; /* The context mark (if `context` is not `NULL`). */ yaml_mark_t context_mark; /* The problem description. */ const char *problem; /* The problem mark. */ yaml_mark_t problem_mark; } loading; /* * A problem occured while writing into the output stream (relevant for * `YAML_WRITER_ERROR`). */ struct { /* The problem description. */ const char *problem; /* The position in the output stream, in bytes. */ size_t offset; } writing; /* * A problem while dumping YAML data into the output stream (relevant * for `YAML_EMITTER_ERROR` and `YAML_SERIALIZER_ERROR`). */ struct { /* The problem description. */ const char *problem; } dumping; /* * A problem occured while resolving an implicit YAML node tag * (relevant for `YAML_RESOLVER_ERROR`). */ struct { /* The problem description. */ const char *problem; } resolving; } data; } yaml_error_t; /* * Generate an error message. * * Given an instance of the `yaml_error_t` structure and a buffer, the function * fills the buffer with a message describing the error. The generated message * follows the pattern: `"Error type: error details"`. If the buffer is not * large enough to hold the whole message, the function fails. * * Arguments: * * - `error`: an error object obtained using `yaml_parser_get_error()` or * `yaml_emitter_get_error()`. * * - `buffer`: a pointer to a character buffer to be filled with a generated * error message. * * - `capacity`: the size of the buffer. * * Returns: `1` if the function succeeded, `0` on error. The function may fail * if the provided buffer is not large enough to hold the whole buffer, in * which case an application may increase the size of the buffer and call the * function again. If the function fails, the content of the buffer is * undefined. */ YAML_DECLARE(int) yaml_error_message(yaml_error_t *error, char *buffer, size_t capacity); /****************************************************************************** * Basic Types ******************************************************************************/ /* * The character type (UTF-8 octet). * * Usage of the string type `(yaml_char_t *)` in the LibYAML API indicates that * the string is encoded in UTF-8. */ typedef unsigned char yaml_char_t; /* * The version directive information. * * Note that LibYAML only supports YAML 1.1. */ typedef struct yaml_version_directive_s { /* The major version number. */ int major; /* The minor version number. */ int minor; } yaml_version_directive_t; /* * The tag directive information. */ typedef struct yaml_tag_directive_s { /* The tag handle. */ yaml_char_t *handle; /* The tag prefix. */ yaml_char_t *prefix; } yaml_tag_directive_t; /* * The stream encoding. * * An application may explicitly specify the encoding in the input stream or * let the parser to detect the input stream encoding from a BOM mark. If the * stream does not start with a BOM mark, UTF-8 is assumed. * * An application may specify the encoding of the output stream or let the * emitter to choose a suitable encoding, in which case, UTF-8 is used. */ typedef enum yaml_encoding_e { /* The default/autodetected encoding. */ YAML_ANY_ENCODING, /* The UTF-8 encoding. */ YAML_UTF8_ENCODING, /* The UTF-16-LE encoding. */ YAML_UTF16LE_ENCODING, /* The UTF-16-BE encoding. */ YAML_UTF16BE_ENCODING } yaml_encoding_t; /* * Line break types. * * An application may specify the line break type the emitter should use or * leave it to the emitter discretion. In the latter case, LN (Unix style) is * used. */ typedef enum yaml_break_e { /* Let the parser choose the break type. */ YAML_ANY_BREAK, /* Use CR for line breaks (Mac style). */ YAML_CR_BREAK, /* Use LN for line breaks (Unix style). */ YAML_LN_BREAK, /* Use CR LN for line breaks (DOS style). */ YAML_CRLN_BREAK } yaml_break_t; /****************************************************************************** * Node Styles ******************************************************************************/ /* * Scalar styles. * * There are two groups of scalar types in YAML: flow and block. Flow scalars * are divided into three styles: plain, single-quoted, and double-quoted; * block scalars are divided into two styles: literal and folded. * * The parser reports the style in which a scalar node is represented, however * it is a purely presentation details that must not be used in interpreting * the node content. * * An application may suggest a preferred node style or leave it completely * to the emitter discretion. Note that the emitter may ignore any stylistic * suggestions. */ typedef enum yaml_scalar_style_e { /* Let the emitter choose the style. */ YAML_ANY_SCALAR_STYLE, /* The plain flow scalar style. */ YAML_PLAIN_SCALAR_STYLE, /* The single-quoted flow scalar style. */ YAML_SINGLE_QUOTED_SCALAR_STYLE, /* The double-quoted flow scalar style. */ YAML_DOUBLE_QUOTED_SCALAR_STYLE, /* The literal block scalar style. */ YAML_LITERAL_SCALAR_STYLE, /* The folded block scalar style. */ YAML_FOLDED_SCALAR_STYLE } yaml_scalar_style_t; /* * Sequence styles. * * YAML supports two sequence styles: flow and block. * * The parser reports the style of a sequence node, but this information should * not be used in interpreting the sequence content. * * An application may suggest a preferred sequence style or leave it completely * to the emitter discretion. Note that the emitter may ignore any stylistic * hints. */ typedef enum yaml_sequence_style_e { /* Let the emitter choose the style. */ YAML_ANY_SEQUENCE_STYLE, /* The flow sequence style. */ YAML_FLOW_SEQUENCE_STYLE /* The block sequence style. */ YAML_BLOCK_SEQUENCE_STYLE, } yaml_sequence_style_t; /* * Mapping styles. * * YAML supports two mapping styles: flow and block. * * The parser reports the style of a mapping node, but this information should * not be used in interpreting the mapping content. * * An application may suggest a preferred mapping style or leave it completely * to the emitter discretion. Note that the emitter may ignore any stylistic * hints. */ typedef enum yaml_mapping_style_e { /* Let the emitter choose the style. */ YAML_ANY_MAPPING_STYLE, /* The block mapping style. */ YAML_BLOCK_MAPPING_STYLE, /* The flow mapping style. */ YAML_FLOW_MAPPING_STYLE } yaml_mapping_style_t; /****************************************************************************** * Tokens ******************************************************************************/ /* * Token types. * * The LibYAML scanner generates the following types of tokens: * * - STREAM-START: indicates the beginning of the stream. * * - STREAM-END: indicates the end of the stream. * * - VERSION-DIRECTIVE: describes the `%YAML` directive. * * - TAG-DIRECTIVE: describes the `%TAG` directive. * * - DOCUMENT-START: the indicator `---`. * * - DOCUMENT-END: the indicator `...`. * * - BLOCK-SEQUENCE-START: indentation increase indicating the beginning of a * block sequence node. * * - BLOCK-MAPPING-START: indentation increase indicating the beginning of a * block mapping node. * * - BLOCK-END: indentation decrease indicating the end of a block collection * node. * * - FLOW-SEQUENCE-START: the indicator `[`. * * - FLOW-SEQUENCE-END: the indicator `]`. * * - FLOW-MAPPING-START: the indicator `{`. * * - FLOW-MAPPING-END: the indicator `}`. * * - BLOCK-ENTRY: the beginning of an item of a block sequence. * * - FLOW-ENTRY: the beginning of an item of a flow sequence. * * - KEY: the beginning of a simple key, or the indicator `?`. * * - VALUE: the indicator `:`. * * - ALIAS: an alias of a node. * * - ANCHOR: a node anchor. * * - TAG: a node tag. * * - SCALAR: the content of a scalar node. */ typedef enum yaml_token_type_e { /* An empty unitialized token. */ YAML_NO_TOKEN, /* A STREAM-START token. */ YAML_STREAM_START_TOKEN, /* A STREAM-END token. */ YAML_STREAM_END_TOKEN, /* A VERSION-DIRECTIVE token. */ YAML_VERSION_DIRECTIVE_TOKEN, /* A TAG-DIRECTIVE token. */ YAML_TAG_DIRECTIVE_TOKEN, /* A DOCUMENT-START token. */ YAML_DOCUMENT_START_TOKEN, /* A DOCUMENT-END token. */ YAML_DOCUMENT_END_TOKEN, /* A BLOCK-SEQUENCE-START token. */ YAML_BLOCK_SEQUENCE_START_TOKEN, /* A BLOCK-SEQUENCE-END token. */ YAML_BLOCK_MAPPING_START_TOKEN, /* A BLOCK-END token. */ YAML_BLOCK_END_TOKEN, /* A FLOW-SEQUENCE-START token. */ YAML_FLOW_SEQUENCE_START_TOKEN, /* A FLOW-SEQUENCE-END token. */ YAML_FLOW_SEQUENCE_END_TOKEN, /* A FLOW-MAPPING-START token. */ YAML_FLOW_MAPPING_START_TOKEN, /* A FLOW-MAPPING-END token. */ YAML_FLOW_MAPPING_END_TOKEN, /* A BLOCK-ENTRY token. */ YAML_BLOCK_ENTRY_TOKEN, /* A FLOW-ENTRY token. */ YAML_FLOW_ENTRY_TOKEN, /* A KEY token. */ YAML_KEY_TOKEN, /* A VALUE token. */ YAML_VALUE_TOKEN, /* An ALIAS token. */ YAML_ALIAS_TOKEN, /* An ANCHOR token. */ YAML_ANCHOR_TOKEN, /* A TAG token. */ YAML_TAG_TOKEN, /* A SCALAR token. */ YAML_SCALAR_TOKEN } yaml_token_type_t; /* * The token object. * * Typically the token API is too low-level to be used directly by * applications. A possible user of the token API is a syntax highlighting * application. */ typedef struct yaml_token_s { /* The token type. */ yaml_token_type_t type; /* The token data. */ union { /* Extra data associated with a STREAM-START token. */ struct { /* The stream encoding. */ yaml_encoding_t encoding; } stream_start; /* Extra data associated with a VERSION-DIRECTIVE token. */ struct { /* The major version number. */ int major; /* The minor version number. */ int minor; } version_directive; /* Extra data associated with a TAG-DIRECTIVE token. */ struct { /* The tag handle. */ yaml_char_t *handle; /* The tag prefix. */ yaml_char_t *prefix; } tag_directive; /* Extra data associated with an ALIAS token. */ struct { /* The alias value. */ yaml_char_t *value; } alias; /* Extra data associated with an ANCHOR token. */ struct { /* The anchor value. */ yaml_char_t *value; } anchor; /* Extra data associated with a TAG token. */ struct { /* The tag handle. */ yaml_char_t *handle; /* The tag suffix. */ yaml_char_t *suffix; } tag; /* Extra data associated with a SCALAR token. */ struct { /* The scalar value. */ yaml_char_t *value; /* The length of the scalar value. */ size_t length; /* The scalar style. */ yaml_scalar_style_t style; } scalar; } data; /* The beginning of the token. */ yaml_mark_t start_mark; /* The end of the token. */ yaml_mark_t end_mark; } yaml_token_t; /* * Allocate a new empty token object. * * A token object allocated using this function must be deleted with * `yaml_token_delete()`. * * Returns: a new empty token object or `NULL` on error. The function may fail * if it cannot allocate memory for a new token object. */ YAML_DECLARE(yaml_token_t *) yaml_token_new(void); /* * Deallocate a token object and free the associated data. * * A token object must be previously allocated with `yaml_token_new()`. * * Arguments: * * - `token`: a token object to be deallocated. */ YAML_DECLARE(void) yaml_token_delete(yaml_token_t *token); /* * Duplicate a token object. * * This function creates a deep copy of an existing token object. It accepts * two token objects: an empty token and a model token. The latter is supposed * to be initialized with `yaml_parser_parse_token()`. The function assigns * the type of the model to the empty token as well as duplicates and copies * the internal state associated with the model token. * * Arguments: * * - `token`: an empty token object. * * - `model`: a token to be copied. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the state of the model token. In that case, * the token remains empty. */ YAML_DECLARE(int) yaml_token_duplicate(yaml_token_t *token, const yaml_token_t *model); /* * Clear the token state. * * This function clears the type and the internal state of a token object * freeing any associated data. After applying this function to a token, it * becomes empty. It is supposed that the token was previously initialized * using `yaml_parser_parse_token()` or `yaml_token_duplicate()`. * * Arguments: * * - `token`: a token object. */ YAML_DECLARE(void) yaml_token_clear(yaml_token_t *token); /****************************************************************************** * Events ******************************************************************************/ /* * Event types. * * The LibYAML parser generates, while the LibYAML emitter accepts, YAML events * of the following types: * * - STREAM-START: indicates the beginning of the stream. * * - STREAM-END: indicates the end of the stream. * * - DOCUMENT-START: indicates the beginning of the document. * * - DOCUMENT-END: indicates the end of the document. * * - ALIAS: an alias to an already produced node. * * - SCALAR: a scalar node. * * - SEQUENCE-START: indicates the beginning of a sequence node. * * - SEQUENCE-END: indicates the end of a sequence node. * * - MAPPING-START: indicates the beginning of a mapping node. * * - MAPPING-END: indicates the end of a mapping node. * * A valid sequence of events obeys the grammar: * * stream ::= STREAM-START document* STREAM-END * document ::= DOCUMENT-START node DOCUMENT-END * node ::= ALIAS | SCALAR | sequence | mapping * sequence ::= SEQUENCE-START node* SEQUENCE-END * mapping ::= MAPPING-START (node node)* MAPPING-END */ typedef enum yaml_event_type_e { /* An empty unitialized event. */ YAML_NO_EVENT, /* A STREAM-START event. */ YAML_STREAM_START_EVENT, /* A STREAM-END event. */ YAML_STREAM_END_EVENT, /* A DOCUMENT-START event. */ YAML_DOCUMENT_START_EVENT, /* A DOCUMENT-END event. */ YAML_DOCUMENT_END_EVENT, /* An ALIAS event. */ YAML_ALIAS_EVENT, /* A SCALAR event. */ YAML_SCALAR_EVENT, /* A SEQUENCE-START event. */ YAML_SEQUENCE_START_EVENT, /* A SEQUENCE-END event. */ YAML_SEQUENCE_END_EVENT, /* A MAPPING-START event. */ YAML_MAPPING_START_EVENT, /* A MAPPING-END event. */ YAML_MAPPING_END_EVENT } yaml_event_type_t; /* * The event object. * * The event-level API of LibYAML should be used for streaming applications. */ typedef struct yaml_event_s { /* The event type. */ yaml_event_type_t type; /* The event data. */ union { /* The stream parameters (for `YAML_STREAM_START_EVENT`). */ struct { /* The document encoding. */ yaml_encoding_t encoding; } stream_start; /* The document parameters (for `YAML_DOCUMENT_START_EVENT`). */ struct { /* The version directive or `NULL` if not present. */ yaml_version_directive_t *version_directive; /* The list of tag directives. */ struct { /* The beginning of the list or `NULL`. */ yaml_tag_directive_t *list; /* The length of the list. */ size_t length; /* The capacity of the list (used internally). */ size_t capacity; } tag_directives; /* Set if the document indicator is omitted. */ int is_implicit; } document_start; /* The document end parameters (for `YAML_DOCUMENT_END_EVENT`). */ struct { /* Set if the document end indicator is omitted. */ int is_implicit; } document_end; /* The alias parameters (for `YAML_ALIAS_EVENT`). */ struct { /* The anchor. */ yaml_char_t *anchor; } alias; /* The scalar parameters (for `YAML_SCALAR_EVENT`). */ struct { /* The node anchor or `NULL`. */ yaml_char_t *anchor; /* The node tag or `NULL`. */ yaml_char_t *tag; /* The scalar value. */ yaml_char_t *value; /* The length of the scalar value (in bytes). */ size_t length; /* Set if the tag is optional for the plain style. */ int is_plain_nonspecific; /* Set if the tag is optional for any non-plain style. */ int is_quoted_nonspecific; /* The scalar style. */ yaml_scalar_style_t style; } scalar; /* The sequence parameters (for `YAML_SEQUENCE_START_EVENT`). */ struct { /* The node anchor or `NULL`. */ yaml_char_t *anchor; /* The node tag or `NULL`. */ yaml_char_t *tag; /* Set if the tag is optional. */ int is_nonspecific; /* The sequence style. */ yaml_sequence_style_t style; } sequence_start; /* The mapping parameters (for `YAML_MAPPING_START_EVENT`). */ struct { /* The node anchor or `NULL`. */ yaml_char_t *anchor; /* The node tag or `NULL`. */ yaml_char_t *tag; /* Set if the tag is optional. */ int is_nonspecific; /* The mapping style. */ yaml_mapping_style_t style; } mapping_start; } data; /* The beginning of the event. */ yaml_mark_t start_mark; /* The end of the event. */ yaml_mark_t end_mark; } yaml_event_t; /* * Allocate a new empty event object. * * An event object allocated using this function must be deleted with * `yaml_event_delete()`. * * Returns: a new empty event object or `NULL` on error. The function may fail * if it cannot allocate memory for a new event object. */ YAML_DECLARE(yaml_event_t *) yaml_event_new(void); /* * Deallocate an event object and free the associated data. * * An event object must be previously allocated with `yaml_event_new()`. * * Arguments: * * - `event`: an event object to be deallocated. */ YAML_DECLARE(void) yaml_event_delete(yaml_event_t *event); /* * Duplicate an event object. * * This function creates a deep copy of an existing event object. It accepts * two objects: an empty event and a model event. The model event is supposed * to be initialized either with `yaml_parser_parse_event()` or using one of * the functions `yaml_event_create_*()`. The function assigns the type of the * model to the empty event and copies the internal state associated with the * model event. * * Arguments: * * - `event`: an empty event object. * * - `model`: an event to be copied. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the state of the model event. In that case, * the event remains empty. */ YAML_DECLARE(int) yaml_event_duplicate(yaml_event_t *event, const yaml_event_t *model); /* * Clear the event state. * * This function clears the type and the internal state of an event object * freeing any associated data. After applying this function to an event, it * becomes empty. It is supposed that the event was previously initialized * using `yaml_parser_parse_event()` or `yaml_event_duplicate()`. Note that * the function `yaml_emitter_emit_event()` also clears the given event. * * Arguments: * * - `event`: an event object. */ YAML_DECLARE(void) yaml_event_clear(yaml_event_t *event); /* * Create a STREAM-START event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * - `encoding`: the stream encoding. * * Returns: `1`. The function never fails. */ YAML_DECLARE(int) yaml_event_create_stream_start(yaml_event_t *event, yaml_encoding_t encoding); /* * Create a STREAM-END event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * Returns: `1`. The function never fails. */ YAML_DECLARE(int) yaml_event_create_stream_end(yaml_event_t *event); /* * Create a DOCUMENT-START event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * - `version_directive`: a structure specifying the content of the `%YAML` * directive or `NULL` if the directive could be omitted. Note that LibYAML * supports YAML 1.1 only. The function does not check if the supplied * version equals to 1.1, but the emitter will fail to emit the event if it * is not so. * * - `tag_directives_list`: a pointer to a list specifying the content of the * `%TAG` directives associated with the document or `NULL` if the document * does not contain `%TAG` directives. The content of a tag directive is a * pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings. The tag * handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_` * and `-` surrounded by `!`. The tag prefix is a prefix of any valid tag, * that is, it is a non-empty prefix of either a global tag (a valid URI) or * a local tag (an arbitrary string starting with `!`). The function does * not check if the given directive values satisfy these requirements, but * the emitter will fail to emit the event if they are not met. * * - `tag_directives_length`: the length of `tag_directives_list`; `0` if * `tag_directives_list` is `NULL`. * * - `is_implicit`: `1` if the document indicator `---` is omitted, `0` * otherwise. Note that this attribute is only a stylistic hint and could be * ignored by the emitter. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the event parameters. In this case, the * event remains empty. */ YAML_DECLARE(int) yaml_event_create_document_start(yaml_event_t *event, const yaml_version_directive_t *version_directive, const yaml_tag_directive_t *tag_directives_list, size_t tag_directives_length, int is_implicit); /* * Create a DOCUMENT-END event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * - `is_implicit`: `1` if the document end indicator `...` is omitted, `0` * otherwise. Note that this attribute is only a stylistic hint and could be * ignored by the emitter. * * Returns: `1`. The function never fails. */ YAML_DECLARE(int) yaml_event_create_document_end(yaml_event_t *event, int is_implicit); /* * Create an ANCHOR event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * - `anchor`: the anchor value. The anchor should be a non-empty * NUL-terminated string containing only alphanumerical characters, `_`, and * `-`. The function does not check if this requirement is satisfied, but if * it is not so, the emitter will fail to emit the generated event. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating `anchor`. In this case, the event remains * empty. */ YAML_DECLARE(int) yaml_event_create_alias(yaml_event_t *event, const yaml_char_t *anchor); /* * Create a SCALAR event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * - `anchor`: the anchor value or `NULL`. The anchor should be a non-empty * NUL-terminated string containing only alphanumerical characters, `_`, and * `-`. * * - `tag`: the tag value or `NULL`. The tag should be a non-empty UTF-8 * NUL-terminated string. The tag could be global (a valid URI) or local (an * arbitrary string starting with `!`). If `NULL` is provided, at least one * of the flags `is_plain_nonspecific` and `is_quoted_nonspecific` must be * set. The function does not check whether these requirements are * satisfied, but the emitter will fail to emit the event if it is not so. * * - `value`: the value of the scalar node. The value should be a UTF-8 * string. It could contain any valid UTF-8 character including NUL. The * function does not check if `value` is a valid UTF-8 string, but the * emitter will fail to emit the event if it is not so. * * - `length`: the length of the scalar value (in bytes) or `-1`. If `length` * is set to `-1`, the `value` is assumed to be NUL-terminated. * * - `is_plain_nonspecific`: `1` if the node tag could be omitted while * emitting the node provided that the the plain style is used for * representing the node value; `0` otherwise. That this flag is set assumes * that the tag could be correctly determined by the parser using the node * position and content. * * - `is_quoted_nonspecific`: `1` if the node tag could be omitted while * emitting the node provided that the node value is represented using any * non-plain style; `0` otherwise. That this flag is set assumes that the * tag could be correctly determined by the parser using the node position * and content. * * - `style`: the node style. Note that this attribute only serves as a hint * and may be ignored by the emitter. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the given string buffers. In this case, the * event remains empty. */ YAML_DECLARE(int) yaml_event_create_scalar(yaml_event_t *event, const yaml_char_t *anchor, const yaml_char_t *tag, const yaml_char_t *value, int length, int is_plain_nonspecific, int is_quoted_nonspecific, yaml_scalar_style_t style); /* * Create a SEQUENCE-START event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * - `anchor`: the anchor value or `NULL`. The anchor should be a non-empty * NUL-terminated string containing only alphanumerical characters, `_`, and * `-`. The function does not check if this requirement is satisfied, but if * it is not so, the emitter will fail to emit the generated event. * * - `tag`: the tag value or `NULL`. The tag should be a non-empty UTF-8 * NUL-terminated string. The tag could be global (a valid URI) or local (an * arbitrary string starting with `!`). If `NULL` is provided, the flag * `is_nonspecific` must be set. The function does not check whether these * requirements are satisfied, but if it is not so, the emitter will fail to * emit the generated event. * * - `is_nonspecific`: `1` if the node tag could be omitted while * emitting the node; `0` otherwise. This flag should only be set if the * node tag could be correctly determined by the parser using the node * position in the document graph. * * - `style`: the node style. Note that this attribute only serves as a hint * and may be ignored by the emitter. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the given string buffers. In this case, the * event remains empty. */ YAML_DECLARE(int) yaml_event_create_sequence_start(yaml_event_t *event, const yaml_char_t *anchor, const yaml_char_t *tag, int is_nonspecific, yaml_sequence_style_t style); /* * Create a SEQUENCE-END event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * Returns: `1`. This function never fails. */ YAML_DECLARE(int) yaml_event_create_sequence_end(yaml_event_t *event); /* * Create a MAPPING-START event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * - `anchor`: the anchor value or `NULL`. The anchor should be a non-empty * NUL-terminated string containing only alphanumerical characters, `_`, and * `-`. The function does not check if this requirement is satisfied, but if * it is not so, the emitter will fail to emit the generated event. * * - `tag`: the tag value or `NULL`. The tag should be a non-empty UTF-8 * NUL-terminated string. The tag could be global (a valid URI) or local (an * arbitrary string starting with `!`). If `NULL` is provided, the flag * `is_nonspecific` must be set. The function does not check whether these * requirements are satisfied, but if it is not so, the emitter will fail to * emit the generated event. * * - `is_nonspecific`: `1` if the node tag could be omitted while * emitting the node; `0` otherwise. This flag should only be set if the * node tag could be correctly determined by the parser using the node * position in the document graph. * * - `style`: the node style. Note that this attribute only serves as a hint * and may be ignored by the emitter. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the given string buffers. In this case, the * event remains empty. */ YAML_DECLARE(int) yaml_event_create_mapping_start(yaml_event_t *event, const yaml_char_t *anchor, const yaml_char_t *tag, int is_nonspecific, yaml_mapping_style_t style); /* * Create a MAPPING-END event. * * This function initializes an empty event object allocated with * `yaml_event_new()`. The initialized event could be fed to * `yaml_emitter_emit_event()`. * * Arguments: * * - `event`: an empty event object. * * Returns: `1`. This function never fails. */ YAML_DECLARE(int) yaml_event_create_mapping_end(yaml_event_t *event); /****************************************************************************** * Documents and Nodes ******************************************************************************/ /* * Well-known scalar tags. */ #define YAML_NULL_TAG ((const yaml_char_t *) "tag:yaml.org,2002:null") #define YAML_BOOL_TAG ((const yaml_char_t *) "tag:yaml.org,2002:bool") #define YAML_STR_TAG ((const yaml_char_t *) "tag:yaml.org,2002:str") #define YAML_INT_TAG ((const yaml_char_t *) "tag:yaml.org,2002:int") #define YAML_FLOAT_TAG ((const yaml_char_t *) "tag:yaml.org,2002:float") /* * Basic collection tags. */ #define YAML_SEQ_TAG ((const yaml_char_t *) "tag:yaml.org,2002:seq") #define YAML_MAP_TAG ((const yaml_char_t *) "tag:yaml.org,2002:map") /* * The default tags for nodes lacking an explicit tag. */ #define YAML_DEFAULT_SCALAR_TAG YAML_STR_TAG #define YAML_DEFAULT_SEQUENCE_TAG YAML_SEQ_TAG #define YAML_DEFAULT_MAPPING_TAG YAML_MAP_TAG /* * Document types. * * There are no different document types in LibYAML: the document type field is * only used to distinguish between newly allocated documents and those that * are initialized with `yaml_parser_parse_document()` or * `yaml_document_create()`. */ typedef enum yaml_document_type_e { /* An empty uninitialized document. */ YAML_NO_DOCUMENT. /* A YAML document. */ YAML_DOCUMENT } yaml_document_type_t; /* * Node types. * * YAML recognizes three kinds of nodes: scalar, sequence and mapping. */ typedef enum yaml_node_type_e { /* An empty node. */ YAML_NO_NODE, /* A scalar node. */ YAML_SCALAR_NODE, /* A sequence node. */ YAML_SEQUENCE_NODE, /* A mapping node. */ YAML_MAPPING_NODE } yaml_node_type_t; /* * Arc types. * * Arcs are used to specify the path from the root node to a given node in the * document graph. There are three kinds of arcs: an item in a sequence node, * a key in a mapping node, and a value in a mapping node. */ typedef enum yaml_arc_type_e { /* An empty arc. */ YAML_NO_ARC, /* An item of a sequence. */ YAML_SEQUENCE_ITEM_ARC, /* A key of a mapping. */ YAML_MAPPING_KEY_ARC, /* A value of a mapping. */ YAML_MAPPING_VALUE_ARC } yaml_arc_type_t; /* * An element of a sequence node. */ typedef int yaml_node_item_t; /* * An element of a mapping node. */ typedef struct yaml_node_pair_s { /* A key in a mapping. */ int key; /* A value in a mapping. */ int value; } yaml_node_pair_t; /* * A path element. * * An arc is an element of a path from the root node to some other node in a * YAML document. An arc consists of a collection node and information on how * it is connected to the next node in the path. If the arc type is a sequence * item, then the collection node is a sequence and the arc refers to the index * in this sequence. If the arc type is a mapping key, then the collection * node is a mapping. If the arc type is a mapping value, then the collection * node is a mapping and the arc refers to the key associated to the value. */ typedef struct yaml_arc_s { /* The arc type. */ yaml_arc_type_t type; /* The tag of the collection node. */ yaml_char_t *tag; /* The connection information. */ union { /* The sequence item data (for `YAML_SEQUENCE_ITEM_ARC`). */ struct { /* The index of the item in the sequence (starting from `0`). */ int index; } item; /* The mapping value data (for `YAML_MAPPING_VALUE_ARC`). */ struct { /* The key associated with the value. */ struct { /* The key node type. */ yaml_node_type_t type; /* The key node tag. */ yaml_char_t *tag; /* The key node details. */ union { /* The scalar data (for a scalar key). */ struct { /* The scalar value. */ yaml_char_t *value; /* The scalar length. */ size_t length; } scalar; } data; } key; } value; } data; } yaml_arc_t; /* * The node object. * * A node object represents a node in a YAML document graph. Node objects are * created using the family of functions `yaml_document_add_*()`. Links * between nodes are created using the functions `yaml_document_append_*()`. A * node object is destroyed when the document containing it is destroyed. */ struct yaml_node_s { /* The node type. */ yaml_node_type_t type; /* The node anchor or `NULL`. */ yaml_char_t *anchor; /* The node tag. */ yaml_char_t *tag; /* The node data. */ union { /* The scalar parameters (for `YAML_SCALAR_NODE`). */ struct { /* The scalar value. */ yaml_char_t *value; /* The length of the scalar value. */ size_t length; /* The scalar style. */ yaml_scalar_style_t style; } scalar; /* The sequence parameters (for `YAML_SEQUENCE_NODE`). */ struct { /* The list of sequence items. */ struct { /* The pointer to the beginning of the list. */ yaml_node_item_t *list; /* The length of the list. */ size_t length; /* The capacity of the list (used internally). */ size_t capacity; } items; /* The sequence style. */ yaml_sequence_style_t style; } sequence; /* The mapping parameters (for `YAML_MAPPING_NODE`). */ struct { /* The list of mapping pairs (key, value). */ struct { /** The pointer to the beginning of the list. */ yaml_node_pair_t *list; /* The length of the list. */ size_t length; /* The capacity of the list (used internally). */ size_t capacity; } pairs; /* The mapping style. */ yaml_mapping_style_t style; } mapping; } data; /* The beginning of the node. */ yaml_mark_t start_mark; /* The end of the node. */ yaml_mark_t end_mark; }; /* * The incomplete node object. * * This structure provides the information about a node that a tag resolver * could use to determine the specific node tag. This information includes * the path from the root node and the node content for scalar nodes. */ typedef struct yaml_incomplete_node_s { /* The node type. */ yaml_node_type_t type; /* The path to the new node. */ struct { /* The pointer to the beginning of the list. */ yaml_arc_t *list; /* The length of the list. */ size_t length; /* The capacity of the list (used internally). */ size_t capacity; } path; /* The node data. */ union { /* The scalar parameters (for `YAML_SCALAR_NODE`). */ struct { /* The scalar value. */ yaml_char_t *value; /* The length of the scalar value. */ size_t length; /* Set if the scalar is plain. */ int is_plain; } scalar; } data; /* The position of the node. */ yaml_mark_t mark; } yaml_incomplete_node_t; /* * The document object. * * A document object represents the main structure of the YAML object model: * the document graph consisting of nodes of three kinds: scalars, sequences, * and mappings with the selected root node. * * An empty document object is allocated using the function * `yaml_document_new()`. Then the function `yaml_parser_parse_document()` * could be used to load a YAML document from the input stream. Alternatively, * a document could be created with `yaml_document_create()` and its content * could be specified using the families of functions `yaml_document_add_*()` * and `yaml_document_append_*()`. A document with all associated nodes could * be destroyed using the function `yaml_document_delete()`. */ typedef struct yaml_document_s { /* The document type. */ yaml_document_type_t type; /* The document nodes (for internal use only). */ struct { /* The pointer to the beginning of the list. */ yaml_node_t *list; /* The length of the list. */ size_t length; /* The capacity of the list. */ size_t capacity; } nodes; /* The version directive or `NULL`. */ yaml_version_directive_t *version_directive; /* The list of tag directives. */ struct { /* The pointer to the beginning of the list or `NULL`. */ yaml_tag_directive_t *list; /** The length of the list. */ size_t length; /** The capacity of the list (used internally). */ size_t capacity; } tag_directives; /** Set if the document start indicator is implicit. */ int is_start_implicit; /** Set if the document end indicator is implicit. */ int is_end_implicit; /** The beginning of the document. */ yaml_mark_t start_mark; /** The end of the document. */ yaml_mark_t end_mark; } yaml_document_t; /* * Allocate a new empty document object. * * A document object allocated using this function must be deleted with * `yaml_document_delete()`. * * Returns: a new empty document object or `NULL` on error. The function may * fail if it cannot allocate memory for a new object. */ YAML_DECLARE(yaml_document_t *) yaml_document_new(void); /* * Deallocate a document object and free the associated data. * * A document object must be previously allocated with `yaml_document_new()`. * * Arguments: * * - `document`: a document object to be deallocated. */ YAML_DECLARE(void) yaml_document_delete(yaml_document_t *document); /* * Duplicate a document object. * * This function creates a complete copy of an existing document and all the * nodes it contains. The function accepts two objects: an empty document and * a model document. The model is supposed to be initialized either with * `yaml_parser_parse_document()` or constructed manually. The functions * duplicate the content of the document and its nodes and assigns it to the * empty document. * * Arguments: * * - `document`: an empty document object. * * - `model`: a document to be copied. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the state of the model. In that case, the * document remains empty. */ YAML_DECLARE(int) yaml_document_duplicate(yaml_document_t *document, yaml_document_t *model); /* * Clear the document. * * This function clears the type of the document and destroys all the document * nodes. After applying this function to a document, it becomes empty. It is * supposed that the document was previously initialized using * `yaml_parser_parse_document()` or created manually. Note that the function * `yaml_emitter_emit_document()` also clears the given document. * * Arguments: * * - `document`: a document object. */ YAML_DECLARE(void) yaml_document_clear(yaml_document_t *document); /* * Create a YAML document. * * This function initializes an empty document object allocated with * `yaml_document_new()`. Further, nodes could be added to the document using * the functions `yaml_document_add_*()` and `yaml_document_append_*()`. The * initialized document could be fed to `yaml_emitter_emit_document()`. * * Arguments: * * - `document`: an empty document object. * * - `version_directive`: a structure specifying the content of the `%YAML` * directive or `NULL` if the directive could be omitted. Note that LibYAML * supports YAML 1.1 only. The constructor does not check if the supplied * version equals to 1.1, but the emitter will fail to emit the document if * it is not so. * * - `tag_directives_list`: a pointer to a list specifying the content of the * `%TAG` directives associated with the document or `NULL` if the document * does not contain `%TAG` directives. The content of a tag directive is a * pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings. The tag * handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_` * and `-` surrounded by `!`. The tag prefix is a prefix of any valid tag, * that is, it is a non-empty prefix of either a global tag (a valid URI) or * a local tag (an arbitrary string starting with `!`). The constructor does * not check if the given directive values satisfy these requirements, but * the emitter will fail to emit the document if they are not met. * * - `tag_directives_length`: the length of `tag_directives_list`; `0` if * `tag_directives_list` is `NULL`. * * - `is_start_implicit`: `1` if the document start indicator `---` is omitted; * `0` otherwise. Note that this attribute is only a stylistic hint and * could be ignored by the emitter. * * - `is_end_implicit`: `1` if the document end indicator `...` is omitted; `0` * otherwise. Note that this attribute is only a stylistic hint and could be * ignored by the emitter. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the document parameters. In this case, the * document remains empty. */ YAML_DECLARE(int) yaml_document_create(yaml_document_t *document, const yaml_version_directive_t *version_directive, const yaml_tag_directive_t *tag_directives_list, size_t tag_directives_length, int is_start_implicit, int is_end_implicit); /** * Get a node of a YAML document. * * The root node of the document has the id `0`. * * The pointer returned by this function is valid until any of the functions * modifying the document is called. * * Arguments: * * - `document`: a document object. * * - `node_id`: the node id. The node id starts from `0` and increases by `1` * for each newly added node. Specifying a negative `node_id` is possible, * which is interpeted as the number ( - `node_id`). * * Returns: a pointer to the node object or `NULL` if `node_id` is out of * range. */ YAML_DECLARE(yaml_node_t *) yaml_document_get_node(yaml_document_t *document, int node_id); /* * Create a SCALAR node and attach it to the document. * * Note that the first node attached to a document becomes the root node. * There must exist a path from the root node to any node added to the * document, otherwise the function `yaml_emitter_emit_document()` will fail. * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * - `anchor`: the node anchor or `NULL`. The anchor should be a non-empty * NUL-terminated string containing only alphanumerical characters, `_`, and * `-`. The function does not check whether this requirement is satisfied, * but the emitter may fail to emit the node if it is not so. This parameter * is considered as a stylistic hint and could be ignored by the emitter. * The emitter may automatically generate an anchor for a node that does not * specify it or specifies a duplicate anchor. * * - `tag`: the node tag. The tag should be a non-empty UTF-8 NUL-terminated * string. The tag could be global (a valid URI) or local (an arbitrary * string starting with `!`). The function does not check whether these * requirements are satisfied, but the emitter will fail to emit the node if * it is not so. * * - `value`: the scalar value. The value should be a string containing any * valid UTF-8 character including NUL. The function does not check if * `value` is a valid UTF-8 string, but the emitter will fail to emit the * node if it is not so. * * - `length`: the length of the scalar value (in bytes) or `-1`. If `length` * is set to `-1`, the `value` is assumed to be NUL-terminated. * * - `style`: the node style. Note that this attribute only serves as a hint * and may be ignored by the emitter. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the given string buffers. If the function * succeeds, the id of the added node is returned via the pointer `node_id` * if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_scalar(yaml_document_t *document, int *node_id, const yaml_char_t *anchor, const yaml_char_t *tag, const yaml_char_t *value, int length, yaml_scalar_style_t style); /* * Create a SEQUENCE node and attach it to the document. * * Note that the first node attached to a document becomes the root node. * There must exist a path from the root node to any node added to the * document, otherwise the function `yaml_emitter_emit_document()` will fail. * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * - `anchor`: the node anchor or `NULL`. The anchor should be a non-empty * NUL-terminated string containing only alphanumerical characters, `_`, and * `-`. The function does not check whether this requirement is satisfied, * but the emitter may fail to emit the node if it is not so. This parameter * is considered as a stylistic hint and could be ignored by the emitter. * The emitter may automatically generate an anchor for a node that does not * specify it or specifies a duplicate anchor. * * - `tag`: the node tag. The tag should be a non-empty UTF-8 NUL-terminated * string. The tag could be global (a valid URI) or local (an arbitrary * string starting with `!`). The function does not check whether these * requirements are satisfied, but the emitter will fail to emit the node if * it is not so. * * - `style`: the node style. Note that this attribute only serves as a hint * and may be ignored by the emitter. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the given string buffers. If the function * succeeds, the id of the added node is returned via the pointer `node_id` * if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_sequence(yaml_document_t *document, int *node_id, const yaml_char_t *anchor, const yaml_char_t *tag, yaml_sequence_style_t style); /* * Create a MAPPING node and attach it to the document. * * Note that the first node attached to a document becomes the root node. * There must exist a path from the root node to any node added to the * document, otherwise the function `yaml_emitter_emit_document()` will fail. * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * - `anchor`: the node anchor or `NULL`. The anchor should be a non-empty * NUL-terminated string containing only alphanumerical characters, `_`, and * `-`. The function does not check whether this requirement is satisfied, * but the emitter may fail to emit the node if it is not so. This parameter * is considered as a stylistic hint and could be ignored by the emitter. * The emitter may automatically generate an anchor for a node that does not * specify it or specifies a duplicate anchor. * * - `tag`: the node tag. The tag should be a non-empty UTF-8 NUL-terminated * string. The tag could be global (a valid URI) or local (an arbitrary * string starting with `!`). The function does not check whether these * requirements are satisfied, but the emitter will fail to emit the node if * it is not so. * * - `style`: the node style. Note that this attribute only serves as a hint * and may be ignored by the emitter. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for duplicating the given string buffers. If the function * succeeds, the id of the added node is returned via the pointer `node_id` * if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_mapping(yaml_document_t *document, int *node_id, const yaml_char_t *anchor, const yaml_char_t *tag, yaml_mapping_style_t style); /* * Get the value of a `!!null` SCALAR node. * * Use this function to ensure that the given node is a scalar, the node tag is * equal to `tag:yaml.org,2002:null` and the node value is a valid null value. * Given that the `!!null` tag admits only one valid value, the value is not * returned. * * Arguments: * * - `document`: a document object. * * - `node_id`: the node id; could be negative. * * Returns: `1` if the node is a valid `!!null` scalar, `0` otherwise. */ YAML_DECLARE(int) yaml_document_get_null_node(yaml_document_t *document, int node_id); /* * Get the value of a `!!bool` SCALAR node. * * Use this function to ensure that the given node is a scalar, the node tag is * `tag:yaml.org,2002:bool` and the node value is a valid boolean value. The * function returns the true value as `1` and the false value as `0`. * * Arguments: * * - `document`: a document object. * * - `node_id`: the node id; could be negative. * * - `value`: a pointer to save the node value or `NULL`. * * Returns: `1` if the node is a valid `!!bool` scalar, `0` otherwise. If the * function succeeds and `value` is not `NULL`, the node value is saved to * `value`. */ YAML_DECLARE(int) yaml_document_get_bool_node(yaml_document_t *document, int node_id, int *value); /* * Get the value of a `!!str` SCALAR node. * * Use this function to ensure that the given node is a scalar, the node tag is * `tag:yaml.org,2002:str` and the node value is a string that does not contain * the NUL character. In this case, the function returns the node value. The * produced value is valid until the document object is cleared or deleted. * * Arguments: * * - `document`: a document object. * * - `node_id`: the node id; could be negative. * * - `value`: a pointer to save the node value or `NULL`. * * Returns: `1` if the node is a valid `!!str` scalar, `0` otherwise. If the * function succeeds and `value` is not `NULL`, the node value is saved to * `value`. */ YAML_DECLARE(int) yaml_document_get_str_node(yaml_document_t *document, int node_id, char **value); /* * Get the value of an `!!int` SCALAR node. * * Use this function to ensure that the given node is a scalar, the node tag is * `tag:yaml.org,2002:int` and the node value is a valid integer. In this * case, the function parses the node value and returns an integer number. The * function recognizes decimal, hexdecimal and octal numbers including negative * numbers. * * Arguments: * * - `document`: a document object. * * - `node_id`: the node id; could be negative. * * - `value`: a pointer to save the node value or `NULL`. * * Returns: `1` if the node is a valid `!!int` scalar, `0` otherwise. If the * function succeeds and `value` is not `NULL`, the node value is saved to * `value`. */ YAML_DECLARE(int) yaml_document_get_int_node(yaml_document_t *document, int node_id, int *value); /* * Get the value of a `!!float` SCALAR node. * * Use this function to ensure that the given node is a scalar, the node tag is * `tag:yaml.org,2002:float` and the node value is a valid float value. In * this case, the function parses the node value and returns a float number. * The function recognizes float values in exponential and fixed notation as * well as special values `.nan`, `.inf` and `-.inf`. * * Arguments: * * - `document`: a document object. * * - `node_id`: the node id; could be negative. * * - `value`: a pointer to save the node value or `NULL`. * * Returns: `1` if the node is a valid `!!float` scalar, `0` otherwise. If the * function succeeds and `value` is not `NULL`, the node value is saved to * `value`. */ YAML_DECLARE(int) yaml_document_get_float_node(yaml_document_t *document, int node_id, double *value); /* * Get the value of a `!!seq` SEQUENCE node. * * Use this function to ensure that the given node is a sequence and the node * tag is `tag:yaml.org,2002:seq`. In this case, the function returns the list * of nodes that belong to the sequence. The produced list is valid until the * document object is modified. * * Arguments: * * - `document`: a document object. * * - `node_id`: the node id; could be negative. * * - `items`: a pointer to save the list of sequence items or `NULL`. * * - `length`: a pointer to save the length of the sequence or `NULL`. * `length` must be equal to `NULL` if and only if `items` is also `NULL`. * * Returns: `1` if the node is a valid `!!seq` sequence, `0` otherwise. If the * function succeeds and `items` is not `NULL`, the list of sequence items is * saved to `items` and the sequence length is saved to `length`. */ YAML_DECLARE(int) yaml_document_get_seq_node(yaml_document_t *document, int node_id, yaml_node_item_t **items, size_t *length); /* * Get the value of a `!!map` MAPPING node. * * Use this function to ensure that the given node is a mapping and the node * tag is `tag:yaml.org,2002:map`. In this case, the function returns the list * of node pairs (key, value) that belong to the sequence. The produced list * is valid until the document is modified. * * Arguments: * * - `document`: a document object. * * - `node_id`: the node id; could be negative. * * - `pairs`: a pointer to save the list of mapping pairs or `NULL`. * * - `length`: a pointer to save the length of the mapping or `NULL`. * `length` must be equal to `NULL` if and only if `pairs` is also `NULL`. * * Returns: `1` if the node is a valid `!!map` mapping, `0` otherwise. If the * function succeeds and `pairs` is not `NULL`, the list of mapping pairs is * saved to `pairs` and the mapping length is saved to `length`. */ YAML_DECLARE(int) yaml_document_get_map_node(yaml_document_t *document, int node_id, yaml_node_pair_t **pairs, size_t *length); /* * Add a `!!null` SCALAR node to the document. * * This function is a shorthand for the call: * * yaml_document_add_scalar(document, node_id, NULL, * YAML_NULL_TAG, "null", -1, YAML_ANY_SCALAR_STYLE) * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for new buffers. If the function succeeds, the id of the * added node is returned via the pointer `node_id` if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_null_node(yaml_document_t *document, int *node_id); /* * Add a `!!bool` SCALAR node to the document. * * This function is a shorthand for the call: * * yaml_document_add_scalar(document, node_id, NULL, * YAML_BOOL_TAG, (value ? "true" : "false"), -1, * YAML_ANY_SCALAR_STYLE) * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * - `value`: a boolean value; any non-zero value is true, `0` is false. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for new buffers. If the function succeeds, the id of the * added node is returned via the pointer `node_id` if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_bool_node(yaml_document_t *document, int *node_id, int value); /* * Add a `!!str` SCALAR node to the document. * * This function is a shorthand for the call: * * yaml_document_add_scalar(document, node_id, NULL, * YAML_STR_TAG, (const yaml_char_t *) value, -1, * YAML_ANY_SCALAR_STYLE) * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * - `value`: a NUL-terminated UTF-8 string. The function does not check if * `value` is a valid UTF-8 string, but if it is not so, the emitter will * fail to emit the node. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for new buffers. If the function succeeds, the id of the * added node is returned via the pointer `node_id` if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_str_node(yaml_document_t *document, int *node_id, const char *value); /* * Add an `!!int` SCALAR node to the document. * * This function is a shorthand for the call: * * yaml_document_add_scalar(document, node_id, NULL, * YAML_INT_TAG, , -1, * YAML_ANY_SCALAR_STYLE) * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * - `value`: an integer value. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for new buffers. If the function succeeds, the id of the * added node is returned via the pointer `node_id` if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_int_node(yaml_document_t *document, int *node_id, int value); /* * Add a `!!float` SCALAR node to the document. * * This function is a shorthand for the call: * * yaml_document_add_scalar(document, node_id, NULL, * YAML_FLOAT_TAG, , -1, * YAML_ANY_SCALAR_STYLE) * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * - `value`: a float value. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for new buffers. If the function succeeds, the id of the * added node is returned via the pointer `node_id` if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_float_node(yaml_document_t *document, int *node_id, double value); /* * Add a `!!seq` SEQUENCE node to the document. * * This function is a shorthand for the call: * * yaml_document_add_sequence(document, node_id, NULL, * YAML_SEQ_TAG, YAML_ANY_SEQUENCE_STYLE) * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for new buffers. If the function succeeds, the id of the * added node is returned via the pointer `node_id` if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_seq_node(yaml_document_t *document, int *node_id); /* * Add a `!!map` MAPPING node to the document. * * This function is a shorthand for the call: * * yaml_document_add_mapping(document, node_id, NULL, * YAML_MAP_TAG, YAML_ANY_MAPPING_STYLE) * * Arguments: * * - `document`: a document object. * * - `node_id`: a pointer to save the id of the generated node or `NULL`. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for new buffers. If the function succeeds, the id of the * added node is returned via the pointer `node_id` if it is not set to `NULL`. */ YAML_DECLARE(int) yaml_document_add_map_node(yaml_document_t *document, int *node_id); /* * Add an item to a SEQUENCE node. * * The order in which items are added to a sequence coincides with the order * they are emitted into the output stream. * * Arguments: * * - `document`: a document object. * * - `sequence_id`: the id of a sequence node; could be negative. It is a * fatal error if `sequence_id` does not refer to an existing sequence node. * * - `item_id`: the id of an item node; could be negative. It is a fatal error * if `item_id` does not refer to an existing node. Note that it is possible * for `item_id` to coincide with `sequence_id`, which means that the * sequence recursively contains itself. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for internal buffers. */ YAML_DECLARE(int) yaml_document_append_sequence_item(yaml_document_t *document, int sequence_id, int item_id); /* * Add a pair of a key and a value to a MAPPING node. * * The order in which (key, value) pairs are added to a mapping coincides with * the order in which they are presented in the output stream. Note that the * mapping key order is a presentation detail and should not used to convey any * information. An ordered mapping could be represented as a sequence of * single-paired mappings. * * Arguments: * * - `document`: a document object. * * - `mapping_id`: the id of a mapping node; could be negative. It is a * fatal error if `mapping_id` does not refer to an existing mapping node. * * - `key_id`: the id of a key node; could be negative. It is a fatal error * if `key_id` does not refer to an existing node. * * - `value_id`: the id of a value node; could be negative. It is a fatal * error if `value_id` does not refer to an existing node. * * Returns: `1` on success, `0` on error. The function may fail if it cannot * allocate memory for internal buffers. */ YAML_DECLARE(int) yaml_document_append_mapping_pair(yaml_document_t *document, int mapping_id, int key_id, int value_id); /****************************************************************************** * Callback Definitions ******************************************************************************/ /* * The prototype of a read handler. * * The reader is called when the parser needs to read more bytes from the input * stream. The reader is given a buffer to fill and should returns the number * of bytes read. The reader should block if no data from the input stream is * available, but it should return immediately if it could produce least one * byte of the input stream. If the reader reaches the stream end, it should * return immediately setting the number of bytes read to `0`. * * Arguments: * * - `data`: a pointer to an application data specified with * `yaml_parser_set_reader()`. * * - `buffer`: a pointer to a buffer which should be filled with the bytes * from the input stream. * * - `capacity`: the maximum capacity of the buffer. * * - `length`: a pointer to save the actual number of bytes read from the input * stream; `length` equals `0` signifies that the reader reached the end of * the stream. * * Return: on success, the reader should return `1`. If the reader fails for * any reason, it should return `0`. On the end of the input stream, the * reader should set `length` to `0` and return `1`. */ typedef int yaml_reader_t(void *data, unsigned char *buffer, size_t capacity, size_t *length); /* * The prototype of a write handler. * * The writer is called when the emitter needs to flush the accumulated bytes * into the output stream. * * Arguments: * * - `data`: a pointer to an application data specified with * `yaml_emitter_set_writer()`. * * - `buffer`: a pointer to a buffer with bytes to be written to the output * stream. * * - `length`: the number of bytes to be written. * * Returns: on success, the writer should return `1`. If the writer fails for * any reason, it should return `0`. */ typedef int yaml_writer_t(void *data, const unsigned char *buffer, size_t length); /** * The prototype of a nonspecific tag resolver. * * The resolver is called when the parser encounters a node without an explicit * tag. The resolver should determine the correct tag of the node from the * path to the node from the root node and, in case of the scalar node, the * node value. The resolver is also called by the emitter to determine whether * the node tag could be omitted. * * Arguments: * * - `data`: a pointer to an application data specified with * `yaml_parser_set_resolver()` or `yaml_emitter_set_resolver()`. * * - `node`: information about the new node. * * - `tag`: A pointer to save the guessed node tag. The value returned by the * resolved is immediately copied. * * Returns: on success, the resolver should return `1`. If the resolver fails * for any reason, it should return `0`. */ typedef int yaml_resolver_t(void *data, yaml_incomplete_node_t *node, yaml_char_t **tag); /****************************************************************************** * Parser Definitions ******************************************************************************/ /* * An opaque definition of the parser object. * * A parser object is used to parse an input YAML stream producing a sequence * of YAML tokens, events or documents. */ typedef struct yaml_parser_s yaml_parser_t; /* * Allocate a new parser object. * * An allocated parser object should be deleted with `yaml_parser_delete()` * * Returns: a new parser object or `NULL` on error. The function may fail if * it cannot allocate memory for internal buffers. */ YAML_DECLARE(yaml_parser_t *) yaml_parser_new(void); /* * Deallocate a parser and free the internal parser data. * * A parser object must be previously allocated with `yaml_parser_new()`. * * Arguments: * * - `parser`: a parser object. */ YAML_DECLARE(void) yaml_parser_delete(yaml_parser_t *parser); /* * Clear and reinitialize the internal state of the parser. * * This function could be used for cleaning up a parser object after an error * condition or after the end of the input stream is reached. A cleaned parser * object may be reused to parse another YAML stream. Note that all the parser * parameters including the read handler must be reset. * * Arguments: * * - `parser`: a parser object. */ YAML_DECLARE(void) yaml_parser_clear(yaml_parser_t *parser); /* * Get the parser error. * * Use this function to get a detailed error information after failure of one * of the following functions: `yaml_parser_parse_token()`, * `yaml_parser_parse_event()`, `yaml_parser_parse_document()`, * `yaml_parser_parse_single_document()`. * * The pointer returned by the function is only valid until the parser object * is not modified. However the error object could be safely copied. * * Arguments: * * - `parser`: a parser object. * * Returns: a pointer to an error object. The returned pointer is only valid * until the parser object is not modified or deleted. However the error * object could be safely copied. */ YAML_DECLARE(yaml_error_t *) yaml_parser_get_error(yaml_parser_t *parser); /* * Set the parser to read the input stream from a character buffer. * * Arguments: * * - `parser`: a parser object. * * - `buffer`: a pointer to character buffer containing the input stream. The * buffer must be valid until the parser object is cleared or deleted. * * - `length`: the length of the buffer in bytes. */ YAML_DECLARE(void) yaml_parser_set_string_reader(yaml_parser_t *parser, const unsigned char *buffer, size_t length); /* * Set the parser to read the input stream from a file. * * Arguments: * * - `parser`: a parser object. * * - `file`: a pointer to an open file object. The pointer must be valid until * the parser object is cleared or deleted. */ YAML_DECLARE(void) yaml_parser_set_file_reader(yaml_parser_t *parser, FILE *file); /* * Set an input stream reader for a parser. * * Arguments: * * - `parser`: a parser object. * * - `reader`: a read handler. * * - `data`: application data for passing to the reader. */ YAML_DECLARE(void) yaml_parser_set_reader(yaml_parser_t *parser, yaml_reader_t *reader, void *data); /* * Set the standard nonspecific tag resolver for a parser. * * The standard resolver recognizes the following scalar tags: `!!null`, * `!!bool`, `!!str`, `!!int`, and `!!float`. * * Arguments: * * - `parser`: a parser object. */ YAML_DECLARE(void) yaml_parser_set_standard_resolver(yaml_parser_t *parser); /* * Set a nonspecific tag resolver for a parser. * * Arguments: * * - `parser`: a parser object. * * - `resolver`: a resolve handler. * * - `data`: application data for passing to the resolver. */ YAML_DECLARE(void) yaml_parser_set_resolver(yaml_parser_t *parser, yaml_resolver_t *resolver, void *data); /* * Set the input stream encoding. * * Typically the parser guesses the input stream encoding by the BOM mark. If * the BOM mark is not present, the UTF-8 encoding is assumed. An application * could override the detection mechanism by specifying the the encoding * explicitly. * * Arguments: * * - `parser`: a parser object. * * - `encoding`: the input stream encoding. */ YAML_DECLARE(void) yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding); /* * Parse the input stream and produce the next token. * * An application may call this function subsequently to produce a sequence of * tokens corresponding to the input stream. The first token in the sequence * is STREAM-START and the last token is STREAM-END. When the stream ends, the * parser produces empty tokens. * * An application must not alternate calls of the functions * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`, * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on * the same parser object. * * Arguments: * * - `parser`: a parser object. * * - `token`: an empty token object to save the token produced by the parser. * An application is responsible for clearing or deleting the produced token. * If the parser fails or the stream end is reached, the object is kept * empty. * * Returns: `1` on success, `0` on error. If the function succeeds and the * stream end is not reached, the token data is saved to the given token * object. If the function fails, the error details could be obtained with * `yaml_parser_get_error()`. In case of error, the parser is non-functional * until it is cleared. */ YAML_DECLARE(int) yaml_parser_parse_token(yaml_parser_t *parser, yaml_token_t *token); /* * Parse the input stream and produce the next parsing event. * * An application may call this function subsequently to produce a sequence of * events corresponding to the input stream. The produced events satisfy * the grammar: * * stream ::= STREAM-START document* STREAM-END * document ::= DOCUMENT-START node DOCUMENT-END * node ::= ALIAS | SCALAR | sequence | mapping * sequence ::= SEQUENCE-START node* SEQUENCE-END * mapping ::= MAPPING-START (node node)* MAPPING-END * * When the stream ends, the parser produces empty tokens. * * An application must not alternate calls of the functions * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`, * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on * the same parser object. * * Arguments: * * - `parser`: a parser object. * * - `event`: an empty event object to save the event produced by the parser. * An application is responsible for clearing or deleting the produced event. * Alternatively the produced event could be fed to the emitter. If the * parser fails or the stream end is reached, the object is kept empty. * * Returns: `1` on success, `0` on error. If the function succeeds and the * stream end is not reached, the event data is saved to the given event * object. If the function fails, the error details could be obtained with * `yaml_parser_get_error()`. In case of error, the parser is non-functional * until it is cleared. */ YAML_DECLARE(int) yaml_parser_parse_event(yaml_parser_t *parser, yaml_event_t *event); /* * Parse the input stream and produce the next YAML document. * * An application may call this function subsequently to produce a sequence of * documents constituting the input stream. When the stream ends, the parser * produces empty documents. * * An application must not alternate calls of the functions * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`, * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on * the same parser object. * * Arguments: * * - `parser`: a parser object. * * - `document`: an empty document object to save the document produced by the * parser. An application is responsible for clearing or deleting the * produced document. Alternatively the produced document could be fed to * the emitter. If the parser fails or the stream end is reached, the object * is kept empty. * * Returns: `1` on success, `0` on error. If the function succeeds and the * stream end is not reached, the document data is saved to the given document * object. If the function fails, the error details could be obtained with * `yaml_parser_get_error()`. In case of error, the parser is non-functional * until it is cleared. */ YAML_DECLARE(int) yaml_parser_parse_document(yaml_parser_t *parser, yaml_document_t *document); /* * Parse the input stream containing a single YAML document. * * An application may call this function to ensure that the input stream contain * no more that one document. If the stream is empty, the parser produces an * empty document. If the stream contains a single document, the parser returns * it. If the stream contains more than one document, the parser produces an * error. * * An application must not alternate calls of the functions * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`, * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on * the same parser object. * * Arguments: * * - `parser`: a parser object. * * - `document`: an empty document object to save the document produced by the * parser. An application is responsible for clearing or deleting the * produced document. Alternatively the produced document could be fed to * the emitter. If the parser fails or the stream is empty, the object is * kept empty. * * Returns: `1` on success, `0` on error. If the function succeeds and the * stream is not empty, the document data is saved to the given document * object. If the function fails, the error details could be obtained with * `yaml_parser_get_error()`. In case of error, the parser is non-functional * until it is cleared. */ YAML_DECLARE(int) yaml_parser_parse_single_document(yaml_parser_t *parser, yaml_document_t *document); /****************************************************************************** * Emitter Definitions ******************************************************************************/ /* * An opaque definition of the emitter object. * * An emitter object is used to emit YAML events or documents into an output * YAML stream. */ typedef struct yaml_emitter_s yaml_emitter_t; /* * Allocate a new emitter object. * * An allocated emitter object should be deleted with `yaml_emitter_delete()`. * * Returns: a new emitter or `NULL` on error. The function mail fail if it * cannot allocate memory for internal buffers. */ YAML_DECLARE(yaml_emitter_t *) yaml_emitter_new(void); /* * Deallocate an emitter and free the internal emitter data. * * An emitter object must be previously allocated with `yaml_emitter_new()`. * * Arguments: * * - `emitter`: an emitter object. */ YAML_DECLARE(void) yaml_emitter_delete(yaml_emitter_t *emitter); /* * Clear and reinitialize the internal state of the emitter. * * This function could be used for cleaning up an emitter object after an error * condition or after a complete YAML stream was produced. A cleaned emitter * object may be reused to produce another YAML stream. Note that all the * emitter parameters including the write handler must be reset. * * Arguments: * * - `emitter`: an emitter object. */ YAML_DECLARE(void) yaml_emitter_clear(yaml_emitter_t *emitter); /* * Get the emitter error. * * Use this function to get a detailed error information after failure of one * of the following functions: `yaml_emitter_emit_event()`, * `yaml_emitter_open()`, `yaml_emitter_close()`, * `yaml_emitter_emit_document()`, `yaml_emitter_emit_single_document()`. * * The pointer returned by the function is only valid until the emitter object * is not modified. However the error object could be safely copied. * * Arguments: * * - `emitter`: an emitter object. * * Returns: a pointer to an error object. The returned pointer is only valid * until the emitter object is not modified or deleted. However the error * object could be safely copied. */ YAML_DECLARE(yaml_error_t *) yaml_emitter_get_error(yaml_emitter_t *emitter); /* * Set the emitter to dump the generated YAML stream into a string buffer. * * Arguments: * * - `emitter`: an emitter object. * * - `buffer`: a pointer to a buffer to store the generated YAML stream. The * pointer must be valid until the emitter object is cleared or deleted. * * - `capacity`: the size of the buffer. The emitter will fail if the buffer * is smaller than required to hold the whole stream. * * - `length`: a pointer to save the length of the produced stream (in bytes). */ YAML_DECLARE(void) yaml_emitter_set_string_writer(yaml_emitter_t *emitter, unsigned char *buffer, size_t capacity, size_t *length); /* * Set the emitter to dump the generated YAML stream into a file. * * Arguments: * * - `emitter`: an emitter object. * * - `file`: a pointer to a file open for writing. The pointer must be valid * until the emitter object is cleared or deleted. */ YAML_DECLARE(void) yaml_emitter_set_file_writer(yaml_emitter_t *emitter, FILE *file); /* * Set the output stream writer for an emitter. * * Arguments: * * - `emitter`: an emitter object. * * - `writer`: a write handler. * * - `data`: application data for passing to the writer. */ YAML_DECLARE(void) yaml_emitter_set_writer(yaml_emitter_t *emitter, yaml_writer_t *writer, void *data); /* * Set the standard nonspecific tag resolver for an emitter. * * The standard resolver recognizes the following scalar tags: `!!null`, * `!!bool`, `!!str`, `!!int`, and `!!float`. * * Arguments: * * - `emitter`: an emitter object. */ YAML_DECLARE(void) yaml_emitter_set_standard_resolver(yaml_emitter_t *emitter); /* * Set a nonspecific tag resolver for an emitter. * * Arguments: * * - `emitter`: an emitter object. * * - `resolver`: a resolve handler. * * - `data`: application data for passing to the resolver. */ YAML_DECLARE(void) yaml_emitter_set_resolver(yaml_emitter_t *emitter, yaml_resolver_t *resolver, void *data); /* * Set the output stream encoding. * * The emitter uses the UTF-8 encoding for the output stream unless another * encoding is specified explicitly. The encoding could be specified using * this function or via the `encoding` parameter of the STREAM-START event. * * Arguments: * * - `emitter`: an emitter object. * * - `encoding`: the output stream encoding. */ YAML_DECLARE(void) yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding); /* * Specify if the emitter should use the "canonical" output format. * * The "canonical" format uses the flow style for collections and the * double-quoted style for scalars. Node tags are always dumped explicitly. * * Arguments: * * - `emitter`: an emitter object. * * - `is_canonical`: `1` to set the "canonical" format, `0` otherwise. */ YAML_DECLARE(void) yaml_emitter_set_canonical(yaml_emitter_t *emitter, int is_canonical); /* * Set the intendation increment. * * The default intendation increment is `2`. * * Arguments: * * - `emitter`: an emitter object. * * - `indent`: the indentation increment; a number between `2` and `9`. */ YAML_DECLARE(void) yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent); /* * Set the preferred line width. * * The default preferred line width is `80`. The given line width is only a * stylistic hint and could be violated by the emitter. When the line width is * exceeded, the emitter seeks for a way to move to the next line. * * Arguments: * * - `emitter`: an emitter object. * * - `width`: the preferred line width; `-1` means unlimited. */ YAML_DECLARE(void) yaml_emitter_set_width(yaml_emitter_t *emitter, int width); /* * Specify if non-ASCII characters could be emitted unescaped. * * By default, the emitter always escapes non-ASCII characters using the `\u` * or `\U` format. * * Arguments: * * - `emitter`: an emitter object. * * - `is_unicode`: `1` if unescaped non-ASCII characters are allowed; `0` * otherwise. */ YAML_DECLARE(void) yaml_emitter_set_unicode(yaml_emitter_t *emitter, int is_unicode); /* * Set the preferred line break. * * By default, the emitter uses the LN character for line breaks. * * Arguments: * * - `emitter`: an emitter object. * * - `line_break`: the preferred line break. */ YAML_DECLARE(void) yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break); /* * Emit an event to the output YAML stream. * * An application needs to call this function subsequently to produce a whole * YAML stream. The event sequence must satisfy the following grammar: * * stream ::= STREAM-START document* STREAM-END * document ::= DOCUMENT-START node DOCUMENT-END * node ::= ALIAS | SCALAR | sequence | mapping * sequence ::= SEQUENCE-START node* SEQUENCE-END * mapping ::= MAPPING-START (node node)* MAPPING-END * * An application must not alternate the calls of the functions * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and * `yaml_emitter_emit_single_document()` on the same emitter object. * * Arguments: * * - `emitter`: an emitter object. * * - `event`: an event to emit. The event must be previously initialized using * either one of the functions `yaml_event_create_*()` or with * `yaml_parser_parse_event()`. The emitter takes the responsibility for the * event data and clears the event, so that it becomes empty. The event is * cleared even if the function fails. * * Returns: `1` on success, `0` on error. Note that the emitter may not * immediately dump the given event, so that the function could indicate * success on an errorneous event. In this case, some of the next calls of the * function will generate an error. If the function fails, the error details * could be obtained with `yaml_emitter_get_error()`. In case of error, the * emitter is non-functional until it is cleared. */ YAML_DECLARE(int) yaml_emitter_emit_event(yaml_emitter_t *emitter, yaml_event_t *event); /* * Start a YAML stream. * * This function should be used in conjunction with * `yaml_emitter_emit_document()` and `yaml_emitter_end()`. This function must * be called once before any documents are emitted. * * Arguments: * * - `emitter`: an emitter object. * * Returns: `1` on success, `0` on error. If the function fails, the error * details could be obtained with `yaml_emitter_get_error()`. In case of * error, the emitter is non-functional until it is cleared. */ YAML_DECLARE(int) yaml_emitter_start(yaml_emitter_t *emitter); /* * Finish a YAML stream. * * This function should be used in conjunction with `yaml_emitter_start()` and * `yaml_emitter_emit_document()`. This function must be called once after all * documents are emitted. * * Arguments: * * - `emitter`: an emitter object. * * Returns: `1` on success, `0` on error. If the function fails, the error * details could be obtained with `yaml_emitter_get_error()`. In case of * error, the emitter is non-functional until it is cleared. */ YAML_DECLARE(int) yaml_emitter_end(yaml_emitter_t *emitter); /* * Emit a YAML document. * * Before emitting any documents, the function `yaml_emitter_start()` must be * called. After all documents are emitted, the function `yaml_emitter_end()` * must be called. * * An application must not alternate the calls of the functions * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and * `yaml_emitter_emit_single_document()` on the same emitter object. * * Arguments: * * - `emitter`: an emitter object. * * - `document`: a document to emit. The document must have a root node with * all the other nodes reachable from it. The document may be prepared using * the functions `yaml_document_create()`, `yaml_document_add_*()` and * `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`. * The emitter takes the responsibility for the document content and clears * the document, so that it becomes empty. The document is cleared even if * the function fails. * * Returns: `1` on success, `0` on error. If the function fails, the error * details could be obtained with `yaml_emitter_get_error()`. In case of * error, the emitter is non-functional until it is cleared. */ YAML_DECLARE(int) yaml_emitter_emit_document(yaml_emitter_t *emitter, yaml_document_t *document); /* * Emit a YAML stream consisting of a single document. * * This function is a shorthand of the calls: * * yaml_emitter_start(emitter) * yaml_emitter_emit_document(emitter, document) * yaml_emitter_end(emitter) * * An application must not alternate the calls of the functions * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and * `yaml_emitter_emit_single_document()` on the same emitter object. * * Arguments: * * - `emitter`: an emitter object. * * - `document`: a document to emit. The document must have a root node with * all the other nodes reachable from it. The document may be prepared using * the functions `yaml_document_create()`, `yaml_document_add_*()` and * `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`. * The emitter takes the responsibility for the document content and clears * the document, so that it becomes empty. The document is cleared even if * the function fails. * * Returns: `1` on success, `0` on error. If the function fails, the error * details could be obtained with `yaml_emitter_get_error()`. In case of * error, the emitter is non-functional until it is cleared. */ YAML_DECLARE(int) yaml_emitter_emit_single_document(yaml_emitter_t *emitter, yaml_document_t *document); /* * Flush the accumulated characters. * * This function flushes the accumulated characters from the internal emitter * buffer to the output stream. Note that the buffer is flushed automatically * when a complete document has emitted or a stream has ended. * * Arguments: * * - `emitter`: an emitter object. * * Returns: `1` on success, `0` on error. If the function fails, the error * details could be obtained with `yaml_emitter_get_error()`. In case of * error, the emitter is non-functional until it is cleared. */ YAML_DECLARE(int) yaml_emitter_flush(yaml_emitter_t *emitter); #ifdef __cplusplus } #endif #endif /* #ifndef YAML_H */