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

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

Minor API updates.

Line 
1/*****************************************************************************
2 * Public Interface for LibYAML
3 *
4 * Copyright (c) 2006 Kirill Simonov
5 *
6 * LibYAML is free software; you can use, modify and/or redistribute it under
7 * the terms of the MIT license; see the file LICENCE for more details.
8 *****************************************************************************/
9
10/*****************************************************************************
11 * General guidelines.
12 *****************************************************************************/
13
14/*
15 * Basic conventions.
16 *
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_`.
20 *
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 *
39 * FIXME: Calling conventions.
40 * FIXME: Memory allocation.
41 * FIXME: Errors and exceptions.
42 * FIXME: And so on, and so forth.
43 *
44 *
45 *
46 *
47 */
48
49
50#ifndef YAML_H
51#define YAML_H
52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57#include <stdlib.h>
58#include <stdio.h>
59#include <string.h>
60
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.
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
92/*****************************************************************************
93 * Version Information
94 *****************************************************************************/
95
96/*
97 * The major, minor and patch version numbers of LibYAML.
98 */
99
100#define YAML_VERSION_MAJOR  0
101#define YAML_VERSION_MINOR  2
102#define YAML_VERSION_PATCH  0
103
104/*
105 * The version of LibYAML as a string.
106 */
107
108#define YAML_VERSION_STRING "0.2.0"
109
110/*
111 * Get the library version numbers at runtime.
112 *
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.
120 */
121
122YAML_DECLARE(void)
123yaml_get_version(int *major, int *minor, int *patch);
124
125/*
126 * Get the library version as a string at runtime.
127 *
128 * Returns: the version of LibYAML as a static string.
129 */
130
131YAML_DECLARE(const char *)
132yaml_get_version_string(void);
133
134/*****************************************************************************
135 * Error Handling
136 *****************************************************************************/
137
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.
144 */
145
146typedef enum yaml_error_type_e {
147    /* No error was produced. */
148    YAML_NO_ERROR,
149
150    /* Cannot allocate or reallocate a block of memory. */
151    YAML_MEMORY_ERROR,
152
153    /* Cannot read from the input stream. */
154    YAML_READER_ERROR,
155    /* Cannot decode a character in the input stream. */
156    YAML_DECODER_ERROR,
157    /* Cannot scan a YAML token. */
158    YAML_SCANNER_ERROR,
159    /* Cannot parse a YAML event. */
160    YAML_PARSER_ERROR,
161    /* Cannot compose a YAML document. */
162    YAML_COMPOSER_ERROR,
163
164    /* Cannot write into the output stream. */
165    YAML_WRITER_ERROR,
166    /* Cannot emit a YAML event. */
167    YAML_EMITTER_ERROR,
168    /* Cannot serialize a YAML document. */
169    YAML_SERIALIZER_ERROR,
170
171    /* Cannot resolve an implicit YAML node tag. */
172    YAML_RESOLVER_ERROR
173} yaml_error_type_t;
174
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
183typedef struct yaml_mark_s {
184    /* The number of the character in the input stream (starting from zero). */
185    size_t index;
186    /* The line in the input stream (starting from zero). */
187    size_t line;
188    /* The column in the input stream (starting from zero). */
189    size_t column;
190} yaml_mark_t;
191
192/*
193 * Error details.
194 *
195 * The structure gives detailed information on any problem that occured during
196 * parsing or emitting.
197 */
198
199typedef struct yaml_error_s {
200
201    /* The error type. */
202    yaml_error_type_t type;
203
204    /* The specific information for each error type. */
205    union {
206
207        /*
208         * A problem occured while reading the input stream (relevant for
209         * `YAML_READER_ERROR` and `YAML_DECODER_ERROR`).
210         */
211        struct {
212            /* The problem description. */
213            const char *problem;
214            /* The position in the input stream, in bytes. */
215            size_t offset;
216            /* The problematic octet or character (`-1` if not applicable). */
217            int value;
218        } reading;
219
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`).
224         */
225        struct {
226            /* The description of the context in which the problem occured
227               (`NULL` if not applicable). */
228            const char *context;
229            /* The context mark (if `context` is not `NULL`). */
230            yaml_mark_t context_mark;
231            /* The problem description. */
232            const char *problem;
233            /* The problem mark. */
234            yaml_mark_t problem_mark;
235        } loading;
236
237        /*
238         * A problem occured while writing into the output stream (relevant for
239         * `YAML_WRITER_ERROR`).
240         */
241        struct {
242            /* The problem description. */
243            const char *problem;
244            /* The position in the output stream, in bytes. */
245            size_t offset;
246        } writing;
247
248        /*
249         * A problem while dumping YAML data into the output stream (relevant
250         * for `YAML_EMITTER_ERROR` and `YAML_SERIALIZER_ERROR`).
251         */
252        struct {
253            /* The problem description. */
254            const char *problem;
255        } dumping;
256
257        /*
258         * A problem occured while resolving an implicit YAML node tag
259         * (relevant for `YAML_RESOLVER_ERROR`).
260         */
261        struct {
262            /* The problem description. */
263            const char *problem;
264        } resolving;
265
266    } data;
267
268} yaml_error_t;
269
270/*
271 * Generate an error message.
272 *
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.
277 *
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.
293 */
294
295YAML_DECLARE(int)
296yaml_error_message(yaml_error_t *error, char *buffer, size_t capacity);
297
298/*****************************************************************************
299 * Basic Types
300 *****************************************************************************/
301
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.
307 */
308
309typedef unsigned char yaml_char_t;
310
311/*
312 * The version directive information.
313 *
314 * Note that LibYAML only supports YAML 1.1.
315 */
316
317typedef struct yaml_version_directive_s {
318    /* The major version number. */
319    int major;
320    /* The minor version number. */
321    int minor;
322} yaml_version_directive_t;
323
324/*
325 * The tag directive information.
326 */
327
328typedef struct yaml_tag_directive_s {
329    /* The tag handle. */
330    yaml_char_t *handle;
331    /* The tag prefix. */
332    yaml_char_t *prefix;
333} yaml_tag_directive_t;
334
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
346typedef enum yaml_encoding_e {
347    /* The default/autodetected encoding. */
348    YAML_ANY_ENCODING,
349    /* The UTF-8 encoding. */
350    YAML_UTF8_ENCODING,
351    /* The UTF-16-LE encoding. */
352    YAML_UTF16LE_ENCODING,
353    /* The UTF-16-BE encoding. */
354    YAML_UTF16BE_ENCODING
355} yaml_encoding_t;
356
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
365typedef enum yaml_break_e {
366    /* Let the parser choose the break type. */
367    YAML_ANY_BREAK,
368    /* Use CR for line breaks (Mac style). */
369    YAML_CR_BREAK,
370    /* Use LN for line breaks (Unix style). */
371    YAML_LN_BREAK,
372    /* Use CR LN for line breaks (DOS style). */
373    YAML_CRLN_BREAK
374} yaml_break_t;
375
376/*****************************************************************************
377 * Node Styles
378 *****************************************************************************/
379
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.
394 */
395
396typedef enum yaml_scalar_style_e {
397    /* Let the emitter choose the style. */
398    YAML_ANY_SCALAR_STYLE,
399
400    /* The plain flow scalar style. */
401    YAML_PLAIN_SCALAR_STYLE,
402
403    /* The single-quoted flow scalar style. */
404    YAML_SINGLE_QUOTED_SCALAR_STYLE,
405    /* The double-quoted flow scalar style. */
406    YAML_DOUBLE_QUOTED_SCALAR_STYLE,
407
408    /* The literal block scalar style. */
409    YAML_LITERAL_SCALAR_STYLE,
410    /* The folded block scalar style. */
411    YAML_FOLDED_SCALAR_STYLE
412} yaml_scalar_style_t;
413
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 */
426typedef enum yaml_sequence_style_e {
427    /* Let the emitter choose the style. */
428    YAML_ANY_SEQUENCE_STYLE,
429
430    /* The flow sequence style. */
431    YAML_FLOW_SEQUENCE_STYLE,
432    /* The block sequence style. */
433    YAML_BLOCK_SEQUENCE_STYLE
434} yaml_sequence_style_t;
435
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
449typedef enum yaml_mapping_style_e {
450    /* Let the emitter choose the style. */
451    YAML_ANY_MAPPING_STYLE,
452
453    /* The block mapping style. */
454    YAML_BLOCK_MAPPING_STYLE,
455    /* The flow mapping style. */
456    YAML_FLOW_MAPPING_STYLE
457} yaml_mapping_style_t;
458
459/*****************************************************************************
460 * Tokens
461 *****************************************************************************/
462
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.
512 */
513
514typedef enum yaml_token_type_e {
515    /* An empty unitialized token. */
516    YAML_NO_TOKEN,
517
518    /* A STREAM-START token. */
519    YAML_STREAM_START_TOKEN,
520    /* A STREAM-END token. */
521    YAML_STREAM_END_TOKEN,
522
523    /* A VERSION-DIRECTIVE token. */
524    YAML_VERSION_DIRECTIVE_TOKEN,
525    /* A TAG-DIRECTIVE token. */
526    YAML_TAG_DIRECTIVE_TOKEN,
527    /* A DOCUMENT-START token. */
528    YAML_DOCUMENT_START_TOKEN,
529    /* A DOCUMENT-END token. */
530    YAML_DOCUMENT_END_TOKEN,
531
532    /* A BLOCK-SEQUENCE-START token. */
533    YAML_BLOCK_SEQUENCE_START_TOKEN,
534    /* A BLOCK-SEQUENCE-END token. */
535    YAML_BLOCK_MAPPING_START_TOKEN,
536    /* A BLOCK-END token. */
537    YAML_BLOCK_END_TOKEN,
538
539    /* A FLOW-SEQUENCE-START token. */
540    YAML_FLOW_SEQUENCE_START_TOKEN,
541    /* A FLOW-SEQUENCE-END token. */
542    YAML_FLOW_SEQUENCE_END_TOKEN,
543    /* A FLOW-MAPPING-START token. */
544    YAML_FLOW_MAPPING_START_TOKEN,
545    /* A FLOW-MAPPING-END token. */
546    YAML_FLOW_MAPPING_END_TOKEN,
547
548    /* A BLOCK-ENTRY token. */
549    YAML_BLOCK_ENTRY_TOKEN,
550    /* A FLOW-ENTRY token. */
551    YAML_FLOW_ENTRY_TOKEN,
552    /* A KEY token. */
553    YAML_KEY_TOKEN,
554    /* A VALUE token. */
555    YAML_VALUE_TOKEN,
556
557    /* An ALIAS token. */
558    YAML_ALIAS_TOKEN,
559    /* An ANCHOR token. */
560    YAML_ANCHOR_TOKEN,
561    /* A TAG token. */
562    YAML_TAG_TOKEN,
563    /* A SCALAR token. */
564    YAML_SCALAR_TOKEN
565} yaml_token_type_t;
566
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
575typedef struct yaml_token_s {
576
577    /* The token type. */
578    yaml_token_type_t type;
579
580    /* The token data. */
581    union {
582
583        /* Extra data associated with a STREAM-START token. */
584        struct {
585            /* The stream encoding. */
586            yaml_encoding_t encoding;
587        } stream_start;
588
589        /* Extra data associated with a VERSION-DIRECTIVE token. */
590        struct {
591            /* The major version number. */
592            int major;
593            /* The minor version number. */
594            int minor;
595        } version_directive;
596
597        /* Extra data associated with a TAG-DIRECTIVE token. */
598        struct {
599            /* The tag handle. */
600            yaml_char_t *handle;
601            /* The tag prefix. */
602            yaml_char_t *prefix;
603        } tag_directive;
604
605        /* Extra data associated with an ALIAS token. */
606        struct {
607            /* The alias value. */
608            yaml_char_t *value;
609        } alias;
610
611        /* Extra data associated with an ANCHOR token. */
612        struct {
613            /* The anchor value. */
614            yaml_char_t *value;
615        } anchor;
616
617        /* Extra data associated with a TAG token. */
618        struct {
619            /* The tag handle. */
620            yaml_char_t *handle;
621            /* The tag suffix. */
622            yaml_char_t *suffix;
623        } tag;
624
625        /* Extra data associated with a SCALAR token. */
626        struct {
627            /* The scalar value. */
628            yaml_char_t *value;
629            /* The length of the scalar value. */
630            size_t length;
631            /* The scalar style. */
632            yaml_scalar_style_t style;
633        } scalar;
634
635    } data;
636
637    /* The beginning of the token. */
638    yaml_mark_t start_mark;
639    /* The end of the token. */
640    yaml_mark_t end_mark;
641
642} yaml_token_t;
643
644/*
645 * Allocate a new empty token object.
646 *
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.
652 */
653
654YAML_DECLARE(yaml_token_t *)
655yaml_token_new(void);
656
657/*
658 * Deallocate a token object and free the associated data.
659 *
660 * A token object must be previously allocated with `yaml_token_new()`.
661 *
662 * Arguments:
663 *
664 * - `token`: a token object to be deallocated.
665 */
666
667YAML_DECLARE(void)
668yaml_token_delete(yaml_token_t *token);
669
670/*
671 * Duplicate a token object.
672 *
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.
678 *
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.
688 */
689
690YAML_DECLARE(int)
691yaml_token_duplicate(yaml_token_t *token, const yaml_token_t *model);
692
693/*
694 * Clear the token state.
695 *
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.
704 */
705
706YAML_DECLARE(void)
707yaml_token_clear(yaml_token_t *token);
708
709/*****************************************************************************
710 * Events
711 *****************************************************************************/
712
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
746 */
747
748typedef enum yaml_event_type_e {
749    /* An empty unitialized event. */
750    YAML_NO_EVENT,
751
752    /* A STREAM-START event. */
753    YAML_STREAM_START_EVENT,
754    /* A STREAM-END event. */
755    YAML_STREAM_END_EVENT,
756
757    /* A DOCUMENT-START event. */
758    YAML_DOCUMENT_START_EVENT,
759    /* A DOCUMENT-END event. */
760    YAML_DOCUMENT_END_EVENT,
761
762    /* An ALIAS event. */
763    YAML_ALIAS_EVENT,
764    /* A SCALAR event. */
765    YAML_SCALAR_EVENT,
766
767    /* A SEQUENCE-START event. */
768    YAML_SEQUENCE_START_EVENT,
769    /* A SEQUENCE-END event. */
770    YAML_SEQUENCE_END_EVENT,
771
772    /* A MAPPING-START event. */
773    YAML_MAPPING_START_EVENT,
774    /* A MAPPING-END event. */
775    YAML_MAPPING_END_EVENT
776} yaml_event_type_t;
777
778/*
779 * The event object.
780 *
781 * The event-level API of LibYAML should be used for streaming applications.
782 */
783
784typedef struct yaml_event_s {
785
786    /* The event type. */
787    yaml_event_type_t type;
788
789    /* The event data. */
790    union {
791       
792        /* The stream parameters (for `YAML_STREAM_START_EVENT`). */
793        struct {
794            /* The document encoding. */
795            yaml_encoding_t encoding;
796        } stream_start;
797
798        /* The document parameters (for `YAML_DOCUMENT_START_EVENT`). */
799        struct {
800            /* The version directive or `NULL` if not present. */
801            yaml_version_directive_t *version_directive;
802
803            /* The list of tag directives. */
804            struct {
805                /* The beginning of the list or `NULL`. */
806                yaml_tag_directive_t *list;
807                /* The length of the list. */
808                size_t length;
809                /* The capacity of the list (used internally). */
810                size_t capacity;
811            } tag_directives;
812
813            /* Set if the document indicator is omitted. */
814            int is_implicit;
815        } document_start;
816
817        /* The document end parameters (for `YAML_DOCUMENT_END_EVENT`). */
818        struct {
819            /* Set if the document end indicator is omitted. */
820            int is_implicit;
821        } document_end;
822
823        /* The alias parameters (for `YAML_ALIAS_EVENT`). */
824        struct {
825            /* The anchor. */
826            yaml_char_t *anchor;
827        } alias;
828
829        /* The scalar parameters (for `YAML_SCALAR_EVENT`). */
830        struct {
831            /* The node anchor or `NULL`. */
832            yaml_char_t *anchor;
833            /* The node tag or `NULL`. */
834            yaml_char_t *tag;
835            /* The scalar value. */
836            yaml_char_t *value;
837            /* The length of the scalar value (in bytes). */
838            size_t length;
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. */
844            yaml_scalar_style_t style;
845        } scalar;
846
847        /* The sequence parameters (for `YAML_SEQUENCE_START_EVENT`). */
848        struct {
849            /* The node anchor or `NULL`. */
850            yaml_char_t *anchor;
851            /* The node tag or `NULL`. */
852            yaml_char_t *tag;
853            /* Set if the tag is optional. */
854            int is_nonspecific;
855            /* The sequence style. */
856            yaml_sequence_style_t style;
857        } sequence_start;
858
859        /* The mapping parameters (for `YAML_MAPPING_START_EVENT`). */
860        struct {
861            /* The node anchor or `NULL`. */
862            yaml_char_t *anchor;
863            /* The node tag or `NULL`. */
864            yaml_char_t *tag;
865            /* Set if the tag is optional. */
866            int is_nonspecific;
867            /* The mapping style. */
868            yaml_mapping_style_t style;
869        } mapping_start;
870
871    } data;
872
873    /* The beginning of the event. */
874    yaml_mark_t start_mark;
875    /* The end of the event. */
876    yaml_mark_t end_mark;
877
878} yaml_event_t;
879
880/*
881 * Allocate a new empty event object.
882 *
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.
888 */
889
890YAML_DECLARE(yaml_event_t *)
891yaml_event_new(void);
892
893/*
894 * Deallocate an event object and free the associated data.
895 *
896 * An event object must be previously allocated with `yaml_event_new()`.
897 *
898 * Arguments:
899 *
900 * - `event`: an event object to be deallocated.
901 */
902
903YAML_DECLARE(void)
904yaml_event_delete(yaml_event_t *event);
905
906/*
907 * Duplicate an event object.
908 *
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.
915 *
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.
925 */
926
927YAML_DECLARE(int)
928yaml_event_duplicate(yaml_event_t *event, const yaml_event_t *model);
929
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/*
948 * Create a STREAM-START event.
949 *
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()`.
953 *
954 * Arguments:
955 *
956 * - `event`: an empty event object.
957 *
958 * - `encoding`: the stream encoding.
959 *
960 * Returns: `1`.  The function never fails.
961 */
962
963YAML_DECLARE(int)
964yaml_event_create_stream_start(yaml_event_t *event,
965        yaml_encoding_t encoding);
966
967/*
968 * Create a STREAM-END event.
969 *
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()`.
973 *
974 * Arguments:
975 *
976 * - `event`: an empty event object.
977 *
978 * Returns: `1`.  The function never fails.
979 */
980
981YAML_DECLARE(int)
982yaml_event_create_stream_end(yaml_event_t *event);
983
984/*
985 * Create a DOCUMENT-START event.
986 *
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()`.
990 *
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.
1022 */
1023
1024YAML_DECLARE(int)
1025yaml_event_create_document_start(yaml_event_t *event,
1026        const yaml_version_directive_t *version_directive,
1027        const yaml_tag_directive_t *tag_directives_list,
1028        size_t tag_directives_length,
1029        int is_implicit);
1030
1031/*
1032 * Create a DOCUMENT-END event.
1033 *
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()`.
1037 *
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.
1047 */
1048
1049YAML_DECLARE(int)
1050yaml_event_create_document_end(yaml_event_t *event, int is_implicit);
1051
1052/*
1053 * Create an ANCHOR event.
1054 *
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()`.
1058 *
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.
1071 */
1072
1073YAML_DECLARE(int)
1074yaml_event_create_alias(yaml_event_t *event, const yaml_char_t *anchor);
1075
1076/*
1077 * Create a SCALAR event.
1078 *
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()`.
1082 *
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.
1124 */
1125
1126YAML_DECLARE(int)
1127yaml_event_create_scalar(yaml_event_t *event,
1128        const yaml_char_t *anchor, const yaml_char_t *tag,
1129        const yaml_char_t *value, int length,
1130        int is_plain_nonspecific, int is_quoted_nonspecific,
1131        yaml_scalar_style_t style);
1132
1133/*
1134 * Create a SEQUENCE-START event.
1135 *
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()`.
1139 *
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.
1167 */
1168
1169YAML_DECLARE(int)
1170yaml_event_create_sequence_start(yaml_event_t *event,
1171        const yaml_char_t *anchor, const yaml_char_t *tag,
1172        int is_nonspecific, yaml_sequence_style_t style);
1173
1174/*
1175 * Create a SEQUENCE-END event.
1176 *
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()`.
1180 *
1181 * Arguments:
1182 *
1183 * - `event`: an empty event object.
1184 *
1185 * Returns: `1`.  This function never fails.
1186 */
1187
1188YAML_DECLARE(int)
1189yaml_event_create_sequence_end(yaml_event_t *event);
1190
1191/*
1192 * Create a MAPPING-START event.
1193 *
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()`.
1197 *
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.
1225 */
1226
1227YAML_DECLARE(int)
1228yaml_event_create_mapping_start(yaml_event_t *event,
1229        const yaml_char_t *anchor, const yaml_char_t *tag,
1230        int is_nonspecific, yaml_mapping_style_t style);
1231
1232/*
1233 * Create a MAPPING-END event.
1234 *
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()`.
1238 *
1239 * Arguments:
1240 *
1241 * - `event`: an empty event object.
1242 *
1243 * Returns: `1`.  This function never fails.
1244 */
1245
1246YAML_DECLARE(int)
1247yaml_event_create_mapping_end(yaml_event_t *event);
1248
1249/*****************************************************************************
1250 * Documents and Nodes
1251 *****************************************************************************/
1252
1253/*
1254 * Well-known scalar tags.
1255 */
1256
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")
1262
1263/*
1264 * Basic collection tags.
1265 */
1266
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")
1269
1270/*
1271 * The default tags for nodes lacking an explicit tag.
1272 */
1273
1274#define YAML_DEFAULT_SCALAR_TAG     YAML_STR_TAG
1275#define YAML_DEFAULT_SEQUENCE_TAG   YAML_SEQ_TAG
1276#define YAML_DEFAULT_MAPPING_TAG    YAML_MAP_TAG
1277
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. */
1289    YAML_NO_DOCUMENT,
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
1301typedef enum yaml_node_type_e {
1302    /* An empty node. */
1303    YAML_NO_NODE,
1304
1305    /* A scalar node. */
1306    YAML_SCALAR_NODE,
1307    /* A sequence node. */
1308    YAML_SEQUENCE_NODE,
1309    /* A mapping node. */
1310    YAML_MAPPING_NODE
1311} yaml_node_type_t;
1312
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
1321typedef enum yaml_arc_type_e {
1322    /* An empty arc. */
1323    YAML_NO_ARC,
1324
1325    /* An item of a sequence. */
1326    YAML_SEQUENCE_ITEM_ARC,
1327    /* A key of a mapping. */
1328    YAML_MAPPING_KEY_ARC,
1329    /* A value of a mapping. */
1330    YAML_MAPPING_VALUE_ARC
1331} yaml_arc_type_t;
1332
1333/*
1334 * An element of a sequence node.
1335 */
1336
1337typedef int yaml_node_item_t;
1338
1339/*
1340 * An element of a mapping node.
1341 */
1342
1343typedef struct yaml_node_pair_s {
1344    /* A key in a mapping. */
1345    int key;
1346    /* A value in a mapping. */
1347    int value;
1348} yaml_node_pair_t;
1349
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
1362typedef struct yaml_arc_s {
1363
1364    /* The arc type. */
1365    yaml_arc_type_t type;
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;
1400} yaml_arc_t;
1401
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
1411typedef struct yaml_node_s {
1412
1413    /* The node type. */
1414    yaml_node_type_t type;
1415
1416    /* The node anchor or `NULL`. */
1417    yaml_char_t *anchor;
1418    /* The node tag. */
1419    yaml_char_t *tag;
1420
1421    /* The node data. */
1422    union {
1423       
1424        /* The scalar parameters (for `YAML_SCALAR_NODE`). */
1425        struct {
1426            /* The scalar value. */
1427            yaml_char_t *value;
1428            /* The length of the scalar value. */
1429            size_t length;
1430            /* The scalar style. */
1431            yaml_scalar_style_t style;
1432        } scalar;
1433
1434        /* The sequence parameters (for `YAML_SEQUENCE_NODE`). */
1435        struct {
1436            /* The list of sequence items. */
1437            struct {
1438                /* The pointer to the beginning of the list. */
1439                yaml_node_item_t *list;
1440                /* The length of the list. */
1441                size_t length;
1442                /* The capacity of the list (used internally). */
1443                size_t capacity;
1444            } items;
1445            /* The sequence style. */
1446            yaml_sequence_style_t style;
1447        } sequence;
1448
1449        /* The mapping parameters (for `YAML_MAPPING_NODE`). */
1450        struct {
1451            /* The list of mapping pairs (key, value). */
1452            struct {
1453                /** The pointer to the beginning of the list. */
1454                yaml_node_pair_t *list;
1455                /* The length of the list. */
1456                size_t length;
1457                /* The capacity of the list (used internally). */
1458                size_t capacity;
1459            } pairs;
1460            /* The mapping style. */
1461            yaml_mapping_style_t style;
1462        } mapping;
1463
1464    } data;
1465
1466    /* The beginning of the node. */
1467    yaml_mark_t start_mark;
1468    /* The end of the node. */
1469    yaml_mark_t end_mark;
1470
1471} yaml_node_t;
1472
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
1481typedef struct yaml_incomplete_node_s {
1482
1483    /* The node type. */
1484    yaml_node_type_t type;
1485
1486    /* The path to the new node. */
1487    struct {
1488        /* The pointer to the beginning of the list. */
1489        yaml_arc_t *list;
1490        /* The length of the list. */
1491        size_t length;
1492        /* The capacity of the list (used internally). */
1493        size_t capacity;
1494    } path;
1495
1496    /* The node data. */
1497    union {
1498
1499        /* The scalar parameters (for `YAML_SCALAR_NODE`). */
1500        struct {
1501            /* The scalar value. */
1502            yaml_char_t *value;
1503            /* The length of the scalar value. */
1504            size_t length;
1505            /* Set if the scalar is plain. */
1506            int is_plain;
1507        } scalar;
1508
1509    } data;
1510
1511    /* The position of the node. */
1512    yaml_mark_t mark;
1513
1514} yaml_incomplete_node_t;
1515
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
1532typedef struct yaml_document_s {
1533
1534    /* The document type. */
1535    yaml_document_type_t type;
1536
1537    /* The document nodes (for internal use only). */
1538    struct {
1539        /* The pointer to the beginning of the list. */
1540        yaml_node_t *list;
1541        /* The length of the list. */
1542        size_t length;
1543        /* The capacity of the list. */
1544        size_t capacity;
1545    } nodes;
1546
1547    /* The version directive or `NULL`. */
1548    yaml_version_directive_t *version_directive;
1549
1550    /* The list of tag directives. */
1551    struct {
1552        /* The pointer to the beginning of the list or `NULL`. */
1553        yaml_tag_directive_t *list;
1554        /** The length of the list. */
1555        size_t length;
1556        /** The capacity of the list (used internally). */
1557        size_t capacity;
1558    } tag_directives;
1559
1560    /** Set if the document start indicator is implicit. */
1561    int is_start_implicit;
1562    /** Set if the document end indicator is implicit. */
1563    int is_end_implicit;
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
1572/*
1573 * Allocate a new empty document object.
1574 *
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.
1580 */
1581
1582YAML_DECLARE(yaml_document_t *)
1583yaml_document_new(void);
1584
1585/*
1586 * Deallocate a document object and free the associated data.
1587 *
1588 * A document object must be previously allocated with `yaml_document_new()`.
1589 *
1590 * Arguments:
1591 *
1592 * - `document`: a document object to be deallocated.
1593 */
1594
1595YAML_DECLARE(void)
1596yaml_document_delete(yaml_document_t *document);
1597
1598/*
1599 * Duplicate a document object.
1600 *
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.
1607 *
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.
1617 */
1618
1619YAML_DECLARE(int)
1620yaml_document_duplicate(yaml_document_t *document, yaml_document_t *model);
1621
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/*
1640 * Create a YAML document.
1641 *
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()`.
1646 *
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.
1682 */
1683
1684YAML_DECLARE(int)
1685yaml_document_create(yaml_document_t *document,
1686        const yaml_version_directive_t *version_directive,
1687        const yaml_tag_directive_t *tag_directives_list,
1688        size_t tag_directives_length,
1689        int is_start_implicit, int is_end_implicit);
1690
1691/**
1692 * Get a node of a YAML document.
1693 *
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.
1709 */
1710
1711YAML_DECLARE(yaml_node_t *)
1712yaml_document_get_node(yaml_document_t *document, int node_id);
1713
1714/*
1715 * Create a SCALAR node and attach it to the document.
1716 *
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.
1720 *
1721 * Arguments:
1722 *
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`.
1756 */
1757
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);
1763
1764/*
1765 * Create a SEQUENCE node and attach it to the document.
1766 *
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.
1770 *
1771 * Arguments:
1772 *
1773 * - `document`: a document object.
1774 *
1775 * - `node_id`: a pointer to save the id of the generated node or `NULL`.
1776 *
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`.
1798 */
1799
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);
1804
1805/*
1806 * Create a MAPPING node and attach it to the document.
1807 *
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.
1811 *
1812 * Arguments:
1813 *
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`.
1839 */
1840
1841YAML_DECLARE(int)
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);
1845
1846/*
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/*
1903 * Get the value of a `!!null` SCALAR node.
1904 *
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.
1909 *
1910 * Arguments:
1911 *
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.
1917 */
1918
1919YAML_DECLARE(int)
1920yaml_document_get_null_node(yaml_document_t *document, int node_id);
1921
1922/*
1923 * Get the value of a `!!bool` SCALAR node.
1924 *
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`.
1928 *
1929 * Arguments:
1930 *
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`.
1940 */
1941
1942YAML_DECLARE(int)
1943yaml_document_get_bool_node(yaml_document_t *document, int node_id,
1944        int *value);
1945
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
1978 * numbers.  The function uses `strtol()` for string-to-integer conversion.
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,
1995        long *value);
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
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.
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,
2181        long value);
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
2253/*****************************************************************************
2254 * Callback Definitions
2255 *****************************************************************************/
2256
2257/*
2258 * The prototype of a read handler.
2259 *
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`.
2266 *
2267 * Arguments:
2268 *
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`.
2284 */
2285
2286typedef int yaml_reader_t(void *data, unsigned char *buffer, size_t capacity,
2287        size_t *length);
2288
2289/*
2290 * The prototype of a write handler.
2291 *
2292 * The writer is called when the emitter needs to flush the accumulated bytes
2293 * into the output stream.
2294 *
2295 * Arguments:
2296 *
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`.
2307 */
2308
2309typedef int yaml_writer_t(void *data, const unsigned char *buffer,
2310        size_t length);
2311
2312/**
2313 * The prototype of a nonspecific tag resolver.
2314 *
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.
2320 *
2321 * Arguments:
2322 *
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`.
2333 */
2334
2335typedef int yaml_resolver_t(void *data, yaml_incomplete_node_t *node,
2336        const yaml_char_t **tag);
2337
2338/*****************************************************************************
2339 * Parser Definitions
2340 *****************************************************************************/
2341
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.
2347 */
2348
2349typedef struct yaml_parser_s yaml_parser_t;
2350
2351/*
2352 * Allocate a new parser object.
2353 *
2354 * An allocated parser object should be deleted with `yaml_parser_delete()`
2355 *
2356 * Returns: a new parser object or `NULL` on error.  The function may fail if
2357 * it cannot allocate memory for internal buffers.
2358 */
2359
2360YAML_DECLARE(yaml_parser_t *)
2361yaml_parser_new(void);
2362
2363/*
2364 * Deallocate a parser and free the internal parser data.
2365 *
2366 * A parser object must be previously allocated with `yaml_parser_new()`.
2367 *
2368 * Arguments:
2369 *
2370 * - `parser`: a parser object.
2371 */
2372
2373YAML_DECLARE(void)
2374yaml_parser_delete(yaml_parser_t *parser);
2375
2376/*
2377 * Clear and reinitialize the internal state of the parser.
2378 *
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.
2387 */
2388
2389YAML_DECLARE(void)
2390yaml_parser_reset(yaml_parser_t *parser);
2391
2392/*
2393 * Get the parser error.
2394 *
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()`.
2399 *
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.
2410 */
2411
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
2428YAML_DECLARE(void)
2429yaml_parser_set_string_reader(yaml_parser_t *parser,
2430        const unsigned char *buffer, size_t length);
2431
2432/*
2433 * Set the parser to read the input stream from a file.
2434 *
2435 * Arguments:
2436 *
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.
2441 */
2442
2443YAML_DECLARE(void)
2444yaml_parser_set_file_reader(yaml_parser_t *parser, FILE *file);
2445
2446/*
2447 * Set an input stream reader for a parser.
2448 *
2449 * Arguments:
2450 *
2451 * - `parser`: a parser object.
2452 *
2453 * - `reader`: a read handler.
2454 *
2455 * - `data`: application data for passing to the reader.
2456 */
2457
2458YAML_DECLARE(void)
2459yaml_parser_set_reader(yaml_parser_t *parser,
2460        yaml_reader_t *reader, void *data);
2461
2462/*
2463 * Set the standard nonspecific tag resolver for a parser.
2464 *
2465 * The standard resolver recognizes the following scalar tags: `!!null`,
2466 * `!!bool`, `!!str`, `!!int`, and `!!float`.
2467 *
2468 * Arguments:
2469 *
2470 * - `parser`: a parser object.
2471 */
2472
2473YAML_DECLARE(void)
2474yaml_parser_set_standard_resolver(yaml_parser_t *parser);
2475
2476/*
2477 * Set a nonspecific tag resolver for a parser.
2478 *
2479 * Arguments:
2480 *
2481 * - `parser`: a parser object.
2482 *
2483 * - `resolver`: a resolve handler.
2484 *
2485 * - `data`: application data for passing to the resolver.
2486 */
2487
2488YAML_DECLARE(void)
2489yaml_parser_set_resolver(yaml_parser_t *parser,
2490        yaml_resolver_t *resolver, void *data);
2491
2492/*
2493 * Set the input stream encoding.
2494 *
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.
2505 */
2506
2507YAML_DECLARE(void)
2508yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
2509
2510/*
2511 * Parse the input stream and produce the next token.
2512 *
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.
2517 *
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.
2522 *
2523 * Arguments:
2524 *
2525 * - `parser`: a parser object.
2526 *
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.
2537 */
2538
2539YAML_DECLARE(int)
2540yaml_parser_parse_token(yaml_parser_t *parser, yaml_token_t *token);
2541
2542/*
2543 * Parse the input stream and produce the next parsing event.
2544 *
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:
2548 *
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
2554 *
2555 * When the stream ends, the parser produces empty tokens.
2556 *
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.
2561 *
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.
2576 */
2577
2578YAML_DECLARE(int)
2579yaml_parser_parse_event(yaml_parser_t *parser, yaml_event_t *event);
2580
2581/*
2582 * Parse the input stream and produce the next YAML document.
2583 *
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.
2587 *
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.
2592 *
2593 * Arguments:
2594 *
2595 * - `parser`: a parser object.
2596 *
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.
2602 *
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.
2608 */
2609
2610YAML_DECLARE(int)
2611yaml_parser_parse_document(yaml_parser_t *parser, yaml_document_t *document);
2612
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 */
2643
2644YAML_DECLARE(int)
2645yaml_parser_parse_single_document(yaml_parser_t *parser,
2646        yaml_document_t *document);
2647
2648/*****************************************************************************
2649 * Emitter Definitions
2650 *****************************************************************************/
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.
2657 */
2658
2659typedef struct yaml_emitter_s yaml_emitter_t;
2660
2661/*
2662 * Allocate a new emitter object.
2663 *
2664 * An allocated emitter object should be deleted with `yaml_emitter_delete()`.
2665 *
2666 * Returns: a new emitter or `NULL` on error.  The function mail fail if it
2667 * cannot allocate memory for internal buffers.
2668 */
2669
2670YAML_DECLARE(yaml_emitter_t *)
2671yaml_emitter_new(void);
2672
2673/*
2674 * Deallocate an emitter and free the internal emitter data.
2675 *
2676 * An emitter object must be previously allocated with `yaml_emitter_new()`.
2677 *
2678 * Arguments:
2679 *
2680 * - `emitter`: an emitter object.
2681 */
2682
2683YAML_DECLARE(void)
2684yaml_emitter_delete(yaml_emitter_t *emitter);
2685
2686/*
2687 * Clear and reinitialize the internal state of the emitter.
2688 *
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.
2697 */
2698
2699YAML_DECLARE(void)
2700yaml_emitter_reset(yaml_emitter_t *emitter);
2701
2702/*
2703 * Get the emitter error.
2704 *
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()`.
2709 *
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.
2720 */
2721
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
2741YAML_DECLARE(void)
2742yaml_emitter_set_string_writer(yaml_emitter_t *emitter,
2743        unsigned char *buffer, size_t capacity, size_t *length);
2744
2745/*
2746 * Set the emitter to dump the generated YAML stream into a file.
2747 *
2748 * Arguments:
2749 *
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.
2754 */
2755
2756YAML_DECLARE(void)
2757yaml_emitter_set_file_writer(yaml_emitter_t *emitter, FILE *file);
2758
2759/*
2760 * Set the output stream writer for an emitter.
2761 *
2762 * Arguments:
2763 *
2764 * - `emitter`: an emitter object.
2765 *
2766 * - `writer`: a write handler.
2767 *
2768 * - `data`: application data for passing to the writer.
2769 */
2770
2771YAML_DECLARE(void)
2772yaml_emitter_set_writer(yaml_emitter_t *emitter,
2773        yaml_writer_t *writer, void *data);
2774
2775/*
2776 * Set the standard nonspecific tag resolver for an emitter.
2777 *
2778 * The standard resolver recognizes the following scalar tags: `!!null`,
2779 * `!!bool`, `!!str`, `!!int`, and `!!float`.
2780 *
2781 * Arguments:
2782 *
2783 * - `emitter`: an emitter object.
2784 */
2785
2786YAML_DECLARE(void)
2787yaml_emitter_set_standard_resolver(yaml_emitter_t *emitter);
2788
2789/*
2790 * Set a nonspecific tag resolver for an emitter.
2791 *
2792 * Arguments:
2793 *
2794 * - `emitter`: an emitter object.
2795 *
2796 * - `resolver`: a resolve handler.
2797 *
2798 * - `data`: application data for passing to the resolver.
2799 */
2800
2801YAML_DECLARE(void)
2802yaml_emitter_set_resolver(yaml_emitter_t *emitter,
2803        yaml_resolver_t *resolver, void *data);
2804
2805/*
2806 * Set the output stream encoding.
2807 *
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.
2817 */
2818
2819YAML_DECLARE(void)
2820yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
2821
2822/*
2823 * Specify if the emitter should use the "canonical" output format.
2824 *
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.
2833 */
2834
2835YAML_DECLARE(void)
2836yaml_emitter_set_canonical(yaml_emitter_t *emitter, int is_canonical);
2837
2838/*
2839 * Set the intendation increment.
2840 *
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`.
2848 */
2849
2850YAML_DECLARE(void)
2851yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
2852
2853/*
2854 * Set the preferred line width.
2855 *
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.
2865 */
2866
2867YAML_DECLARE(void)
2868yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
2869
2870/*
2871 * Specify if non-ASCII characters could be emitted unescaped.
2872 *
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.
2882 */
2883
2884YAML_DECLARE(void)
2885yaml_emitter_set_unicode(yaml_emitter_t *emitter, int is_unicode);
2886
2887/*
2888 * Set the preferred line break.
2889 *
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.
2897 */
2898
2899YAML_DECLARE(void)
2900yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
2901
2902/*
2903 * Emit an event to the output YAML stream.
2904 *
2905 * An application needs to call this function subsequently to produce a whole
2906 * YAML stream.  The event sequence must satisfy the following grammar:
2907 *
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
2913 *
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.
2934 */
2935
2936YAML_DECLARE(int)
2937yaml_emitter_emit_event(yaml_emitter_t *emitter, yaml_event_t *event);
2938
2939/*
2940 * Start a YAML stream.
2941 *
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.
2945 *
2946 * Arguments:
2947 *
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.
2953 */
2954
2955YAML_DECLARE(int)
2956yaml_emitter_start(yaml_emitter_t *emitter);
2957
2958/*
2959 * Finish a YAML stream.
2960 *
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.
2964 *
2965 * Arguments:
2966 *
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.
2972 */
2973
2974YAML_DECLARE(int)
2975yaml_emitter_end(yaml_emitter_t *emitter);
2976
2977/*
2978 * Emit a YAML document.
2979 *
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.
2983 *
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.
2987 *
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.
3003 */
3004
3005YAML_DECLARE(int)
3006yaml_emitter_emit_document(yaml_emitter_t *emitter, yaml_document_t *document);
3007
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 */
3037
3038YAML_DECLARE(int)
3039yaml_emitter_emit_single_document(yaml_emitter_t *emitter,
3040        yaml_document_t *document);
3041
3042/*
3043 * Flush the accumulated characters.
3044 *
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.
3048 *
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.
3056 */
3057
3058YAML_DECLARE(int)
3059yaml_emitter_flush(yaml_emitter_t *emitter);
3060
3061
3062#ifdef __cplusplus
3063}
3064#endif
3065
3066#endif /* #ifndef YAML_H */
3067
Note: See TracBrowser for help on using the repository browser.