Ignore:
Timestamp:
01/03/08 22:33:04 (6 years ago)
Author:
xi
Message:

Drop doxygen support, add more API documentation, API changes.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • libyaml/trunk/include/yaml.h

    r265 r266  
    1 /** 
    2  * @file yaml.h 
    3  * @brief Public interface for libyaml. 
    4  *  
    5  * Include the header file with the code: 
    6  * @code 
    7  * #include <yaml.h> 
    8  * @endcode 
    9  */ 
     1/***************************************************************************** 
     2 * Public Interface for LibYAML 
     3 * 
     4 * Copyright (c) 2006 Kirill Simonov 
     5 * 
     6 * LibYAML is free software; you can use, modify and/or redistribute it under 
     7 * the terms of the MIT license; see the file LICENCE for more details. 
     8 *****************************************************************************/ 
     9 
     10/* 
     11 * General guidelines. 
     12 * 
     13 * Naming conventions: all functions exported by LibYAML starts with the `yaml_` prefix; 
     14 * types starts with `yaml_` and ends with `_t`; macros and enumerations starts 
     15 * with `YAML_`. 
     16 * 
     17 * FIXME: Calling conventions. 
     18 * FIXME: Memory allocation. 
     19 * FIXME: Errors and exceptions. 
     20 * FIXME: And so on, and so forth. 
     21 */ 
     22 
    1023 
    1124#ifndef YAML_H 
     
    2033#include <string.h> 
    2134 
    22 /** 
    23  * @defgroup export Export Definitions 
    24  * @{ 
    25  */ 
    26  
    27 /** The public API declaration. */ 
     35/***************************************************************************** 
     36 * Export Definitions 
     37 *****************************************************************************/ 
     38 
     39/* 
     40 * Public API declarations. 
     41 * 
     42 * The following definitions are relevant only for the Win32 platform.  If you 
     43 * are building LibYAML as a static library or linking your application against 
     44 * LibYAML compiled as a static library, define the macro 
     45 * `YAML_DECLARE_STATIC`.  If you are building LibYAML as a dynamic library 
     46 * (DLL), you need to define `YAML_DECLARE_EXPORT`.  You don't need to define 
     47 * any macros in case you are linking your application against LibYAML compiled 
     48 * as DLL. 
     49 * 
     50 * There is no need to define any macros if you use LibYAML on non-Win32 
     51 * platform. 
     52 */ 
    2853 
    2954#ifdef WIN32 
     
    3964#endif 
    4065 
    41 /** @} */ 
    42  
    43 /** 
    44  * @defgroup version Version Information 
    45  * @{ 
    46  */ 
    47  
    48 /** The major version number. */ 
     66/***************************************************************************** 
     67 * Version Information 
     68 *****************************************************************************/ 
     69 
     70/* 
     71 * The major, minor and patch version numbers of LibYAML. 
     72 */ 
     73 
    4974#define YAML_VERSION_MAJOR  0 
    50  
    51 /** The minor version number. */ 
    5275#define YAML_VERSION_MINOR  2 
    53  
    54 /** The patch version number. */ 
    5576#define YAML_VERSION_PATCH  0 
    5677 
    57 /** The version string generator macro. */ 
    58 #define YAML_VERSION_STRING_GENERATOR(major,minor,patch)                        \ 
    59     (#major "." #minor "." #patch) 
    60  
    61 /** The version string. */ 
    62 #define YAML_VERSION_STRING                                                     \ 
    63     YAML_VERSION_STRING_GENERATOR(YAML_VERSION_MAJOR,YAML_VERSION_MINOR,YAML_VERSION_PATCH) 
    64  
    65 /** 
     78/* 
     79 * The version of LibYAML as a string. 
     80 */ 
     81 
     82#define YAML_VERSION_STRING "0.2.0" 
     83 
     84/* 
    6685 * Get the library version numbers at runtime. 
    6786 * 
    68  * @param[out]      major   Major version number. 
    69  * @param[out]      minor   Minor version number. 
    70  * @param[out]      patch   Patch version number. 
     87 * Arguments: 
     88 * 
     89 * - `major`: a pointer to store the major version number. 
     90 * 
     91 * - `minor`: a pointer to store the minor version number. 
     92 * 
     93 * - `patch`: a pointer to store the patch version number. 
    7194 */ 
    7295 
     
    7497yaml_get_version(int *major, int *minor, int *patch); 
    7598 
    76 /** 
     99/* 
    77100 * Get the library version as a string at runtime. 
    78101 * 
    79  * @returns The function returns the pointer to a static string of the form 
    80  * @c "X.Y.Z", where @c X is the major version number, @c Y is the minor version 
    81  * number, and @c Z is the patch version number. 
     102 * Returns: the version of LibYAML as a static string. 
    82103 */ 
    83104 
     
    85106yaml_get_version_string(void); 
    86107 
    87 /** @} */ 
    88  
    89 /** 
    90  * @defgroup styles Error Handling 
    91  * @{ 
    92  */ 
    93  
    94 /** Many bad things could happen with the parser and the emitter. */ 
     108/***************************************************************************** 
     109 * Error Handling 
     110 *****************************************************************************/ 
     111 
     112/* 
     113 * The type of the error. 
     114 * 
     115 * The YAML parser and emitter reports any error details using the 
     116 * `yaml_error_t` structure.  The error type shows what subsystem generated the 
     117 * error and what additional information about the error is available. 
     118 */ 
     119 
    95120typedef enum yaml_error_type_e { 
    96     /** No error is produced. */ 
     121    /* No error was produced. */ 
    97122    YAML_NO_ERROR, 
    98123 
    99     /** Cannot allocate or reallocate a block of memory. */ 
     124    /* Cannot allocate or reallocate a block of memory. */ 
    100125    YAML_MEMORY_ERROR, 
    101126 
    102     /** Cannot read from the input stream. */ 
     127    /* Cannot read from the input stream. */ 
    103128    YAML_READER_ERROR, 
    104     /** Cannot decode the input stream. */ 
     129    /* Cannot decode a character in the input stream. */ 
    105130    YAML_DECODER_ERROR, 
    106     /** Cannot scan a YAML token. */ 
     131    /* Cannot scan a YAML token. */ 
    107132    YAML_SCANNER_ERROR, 
    108     /** Cannot parse a YAML production. */ 
     133    /* Cannot parse a YAML event. */ 
    109134    YAML_PARSER_ERROR, 
    110     /** Cannot compose a YAML document. */ 
     135    /* Cannot compose a YAML document. */ 
    111136    YAML_COMPOSER_ERROR, 
    112137 
    113     /** Cannot write into the output stream. */ 
     138    /* Cannot write into the output stream. */ 
    114139    YAML_WRITER_ERROR, 
    115     /** Cannot emit a YAML event. */ 
     140    /* Cannot emit a YAML event. */ 
    116141    YAML_EMITTER_ERROR, 
    117     /** Cannot serialize a YAML document. */ 
     142    /* Cannot serialize a YAML document. */ 
    118143    YAML_SERIALIZER_ERROR, 
    119144 
    120     /** Cannot resolve an implicit tag. */ 
     145    /* Cannot resolve an implicit YAML node tag. */ 
    121146    YAML_RESOLVER_ERROR 
    122147} yaml_error_type_t; 
    123148 
    124 /** The pointer position. */ 
     149/* 
     150 * Position in the input stream. 
     151 * 
     152 * Marks are used to indicate the position of YAML tokens, events and documents 
     153 * in the input stream as well as to point to the place where a parser error has 
     154 * occured. 
     155 */ 
     156 
    125157typedef struct yaml_mark_s { 
    126     /** The character number (starting from zero). */ 
     158    /* The number of the character in the input stream (starting from zero). */ 
    127159    size_t index; 
    128  
    129     /** The mark line (starting from zero). */ 
     160    /* The line in the input stream (starting from zero). */ 
    130161    size_t line; 
    131  
    132     /** The mark column (starting from zero). */ 
     162    /* The column in the input stream (starting from zero). */ 
    133163    size_t column; 
    134164} yaml_mark_t; 
    135165 
    136 /** The error details. */ 
     166/* 
     167 * Error details. 
     168 * 
     169 * The structure gives detailed information on any problem that occured during 
     170 * parsing or emitting. 
     171 */ 
     172 
    137173typedef struct yaml_error_s { 
    138174 
    139     /** The error type. */ 
     175    /* The error type. */ 
    140176    yaml_error_type_t type; 
    141177 
    142     /** The detailed error information. */ 
     178    /* The specific information for each error type. */ 
    143179    union { 
    144180 
    145         /** 
    146          * A problem while reading the stream (@c YAML_READER_ERROR or 
    147          * @c YAML_DECODER_ERROR). 
     181        /* 
     182         * A problem occured while reading the input stream (relevant for 
     183         * `YAML_READER_ERROR` and `YAML_DECODER_ERROR`). 
    148184         */ 
    149185        struct { 
    150             /** The problem description. */ 
     186            /* The problem description. */ 
    151187            const char *problem; 
    152             /** The stream offset. */ 
     188            /* The position in the input stream, in bytes. */ 
    153189            size_t offset; 
    154             /** The problematic octet or character (@c -1 if not applicable). */ 
     190            /* The problematic octet or character (`-1` if not applicable). */ 
    155191            int value; 
    156192        } reading; 
    157193 
    158         /** 
    159          * A problem while loading the stream (@c YAML_SCANNER_ERROR, 
    160          * @c YAML_PARSER_ERROR, or @c YAML_COMPOSER_ERROR). 
     194        /* 
     195         * A problem occured while loading YAML data from the input stream 
     196         * (relevant for `YAML_SCANNER_ERROR`, `YAML_PARSER_ERROR`, and 
     197         * `YAML_COMPOSER_ERROR`). 
    161198         */ 
    162199        struct { 
    163             /** The context in which the problem occured 
    164              * (@c NULL if not applicable). 
    165              */ 
     200            /* The description of the context in which the problem occured 
     201               (`NULL` if not applicable). */ 
    166202            const char *context; 
    167             /** The context mark (if @c problem_mark is not @c NULL). **/ 
     203            /* The context mark (if `context` is not `NULL`). */ 
    168204            yaml_mark_t context_mark; 
    169             /** The problem description. */ 
     205            /* The problem description. */ 
    170206            const char *problem; 
    171             /** The problem mark. */ 
     207            /* The problem mark. */ 
    172208            yaml_mark_t problem_mark; 
    173209        } loading; 
    174210 
    175         /** A problem while writing into the stream (@c YAML_WRITER_ERROR). */ 
     211        /* 
     212         * A problem occured while writing into the output stream (relevant for 
     213         * `YAML_WRITER_ERROR`). 
     214         */ 
    176215        struct { 
    177             /** The problem description. */ 
     216            /* The problem description. */ 
    178217            const char *problem; 
    179             /** The stream offset. */ 
     218            /* The position in the output stream, in bytes. */ 
    180219            size_t offset; 
    181220        } writing; 
    182221 
    183         /** A problem while dumping into the stream (@c YAML_EMITTER_ERROR and 
    184          * @c YAML_SERIALIZER_ERROR). 
     222        /* 
     223         * A problem while dumping YAML data into the output stream (relevant 
     224         * for `YAML_EMITTER_ERROR` and `YAML_SERIALIZER_ERROR`). 
    185225         */ 
    186226        struct { 
    187             /** The problem description. */ 
     227            /* The problem description. */ 
    188228            const char *problem; 
    189229        } dumping; 
    190230 
    191         /** A problem while resolving an implicit tag (@c YAML_RESOLVER_ERROR). */ 
     231        /* 
     232         * A problem occured while resolving an implicit YAML node tag 
     233         * (relevant for `YAML_RESOLVER_ERROR`). 
     234         */ 
    192235        struct { 
    193             /** The problem description. */ 
     236            /* The problem description. */ 
    194237            const char *problem; 
    195238        } resolving; 
     
    199242} yaml_error_t; 
    200243 
    201 /** 
    202  * Create an error message. 
    203  * 
    204  * @param[in]   error   An error object. 
    205  * @param[out]  buffer         model   A token to copy. 
    206  * 
    207  * @returns @c 1 if the function succeeded, @c 0 on error.  The function may 
    208  * fail if the buffer is not large enough to contain the whole message. 
     244/* 
     245 * Generate an error message. 
     246 * 
     247 * Given an instance of the `yaml_error_t` structure and a buffer, the function 
     248 * fills the buffer with a message describing the error.  The generated message 
     249 * follows the pattern: `"Error type: error details"`.  If the buffer is not 
     250 * large enough to hold the whole message, the function fails. 
     251 * 
     252 * Arguments: 
     253 * 
     254 * - `error`: an error object obtained using `yaml_parser_get_error()` or 
     255 *   `yaml_emitter_get_error()`. 
     256 * 
     257 * - `buffer`: a pointer to a character buffer to be filled with a generated 
     258 *   error message. 
     259 * 
     260 * - `capacity`: the size of the buffer. 
     261 * 
     262 * Returns: `1` if the function succeeded, `0` on error.  The function may fail 
     263 * if the provided buffer is not large enough to hold the whole buffer, in 
     264 * which case an application may increase the size of the buffer and call the 
     265 * function again.  If the function fails, the content of the buffer is 
     266 * undefined. 
    209267 */ 
    210268 
     
    212270yaml_error_message(yaml_error_t *error, char *buffer, size_t capacity); 
    213271 
    214 /** @} */ 
    215  
    216 /** 
    217  * @defgroup basic Basic Types 
    218  * @{ 
    219  */ 
    220  
    221 /** The character type (UTF-8 octet). */ 
     272/****************************************************************************** 
     273 * Basic Types 
     274 ******************************************************************************/ 
     275 
     276/* 
     277 * The character type (UTF-8 octet). 
     278 * 
     279 * Usage of the string type `(yaml_char_t *)` in the LibYAML API indicates that 
     280 * the string is encoded in UTF-8. 
     281 */ 
     282 
    222283typedef unsigned char yaml_char_t; 
    223284 
    224 /** The version directive data. */ 
     285/* 
     286 * The version directive information. 
     287 * 
     288 * Note that LibYAML only supports YAML 1.1. 
     289 */ 
     290 
    225291typedef struct yaml_version_directive_s { 
    226     /** The major version number. */ 
     292    /* The major version number. */ 
    227293    int major; 
    228     /** The minor version number. */ 
     294    /* The minor version number. */ 
    229295    int minor; 
    230296} yaml_version_directive_t; 
    231297 
    232 /** The tag directive data. */ 
     298/* 
     299 * The tag directive information. 
     300 */ 
     301 
    233302typedef struct yaml_tag_directive_s { 
    234     /** The tag handle. */ 
     303    /* The tag handle. */ 
    235304    yaml_char_t *handle; 
    236     /** The tag prefix. */ 
     305    /* The tag prefix. */ 
    237306    yaml_char_t *prefix; 
    238307} yaml_tag_directive_t; 
    239308 
    240 /** The stream encoding. */ 
     309/* 
     310 * The stream encoding. 
     311 * 
     312 * An application may explicitly specify the encoding in the input stream or 
     313 * let the parser to detect the input stream encoding from a BOM mark.  If the 
     314 * stream does not start with a BOM mark, UTF-8 is assumed. 
     315 * 
     316 * An application may specify the encoding of the output stream or let the 
     317 * emitter to choose a suitable encoding, in which case, UTF-8 is used. 
     318 */ 
     319 
    241320typedef enum yaml_encoding_e { 
    242     /** Let the parser choose the encoding. */ 
     321    /* The default/autodetected encoding. */ 
    243322    YAML_ANY_ENCODING, 
    244     /** The default UTF-8 encoding. */ 
     323    /* The UTF-8 encoding. */ 
    245324    YAML_UTF8_ENCODING, 
    246     /** The UTF-16-LE encoding with BOM. */ 
     325    /* The UTF-16-LE encoding. */ 
    247326    YAML_UTF16LE_ENCODING, 
    248     /** The UTF-16-BE encoding with BOM. */ 
     327    /* The UTF-16-BE encoding. */ 
    249328    YAML_UTF16BE_ENCODING 
    250329} yaml_encoding_t; 
    251330 
    252 /** Line break types. */ 
     331/* 
     332 * Line break types. 
     333 * 
     334 * An application may specify the line break type the emitter should use or 
     335 * leave it to the emitter discretion.  In the latter case, LN (Unix style) is 
     336 * used. 
     337 */ 
     338 
    253339typedef enum yaml_break_e { 
    254     /** Let the parser choose the break type. */ 
     340    /* Let the parser choose the break type. */ 
    255341    YAML_ANY_BREAK, 
    256     /** Use CR for line breaks (Mac style). */ 
     342    /* Use CR for line breaks (Mac style). */ 
    257343    YAML_CR_BREAK, 
    258     /** Use LN for line breaks (Unix style). */ 
     344    /* Use LN for line breaks (Unix style). */ 
    259345    YAML_LN_BREAK, 
    260     /** Use CR LN for line breaks (DOS style). */ 
     346    /* Use CR LN for line breaks (DOS style). */ 
    261347    YAML_CRLN_BREAK 
    262348} yaml_break_t; 
    263349 
    264 /** @} */ 
    265  
    266 /** 
    267  * @defgroup styles Node Styles 
    268  * @{ 
    269  */ 
    270  
    271 /** Scalar styles. */ 
     350/****************************************************************************** 
     351 * Node Styles 
     352 ******************************************************************************/ 
     353 
     354/* 
     355 * Scalar styles. 
     356 * 
     357 * There are two groups of scalar types in YAML: flow and block.  Flow scalars 
     358 * are divided into three styles: plain, single-quoted, and double-quoted; 
     359 * block scalars are divided into two styles: literal and folded. 
     360 * 
     361 * The parser reports the style in which a scalar node is represented, however 
     362 * it is a purely presentation details that must not be used in interpreting 
     363 * the node content. 
     364 * 
     365 * An application may suggest a preferred node style or leave it completely 
     366 * to the emitter discretion.  Note that the emitter may ignore any stylistic 
     367 * suggestions. 
     368 */ 
     369 
    272370typedef enum yaml_scalar_style_e { 
    273     /** Let the emitter choose the style. */ 
     371    /* Let the emitter choose the style. */ 
    274372    YAML_ANY_SCALAR_STYLE, 
    275373 
    276     /** The plain scalar style. */ 
     374    /* The plain flow scalar style. */ 
    277375    YAML_PLAIN_SCALAR_STYLE, 
    278376 
    279     /** The single-quoted scalar style. */ 
     377    /* The single-quoted flow scalar style. */ 
    280378    YAML_SINGLE_QUOTED_SCALAR_STYLE, 
    281     /** The double-quoted scalar style. */ 
     379    /* The double-quoted flow scalar style. */ 
    282380    YAML_DOUBLE_QUOTED_SCALAR_STYLE, 
    283381 
    284     /** The literal scalar style. */ 
     382    /* The literal block scalar style. */ 
    285383    YAML_LITERAL_SCALAR_STYLE, 
    286     /** The folded scalar style. */ 
     384    /* The folded block scalar style. */ 
    287385    YAML_FOLDED_SCALAR_STYLE 
    288386} yaml_scalar_style_t; 
    289387 
    290 /** Sequence styles. */ 
     388/* 
     389 * Sequence styles. 
     390 * 
     391 * YAML supports two sequence styles: flow and block. 
     392 * 
     393 * The parser reports the style of a sequence node, but this information should 
     394 * not be used in interpreting the sequence content. 
     395 * 
     396 * An application may suggest a preferred sequence style or leave it completely 
     397 * to the emitter discretion.  Note that the emitter may ignore any stylistic 
     398 * hints. 
     399 */ 
    291400typedef enum yaml_sequence_style_e { 
    292     /** Let the emitter choose the style. */ 
     401    /* Let the emitter choose the style. */ 
    293402    YAML_ANY_SEQUENCE_STYLE, 
    294403 
    295     /** The block sequence style. */ 
     404    /* The flow sequence style. */ 
     405    YAML_FLOW_SEQUENCE_STYLE 
     406    /* The block sequence style. */ 
    296407    YAML_BLOCK_SEQUENCE_STYLE, 
    297     /** The flow sequence style. */ 
    298     YAML_FLOW_SEQUENCE_STYLE 
    299408} yaml_sequence_style_t; 
    300409 
    301 /** Mapping styles. */ 
     410/* 
     411 * Mapping styles. 
     412 * 
     413 * YAML supports two mapping styles: flow and block. 
     414 * 
     415 * The parser reports the style of a mapping node, but this information should 
     416 * not be used in interpreting the mapping content. 
     417 * 
     418 * An application may suggest a preferred mapping style or leave it completely 
     419 * to the emitter discretion.  Note that the emitter may ignore any stylistic 
     420 * hints. 
     421 */ 
     422 
    302423typedef enum yaml_mapping_style_e { 
    303     /** Let the emitter choose the style. */ 
     424    /* Let the emitter choose the style. */ 
    304425    YAML_ANY_MAPPING_STYLE, 
    305426 
    306     /** The block mapping style. */ 
     427    /* The block mapping style. */ 
    307428    YAML_BLOCK_MAPPING_STYLE, 
    308     /** The flow mapping style. */ 
     429    /* The flow mapping style. */ 
    309430    YAML_FLOW_MAPPING_STYLE 
    310 /*    YAML_FLOW_SET_MAPPING_STYLE   */ 
    311431} yaml_mapping_style_t; 
    312432 
    313 /** @} */ 
    314  
    315 /** 
    316  * @defgroup tokens Tokens 
    317  * @{ 
    318  */ 
    319  
    320 /** Token types. */ 
     433/****************************************************************************** 
     434 * Tokens 
     435 ******************************************************************************/ 
     436 
     437/* 
     438 * Token types. 
     439 * 
     440 * The LibYAML scanner generates the following types of tokens: 
     441 * 
     442 * - STREAM-START: indicates the beginning of the stream. 
     443 * 
     444 * - STREAM-END: indicates the end of the stream. 
     445 * 
     446 * - VERSION-DIRECTIVE: describes the `%YAML` directive. 
     447 * 
     448 * - TAG-DIRECTIVE: describes the `%TAG` directive. 
     449 * 
     450 * - DOCUMENT-START: the indicator `---`. 
     451 * 
     452 * - DOCUMENT-END: the indicator `...`. 
     453 * 
     454 * - BLOCK-SEQUENCE-START: indentation increase indicating the beginning of a 
     455 *   block sequence node. 
     456 * 
     457 * - BLOCK-MAPPING-START: indentation increase indicating the beginning of a 
     458 *   block mapping node. 
     459 * 
     460 * - BLOCK-END: indentation decrease indicating the end of a block collection 
     461 *   node. 
     462 * 
     463 * - FLOW-SEQUENCE-START: the indicator `[`. 
     464 * 
     465 * - FLOW-SEQUENCE-END: the indicator `]`. 
     466 * 
     467 * - FLOW-MAPPING-START: the indicator `{`. 
     468 * 
     469 * - FLOW-MAPPING-END: the indicator `}`. 
     470 * 
     471 * - BLOCK-ENTRY: the beginning of an item of a block sequence. 
     472 * 
     473 * - FLOW-ENTRY: the beginning of an item of a flow sequence. 
     474 * 
     475 * - KEY: the beginning of a simple key, or the indicator `?`. 
     476 * 
     477 * - VALUE: the indicator `:`. 
     478 * 
     479 * - ALIAS: an alias of a node. 
     480 * 
     481 * - ANCHOR: a node anchor. 
     482 * 
     483 * - TAG: a node tag. 
     484 * 
     485 * - SCALAR: the content of a scalar node. 
     486 */ 
     487 
    321488typedef enum yaml_token_type_e { 
    322     /** An empty token. */ 
     489    /* An empty unitialized token. */ 
    323490    YAML_NO_TOKEN, 
    324491 
    325     /** A STREAM-START token. */ 
     492    /* A STREAM-START token. */ 
    326493    YAML_STREAM_START_TOKEN, 
    327     /** A STREAM-END token. */ 
     494    /* A STREAM-END token. */ 
    328495    YAML_STREAM_END_TOKEN, 
    329496 
    330     /** A VERSION-DIRECTIVE token. */ 
     497    /* A VERSION-DIRECTIVE token. */ 
    331498    YAML_VERSION_DIRECTIVE_TOKEN, 
    332     /** A TAG-DIRECTIVE token. */ 
     499    /* A TAG-DIRECTIVE token. */ 
    333500    YAML_TAG_DIRECTIVE_TOKEN, 
    334     /** A DOCUMENT-START token. */ 
     501    /* A DOCUMENT-START token. */ 
    335502    YAML_DOCUMENT_START_TOKEN, 
    336     /** A DOCUMENT-END token. */ 
     503    /* A DOCUMENT-END token. */ 
    337504    YAML_DOCUMENT_END_TOKEN, 
    338505 
    339     /** A BLOCK-SEQUENCE-START token. */ 
     506    /* A BLOCK-SEQUENCE-START token. */ 
    340507    YAML_BLOCK_SEQUENCE_START_TOKEN, 
    341     /** A BLOCK-SEQUENCE-END token. */ 
     508    /* A BLOCK-SEQUENCE-END token. */ 
    342509    YAML_BLOCK_MAPPING_START_TOKEN, 
    343     /** A BLOCK-END token. */ 
     510    /* A BLOCK-END token. */ 
    344511    YAML_BLOCK_END_TOKEN, 
    345512 
    346     /** A FLOW-SEQUENCE-START token. */ 
     513    /* A FLOW-SEQUENCE-START token. */ 
    347514    YAML_FLOW_SEQUENCE_START_TOKEN, 
    348     /** A FLOW-SEQUENCE-END token. */ 
     515    /* A FLOW-SEQUENCE-END token. */ 
    349516    YAML_FLOW_SEQUENCE_END_TOKEN, 
    350     /** A FLOW-MAPPING-START token. */ 
     517    /* A FLOW-MAPPING-START token. */ 
    351518    YAML_FLOW_MAPPING_START_TOKEN, 
    352     /** A FLOW-MAPPING-END token. */ 
     519    /* A FLOW-MAPPING-END token. */ 
    353520    YAML_FLOW_MAPPING_END_TOKEN, 
    354521 
    355     /** A BLOCK-ENTRY token. */ 
     522    /* A BLOCK-ENTRY token. */ 
    356523    YAML_BLOCK_ENTRY_TOKEN, 
    357     /** A FLOW-ENTRY token. */ 
     524    /* A FLOW-ENTRY token. */ 
    358525    YAML_FLOW_ENTRY_TOKEN, 
    359     /** A KEY token. */ 
     526    /* A KEY token. */ 
    360527    YAML_KEY_TOKEN, 
    361     /** A VALUE token. */ 
     528    /* A VALUE token. */ 
    362529    YAML_VALUE_TOKEN, 
    363530 
    364     /** An ALIAS token. */ 
     531    /* An ALIAS token. */ 
    365532    YAML_ALIAS_TOKEN, 
    366     /** An ANCHOR token. */ 
     533    /* An ANCHOR token. */ 
    367534    YAML_ANCHOR_TOKEN, 
    368     /** A TAG token. */ 
     535    /* A TAG token. */ 
    369536    YAML_TAG_TOKEN, 
    370     /** A SCALAR token. */ 
     537    /* A SCALAR token. */ 
    371538    YAML_SCALAR_TOKEN 
    372539} yaml_token_type_t; 
    373540 
    374 /** The token structure. */ 
     541/* 
     542 * The token object. 
     543 * 
     544 * Typically the token API is too low-level to be used directly by 
     545 * applications.  A possible user of the token API is a syntax highlighting 
     546 * application. 
     547 */ 
     548 
    375549typedef struct yaml_token_s { 
    376550 
    377     /** The token type. */ 
     551    /* The token type. */ 
    378552    yaml_token_type_t type; 
    379553 
    380     /** The token data. */ 
     554    /* The token data. */ 
    381555    union { 
    382556 
    383         /** The stream start (for @c YAML_STREAM_START_TOKEN). */ 
     557        /* Extra data associated with a STREAM-START token. */ 
    384558        struct { 
    385             /** The stream encoding. */ 
     559            /* The stream encoding. */ 
    386560            yaml_encoding_t encoding; 
    387561        } stream_start; 
    388562 
    389         /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */ 
     563        /* Extra data associated with a VERSION-DIRECTIVE token. */ 
    390564        struct { 
    391             /** The major version number. */ 
     565            /* The major version number. */ 
    392566            int major; 
    393             /** The minor version number. */ 
     567            /* The minor version number. */ 
    394568            int minor; 
    395569        } version_directive; 
    396570 
    397         /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */ 
     571        /* Extra data associated with a TAG-DIRECTIVE token. */ 
    398572        struct { 
    399             /** The tag handle. */ 
     573            /* The tag handle. */ 
    400574            yaml_char_t *handle; 
    401             /** The tag prefix. */ 
     575            /* The tag prefix. */ 
    402576            yaml_char_t *prefix; 
    403577        } tag_directive; 
    404578 
    405         /** The alias (for @c YAML_ALIAS_TOKEN). */ 
     579        /* Extra data associated with an ALIAS token. */ 
    406580        struct { 
    407             /** The alias value. */ 
     581            /* The alias value. */ 
    408582            yaml_char_t *value; 
    409583        } alias; 
    410584 
    411         /** The anchor (for @c YAML_ANCHOR_TOKEN). */ 
     585        /* Extra data associated with an ANCHOR token. */ 
    412586        struct { 
    413             /** The anchor value. */ 
     587            /* The anchor value. */ 
    414588            yaml_char_t *value; 
    415589        } anchor; 
    416590 
    417         /** The tag (for @c YAML_TAG_TOKEN). */ 
     591        /* Extra data associated with a TAG token. */ 
    418592        struct { 
    419             /** The tag handle. */ 
     593            /* The tag handle. */ 
    420594            yaml_char_t *handle; 
    421             /** The tag suffix. */ 
     595            /* The tag suffix. */ 
    422596            yaml_char_t *suffix; 
    423597        } tag; 
    424598 
    425         /** The scalar value (for @c YAML_SCALAR_TOKEN). */ 
     599        /* Extra data associated with a SCALAR token. */ 
    426600        struct { 
    427             /** The scalar value. */ 
     601            /* The scalar value. */ 
    428602            yaml_char_t *value; 
    429             /** The length of the scalar value. */ 
     603            /* The length of the scalar value. */ 
    430604            size_t length; 
    431             /** The scalar style. */ 
     605            /* The scalar style. */ 
    432606            yaml_scalar_style_t style; 
    433607        } scalar; 
     
    435609    } data; 
    436610 
    437     /** The beginning of the token. */ 
     611    /* The beginning of the token. */ 
    438612    yaml_mark_t start_mark; 
    439     /** The end of the token. */ 
     613    /* The end of the token. */ 
    440614    yaml_mark_t end_mark; 
    441615 
    442616} yaml_token_t; 
    443617 
    444 /** 
     618/* 
    445619 * Allocate a new empty token object. 
    446620 * 
    447  * @returns a new token object or @c NULL on error. 
     621 * A token object allocated using this function must be deleted with 
     622 * `yaml_token_delete()`. 
     623 * 
     624 * Returns: a new empty token object or `NULL` on error.  The function may fail 
     625 * if it cannot allocate memory for a new token object. 
    448626 */ 
    449627 
     
    451629yaml_token_new(void); 
    452630 
    453 /** 
    454  * Delete and deallocate a token object. 
    455  * 
    456  * @param[in,out]   token   A token object. 
     631/* 
     632 * Deallocate a token object and free the associated data. 
     633 * 
     634 * A token object must be previously allocated with `yaml_token_new()`. 
     635 * 
     636 * Arguments: 
     637 * 
     638 * - `token`: a token object to be deallocated. 
    457639 */ 
    458640 
     
    460642yaml_token_delete(yaml_token_t *token); 
    461643 
    462 /** 
     644/* 
    463645 * Duplicate a token object. 
    464646 * 
    465  * @param[in,out]   token   An empty token object. 
    466  * @param[in]       model   A token to copy. 
    467  * 
    468  * @returns @c 1 if the function succeeded, @c 0 on error. 
     647 * This function creates a deep copy of an existing token object.  It accepts 
     648 * two token objects: an empty token and a model token.  The latter is supposed 
     649 * to be initialized with `yaml_parser_parse_token()`.  The function assigns 
     650 * the type of the model to the empty token as well as duplicates and copies 
     651 * the internal state associated with the model token. 
     652 * 
     653 * Arguments: 
     654 * 
     655 * - `token`: an empty token object. 
     656 * 
     657 * - `model`: a token to be copied. 
     658 * 
     659 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     660 * allocate memory for duplicating the state of the model token.  In that case, 
     661 * the token remains empty. 
    469662 */ 
    470663 
     
    472665yaml_token_duplicate(yaml_token_t *token, const yaml_token_t *model); 
    473666 
    474 /** 
    475  * Free any memory allocated for a token object. 
    476  * 
    477  * @param[in,out]   token   A token object. 
     667/* 
     668 * Clear the token state. 
     669 * 
     670 * This function clears the type and the internal state of a token object 
     671 * freeing any associated data.  After applying this function to a token, it 
     672 * becomes empty.  It is supposed that the token was previously initialized 
     673 * using `yaml_parser_parse_token()` or `yaml_token_duplicate()`. 
     674 * 
     675 * Arguments: 
     676 * 
     677 * - `token`: a token object. 
    478678 */ 
    479679 
    480680YAML_DECLARE(void) 
    481 yaml_token_destroy(yaml_token_t *token); 
    482  
    483 /** @} */ 
    484  
    485 /** 
    486  * @defgroup events Events 
    487  * @{ 
    488  */ 
    489  
    490 /** Event types. */ 
     681yaml_token_clear(yaml_token_t *token); 
     682 
     683/****************************************************************************** 
     684 * Events 
     685 ******************************************************************************/ 
     686 
     687/* 
     688 * Event types. 
     689 * 
     690 * The LibYAML parser generates, while the LibYAML emitter accepts, YAML events 
     691 * of the following types: 
     692 * 
     693 * - STREAM-START: indicates the beginning of the stream. 
     694 * 
     695 * - STREAM-END: indicates the end of the stream. 
     696 * 
     697 * - DOCUMENT-START: indicates the beginning of the document. 
     698 * 
     699 * - DOCUMENT-END: indicates the end of the document. 
     700 * 
     701 * - ALIAS: an alias to an already produced node. 
     702 * 
     703 * - SCALAR: a scalar node. 
     704 * 
     705 * - SEQUENCE-START: indicates the beginning of a sequence node. 
     706 * 
     707 * - SEQUENCE-END: indicates the end of a sequence node. 
     708 * 
     709 * - MAPPING-START: indicates the beginning of a mapping node. 
     710 * 
     711 * - MAPPING-END: indicates the end of a mapping node. 
     712 * 
     713 * A valid sequence of events obeys the grammar: 
     714 * 
     715 *      stream ::= STREAM-START document* STREAM-END 
     716 *      document ::= DOCUMENT-START node DOCUMENT-END 
     717 *      node ::= ALIAS | SCALAR | sequence | mapping 
     718 *      sequence ::= SEQUENCE-START node* SEQUENCE-END 
     719 *      mapping ::= MAPPING-START (node node)* MAPPING-END 
     720 */ 
     721 
    491722typedef enum yaml_event_type_e { 
    492     /** An empty event. */ 
     723    /* An empty unitialized event. */ 
    493724    YAML_NO_EVENT, 
    494725 
    495     /** A STREAM-START event. */ 
     726    /* A STREAM-START event. */ 
    496727    YAML_STREAM_START_EVENT, 
    497     /** A STREAM-END event. */ 
     728    /* A STREAM-END event. */ 
    498729    YAML_STREAM_END_EVENT, 
    499730 
    500     /** A DOCUMENT-START event. */ 
     731    /* A DOCUMENT-START event. */ 
    501732    YAML_DOCUMENT_START_EVENT, 
    502     /** A DOCUMENT-END event. */ 
     733    /* A DOCUMENT-END event. */ 
    503734    YAML_DOCUMENT_END_EVENT, 
    504735 
    505     /** An ALIAS event. */ 
     736    /* An ALIAS event. */ 
    506737    YAML_ALIAS_EVENT, 
    507     /** A SCALAR event. */ 
     738    /* A SCALAR event. */ 
    508739    YAML_SCALAR_EVENT, 
    509740 
    510     /** A SEQUENCE-START event. */ 
     741    /* A SEQUENCE-START event. */ 
    511742    YAML_SEQUENCE_START_EVENT, 
    512     /** A SEQUENCE-END event. */ 
     743    /* A SEQUENCE-END event. */ 
    513744    YAML_SEQUENCE_END_EVENT, 
    514745 
    515     /** A MAPPING-START event. */ 
     746    /* A MAPPING-START event. */ 
    516747    YAML_MAPPING_START_EVENT, 
    517     /** A MAPPING-END event. */ 
     748    /* A MAPPING-END event. */ 
    518749    YAML_MAPPING_END_EVENT 
    519750} yaml_event_type_t; 
    520751 
    521 /** The event structure. */ 
     752/* 
     753 * The event object. 
     754 * 
     755 * The event-level API of LibYAML should be used for streaming applications. 
     756 */ 
     757 
    522758typedef struct yaml_event_s { 
    523759 
    524     /** The event type. */ 
     760    /* The event type. */ 
    525761    yaml_event_type_t type; 
    526762 
    527     /** The event data. */ 
     763    /* The event data. */ 
    528764    union { 
    529765         
    530         /** The stream parameters (for @c YAML_STREAM_START_EVENT). */ 
     766        /* The stream parameters (for `YAML_STREAM_START_EVENT`). */ 
    531767        struct { 
    532             /** The document encoding. */ 
     768            /* The document encoding. */ 
    533769            yaml_encoding_t encoding; 
    534770        } stream_start; 
    535771 
    536         /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */ 
     772        /* The document parameters (for `YAML_DOCUMENT_START_EVENT`). */ 
    537773        struct { 
    538             /** The version directive. */ 
     774            /* The version directive or `NULL` if not present. */ 
    539775            yaml_version_directive_t *version_directive; 
    540776 
    541             /** The list of tag directives. */ 
     777            /* The list of tag directives. */ 
    542778            struct { 
    543                 /** The beginning of the list. */ 
     779                /* The beginning of the list or `NULL`. */ 
    544780                yaml_tag_directive_t *list; 
    545                 /** The length of the list. */ 
     781                /* The length of the list. */ 
    546782                size_t length; 
    547                 /** The capacity of the list. */ 
     783                /* The capacity of the list (used internally). */ 
    548784                size_t capacity; 
    549785            } tag_directives; 
    550786 
    551             /** Is the document indicator implicit? */ 
     787            /* Set if the document indicator is omitted. */ 
    552788            int is_implicit; 
    553789        } document_start; 
    554790 
    555         /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */ 
     791        /* The document end parameters (for `YAML_DOCUMENT_END_EVENT`). */ 
    556792        struct { 
    557             /** Is the document end indicator implicit? */ 
     793            /* Set if the document end indicator is omitted. */ 
    558794            int is_implicit; 
    559795        } document_end; 
    560796 
    561         /** The alias parameters (for @c YAML_ALIAS_EVENT). */ 
     797        /* The alias parameters (for `YAML_ALIAS_EVENT`). */ 
    562798        struct { 
    563             /** The anchor. */ 
     799            /* The anchor. */ 
    564800            yaml_char_t *anchor; 
    565801        } alias; 
    566802 
    567         /** The scalar parameters (for @c YAML_SCALAR_EVENT). */ 
     803        /* The scalar parameters (for `YAML_SCALAR_EVENT`). */ 
    568804        struct { 
    569             /** The anchor. */ 
     805            /* The node anchor or `NULL`. */ 
    570806            yaml_char_t *anchor; 
    571             /** The tag. */ 
     807            /* The node tag or `NULL`. */ 
    572808            yaml_char_t *tag; 
    573             /** The scalar value. */ 
     809            /* The scalar value. */ 
    574810            yaml_char_t *value; 
    575             /** The length of the scalar value. */ 
     811            /* The length of the scalar value (in bytes). */ 
    576812            size_t length; 
    577             /** Is the tag optional for the plain style? */ 
    578             int is_plain_implicit; 
    579             /** Is the tag optional for any non-plain style? */ 
    580             int is_quoted_implicit; 
    581             /** The scalar style. */ 
     813            /* Set if the tag is optional for the plain style. */ 
     814            int is_plain_nonspecific; 
     815            /* Set if the tag is optional for any non-plain style. */ 
     816            int is_quoted_nonspecific; 
     817            /* The scalar style. */ 
    582818            yaml_scalar_style_t style; 
    583819        } scalar; 
    584820 
    585         /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */ 
     821        /* The sequence parameters (for `YAML_SEQUENCE_START_EVENT`). */ 
    586822        struct { 
    587             /** The anchor. */ 
     823            /* The node anchor or `NULL`. */ 
    588824            yaml_char_t *anchor; 
    589             /** The tag. */ 
     825            /* The node tag or `NULL`. */ 
    590826            yaml_char_t *tag; 
    591             /** Is the tag optional? */ 
    592             int is_implicit; 
    593             /** The sequence style. */ 
     827            /* Set if the tag is optional. */ 
     828            int is_nonspecific; 
     829            /* The sequence style. */ 
    594830            yaml_sequence_style_t style; 
    595831        } sequence_start; 
    596832 
    597         /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */ 
     833        /* The mapping parameters (for `YAML_MAPPING_START_EVENT`). */ 
    598834        struct { 
    599             /** The anchor. */ 
     835            /* The node anchor or `NULL`. */ 
    600836            yaml_char_t *anchor; 
    601             /** The tag. */ 
     837            /* The node tag or `NULL`. */ 
    602838            yaml_char_t *tag; 
    603             /** Is the tag optional? */ 
    604             int is_implicit; 
    605             /** The mapping style. */ 
     839            /* Set if the tag is optional. */ 
     840            int is_nonspecific; 
     841            /* The mapping style. */ 
    606842            yaml_mapping_style_t style; 
    607843        } mapping_start; 
     
    609845    } data; 
    610846 
    611     /** The beginning of the event. */ 
     847    /* The beginning of the event. */ 
    612848    yaml_mark_t start_mark; 
    613     /** The end of the event. */ 
     849    /* The end of the event. */ 
    614850    yaml_mark_t end_mark; 
    615851 
    616852} yaml_event_t; 
    617853 
    618 /** 
     854/* 
    619855 * Allocate a new empty event object. 
    620856 * 
    621  * @returns a new event object or @c NULL on error. 
     857 * An event object allocated using this function must be deleted with 
     858 * `yaml_event_delete()`. 
     859 * 
     860 * Returns: a new empty event object or `NULL` on error.  The function may fail 
     861 * if it cannot allocate memory for a new event object. 
    622862 */ 
    623863 
     
    625865yaml_event_new(void); 
    626866 
    627 /** 
    628  * Delete and deallocate an event object. 
    629  * 
    630  * @param[in,out]   event   An event object. 
     867/* 
     868 * Deallocate an event object and free the associated data. 
     869 * 
     870 * An event object must be previously allocated with `yaml_event_new()`. 
     871 * 
     872 * Arguments: 
     873 * 
     874 * - `event`: an event object to be deallocated. 
    631875 */ 
    632876 
     
    634878yaml_event_delete(yaml_event_t *event); 
    635879 
    636 /** 
    637  * Duplicate a event object. 
    638  * 
    639  * @param[in,out]   event   An empty event object. 
    640  * @param[in]       model   An event to copy. 
    641  * 
    642  * @returns @c 1 if the function succeeded, @c 0 on error. 
     880/* 
     881 * Duplicate an event object. 
     882 * 
     883 * This function creates a deep copy of an existing event object.  It accepts 
     884 * two objects: an empty event and a model event.  The model event is supposed 
     885 * to be initialized either with `yaml_parser_parse_event()` or using one of 
     886 * the functions `yaml_event_create_*()`.  The function assigns the type of the 
     887 * model to the empty event and copies the internal state associated with the 
     888 * model event. 
     889 * 
     890 * Arguments: 
     891 * 
     892 * - `event`: an empty event object. 
     893 * 
     894 * - `model`: an event to be copied. 
     895 * 
     896 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     897 * allocate memory for duplicating the state of the model event.  In that case, 
     898 * the event remains empty. 
    643899 */ 
    644900 
     
    646902yaml_event_duplicate(yaml_event_t *event, const yaml_event_t *model); 
    647903 
    648 /** 
     904/* 
     905 * Clear the event state. 
     906 * 
     907 * This function clears the type and the internal state of an event object 
     908 * freeing any associated data.  After applying this function to an event, it 
     909 * becomes empty.  It is supposed that the event was previously initialized 
     910 * using `yaml_parser_parse_event()` or `yaml_event_duplicate()`.  Note that 
     911 * the function `yaml_emitter_emit_event()` also clears the given event. 
     912 * 
     913 * Arguments: 
     914 * 
     915 * - `event`: an event object. 
     916 */ 
     917 
     918YAML_DECLARE(void) 
     919yaml_event_clear(yaml_event_t *event); 
     920 
     921/* 
    649922 * Create a STREAM-START event. 
    650923 * 
    651  * This function never fails. 
    652  * 
    653  * @param[out]      event       An empty event object. 
    654  * @param[in]       encoding    The stream encoding. 
    655  * 
    656  * @returns @c 1 if the function succeeded, @c 0 on error. 
     924 * This function initializes an empty event object allocated with 
     925 * `yaml_event_new()`.  The initialized event could be fed to 
     926 * `yaml_emitter_emit_event()`. 
     927 * 
     928 * Arguments: 
     929 * 
     930 * - `event`: an empty event object. 
     931 * 
     932 * - `encoding`: the stream encoding. 
     933 * 
     934 * Returns: `1`.  The function never fails. 
    657935 */ 
    658936 
     
    661939        yaml_encoding_t encoding); 
    662940 
    663 /** 
     941/* 
    664942 * Create a STREAM-END event. 
    665943 * 
    666  * This function never fails. 
    667  * 
    668  * @param[out]      event       An empty event object. 
    669  * 
    670  * @returns @c 1 if the function succeeded, @c 0 on error. 
     944 * This function initializes an empty event object allocated with 
     945 * `yaml_event_new()`.  The initialized event could be fed to 
     946 * `yaml_emitter_emit_event()`. 
     947 * 
     948 * Arguments: 
     949 * 
     950 * - `event`: an empty event object. 
     951 * 
     952 * Returns: `1`.  The function never fails. 
    671953 */ 
    672954 
     
    674956yaml_event_create_stream_end(yaml_event_t *event); 
    675957 
    676 /** 
    677  * Create the DOCUMENT-START event. 
    678  * 
    679  * @param[out]      event                   An empty event object. 
    680  * @param[in]       version_directive       The %YAML directive value or 
    681  *                                          @c NULL. 
    682  * @param[in]       tag_directives_list     The beginning of the %TAG 
    683  *                                          directives list or @c NULL.  The 
    684  *                                          list ends with @c (NULL,NULL). 
    685  * @param[in]       is_implicit             Set if the document start 
    686  *                                          indicator is optional.  This 
    687  *                                          parameter is stylistic and may be 
    688  *                                          ignored by the parser. 
    689  * 
    690  * @returns @c 1 if the function succeeded, @c 0 on error. 
     958/* 
     959 * Create a DOCUMENT-START event. 
     960 * 
     961 * This function initializes an empty event object allocated with 
     962 * `yaml_event_new()`.  The initialized event could be fed to 
     963 * `yaml_emitter_emit_event()`. 
     964 * 
     965 * Arguments: 
     966 * 
     967 * - `event`: an empty event object. 
     968 * 
     969 * - `version_directive`: a structure specifying the content of the `%YAML` 
     970 *   directive or `NULL` if the directive could be omitted.  Note that LibYAML 
     971 *   supports YAML 1.1 only.  The function does not check if the supplied 
     972 *   version equals to 1.1, but the emitter will fail to emit the event if it 
     973 *   is not so. 
     974 * 
     975 * - `tag_directives_list`: a pointer to a list specifying the content of the 
     976 *   `%TAG` directives associated with the document or `NULL` if the document 
     977 *   does not contain `%TAG` directives.  The content of a tag directive is a 
     978 *   pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings.  The tag 
     979 *   handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_` 
     980 *   and `-` surrounded by `!`.  The tag prefix is a prefix of any valid tag, 
     981 *   that is, it is a non-empty prefix of either a global tag (a valid URI) or 
     982 *   a local tag (an arbitrary string starting with `!`).  The function does 
     983 *   not check if the given directive values satisfy these requirements, but 
     984 *   the emitter will fail to emit the event if they are not met. 
     985 * 
     986 * - `tag_directives_length`: the length of `tag_directives_list`; `0` if 
     987 *   `tag_directives_list` is `NULL`. 
     988 * 
     989 * - `is_implicit`: `1` if the document indicator `---` is omitted, `0` 
     990 *   otherwise.  Note that this attribute is only a stylistic hint and could be 
     991 *   ignored by the emitter. 
     992 * 
     993 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     994 * allocate memory for duplicating the event parameters.  In this case, the 
     995 * event remains empty. 
    691996 */ 
    692997 
     
    694999yaml_event_create_document_start(yaml_event_t *event, 
    6951000        const yaml_version_directive_t *version_directive, 
    696         const yaml_tag_directive_t *tag_directives, 
     1001        const yaml_tag_directive_t *tag_directives_list, 
     1002        size_t tag_directives_length, 
    6971003        int is_implicit); 
    6981004 
    699 /** 
    700  * Create the DOCUMENT-END event. 
    701  * 
    702  * @param[out]      event       An empty event object. 
    703  * @param[in]       is_implicit Set if the document end indicator is optional. 
    704  *                              This parameter is stylistic and may be ignored 
    705  *                              by the parser. 
    706  * 
    707  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1005/* 
     1006 * Create a DOCUMENT-END event. 
     1007 * 
     1008 * This function initializes an empty event object allocated with 
     1009 * `yaml_event_new()`.  The initialized event could be fed to 
     1010 * `yaml_emitter_emit_event()`. 
     1011 * 
     1012 * Arguments: 
     1013 * 
     1014 * - `event`: an empty event object. 
     1015 * 
     1016 * - `is_implicit`: `1` if the document end indicator `...` is omitted, `0` 
     1017 *   otherwise.  Note that this attribute is only a stylistic hint and could be 
     1018 *   ignored by the emitter. 
     1019 * 
     1020 * Returns: `1`.  The function never fails. 
    7081021 */ 
    7091022 
     
    7111024yaml_event_create_document_end(yaml_event_t *event, int is_implicit); 
    7121025 
    713 /** 
    714  * Create an ALIAS event. 
    715  * 
    716  * @param[out]      event       An empty event object. 
    717  * @param[in]       anchor      The anchor value. 
    718  * 
    719  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1026/* 
     1027 * Create an ANCHOR event. 
     1028 * 
     1029 * This function initializes an empty event object allocated with 
     1030 * `yaml_event_new()`.  The initialized event could be fed to 
     1031 * `yaml_emitter_emit_event()`. 
     1032 * 
     1033 * Arguments: 
     1034 * 
     1035 * - `event`: an empty event object. 
     1036 * 
     1037 * - `anchor`: the anchor value.  The anchor should be a non-empty 
     1038 *   NUL-terminated string containing only alphanumerical characters, `_`, and 
     1039 *   `-`.  The function does not check if this requirement is satisfied, but if 
     1040 *   it is not so, the emitter will fail to emit the generated event. 
     1041 * 
     1042 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1043 * allocate memory for duplicating `anchor`.  In this case, the event remains 
     1044 * empty. 
    7201045 */ 
    7211046 
     
    7231048yaml_event_create_alias(yaml_event_t *event, const yaml_char_t *anchor); 
    7241049 
    725 /** 
     1050/* 
    7261051 * Create a SCALAR event. 
    7271052 * 
    728  * @param[out]      event                   An empty event object. 
    729  * @param[in]       anchor                  The scalar anchor or @c NULL. 
    730  * @param[in]       tag                     The scalar tag or @c NULL.  If 
    731  *                                          latter, one of the 
    732  *                                          @a is_plain_implicit and 
    733  *                                          @a is_quoted_implicit flags must 
    734  *                                          be set. 
    735  * @param[in]       value                   The scalar value. 
    736  * @param[in]       length                  The length of the scalar value. 
    737  * @param[in]       is_plain_implicit       Set if the tag may be omitted for 
    738  *                                          the plain style. 
    739  * @param[in]       is_quoted_implicit      Set if the tag may be omitted for 
    740  *                                          any non-plain style. 
    741  * @param[in]       style                   The scalar style.  This attribute 
    742  *                                          may be ignored by the emitter. 
    743  * 
    744  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1053 * This function initializes an empty event object allocated with 
     1054 * `yaml_event_new()`.  The initialized event could be fed to 
     1055 * `yaml_emitter_emit_event()`. 
     1056 * 
     1057 * Arguments: 
     1058 * 
     1059 * - `event`: an empty event object. 
     1060 * 
     1061 * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty 
     1062 *   NUL-terminated string containing only alphanumerical characters, `_`, and 
     1063 *   `-`. 
     1064 * 
     1065 * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8 
     1066 *   NUL-terminated string.  The tag could be global (a valid URI) or local (an 
     1067 *   arbitrary string starting with `!`).  If `NULL` is provided, at least one 
     1068 *   of the flags `is_plain_nonspecific` and `is_quoted_nonspecific` must be 
     1069 *   set.  The function does not check whether these requirements are 
     1070 *   satisfied, but the emitter will fail to emit the event if it is not so. 
     1071 * 
     1072 * - `value`: the value of the scalar node.  The value should be a UTF-8 
     1073 *   string.  It could contain any valid UTF-8 character including NUL.  The 
     1074 *   function does not check if `value` is a valid UTF-8 string, but the 
     1075 *   emitter will fail to emit the event if it is not so. 
     1076 * 
     1077 * - `length`: the length of the scalar value (in bytes) or `-1`.  If `length` 
     1078 *   is set to `-1`, the `value` is assumed to be NUL-terminated. 
     1079 * 
     1080 * - `is_plain_nonspecific`: `1` if the node tag could be omitted while 
     1081 *   emitting the node provided that the the plain style is used for 
     1082 *   representing the node value; `0` otherwise.  That this flag is set assumes 
     1083 *   that the tag could be correctly determined by the parser using the node 
     1084 *   position and content. 
     1085 * 
     1086 * - `is_quoted_nonspecific`: `1` if the node tag could be omitted while 
     1087 *   emitting the node provided that the node value is represented using any 
     1088 *   non-plain style; `0` otherwise.  That this flag is set assumes that the 
     1089 *   tag could be correctly determined by the parser using the node position 
     1090 *   and content. 
     1091 * 
     1092 * - `style`: the node style.  Note that this attribute only serves as a hint 
     1093 *   and may be ignored by the emitter. 
     1094 * 
     1095 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1096 * allocate memory for duplicating the given string buffers.  In this case, the 
     1097 * event remains empty. 
    7451098 */ 
    7461099 
     
    7481101yaml_event_create_scalar(yaml_event_t *event, 
    7491102        const yaml_char_t *anchor, const yaml_char_t *tag, 
    750         const yaml_char_t *value, size_t length, 
    751         int is_plain_implicit, int is_quoted_implicit, 
     1103        const yaml_char_t *value, int length, 
     1104        int is_plain_nonspecific, int is_quoted_nonspecific, 
    7521105        yaml_scalar_style_t style); 
    7531106 
    754 /** 
     1107/* 
    7551108 * Create a SEQUENCE-START event. 
    7561109 * 
    757  * @param[out]      event       An empty event object. 
    758  * @param[in]       anchor      The sequence anchor or @c NULL. 
    759  * @param[in]       tag         The sequence tag or @c NULL.  If latter, the 
    760  *                              @a is_implicit flag must be set. 
    761  * @param[in]       is_implicit Set if the tag may be omitted. 
    762  * @param[in]       style       The sequence style.  This attribute may be 
    763  *                              ignored by the parser. 
    764  * 
    765  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1110 * This function initializes an empty event object allocated with 
     1111 * `yaml_event_new()`.  The initialized event could be fed to 
     1112 * `yaml_emitter_emit_event()`. 
     1113 * 
     1114 * Arguments: 
     1115 * 
     1116 * - `event`: an empty event object. 
     1117 * 
     1118 * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty 
     1119 *   NUL-terminated string containing only alphanumerical characters, `_`, and 
     1120 *   `-`.  The function does not check if this requirement is satisfied, but if 
     1121 *   it is not so, the emitter will fail to emit the generated event. 
     1122 * 
     1123 * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8 
     1124 *   NUL-terminated string.  The tag could be global (a valid URI) or local (an 
     1125 *   arbitrary string starting with `!`).  If `NULL` is provided, the flag 
     1126 *   `is_nonspecific` must be set.  The function does not check whether these 
     1127 *   requirements are satisfied, but if it is not so, the emitter will fail to 
     1128 *   emit the generated event. 
     1129 * 
     1130 * - `is_nonspecific`: `1` if the node tag could be omitted while 
     1131 *   emitting the node; `0` otherwise.  This flag should only be set if the 
     1132 *   node tag could be correctly determined by the parser using the node 
     1133 *   position in the document graph. 
     1134 * 
     1135 * - `style`: the node style.  Note that this attribute only serves as a hint 
     1136 *   and may be ignored by the emitter. 
     1137 * 
     1138 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1139 * allocate memory for duplicating the given string buffers.  In this case, the 
     1140 * event remains empty. 
    7661141 */ 
    7671142 
     
    7691144yaml_event_create_sequence_start(yaml_event_t *event, 
    7701145        const yaml_char_t *anchor, const yaml_char_t *tag, 
    771         int is_implicit, yaml_sequence_style_t style); 
    772  
    773 /** 
     1146        int is_nonspecific, yaml_sequence_style_t style); 
     1147 
     1148/* 
    7741149 * Create a SEQUENCE-END event. 
    7751150 * 
    776  * @param[out]      event       An empty event object. 
    777  * 
    778  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1151 * This function initializes an empty event object allocated with 
     1152 * `yaml_event_new()`.  The initialized event could be fed to 
     1153 * `yaml_emitter_emit_event()`. 
     1154 * 
     1155 * Arguments: 
     1156 * 
     1157 * - `event`: an empty event object. 
     1158 * 
     1159 * Returns: `1`.  This function never fails. 
    7791160 */ 
    7801161 
     
    7821163yaml_event_create_sequence_end(yaml_event_t *event); 
    7831164 
    784 /** 
     1165/* 
    7851166 * Create a MAPPING-START event. 
    7861167 * 
    787  * @param[out]      event       An empty event object. 
    788  * @param[in]       anchor      The mapping anchor or @c NULL. 
    789  * @param[in]       tag         The mapping tag or @c NULL.  If latter, the 
    790  *                              @a is_implicit flag must be set. 
    791  * @param[in]       is_implicit Set if the tag may be omitted. 
    792  * @param[in]       style       The mapping style. 
    793  * 
    794  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1168 * This function initializes an empty event object allocated with 
     1169 * `yaml_event_new()`.  The initialized event could be fed to 
     1170 * `yaml_emitter_emit_event()`. 
     1171 * 
     1172 * Arguments: 
     1173 * 
     1174 * - `event`: an empty event object. 
     1175 * 
     1176 * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty 
     1177 *   NUL-terminated string containing only alphanumerical characters, `_`, and 
     1178 *   `-`.  The function does not check if this requirement is satisfied, but if 
     1179 *   it is not so, the emitter will fail to emit the generated event. 
     1180 * 
     1181 * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8 
     1182 *   NUL-terminated string.  The tag could be global (a valid URI) or local (an 
     1183 *   arbitrary string starting with `!`).  If `NULL` is provided, the flag 
     1184 *   `is_nonspecific` must be set.  The function does not check whether these 
     1185 *   requirements are satisfied, but if it is not so, the emitter will fail to 
     1186 *   emit the generated event. 
     1187 * 
     1188 * - `is_nonspecific`: `1` if the node tag could be omitted while 
     1189 *   emitting the node; `0` otherwise.  This flag should only be set if the 
     1190 *   node tag could be correctly determined by the parser using the node 
     1191 *   position in the document graph. 
     1192 * 
     1193 * - `style`: the node style.  Note that this attribute only serves as a hint 
     1194 *   and may be ignored by the emitter. 
     1195 * 
     1196 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1197 * allocate memory for duplicating the given string buffers.  In this case, the 
     1198 * event remains empty. 
    7951199 */ 
    7961200 
     
    7981202yaml_event_create_mapping_start(yaml_event_t *event, 
    7991203        const yaml_char_t *anchor, const yaml_char_t *tag, 
    800         int is_implicit, yaml_mapping_style_t style); 
    801  
    802 /** 
     1204        int is_nonspecific, yaml_mapping_style_t style); 
     1205 
     1206/* 
    8031207 * Create a MAPPING-END event. 
    8041208 * 
    805  * @param[out]      event       An empty event object. 
    806  * 
    807  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1209 * This function initializes an empty event object allocated with 
     1210 * `yaml_event_new()`.  The initialized event could be fed to 
     1211 * `yaml_emitter_emit_event()`. 
     1212 * 
     1213 * Arguments: 
     1214 * 
     1215 * - `event`: an empty event object. 
     1216 * 
     1217 * Returns: `1`.  This function never fails. 
    8081218 */ 
    8091219 
     
    8111221yaml_event_create_mapping_end(yaml_event_t *event); 
    8121222 
    813 /** 
    814  * Free any memory allocated for an event object. 
    815  * 
    816  * @param[in,out]   event   An event object. 
    817  */ 
    818  
    819 YAML_DECLARE(void) 
    820 yaml_event_destroy(yaml_event_t *event); 
    821  
    822 /** @} */ 
    823  
    824 /** 
    825  * @defgroup nodes Nodes 
    826  * @{ 
    827  */ 
    828  
    829 /** The tag @c !!null with the only possible value: @c null. */ 
     1223/****************************************************************************** 
     1224 * Documents and Nodes 
     1225 ******************************************************************************/ 
     1226 
     1227/* 
     1228 * Well-known scalar tags. 
     1229 */ 
     1230 
    8301231#define YAML_NULL_TAG       ((const yaml_char_t *) "tag:yaml.org,2002:null") 
    831 /** The tag @c !!bool with the values: @c true and @c falce. */ 
    8321232#define YAML_BOOL_TAG       ((const yaml_char_t *) "tag:yaml.org,2002:bool") 
    833 /** The tag @c !!str for string values. */ 
    8341233#define YAML_STR_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:str") 
    835 /** The tag @c !!int for integer values. */ 
    8361234#define YAML_INT_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:int") 
    837 /** The tag @c !!float for float values. */ 
    8381235#define YAML_FLOAT_TAG      ((const yaml_char_t *) "tag:yaml.org,2002:float") 
    8391236 
    840 /** The tag @c !!seq is used to denote sequences. */ 
     1237/* 
     1238 * Basic collection tags. 
     1239 */ 
     1240 
    8411241#define YAML_SEQ_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:seq") 
    842 /** The tag @c !!map is used to denote mapping. */ 
    8431242#define YAML_MAP_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:map") 
    8441243 
    845 /** The default scalar tag is @c !!str. */ 
     1244/* 
     1245 * The default tags for nodes lacking an explicit tag. 
     1246 */ 
     1247 
    8461248#define YAML_DEFAULT_SCALAR_TAG     YAML_STR_TAG 
    847 /** The default sequence tag is @c !!seq. */ 
    8481249#define YAML_DEFAULT_SEQUENCE_TAG   YAML_SEQ_TAG 
    849 /** The default mapping tag is @c !!map. */ 
    8501250#define YAML_DEFAULT_MAPPING_TAG    YAML_MAP_TAG 
    8511251 
    852 /** Node types. */ 
     1252/* 
     1253 * Document types. 
     1254 * 
     1255 * There are no different document types in LibYAML: the document type field is 
     1256 * only used to distinguish between newly allocated documents and those that 
     1257 * are initialized with `yaml_parser_parse_document()` or 
     1258 * `yaml_document_create()`. 
     1259 */ 
     1260 
     1261typedef enum yaml_document_type_e { 
     1262    /* An empty uninitialized document. */ 
     1263    YAML_NO_DOCUMENT. 
     1264 
     1265    /* A YAML document. */ 
     1266    YAML_DOCUMENT 
     1267} yaml_document_type_t; 
     1268 
     1269/* 
     1270 * Node types. 
     1271 * 
     1272 * YAML recognizes three kinds of nodes: scalar, sequence and mapping. 
     1273 */ 
     1274 
    8531275typedef enum yaml_node_type_e { 
    854     /** An empty node. */ 
     1276    /* An empty node. */ 
    8551277    YAML_NO_NODE, 
    8561278 
    857     /** A scalar node. */ 
     1279    /* A scalar node. */ 
    8581280    YAML_SCALAR_NODE, 
    859     /** A sequence node. */ 
     1281    /* A sequence node. */ 
    8601282    YAML_SEQUENCE_NODE, 
    861     /** A mapping node. */ 
     1283    /* A mapping node. */ 
    8621284    YAML_MAPPING_NODE 
    8631285} yaml_node_type_t; 
    8641286 
    865 /** Arc types. */ 
     1287/* 
     1288 * Arc types. 
     1289 * 
     1290 * Arcs are used to specify the path from the root node to a given node in the 
     1291 * document graph.  There are three kinds of arcs: an item in a sequence node, 
     1292 * a key in a mapping node, and a value in a mapping node. 
     1293 */ 
     1294 
    8661295typedef enum yaml_arc_type_e { 
    867     /** An empty arc. */ 
     1296    /* An empty arc. */ 
    8681297    YAML_NO_ARC, 
    8691298 
    870     /** An item of a sequence. */ 
     1299    /* An item of a sequence. */ 
    8711300    YAML_SEQUENCE_ITEM_ARC, 
    872     /** A key of a mapping. */ 
     1301    /* A key of a mapping. */ 
    8731302    YAML_MAPPING_KEY_ARC, 
    874     /** A value of a mapping. */ 
     1303    /* A value of a mapping. */ 
    8751304    YAML_MAPPING_VALUE_ARC 
    8761305} yaml_arc_type_t; 
    8771306 
    878 /** The forward definition of a document node structure. */ 
    879 typedef struct yaml_node_s yaml_node_t; 
    880  
    881 /** An element of a sequence node. */ 
     1307/* 
     1308 * An element of a sequence node. 
     1309 */ 
     1310 
    8821311typedef int yaml_node_item_t; 
    8831312 
    884 /** An element of a mapping node. */ 
     1313/* 
     1314 * An element of a mapping node. 
     1315 */ 
     1316 
    8851317typedef struct yaml_node_pair_s { 
    886     /** The key of the element. */ 
     1318    /* A key in a mapping. */ 
    8871319    int key; 
    888     /** The value of the element. */ 
     1320    /* A value in a mapping. */ 
    8891321    int value; 
    8901322} yaml_node_pair_t; 
    8911323 
    892 /** An element of a path in a YAML document. */ 
     1324/* 
     1325 * A path element. 
     1326 * 
     1327 * An arc is an element of a path from the root node to some other node in a 
     1328 * YAML document.  An arc consists of a collection node and information on how 
     1329 * it is connected to the next node in the path.  If the arc type is a sequence 
     1330 * item, then the collection node is a sequence and the arc refers to the index 
     1331 * in this sequence.  If the arc type is a mapping key, then the collection 
     1332 * node is a mapping.  If the arc type is a mapping value, then the collection 
     1333 * node is a mapping and the arc refers to the key associated to the value. 
     1334 */ 
     1335 
    8931336typedef struct yaml_arc_s { 
    894     /** The arc type. */ 
     1337 
     1338    /* The arc type. */ 
    8951339    yaml_arc_type_t type; 
    896     /** The collection node. */ 
    897     int node; 
    898     /** A pointer in the collection node. */ 
    899     int item; 
     1340 
     1341    /* The tag of the collection node. */ 
     1342    yaml_char_t *tag; 
     1343 
     1344    /* The connection information. */ 
     1345    union { 
     1346 
     1347        /* The sequence item data (for `YAML_SEQUENCE_ITEM_ARC`). */ 
     1348        struct { 
     1349            /* The index of the item in the sequence (starting from `0`). */ 
     1350            int index; 
     1351        } item; 
     1352 
     1353        /* The mapping value data (for `YAML_MAPPING_VALUE_ARC`). */ 
     1354        struct { 
     1355            /* The key associated with the value. */ 
     1356            struct { 
     1357                /* The key node type. */ 
     1358                yaml_node_type_t type; 
     1359                /* The key node tag. */ 
     1360                yaml_char_t *tag; 
     1361                /* The key node details. */ 
     1362                union { 
     1363                    /* The scalar data (for a scalar key). */ 
     1364                    struct { 
     1365                        /* The scalar value. */ 
     1366                        yaml_char_t *value; 
     1367                        /* The scalar length. */ 
     1368                        size_t length; 
     1369                    } scalar; 
     1370                } data; 
     1371            } key; 
     1372        } value; 
     1373    } data; 
    9001374} yaml_arc_t; 
    9011375 
    902 /** The node structure. */ 
     1376/* 
     1377 * The node object. 
     1378 * 
     1379 * A node object represents a node in a YAML document graph.  Node objects are 
     1380 * created using the family of functions `yaml_document_add_*()`.  Links 
     1381 * between nodes are created using the functions `yaml_document_append_*()`. A 
     1382 * node object is destroyed when the document containing it is destroyed. 
     1383 */ 
     1384 
    9031385struct yaml_node_s { 
    9041386 
    905     /** The node type. */ 
     1387    /* The node type. */ 
    9061388    yaml_node_type_t type; 
    9071389 
    908     /** The node anchor. */ 
     1390    /* The node anchor or `NULL`. */ 
    9091391    yaml_char_t *anchor; 
    910     /** The node tag. */ 
     1392    /* The node tag. */ 
    9111393    yaml_char_t *tag; 
    9121394 
    913     /** The node data. */ 
     1395    /* The node data. */ 
    9141396    union { 
    9151397         
    916         /** The scalar parameters (for @c YAML_SCALAR_NODE). */ 
     1398        /* The scalar parameters (for `YAML_SCALAR_NODE`). */ 
    9171399        struct { 
    918             /** The scalar value. */ 
     1400            /* The scalar value. */ 
    9191401            yaml_char_t *value; 
    920             /** The length of the scalar value. */ 
     1402            /* The length of the scalar value. */ 
    9211403            size_t length; 
    922             /** The scalar style. */ 
     1404            /* The scalar style. */ 
    9231405            yaml_scalar_style_t style; 
    9241406        } scalar; 
    9251407 
    926         /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */ 
     1408        /* The sequence parameters (for `YAML_SEQUENCE_NODE`). */ 
    9271409        struct { 
    928             /** The list of sequence items. */ 
     1410            /* The list of sequence items. */ 
    9291411            struct { 
    930                 /** The beginning of the list. */ 
     1412                /* The pointer to the beginning of the list. */ 
    9311413                yaml_node_item_t *list; 
    932                 /** The length of the list. */ 
     1414                /* The length of the list. */ 
    9331415                size_t length; 
    934                 /** The capacity of the list. */ 
     1416                /* The capacity of the list (used internally). */ 
    9351417                size_t capacity; 
    9361418            } items; 
    937             /** The sequence style. */ 
     1419            /* The sequence style. */ 
    9381420            yaml_sequence_style_t style; 
    9391421        } sequence; 
    9401422 
    941         /** The mapping parameters (for @c YAML_MAPPING_NODE). */ 
     1423        /* The mapping parameters (for `YAML_MAPPING_NODE`). */ 
    9421424        struct { 
    943             /** The list of mapping pairs (key, value). */ 
     1425            /* The list of mapping pairs (key, value). */ 
    9441426            struct { 
    945                 /** The beginning of the list. */ 
     1427                /** The pointer to the beginning of the list. */ 
    9461428                yaml_node_pair_t *list; 
    947                 /** The length of the list. */ 
     1429                /* The length of the list. */ 
    9481430                size_t length; 
    949                 /** The capacity of the list. */ 
     1431                /* The capacity of the list (used internally). */ 
    9501432                size_t capacity; 
    9511433            } pairs; 
    952             /** The mapping style. */ 
     1434            /* The mapping style. */ 
    9531435            yaml_mapping_style_t style; 
    9541436        } mapping; 
     
    9561438    } data; 
    9571439 
    958     /** The beginning of the node. */ 
     1440    /* The beginning of the node. */ 
    9591441    yaml_mark_t start_mark; 
    960     /** The end of the node. */ 
     1442    /* The end of the node. */ 
    9611443    yaml_mark_t end_mark; 
    9621444 
    9631445}; 
    9641446 
    965 /** The incomplete node structure. */ 
     1447/* 
     1448 * The incomplete node object. 
     1449 * 
     1450 * This structure provides the information about a node that a tag resolver 
     1451 * could use to determine the specific node tag.  This information includes 
     1452 * the path from the root node and the node content for scalar nodes. 
     1453 */ 
     1454 
    9661455typedef struct yaml_incomplete_node_s { 
    9671456 
    968     /** The node type. */ 
     1457    /* The node type. */ 
    9691458    yaml_node_type_t type; 
    9701459 
    971     /** The path to the new node. */ 
     1460    /* The path to the new node. */ 
    9721461    struct { 
    973         /** The beginning of the list. */ 
     1462        /* The pointer to the beginning of the list. */ 
    9741463        yaml_arc_t *list; 
     1464        /* The length of the list. */ 
     1465        size_t length; 
     1466        /* The capacity of the list (used internally). */ 
     1467        size_t capacity; 
     1468    } path; 
     1469 
     1470    /* The node data. */ 
     1471    union { 
     1472 
     1473        /* The scalar parameters (for `YAML_SCALAR_NODE`). */ 
     1474        struct { 
     1475            /* The scalar value. */ 
     1476            yaml_char_t *value; 
     1477            /* The length of the scalar value. */ 
     1478            size_t length; 
     1479            /* Set if the scalar is plain. */ 
     1480            int is_plain; 
     1481        } scalar; 
     1482 
     1483    } data; 
     1484 
     1485    /* The position of the node. */ 
     1486    yaml_mark_t mark; 
     1487 
     1488} yaml_incomplete_node_t; 
     1489 
     1490/* 
     1491 * The document object. 
     1492 * 
     1493 * A document object represents the main structure of the YAML object model: 
     1494 * the document graph consisting of nodes of three kinds: scalars, sequences, 
     1495 * and mappings with the selected root node. 
     1496 * 
     1497 * An empty document object is allocated using the function 
     1498 * `yaml_document_new()`.  Then the function `yaml_parser_parse_document()` 
     1499 * could be used to load a YAML document from the input stream.  Alternatively, 
     1500 * a document could be created with `yaml_document_create()` and its content 
     1501 * could be specified using the families of functions `yaml_document_add_*()` 
     1502 * and `yaml_document_append_*()`.  A document with all associated nodes could 
     1503 * be destroyed using the function `yaml_document_delete()`. 
     1504 */ 
     1505 
     1506typedef struct yaml_document_s { 
     1507 
     1508    /* The document type. */ 
     1509    yaml_document_type_t type; 
     1510 
     1511    /* The document nodes (for internal use only). */ 
     1512    struct { 
     1513        /* The pointer to the beginning of the list. */ 
     1514        yaml_node_t *list; 
     1515        /* The length of the list. */ 
     1516        size_t length; 
     1517        /* The capacity of the list. */ 
     1518        size_t capacity; 
     1519    } nodes; 
     1520 
     1521    /* The version directive or `NULL`. */ 
     1522    yaml_version_directive_t *version_directive; 
     1523 
     1524    /* The list of tag directives. */ 
     1525    struct { 
     1526        /* The pointer to the beginning of the list or `NULL`. */ 
     1527        yaml_tag_directive_t *list; 
    9751528        /** The length of the list. */ 
    9761529        size_t length; 
    977         /** The capacity of the list. */ 
    978         size_t capacity; 
    979     } path; 
    980  
    981     /** The node data. */ 
    982     union { 
    983  
    984         /** The scalar parameters (for @c YAML_SCALAR_NODE). */ 
    985         struct { 
    986             /** The scalar value. */ 
    987             yaml_char_t *value; 
    988             /** The length of the scalar value. */ 
    989             size_t length; 
    990             /** Set if the scalar is plain. */ 
    991             int is_plain; 
    992         } scalar; 
    993  
    994     } data; 
    995  
    996     /** The position of the node. */ 
    997     yaml_mark_t mark; 
    998  
    999 } yaml_incomplete_node_t; 
    1000  
    1001 /** The document structure. */ 
    1002 typedef struct yaml_document_s { 
    1003  
    1004     /** The document nodes. */ 
    1005     struct { 
    1006         /** The beginning of the list. */ 
    1007         yaml_node_t *list; 
    1008         /** The length of the list. */ 
    1009         size_t length; 
    1010         /** The capacity of the list. */ 
    1011         size_t capacity; 
    1012     } nodes; 
    1013  
    1014     /** The version directive. */ 
    1015     yaml_version_directive_t *version_directive; 
    1016  
    1017     /** The list of tag directives. */ 
    1018     struct { 
    1019         /** The beginning of the tag directive list. */ 
    1020         yaml_tag_directive_t *list; 
    1021         /** The length of the tag directive list. */ 
    1022         size_t length; 
    1023         /** The capacity of the tag directive list. */ 
     1530        /** The capacity of the list (used internally). */ 
    10241531        size_t capacity; 
    10251532    } tag_directives; 
    10261533 
    1027     /** Is the document start indicator implicit? */ 
     1534    /** Set if the document start indicator is implicit. */ 
    10281535    int is_start_implicit; 
    1029     /** Is the document end indicator implicit? */ 
     1536    /** Set if the document end indicator is implicit. */ 
    10301537    int is_end_implicit; 
    10311538 
     
    10371544} yaml_document_t; 
    10381545 
    1039 #if 0 
    1040  
    1041 /** 
     1546/* 
    10421547 * Allocate a new empty document object. 
    10431548 * 
    1044  * @returns a new document object or @c NULL on error. 
     1549 * A document object allocated using this function must be deleted with 
     1550 * `yaml_document_delete()`. 
     1551 * 
     1552 * Returns: a new empty document object or `NULL` on error.  The function may 
     1553 * fail if it cannot allocate memory for a new object. 
    10451554 */ 
    10461555 
     
    10481557yaml_document_new(void); 
    10491558 
    1050 /** 
    1051  * Delete and deallocatge a document object. 
    1052  * 
    1053  * @param[in,out]   document    A document object. 
     1559/* 
     1560 * Deallocate a document object and free the associated data. 
     1561 * 
     1562 * A document object must be previously allocated with `yaml_document_new()`. 
     1563 * 
     1564 * Arguments: 
     1565 * 
     1566 * - `document`: a document object to be deallocated. 
    10541567 */ 
    10551568 
     
    10571570yaml_document_delete(yaml_document_t *document); 
    10581571 
    1059 /** 
     1572/* 
    10601573 * Duplicate a document object. 
    10611574 * 
    1062  * @param[in,out]   document   An empty document object. 
    1063  * @param[in]       model       A document to copy. 
    1064  * 
    1065  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1575 * This function creates a complete copy of an existing document and all the 
     1576 * nodes it contains.  The function accepts two objects: an empty document and 
     1577 * a model document.  The model is supposed to be initialized either with 
     1578 * `yaml_parser_parse_document()` or constructed manually.  The functions 
     1579 * duplicate the content of the document and its nodes and assigns it to the 
     1580 * empty document. 
     1581 * 
     1582 * Arguments: 
     1583 * 
     1584 * - `document`: an empty document object. 
     1585 * 
     1586 * - `model`: a document to be copied. 
     1587 * 
     1588 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1589 * allocate memory for duplicating the state of the model.  In that case, the 
     1590 * document remains empty. 
    10661591 */ 
    10671592 
     
    10691594yaml_document_duplicate(yaml_document_t *document, yaml_document_t *model); 
    10701595 
    1071 /** 
     1596/* 
     1597 * Clear the document. 
     1598 * 
     1599 * This function clears the type of the document and destroys all the document 
     1600 * nodes.  After applying this function to a document, it becomes empty.  It is 
     1601 * supposed that the document was previously initialized using 
     1602 * `yaml_parser_parse_document()` or created manually.  Note that the function 
     1603 * `yaml_emitter_emit_document()` also clears the given document. 
     1604 * 
     1605 * Arguments: 
     1606 * 
     1607 * - `document`: a document object. 
     1608 */ 
     1609 
     1610YAML_DECLARE(void) 
     1611yaml_document_clear(yaml_document_t *document); 
     1612 
     1613/* 
    10721614 * Create a YAML document. 
    10731615 * 
    1074  * @param[out]      document                An empty document object. 
    1075  * @param[in]       version_directive       The %YAML directive value or 
    1076  *                                          @c NULL. 
    1077  * @param[in]       tag_directives          The list of the %TAG directives or 
    1078  *                                          @c NULL.  The list must end with 
    1079  *                                          the pair @c (NULL,NULL). 
    1080  * @param[in]       is_start_implicit       If the document start indicator is 
    1081  *                                          implicit. 
    1082  * @param[in]       is_end_implicit         If the document end indicator is 
    1083  *                                          implicit. 
    1084  * 
    1085  * @returns @c 1 if the function succeeded, @c 0 on error. 
     1616 * This function initializes an empty document object allocated with 
     1617 * `yaml_document_new()`.  Further, nodes could be added to the document using 
     1618 * the functions `yaml_document_add_*()` and `yaml_document_append_*()`.  The 
     1619 * initialized document could be fed to `yaml_emitter_emit_document()`. 
     1620 * 
     1621 * Arguments: 
     1622 * 
     1623 * - `document`: an empty document object. 
     1624 * 
     1625 * - `version_directive`: a structure specifying the content of the `%YAML` 
     1626 *   directive or `NULL` if the directive could be omitted.  Note that LibYAML 
     1627 *   supports YAML 1.1 only.  The constructor does not check if the supplied 
     1628 *   version equals to 1.1, but the emitter will fail to emit the document if 
     1629 *   it is not so. 
     1630 * 
     1631 * - `tag_directives_list`: a pointer to a list specifying the content of the 
     1632 *   `%TAG` directives associated with the document or `NULL` if the document 
     1633 *   does not contain `%TAG` directives.  The content of a tag directive is a 
     1634 *   pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings.  The tag 
     1635 *   handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_` 
     1636 *   and `-` surrounded by `!`.  The tag prefix is a prefix of any valid tag, 
     1637 *   that is, it is a non-empty prefix of either a global tag (a valid URI) or 
     1638 *   a local tag (an arbitrary string starting with `!`).  The constructor does 
     1639 *   not check if the given directive values satisfy these requirements, but 
     1640 *   the emitter will fail to emit the document if they are not met. 
     1641 * 
     1642 * - `tag_directives_length`: the length of `tag_directives_list`; `0` if 
     1643 *   `tag_directives_list` is `NULL`. 
     1644 * 
     1645 * - `is_start_implicit`: `1` if the document start indicator `---` is omitted; 
     1646 *   `0` otherwise.  Note that this attribute is only a stylistic hint and 
     1647 *   could be ignored by the emitter. 
     1648 * 
     1649 * - `is_end_implicit`: `1` if the document end indicator `...` is omitted; `0` 
     1650 *   otherwise.  Note that this attribute is only a stylistic hint and could be 
     1651 *   ignored by the emitter. 
     1652 * 
     1653 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1654 * allocate memory for duplicating the document parameters.  In this case, the 
     1655 * document remains empty. 
    10861656 */ 
    10871657 
    10881658YAML_DECLARE(int) 
    10891659yaml_document_create(yaml_document_t *document, 
    1090         yaml_version_directive_t *version_directive, 
    1091         yaml_tag_directive_t *tag_directives, 
     1660        const yaml_version_directive_t *version_directive, 
     1661        const yaml_tag_directive_t *tag_directives_list, 
     1662        size_t tag_directives_length, 
    10921663        int is_start_implicit, int is_end_implicit); 
    1093  
    1094 /** 
    1095  * Delete a YAML document and all its nodes. 
    1096  * 
    1097  * @param[in,out]   document        A document object. 
    1098  */ 
    1099  
    1100 YAML_DECLARE(void) 
    1101 yaml_document_destroy(yaml_document_t *document); 
    11021664 
    11031665/** 
    11041666 * Get a node of a YAML document. 
    11051667 * 
     1668 * The root node of the document has the id `0`. 
     1669 * 
    11061670 * The pointer returned by this function is valid until any of the functions 
    1107  * modifying the documents is called. 
    1108  * 
    1109  * @param[in]       document        A document object. 
    1110  * @param[in]       index           The node id. 
    1111  * 
    1112  * @returns the node objct or @c NULL if @c node_id is out of range. 
     1671 * modifying the document is called. 
     1672 * 
     1673 * Arguments: 
     1674 * 
     1675 * - `document`: a document object. 
     1676 * 
     1677 * - `node_id`: the node id.  The node id starts from `0` and increases by `1` 
     1678 *   for each newly added node.  Specifying a negative `node_id` is possible, 
     1679 *   which is interpeted as the number (<total number of nodes> - `node_id`). 
     1680 * 
     1681 * Returns: a pointer to the node object or `NULL` if `node_id` is out of 
     1682 * range. 
    11131683 */ 
    11141684 
    11151685YAML_DECLARE(yaml_node_t *) 
    1116 yaml_document_get_node(yaml_document_t *document, int index); 
    1117  
    1118 /** 
    1119  * Get the root of a YAML document node. 
    1120  * 
    1121  * The root object is the first object added to the document. 
    1122  * 
    1123  * The pointer returned by this function is valid until any of the functions 
    1124  * modifying the documents is called. 
    1125  * 
    1126  * An empty document produced by the parser signifies the end of a YAML 
    1127  * stream. 
    1128  * 
    1129  * @param[in]       document        A document object. 
    1130  * 
    1131  * @returns the node object or @c NULL if the document is empty. 
    1132  */ 
    1133  
    1134 YAML_DECLARE(yaml_node_t *) 
    1135 yaml_document_get_root_node(yaml_document_t *document); 
    1136  
    1137 /** 
     1686yaml_document_get_node(yaml_document_t *document, int node_id); 
     1687 
     1688/* 
    11381689 * Create a SCALAR node and attach it to the document. 
    11391690 * 
    1140  * The @a style argument may be ignored by the emitter. 
    1141  * 
    1142  * @param[in,out]   document        A document object. 
    1143  * @param[in]       anchor          A preferred anchor for the node or @c NULL. 
    1144  * @param[in]       tag             The scalar tag. 
    1145  * @param[in]       value           The scalar value. 
    1146  * @param[in]       length          The length of the scalar value. 
    1147  * @param[in]       style           The scalar style. 
    1148  * 
    1149  * @returns the node id or @c 0 on error. 
    1150  */ 
    1151  
    1152 YAML_DECLARE(int) 
    1153 yaml_document_add_scalar(yaml_document_t *document, 
    1154         yaml_char_t *anchor, yaml_char_t *tag, yaml_char_t *value, 
    1155         size_t length, yaml_scalar_style_t style); 
    1156  
    1157 /** 
     1691 * Note that the first node attached to a document becomes the root node. 
     1692 * There must exist a path from the root node to any node added to the 
     1693 * document, otherwise the function `yaml_emitter_emit_document()` will fail. 
     1694 * 
     1695 * Arguments: 
     1696 * 
     1697 * - `document`: a document object. 
     1698 * 
     1699 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     1700 * 
     1701 * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty 
     1702 *   NUL-terminated string containing only alphanumerical characters, `_`, and 
     1703 *   `-`.  The function does not check whether this requirement is satisfied, 
     1704 *   but the emitter may fail to emit the node if it is not so.  This parameter 
     1705 *   is considered as a stylistic hint and could be ignored by the emitter. 
     1706 *   The emitter may automatically generate an anchor for a node that does not 
     1707 *   specify it or specifies a duplicate anchor. 
     1708 * 
     1709 * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated 
     1710 *   string.  The tag could be global (a valid URI) or local (an arbitrary 
     1711 *   string starting with `!`).  The function does not check whether these 
     1712 *   requirements are satisfied, but the emitter will fail to emit the node if 
     1713 *   it is not so. 
     1714 * 
     1715 * - `value`: the scalar value.  The value should be a string containing any 
     1716 *   valid UTF-8 character including NUL.  The function does not check if 
     1717 *   `value` is a valid UTF-8 string, but the emitter will fail to emit the 
     1718 *   node if it is not so. 
     1719 * 
     1720 * - `length`: the length of the scalar value (in bytes) or `-1`.  If `length` 
     1721 *   is set to `-1`, the `value` is assumed to be NUL-terminated. 
     1722 * 
     1723 * - `style`: the node style.  Note that this attribute only serves as a hint 
     1724 *   and may be ignored by the emitter. 
     1725 * 
     1726 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1727 * allocate memory for duplicating the given string buffers.  If the function 
     1728 * succeeds, the id of the added node is returned via the pointer `node_id` 
     1729 * if it is not set to `NULL`. 
     1730 */ 
     1731 
     1732YAML_DECLARE(int) 
     1733yaml_document_add_scalar(yaml_document_t *document, int *node_id, 
     1734        const yaml_char_t *anchor, const yaml_char_t *tag, 
     1735        const yaml_char_t *value, int length, 
     1736        yaml_scalar_style_t style); 
     1737 
     1738/* 
    11581739 * Create a SEQUENCE node and attach it to the document. 
    11591740 * 
    1160  * The @a style argument may be ignored by the emitter. 
    1161  * 
    1162  * @param[in,out]   document    A document object. 
    1163  * @param[in]       anchor      A preferred anchor for the node or @c NULL. 
    1164  * @param[in]       tag         The sequence tag. 
    1165  * @param[in]       style       The sequence style. 
    1166  * 
    1167  * @returns the node id or @c 0 on error. 
    1168  */ 
    1169  
    1170 YAML_DECLARE(int) 
    1171 yaml_document_add_sequence(yaml_document_t *document, 
    1172         yaml_char_t *anchor, yaml_char_t *tag, yaml_sequence_style_t style); 
    1173  
    1174 /** 
     1741 * Note that the first node attached to a document becomes the root node. 
     1742 * There must exist a path from the root node to any node added to the 
     1743 * document, otherwise the function `yaml_emitter_emit_document()` will fail. 
     1744 * 
     1745 * Arguments: 
     1746 * 
     1747 * - `document`: a document object. 
     1748 * 
     1749 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     1750 * 
     1751 * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty 
     1752 *   NUL-terminated string containing only alphanumerical characters, `_`, and 
     1753 *   `-`.  The function does not check whether this requirement is satisfied, 
     1754 *   but the emitter may fail to emit the node if it is not so.  This parameter 
     1755 *   is considered as a stylistic hint and could be ignored by the emitter. 
     1756 *   The emitter may automatically generate an anchor for a node that does not 
     1757 *   specify it or specifies a duplicate anchor. 
     1758 * 
     1759 * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated 
     1760 *   string.  The tag could be global (a valid URI) or local (an arbitrary 
     1761 *   string starting with `!`).  The function does not check whether these 
     1762 *   requirements are satisfied, but the emitter will fail to emit the node if 
     1763 *   it is not so. 
     1764 * 
     1765 * - `style`: the node style.  Note that this attribute only serves as a hint 
     1766 *   and may be ignored by the emitter. 
     1767 * 
     1768 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1769 * allocate memory for duplicating the given string buffers.  If the function 
     1770 * succeeds, the id of the added node is returned via the pointer `node_id` 
     1771 * if it is not set to `NULL`. 
     1772 */ 
     1773 
     1774YAML_DECLARE(int) 
     1775yaml_document_add_sequence(yaml_document_t *document, int *node_id, 
     1776        const yaml_char_t *anchor, const yaml_char_t *tag, 
     1777        yaml_sequence_style_t style); 
     1778 
     1779/* 
    11751780 * Create a MAPPING node and attach it to the document. 
    11761781 * 
    1177  * The @a style argument may be ignored by the emitter. 
    1178  * 
    1179  * @param[in,out]   document    A document object. 
    1180  * @param[in]       anchor      A preferred anchor for the node or @c NULL. 
    1181  * @param[in]       tag         The sequence tag. 
    1182  * @param[in]       style       The sequence style. 
    1183  * 
    1184  * @returns the node id or @c 0 on error. 
    1185  */ 
    1186  
    1187 YAML_DECLARE(int) 
    1188 yaml_document_add_mapping(yaml_document_t *document, 
    1189         yaml_char_t *anchor, yaml_char_t *tag, yaml_mapping_style_t style); 
    1190  
    1191 /** 
     1782 * Note that the first node attached to a document becomes the root node. 
     1783 * There must exist a path from the root node to any node added to the 
     1784 * document, otherwise the function `yaml_emitter_emit_document()` will fail. 
     1785 * 
     1786 * Arguments: 
     1787 * 
     1788 * - `document`: a document object. 
     1789 * 
     1790 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     1791 * 
     1792 * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty 
     1793 *   NUL-terminated string containing only alphanumerical characters, `_`, and 
     1794 *   `-`.  The function does not check whether this requirement is satisfied, 
     1795 *   but the emitter may fail to emit the node if it is not so.  This parameter 
     1796 *   is considered as a stylistic hint and could be ignored by the emitter. 
     1797 *   The emitter may automatically generate an anchor for a node that does not 
     1798 *   specify it or specifies a duplicate anchor. 
     1799 * 
     1800 * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated 
     1801 *   string.  The tag could be global (a valid URI) or local (an arbitrary 
     1802 *   string starting with `!`).  The function does not check whether these 
     1803 *   requirements are satisfied, but the emitter will fail to emit the node if 
     1804 *   it is not so. 
     1805 * 
     1806 * - `style`: the node style.  Note that this attribute only serves as a hint 
     1807 *   and may be ignored by the emitter. 
     1808 * 
     1809 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     1810 * allocate memory for duplicating the given string buffers.  If the function 
     1811 * succeeds, the id of the added node is returned via the pointer `node_id` 
     1812 * if it is not set to `NULL`. 
     1813 */ 
     1814 
     1815YAML_DECLARE(int) 
     1816yaml_document_add_mapping(yaml_document_t *document, int *node_id, 
     1817        const yaml_char_t *anchor, const yaml_char_t *tag, 
     1818        yaml_mapping_style_t style); 
     1819 
     1820/* 
     1821 * Get the value of a `!!null` SCALAR node. 
     1822 * 
     1823 * Use this function to ensure that the given node is a scalar, the node tag is 
     1824 * equal to `tag:yaml.org,2002:null` and the node value is a valid null value. 
     1825 * Given that the `!!null` tag admits only one valid value, the value is not 
     1826 * returned. 
     1827 * 
     1828 * Arguments: 
     1829 * 
     1830 * - `document`: a document object. 
     1831 * 
     1832 * - `node_id`: the node id; could be negative. 
     1833 * 
     1834 * Returns: `1` if the node is a valid `!!null` scalar, `0` otherwise. 
     1835 */ 
     1836 
     1837YAML_DECLARE(int) 
     1838yaml_document_get_null_node(yaml_document_t *document, int node_id); 
     1839 
     1840/* 
     1841 * Get the value of a `!!bool` SCALAR node. 
     1842 * 
     1843 * Use this function to ensure that the given node is a scalar, the node tag is 
     1844 * `tag:yaml.org,2002:bool` and the node value is a valid boolean value.  The 
     1845 * function returns the true value as `1` and the false value as `0`. 
     1846 * 
     1847 * Arguments: 
     1848 * 
     1849 * - `document`: a document object. 
     1850 * 
     1851 * - `node_id`: the node id; could be negative. 
     1852 * 
     1853 * - `value`: a pointer to save the node value or `NULL`. 
     1854 * 
     1855 * Returns: `1` if the node is a valid `!!bool` scalar, `0` otherwise.  If the 
     1856 * function succeeds and `value` is not `NULL`, the node value is saved to 
     1857 * `value`. 
     1858 */ 
     1859 
     1860YAML_DECLARE(int) 
     1861yaml_document_get_bool_node(yaml_document_t *document, int node_id, 
     1862        int *value); 
     1863 
     1864/* 
     1865 * Get the value of a `!!str` SCALAR node. 
     1866 * 
     1867 * Use this function to ensure that the given node is a scalar, the node tag is 
     1868 * `tag:yaml.org,2002:str` and the node value is a string that does not contain 
     1869 * the NUL character.  In this case, the function returns the node value.  The 
     1870 * produced value is valid until the document object is cleared or deleted. 
     1871 * 
     1872 * Arguments: 
     1873 * 
     1874 * - `document`: a document object. 
     1875 * 
     1876 * - `node_id`: the node id; could be negative. 
     1877 * 
     1878 * - `value`: a pointer to save the node value or `NULL`. 
     1879 * 
     1880 * Returns: `1` if the node is a valid `!!str` scalar, `0` otherwise.  If the 
     1881 * function succeeds and `value` is not `NULL`, the node value is saved to 
     1882 * `value`. 
     1883 */ 
     1884 
     1885YAML_DECLARE(int) 
     1886yaml_document_get_str_node(yaml_document_t *document, int node_id, 
     1887        char **value); 
     1888 
     1889/* 
     1890 * Get the value of an `!!int` SCALAR node. 
     1891 * 
     1892 * Use this function to ensure that the given node is a scalar, the node tag is 
     1893 * `tag:yaml.org,2002:int` and the node value is a valid integer.  In this 
     1894 * case, the function parses the node value and returns an integer number.  The 
     1895 * function recognizes decimal, hexdecimal and octal numbers including negative 
     1896 * numbers. 
     1897 * 
     1898 * Arguments: 
     1899 * 
     1900 * - `document`: a document object. 
     1901 * 
     1902 * - `node_id`: the node id; could be negative. 
     1903 * 
     1904 * - `value`: a pointer to save the node value or `NULL`. 
     1905 * 
     1906 * Returns: `1` if the node is a valid `!!int` scalar, `0` otherwise.  If the 
     1907 * function succeeds and `value` is not `NULL`, the node value is saved to 
     1908 * `value`. 
     1909 */ 
     1910 
     1911YAML_DECLARE(int) 
     1912yaml_document_get_int_node(yaml_document_t *document, int node_id, 
     1913        int *value); 
     1914 
     1915/* 
     1916 * Get the value of a `!!float` SCALAR node. 
     1917 * 
     1918 * Use this function to ensure that the given node is a scalar, the node tag is 
     1919 * `tag:yaml.org,2002:float` and the node value is a valid float value.  In 
     1920 * this case, the function parses the node value and returns a float number. 
     1921 * The function recognizes float values in exponential and fixed notation as 
     1922 * well as special values `.nan`, `.inf` and `-.inf`. 
     1923 * 
     1924 * Arguments: 
     1925 * 
     1926 * - `document`: a document object. 
     1927 * 
     1928 * - `node_id`: the node id; could be negative. 
     1929 * 
     1930 * - `value`: a pointer to save the node value or `NULL`. 
     1931 * 
     1932 * Returns: `1` if the node is a valid `!!float` scalar, `0` otherwise.  If the 
     1933 * function succeeds and `value` is not `NULL`, the node value is saved to 
     1934 * `value`. 
     1935 */ 
     1936 
     1937YAML_DECLARE(int) 
     1938yaml_document_get_float_node(yaml_document_t *document, int node_id, 
     1939        double *value); 
     1940 
     1941/* 
     1942 * Get the value of a `!!seq` SEQUENCE node. 
     1943 * 
     1944 * Use this function to ensure that the given node is a sequence and the node 
     1945 * tag is `tag:yaml.org,2002:seq`.  In this case, the function returns the list 
     1946 * of nodes that belong to the sequence.  The produced list is valid until the 
     1947 * document object is modified. 
     1948 * 
     1949 * Arguments: 
     1950 * 
     1951 * - `document`: a document object. 
     1952 * 
     1953 * - `node_id`: the node id; could be negative. 
     1954 * 
     1955 * - `items`: a pointer to save the list of sequence items or `NULL`. 
     1956 * 
     1957 * - `length`: a pointer to save the length of the sequence or `NULL`. 
     1958 *   `length` must be equal to `NULL` if and only if `items` is also `NULL`. 
     1959 * 
     1960 * Returns: `1` if the node is a valid `!!seq` sequence, `0` otherwise.  If the 
     1961 * function succeeds and `items` is not `NULL`, the list of sequence items is 
     1962 * saved to `items` and the sequence length is saved to `length`. 
     1963 */ 
     1964 
     1965YAML_DECLARE(int) 
     1966yaml_document_get_seq_node(yaml_document_t *document, int node_id, 
     1967        yaml_node_item_t **items, size_t *length); 
     1968 
     1969/* 
     1970 * Get the value of a `!!map` MAPPING node. 
     1971 * 
     1972 * Use this function to ensure that the given node is a mapping and the node 
     1973 * tag is `tag:yaml.org,2002:map`.  In this case, the function returns the list 
     1974 * of node pairs (key, value) that belong to the sequence.  The produced list 
     1975 * is valid until the document is modified. 
     1976 * 
     1977 * Arguments: 
     1978 * 
     1979 * - `document`: a document object. 
     1980 * 
     1981 * - `node_id`: the node id; could be negative. 
     1982 * 
     1983 * - `pairs`: a pointer to save the list of mapping pairs or `NULL`. 
     1984 * 
     1985 * - `length`: a pointer to save the length of the mapping or `NULL`. 
     1986 *   `length` must be equal to `NULL` if and only if `pairs` is also `NULL`. 
     1987 * 
     1988 * Returns: `1` if the node is a valid `!!map` mapping, `0` otherwise.  If the 
     1989 * function succeeds and `pairs` is not `NULL`, the list of mapping pairs is 
     1990 * saved to `pairs` and the mapping length is saved to `length`. 
     1991 */ 
     1992 
     1993YAML_DECLARE(int) 
     1994yaml_document_get_map_node(yaml_document_t *document, int node_id, 
     1995        yaml_node_pair_t **pairs, size_t *length); 
     1996 
     1997/* 
     1998 * Add a `!!null` SCALAR node to the document. 
     1999 * 
     2000 * This function is a shorthand for the call: 
     2001 * 
     2002 *      yaml_document_add_scalar(document, node_id, NULL, 
     2003 *              YAML_NULL_TAG, "null", -1, YAML_ANY_SCALAR_STYLE) 
     2004 * 
     2005 * Arguments: 
     2006 * 
     2007 * - `document`: a document object. 
     2008 * 
     2009 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2010 * 
     2011 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2012 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2013 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2014 */ 
     2015 
     2016YAML_DECLARE(int) 
     2017yaml_document_add_null_node(yaml_document_t *document, int *node_id); 
     2018 
     2019/* 
     2020 * Add a `!!bool` SCALAR node to the document. 
     2021 * 
     2022 * This function is a shorthand for the call: 
     2023 * 
     2024 *      yaml_document_add_scalar(document, node_id, NULL, 
     2025 *              YAML_BOOL_TAG, (value ? "true" : "false"), -1, 
     2026 *              YAML_ANY_SCALAR_STYLE) 
     2027 * 
     2028 * Arguments: 
     2029 * 
     2030 * - `document`: a document object. 
     2031 * 
     2032 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2033 * 
     2034 * - `value`: a boolean value; any non-zero value is true, `0` is false. 
     2035 * 
     2036 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2037 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2038 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2039 */ 
     2040 
     2041YAML_DECLARE(int) 
     2042yaml_document_add_bool_node(yaml_document_t *document, int *node_id, 
     2043        int value); 
     2044 
     2045/* 
     2046 * Add a `!!str` SCALAR node to the document. 
     2047 * 
     2048 * This function is a shorthand for the call: 
     2049 * 
     2050 *      yaml_document_add_scalar(document, node_id, NULL, 
     2051 *              YAML_STR_TAG, (const yaml_char_t *) value, -1, 
     2052 *              YAML_ANY_SCALAR_STYLE) 
     2053 * 
     2054 * Arguments: 
     2055 * 
     2056 * - `document`: a document object. 
     2057 * 
     2058 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2059 * 
     2060 * - `value`: a NUL-terminated UTF-8 string.  The function does not check if 
     2061 *   `value` is a valid UTF-8 string, but if it is not so, the emitter will 
     2062 *   fail to emit the node. 
     2063 * 
     2064 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2065 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2066 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2067 */ 
     2068 
     2069YAML_DECLARE(int) 
     2070yaml_document_add_str_node(yaml_document_t *document, int *node_id, 
     2071        const char *value); 
     2072 
     2073/* 
     2074 * Add an `!!int` SCALAR node to the document. 
     2075 * 
     2076 * This function is a shorthand for the call: 
     2077 * 
     2078 *      yaml_document_add_scalar(document, node_id, NULL, 
     2079 *              YAML_INT_TAG, <string representation of the value>, -1, 
     2080 *              YAML_ANY_SCALAR_STYLE) 
     2081 * 
     2082 * Arguments: 
     2083 * 
     2084 * - `document`: a document object. 
     2085 * 
     2086 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2087 * 
     2088 * - `value`: an integer value. 
     2089 * 
     2090 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2091 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2092 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2093 */ 
     2094 
     2095YAML_DECLARE(int) 
     2096yaml_document_add_int_node(yaml_document_t *document, int *node_id, 
     2097        int value); 
     2098 
     2099/* 
     2100 * Add a `!!float` SCALAR node to the document. 
     2101 * 
     2102 * This function is a shorthand for the call: 
     2103 * 
     2104 *      yaml_document_add_scalar(document, node_id, NULL, 
     2105 *              YAML_FLOAT_TAG, <string representation of the value>, -1, 
     2106 *              YAML_ANY_SCALAR_STYLE) 
     2107 * 
     2108 * Arguments: 
     2109 * 
     2110 * - `document`: a document object. 
     2111 * 
     2112 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2113 * 
     2114 * - `value`: a float value. 
     2115 * 
     2116 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2117 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2118 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2119 */ 
     2120 
     2121YAML_DECLARE(int) 
     2122yaml_document_add_float_node(yaml_document_t *document, int *node_id, 
     2123        double value); 
     2124 
     2125/* 
     2126 * Add a `!!seq` SEQUENCE node to the document. 
     2127 * 
     2128 * This function is a shorthand for the call: 
     2129 * 
     2130 *      yaml_document_add_sequence(document, node_id, NULL, 
     2131 *              YAML_SEQ_TAG, YAML_ANY_SEQUENCE_STYLE) 
     2132 * 
     2133 * Arguments: 
     2134 * 
     2135 * - `document`: a document object. 
     2136 * 
     2137 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2138 * 
     2139 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2140 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2141 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2142 */ 
     2143 
     2144YAML_DECLARE(int) 
     2145yaml_document_add_seq_node(yaml_document_t *document, int *node_id); 
     2146 
     2147/* 
     2148 * Add a `!!map` MAPPING node to the document. 
     2149 * 
     2150 * This function is a shorthand for the call: 
     2151 * 
     2152 *      yaml_document_add_mapping(document, node_id, NULL, 
     2153 *              YAML_MAP_TAG, YAML_ANY_MAPPING_STYLE) 
     2154 * 
     2155 * Arguments: 
     2156 * 
     2157 * - `document`: a document object. 
     2158 * 
     2159 * - `node_id`: a pointer to save the id of the generated node or `NULL`. 
     2160 * 
     2161 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2162 * allocate memory for new buffers.  If the function succeeds, the id of the 
     2163 * added node is returned via the pointer `node_id` if it is not set to `NULL`. 
     2164 */ 
     2165 
     2166YAML_DECLARE(int) 
     2167yaml_document_add_map_node(yaml_document_t *document, int *node_id); 
     2168 
     2169/* 
    11922170 * Add an item to a SEQUENCE node. 
    11932171 * 
    1194  * @param[in,out]   document    A document object. 
    1195  * @param[in]       sequence    The sequence node id. 
    1196  * @param[in]       item        The item node id. 
    1197 * 
    1198  * @returns @c 1 if the function succeeded, @c 0 on error. 
     2172 * The order in which items are added to a sequence coincides with the order 
     2173 * they are emitted into the output stream. 
     2174 * 
     2175 * Arguments: 
     2176 * 
     2177 * - `document`: a document object. 
     2178 * 
     2179 * - `sequence_id`: the id of a sequence node; could be negative.  It is a 
     2180 *   fatal error if `sequence_id` does not refer to an existing sequence node. 
     2181 * 
     2182 * - `item_id`: the id of an item node; could be negative.  It is a fatal error 
     2183 *   if `item_id` does not refer to an existing node.  Note that it is possible 
     2184 *   for `item_id` to coincide with `sequence_id`, which means that the 
     2185 *   sequence recursively contains itself. 
     2186 * 
     2187 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2188 * allocate memory for internal buffers. 
    11992189 */ 
    12002190 
    12012191YAML_DECLARE(int) 
    12022192yaml_document_append_sequence_item(yaml_document_t *document, 
    1203         int sequence, int item); 
    1204  
    1205 /** 
     2193        int sequence_id, int item_id); 
     2194 
     2195/* 
    12062196 * Add a pair of a key and a value to a MAPPING node. 
    12072197 * 
    1208  * @param[in,out]   document    A document object. 
    1209  * @param[in]       mapping     The mapping node id. 
    1210  * @param[in]       key         The key node id. 
    1211  * @param[in]       value       The value node id. 
    1212 * 
    1213  * @returns @c 1 if the function succeeded, @c 0 on error. 
     2198 * The order in which (key, value) pairs are added to a mapping coincides with 
     2199 * the order in which they are presented in the output stream.  Note that the 
     2200 * mapping key order is a presentation detail and should not used to convey any 
     2201 * information.  An ordered mapping could be represented as a sequence of 
     2202 * single-paired mappings. 
     2203 * 
     2204 * Arguments: 
     2205 * 
     2206 * - `document`: a document object. 
     2207 * 
     2208 * - `mapping_id`: the id of a mapping node; could be negative.  It is a 
     2209 *   fatal error if `mapping_id` does not refer to an existing mapping node. 
     2210 * 
     2211 * - `key_id`: the id of a key node; could be negative.  It is a fatal error 
     2212 *   if `key_id` does not refer to an existing node. 
     2213 * 
     2214 * - `value_id`: the id of a value node; could be negative.  It is a fatal 
     2215 *   error if `value_id` does not refer to an existing node. 
     2216 * 
     2217 * Returns: `1` on success, `0` on error.  The function may fail if it cannot 
     2218 * allocate memory for internal buffers. 
    12142219 */ 
    12152220 
    12162221YAML_DECLARE(int) 
    12172222yaml_document_append_mapping_pair(yaml_document_t *document, 
    1218         int mapping, int key, int value); 
    1219  
    1220 #endif 
    1221  
    1222 /** 
    1223  * @defgroup callbacks Callback Definitions 
    1224  * @{ 
    1225  */ 
    1226  
    1227 /** 
     2223        int mapping_id, int key_id, int value_id); 
     2224 
     2225/****************************************************************************** 
     2226 * Callback Definitions 
     2227 ******************************************************************************/ 
     2228 
     2229/* 
    12282230 * The prototype of a read handler. 
    12292231 * 
    1230  * The read handler is called when the parser needs to read more bytes from the 
    1231  * source.  The handler should read no more than @a size bytes and write them 
    1232  * to the @a buffer.  The number of the read bytes should be returned using the 
    1233  * @a size_read variable.  If the handler reaches the stream end, @a size_read 
    1234  * must be set to @c 0. 
    1235  * 
    1236  * @param[in,out]   data        A pointer to an application data specified by 
    1237  *                              @c yaml_parser_set_reader(). 
    1238  * @param[out]      buffer      The buffer to write the data from the source. 
    1239  * @param[in]       capacity    The maximum number of bytes the buffer can hold. 
    1240  * @param[out]      length      The actual number of bytes read from the source. 
    1241  * 
    1242  * @returns On success, the handler should return @c 1.  If the handler failed, 
    1243  * the returned value should be @c 0.  On EOF, the handler should set the 
    1244  * @a size_read to @c 0 and return @c 1. 
     2232 * The reader is called when the parser needs to read more bytes from the input 
     2233 * stream.  The reader is given a buffer to fill and should returns the number 
     2234 * of bytes read.  The reader should block if no data from the input stream is 
     2235 * available, but it should return immediately if it could produce least one 
     2236 * byte of the input stream.  If the reader reaches the stream end, it should 
     2237 * return immediately setting the number of bytes read to `0`. 
     2238 * 
     2239 * Arguments: 
     2240 * 
     2241 * - `data`: a pointer to an application data specified with 
     2242 *   `yaml_parser_set_reader()`. 
     2243 * 
     2244 * - `buffer`: a pointer to a buffer which should be filled with the bytes 
     2245 *   from the input stream. 
     2246 * 
     2247 * - `capacity`: the maximum capacity of the buffer. 
     2248 * 
     2249 * - `length`: a pointer to save the actual number of bytes read from the input 
     2250 *   stream; `length` equals `0` signifies that the reader reached the end of 
     2251 *   the stream. 
     2252 * 
     2253 * Return: on success, the reader should return `1`.  If the reader fails for 
     2254 * any reason, it should return `0`.  On the end of the input stream, the 
     2255 * reader should set `length` to `0` and return `1`. 
    12452256 */ 
    12462257 
     
    12482259        size_t *length); 
    12492260 
    1250 /** 
     2261/* 
    12512262 * The prototype of a write handler. 
    12522263 * 
    1253  * The write handler is called when the emitter needs to flush the accumulated 
    1254  * characters to the output.  The handler should write @a size bytes of the 
    1255  * @a buffer to the output. 
    1256  * 
    1257  * @param[in,out]   data        A pointer to an application data specified by 
    1258  *                              @c yaml_emitter_set_writer(). 
    1259  * @param[in]       buffer      The buffer with bytes to be written. 
    1260  * @param[in]       length      The number of bytes to be written. 
    1261  * 
    1262  * @returns On success, the handler should return @c 1.  If the handler failed, 
    1263  * it should return @c 0. 
     2264 * The writer is called when the emitter needs to flush the accumulated bytes 
     2265 * into the output stream. 
     2266 * 
     2267 * Arguments: 
     2268 * 
     2269 * - `data`: a pointer to an application data specified with 
     2270 *   `yaml_emitter_set_writer()`. 
     2271 * 
     2272 * - `buffer`: a pointer to a buffer with bytes to be written to the output 
     2273 *   stream. 
     2274 * 
     2275 * - `length`: the number of bytes to be written. 
     2276 * 
     2277 * Returns: on success, the writer should return `1`.  If the writer fails for 
     2278 * any reason, it should return `0`. 
    12642279 */ 
    12652280 
     
    12682283 
    12692284/** 
    1270  * The prototype of a tag resolver. 
    1271  * 
    1272  * The resolve handler is called when the parser encounters a new node without 
    1273  * an explicit tag.  The handler should determine the correct tag of the node 
    1274  * basing on the node kind, the path to the node from the document root and, 
    1275  * in the case of the scalar node, the node value.  The handler is also called 
    1276  * by the emitter to determine whether the node tag could be omitted. 
    1277  * 
    1278  * @param[in,out]   data        A pointer to an application data specified by 
    1279  *                              @c yaml_parser_set_writter() or 
    1280  *                              @c yaml_emitter_set_writer(). 
    1281  * @param[in]       node        Information about the new node. 
    1282  * @param[out]      tag         The guessed node tag. 
    1283  * 
    1284  * @returns On success, the handler should return @c 1.  If the handler failed, 
    1285  * it should return @c 0. 
     2285 * The prototype of a nonspecific tag resolver. 
     2286 * 
     2287 * The resolver is called when the parser encounters a node without an explicit 
     2288 * tag.  The resolver should determine the correct tag of the node from the 
     2289 * path to the node from the root node and, in case of the scalar node, the 
     2290 * node value.  The resolver is also called by the emitter to determine whether 
     2291 * the node tag could be omitted. 
     2292 * 
     2293 * Arguments: 
     2294 * 
     2295 * - `data`: a pointer to an application data specified with 
     2296 *   `yaml_parser_set_resolver()` or `yaml_emitter_set_resolver()`. 
     2297 * 
     2298 * - `node`: information about the new node. 
     2299 * 
     2300 * - `tag`: A pointer to save the guessed node tag.  The value returned by the 
     2301 *   resolved is immediately copied. 
     2302 * 
     2303 * Returns: on success, the resolver should return `1`.  If the resolver fails 
     2304 * for any reason, it should return `0`. 
    12862305 */ 
    12872306 
     
    12892308        yaml_char_t **tag); 
    12902309 
    1291 /** @} */ 
    1292  
    1293 /** 
    1294  * @defgroup parser Parser Definitions 
    1295  * @{ 
    1296  */ 
    1297  
    1298 /** The parser object. */ 
     2310/****************************************************************************** 
     2311 * Parser Definitions 
     2312 ******************************************************************************/ 
     2313 
     2314/* 
     2315 * An opaque definition of the parser object. 
     2316 * 
     2317 * A parser object is used to parse an input YAML stream producing a sequence 
     2318 * of YAML tokens, events or documents. 
     2319 */ 
     2320 
    12992321typedef struct yaml_parser_s yaml_parser_t; 
    13002322 
    1301 /** 
    1302  * Create a new parser object. 
    1303  * 
    1304  * This function creates a new parser object.  An application is responsible 
    1305  * for destroying the object using the @c yaml_parser_delete() function. 
    1306  * 
    1307  * @returns a new parser object or @c NULL on error. 
     2323/* 
     2324 * Allocate a new parser object. 
     2325 * 
     2326 * An allocated parser object should be deleted with `yaml_parser_delete()` 
     2327 * 
     2328 * Returns: a new parser object or `NULL` on error.  The function may fail if 
     2329 * it cannot allocate memory for internal buffers. 
    13082330 */ 
    13092331 
     
    13112333yaml_parser_new(void); 
    13122334 
    1313 /** 
    1314  * Destroy a parser. 
    1315  * 
    1316  * @param[in,out]   parser  A parser object. 
     2335/* 
     2336 * Deallocate a parser and free the internal parser data. 
     2337 *  
     2338 * A parser object must be previously allocated with `yaml_parser_new()`. 
     2339 * 
     2340 * Arguments: 
     2341 * 
     2342 * - `parser`: a parser object. 
    13172343 */ 
    13182344 
     
    13202346yaml_parser_delete(yaml_parser_t *parser); 
    13212347 
    1322 /** 
    1323  * Get a parser error. 
    1324  * 
    1325  * @param[in]   parser  A parser object. 
    1326  * @param[out]  error   An error object. 
     2348/* 
     2349 * Clear and reinitialize the internal state of the parser. 
     2350 * 
     2351 * This function could be used for cleaning up a parser object after an error 
     2352 * condition or after the end of the input stream is reached.  A cleaned parser 
     2353 * object may be reused to parse another YAML stream.  Note that all the parser 
     2354 * parameters including the read handler must be reset. 
     2355 * 
     2356 * Arguments: 
     2357 * 
     2358 * - `parser`: a parser object. 
    13272359 */ 
    13282360 
    13292361YAML_DECLARE(void) 
    1330 yaml_parser_get_error(yaml_parser_t *parser, yaml_error_t *error); 
    1331  
    1332 /** 
    1333  * Set a string input. 
    1334  * 
    1335  * Note that the @a input pointer must be valid while the @a parser object 
    1336  * exists.  The application is responsible for destroing @a input after 
    1337  * destroying the @a parser. 
    1338  * 
    1339  * @param[in,out]   parser  A parser object. 
    1340  * @param[in]       buffer  A source data. 
    1341  * @param[in]       length  The length of the source data in bytes. 
     2362yaml_parser_clear(yaml_parser_t *parser); 
     2363 
     2364/* 
     2365 * Get the parser error. 
     2366 * 
     2367 * Use this function to get a detailed error information after failure of one 
     2368 * of the following functions: `yaml_parser_parse_token()`, 
     2369 * `yaml_parser_parse_event()`, `yaml_parser_parse_document()`, 
     2370 * `yaml_parser_parse_single_document()`. 
     2371 * 
     2372 * The pointer returned by the function is only valid until the parser object 
     2373 * is not modified.  However the error object could be safely copied. 
     2374 * 
     2375 * Arguments: 
     2376 * 
     2377 * - `parser`: a parser object. 
     2378 * 
     2379 * Returns: a pointer to an error object.  The returned pointer is only valid 
     2380 * until the parser object is not modified or deleted.  However the error 
     2381 * object could be safely copied. 
     2382 */ 
     2383 
     2384YAML_DECLARE(yaml_error_t *) 
     2385yaml_parser_get_error(yaml_parser_t *parser); 
     2386 
     2387/* 
     2388 * Set the parser to read the input stream from a character buffer. 
     2389 * 
     2390 * Arguments: 
     2391 * 
     2392 * - `parser`: a parser object. 
     2393 * 
     2394 * - `buffer`: a pointer to character buffer containing the input stream.  The 
     2395 *   buffer must be valid until the parser object is cleared or deleted. 
     2396 * 
     2397 * - `length`: the length of the buffer in bytes. 
    13422398 */ 
    13432399 
     
    13462402        const unsigned char *buffer, size_t length); 
    13472403 
    1348 /** 
    1349  * Set a file input. 
    1350  * 
    1351  * @a file should be a file object open for reading.  The application is 
    1352  * responsible for closing the @a file. 
    1353  * 
    1354  * @param[in,out]   parser  A parser object. 
    1355  * @param[in]       file    An open file. 
     2404/* 
     2405 * Set the parser to read the input stream from a file. 
     2406 * 
     2407 * Arguments: 
     2408 * 
     2409 * - `parser`: a parser object. 
     2410 * 
     2411 * - `file`: a pointer to an open file object.  The pointer must be valid until 
     2412 *   the parser object is cleared or deleted. 
    13562413 */ 
    13572414 
     
    13592416yaml_parser_set_file_reader(yaml_parser_t *parser, FILE *file); 
    13602417 
    1361 /** 
    1362  * Set a generic input handler. 
    1363  * 
    1364  * @param[in,out]   parser  A parser object. 
    1365  * @param[in]       reader  A read handler. 
    1366  * @param[in]       data    Any application data for passing to the read 
    1367  *                          handler. 
     2418/* 
     2419 * Set an input stream reader for a parser. 
     2420 * 
     2421 * Arguments: 
     2422 * 
     2423 * - `parser`: a parser object. 
     2424 * 
     2425 * - `reader`: a read handler. 
     2426 * 
     2427 * - `data`: application data for passing to the reader. 
    13682428 */ 
    13692429 
     
    13722432        yaml_reader_t *reader, void *data); 
    13732433 
    1374 #if 0 
    1375  
    1376 /** 
    1377  * Set the standard resolve handler. 
    1378  * 
    1379  * The standard resolver recognize the following scalar kinds: !!null, !!bool, 
    1380  * !!str, !!int and !!float. 
    1381  * 
    1382  * @param[in,out]   parser  A parser object. 
     2434/* 
     2435 * Set the standard nonspecific tag resolver for a parser. 
     2436 * 
     2437 * The standard resolver recognizes the following scalar tags: `!!null`, 
     2438 * `!!bool`, `!!str`, `!!int`, and `!!float`. 
     2439 * 
     2440 * Arguments: 
     2441 * 
     2442 * - `parser`: a parser object. 
    13832443 */ 
    13842444 
     
    13862446yaml_parser_set_standard_resolver(yaml_parser_t *parser); 
    13872447 
    1388 /** 
    1389  * Set the resolve handler. 
    1390  * 
    1391  * The standard resolver recognize the following scalar kinds: !!null, !!bool, 
    1392  * !!str, !!int and !!float. 
    1393  * 
    1394  * @param[in,out]   parser      A parser object. 
    1395  * @param[in]       resolver    A resolve handler. 
    1396  * @param[in]       data        Any application data for passing to the resolve 
    1397  *                              handler. 
     2448/* 
     2449 * Set a nonspecific tag resolver for a parser. 
     2450 * 
     2451 * Arguments: 
     2452 * 
     2453 * - `parser`: a parser object. 
     2454 * 
     2455 * - `resolver`: a resolve handler. 
     2456 * 
     2457 * - `data`: application data for passing to the resolver. 
    13982458 */ 
    13992459 
     
    14022462        yaml_resolver_t *resolver, void *data); 
    14032463 
    1404 #endif 
    1405  
    1406 /** 
    1407  * Set the source encoding. 
    1408  * 
    1409  * @param[in,out]   parser      A parser object. 
    1410  * @param[in]       encoding    The source encoding. 
     2464/* 
     2465 * Set the input stream encoding. 
     2466 * 
     2467 * Typically the parser guesses the input stream encoding by the BOM mark.  If 
     2468 * the BOM mark is not present, the UTF-8 encoding is assumed.  An application 
     2469 * could override the detection mechanism by specifying the the encoding 
     2470 * explicitly. 
     2471 * 
     2472 * Arguments: 
     2473 * 
     2474 * - `parser`: a parser object. 
     2475 * 
     2476 * - `encoding`: the input stream encoding. 
    14112477 */ 
    14122478 
     
    14142480yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding); 
    14152481 
    1416 /** 
    1417  * Scan the input stream and produce the next token. 
    1418  * 
    1419  * Call the function subsequently to produce a sequence of tokens corresponding 
    1420  * to the input stream.  The initial token has the type 
    1421  * @c YAML_STREAM_START_TOKEN while the ending token has the type 
    1422  * @c YAML_STREAM_END_TOKEN. 
    1423  * 
    1424  * An application is responsible for freeing any buffers associated with the 
    1425  * produced token object using the @c yaml_token_delete() function. 
    1426  * 
    1427  * An application must not alternate the calls of @c yaml_parser_scan() with 
    1428  * the calls of @c yaml_parser_parse() or @c yaml_parser_load(). Doing this 
    1429  * will break the parser. 
    1430  * 
    1431  * @param[in,out]   parser      A parser object. 
    1432  * @param[out]      token       An empty token object. 
    1433  * 
    1434  * @returns @c 1 if the function succeeded, @c 0 on error. 
     2482/* 
     2483 * Parse the input stream and produce the next token. 
     2484 * 
     2485 * An application may call this function subsequently to produce a sequence of 
     2486 * tokens corresponding to the input stream.  The first token in the sequence 
     2487 * is STREAM-START and the last token is STREAM-END.  When the stream ends, the 
     2488 * parser produces empty tokens. 
     2489 * 
     2490 * An application must not alternate calls of the functions 
     2491 * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`, 
     2492 * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on 
     2493 * the same parser object. 
     2494 * 
     2495 * Arguments: 
     2496 * 
     2497 * - `parser`: a parser object. 
     2498 * 
     2499 * - `token`: an empty token object to save the token produced by the parser. 
     2500 *   An application is responsible for clearing or deleting the produced token. 
     2501 *   If the parser fails or the stream end is reached, the object is kept 
     2502 *   empty. 
     2503 * 
     2504 * Returns: `1` on success, `0` on error.  If the function succeeds and the 
     2505 * stream end is not reached, the token data is saved to the given token 
     2506 * object.  If the function fails, the error details could be obtained with 
     2507 * `yaml_parser_get_error()`.  In case of error, the parser is non-functional 
     2508 * until it is cleared. 
    14352509 */ 
    14362510 
     
    14382512yaml_parser_parse_token(yaml_parser_t *parser, yaml_token_t *token); 
    14392513 
    1440 /** 
     2514/* 
    14412515 * Parse the input stream and produce the next parsing event. 
    14422516 * 
    1443  * Call the function subsequently to produce a sequence of events corresponding 
    1444  * to the input stream.  The initial event has the type 
    1445  * @c YAML_STREAM_START_EVENT while the ending event has the type 
    1446  * @c YAML_STREAM_END_EVENT. 
    1447  * 
    1448  * An application is responsible for freeing any buffers associated with the 
    1449  * produced event object using the @c yaml_event_delete() function. 
    1450  * 
    1451  * An application must not alternate the calls of @c yaml_parser_parse() with 
    1452  * the calls of @c yaml_parser_scan() or @c yaml_parser_load(). Doing this will 
    1453  * break the parser. 
    1454  * 
    1455  * @param[in,out]   parser      A parser object. 
    1456  * @param[out]      event       An empty event object. 
    1457  * 
    1458  * @returns @c 1 if the function succeeded, @c 0 on error. 
     2517 * An application may call this function subsequently to produce a sequence of 
     2518 * events corresponding to the input stream.  The produced events satisfy 
     2519 * the grammar: 
     2520 * 
     2521 *      stream ::= STREAM-START document* STREAM-END 
     2522 *      document ::= DOCUMENT-START node DOCUMENT-END 
     2523 *      node ::= ALIAS | SCALAR | sequence | mapping 
     2524 *      sequence ::= SEQUENCE-START node* SEQUENCE-END 
     2525 *      mapping ::= MAPPING-START (node node)* MAPPING-END 
     2526 * 
     2527 * When the stream ends, the parser produces empty tokens. 
     2528 * 
     2529 * An application must not alternate calls of the functions 
     2530 * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`, 
     2531 * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on 
     2532 * the same parser object. 
     2533 * 
     2534 * Arguments: 
     2535 * 
     2536 * - `parser`: a parser object. 
     2537 * 
     2538 * - `event`: an empty event object to save the event produced by the parser. 
     2539 *   An application is responsible for clearing or deleting the produced event. 
     2540 *   Alternatively the produced event could be fed to the emitter.  If the 
     2541 *   parser fails or the stream end is reached, the object is kept empty. 
     2542 * 
     2543 * Returns: `1` on success, `0` on error.  If the function succeeds and the 
     2544 * stream end is not reached, the event data is saved to the given event 
     2545 * object.  If the function fails, the error details could be obtained with 
     2546 * `yaml_parser_get_error()`.  In case of error, the parser is non-functional 
     2547 * until it is cleared. 
    14592548 */ 
    14602549 
     
    14622551yaml_parser_parse_event(yaml_parser_t *parser, yaml_event_t *event); 
    14632552 
    1464 #if 0 
    1465  
    1466 /** 
     2553/* 
    14672554 * Parse the input stream and produce the next YAML document. 
    14682555 * 
    1469  * Call this function subsequently to produce a sequence of documents 
    1470  * constituting the input stream. 
    1471  * 
    1472  * If the produced document has no root node, it means that the document 
    1473  * end has been reached. 
    1474  * 
    1475  * An application is responsible for freeing any data associated with the 
    1476  * produced document object using the @c yaml_document_delete() function. 
    1477  * 
    1478  * An application must not alternate the calls of @c yaml_parser_load() with 
    1479  * the calls of @c yaml_parser_scan() or @c yaml_parser_parse(). Doing this 
    1480  * will break the parser. 
    1481  * 
    1482  * @param[in,out]   parser      A parser object. 
    1483  * @param[out]      document    An empty document object. 
    1484  * 
    1485  * @return @c 1 if the function succeeded, @c 0 on error. 
     2556 * An application may call this function subsequently to produce a sequence of 
     2557 * documents constituting the input stream.  When the stream ends, the parser 
     2558 * produces empty documents. 
     2559 * 
     2560 * An application must not alternate calls of the functions 
     2561 * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`, 
     2562 * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on 
     2563 * the same parser object. 
     2564 * 
     2565 * Arguments: 
     2566 * 
     2567 * - `parser`: a parser object. 
     2568 * 
     2569 * - `document`: an empty document object to save the document produced by the 
     2570 *   parser.  An application is responsible for clearing or deleting the 
     2571 *   produced document.  Alternatively the produced document could be fed to 
     2572 *   the emitter.  If the parser fails or the stream end is reached, the object 
     2573 *   is kept empty. 
     2574 * 
     2575 * Returns: `1` on success, `0` on error.  If the function succeeds and the 
     2576 * stream end is not reached, the document data is saved to the given document 
     2577 * object.  If the function fails, the error details could be obtained with 
     2578 * `yaml_parser_get_error()`.  In case of error, the parser is non-functional 
     2579 * until it is cleared. 
    14862580 */ 
    14872581 
     
    14892583yaml_parser_parse_document(yaml_parser_t *parser, yaml_document_t *document); 
    14902584 
    1491 #endif 
    1492  
    1493 /** @} */ 
    1494  
    1495 /** 
    1496  * @defgroup emitter Emitter Definitions 
    1497  * @{ 
    1498  */ 
    1499  
    1500 /** The emitter object. */ 
     2585/* 
     2586 * Parse the input stream containing a single YAML document. 
     2587 * 
     2588 * An application may call this function to ensure that the input stream contain 
     2589 * no more that one document.  If the stream is empty, the parser produces an 
     2590 * empty document.  If the stream contains a single document, the parser returns 
     2591 * it.  If the stream contains more than one document, the parser produces an 
     2592 * error. 
     2593 * 
     2594 * An application must not alternate calls of the functions 
     2595 * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`, 
     2596 * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on 
     2597 * the same parser object. 
     2598 * 
     2599 * Arguments: 
     2600 * 
     2601 * - `parser`: a parser object. 
     2602 * 
     2603 * - `document`: an empty document object to save the document produced by the 
     2604 *   parser.  An application is responsible for clearing or deleting the 
     2605 *   produced document.  Alternatively the produced document could be fed to 
     2606 *   the emitter.  If the parser fails or the stream is empty, the object is 
     2607 *   kept empty. 
     2608 * 
     2609 * Returns: `1` on success, `0` on error.  If the function succeeds and the 
     2610 * stream is not empty, the document data is saved to the given document 
     2611 * object.  If the function fails, the error details could be obtained with 
     2612 * `yaml_parser_get_error()`.  In case of error, the parser is non-functional 
     2613 * until it is cleared. 
     2614 */ 
     2615 
     2616YAML_DECLARE(int) 
     2617yaml_parser_parse_single_document(yaml_parser_t *parser, 
     2618        yaml_document_t *document); 
     2619 
     2620/****************************************************************************** 
     2621 * Emitter Definitions 
     2622 ******************************************************************************/ 
     2623 
     2624/* 
     2625 * An opaque definition of the emitter object. 
     2626 * 
     2627 * An emitter object is used to emit YAML events or documents into an output 
     2628 * YAML stream. 
     2629 */ 
     2630 
    15012631typedef struct yaml_emitter_s yaml_emitter_t; 
    15022632 
    1503 /** 
    1504  * Create a new emitter object. 
    1505  * 
    1506  * This function creates a new emitter object.  An application is responsible 
    1507  * for destroying the object using the @c yaml_emitter_delete() function. 
    1508  * 
    1509  * @returns a new emitter object or @c NULL on error. 
     2633/* 
     2634 * Allocate a new emitter object. 
     2635 * 
     2636 * An allocated emitter object should be deleted with `yaml_emitter_delete()`. 
     2637 * 
     2638 * Returns: a new emitter or `NULL` on error.  The function mail fail if it 
     2639 * cannot allocate memory for internal buffers. 
    15102640 */ 
    15112641 
     
    15132643yaml_emitter_new(void); 
    15142644 
    1515 /** 
    1516  * Destroy an emitter. 
    1517  * 
    1518  * @param[in,out]   emitter     An emitter object. 
     2645/* 
     2646 * Deallocate an emitter and free the internal emitter data. 
     2647 *  
     2648 * An emitter object must be previously allocated with `yaml_emitter_new()`. 
     2649 * 
     2650 * Arguments: 
     2651 * 
     2652 * - `emitter`: an emitter object. 
    15192653 */ 
    15202654 
     
    15222656yaml_emitter_delete(yaml_emitter_t *emitter); 
    15232657 
    1524 /** 
    1525  * Get an emitter error. 
    1526  * 
    1527  * @param[in]   emitter An emitter object. 
    1528  * @param[out]  error   An error object. 
     2658/* 
     2659 * Clear and reinitialize the internal state of the emitter. 
     2660 * 
     2661 * This function could be used for cleaning up an emitter object after an error 
     2662 * condition or after a complete YAML stream was produced.  A cleaned emitter 
     2663 * object may be reused to produce another YAML stream.  Note that all the 
     2664 * emitter parameters including the write handler must be reset. 
     2665 * 
     2666 * Arguments: 
     2667 * 
     2668 * - `emitter`: an emitter object. 
    15292669 */ 
    15302670 
    15312671YAML_DECLARE(void) 
    1532 yaml_emitter_get_error(yaml_emitter_t *emitter, yaml_error_t *error); 
    1533  
    1534 /** 
    1535  * Set a string output. 
    1536  * 
    1537  * The emitter will write the output characters to the @a output buffer of the 
    1538  * size @a size.  The emitter will set @a size_written to the number of written 
    1539  * bytes.  If the buffer is smaller than required, the emitter produces the 
    1540  * @c YAML_WRITE_ERROR error. 
    1541  * 
    1542  * @param[in,out]   emitter         An emitter object. 
    1543  * @param[in]       buffer          An output buffer. 
    1544  * @param[in]       capacity        The buffer size. 
    1545  * @param[in]       length          The pointer to save the number of written 
    1546  *                                  bytes. 
     2672yaml_emitter_clear(yaml_emitter_t *emitter); 
     2673 
     2674/* 
     2675 * Get the emitter error. 
     2676 * 
     2677 * Use this function to get a detailed error information after failure of one 
     2678 * of the following functions: `yaml_emitter_emit_event()`, 
     2679 * `yaml_emitter_open()`, `yaml_emitter_close()`, 
     2680 * `yaml_emitter_emit_document()`, `yaml_emitter_emit_single_document()`. 
     2681 * 
     2682 * The pointer returned by the function is only valid until the emitter object 
     2683 * is not modified.  However the error object could be safely copied. 
     2684 * 
     2685 * Arguments: 
     2686 * 
     2687 * - `emitter`: an emitter object. 
     2688 * 
     2689 * Returns: a pointer to an error object.  The returned pointer is only valid 
     2690 * until the emitter object is not modified or deleted.  However the error 
     2691 * object could be safely copied. 
     2692 */ 
     2693 
     2694YAML_DECLARE(yaml_error_t *) 
     2695yaml_emitter_get_error(yaml_emitter_t *emitter); 
     2696 
     2697/* 
     2698 * Set the emitter to dump the generated YAML stream into a string buffer. 
     2699 * 
     2700 * Arguments: 
     2701 * 
     2702 * - `emitter`: an emitter object. 
     2703 * 
     2704 * - `buffer`: a pointer to a buffer to store the generated YAML stream.  The 
     2705 *   pointer must be valid until the emitter object is cleared or deleted. 
     2706 * 
     2707 * - `capacity`: the size of the buffer.  The emitter will fail if the buffer 
     2708 *   is smaller than required to hold the whole stream. 
     2709 * 
     2710 * - `length`: a pointer to save the length of the produced stream (in bytes). 
    15472711 */ 
    15482712 
     
    15512715        unsigned char *buffer, size_t capacity, size_t *length); 
    15522716 
    1553 /** 
    1554  * Set a file output. 
    1555  * 
    1556  * @a file should be a file object open for writing.  The application is 
    1557  * responsible for closing the @a file. 
    1558  * 
    1559  * @param[in,out]   emitter     An emitter object. 
    1560  * @param[in]       file        An open file. 
     2717/* 
     2718 * Set the emitter to dump the generated YAML stream into a file. 
     2719 * 
     2720 * Arguments: 
     2721 * 
     2722 * - `emitter`: an emitter object. 
     2723 * 
     2724 * - `file`: a pointer to a file open for writing.  The pointer must be valid 
     2725 *   until the emitter object is cleared or deleted. 
    15612726 */ 
    15622727 
     
    15642729yaml_emitter_set_file_writer(yaml_emitter_t *emitter, FILE *file); 
    15652730 
    1566 /** 
    1567  * Set a generic output handler. 
    1568  * 
    1569  * @param[in,out]   emitter     An emitter object. 
    1570  * @param[in]       writer      A write handler. 
    1571  * @param[in]       data        Any application data for passing to the write 
    1572  *                              handler. 
     2731/* 
     2732 * Set the output stream writer for an emitter. 
     2733 * 
     2734 * Arguments: 
     2735 * 
     2736 * - `emitter`: an emitter object. 
     2737 * 
     2738 * - `writer`: a write handler. 
     2739 * 
     2740 * - `data`: application data for passing to the writer. 
    15732741 */ 
    15742742 
     
    15772745        yaml_writer_t *writer, void *data); 
    15782746 
    1579 #if 0 
    1580  
    1581 /** 
    1582  * Set the standard resolve handler. 
    1583  * 
    1584  * The standard resolver recognize the following scalar kinds: !!null, !!bool, 
    1585  * !!str, !!int and !!float. 
    1586  * 
    1587  * @param[in,out]   emitter An emitter object. 
     2747/* 
     2748 * Set the standard nonspecific tag resolver for an emitter. 
     2749 * 
     2750 * The standard resolver recognizes the following scalar tags: `!!null`, 
     2751 * `!!bool`, `!!str`, `!!int`, and `!!float`. 
     2752 * 
     2753 * Arguments: 
     2754 * 
     2755 * - `emitter`: an emitter object. 
    15882756 */ 
    15892757 
     
    15912759yaml_emitter_set_standard_resolver(yaml_emitter_t *emitter); 
    15922760 
    1593 /** 
    1594  * Set the resolve handler. 
    1595  * 
    1596  * The standard resolver recognize the following scalar kinds: !!null, !!bool, 
    1597  * !!str, !!int and !!float. 
    1598  * 
    1599  * @param[in,out]   emitter     An emitter object. 
    1600  * @param[in]       resolver    A resolve handler. 
    1601  * @param[in]       data        Any application data for passing to the resolve 
    1602  *                              handler. 
     2761/* 
     2762 * Set a nonspecific tag resolver for an emitter. 
     2763 * 
     2764 * Arguments: 
     2765 * 
     2766 * - `emitter`: an emitter object. 
     2767 * 
     2768 * - `resolver`: a resolve handler. 
     2769 * 
     2770 * - `data`: application data for passing to the resolver. 
    16032771 */ 
    16042772 
     
    16072775        yaml_resolver_t *resolver, void *data); 
    16082776 
    1609 #endif 
    1610  
    1611 /** 
    1612  * Set the output encoding. 
    1613  * 
    1614  * @param[in,out]   emitter     An emitter object. 
    1615  * @param[in]       encoding    The output encoding. 
     2777/* 
     2778 * Set the output stream encoding. 
     2779 * 
     2780 * The emitter uses the UTF-8 encoding for the output stream unless another 
     2781 * encoding is specified explicitly.  The encoding could be specified using 
     2782 * this function or via the `encoding` parameter of the STREAM-START event. 
     2783 * 
     2784 * Arguments: 
     2785 * 
     2786 * - `emitter`: an emitter object. 
     2787 * 
     2788 * - `encoding`: the output stream encoding. 
    16162789 */ 
    16172790 
     
    16192792yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding); 
    16202793 
    1621 /** 
    1622  * Set if the output should be in the "canonical" format as in the YAML 
    1623  * specification. 
    1624  * 
    1625  * @param[in,out]   emitter         An emitter object. 
    1626  * @param[in]       is_canonical    If the output is canonical. 
     2794/* 
     2795 * Specify if the emitter should use the "canonical" output format. 
     2796 * 
     2797 * The "canonical" format uses the flow style for collections and the 
     2798 * double-quoted style for scalars.  Node tags are always dumped explicitly. 
     2799 * 
     2800 * Arguments: 
     2801 * 
     2802 * - `emitter`: an emitter object. 
     2803 * 
     2804 * - `is_canonical`: `1` to set the "canonical" format, `0` otherwise. 
    16272805 */ 
    16282806 
     
    16302808yaml_emitter_set_canonical(yaml_emitter_t *emitter, int is_canonical); 
    16312809 
    1632 /** 
     2810/* 
    16332811 * Set the intendation increment. 
    16342812 * 
    1635  * @param[in,out]   emitter     An emitter object. 
    1636  * @param[in]       indent      The indentation increment (1 < . < 10). 
     2813 * The default intendation increment is `2`. 
     2814 * 
     2815 * Arguments: 
     2816 * 
     2817 * - `emitter`: an emitter object. 
     2818 * 
     2819 * - `indent`: the indentation increment; a number between `2` and `9`. 
    16372820 */ 
    16382821 
     
    16402823yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent); 
    16412824 
    1642 /** 
    1643  * Set the preferred line width. @c -1 means unlimited. 
    1644  * 
    1645  * @param[in,out]   emitter     An emitter object. 
    1646  * @param[in]       width       The preferred line width. 
     2825/* 
     2826 * Set the preferred line width. 
     2827 * 
     2828 * The default preferred line width is `80`.  The given line width is only a 
     2829 * stylistic hint and could be violated by the emitter.  When the line width is 
     2830 * exceeded, the emitter seeks for a way to move to the next line. 
     2831 * 
     2832 * Arguments: 
     2833 * 
     2834 * - `emitter`: an emitter object. 
     2835 * 
     2836 * - `width`: the preferred line width; `-1` means unlimited. 
    16472837 */ 
    16482838 
     
    16502840yaml_emitter_set_width(yaml_emitter_t *emitter, int width); 
    16512841 
    1652 /** 
    1653  * Set if unescaped non-ASCII characters are allowed. 
    1654  * 
    1655  * @param[in,out]   emitter     An emitter object. 
    1656  * @param[in]       is_unicode  If unescaped Unicode characters are allowed. 
     2842/* 
     2843 * Specify if non-ASCII characters could be emitted unescaped. 
     2844 * 
     2845 * By default, the emitter always escapes non-ASCII characters using the `\u` 
     2846 * or `\U` format. 
     2847 * 
     2848 * Arguments: 
     2849 * 
     2850 * - `emitter`: an emitter object. 
     2851 * 
     2852 * - `is_unicode`: `1` if unescaped non-ASCII characters are allowed; `0` 
     2853 *   otherwise. 
    16572854 */ 
    16582855 
     
    16602857yaml_emitter_set_unicode(yaml_emitter_t *emitter, int is_unicode); 
    16612858 
    1662 /** 
     2859/* 
    16632860 * Set the preferred line break. 
    16642861 * 
    1665  * @param[in,out]   emitter     An emitter object. 
    1666  * @param[in]       line_break  The preferred line break. 
     2862 * By default, the emitter uses the LN character for line breaks. 
     2863 * 
     2864 * Arguments: 
     2865 * 
     2866 * - `emitter`: an emitter object. 
     2867 * 
     2868 * - `line_break`: the preferred line break. 
    16672869 */ 
    16682870 
     
    16702872yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break); 
    16712873 
    1672 /** 
    1673  * Emit an event. 
    1674  * 
    1675  * The event object may be generated using the yaml_parser_parse() function. 
    1676  * The emitter takes the responsibility for the event object and destroys its 
    1677  * content after it is emitted. The event object is destroyed even if the 
    1678  * function fails. 
    1679  * 
    1680  * @param[in,out]   emitter     An emitter object. 
    1681  * @param[in,out]   event       An event object. 
    1682  * 
    1683  * @returns @c 1 if the function succeeded, @c 0 on error. 
     2874/* 
     2875 * Emit an event to the output YAML stream. 
     2876 * 
     2877 * An application needs to call this function subsequently to produce a whole 
     2878 * YAML stream.  The event sequence must satisfy the following grammar: 
     2879 * 
     2880 *      stream ::= STREAM-START document* STREAM-END 
     2881 *      document ::= DOCUMENT-START node DOCUMENT-END 
     2882 *      node ::= ALIAS | SCALAR | sequence | mapping 
     2883 *      sequence ::= SEQUENCE-START node* SEQUENCE-END 
     2884 *      mapping ::= MAPPING-START (node node)* MAPPING-END 
     2885 * 
     2886 * An application must not alternate the calls of the functions 
     2887 * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and 
     2888 * `yaml_emitter_emit_single_document()` on the same emitter object. 
     2889 * 
     2890 * Arguments: 
     2891 * 
     2892 * - `emitter`: an emitter object. 
     2893 * 
     2894 * - `event`: an event to emit.  The event must be previously initialized using 
     2895 *   either one of the functions `yaml_event_create_*()` or with 
     2896 *   `yaml_parser_parse_event()`.  The emitter takes the responsibility for the 
     2897 *   event data and clears the event, so that it becomes empty.  The event is 
     2898 *   cleared even if the function fails. 
     2899 * 
     2900 * Returns: `1` on success, `0` on error.  Note that the emitter may not 
     2901 * immediately dump the given event, so that the function could indicate 
     2902 * success on an errorneous event.  In this case, some of the next calls of the 
     2903 * function will generate an error.  If the function fails, the error details 
     2904 * could be obtained with `yaml_emitter_get_error()`.  In case of error, the 
     2905 * emitter is non-functional until it is cleared. 
    16842906 */ 
    16852907 
     
    16872909yaml_emitter_emit_event(yaml_emitter_t *emitter, yaml_event_t *event); 
    16882910 
    1689 #if 0 
    1690  
    1691 /** 
     2911/* 
    16922912 * Start a YAML stream. 
    16932913 * 
    1694  * This function should be used before the first @c yaml_emitter_dump() is 
    1695  * called. 
    1696  * 
    1697  * @param[in,out]   emitter     An emitter object. 
    1698  * 
    1699  * @returns @c 1 if the function succeeded, @c 0 on error. 
    1700  */ 
    1701  
    1702 YAML_DECLARE(int) 
    1703 yaml_emitter_open(yaml_emitter_t *emitter); 
    1704  
    1705 /** 
     2914 * This function should be used in conjunction with 
     2915 * `yaml_emitter_emit_document()` and `yaml_emitter_end()`.  This function must 
     2916 * be called once before any documents are emitted. 
     2917 * 
     2918 * Arguments: 
     2919 * 
     2920 * - `emitter`: an emitter object. 
     2921 * 
     2922 * Returns: `1` on success, `0` on error.  If the function fails, the error 
     2923 * details could be obtained with `yaml_emitter_get_error()`.  In case of 
     2924 * error, the emitter is non-functional until it is cleared. 
     2925 */ 
     2926 
     2927YAML_DECLARE(int) 
     2928yaml_emitter_start(yaml_emitter_t *emitter); 
     2929 
     2930/* 
    17062931 * Finish a YAML stream. 
    17072932 * 
    1708  * This function should be used after the last @c yaml_emitter_dump() is 
    1709  * called. 
    1710  * 
    1711  * @param[in,out]   emitter     An emitter object. 
    1712  * 
    1713  * @returns @c 1 if the function succeeded, @c 0 on error. 
    1714  */ 
    1715  
    1716 YAML_DECLARE(int) 
    1717 yaml_emitter_close(yaml_emitter_t *emitter); 
    1718  
    1719 /** 
     2933 * This function should be used in conjunction with `yaml_emitter_start()` and 
     2934 * `yaml_emitter_emit_document()`.  This function must be called once after all 
     2935 * documents are emitted. 
     2936 * 
     2937 * Arguments: 
     2938 * 
     2939 * - `emitter`: an emitter object. 
     2940 * 
     2941 * Returns: `1` on success, `0` on error.  If the function fails, the error 
     2942 * details could be obtained with `yaml_emitter_get_error()`.  In case of 
     2943 * error, the emitter is non-functional until it is cleared. 
     2944 */ 
     2945 
     2946YAML_DECLARE(int) 
     2947yaml_emitter_end(yaml_emitter_t *emitter); 
     2948 
     2949/* 
    17202950 * Emit a YAML document. 
    17212951 * 
    1722  * The document object may be generated using the @c yaml_parser_load() 
    1723  * function or the @c yaml_document_initialize() function.  The emitter takes 
    1724  * the responsibility for the document object and destoys its content after 
    1725  * it is emitted. The document object is destroyed even if the function fails. 
    1726  * 
    1727  * @param[in,out]   emitter     An emitter object. 
    1728  * @param[in,out]   document    A document object. 
    1729  * 
    1730  * @returns @c 1 if the function succeeded, @c 0 on error. 
     2952 * Before emitting any documents, the function `yaml_emitter_start()` must be 
     2953 * called.  After all documents are emitted, the function `yaml_emitter_end()` 
     2954 * must be called. 
     2955 * 
     2956 * An application must not alternate the calls of the functions 
     2957 * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and 
     2958 * `yaml_emitter_emit_single_document()` on the same emitter object. 
     2959 * 
     2960 * Arguments: 
     2961 * 
     2962 * - `emitter`: an emitter object. 
     2963 * 
     2964 * - `document`: a document to emit.  The document must have a root node with 
     2965 *   all the other nodes reachable from it.  The document may be prepared using 
     2966 *   the functions `yaml_document_create()`, `yaml_document_add_*()` and 
     2967 *   `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`. 
     2968 *   The emitter takes the responsibility for the document content and clears 
     2969 *   the document, so that it becomes empty.  The document is cleared even if 
     2970 *   the function fails. 
     2971 * 
     2972 * Returns: `1` on success, `0` on error.  If the function fails, the error 
     2973 * details could be obtained with `yaml_emitter_get_error()`.  In case of 
     2974 * error, the emitter is non-functional until it is cleared. 
    17312975 */ 
    17322976 
     
    17342978yaml_emitter_emit_document(yaml_emitter_t *emitter, yaml_document_t *document); 
    17352979 
    1736 #endif 
    1737  
    1738 /** 
    1739  * Flush the accumulated characters to the output stream. 
    1740  * 
    1741  * @param[in,out]   emitter     An emitter object. 
    1742  * 
    1743  * @returns @c 1 if the function succeeded, @c 0 on error. 
     2980/* 
     2981 * Emit a YAML stream consisting of a single document. 
     2982 * 
     2983 * This function is a shorthand of the calls: 
     2984 * 
     2985 *      yaml_emitter_start(emitter) 
     2986 *      yaml_emitter_emit_document(emitter, document) 
     2987 *      yaml_emitter_end(emitter) 
     2988 * 
     2989 * An application must not alternate the calls of the functions 
     2990 * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and 
     2991 * `yaml_emitter_emit_single_document()` on the same emitter object. 
     2992 * 
     2993 * Arguments: 
     2994 * 
     2995 * - `emitter`: an emitter object. 
     2996 * 
     2997 * - `document`: a document to emit.  The document must have a root node with 
     2998 *   all the other nodes reachable from it.  The document may be prepared using 
     2999 *   the functions `yaml_document_create()`, `yaml_document_add_*()` and 
     3000 *   `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`. 
     3001 *   The emitter takes the responsibility for the document content and clears 
     3002 *   the document, so that it becomes empty.  The document is cleared even if 
     3003 *   the function fails. 
     3004 * 
     3005 * Returns: `1` on success, `0` on error.  If the function fails, the error 
     3006 * details could be obtained with `yaml_emitter_get_error()`.  In case of 
     3007 * error, the emitter is non-functional until it is cleared. 
     3008 */ 
     3009 
     3010YAML_DECLARE(int) 
     3011yaml_emitter_emit_single_document(yaml_emitter_t *emitter, 
     3012        yaml_document_t *document); 
     3013 
     3014/* 
     3015 * Flush the accumulated characters. 
     3016 * 
     3017 * This function flushes the accumulated characters from the internal emitter 
     3018 * buffer to the output stream.  Note that the buffer is flushed automatically 
     3019 * when a complete document has emitted or a stream has ended. 
     3020 * 
     3021 * Arguments: 
     3022 * 
     3023 * - `emitter`: an emitter object. 
     3024 * 
     3025 * Returns: `1` on success, `0` on error.  If the function fails, the error 
     3026 * details could be obtained with `yaml_emitter_get_error()`.  In case of 
     3027 * error, the emitter is non-functional until it is cleared. 
    17443028 */ 
    17453029 
     
    17473031yaml_emitter_flush(yaml_emitter_t *emitter); 
    17483032 
    1749 /** @} */ 
    17503033 
    17513034#ifdef __cplusplus 
Note: See TracChangeset for help on using the changeset viewer.