source: libyaml/trunk/include/yaml.h @ 267

Revision 267, 95.9 KB checked in by xi, 6 years ago (diff)

Minor API updates.

RevLine 
[266]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
[267]10/*****************************************************************************
11 * General guidelines.
12 *****************************************************************************/
13
[266]14/*
[267]15 * Basic conventions.
[266]16 *
[267]17 * All functions exported by exported by LibYAML starts with the the prefix
18 * `yaml_`; types starts with `yaml_` and ends with `_t`; macros and
19 * enumeration values start with `YAML_`.
[266]20 *
[267]21 * A function may serve as method for an object or a particular type; such
22 * functions start with `yaml_<type>`.  A type constructor is named
23 * `yaml_<type>_new()`, a type destructor is named `yaml_<type>_delete()`.
24 *
25 * A function signifies whether it succeeded or failed with its return value;
26 * typically it is `1` for success, `0` for failure.  Functions that return a
27 * pointer may indicate an error condition by returning `NULL`.  Functions that
28 * never fail commonly do not return any value.  For most of the functions, an
29 * error value means that the function is unable to allocate some memory
30 * buffer.  For parsing and emitting functions, detailed information on the
31 * nature of the error could be obtained.
32 *
33 * LibYAML provides two active objects: parsers and emitters and three passive
34 * objects: tokens, events and documents.
35 *
36 *
37 *
38 *
[266]39 * FIXME: Calling conventions.
40 * FIXME: Memory allocation.
41 * FIXME: Errors and exceptions.
42 * FIXME: And so on, and so forth.
[267]43 *
44 *
45 *
46 *
[172]47 */
[162]48
[266]49
[169]50#ifndef YAML_H
51#define YAML_H
[162]52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
[169]57#include <stdlib.h>
[179]58#include <stdio.h>
59#include <string.h>
[162]60
[266]61/*****************************************************************************
62 * Export Definitions
63 *****************************************************************************/
64
65/*
66 * Public API declarations.
67 *
68 * The following definitions are relevant only for the Win32 platform.  If you
69 * are building LibYAML as a static library or linking your application against
70 * LibYAML compiled as a static library, define the macro
71 * `YAML_DECLARE_STATIC`.  If you are building LibYAML as a dynamic library
72 * (DLL), you need to define `YAML_DECLARE_EXPORT`.  You don't need to define
73 * any macros in case you are linking your application against LibYAML compiled
74 * as DLL.
75 *
76 * There is no need to define any macros if you use LibYAML on non-Win32
77 * platform.
[183]78 */
79
80#ifdef WIN32
81#   if defined(YAML_DECLARE_STATIC)
82#       define  YAML_DECLARE(type)  type
83#   elif defined(YAML_DECLARE_EXPORT)
84#       define  YAML_DECLARE(type)  __declspec(dllexport) type
85#   else
86#       define  YAML_DECLARE(type)  __declspec(dllimport) type
87#   endif
88#else
89#   define  YAML_DECLARE(type)  type
90#endif
91
[266]92/*****************************************************************************
93 * Version Information
94 *****************************************************************************/
[183]95
[266]96/*
97 * The major, minor and patch version numbers of LibYAML.
[178]98 */
[169]99
[264]100#define YAML_VERSION_MAJOR  0
101#define YAML_VERSION_MINOR  2
102#define YAML_VERSION_PATCH  0
103
[266]104/*
105 * The version of LibYAML as a string.
106 */
[264]107
[266]108#define YAML_VERSION_STRING "0.2.0"
[264]109
[266]110/*
[264]111 * Get the library version numbers at runtime.
[178]112 *
[266]113 * Arguments:
114 *
115 * - `major`: a pointer to store the major version number.
116 *
117 * - `minor`: a pointer to store the minor version number.
118 *
119 * - `patch`: a pointer to store the patch version number.
[178]120 */
121
[183]122YAML_DECLARE(void)
[178]123yaml_get_version(int *major, int *minor, int *patch);
124
[266]125/*
[264]126 * Get the library version as a string at runtime.
127 *
[266]128 * Returns: the version of LibYAML as a static string.
[264]129 */
130
131YAML_DECLARE(const char *)
132yaml_get_version_string(void);
133
[266]134/*****************************************************************************
135 * Error Handling
136 *****************************************************************************/
[178]137
[266]138/*
139 * The type of the error.
140 *
141 * The YAML parser and emitter reports any error details using the
142 * `yaml_error_t` structure.  The error type shows what subsystem generated the
143 * error and what additional information about the error is available.
[261]144 */
145
146typedef enum yaml_error_type_e {
[266]147    /* No error was produced. */
[261]148    YAML_NO_ERROR,
149
[266]150    /* Cannot allocate or reallocate a block of memory. */
[261]151    YAML_MEMORY_ERROR,
152
[266]153    /* Cannot read from the input stream. */
[261]154    YAML_READER_ERROR,
[266]155    /* Cannot decode a character in the input stream. */
[261]156    YAML_DECODER_ERROR,
[266]157    /* Cannot scan a YAML token. */
[261]158    YAML_SCANNER_ERROR,
[266]159    /* Cannot parse a YAML event. */
[261]160    YAML_PARSER_ERROR,
[266]161    /* Cannot compose a YAML document. */
[261]162    YAML_COMPOSER_ERROR,
163
[266]164    /* Cannot write into the output stream. */
[261]165    YAML_WRITER_ERROR,
[266]166    /* Cannot emit a YAML event. */
[261]167    YAML_EMITTER_ERROR,
[266]168    /* Cannot serialize a YAML document. */
[264]169    YAML_SERIALIZER_ERROR,
170
[266]171    /* Cannot resolve an implicit YAML node tag. */
[264]172    YAML_RESOLVER_ERROR
[261]173} yaml_error_type_t;
174
[266]175/*
176 * Position in the input stream.
177 *
178 * Marks are used to indicate the position of YAML tokens, events and documents
179 * in the input stream as well as to point to the place where a parser error has
180 * occured.
181 */
182
[261]183typedef struct yaml_mark_s {
[266]184    /* The number of the character in the input stream (starting from zero). */
[261]185    size_t index;
[266]186    /* The line in the input stream (starting from zero). */
[261]187    size_t line;
[266]188    /* The column in the input stream (starting from zero). */
[261]189    size_t column;
190} yaml_mark_t;
191
[266]192/*
193 * Error details.
194 *
195 * The structure gives detailed information on any problem that occured during
196 * parsing or emitting.
197 */
198
[261]199typedef struct yaml_error_s {
200
[266]201    /* The error type. */
[261]202    yaml_error_type_t type;
203
[266]204    /* The specific information for each error type. */
[261]205    union {
206
[266]207        /*
208         * A problem occured while reading the input stream (relevant for
209         * `YAML_READER_ERROR` and `YAML_DECODER_ERROR`).
[261]210         */
211        struct {
[266]212            /* The problem description. */
[261]213            const char *problem;
[266]214            /* The position in the input stream, in bytes. */
[261]215            size_t offset;
[266]216            /* The problematic octet or character (`-1` if not applicable). */
[261]217            int value;
218        } reading;
219
[266]220        /*
221         * A problem occured while loading YAML data from the input stream
222         * (relevant for `YAML_SCANNER_ERROR`, `YAML_PARSER_ERROR`, and
223         * `YAML_COMPOSER_ERROR`).
[261]224         */
225        struct {
[266]226            /* The description of the context in which the problem occured
227               (`NULL` if not applicable). */
[261]228            const char *context;
[266]229            /* The context mark (if `context` is not `NULL`). */
[261]230            yaml_mark_t context_mark;
[266]231            /* The problem description. */
[264]232            const char *problem;
[266]233            /* The problem mark. */
[264]234            yaml_mark_t problem_mark;
[261]235        } loading;
236
[266]237        /*
238         * A problem occured while writing into the output stream (relevant for
239         * `YAML_WRITER_ERROR`).
240         */
[261]241        struct {
[266]242            /* The problem description. */
[261]243            const char *problem;
[266]244            /* The position in the output stream, in bytes. */
[261]245            size_t offset;
246        } writing;
247
[266]248        /*
249         * A problem while dumping YAML data into the output stream (relevant
250         * for `YAML_EMITTER_ERROR` and `YAML_SERIALIZER_ERROR`).
[261]251         */
252        struct {
[266]253            /* The problem description. */
[261]254            const char *problem;
255        } dumping;
256
[266]257        /*
258         * A problem occured while resolving an implicit YAML node tag
259         * (relevant for `YAML_RESOLVER_ERROR`).
260         */
[264]261        struct {
[266]262            /* The problem description. */
[264]263            const char *problem;
264        } resolving;
265
[261]266    } data;
267
268} yaml_error_t;
269
[266]270/*
271 * Generate an error message.
[264]272 *
[266]273 * Given an instance of the `yaml_error_t` structure and a buffer, the function
274 * fills the buffer with a message describing the error.  The generated message
275 * follows the pattern: `"Error type: error details"`.  If the buffer is not
276 * large enough to hold the whole message, the function fails.
[264]277 *
[266]278 * Arguments:
279 *
280 * - `error`: an error object obtained using `yaml_parser_get_error()` or
281 *   `yaml_emitter_get_error()`.
282 *
283 * - `buffer`: a pointer to a character buffer to be filled with a generated
284 *   error message.
285 *
286 * - `capacity`: the size of the buffer.
287 *
288 * Returns: `1` if the function succeeded, `0` on error.  The function may fail
289 * if the provided buffer is not large enough to hold the whole buffer, in
290 * which case an application may increase the size of the buffer and call the
291 * function again.  If the function fails, the content of the buffer is
292 * undefined.
[264]293 */
[261]294
[264]295YAML_DECLARE(int)
296yaml_error_message(yaml_error_t *error, char *buffer, size_t capacity);
297
[267]298/*****************************************************************************
[266]299 * Basic Types
[267]300 *****************************************************************************/
[261]301
[266]302/*
303 * The character type (UTF-8 octet).
304 *
305 * Usage of the string type `(yaml_char_t *)` in the LibYAML API indicates that
306 * the string is encoded in UTF-8.
[178]307 */
308
309typedef unsigned char yaml_char_t;
310
[266]311/*
312 * The version directive information.
313 *
314 * Note that LibYAML only supports YAML 1.1.
315 */
316
[238]317typedef struct yaml_version_directive_s {
[266]318    /* The major version number. */
[199]319    int major;
[266]320    /* The minor version number. */
[199]321    int minor;
322} yaml_version_directive_t;
323
[266]324/*
325 * The tag directive information.
326 */
327
[238]328typedef struct yaml_tag_directive_s {
[266]329    /* The tag handle. */
[199]330    yaml_char_t *handle;
[266]331    /* The tag prefix. */
[199]332    yaml_char_t *prefix;
333} yaml_tag_directive_t;
334
[266]335/*
336 * The stream encoding.
337 *
338 * An application may explicitly specify the encoding in the input stream or
339 * let the parser to detect the input stream encoding from a BOM mark.  If the
340 * stream does not start with a BOM mark, UTF-8 is assumed.
341 *
342 * An application may specify the encoding of the output stream or let the
343 * emitter to choose a suitable encoding, in which case, UTF-8 is used.
344 */
345
[238]346typedef enum yaml_encoding_e {
[266]347    /* The default/autodetected encoding. */
[178]348    YAML_ANY_ENCODING,
[266]349    /* The UTF-8 encoding. */
[162]350    YAML_UTF8_ENCODING,
[266]351    /* The UTF-16-LE encoding. */
[162]352    YAML_UTF16LE_ENCODING,
[266]353    /* The UTF-16-BE encoding. */
[162]354    YAML_UTF16BE_ENCODING
355} yaml_encoding_t;
356
[266]357/*
358 * Line break types.
359 *
360 * An application may specify the line break type the emitter should use or
361 * leave it to the emitter discretion.  In the latter case, LN (Unix style) is
362 * used.
363 */
364
[238]365typedef enum yaml_break_e {
[266]366    /* Let the parser choose the break type. */
[211]367    YAML_ANY_BREAK,
[266]368    /* Use CR for line breaks (Mac style). */
[211]369    YAML_CR_BREAK,
[266]370    /* Use LN for line breaks (Unix style). */
[211]371    YAML_LN_BREAK,
[266]372    /* Use CR LN for line breaks (DOS style). */
[211]373    YAML_CRLN_BREAK
374} yaml_break_t;
375
[267]376/*****************************************************************************
[266]377 * Node Styles
[267]378 *****************************************************************************/
[179]379
[266]380/*
381 * Scalar styles.
382 *
383 * There are two groups of scalar types in YAML: flow and block.  Flow scalars
384 * are divided into three styles: plain, single-quoted, and double-quoted;
385 * block scalars are divided into two styles: literal and folded.
386 *
387 * The parser reports the style in which a scalar node is represented, however
388 * it is a purely presentation details that must not be used in interpreting
389 * the node content.
390 *
391 * An application may suggest a preferred node style or leave it completely
392 * to the emitter discretion.  Note that the emitter may ignore any stylistic
393 * suggestions.
[183]394 */
[179]395
[238]396typedef enum yaml_scalar_style_e {
[266]397    /* Let the emitter choose the style. */
[169]398    YAML_ANY_SCALAR_STYLE,
[183]399
[266]400    /* The plain flow scalar style. */
[162]401    YAML_PLAIN_SCALAR_STYLE,
[183]402
[266]403    /* The single-quoted flow scalar style. */
[162]404    YAML_SINGLE_QUOTED_SCALAR_STYLE,
[266]405    /* The double-quoted flow scalar style. */
[162]406    YAML_DOUBLE_QUOTED_SCALAR_STYLE,
[183]407
[266]408    /* The literal block scalar style. */
[162]409    YAML_LITERAL_SCALAR_STYLE,
[266]410    /* The folded block scalar style. */
[162]411    YAML_FOLDED_SCALAR_STYLE
412} yaml_scalar_style_t;
413
[266]414/*
415 * Sequence styles.
416 *
417 * YAML supports two sequence styles: flow and block.
418 *
419 * The parser reports the style of a sequence node, but this information should
420 * not be used in interpreting the sequence content.
421 *
422 * An application may suggest a preferred sequence style or leave it completely
423 * to the emitter discretion.  Note that the emitter may ignore any stylistic
424 * hints.
425 */
[238]426typedef enum yaml_sequence_style_e {
[266]427    /* Let the emitter choose the style. */
[169]428    YAML_ANY_SEQUENCE_STYLE,
[183]429
[266]430    /* The flow sequence style. */
[267]431    YAML_FLOW_SEQUENCE_STYLE,
[266]432    /* The block sequence style. */
[267]433    YAML_BLOCK_SEQUENCE_STYLE
[162]434} yaml_sequence_style_t;
435
[266]436/*
437 * Mapping styles.
438 *
439 * YAML supports two mapping styles: flow and block.
440 *
441 * The parser reports the style of a mapping node, but this information should
442 * not be used in interpreting the mapping content.
443 *
444 * An application may suggest a preferred mapping style or leave it completely
445 * to the emitter discretion.  Note that the emitter may ignore any stylistic
446 * hints.
447 */
448
[238]449typedef enum yaml_mapping_style_e {
[266]450    /* Let the emitter choose the style. */
[169]451    YAML_ANY_MAPPING_STYLE,
[183]452
[266]453    /* The block mapping style. */
[162]454    YAML_BLOCK_MAPPING_STYLE,
[266]455    /* The flow mapping style. */
[213]456    YAML_FLOW_MAPPING_STYLE
[162]457} yaml_mapping_style_t;
458
[267]459/*****************************************************************************
[266]460 * Tokens
[267]461 *****************************************************************************/
[183]462
[266]463/*
464 * Token types.
465 *
466 * The LibYAML scanner generates the following types of tokens:
467 *
468 * - STREAM-START: indicates the beginning of the stream.
469 *
470 * - STREAM-END: indicates the end of the stream.
471 *
472 * - VERSION-DIRECTIVE: describes the `%YAML` directive.
473 *
474 * - TAG-DIRECTIVE: describes the `%TAG` directive.
475 *
476 * - DOCUMENT-START: the indicator `---`.
477 *
478 * - DOCUMENT-END: the indicator `...`.
479 *
480 * - BLOCK-SEQUENCE-START: indentation increase indicating the beginning of a
481 *   block sequence node.
482 *
483 * - BLOCK-MAPPING-START: indentation increase indicating the beginning of a
484 *   block mapping node.
485 *
486 * - BLOCK-END: indentation decrease indicating the end of a block collection
487 *   node.
488 *
489 * - FLOW-SEQUENCE-START: the indicator `[`.
490 *
491 * - FLOW-SEQUENCE-END: the indicator `]`.
492 *
493 * - FLOW-MAPPING-START: the indicator `{`.
494 *
495 * - FLOW-MAPPING-END: the indicator `}`.
496 *
497 * - BLOCK-ENTRY: the beginning of an item of a block sequence.
498 *
499 * - FLOW-ENTRY: the beginning of an item of a flow sequence.
500 *
501 * - KEY: the beginning of a simple key, or the indicator `?`.
502 *
503 * - VALUE: the indicator `:`.
504 *
505 * - ALIAS: an alias of a node.
506 *
507 * - ANCHOR: a node anchor.
508 *
509 * - TAG: a node tag.
510 *
511 * - SCALAR: the content of a scalar node.
[183]512 */
513
[238]514typedef enum yaml_token_type_e {
[266]515    /* An empty unitialized token. */
[208]516    YAML_NO_TOKEN,
517
[266]518    /* A STREAM-START token. */
[162]519    YAML_STREAM_START_TOKEN,
[266]520    /* A STREAM-END token. */
[162]521    YAML_STREAM_END_TOKEN,
[169]522
[266]523    /* A VERSION-DIRECTIVE token. */
[162]524    YAML_VERSION_DIRECTIVE_TOKEN,
[266]525    /* A TAG-DIRECTIVE token. */
[162]526    YAML_TAG_DIRECTIVE_TOKEN,
[266]527    /* A DOCUMENT-START token. */
[162]528    YAML_DOCUMENT_START_TOKEN,
[266]529    /* A DOCUMENT-END token. */
[162]530    YAML_DOCUMENT_END_TOKEN,
[169]531
[266]532    /* A BLOCK-SEQUENCE-START token. */
[162]533    YAML_BLOCK_SEQUENCE_START_TOKEN,
[266]534    /* A BLOCK-SEQUENCE-END token. */
[162]535    YAML_BLOCK_MAPPING_START_TOKEN,
[266]536    /* A BLOCK-END token. */
[162]537    YAML_BLOCK_END_TOKEN,
[169]538
[266]539    /* A FLOW-SEQUENCE-START token. */
[162]540    YAML_FLOW_SEQUENCE_START_TOKEN,
[266]541    /* A FLOW-SEQUENCE-END token. */
[162]542    YAML_FLOW_SEQUENCE_END_TOKEN,
[266]543    /* A FLOW-MAPPING-START token. */
[162]544    YAML_FLOW_MAPPING_START_TOKEN,
[266]545    /* A FLOW-MAPPING-END token. */
[162]546    YAML_FLOW_MAPPING_END_TOKEN,
[169]547
[266]548    /* A BLOCK-ENTRY token. */
[162]549    YAML_BLOCK_ENTRY_TOKEN,
[266]550    /* A FLOW-ENTRY token. */
[162]551    YAML_FLOW_ENTRY_TOKEN,
[266]552    /* A KEY token. */
[162]553    YAML_KEY_TOKEN,
[266]554    /* A VALUE token. */
[162]555    YAML_VALUE_TOKEN,
[169]556
[266]557    /* An ALIAS token. */
[162]558    YAML_ALIAS_TOKEN,
[266]559    /* An ANCHOR token. */
[162]560    YAML_ANCHOR_TOKEN,
[266]561    /* A TAG token. */
[162]562    YAML_TAG_TOKEN,
[266]563    /* A SCALAR token. */
[162]564    YAML_SCALAR_TOKEN
565} yaml_token_type_t;
566
[266]567/*
568 * The token object.
569 *
570 * Typically the token API is too low-level to be used directly by
571 * applications.  A possible user of the token API is a syntax highlighting
572 * application.
573 */
574
[238]575typedef struct yaml_token_s {
[169]576
[266]577    /* The token type. */
[183]578    yaml_token_type_t type;
[169]579
[266]580    /* The token data. */
[183]581    union {
[169]582
[266]583        /* Extra data associated with a STREAM-START token. */
[199]584        struct {
[266]585            /* The stream encoding. */
[199]586            yaml_encoding_t encoding;
587        } stream_start;
[169]588
[266]589        /* Extra data associated with a VERSION-DIRECTIVE token. */
[261]590        struct {
[266]591            /* The major version number. */
[261]592            int major;
[266]593            /* The minor version number. */
[261]594            int minor;
595        } version_directive;
596
[266]597        /* Extra data associated with a TAG-DIRECTIVE token. */
[261]598        struct {
[266]599            /* The tag handle. */
[261]600            yaml_char_t *handle;
[266]601            /* The tag prefix. */
[261]602            yaml_char_t *prefix;
603        } tag_directive;
604
[266]605        /* Extra data associated with an ALIAS token. */
[199]606        struct {
[266]607            /* The alias value. */
[199]608            yaml_char_t *value;
609        } alias;
[162]610
[266]611        /* Extra data associated with an ANCHOR token. */
[199]612        struct {
[266]613            /* The anchor value. */
[199]614            yaml_char_t *value;
615        } anchor;
616
[266]617        /* Extra data associated with a TAG token. */
[183]618        struct {
[266]619            /* The tag handle. */
[183]620            yaml_char_t *handle;
[266]621            /* The tag suffix. */
[183]622            yaml_char_t *suffix;
623        } tag;
[162]624
[266]625        /* Extra data associated with a SCALAR token. */
[162]626        struct {
[266]627            /* The scalar value. */
[183]628            yaml_char_t *value;
[266]629            /* The length of the scalar value. */
[169]630            size_t length;
[266]631            /* The scalar style. */
[162]632            yaml_scalar_style_t style;
633        } scalar;
[183]634
[162]635    } data;
[183]636
[266]637    /* The beginning of the token. */
[162]638    yaml_mark_t start_mark;
[266]639    /* The end of the token. */
[162]640    yaml_mark_t end_mark;
[183]641
[162]642} yaml_token_t;
643
[266]644/*
[261]645 * Allocate a new empty token object.
[183]646 *
[266]647 * A token object allocated using this function must be deleted with
648 * `yaml_token_delete()`.
649 *
650 * Returns: a new empty token object or `NULL` on error.  The function may fail
651 * if it cannot allocate memory for a new token object.
[261]652 */
653
654YAML_DECLARE(yaml_token_t *)
655yaml_token_new(void);
656
[266]657/*
658 * Deallocate a token object and free the associated data.
[261]659 *
[266]660 * A token object must be previously allocated with `yaml_token_new()`.
661 *
662 * Arguments:
663 *
664 * - `token`: a token object to be deallocated.
[183]665 */
666
667YAML_DECLARE(void)
668yaml_token_delete(yaml_token_t *token);
669
[266]670/*
[261]671 * Duplicate a token object.
672 *
[266]673 * This function creates a deep copy of an existing token object.  It accepts
674 * two token objects: an empty token and a model token.  The latter is supposed
675 * to be initialized with `yaml_parser_parse_token()`.  The function assigns
676 * the type of the model to the empty token as well as duplicates and copies
677 * the internal state associated with the model token.
[261]678 *
[266]679 * Arguments:
680 *
681 * - `token`: an empty token object.
682 *
683 * - `model`: a token to be copied.
684 *
685 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
686 * allocate memory for duplicating the state of the model token.  In that case,
687 * the token remains empty.
[261]688 */
689
690YAML_DECLARE(int)
[264]691yaml_token_duplicate(yaml_token_t *token, const yaml_token_t *model);
[261]692
[266]693/*
694 * Clear the token state.
[261]695 *
[266]696 * This function clears the type and the internal state of a token object
697 * freeing any associated data.  After applying this function to a token, it
698 * becomes empty.  It is supposed that the token was previously initialized
699 * using `yaml_parser_parse_token()` or `yaml_token_duplicate()`.
700 *
701 * Arguments:
702 *
703 * - `token`: a token object.
[261]704 */
705
706YAML_DECLARE(void)
[266]707yaml_token_clear(yaml_token_t *token);
[261]708
[267]709/*****************************************************************************
[266]710 * Events
[267]711 *****************************************************************************/
[183]712
[266]713/*
714 * Event types.
715 *
716 * The LibYAML parser generates, while the LibYAML emitter accepts, YAML events
717 * of the following types:
718 *
719 * - STREAM-START: indicates the beginning of the stream.
720 *
721 * - STREAM-END: indicates the end of the stream.
722 *
723 * - DOCUMENT-START: indicates the beginning of the document.
724 *
725 * - DOCUMENT-END: indicates the end of the document.
726 *
727 * - ALIAS: an alias to an already produced node.
728 *
729 * - SCALAR: a scalar node.
730 *
731 * - SEQUENCE-START: indicates the beginning of a sequence node.
732 *
733 * - SEQUENCE-END: indicates the end of a sequence node.
734 *
735 * - MAPPING-START: indicates the beginning of a mapping node.
736 *
737 * - MAPPING-END: indicates the end of a mapping node.
738 *
739 * A valid sequence of events obeys the grammar:
740 *
741 *      stream ::= STREAM-START document* STREAM-END
742 *      document ::= DOCUMENT-START node DOCUMENT-END
743 *      node ::= ALIAS | SCALAR | sequence | mapping
744 *      sequence ::= SEQUENCE-START node* SEQUENCE-END
745 *      mapping ::= MAPPING-START (node node)* MAPPING-END
[199]746 */
[183]747
[238]748typedef enum yaml_event_type_e {
[266]749    /* An empty unitialized event. */
[208]750    YAML_NO_EVENT,
751
[266]752    /* A STREAM-START event. */
[183]753    YAML_STREAM_START_EVENT,
[266]754    /* A STREAM-END event. */
[183]755    YAML_STREAM_END_EVENT,
756
[266]757    /* A DOCUMENT-START event. */
[183]758    YAML_DOCUMENT_START_EVENT,
[266]759    /* A DOCUMENT-END event. */
[183]760    YAML_DOCUMENT_END_EVENT,
761
[266]762    /* An ALIAS event. */
[183]763    YAML_ALIAS_EVENT,
[266]764    /* A SCALAR event. */
[183]765    YAML_SCALAR_EVENT,
766
[266]767    /* A SEQUENCE-START event. */
[183]768    YAML_SEQUENCE_START_EVENT,
[266]769    /* A SEQUENCE-END event. */
[183]770    YAML_SEQUENCE_END_EVENT,
771
[266]772    /* A MAPPING-START event. */
[183]773    YAML_MAPPING_START_EVENT,
[266]774    /* A MAPPING-END event. */
[183]775    YAML_MAPPING_END_EVENT
776} yaml_event_type_t;
777
[266]778/*
779 * The event object.
780 *
781 * The event-level API of LibYAML should be used for streaming applications.
782 */
783
[238]784typedef struct yaml_event_s {
[199]785
[266]786    /* The event type. */
[162]787    yaml_event_type_t type;
[199]788
[266]789    /* The event data. */
[162]790    union {
[199]791       
[266]792        /* The stream parameters (for `YAML_STREAM_START_EVENT`). */
[162]793        struct {
[266]794            /* The document encoding. */
[162]795            yaml_encoding_t encoding;
796        } stream_start;
[199]797
[266]798        /* The document parameters (for `YAML_DOCUMENT_START_EVENT`). */
[162]799        struct {
[266]800            /* The version directive or `NULL` if not present. */
[199]801            yaml_version_directive_t *version_directive;
[208]802
[266]803            /* The list of tag directives. */
[208]804            struct {
[266]805                /* The beginning of the list or `NULL`. */
[261]806                yaml_tag_directive_t *list;
[266]807                /* The length of the list. */
[261]808                size_t length;
[266]809                /* The capacity of the list (used internally). */
[261]810                size_t capacity;
[208]811            } tag_directives;
812
[266]813            /* Set if the document indicator is omitted. */
[261]814            int is_implicit;
[162]815        } document_start;
[199]816
[266]817        /* The document end parameters (for `YAML_DOCUMENT_END_EVENT`). */
[162]818        struct {
[266]819            /* Set if the document end indicator is omitted. */
[261]820            int is_implicit;
[162]821        } document_end;
[199]822
[266]823        /* The alias parameters (for `YAML_ALIAS_EVENT`). */
[162]824        struct {
[266]825            /* The anchor. */
[199]826            yaml_char_t *anchor;
[162]827        } alias;
[199]828
[266]829        /* The scalar parameters (for `YAML_SCALAR_EVENT`). */
[162]830        struct {
[266]831            /* The node anchor or `NULL`. */
[199]832            yaml_char_t *anchor;
[266]833            /* The node tag or `NULL`. */
[199]834            yaml_char_t *tag;
[266]835            /* The scalar value. */
[199]836            yaml_char_t *value;
[266]837            /* The length of the scalar value (in bytes). */
[169]838            size_t length;
[266]839            /* Set if the tag is optional for the plain style. */
840            int is_plain_nonspecific;
841            /* Set if the tag is optional for any non-plain style. */
842            int is_quoted_nonspecific;
843            /* The scalar style. */
[162]844            yaml_scalar_style_t style;
845        } scalar;
[199]846
[266]847        /* The sequence parameters (for `YAML_SEQUENCE_START_EVENT`). */
[162]848        struct {
[266]849            /* The node anchor or `NULL`. */
[199]850            yaml_char_t *anchor;
[266]851            /* The node tag or `NULL`. */
[199]852            yaml_char_t *tag;
[266]853            /* Set if the tag is optional. */
854            int is_nonspecific;
855            /* The sequence style. */
[162]856            yaml_sequence_style_t style;
857        } sequence_start;
[199]858
[266]859        /* The mapping parameters (for `YAML_MAPPING_START_EVENT`). */
[162]860        struct {
[266]861            /* The node anchor or `NULL`. */
[199]862            yaml_char_t *anchor;
[266]863            /* The node tag or `NULL`. */
[199]864            yaml_char_t *tag;
[266]865            /* Set if the tag is optional. */
866            int is_nonspecific;
867            /* The mapping style. */
[162]868            yaml_mapping_style_t style;
869        } mapping_start;
[199]870
[162]871    } data;
[199]872
[266]873    /* The beginning of the event. */
[162]874    yaml_mark_t start_mark;
[266]875    /* The end of the event. */
[162]876    yaml_mark_t end_mark;
[208]877
[162]878} yaml_event_t;
879
[266]880/*
[261]881 * Allocate a new empty event object.
[213]882 *
[266]883 * An event object allocated using this function must be deleted with
884 * `yaml_event_delete()`.
885 *
886 * Returns: a new empty event object or `NULL` on error.  The function may fail
887 * if it cannot allocate memory for a new event object.
[261]888 */
889
890YAML_DECLARE(yaml_event_t *)
891yaml_event_new(void);
892
[266]893/*
894 * Deallocate an event object and free the associated data.
[261]895 *
[266]896 * An event object must be previously allocated with `yaml_event_new()`.
897 *
898 * Arguments:
899 *
900 * - `event`: an event object to be deallocated.
[261]901 */
902
903YAML_DECLARE(void)
904yaml_event_delete(yaml_event_t *event);
905
[266]906/*
907 * Duplicate an event object.
[261]908 *
[266]909 * This function creates a deep copy of an existing event object.  It accepts
910 * two objects: an empty event and a model event.  The model event is supposed
911 * to be initialized either with `yaml_parser_parse_event()` or using one of
912 * the functions `yaml_event_create_*()`.  The function assigns the type of the
913 * model to the empty event and copies the internal state associated with the
914 * model event.
[261]915 *
[266]916 * Arguments:
917 *
918 * - `event`: an empty event object.
919 *
920 * - `model`: an event to be copied.
921 *
922 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
923 * allocate memory for duplicating the state of the model event.  In that case,
924 * the event remains empty.
[261]925 */
926
927YAML_DECLARE(int)
[264]928yaml_event_duplicate(yaml_event_t *event, const yaml_event_t *model);
[261]929
[266]930/*
931 * Clear the event state.
932 *
933 * This function clears the type and the internal state of an event object
934 * freeing any associated data.  After applying this function to an event, it
935 * becomes empty.  It is supposed that the event was previously initialized
936 * using `yaml_parser_parse_event()` or `yaml_event_duplicate()`.  Note that
937 * the function `yaml_emitter_emit_event()` also clears the given event.
938 *
939 * Arguments:
940 *
941 * - `event`: an event object.
942 */
943
944YAML_DECLARE(void)
945yaml_event_clear(yaml_event_t *event);
946
947/*
[261]948 * Create a STREAM-START event.
949 *
[266]950 * This function initializes an empty event object allocated with
951 * `yaml_event_new()`.  The initialized event could be fed to
952 * `yaml_emitter_emit_event()`.
[261]953 *
[266]954 * Arguments:
[213]955 *
[266]956 * - `event`: an empty event object.
957 *
958 * - `encoding`: the stream encoding.
959 *
960 * Returns: `1`.  The function never fails.
[213]961 */
962
963YAML_DECLARE(int)
[261]964yaml_event_create_stream_start(yaml_event_t *event,
[213]965        yaml_encoding_t encoding);
966
[266]967/*
[261]968 * Create a STREAM-END event.
[213]969 *
[266]970 * This function initializes an empty event object allocated with
971 * `yaml_event_new()`.  The initialized event could be fed to
972 * `yaml_emitter_emit_event()`.
[261]973 *
[266]974 * Arguments:
[213]975 *
[266]976 * - `event`: an empty event object.
977 *
978 * Returns: `1`.  The function never fails.
[213]979 */
980
981YAML_DECLARE(int)
[261]982yaml_event_create_stream_end(yaml_event_t *event);
[213]983
[266]984/*
985 * Create a DOCUMENT-START event.
[213]986 *
[266]987 * This function initializes an empty event object allocated with
988 * `yaml_event_new()`.  The initialized event could be fed to
989 * `yaml_emitter_emit_event()`.
[213]990 *
[266]991 * Arguments:
992 *
993 * - `event`: an empty event object.
994 *
995 * - `version_directive`: a structure specifying the content of the `%YAML`
996 *   directive or `NULL` if the directive could be omitted.  Note that LibYAML
997 *   supports YAML 1.1 only.  The function does not check if the supplied
998 *   version equals to 1.1, but the emitter will fail to emit the event if it
999 *   is not so.
1000 *
1001 * - `tag_directives_list`: a pointer to a list specifying the content of the
1002 *   `%TAG` directives associated with the document or `NULL` if the document
1003 *   does not contain `%TAG` directives.  The content of a tag directive is a
1004 *   pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings.  The tag
1005 *   handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_`
1006 *   and `-` surrounded by `!`.  The tag prefix is a prefix of any valid tag,
1007 *   that is, it is a non-empty prefix of either a global tag (a valid URI) or
1008 *   a local tag (an arbitrary string starting with `!`).  The function does
1009 *   not check if the given directive values satisfy these requirements, but
1010 *   the emitter will fail to emit the event if they are not met.
1011 *
1012 * - `tag_directives_length`: the length of `tag_directives_list`; `0` if
1013 *   `tag_directives_list` is `NULL`.
1014 *
1015 * - `is_implicit`: `1` if the document indicator `---` is omitted, `0`
1016 *   otherwise.  Note that this attribute is only a stylistic hint and could be
1017 *   ignored by the emitter.
1018 *
1019 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1020 * allocate memory for duplicating the event parameters.  In this case, the
1021 * event remains empty.
[213]1022 */
1023
1024YAML_DECLARE(int)
[261]1025yaml_event_create_document_start(yaml_event_t *event,
1026        const yaml_version_directive_t *version_directive,
[266]1027        const yaml_tag_directive_t *tag_directives_list,
1028        size_t tag_directives_length,
[261]1029        int is_implicit);
[213]1030
[266]1031/*
1032 * Create a DOCUMENT-END event.
[213]1033 *
[266]1034 * This function initializes an empty event object allocated with
1035 * `yaml_event_new()`.  The initialized event could be fed to
1036 * `yaml_emitter_emit_event()`.
[213]1037 *
[266]1038 * Arguments:
1039 *
1040 * - `event`: an empty event object.
1041 *
1042 * - `is_implicit`: `1` if the document end indicator `...` is omitted, `0`
1043 *   otherwise.  Note that this attribute is only a stylistic hint and could be
1044 *   ignored by the emitter.
1045 *
1046 * Returns: `1`.  The function never fails.
[213]1047 */
1048
1049YAML_DECLARE(int)
[261]1050yaml_event_create_document_end(yaml_event_t *event, int is_implicit);
[213]1051
[266]1052/*
1053 * Create an ANCHOR event.
[213]1054 *
[266]1055 * This function initializes an empty event object allocated with
1056 * `yaml_event_new()`.  The initialized event could be fed to
1057 * `yaml_emitter_emit_event()`.
[213]1058 *
[266]1059 * Arguments:
1060 *
1061 * - `event`: an empty event object.
1062 *
1063 * - `anchor`: the anchor value.  The anchor should be a non-empty
1064 *   NUL-terminated string containing only alphanumerical characters, `_`, and
1065 *   `-`.  The function does not check if this requirement is satisfied, but if
1066 *   it is not so, the emitter will fail to emit the generated event.
1067 *
1068 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1069 * allocate memory for duplicating `anchor`.  In this case, the event remains
1070 * empty.
[213]1071 */
1072
1073YAML_DECLARE(int)
[261]1074yaml_event_create_alias(yaml_event_t *event, const yaml_char_t *anchor);
[213]1075
[266]1076/*
[213]1077 * Create a SCALAR event.
1078 *
[266]1079 * This function initializes an empty event object allocated with
1080 * `yaml_event_new()`.  The initialized event could be fed to
1081 * `yaml_emitter_emit_event()`.
[213]1082 *
[266]1083 * Arguments:
1084 *
1085 * - `event`: an empty event object.
1086 *
1087 * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty
1088 *   NUL-terminated string containing only alphanumerical characters, `_`, and
1089 *   `-`.
1090 *
1091 * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8
1092 *   NUL-terminated string.  The tag could be global (a valid URI) or local (an
1093 *   arbitrary string starting with `!`).  If `NULL` is provided, at least one
1094 *   of the flags `is_plain_nonspecific` and `is_quoted_nonspecific` must be
1095 *   set.  The function does not check whether these requirements are
1096 *   satisfied, but the emitter will fail to emit the event if it is not so.
1097 *
1098 * - `value`: the value of the scalar node.  The value should be a UTF-8
1099 *   string.  It could contain any valid UTF-8 character including NUL.  The
1100 *   function does not check if `value` is a valid UTF-8 string, but the
1101 *   emitter will fail to emit the event if it is not so.
1102 *
1103 * - `length`: the length of the scalar value (in bytes) or `-1`.  If `length`
1104 *   is set to `-1`, the `value` is assumed to be NUL-terminated.
1105 *
1106 * - `is_plain_nonspecific`: `1` if the node tag could be omitted while
1107 *   emitting the node provided that the the plain style is used for
1108 *   representing the node value; `0` otherwise.  That this flag is set assumes
1109 *   that the tag could be correctly determined by the parser using the node
1110 *   position and content.
1111 *
1112 * - `is_quoted_nonspecific`: `1` if the node tag could be omitted while
1113 *   emitting the node provided that the node value is represented using any
1114 *   non-plain style; `0` otherwise.  That this flag is set assumes that the
1115 *   tag could be correctly determined by the parser using the node position
1116 *   and content.
1117 *
1118 * - `style`: the node style.  Note that this attribute only serves as a hint
1119 *   and may be ignored by the emitter.
1120 *
1121 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1122 * allocate memory for duplicating the given string buffers.  In this case, the
1123 * event remains empty.
[213]1124 */
1125
1126YAML_DECLARE(int)
[261]1127yaml_event_create_scalar(yaml_event_t *event,
1128        const yaml_char_t *anchor, const yaml_char_t *tag,
[266]1129        const yaml_char_t *value, int length,
1130        int is_plain_nonspecific, int is_quoted_nonspecific,
[213]1131        yaml_scalar_style_t style);
1132
[266]1133/*
[213]1134 * Create a SEQUENCE-START event.
1135 *
[266]1136 * This function initializes an empty event object allocated with
1137 * `yaml_event_new()`.  The initialized event could be fed to
1138 * `yaml_emitter_emit_event()`.
[213]1139 *
[266]1140 * Arguments:
1141 *
1142 * - `event`: an empty event object.
1143 *
1144 * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty
1145 *   NUL-terminated string containing only alphanumerical characters, `_`, and
1146 *   `-`.  The function does not check if this requirement is satisfied, but if
1147 *   it is not so, the emitter will fail to emit the generated event.
1148 *
1149 * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8
1150 *   NUL-terminated string.  The tag could be global (a valid URI) or local (an
1151 *   arbitrary string starting with `!`).  If `NULL` is provided, the flag
1152 *   `is_nonspecific` must be set.  The function does not check whether these
1153 *   requirements are satisfied, but if it is not so, the emitter will fail to
1154 *   emit the generated event.
1155 *
1156 * - `is_nonspecific`: `1` if the node tag could be omitted while
1157 *   emitting the node; `0` otherwise.  This flag should only be set if the
1158 *   node tag could be correctly determined by the parser using the node
1159 *   position in the document graph.
1160 *
1161 * - `style`: the node style.  Note that this attribute only serves as a hint
1162 *   and may be ignored by the emitter.
1163 *
1164 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1165 * allocate memory for duplicating the given string buffers.  In this case, the
1166 * event remains empty.
[213]1167 */
1168
1169YAML_DECLARE(int)
[261]1170yaml_event_create_sequence_start(yaml_event_t *event,
1171        const yaml_char_t *anchor, const yaml_char_t *tag,
[266]1172        int is_nonspecific, yaml_sequence_style_t style);
[213]1173
[266]1174/*
[213]1175 * Create a SEQUENCE-END event.
1176 *
[266]1177 * This function initializes an empty event object allocated with
1178 * `yaml_event_new()`.  The initialized event could be fed to
1179 * `yaml_emitter_emit_event()`.
[213]1180 *
[266]1181 * Arguments:
1182 *
1183 * - `event`: an empty event object.
1184 *
1185 * Returns: `1`.  This function never fails.
[213]1186 */
1187
1188YAML_DECLARE(int)
[261]1189yaml_event_create_sequence_end(yaml_event_t *event);
[213]1190
[266]1191/*
[213]1192 * Create a MAPPING-START event.
1193 *
[266]1194 * This function initializes an empty event object allocated with
1195 * `yaml_event_new()`.  The initialized event could be fed to
1196 * `yaml_emitter_emit_event()`.
[213]1197 *
[266]1198 * Arguments:
1199 *
1200 * - `event`: an empty event object.
1201 *
1202 * - `anchor`: the anchor value or `NULL`.  The anchor should be a non-empty
1203 *   NUL-terminated string containing only alphanumerical characters, `_`, and
1204 *   `-`.  The function does not check if this requirement is satisfied, but if
1205 *   it is not so, the emitter will fail to emit the generated event.
1206 *
1207 * - `tag`: the tag value or `NULL`.  The tag should be a non-empty UTF-8
1208 *   NUL-terminated string.  The tag could be global (a valid URI) or local (an
1209 *   arbitrary string starting with `!`).  If `NULL` is provided, the flag
1210 *   `is_nonspecific` must be set.  The function does not check whether these
1211 *   requirements are satisfied, but if it is not so, the emitter will fail to
1212 *   emit the generated event.
1213 *
1214 * - `is_nonspecific`: `1` if the node tag could be omitted while
1215 *   emitting the node; `0` otherwise.  This flag should only be set if the
1216 *   node tag could be correctly determined by the parser using the node
1217 *   position in the document graph.
1218 *
1219 * - `style`: the node style.  Note that this attribute only serves as a hint
1220 *   and may be ignored by the emitter.
1221 *
1222 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1223 * allocate memory for duplicating the given string buffers.  In this case, the
1224 * event remains empty.
[213]1225 */
1226
1227YAML_DECLARE(int)
[261]1228yaml_event_create_mapping_start(yaml_event_t *event,
1229        const yaml_char_t *anchor, const yaml_char_t *tag,
[266]1230        int is_nonspecific, yaml_mapping_style_t style);
[213]1231
[266]1232/*
[213]1233 * Create a MAPPING-END event.
1234 *
[266]1235 * This function initializes an empty event object allocated with
1236 * `yaml_event_new()`.  The initialized event could be fed to
1237 * `yaml_emitter_emit_event()`.
[213]1238 *
[266]1239 * Arguments:
1240 *
1241 * - `event`: an empty event object.
1242 *
1243 * Returns: `1`.  This function never fails.
[213]1244 */
1245
1246YAML_DECLARE(int)
[261]1247yaml_event_create_mapping_end(yaml_event_t *event);
[213]1248
[267]1249/*****************************************************************************
[266]1250 * Documents and Nodes
[267]1251 *****************************************************************************/
[199]1252
[266]1253/*
1254 * Well-known scalar tags.
[237]1255 */
1256
[264]1257#define YAML_NULL_TAG       ((const yaml_char_t *) "tag:yaml.org,2002:null")
1258#define YAML_BOOL_TAG       ((const yaml_char_t *) "tag:yaml.org,2002:bool")
1259#define YAML_STR_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:str")
1260#define YAML_INT_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:int")
1261#define YAML_FLOAT_TAG      ((const yaml_char_t *) "tag:yaml.org,2002:float")
[237]1262
[266]1263/*
1264 * Basic collection tags.
1265 */
1266
[264]1267#define YAML_SEQ_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:seq")
1268#define YAML_MAP_TAG        ((const yaml_char_t *) "tag:yaml.org,2002:map")
[237]1269
[266]1270/*
1271 * The default tags for nodes lacking an explicit tag.
1272 */
1273
[237]1274#define YAML_DEFAULT_SCALAR_TAG     YAML_STR_TAG
1275#define YAML_DEFAULT_SEQUENCE_TAG   YAML_SEQ_TAG
[238]1276#define YAML_DEFAULT_MAPPING_TAG    YAML_MAP_TAG
[237]1277
[266]1278/*
1279 * Document types.
1280 *
1281 * There are no different document types in LibYAML: the document type field is
1282 * only used to distinguish between newly allocated documents and those that
1283 * are initialized with `yaml_parser_parse_document()` or
1284 * `yaml_document_create()`.
1285 */
1286
1287typedef enum yaml_document_type_e {
1288    /* An empty uninitialized document. */
[267]1289    YAML_NO_DOCUMENT,
[266]1290
1291    /* A YAML document. */
1292    YAML_DOCUMENT
1293} yaml_document_type_t;
1294
1295/*
1296 * Node types.
1297 *
1298 * YAML recognizes three kinds of nodes: scalar, sequence and mapping.
1299 */
1300
[238]1301typedef enum yaml_node_type_e {
[266]1302    /* An empty node. */
[237]1303    YAML_NO_NODE,
1304
[266]1305    /* A scalar node. */
[237]1306    YAML_SCALAR_NODE,
[266]1307    /* A sequence node. */
[237]1308    YAML_SEQUENCE_NODE,
[266]1309    /* A mapping node. */
[237]1310    YAML_MAPPING_NODE
1311} yaml_node_type_t;
1312
[266]1313/*
1314 * Arc types.
1315 *
1316 * Arcs are used to specify the path from the root node to a given node in the
1317 * document graph.  There are three kinds of arcs: an item in a sequence node,
1318 * a key in a mapping node, and a value in a mapping node.
1319 */
1320
[261]1321typedef enum yaml_arc_type_e {
[266]1322    /* An empty arc. */
[261]1323    YAML_NO_ARC,
1324
[266]1325    /* An item of a sequence. */
[261]1326    YAML_SEQUENCE_ITEM_ARC,
[266]1327    /* A key of a mapping. */
[261]1328    YAML_MAPPING_KEY_ARC,
[266]1329    /* A value of a mapping. */
[261]1330    YAML_MAPPING_VALUE_ARC
1331} yaml_arc_type_t;
1332
[266]1333/*
1334 * An element of a sequence node.
1335 */
[237]1336
[238]1337typedef int yaml_node_item_t;
[237]1338
[266]1339/*
1340 * An element of a mapping node.
1341 */
1342
[238]1343typedef struct yaml_node_pair_s {
[266]1344    /* A key in a mapping. */
[238]1345    int key;
[266]1346    /* A value in a mapping. */
[238]1347    int value;
[237]1348} yaml_node_pair_t;
1349
[266]1350/*
1351 * A path element.
1352 *
1353 * An arc is an element of a path from the root node to some other node in a
1354 * YAML document.  An arc consists of a collection node and information on how
1355 * it is connected to the next node in the path.  If the arc type is a sequence
1356 * item, then the collection node is a sequence and the arc refers to the index
1357 * in this sequence.  If the arc type is a mapping key, then the collection
1358 * node is a mapping.  If the arc type is a mapping value, then the collection
1359 * node is a mapping and the arc refers to the key associated to the value.
1360 */
1361
[261]1362typedef struct yaml_arc_s {
[266]1363
1364    /* The arc type. */
[261]1365    yaml_arc_type_t type;
[266]1366
1367    /* The tag of the collection node. */
1368    yaml_char_t *tag;
1369
1370    /* The connection information. */
1371    union {
1372
1373        /* The sequence item data (for `YAML_SEQUENCE_ITEM_ARC`). */
1374        struct {
1375            /* The index of the item in the sequence (starting from `0`). */
1376            int index;
1377        } item;
1378
1379        /* The mapping value data (for `YAML_MAPPING_VALUE_ARC`). */
1380        struct {
1381            /* The key associated with the value. */
1382            struct {
1383                /* The key node type. */
1384                yaml_node_type_t type;
1385                /* The key node tag. */
1386                yaml_char_t *tag;
1387                /* The key node details. */
1388                union {
1389                    /* The scalar data (for a scalar key). */
1390                    struct {
1391                        /* The scalar value. */
1392                        yaml_char_t *value;
1393                        /* The scalar length. */
1394                        size_t length;
1395                    } scalar;
1396                } data;
1397            } key;
1398        } value;
1399    } data;
[261]1400} yaml_arc_t;
1401
[266]1402/*
1403 * The node object.
1404 *
1405 * A node object represents a node in a YAML document graph.  Node objects are
1406 * created using the family of functions `yaml_document_add_*()`.  Links
1407 * between nodes are created using the functions `yaml_document_append_*()`. A
1408 * node object is destroyed when the document containing it is destroyed.
1409 */
1410
[267]1411typedef struct yaml_node_s {
[237]1412
[266]1413    /* The node type. */
[237]1414    yaml_node_type_t type;
1415
[266]1416    /* The node anchor or `NULL`. */
[261]1417    yaml_char_t *anchor;
[266]1418    /* The node tag. */
[238]1419    yaml_char_t *tag;
[237]1420
[266]1421    /* The node data. */
[237]1422    union {
1423       
[266]1424        /* The scalar parameters (for `YAML_SCALAR_NODE`). */
[237]1425        struct {
[266]1426            /* The scalar value. */
[237]1427            yaml_char_t *value;
[266]1428            /* The length of the scalar value. */
[237]1429            size_t length;
[266]1430            /* The scalar style. */
[237]1431            yaml_scalar_style_t style;
1432        } scalar;
1433
[266]1434        /* The sequence parameters (for `YAML_SEQUENCE_NODE`). */
[237]1435        struct {
[266]1436            /* The list of sequence items. */
[237]1437            struct {
[266]1438                /* The pointer to the beginning of the list. */
[261]1439                yaml_node_item_t *list;
[266]1440                /* The length of the list. */
[261]1441                size_t length;
[266]1442                /* The capacity of the list (used internally). */
[261]1443                size_t capacity;
[237]1444            } items;
[266]1445            /* The sequence style. */
[237]1446            yaml_sequence_style_t style;
1447        } sequence;
1448
[266]1449        /* The mapping parameters (for `YAML_MAPPING_NODE`). */
[237]1450        struct {
[266]1451            /* The list of mapping pairs (key, value). */
[237]1452            struct {
[266]1453                /** The pointer to the beginning of the list. */
[261]1454                yaml_node_pair_t *list;
[266]1455                /* The length of the list. */
[261]1456                size_t length;
[266]1457                /* The capacity of the list (used internally). */
[261]1458                size_t capacity;
[237]1459            } pairs;
[266]1460            /* The mapping style. */
[237]1461            yaml_mapping_style_t style;
1462        } mapping;
1463
1464    } data;
1465
[266]1466    /* The beginning of the node. */
[237]1467    yaml_mark_t start_mark;
[266]1468    /* The end of the node. */
[237]1469    yaml_mark_t end_mark;
1470
[267]1471} yaml_node_t;
[237]1472
[266]1473/*
1474 * The incomplete node object.
1475 *
1476 * This structure provides the information about a node that a tag resolver
1477 * could use to determine the specific node tag.  This information includes
1478 * the path from the root node and the node content for scalar nodes.
1479 */
1480
[261]1481typedef struct yaml_incomplete_node_s {
1482
[266]1483    /* The node type. */
[261]1484    yaml_node_type_t type;
1485
[266]1486    /* The path to the new node. */
[261]1487    struct {
[266]1488        /* The pointer to the beginning of the list. */
[261]1489        yaml_arc_t *list;
[266]1490        /* The length of the list. */
[261]1491        size_t length;
[266]1492        /* The capacity of the list (used internally). */
[261]1493        size_t capacity;
1494    } path;
1495
[266]1496    /* The node data. */
[261]1497    union {
1498
[266]1499        /* The scalar parameters (for `YAML_SCALAR_NODE`). */
[261]1500        struct {
[266]1501            /* The scalar value. */
[261]1502            yaml_char_t *value;
[266]1503            /* The length of the scalar value. */
[261]1504            size_t length;
[266]1505            /* Set if the scalar is plain. */
[261]1506            int is_plain;
1507        } scalar;
1508
1509    } data;
1510
[266]1511    /* The position of the node. */
[261]1512    yaml_mark_t mark;
1513
1514} yaml_incomplete_node_t;
1515
[266]1516/*
1517 * The document object.
1518 *
1519 * A document object represents the main structure of the YAML object model:
1520 * the document graph consisting of nodes of three kinds: scalars, sequences,
1521 * and mappings with the selected root node.
1522 *
1523 * An empty document object is allocated using the function
1524 * `yaml_document_new()`.  Then the function `yaml_parser_parse_document()`
1525 * could be used to load a YAML document from the input stream.  Alternatively,
1526 * a document could be created with `yaml_document_create()` and its content
1527 * could be specified using the families of functions `yaml_document_add_*()`
1528 * and `yaml_document_append_*()`.  A document with all associated nodes could
1529 * be destroyed using the function `yaml_document_delete()`.
1530 */
1531
[238]1532typedef struct yaml_document_s {
[237]1533
[266]1534    /* The document type. */
1535    yaml_document_type_t type;
1536
1537    /* The document nodes (for internal use only). */
[238]1538    struct {
[266]1539        /* The pointer to the beginning of the list. */
[261]1540        yaml_node_t *list;
[266]1541        /* The length of the list. */
[261]1542        size_t length;
[266]1543        /* The capacity of the list. */
[261]1544        size_t capacity;
[238]1545    } nodes;
[237]1546
[266]1547    /* The version directive or `NULL`. */
[238]1548    yaml_version_directive_t *version_directive;
1549
[266]1550    /* The list of tag directives. */
[238]1551    struct {
[266]1552        /* The pointer to the beginning of the list or `NULL`. */
[261]1553        yaml_tag_directive_t *list;
[266]1554        /** The length of the list. */
[261]1555        size_t length;
[266]1556        /** The capacity of the list (used internally). */
[261]1557        size_t capacity;
[238]1558    } tag_directives;
1559
[266]1560    /** Set if the document start indicator is implicit. */
[261]1561    int is_start_implicit;
[266]1562    /** Set if the document end indicator is implicit. */
[261]1563    int is_end_implicit;
[238]1564
1565    /** The beginning of the document. */
1566    yaml_mark_t start_mark;
1567    /** The end of the document. */
1568    yaml_mark_t end_mark;
1569
1570} yaml_document_t;
1571
[266]1572/*
[261]1573 * Allocate a new empty document object.
1574 *
[266]1575 * A document object allocated using this function must be deleted with
1576 * `yaml_document_delete()`.
1577 *
1578 * Returns: a new empty document object or `NULL` on error.  The function may
1579 * fail if it cannot allocate memory for a new object.
[261]1580 */
1581
1582YAML_DECLARE(yaml_document_t *)
1583yaml_document_new(void);
1584
[266]1585/*
1586 * Deallocate a document object and free the associated data.
[261]1587 *
[266]1588 * A document object must be previously allocated with `yaml_document_new()`.
1589 *
1590 * Arguments:
1591 *
1592 * - `document`: a document object to be deallocated.
[261]1593 */
1594
1595YAML_DECLARE(void)
1596yaml_document_delete(yaml_document_t *document);
1597
[266]1598/*
[261]1599 * Duplicate a document object.
1600 *
[266]1601 * This function creates a complete copy of an existing document and all the
1602 * nodes it contains.  The function accepts two objects: an empty document and
1603 * a model document.  The model is supposed to be initialized either with
1604 * `yaml_parser_parse_document()` or constructed manually.  The functions
1605 * duplicate the content of the document and its nodes and assigns it to the
1606 * empty document.
[261]1607 *
[266]1608 * Arguments:
1609 *
1610 * - `document`: an empty document object.
1611 *
1612 * - `model`: a document to be copied.
1613 *
1614 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1615 * allocate memory for duplicating the state of the model.  In that case, the
1616 * document remains empty.
[261]1617 */
1618
1619YAML_DECLARE(int)
1620yaml_document_duplicate(yaml_document_t *document, yaml_document_t *model);
1621
[266]1622/*
1623 * Clear the document.
1624 *
1625 * This function clears the type of the document and destroys all the document
1626 * nodes.  After applying this function to a document, it becomes empty.  It is
1627 * supposed that the document was previously initialized using
1628 * `yaml_parser_parse_document()` or created manually.  Note that the function
1629 * `yaml_emitter_emit_document()` also clears the given document.
1630 *
1631 * Arguments:
1632 *
1633 * - `document`: a document object.
1634 */
1635
1636YAML_DECLARE(void)
1637yaml_document_clear(yaml_document_t *document);
1638
1639/*
[238]1640 * Create a YAML document.
[237]1641 *
[266]1642 * This function initializes an empty document object allocated with
1643 * `yaml_document_new()`.  Further, nodes could be added to the document using
1644 * the functions `yaml_document_add_*()` and `yaml_document_append_*()`.  The
1645 * initialized document could be fed to `yaml_emitter_emit_document()`.
[237]1646 *
[266]1647 * Arguments:
1648 *
1649 * - `document`: an empty document object.
1650 *
1651 * - `version_directive`: a structure specifying the content of the `%YAML`
1652 *   directive or `NULL` if the directive could be omitted.  Note that LibYAML
1653 *   supports YAML 1.1 only.  The constructor does not check if the supplied
1654 *   version equals to 1.1, but the emitter will fail to emit the document if
1655 *   it is not so.
1656 *
1657 * - `tag_directives_list`: a pointer to a list specifying the content of the
1658 *   `%TAG` directives associated with the document or `NULL` if the document
1659 *   does not contain `%TAG` directives.  The content of a tag directive is a
1660 *   pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings.  The tag
1661 *   handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_`
1662 *   and `-` surrounded by `!`.  The tag prefix is a prefix of any valid tag,
1663 *   that is, it is a non-empty prefix of either a global tag (a valid URI) or
1664 *   a local tag (an arbitrary string starting with `!`).  The constructor does
1665 *   not check if the given directive values satisfy these requirements, but
1666 *   the emitter will fail to emit the document if they are not met.
1667 *
1668 * - `tag_directives_length`: the length of `tag_directives_list`; `0` if
1669 *   `tag_directives_list` is `NULL`.
1670 *
1671 * - `is_start_implicit`: `1` if the document start indicator `---` is omitted;
1672 *   `0` otherwise.  Note that this attribute is only a stylistic hint and
1673 *   could be ignored by the emitter.
1674 *
1675 * - `is_end_implicit`: `1` if the document end indicator `...` is omitted; `0`
1676 *   otherwise.  Note that this attribute is only a stylistic hint and could be
1677 *   ignored by the emitter.
1678 *
1679 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1680 * allocate memory for duplicating the document parameters.  In this case, the
1681 * document remains empty.
[237]1682 */
1683
1684YAML_DECLARE(int)
[261]1685yaml_document_create(yaml_document_t *document,
[266]1686        const yaml_version_directive_t *version_directive,
1687        const yaml_tag_directive_t *tag_directives_list,
1688        size_t tag_directives_length,
[261]1689        int is_start_implicit, int is_end_implicit);
[237]1690
1691/**
[266]1692 * Get a node of a YAML document.
[237]1693 *
[266]1694 * The root node of the document has the id `0`.
1695 *
1696 * The pointer returned by this function is valid until any of the functions
1697 * modifying the document is called.
1698 *
1699 * Arguments:
1700 *
1701 * - `document`: a document object.
1702 *
1703 * - `node_id`: the node id.  The node id starts from `0` and increases by `1`
1704 *   for each newly added node.  Specifying a negative `node_id` is possible,
1705 *   which is interpeted as the number (<total number of nodes> - `node_id`).
1706 *
1707 * Returns: a pointer to the node object or `NULL` if `node_id` is out of
1708 * range.
[237]1709 */
1710
[266]1711YAML_DECLARE(yaml_node_t *)
1712yaml_document_get_node(yaml_document_t *document, int node_id);
[237]1713
[266]1714/*
1715 * Create a SCALAR node and attach it to the document.
[237]1716 *
[266]1717 * Note that the first node attached to a document becomes the root node.
1718 * There must exist a path from the root node to any node added to the
1719 * document, otherwise the function `yaml_emitter_emit_document()` will fail.
[237]1720 *
[266]1721 * Arguments:
[238]1722 *
[266]1723 * - `document`: a document object.
1724 *
1725 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
1726 *
1727 * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty
1728 *   NUL-terminated string containing only alphanumerical characters, `_`, and
1729 *   `-`.  The function does not check whether this requirement is satisfied,
1730 *   but the emitter may fail to emit the node if it is not so.  This parameter
1731 *   is considered as a stylistic hint and could be ignored by the emitter.
1732 *   The emitter may automatically generate an anchor for a node that does not
1733 *   specify it or specifies a duplicate anchor.
1734 *
1735 * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated
1736 *   string.  The tag could be global (a valid URI) or local (an arbitrary
1737 *   string starting with `!`).  The function does not check whether these
1738 *   requirements are satisfied, but the emitter will fail to emit the node if
1739 *   it is not so.
1740 *
1741 * - `value`: the scalar value.  The value should be a string containing any
1742 *   valid UTF-8 character including NUL.  The function does not check if
1743 *   `value` is a valid UTF-8 string, but the emitter will fail to emit the
1744 *   node if it is not so.
1745 *
1746 * - `length`: the length of the scalar value (in bytes) or `-1`.  If `length`
1747 *   is set to `-1`, the `value` is assumed to be NUL-terminated.
1748 *
1749 * - `style`: the node style.  Note that this attribute only serves as a hint
1750 *   and may be ignored by the emitter.
1751 *
1752 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1753 * allocate memory for duplicating the given string buffers.  If the function
1754 * succeeds, the id of the added node is returned via the pointer `node_id`
1755 * if it is not set to `NULL`.
[237]1756 */
1757
[266]1758YAML_DECLARE(int)
1759yaml_document_add_scalar(yaml_document_t *document, int *node_id,
1760        const yaml_char_t *anchor, const yaml_char_t *tag,
1761        const yaml_char_t *value, int length,
1762        yaml_scalar_style_t style);
[237]1763
[266]1764/*
1765 * Create a SEQUENCE node and attach it to the document.
[237]1766 *
[266]1767 * Note that the first node attached to a document becomes the root node.
1768 * There must exist a path from the root node to any node added to the
1769 * document, otherwise the function `yaml_emitter_emit_document()` will fail.
[237]1770 *
[266]1771 * Arguments:
[237]1772 *
[266]1773 * - `document`: a document object.
[238]1774 *
[266]1775 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
[238]1776 *
[266]1777 * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty
1778 *   NUL-terminated string containing only alphanumerical characters, `_`, and
1779 *   `-`.  The function does not check whether this requirement is satisfied,
1780 *   but the emitter may fail to emit the node if it is not so.  This parameter
1781 *   is considered as a stylistic hint and could be ignored by the emitter.
1782 *   The emitter may automatically generate an anchor for a node that does not
1783 *   specify it or specifies a duplicate anchor.
1784 *
1785 * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated
1786 *   string.  The tag could be global (a valid URI) or local (an arbitrary
1787 *   string starting with `!`).  The function does not check whether these
1788 *   requirements are satisfied, but the emitter will fail to emit the node if
1789 *   it is not so.
1790 *
1791 * - `style`: the node style.  Note that this attribute only serves as a hint
1792 *   and may be ignored by the emitter.
1793 *
1794 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1795 * allocate memory for duplicating the given string buffers.  If the function
1796 * succeeds, the id of the added node is returned via the pointer `node_id`
1797 * if it is not set to `NULL`.
[237]1798 */
1799
[266]1800YAML_DECLARE(int)
1801yaml_document_add_sequence(yaml_document_t *document, int *node_id,
1802        const yaml_char_t *anchor, const yaml_char_t *tag,
1803        yaml_sequence_style_t style);
[237]1804
[266]1805/*
1806 * Create a MAPPING node and attach it to the document.
[237]1807 *
[266]1808 * Note that the first node attached to a document becomes the root node.
1809 * There must exist a path from the root node to any node added to the
1810 * document, otherwise the function `yaml_emitter_emit_document()` will fail.
[237]1811 *
[266]1812 * Arguments:
[237]1813 *
[266]1814 * - `document`: a document object.
1815 *
1816 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
1817 *
1818 * - `anchor`: the node anchor or `NULL`.  The anchor should be a non-empty
1819 *   NUL-terminated string containing only alphanumerical characters, `_`, and
1820 *   `-`.  The function does not check whether this requirement is satisfied,
1821 *   but the emitter may fail to emit the node if it is not so.  This parameter
1822 *   is considered as a stylistic hint and could be ignored by the emitter.
1823 *   The emitter may automatically generate an anchor for a node that does not
1824 *   specify it or specifies a duplicate anchor.
1825 *
1826 * - `tag`: the node tag.  The tag should be a non-empty UTF-8 NUL-terminated
1827 *   string.  The tag could be global (a valid URI) or local (an arbitrary
1828 *   string starting with `!`).  The function does not check whether these
1829 *   requirements are satisfied, but the emitter will fail to emit the node if
1830 *   it is not so.
1831 *
1832 * - `style`: the node style.  Note that this attribute only serves as a hint
1833 *   and may be ignored by the emitter.
1834 *
1835 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1836 * allocate memory for duplicating the given string buffers.  If the function
1837 * succeeds, the id of the added node is returned via the pointer `node_id`
1838 * if it is not set to `NULL`.
[237]1839 */
1840
1841YAML_DECLARE(int)
[266]1842yaml_document_add_mapping(yaml_document_t *document, int *node_id,
1843        const yaml_char_t *anchor, const yaml_char_t *tag,
1844        yaml_mapping_style_t style);
[237]1845
[266]1846/*
[267]1847 * Add an item to a SEQUENCE node.
1848 *
1849 * The order in which items are added to a sequence coincides with the order
1850 * they are emitted into the output stream.
1851 *
1852 * Arguments:
1853 *
1854 * - `document`: a document object.
1855 *
1856 * - `sequence_id`: the id of a sequence node; could be negative.  It is a
1857 *   fatal error if `sequence_id` does not refer to an existing sequence node.
1858 *
1859 * - `item_id`: the id of an item node; could be negative.  It is a fatal error
1860 *   if `item_id` does not refer to an existing node.  Note that it is possible
1861 *   for `item_id` to coincide with `sequence_id`, which means that the
1862 *   sequence recursively contains itself.
1863 *
1864 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1865 * allocate memory for internal buffers.
1866 */
1867
1868YAML_DECLARE(int)
1869yaml_document_append_sequence_item(yaml_document_t *document,
1870        int sequence_id, int item_id);
1871
1872/*
1873 * Add a pair of a key and a value to a MAPPING node.
1874 *
1875 * The order in which (key, value) pairs are added to a mapping coincides with
1876 * the order in which they are presented in the output stream.  Note that the
1877 * mapping key order is a presentation detail and should not used to convey any
1878 * information.  An ordered mapping could be represented as a sequence of
1879 * single-paired mappings.
1880 *
1881 * Arguments:
1882 *
1883 * - `document`: a document object.
1884 *
1885 * - `mapping_id`: the id of a mapping node; could be negative.  It is a
1886 *   fatal error if `mapping_id` does not refer to an existing mapping node.
1887 *
1888 * - `key_id`: the id of a key node; could be negative.  It is a fatal error
1889 *   if `key_id` does not refer to an existing node.
1890 *
1891 * - `value_id`: the id of a value node; could be negative.  It is a fatal
1892 *   error if `value_id` does not refer to an existing node.
1893 *
1894 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
1895 * allocate memory for internal buffers.
1896 */
1897
1898YAML_DECLARE(int)
1899yaml_document_append_mapping_pair(yaml_document_t *document,
1900        int mapping_id, int key_id, int value_id);
1901
1902/*
[266]1903 * Get the value of a `!!null` SCALAR node.
[237]1904 *
[266]1905 * Use this function to ensure that the given node is a scalar, the node tag is
1906 * equal to `tag:yaml.org,2002:null` and the node value is a valid null value.
1907 * Given that the `!!null` tag admits only one valid value, the value is not
1908 * returned.
[237]1909 *
[266]1910 * Arguments:
[238]1911 *
[266]1912 * - `document`: a document object.
1913 *
1914 * - `node_id`: the node id; could be negative.
1915 *
1916 * Returns: `1` if the node is a valid `!!null` scalar, `0` otherwise.
[237]1917 */
1918
1919YAML_DECLARE(int)
[266]1920yaml_document_get_null_node(yaml_document_t *document, int node_id);
[237]1921
[266]1922/*
1923 * Get the value of a `!!bool` SCALAR node.
[237]1924 *
[266]1925 * Use this function to ensure that the given node is a scalar, the node tag is
1926 * `tag:yaml.org,2002:bool` and the node value is a valid boolean value.  The
1927 * function returns the true value as `1` and the false value as `0`.
[237]1928 *
[266]1929 * Arguments:
[238]1930 *
[266]1931 * - `document`: a document object.
1932 *
1933 * - `node_id`: the node id; could be negative.
1934 *
1935 * - `value`: a pointer to save the node value or `NULL`.
1936 *
1937 * Returns: `1` if the node is a valid `!!bool` scalar, `0` otherwise.  If the
1938 * function succeeds and `value` is not `NULL`, the node value is saved to
1939 * `value`.
[237]1940 */
1941
1942YAML_DECLARE(int)
[266]1943yaml_document_get_bool_node(yaml_document_t *document, int node_id,
1944        int *value);
[237]1945
[266]1946/*
1947 * Get the value of a `!!str` SCALAR node.
1948 *
1949 * Use this function to ensure that the given node is a scalar, the node tag is
1950 * `tag:yaml.org,2002:str` and the node value is a string that does not contain
1951 * the NUL character.  In this case, the function returns the node value.  The
1952 * produced value is valid until the document object is cleared or deleted.
1953 *
1954 * Arguments:
1955 *
1956 * - `document`: a document object.
1957 *
1958 * - `node_id`: the node id; could be negative.
1959 *
1960 * - `value`: a pointer to save the node value or `NULL`.
1961 *
1962 * Returns: `1` if the node is a valid `!!str` scalar, `0` otherwise.  If the
1963 * function succeeds and `value` is not `NULL`, the node value is saved to
1964 * `value`.
1965 */
1966
1967YAML_DECLARE(int)
1968yaml_document_get_str_node(yaml_document_t *document, int node_id,
1969        char **value);
1970
1971/*
1972 * Get the value of an `!!int` SCALAR node.
1973 *
1974 * Use this function to ensure that the given node is a scalar, the node tag is
1975 * `tag:yaml.org,2002:int` and the node value is a valid integer.  In this
1976 * case, the function parses the node value and returns an integer number.  The
1977 * function recognizes decimal, hexdecimal and octal numbers including negative
[267]1978 * numbers.  The function uses `strtol()` for string-to-integer conversion.
[266]1979 *
1980 * Arguments:
1981 *
1982 * - `document`: a document object.
1983 *
1984 * - `node_id`: the node id; could be negative.
1985 *
1986 * - `value`: a pointer to save the node value or `NULL`.
1987 *
1988 * Returns: `1` if the node is a valid `!!int` scalar, `0` otherwise.  If the
1989 * function succeeds and `value` is not `NULL`, the node value is saved to
1990 * `value`.
1991 */
1992
1993YAML_DECLARE(int)
1994yaml_document_get_int_node(yaml_document_t *document, int node_id,
[267]1995        long *value);
[266]1996
1997/*
1998 * Get the value of a `!!float` SCALAR node.
1999 *
2000 * Use this function to ensure that the given node is a scalar, the node tag is
2001 * `tag:yaml.org,2002:float` and the node value is a valid float value.  In
2002 * this case, the function parses the node value and returns a float number.
2003 * The function recognizes float values in exponential and fixed notation as
[267]2004 * well as special values `.nan`, `.inf` and `-.inf`.  The function uses
2005 * `strtod()` for string-to-float conversion.  The `.nan`, `.inf` and `-.inf`
2006 * values are generated as `0.0/0.0`, `1.0/0.0` and `-1.0/0.0` respectively.
[266]2007 *
2008 * Arguments:
2009 *
2010 * - `document`: a document object.
2011 *
2012 * - `node_id`: the node id; could be negative.
2013 *
2014 * - `value`: a pointer to save the node value or `NULL`.
2015 *
2016 * Returns: `1` if the node is a valid `!!float` scalar, `0` otherwise.  If the
2017 * function succeeds and `value` is not `NULL`, the node value is saved to
2018 * `value`.
2019 */
2020
2021YAML_DECLARE(int)
2022yaml_document_get_float_node(yaml_document_t *document, int node_id,
2023        double *value);
2024
2025/*
2026 * Get the value of a `!!seq` SEQUENCE node.
2027 *
2028 * Use this function to ensure that the given node is a sequence and the node
2029 * tag is `tag:yaml.org,2002:seq`.  In this case, the function returns the list
2030 * of nodes that belong to the sequence.  The produced list is valid until the
2031 * document object is modified.
2032 *
2033 * Arguments:
2034 *
2035 * - `document`: a document object.
2036 *
2037 * - `node_id`: the node id; could be negative.
2038 *
2039 * - `items`: a pointer to save the list of sequence items or `NULL`.
2040 *
2041 * - `length`: a pointer to save the length of the sequence or `NULL`.
2042 *   `length` must be equal to `NULL` if and only if `items` is also `NULL`.
2043 *
2044 * Returns: `1` if the node is a valid `!!seq` sequence, `0` otherwise.  If the
2045 * function succeeds and `items` is not `NULL`, the list of sequence items is
2046 * saved to `items` and the sequence length is saved to `length`.
2047 */
2048
2049YAML_DECLARE(int)
2050yaml_document_get_seq_node(yaml_document_t *document, int node_id,
2051        yaml_node_item_t **items, size_t *length);
2052
2053/*
2054 * Get the value of a `!!map` MAPPING node.
2055 *
2056 * Use this function to ensure that the given node is a mapping and the node
2057 * tag is `tag:yaml.org,2002:map`.  In this case, the function returns the list
2058 * of node pairs (key, value) that belong to the sequence.  The produced list
2059 * is valid until the document is modified.
2060 *
2061 * Arguments:
2062 *
2063 * - `document`: a document object.
2064 *
2065 * - `node_id`: the node id; could be negative.
2066 *
2067 * - `pairs`: a pointer to save the list of mapping pairs or `NULL`.
2068 *
2069 * - `length`: a pointer to save the length of the mapping or `NULL`.
2070 *   `length` must be equal to `NULL` if and only if `pairs` is also `NULL`.
2071 *
2072 * Returns: `1` if the node is a valid `!!map` mapping, `0` otherwise.  If the
2073 * function succeeds and `pairs` is not `NULL`, the list of mapping pairs is
2074 * saved to `pairs` and the mapping length is saved to `length`.
2075 */
2076
2077YAML_DECLARE(int)
2078yaml_document_get_map_node(yaml_document_t *document, int node_id,
2079        yaml_node_pair_t **pairs, size_t *length);
2080
2081/*
2082 * Add a `!!null` SCALAR node to the document.
2083 *
2084 * This function is a shorthand for the call:
2085 *
2086 *      yaml_document_add_scalar(document, node_id, NULL,
2087 *              YAML_NULL_TAG, "null", -1, YAML_ANY_SCALAR_STYLE)
2088 *
2089 * Arguments:
2090 *
2091 * - `document`: a document object.
2092 *
2093 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
2094 *
2095 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
2096 * allocate memory for new buffers.  If the function succeeds, the id of the
2097 * added node is returned via the pointer `node_id` if it is not set to `NULL`.
2098 */
2099
2100YAML_DECLARE(int)
2101yaml_document_add_null_node(yaml_document_t *document, int *node_id);
2102
2103/*
2104 * Add a `!!bool` SCALAR node to the document.
2105 *
2106 * This function is a shorthand for the call:
2107 *
2108 *      yaml_document_add_scalar(document, node_id, NULL,
2109 *              YAML_BOOL_TAG, (value ? "true" : "false"), -1,
2110 *              YAML_ANY_SCALAR_STYLE)
2111 *
2112 * Arguments:
2113 *
2114 * - `document`: a document object.
2115 *
2116 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
2117 *
2118 * - `value`: a boolean value; any non-zero value is true, `0` is false.
2119 *
2120 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
2121 * allocate memory for new buffers.  If the function succeeds, the id of the
2122 * added node is returned via the pointer `node_id` if it is not set to `NULL`.
2123 */
2124
2125YAML_DECLARE(int)
2126yaml_document_add_bool_node(yaml_document_t *document, int *node_id,
2127        int value);
2128
2129/*
2130 * Add a `!!str` SCALAR node to the document.
2131 *
2132 * This function is a shorthand for the call:
2133 *
2134 *      yaml_document_add_scalar(document, node_id, NULL,
2135 *              YAML_STR_TAG, (const yaml_char_t *) value, -1,
2136 *              YAML_ANY_SCALAR_STYLE)
2137 *
2138 * Arguments:
2139 *
2140 * - `document`: a document object.
2141 *
2142 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
2143 *
2144 * - `value`: a NUL-terminated UTF-8 string.  The function does not check if
2145 *   `value` is a valid UTF-8 string, but if it is not so, the emitter will
2146 *   fail to emit the node.
2147 *
2148 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
2149 * allocate memory for new buffers.  If the function succeeds, the id of the
2150 * added node is returned via the pointer `node_id` if it is not set to `NULL`.
2151 */
2152
2153YAML_DECLARE(int)
2154yaml_document_add_str_node(yaml_document_t *document, int *node_id,
2155        const char *value);
2156
2157/*
2158 * Add an `!!int` SCALAR node to the document.
2159 *
2160 * This function is a shorthand for the call:
2161 *
2162 *      yaml_document_add_scalar(document, node_id, NULL,
2163 *              YAML_INT_TAG, <string representation of the value>, -1,
2164 *              YAML_ANY_SCALAR_STYLE)
2165 *
2166 * Arguments:
2167 *
2168 * - `document`: a document object.
2169 *
2170 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
2171 *
2172 * - `value`: an integer value.
2173 *
2174 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
2175 * allocate memory for new buffers.  If the function succeeds, the id of the
2176 * added node is returned via the pointer `node_id` if it is not set to `NULL`.
2177 */
2178
2179YAML_DECLARE(int)
2180yaml_document_add_int_node(yaml_document_t *document, int *node_id,
[267]2181        long value);
[266]2182
2183/*
2184 * Add a `!!float` SCALAR node to the document.
2185 *
2186 * This function is a shorthand for the call:
2187 *
2188 *      yaml_document_add_scalar(document, node_id, NULL,
2189 *              YAML_FLOAT_TAG, <string representation of the value>, -1,
2190 *              YAML_ANY_SCALAR_STYLE)
2191 *
2192 * Arguments:
2193 *
2194 * - `document`: a document object.
2195 *
2196 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
2197 *
2198 * - `value`: a float value.
2199 *
2200 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
2201 * allocate memory for new buffers.  If the function succeeds, the id of the
2202 * added node is returned via the pointer `node_id` if it is not set to `NULL`.
2203 */
2204
2205YAML_DECLARE(int)
2206yaml_document_add_float_node(yaml_document_t *document, int *node_id,
2207        double value);
2208
2209/*
2210 * Add a `!!seq` SEQUENCE node to the document.
2211 *
2212 * This function is a shorthand for the call:
2213 *
2214 *      yaml_document_add_sequence(document, node_id, NULL,
2215 *              YAML_SEQ_TAG, YAML_ANY_SEQUENCE_STYLE)
2216 *
2217 * Arguments:
2218 *
2219 * - `document`: a document object.
2220 *
2221 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
2222 *
2223 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
2224 * allocate memory for new buffers.  If the function succeeds, the id of the
2225 * added node is returned via the pointer `node_id` if it is not set to `NULL`.
2226 */
2227
2228YAML_DECLARE(int)
2229yaml_document_add_seq_node(yaml_document_t *document, int *node_id);
2230
2231/*
2232 * Add a `!!map` MAPPING node to the document.
2233 *
2234 * This function is a shorthand for the call:
2235 *
2236 *      yaml_document_add_mapping(document, node_id, NULL,
2237 *              YAML_MAP_TAG, YAML_ANY_MAPPING_STYLE)
2238 *
2239 * Arguments:
2240 *
2241 * - `document`: a document object.
2242 *
2243 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
2244 *
2245 * Returns: `1` on success, `0` on error.  The function may fail if it cannot
2246 * allocate memory for new buffers.  If the function succeeds, the id of the
2247 * added node is returned via the pointer `node_id` if it is not set to `NULL`.
2248 */
2249
2250YAML_DECLARE(int)
2251yaml_document_add_map_node(yaml_document_t *document, int *node_id);
2252
[267]2253/*****************************************************************************
[266]2254 * Callback Definitions
[267]2255 *****************************************************************************/
[199]2256
[266]2257/*
[178]2258 * The prototype of a read handler.
2259 *
[266]2260 * The reader is called when the parser needs to read more bytes from the input
2261 * stream.  The reader is given a buffer to fill and should returns the number
2262 * of bytes read.  The reader should block if no data from the input stream is
2263 * available, but it should return immediately if it could produce least one
2264 * byte of the input stream.  If the reader reaches the stream end, it should
2265 * return immediately setting the number of bytes read to `0`.
[178]2266 *
[266]2267 * Arguments:
[178]2268 *
[266]2269 * - `data`: a pointer to an application data specified with
2270 *   `yaml_parser_set_reader()`.
2271 *
2272 * - `buffer`: a pointer to a buffer which should be filled with the bytes
2273 *   from the input stream.
2274 *
2275 * - `capacity`: the maximum capacity of the buffer.
2276 *
2277 * - `length`: a pointer to save the actual number of bytes read from the input
2278 *   stream; `length` equals `0` signifies that the reader reached the end of
2279 *   the stream.
2280 *
2281 * Return: on success, the reader should return `1`.  If the reader fails for
2282 * any reason, it should return `0`.  On the end of the input stream, the
2283 * reader should set `length` to `0` and return `1`.
[178]2284 */
[180]2285
[261]2286typedef int yaml_reader_t(void *data, unsigned char *buffer, size_t capacity,
2287        size_t *length);
[178]2288
[266]2289/*
[261]2290 * The prototype of a write handler.
2291 *
[266]2292 * The writer is called when the emitter needs to flush the accumulated bytes
2293 * into the output stream.
[261]2294 *
[266]2295 * Arguments:
[261]2296 *
[266]2297 * - `data`: a pointer to an application data specified with
2298 *   `yaml_emitter_set_writer()`.
2299 *
2300 * - `buffer`: a pointer to a buffer with bytes to be written to the output
2301 *   stream.
2302 *
2303 * - `length`: the number of bytes to be written.
2304 *
2305 * Returns: on success, the writer should return `1`.  If the writer fails for
2306 * any reason, it should return `0`.
[184]2307 */
2308
[264]2309typedef int yaml_writer_t(void *data, const unsigned char *buffer,
2310        size_t length);
[208]2311
[184]2312/**
[266]2313 * The prototype of a nonspecific tag resolver.
[261]2314 *
[266]2315 * The resolver is called when the parser encounters a node without an explicit
2316 * tag.  The resolver should determine the correct tag of the node from the
2317 * path to the node from the root node and, in case of the scalar node, the
2318 * node value.  The resolver is also called by the emitter to determine whether
2319 * the node tag could be omitted.
[261]2320 *
[266]2321 * Arguments:
[261]2322 *
[266]2323 * - `data`: a pointer to an application data specified with
2324 *   `yaml_parser_set_resolver()` or `yaml_emitter_set_resolver()`.
2325 *
2326 * - `node`: information about the new node.
2327 *
2328 * - `tag`: A pointer to save the guessed node tag.  The value returned by the
2329 *   resolved is immediately copied.
2330 *
2331 * Returns: on success, the resolver should return `1`.  If the resolver fails
2332 * for any reason, it should return `0`.
[201]2333 */
2334
[261]2335typedef int yaml_resolver_t(void *data, yaml_incomplete_node_t *node,
[267]2336        const yaml_char_t **tag);
[238]2337
[267]2338/*****************************************************************************
[266]2339 * Parser Definitions
[267]2340 *****************************************************************************/
[238]2341
[266]2342/*
2343 * An opaque definition of the parser object.
2344 *
2345 * A parser object is used to parse an input YAML stream producing a sequence
2346 * of YAML tokens, events or documents.
[178]2347 */
2348
[261]2349typedef struct yaml_parser_s yaml_parser_t;
[178]2350
[266]2351/*
2352 * Allocate a new parser object.
[178]2353 *
[266]2354 * An allocated parser object should be deleted with `yaml_parser_delete()`
[178]2355 *
[266]2356 * Returns: a new parser object or `NULL` on error.  The function may fail if
2357 * it cannot allocate memory for internal buffers.
[178]2358 */
2359
[261]2360YAML_DECLARE(yaml_parser_t *)
2361yaml_parser_new(void);
[178]2362
[266]2363/*
2364 * Deallocate a parser and free the internal parser data.
2365 *
2366 * A parser object must be previously allocated with `yaml_parser_new()`.
[178]2367 *
[266]2368 * Arguments:
2369 *
2370 * - `parser`: a parser object.
[178]2371 */
2372
[183]2373YAML_DECLARE(void)
[178]2374yaml_parser_delete(yaml_parser_t *parser);
2375
[266]2376/*
2377 * Clear and reinitialize the internal state of the parser.
[261]2378 *
[266]2379 * This function could be used for cleaning up a parser object after an error
2380 * condition or after the end of the input stream is reached.  A cleaned parser
2381 * object may be reused to parse another YAML stream.  Note that all the parser
2382 * parameters including the read handler must be reset.
2383 *
2384 * Arguments:
2385 *
2386 * - `parser`: a parser object.
[261]2387 */
2388
2389YAML_DECLARE(void)
[267]2390yaml_parser_reset(yaml_parser_t *parser);
[261]2391
[266]2392/*
2393 * Get the parser error.
[179]2394 *
[266]2395 * Use this function to get a detailed error information after failure of one
2396 * of the following functions: `yaml_parser_parse_token()`,
2397 * `yaml_parser_parse_event()`, `yaml_parser_parse_document()`,
2398 * `yaml_parser_parse_single_document()`.
[179]2399 *
[266]2400 * The pointer returned by the function is only valid until the parser object
2401 * is not modified.  However the error object could be safely copied.
2402 *
2403 * Arguments:
2404 *
2405 * - `parser`: a parser object.
2406 *
2407 * Returns: a pointer to an error object.  The returned pointer is only valid
2408 * until the parser object is not modified or deleted.  However the error
2409 * object could be safely copied.
[179]2410 */
2411
[266]2412YAML_DECLARE(yaml_error_t *)
2413yaml_parser_get_error(yaml_parser_t *parser);
2414
2415/*
2416 * Set the parser to read the input stream from a character buffer.
2417 *
2418 * Arguments:
2419 *
2420 * - `parser`: a parser object.
2421 *
2422 * - `buffer`: a pointer to character buffer containing the input stream.  The
2423 *   buffer must be valid until the parser object is cleared or deleted.
2424 *
2425 * - `length`: the length of the buffer in bytes.
2426 */
2427
[183]2428YAML_DECLARE(void)
[261]2429yaml_parser_set_string_reader(yaml_parser_t *parser,
2430        const unsigned char *buffer, size_t length);
[179]2431
[266]2432/*
2433 * Set the parser to read the input stream from a file.
[179]2434 *
[266]2435 * Arguments:
[179]2436 *
[266]2437 * - `parser`: a parser object.
2438 *
2439 * - `file`: a pointer to an open file object.  The pointer must be valid until
2440 *   the parser object is cleared or deleted.
[179]2441 */
2442
[183]2443YAML_DECLARE(void)
[261]2444yaml_parser_set_file_reader(yaml_parser_t *parser, FILE *file);
[179]2445
[266]2446/*
2447 * Set an input stream reader for a parser.
[179]2448 *
[266]2449 * Arguments:
2450 *
2451 * - `parser`: a parser object.
2452 *
2453 * - `reader`: a read handler.
2454 *
2455 * - `data`: application data for passing to the reader.
[179]2456 */
2457
[183]2458YAML_DECLARE(void)
[261]2459yaml_parser_set_reader(yaml_parser_t *parser,
2460        yaml_reader_t *reader, void *data);
[179]2461
[266]2462/*
2463 * Set the standard nonspecific tag resolver for a parser.
[261]2464 *
[266]2465 * The standard resolver recognizes the following scalar tags: `!!null`,
2466 * `!!bool`, `!!str`, `!!int`, and `!!float`.
[261]2467 *
[266]2468 * Arguments:
2469 *
2470 * - `parser`: a parser object.
[261]2471 */
2472
2473YAML_DECLARE(void)
2474yaml_parser_set_standard_resolver(yaml_parser_t *parser);
2475
[266]2476/*
2477 * Set a nonspecific tag resolver for a parser.
[261]2478 *
[266]2479 * Arguments:
[261]2480 *
[266]2481 * - `parser`: a parser object.
2482 *
2483 * - `resolver`: a resolve handler.
2484 *
2485 * - `data`: application data for passing to the resolver.
[261]2486 */
2487
2488YAML_DECLARE(void)
2489yaml_parser_set_resolver(yaml_parser_t *parser,
2490        yaml_resolver_t *resolver, void *data);
2491
[266]2492/*
2493 * Set the input stream encoding.
[179]2494 *
[266]2495 * Typically the parser guesses the input stream encoding by the BOM mark.  If
2496 * the BOM mark is not present, the UTF-8 encoding is assumed.  An application
2497 * could override the detection mechanism by specifying the the encoding
2498 * explicitly.
2499 *
2500 * Arguments:
2501 *
2502 * - `parser`: a parser object.
2503 *
2504 * - `encoding`: the input stream encoding.
[179]2505 */
2506
[183]2507YAML_DECLARE(void)
[179]2508yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
2509
[266]2510/*
2511 * Parse the input stream and produce the next token.
[184]2512 *
[266]2513 * An application may call this function subsequently to produce a sequence of
2514 * tokens corresponding to the input stream.  The first token in the sequence
2515 * is STREAM-START and the last token is STREAM-END.  When the stream ends, the
2516 * parser produces empty tokens.
[184]2517 *
[266]2518 * An application must not alternate calls of the functions
2519 * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
2520 * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
2521 * the same parser object.
[184]2522 *
[266]2523 * Arguments:
[184]2524 *
[266]2525 * - `parser`: a parser object.
[184]2526 *
[266]2527 * - `token`: an empty token object to save the token produced by the parser.
2528 *   An application is responsible for clearing or deleting the produced token.
2529 *   If the parser fails or the stream end is reached, the object is kept
2530 *   empty.
2531 *
2532 * Returns: `1` on success, `0` on error.  If the function succeeds and the
2533 * stream end is not reached, the token data is saved to the given token
2534 * object.  If the function fails, the error details could be obtained with
2535 * `yaml_parser_get_error()`.  In case of error, the parser is non-functional
2536 * until it is cleared.
[184]2537 */
2538
[208]2539YAML_DECLARE(int)
[264]2540yaml_parser_parse_token(yaml_parser_t *parser, yaml_token_t *token);
[184]2541
[266]2542/*
[208]2543 * Parse the input stream and produce the next parsing event.
[201]2544 *
[266]2545 * An application may call this function subsequently to produce a sequence of
2546 * events corresponding to the input stream.  The produced events satisfy
2547 * the grammar:
[201]2548 *
[266]2549 *      stream ::= STREAM-START document* STREAM-END
2550 *      document ::= DOCUMENT-START node DOCUMENT-END
2551 *      node ::= ALIAS | SCALAR | sequence | mapping
2552 *      sequence ::= SEQUENCE-START node* SEQUENCE-END
2553 *      mapping ::= MAPPING-START (node node)* MAPPING-END
[201]2554 *
[266]2555 * When the stream ends, the parser produces empty tokens.
[201]2556 *
[266]2557 * An application must not alternate calls of the functions
2558 * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
2559 * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
2560 * the same parser object.
[201]2561 *
[266]2562 * Arguments:
2563 *
2564 * - `parser`: a parser object.
2565 *
2566 * - `event`: an empty event object to save the event produced by the parser.
2567 *   An application is responsible for clearing or deleting the produced event.
2568 *   Alternatively the produced event could be fed to the emitter.  If the
2569 *   parser fails or the stream end is reached, the object is kept empty.
2570 *
2571 * Returns: `1` on success, `0` on error.  If the function succeeds and the
2572 * stream end is not reached, the event data is saved to the given event
2573 * object.  If the function fails, the error details could be obtained with
2574 * `yaml_parser_get_error()`.  In case of error, the parser is non-functional
2575 * until it is cleared.
[201]2576 */
2577
[208]2578YAML_DECLARE(int)
[264]2579yaml_parser_parse_event(yaml_parser_t *parser, yaml_event_t *event);
[201]2580
[266]2581/*
[238]2582 * Parse the input stream and produce the next YAML document.
2583 *
[266]2584 * An application may call this function subsequently to produce a sequence of
2585 * documents constituting the input stream.  When the stream ends, the parser
2586 * produces empty documents.
[238]2587 *
[266]2588 * An application must not alternate calls of the functions
2589 * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
2590 * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
2591 * the same parser object.
[238]2592 *
[266]2593 * Arguments:
[238]2594 *
[266]2595 * - `parser`: a parser object.
[238]2596 *
[266]2597 * - `document`: an empty document object to save the document produced by the
2598 *   parser.  An application is responsible for clearing or deleting the
2599 *   produced document.  Alternatively the produced document could be fed to
2600 *   the emitter.  If the parser fails or the stream end is reached, the object
2601 *   is kept empty.
[238]2602 *
[266]2603 * Returns: `1` on success, `0` on error.  If the function succeeds and the
2604 * stream end is not reached, the document data is saved to the given document
2605 * object.  If the function fails, the error details could be obtained with
2606 * `yaml_parser_get_error()`.  In case of error, the parser is non-functional
2607 * until it is cleared.
[238]2608 */
2609
2610YAML_DECLARE(int)
[264]2611yaml_parser_parse_document(yaml_parser_t *parser, yaml_document_t *document);
[238]2612
[266]2613/*
2614 * Parse the input stream containing a single YAML document.
2615 *
2616 * An application may call this function to ensure that the input stream contain
2617 * no more that one document.  If the stream is empty, the parser produces an
2618 * empty document.  If the stream contains a single document, the parser returns
2619 * it.  If the stream contains more than one document, the parser produces an
2620 * error.
2621 *
2622 * An application must not alternate calls of the functions
2623 * `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
2624 * `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
2625 * the same parser object.
2626 *
2627 * Arguments:
2628 *
2629 * - `parser`: a parser object.
2630 *
2631 * - `document`: an empty document object to save the document produced by the
2632 *   parser.  An application is responsible for clearing or deleting the
2633 *   produced document.  Alternatively the produced document could be fed to
2634 *   the emitter.  If the parser fails or the stream is empty, the object is
2635 *   kept empty.
2636 *
2637 * Returns: `1` on success, `0` on error.  If the function succeeds and the
2638 * stream is not empty, the document data is saved to the given document
2639 * object.  If the function fails, the error details could be obtained with
2640 * `yaml_parser_get_error()`.  In case of error, the parser is non-functional
2641 * until it is cleared.
2642 */
[261]2643
[266]2644YAML_DECLARE(int)
2645yaml_parser_parse_single_document(yaml_parser_t *parser,
2646        yaml_document_t *document);
[178]2647
[267]2648/*****************************************************************************
[266]2649 * Emitter Definitions
[267]2650 *****************************************************************************/
[266]2651
2652/*
2653 * An opaque definition of the emitter object.
2654 *
2655 * An emitter object is used to emit YAML events or documents into an output
2656 * YAML stream.
[211]2657 */
2658
[261]2659typedef struct yaml_emitter_s yaml_emitter_t;
[211]2660
[266]2661/*
2662 * Allocate a new emitter object.
[211]2663 *
[266]2664 * An allocated emitter object should be deleted with `yaml_emitter_delete()`.
[211]2665 *
[266]2666 * Returns: a new emitter or `NULL` on error.  The function mail fail if it
2667 * cannot allocate memory for internal buffers.
[211]2668 */
2669
[261]2670YAML_DECLARE(yaml_emitter_t *)
2671yaml_emitter_new(void);
[211]2672
[266]2673/*
2674 * Deallocate an emitter and free the internal emitter data.
2675 *
2676 * An emitter object must be previously allocated with `yaml_emitter_new()`.
[211]2677 *
[266]2678 * Arguments:
2679 *
2680 * - `emitter`: an emitter object.
[211]2681 */
2682
2683YAML_DECLARE(void)
2684yaml_emitter_delete(yaml_emitter_t *emitter);
2685
[266]2686/*
2687 * Clear and reinitialize the internal state of the emitter.
[261]2688 *
[266]2689 * This function could be used for cleaning up an emitter object after an error
2690 * condition or after a complete YAML stream was produced.  A cleaned emitter
2691 * object may be reused to produce another YAML stream.  Note that all the
2692 * emitter parameters including the write handler must be reset.
2693 *
2694 * Arguments:
2695 *
2696 * - `emitter`: an emitter object.
[261]2697 */
2698
2699YAML_DECLARE(void)
[267]2700yaml_emitter_reset(yaml_emitter_t *emitter);
[261]2701
[266]2702/*
2703 * Get the emitter error.
[211]2704 *
[266]2705 * Use this function to get a detailed error information after failure of one
2706 * of the following functions: `yaml_emitter_emit_event()`,
2707 * `yaml_emitter_open()`, `yaml_emitter_close()`,
2708 * `yaml_emitter_emit_document()`, `yaml_emitter_emit_single_document()`.
[211]2709 *
[266]2710 * The pointer returned by the function is only valid until the emitter object
2711 * is not modified.  However the error object could be safely copied.
2712 *
2713 * Arguments:
2714 *
2715 * - `emitter`: an emitter object.
2716 *
2717 * Returns: a pointer to an error object.  The returned pointer is only valid
2718 * until the emitter object is not modified or deleted.  However the error
2719 * object could be safely copied.
[211]2720 */
2721
[266]2722YAML_DECLARE(yaml_error_t *)
2723yaml_emitter_get_error(yaml_emitter_t *emitter);
2724
2725/*
2726 * Set the emitter to dump the generated YAML stream into a string buffer.
2727 *
2728 * Arguments:
2729 *
2730 * - `emitter`: an emitter object.
2731 *
2732 * - `buffer`: a pointer to a buffer to store the generated YAML stream.  The
2733 *   pointer must be valid until the emitter object is cleared or deleted.
2734 *
2735 * - `capacity`: the size of the buffer.  The emitter will fail if the buffer
2736 *   is smaller than required to hold the whole stream.
2737 *
2738 * - `length`: a pointer to save the length of the produced stream (in bytes).
2739 */
2740
[211]2741YAML_DECLARE(void)
[261]2742yaml_emitter_set_string_writer(yaml_emitter_t *emitter,
[265]2743        unsigned char *buffer, size_t capacity, size_t *length);
[211]2744
[266]2745/*
2746 * Set the emitter to dump the generated YAML stream into a file.
[211]2747 *
[266]2748 * Arguments:
[211]2749 *
[266]2750 * - `emitter`: an emitter object.
2751 *
2752 * - `file`: a pointer to a file open for writing.  The pointer must be valid
2753 *   until the emitter object is cleared or deleted.
[211]2754 */
2755
2756YAML_DECLARE(void)
[261]2757yaml_emitter_set_file_writer(yaml_emitter_t *emitter, FILE *file);
[211]2758
[266]2759/*
2760 * Set the output stream writer for an emitter.
[211]2761 *
[266]2762 * Arguments:
2763 *
2764 * - `emitter`: an emitter object.
2765 *
2766 * - `writer`: a write handler.
2767 *
2768 * - `data`: application data for passing to the writer.
[211]2769 */
2770
2771YAML_DECLARE(void)
[261]2772yaml_emitter_set_writer(yaml_emitter_t *emitter,
2773        yaml_writer_t *writer, void *data);
[211]2774
[266]2775/*
2776 * Set the standard nonspecific tag resolver for an emitter.
[261]2777 *
[266]2778 * The standard resolver recognizes the following scalar tags: `!!null`,
2779 * `!!bool`, `!!str`, `!!int`, and `!!float`.
[261]2780 *
[266]2781 * Arguments:
2782 *
2783 * - `emitter`: an emitter object.
[261]2784 */
2785
2786YAML_DECLARE(void)
2787yaml_emitter_set_standard_resolver(yaml_emitter_t *emitter);
2788
[266]2789/*
2790 * Set a nonspecific tag resolver for an emitter.
[261]2791 *
[266]2792 * Arguments:
[261]2793 *
[266]2794 * - `emitter`: an emitter object.
2795 *
2796 * - `resolver`: a resolve handler.
2797 *
2798 * - `data`: application data for passing to the resolver.
[261]2799 */
2800
2801YAML_DECLARE(void)
2802yaml_emitter_set_resolver(yaml_emitter_t *emitter,
2803        yaml_resolver_t *resolver, void *data);
2804
[266]2805/*
2806 * Set the output stream encoding.
[211]2807 *
[266]2808 * The emitter uses the UTF-8 encoding for the output stream unless another
2809 * encoding is specified explicitly.  The encoding could be specified using
2810 * this function or via the `encoding` parameter of the STREAM-START event.
2811 *
2812 * Arguments:
2813 *
2814 * - `emitter`: an emitter object.
2815 *
2816 * - `encoding`: the output stream encoding.
[211]2817 */
2818
2819YAML_DECLARE(void)
2820yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
2821
[266]2822/*
2823 * Specify if the emitter should use the "canonical" output format.
[211]2824 *
[266]2825 * The "canonical" format uses the flow style for collections and the
2826 * double-quoted style for scalars.  Node tags are always dumped explicitly.
2827 *
2828 * Arguments:
2829 *
2830 * - `emitter`: an emitter object.
2831 *
2832 * - `is_canonical`: `1` to set the "canonical" format, `0` otherwise.
[211]2833 */
2834
2835YAML_DECLARE(void)
[261]2836yaml_emitter_set_canonical(yaml_emitter_t *emitter, int is_canonical);
[211]2837
[266]2838/*
[211]2839 * Set the intendation increment.
2840 *
[266]2841 * The default intendation increment is `2`.
2842 *
2843 * Arguments:
2844 *
2845 * - `emitter`: an emitter object.
2846 *
2847 * - `indent`: the indentation increment; a number between `2` and `9`.
[211]2848 */
2849
2850YAML_DECLARE(void)
2851yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
2852
[266]2853/*
2854 * Set the preferred line width.
[211]2855 *
[266]2856 * The default preferred line width is `80`.  The given line width is only a
2857 * stylistic hint and could be violated by the emitter.  When the line width is
2858 * exceeded, the emitter seeks for a way to move to the next line.
2859 *
2860 * Arguments:
2861 *
2862 * - `emitter`: an emitter object.
2863 *
2864 * - `width`: the preferred line width; `-1` means unlimited.
[211]2865 */
2866
2867YAML_DECLARE(void)
2868yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
2869
[266]2870/*
2871 * Specify if non-ASCII characters could be emitted unescaped.
[211]2872 *
[266]2873 * By default, the emitter always escapes non-ASCII characters using the `\u`
2874 * or `\U` format.
2875 *
2876 * Arguments:
2877 *
2878 * - `emitter`: an emitter object.
2879 *
2880 * - `is_unicode`: `1` if unescaped non-ASCII characters are allowed; `0`
2881 *   otherwise.
[211]2882 */
2883
2884YAML_DECLARE(void)
[261]2885yaml_emitter_set_unicode(yaml_emitter_t *emitter, int is_unicode);
[211]2886
[266]2887/*
[211]2888 * Set the preferred line break.
2889 *
[266]2890 * By default, the emitter uses the LN character for line breaks.
2891 *
2892 * Arguments:
2893 *
2894 * - `emitter`: an emitter object.
2895 *
2896 * - `line_break`: the preferred line break.
[211]2897 */
2898
2899YAML_DECLARE(void)
2900yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
2901
[266]2902/*
2903 * Emit an event to the output YAML stream.
[211]2904 *
[266]2905 * An application needs to call this function subsequently to produce a whole
2906 * YAML stream.  The event sequence must satisfy the following grammar:
[211]2907 *
[266]2908 *      stream ::= STREAM-START document* STREAM-END
2909 *      document ::= DOCUMENT-START node DOCUMENT-END
2910 *      node ::= ALIAS | SCALAR | sequence | mapping
2911 *      sequence ::= SEQUENCE-START node* SEQUENCE-END
2912 *      mapping ::= MAPPING-START (node node)* MAPPING-END
[211]2913 *
[266]2914 * An application must not alternate the calls of the functions
2915 * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
2916 * `yaml_emitter_emit_single_document()` on the same emitter object.
2917 *
2918 * Arguments:
2919 *
2920 * - `emitter`: an emitter object.
2921 *
2922 * - `event`: an event to emit.  The event must be previously initialized using
2923 *   either one of the functions `yaml_event_create_*()` or with
2924 *   `yaml_parser_parse_event()`.  The emitter takes the responsibility for the
2925 *   event data and clears the event, so that it becomes empty.  The event is
2926 *   cleared even if the function fails.
2927 *
2928 * Returns: `1` on success, `0` on error.  Note that the emitter may not
2929 * immediately dump the given event, so that the function could indicate
2930 * success on an errorneous event.  In this case, some of the next calls of the
2931 * function will generate an error.  If the function fails, the error details
2932 * could be obtained with `yaml_emitter_get_error()`.  In case of error, the
2933 * emitter is non-functional until it is cleared.
[211]2934 */
2935
2936YAML_DECLARE(int)
[264]2937yaml_emitter_emit_event(yaml_emitter_t *emitter, yaml_event_t *event);
[179]2938
[266]2939/*
[238]2940 * Start a YAML stream.
2941 *
[266]2942 * This function should be used in conjunction with
2943 * `yaml_emitter_emit_document()` and `yaml_emitter_end()`.  This function must
2944 * be called once before any documents are emitted.
[238]2945 *
[266]2946 * Arguments:
[238]2947 *
[266]2948 * - `emitter`: an emitter object.
2949 *
2950 * Returns: `1` on success, `0` on error.  If the function fails, the error
2951 * details could be obtained with `yaml_emitter_get_error()`.  In case of
2952 * error, the emitter is non-functional until it is cleared.
[238]2953 */
2954
2955YAML_DECLARE(int)
[266]2956yaml_emitter_start(yaml_emitter_t *emitter);
[238]2957
[266]2958/*
[238]2959 * Finish a YAML stream.
2960 *
[266]2961 * This function should be used in conjunction with `yaml_emitter_start()` and
2962 * `yaml_emitter_emit_document()`.  This function must be called once after all
2963 * documents are emitted.
[238]2964 *
[266]2965 * Arguments:
[238]2966 *
[266]2967 * - `emitter`: an emitter object.
2968 *
2969 * Returns: `1` on success, `0` on error.  If the function fails, the error
2970 * details could be obtained with `yaml_emitter_get_error()`.  In case of
2971 * error, the emitter is non-functional until it is cleared.
[238]2972 */
2973
2974YAML_DECLARE(int)
[266]2975yaml_emitter_end(yaml_emitter_t *emitter);
[238]2976
[266]2977/*
[238]2978 * Emit a YAML document.
2979 *
[266]2980 * Before emitting any documents, the function `yaml_emitter_start()` must be
2981 * called.  After all documents are emitted, the function `yaml_emitter_end()`
2982 * must be called.
[238]2983 *
[266]2984 * An application must not alternate the calls of the functions
2985 * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
2986 * `yaml_emitter_emit_single_document()` on the same emitter object.
[238]2987 *
[266]2988 * Arguments:
2989 *
2990 * - `emitter`: an emitter object.
2991 *
2992 * - `document`: a document to emit.  The document must have a root node with
2993 *   all the other nodes reachable from it.  The document may be prepared using
2994 *   the functions `yaml_document_create()`, `yaml_document_add_*()` and
2995 *   `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`.
2996 *   The emitter takes the responsibility for the document content and clears
2997 *   the document, so that it becomes empty.  The document is cleared even if
2998 *   the function fails.
2999 *
3000 * Returns: `1` on success, `0` on error.  If the function fails, the error
3001 * details could be obtained with `yaml_emitter_get_error()`.  In case of
3002 * error, the emitter is non-functional until it is cleared.
[238]3003 */
3004
3005YAML_DECLARE(int)
[264]3006yaml_emitter_emit_document(yaml_emitter_t *emitter, yaml_document_t *document);
[238]3007
[266]3008/*
3009 * Emit a YAML stream consisting of a single document.
3010 *
3011 * This function is a shorthand of the calls:
3012 *
3013 *      yaml_emitter_start(emitter)
3014 *      yaml_emitter_emit_document(emitter, document)
3015 *      yaml_emitter_end(emitter)
3016 *
3017 * An application must not alternate the calls of the functions
3018 * `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
3019 * `yaml_emitter_emit_single_document()` on the same emitter object.
3020 *
3021 * Arguments:
3022 *
3023 * - `emitter`: an emitter object.
3024 *
3025 * - `document`: a document to emit.  The document must have a root node with
3026 *   all the other nodes reachable from it.  The document may be prepared using
3027 *   the functions `yaml_document_create()`, `yaml_document_add_*()` and
3028 *   `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`.
3029 *   The emitter takes the responsibility for the document content and clears
3030 *   the document, so that it becomes empty.  The document is cleared even if
3031 *   the function fails.
3032 *
3033 * Returns: `1` on success, `0` on error.  If the function fails, the error
3034 * details could be obtained with `yaml_emitter_get_error()`.  In case of
3035 * error, the emitter is non-functional until it is cleared.
3036 */
[261]3037
[266]3038YAML_DECLARE(int)
3039yaml_emitter_emit_single_document(yaml_emitter_t *emitter,
3040        yaml_document_t *document);
3041
3042/*
3043 * Flush the accumulated characters.
[211]3044 *
[266]3045 * This function flushes the accumulated characters from the internal emitter
3046 * buffer to the output stream.  Note that the buffer is flushed automatically
3047 * when a complete document has emitted or a stream has ended.
[211]3048 *
[266]3049 * Arguments:
3050 *
3051 * - `emitter`: an emitter object.
3052 *
3053 * Returns: `1` on success, `0` on error.  If the function fails, the error
3054 * details could be obtained with `yaml_emitter_get_error()`.  In case of
3055 * error, the emitter is non-functional until it is cleared.
[211]3056 */
3057
3058YAML_DECLARE(int)
3059yaml_emitter_flush(yaml_emitter_t *emitter);
3060
3061
[162]3062#ifdef __cplusplus
3063}
3064#endif
3065
[169]3066#endif /* #ifndef YAML_H */
[162]3067
Note: See TracBrowser for help on using the repository browser.