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

Revision 266, 94.7 KB checked in by xi, 7 years ago (diff)

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

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