Changeset 266


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

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

Location:
libyaml/trunk
Files:
1 deleted
3 edited

Legend:

Unmodified
Added
Removed
  • libyaml/trunk/README

    r220 r266  
    11LibYAML - A C library for parsing and emitting YAML. 
    2  
    3 The project is in an early stage of development. 
    42 
    53To build and install the library, run: 
     
    1412# make install 
    1513 
    16 For more information, check the LibYAML homepage: 
     14For the API reference, check the file 'include/yaml.h'.  Examples on how to use 
     15LibYAML could be found in the 'tests' directory. 
     16 
     17Check the LibYAML homepage for more information: 
    1718'http://pyyaml.org/wiki/LibYAML'. 
    1819 
     
    2627under the MIT license.  See the file LICENSE for more details. 
    2728 
    28 This project is developed for Python Software Foundation as a part of 
    29 Google Summer of Code under the mentorship of Clark Evans. 
     29The initial version of this project was developed for Python Software 
     30Foundation under the mentorshipf of Clark Evans as a part of Google Summer of 
     31Code 2006. 
  • libyaml/trunk/include/Makefile.am

    r200 r266  
    11INCLUDES = yaml.h 
    2 DOXYGEN_CFG = $(top_srcdir)/doc/doxygen.cfg 
    32 
    43nobase_include_HEADERS = $(INCLUDES) 
    54 
    6 if DOXYGEN 
    7  
    8 html: $(INCLUDES) $(DOXYGEN_CFG) 
    9         PACKAGE=$(PACKAGE) VERSION=$(VERSION) top_srcdir=$(top_srcdir) top_builddir=$(top_builddir) doxygen $(DOXYGEN_CFG) 
    10  
    11 endif 
    12  
    13 distclean-local: 
    14         -rm -rf $(top_builddir)/doc/html 
    15  
    16 dist-hook: html 
    17         cp -a $(top_builddir)/doc/html $(top_distdir)/doc 
  • 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.