root/libyaml/trunk/include/yaml.h

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

/*
 * Basic conventions.
 *
 * All functions exported by exported by LibYAML starts with the the prefix
 * `yaml_`; types starts with `yaml_` and ends with `_t`; macros and
 * enumeration values start with `YAML_`.
 *
 * A function may serve as method for an object or a particular type; such
 * functions start with `yaml_<type>`.  A type constructor is named
 * `yaml_<type>_new()`, a type destructor is named `yaml_<type>_delete()`.
 *
 * A function signifies whether it succeeded or failed with its return value;
 * typically it is `1` for success, `0` for failure.  Functions that return a
 * pointer may indicate an error condition by returning `NULL`.  Functions that
 * never fail commonly do not return any value.  For most of the functions, an
 * error value means that the function is unable to allocate some memory
 * buffer.  For parsing and emitting functions, detailed information on the
 * nature of the error could be obtained.
 *
 * LibYAML provides two active objects: parsers and emitters and three passive
 * objects: tokens, events and documents.
 *
 * 
 *
 *
 * 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 <stdlib.h>
#include <stdio.h>
#include <string.h>

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