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

Revision 261, 46.3 KB checked in by xi, 7 years ago (diff)

API refactoring (Note: it breaks the build).

Line 
1/**
2 * @file yaml.h
3 * @brief Public interface for libyaml.
4 *
5 * Include the header file with the code:
6 * @code
7 * #include <yaml.h>
8 * @endcode
9 */
10
11#ifndef YAML_H
12#define YAML_H
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18#include <stdlib.h>
19#include <stdio.h>
20#include <string.h>
21
22/**
23 * @defgroup export Export Definitions
24 * @{
25 */
26
27/** The public API declaration. */
28
29#ifdef WIN32
30#   if defined(YAML_DECLARE_STATIC)
31#       define  YAML_DECLARE(type)  type
32#   elif defined(YAML_DECLARE_EXPORT)
33#       define  YAML_DECLARE(type)  __declspec(dllexport) type
34#   else
35#       define  YAML_DECLARE(type)  __declspec(dllimport) type
36#   endif
37#else
38#   define  YAML_DECLARE(type)  type
39#endif
40
41/** @} */
42
43/**
44 * @defgroup version Version Information
45 * @{
46 */
47
48/**
49 * Get the library version as a string.
50 *
51 * @returns The function returns the pointer to a static string of the form
52 * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version
53 * number, and @c Z is the patch version number.
54 */
55
56YAML_DECLARE(const char *)
57yaml_get_version_string(void);
58
59/**
60 * Get the library version numbers.
61 *
62 * @param[out]      major   Major version number.
63 * @param[out]      minor   Minor version number.
64 * @param[out]      patch   Patch version number.
65 */
66
67YAML_DECLARE(void)
68yaml_get_version(int *major, int *minor, int *patch);
69
70/** @} */
71
72/**
73 * @defgroup styles Error Handling
74 * @{
75 */
76
77/** Many bad things could happen with the parser and the emitter. */
78typedef enum yaml_error_type_e {
79    /** No error is produced. */
80    YAML_NO_ERROR,
81
82    /** Cannot allocate or reallocate a block of memory. */
83    YAML_MEMORY_ERROR,
84
85    /** Cannot read from the input stream. */
86    YAML_READER_ERROR,
87    /** Cannot decode the input stream. */
88    YAML_DECODER_ERROR,
89
90    /** Cannot scan a YAML token. */
91    YAML_SCANNER_ERROR,
92    /** Cannot parse a YAML production. */
93    YAML_PARSER_ERROR,
94    /** Cannot compose a YAML document. */
95    YAML_COMPOSER_ERROR,
96
97    /** Cannot write into the output stream. */
98    YAML_WRITER_ERROR,
99
100    /** Cannot emit a YAML event. */
101    YAML_EMITTER_ERROR,
102    /** Cannot serialize a YAML document. */
103    YAML_SERIALIZER_ERROR
104} yaml_error_type_t;
105
106/** The pointer position. */
107typedef struct yaml_mark_s {
108    /** The character number (starting from zero). */
109    size_t index;
110
111    /** The mark line (starting from zero). */
112    size_t line;
113
114    /** The mark column (starting from zero). */
115    size_t column;
116} yaml_mark_t;
117
118/** The error details. */
119typedef struct yaml_error_s {
120
121    /** The error type. */
122    yaml_error_type_t type;
123
124    /** The detailed error information. */
125    union {
126
127        /**
128         * A problem while reading the stream (@c YAML_READER_ERROR or
129         * @c YAML_DECODER_ERROR).
130         */
131        struct {
132            /** The problem description. */
133            const char *problem;
134            /** The stream offset. */
135            size_t offset;
136            /** The problematic octet or character (@c -1 if not applicable). */
137            int value;
138        } reading;
139
140        /**
141         * A problem while loading the stream (@c YAML_SCANNER_ERROR,
142         * @c YAML_PARSER_ERROR, or @c YAML_COMPOSER_ERROR).
143         */
144        struct {
145            /** The problem description. */
146            const char *problem;
147            /** The problem mark. */
148            yaml_mark_t problem_mark;
149            /** The context in which the problem occured
150             * (@c NULL if not applicable).
151             */
152            const char *context;
153            /** The context mark (if @c problem_mark is not @c NULL). **/
154            yaml_mark_t context_mark;
155        } loading;
156
157        /** A problem while writing into the stream (@c YAML_WRITER_ERROR). */
158        struct {
159            /** The problem description. */
160            const char *problem;
161            /** The stream offset. */
162            size_t offset;
163        } writing;
164
165        /** A problem while dumping into the stream (@c YAML_EMITTER_ERROR and
166         * @c YAML_SERIALIZER_ERROR).
167         */
168        struct {
169            /** The problem description. */
170            const char *problem;
171        } dumping;
172
173    } data;
174
175} yaml_error_t;
176
177
178/** @} */
179
180/**
181 * @defgroup basic Basic Types
182 * @{
183 */
184
185/** The character type (UTF-8 octet). */
186typedef unsigned char yaml_char_t;
187
188/** The version directive data. */
189typedef struct yaml_version_directive_s {
190    /** The major version number. */
191    int major;
192    /** The minor version number. */
193    int minor;
194} yaml_version_directive_t;
195
196/** The tag directive data. */
197typedef struct yaml_tag_directive_s {
198    /** The tag handle. */
199    yaml_char_t *handle;
200    /** The tag prefix. */
201    yaml_char_t *prefix;
202} yaml_tag_directive_t;
203
204/** The stream encoding. */
205typedef enum yaml_encoding_e {
206    /** Let the parser choose the encoding. */
207    YAML_ANY_ENCODING,
208    /** The default UTF-8 encoding. */
209    YAML_UTF8_ENCODING,
210    /** The UTF-16-LE encoding with BOM. */
211    YAML_UTF16LE_ENCODING,
212    /** The UTF-16-BE encoding with BOM. */
213    YAML_UTF16BE_ENCODING
214} yaml_encoding_t;
215
216/** Line break types. */
217typedef enum yaml_break_e {
218    /** Let the parser choose the break type. */
219    YAML_ANY_BREAK,
220    /** Use CR for line breaks (Mac style). */
221    YAML_CR_BREAK,
222    /** Use LN for line breaks (Unix style). */
223    YAML_LN_BREAK,
224    /** Use CR LN for line breaks (DOS style). */
225    YAML_CRLN_BREAK
226} yaml_break_t;
227
228/** @} */
229
230/**
231 * @defgroup styles Node Styles
232 * @{
233 */
234
235/** Scalar styles. */
236typedef enum yaml_scalar_style_e {
237    /** Let the emitter choose the style. */
238    YAML_ANY_SCALAR_STYLE,
239
240    /** The plain scalar style. */
241    YAML_PLAIN_SCALAR_STYLE,
242
243    /** The single-quoted scalar style. */
244    YAML_SINGLE_QUOTED_SCALAR_STYLE,
245    /** The double-quoted scalar style. */
246    YAML_DOUBLE_QUOTED_SCALAR_STYLE,
247
248    /** The literal scalar style. */
249    YAML_LITERAL_SCALAR_STYLE,
250    /** The folded scalar style. */
251    YAML_FOLDED_SCALAR_STYLE
252} yaml_scalar_style_t;
253
254/** Sequence styles. */
255typedef enum yaml_sequence_style_e {
256    /** Let the emitter choose the style. */
257    YAML_ANY_SEQUENCE_STYLE,
258
259    /** The block sequence style. */
260    YAML_BLOCK_SEQUENCE_STYLE,
261    /** The flow sequence style. */
262    YAML_FLOW_SEQUENCE_STYLE
263} yaml_sequence_style_t;
264
265/** Mapping styles. */
266typedef enum yaml_mapping_style_e {
267    /** Let the emitter choose the style. */
268    YAML_ANY_MAPPING_STYLE,
269
270    /** The block mapping style. */
271    YAML_BLOCK_MAPPING_STYLE,
272    /** The flow mapping style. */
273    YAML_FLOW_MAPPING_STYLE
274/*    YAML_FLOW_SET_MAPPING_STYLE   */
275} yaml_mapping_style_t;
276
277/** @} */
278
279/**
280 * @defgroup tokens Tokens
281 * @{
282 */
283
284/** Token types. */
285typedef enum yaml_token_type_e {
286    /** An empty token. */
287    YAML_NO_TOKEN,
288
289    /** A STREAM-START token. */
290    YAML_STREAM_START_TOKEN,
291    /** A STREAM-END token. */
292    YAML_STREAM_END_TOKEN,
293
294    /** A VERSION-DIRECTIVE token. */
295    YAML_VERSION_DIRECTIVE_TOKEN,
296    /** A TAG-DIRECTIVE token. */
297    YAML_TAG_DIRECTIVE_TOKEN,
298    /** A DOCUMENT-START token. */
299    YAML_DOCUMENT_START_TOKEN,
300    /** A DOCUMENT-END token. */
301    YAML_DOCUMENT_END_TOKEN,
302
303    /** A BLOCK-SEQUENCE-START token. */
304    YAML_BLOCK_SEQUENCE_START_TOKEN,
305    /** A BLOCK-SEQUENCE-END token. */
306    YAML_BLOCK_MAPPING_START_TOKEN,
307    /** A BLOCK-END token. */
308    YAML_BLOCK_END_TOKEN,
309
310    /** A FLOW-SEQUENCE-START token. */
311    YAML_FLOW_SEQUENCE_START_TOKEN,
312    /** A FLOW-SEQUENCE-END token. */
313    YAML_FLOW_SEQUENCE_END_TOKEN,
314    /** A FLOW-MAPPING-START token. */
315    YAML_FLOW_MAPPING_START_TOKEN,
316    /** A FLOW-MAPPING-END token. */
317    YAML_FLOW_MAPPING_END_TOKEN,
318
319    /** A BLOCK-ENTRY token. */
320    YAML_BLOCK_ENTRY_TOKEN,
321    /** A FLOW-ENTRY token. */
322    YAML_FLOW_ENTRY_TOKEN,
323    /** A KEY token. */
324    YAML_KEY_TOKEN,
325    /** A VALUE token. */
326    YAML_VALUE_TOKEN,
327
328    /** An ALIAS token. */
329    YAML_ALIAS_TOKEN,
330    /** An ANCHOR token. */
331    YAML_ANCHOR_TOKEN,
332    /** A TAG token. */
333    YAML_TAG_TOKEN,
334    /** A SCALAR token. */
335    YAML_SCALAR_TOKEN
336} yaml_token_type_t;
337
338/** The token structure. */
339typedef struct yaml_token_s {
340
341    /** The token type. */
342    yaml_token_type_t type;
343
344    /** The token data. */
345    union {
346
347        /** The stream start (for @c YAML_STREAM_START_TOKEN). */
348        struct {
349            /** The stream encoding. */
350            yaml_encoding_t encoding;
351        } stream_start;
352
353        /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
354        struct {
355            /** The major version number. */
356            int major;
357            /** The minor version number. */
358            int minor;
359        } version_directive;
360
361        /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
362        struct {
363            /** The tag handle. */
364            yaml_char_t *handle;
365            /** The tag prefix. */
366            yaml_char_t *prefix;
367        } tag_directive;
368
369        /** The alias (for @c YAML_ALIAS_TOKEN). */
370        struct {
371            /** The alias value. */
372            yaml_char_t *value;
373        } alias;
374
375        /** The anchor (for @c YAML_ANCHOR_TOKEN). */
376        struct {
377            /** The anchor value. */
378            yaml_char_t *value;
379        } anchor;
380
381        /** The tag (for @c YAML_TAG_TOKEN). */
382        struct {
383            /** The tag handle. */
384            yaml_char_t *handle;
385            /** The tag suffix. */
386            yaml_char_t *suffix;
387        } tag;
388
389        /** The scalar value (for @c YAML_SCALAR_TOKEN). */
390        struct {
391            /** The scalar value. */
392            yaml_char_t *value;
393            /** The length of the scalar value. */
394            size_t length;
395            /** The scalar style. */
396            yaml_scalar_style_t style;
397        } scalar;
398
399    } data;
400
401    /** The beginning of the token. */
402    yaml_mark_t start_mark;
403    /** The end of the token. */
404    yaml_mark_t end_mark;
405
406} yaml_token_t;
407
408/**
409 * Allocate a new empty token object.
410 *
411 * @returns a new token object or @c NULL on error.
412 */
413
414YAML_DECLARE(yaml_token_t *)
415yaml_token_new(void);
416
417/**
418 * Delete and deallocate a token object.
419 *
420 * @param[in,out]   token   A token object.
421 */
422
423YAML_DECLARE(void)
424yaml_token_delete(yaml_token_t *token);
425
426/**
427 * Duplicate a token object.
428 *
429 * @param[in,out]   token   An empty token object.
430 * @param[in]       model   A token to copy.
431 *
432 * @returns @c 1 if the function succeeded, @c 0 on error.
433 */
434
435YAML_DECLARE(int)
436yaml_token_duplicate(yaml_token_t *token, yaml_token_t *model);
437
438/**
439 * Free any memory allocated for a token object.
440 *
441 * @param[in,out]   token   A token object.
442 */
443
444YAML_DECLARE(void)
445yaml_token_destroy(yaml_token_t *token);
446
447/** @} */
448
449/**
450 * @defgroup events Events
451 * @{
452 */
453
454/** Event types. */
455typedef enum yaml_event_type_e {
456    /** An empty event. */
457    YAML_NO_EVENT,
458
459    /** A STREAM-START event. */
460    YAML_STREAM_START_EVENT,
461    /** A STREAM-END event. */
462    YAML_STREAM_END_EVENT,
463
464    /** A DOCUMENT-START event. */
465    YAML_DOCUMENT_START_EVENT,
466    /** A DOCUMENT-END event. */
467    YAML_DOCUMENT_END_EVENT,
468
469    /** An ALIAS event. */
470    YAML_ALIAS_EVENT,
471    /** A SCALAR event. */
472    YAML_SCALAR_EVENT,
473
474    /** A SEQUENCE-START event. */
475    YAML_SEQUENCE_START_EVENT,
476    /** A SEQUENCE-END event. */
477    YAML_SEQUENCE_END_EVENT,
478
479    /** A MAPPING-START event. */
480    YAML_MAPPING_START_EVENT,
481    /** A MAPPING-END event. */
482    YAML_MAPPING_END_EVENT
483} yaml_event_type_t;
484
485/** The event structure. */
486typedef struct yaml_event_s {
487
488    /** The event type. */
489    yaml_event_type_t type;
490
491    /** The event data. */
492    union {
493       
494        /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
495        struct {
496            /** The document encoding. */
497            yaml_encoding_t encoding;
498        } stream_start;
499
500        /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
501        struct {
502            /** The version directive. */
503            yaml_version_directive_t *version_directive;
504
505            /** The list of tag directives. */
506            struct {
507                /** The beginning of the list. */
508                yaml_tag_directive_t *list;
509                /** The length of the list. */
510                size_t length;
511                /** The capacity of the list. */
512                size_t capacity;
513            } tag_directives;
514
515            /** Is the document indicator implicit? */
516            int is_implicit;
517        } document_start;
518
519        /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
520        struct {
521            /** Is the document end indicator implicit? */
522            int is_implicit;
523        } document_end;
524
525        /** The alias parameters (for @c YAML_ALIAS_EVENT). */
526        struct {
527            /** The anchor. */
528            yaml_char_t *anchor;
529        } alias;
530
531        /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
532        struct {
533            /** The anchor. */
534            yaml_char_t *anchor;
535            /** The tag. */
536            yaml_char_t *tag;
537            /** The scalar value. */
538            yaml_char_t *value;
539            /** The length of the scalar value. */
540            size_t length;
541            /** Is the tag optional for the plain style? */
542            int is_plain_implicit;
543            /** Is the tag optional for any non-plain style? */
544            int is_quoted_implicit;
545            /** The scalar style. */
546            yaml_scalar_style_t style;
547        } scalar;
548
549        /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
550        struct {
551            /** The anchor. */
552            yaml_char_t *anchor;
553            /** The tag. */
554            yaml_char_t *tag;
555            /** Is the tag optional? */
556            int is_implicit;
557            /** The sequence style. */
558            yaml_sequence_style_t style;
559        } sequence_start;
560
561        /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
562        struct {
563            /** The anchor. */
564            yaml_char_t *anchor;
565            /** The tag. */
566            yaml_char_t *tag;
567            /** Is the tag optional? */
568            int is_implicit;
569            /** The mapping style. */
570            yaml_mapping_style_t style;
571        } mapping_start;
572
573    } data;
574
575    /** The beginning of the event. */
576    yaml_mark_t start_mark;
577    /** The end of the event. */
578    yaml_mark_t end_mark;
579
580} yaml_event_t;
581
582/**
583 * Allocate a new empty event object.
584 *
585 * @returns a new event object or @c NULL on error.
586 */
587
588YAML_DECLARE(yaml_event_t *)
589yaml_event_new(void);
590
591/**
592 * Delete and deallocate an event object.
593 *
594 * @param[in,out]   event   An event object.
595 */
596
597YAML_DECLARE(void)
598yaml_event_delete(yaml_event_t *event);
599
600/**
601 * Duplicate a event object.
602 *
603 * @param[in,out]   event   An empty event object.
604 * @param[in]       model   An event to copy.
605 *
606 * @returns @c 1 if the function succeeded, @c 0 on error.
607 */
608
609YAML_DECLARE(int)
610yaml_event_duplicate(yaml_event_t *event, yaml_event_t *model);
611
612/**
613 * Create a STREAM-START event.
614 *
615 * This function never fails.
616 *
617 * @param[out]      event       An empty event object.
618 * @param[in]       encoding    The stream encoding.
619 *
620 * @returns @c 1 if the function succeeded, @c 0 on error.
621 */
622
623YAML_DECLARE(int)
624yaml_event_create_stream_start(yaml_event_t *event,
625        yaml_encoding_t encoding);
626
627/**
628 * Create a STREAM-END event.
629 *
630 * This function never fails.
631 *
632 * @param[out]      event       An empty event object.
633 *
634 * @returns @c 1 if the function succeeded, @c 0 on error.
635 */
636
637YAML_DECLARE(int)
638yaml_event_create_stream_end(yaml_event_t *event);
639
640/**
641 * Create the DOCUMENT-START event.
642 *
643 * @param[out]      event                   An empty event object.
644 * @param[in]       version_directive       The %YAML directive value or
645 *                                          @c NULL.
646 * @param[in]       tag_directives_list     The beginning of the %TAG
647 *                                          directives list or @c NULL.  The
648 *                                          list ends with @c (NULL,NULL).
649 * @param[in]       is_implicit             Set if the document start
650 *                                          indicator is optional.  This
651 *                                          parameter is stylistic and may be
652 *                                          ignored by the parser.
653 *
654 * @returns @c 1 if the function succeeded, @c 0 on error.
655 */
656
657YAML_DECLARE(int)
658yaml_event_create_document_start(yaml_event_t *event,
659        const yaml_version_directive_t *version_directive,
660        const yaml_tag_directive_t *tag_directives,
661        int is_implicit);
662
663/**
664 * Create the DOCUMENT-END event.
665 *
666 * @param[out]      event       An empty event object.
667 * @param[in]       is_implicit Set if the document end indicator is optional.
668 *                              This parameter is stylistic and may be ignored
669 *                              by the parser.
670 *
671 * @returns @c 1 if the function succeeded, @c 0 on error.
672 */
673
674YAML_DECLARE(int)
675yaml_event_create_document_end(yaml_event_t *event, int is_implicit);
676
677/**
678 * Create an ALIAS event.
679 *
680 * @param[out]      event       An empty event object.
681 * @param[in]       anchor      The anchor value.
682 *
683 * @returns @c 1 if the function succeeded, @c 0 on error.
684 */
685
686YAML_DECLARE(int)
687yaml_event_create_alias(yaml_event_t *event, const yaml_char_t *anchor);
688
689/**
690 * Create a SCALAR event.
691 *
692 * @param[out]      event                   An empty event object.
693 * @param[in]       anchor                  The scalar anchor or @c NULL.
694 * @param[in]       tag                     The scalar tag or @c NULL.  If
695 *                                          latter, one of the
696 *                                          @a is_plain_implicit and
697 *                                          @a is_quoted_implicit flags must
698 *                                          be set.
699 * @param[in]       value                   The scalar value.
700 * @param[in]       length                  The length of the scalar value.
701 * @param[in]       is_plain_implicit       Set if the tag may be omitted for
702 *                                          the plain style.
703 * @param[in]       is_quoted_implicit      Set if the tag may be omitted for
704 *                                          any non-plain style.
705 * @param[in]       style                   The scalar style.  This attribute
706 *                                          may be ignored by the emitter.
707 *
708 * @returns @c 1 if the function succeeded, @c 0 on error.
709 */
710
711YAML_DECLARE(int)
712yaml_event_create_scalar(yaml_event_t *event,
713        const yaml_char_t *anchor, const yaml_char_t *tag,
714        const yaml_char_t *value, size_t length,
715        int is_plain_implicit, int is_quoted_implicit,
716        yaml_scalar_style_t style);
717
718/**
719 * Create a SEQUENCE-START event.
720 *
721 * @param[out]      event       An empty event object.
722 * @param[in]       anchor      The sequence anchor or @c NULL.
723 * @param[in]       tag         The sequence tag or @c NULL.  If latter, the
724 *                              @a is_implicit flag must be set.
725 * @param[in]       is_implicit Set if the tag may be omitted.
726 * @param[in]       style       The sequence style.  This attribute may be
727 *                              ignored by the parser.
728 *
729 * @returns @c 1 if the function succeeded, @c 0 on error.
730 */
731
732YAML_DECLARE(int)
733yaml_event_create_sequence_start(yaml_event_t *event,
734        const yaml_char_t *anchor, const yaml_char_t *tag,
735        int is_implicit, yaml_sequence_style_t style);
736
737/**
738 * Create a SEQUENCE-END event.
739 *
740 * @param[out]      event       An empty event object.
741 *
742 * @returns @c 1 if the function succeeded, @c 0 on error.
743 */
744
745YAML_DECLARE(int)
746yaml_event_create_sequence_end(yaml_event_t *event);
747
748/**
749 * Create a MAPPING-START event.
750 *
751 * @param[out]      event       An empty event object.
752 * @param[in]       anchor      The mapping anchor or @c NULL.
753 * @param[in]       tag         The mapping tag or @c NULL.  If latter, the
754 *                              @a is_implicit flag must be set.
755 * @param[in]       is_implicit Set if the tag may be omitted.
756 * @param[in]       style       The mapping style.
757 *
758 * @returns @c 1 if the function succeeded, @c 0 on error.
759 */
760
761YAML_DECLARE(int)
762yaml_event_create_mapping_start(yaml_event_t *event,
763        const yaml_char_t *anchor, const yaml_char_t *tag,
764        int is_implicit, yaml_mapping_style_t style);
765
766/**
767 * Create a MAPPING-END event.
768 *
769 * @param[out]      event       An empty event object.
770 *
771 * @returns @c 1 if the function succeeded, @c 0 on error.
772 */
773
774YAML_DECLARE(int)
775yaml_event_create_mapping_end(yaml_event_t *event);
776
777/**
778 * Free any memory allocated for an event object.
779 *
780 * @param[in,out]   event   An event object.
781 */
782
783YAML_DECLARE(void)
784yaml_event_destroy(yaml_event_t *event);
785
786/** @} */
787
788/**
789 * @defgroup nodes Nodes
790 * @{
791 */
792
793/** The tag @c !!null with the only possible value: @c null. */
794#define YAML_NULL_TAG       "tag:yaml.org,2002:null"
795/** The tag @c !!bool with the values: @c true and @c falce. */
796#define YAML_BOOL_TAG       "tag:yaml.org,2002:bool"
797/** The tag @c !!str for string values. */
798#define YAML_STR_TAG        "tag:yaml.org,2002:str"
799/** The tag @c !!int for integer values. */
800#define YAML_INT_TAG        "tag:yaml.org,2002:int"
801/** The tag @c !!float for float values. */
802#define YAML_FLOAT_TAG      "tag:yaml.org,2002:float"
803
804/** The tag @c !!seq is used to denote sequences. */
805#define YAML_SEQ_TAG        "tag:yaml.org,2002:seq"
806/** The tag @c !!map is used to denote mapping. */
807#define YAML_MAP_TAG        "tag:yaml.org,2002:map"
808
809/** The default scalar tag is @c !!str. */
810#define YAML_DEFAULT_SCALAR_TAG     YAML_STR_TAG
811/** The default sequence tag is @c !!seq. */
812#define YAML_DEFAULT_SEQUENCE_TAG   YAML_SEQ_TAG
813/** The default mapping tag is @c !!map. */
814#define YAML_DEFAULT_MAPPING_TAG    YAML_MAP_TAG
815
816/** Node types. */
817typedef enum yaml_node_type_e {
818    /** An empty node. */
819    YAML_NO_NODE,
820
821    /** A scalar node. */
822    YAML_SCALAR_NODE,
823    /** A sequence node. */
824    YAML_SEQUENCE_NODE,
825    /** A mapping node. */
826    YAML_MAPPING_NODE
827} yaml_node_type_t;
828
829/** Arc types. */
830typedef enum yaml_arc_type_e {
831    /** An empty arc. */
832    YAML_NO_ARC,
833
834    /** An item of a sequence. */
835    YAML_SEQUENCE_ITEM_ARC,
836    /** A key of a mapping. */
837    YAML_MAPPING_KEY_ARC,
838    /** A value of a mapping. */
839    YAML_MAPPING_VALUE_ARC
840} yaml_arc_type_t;
841
842/** The forward definition of a document node structure. */
843typedef struct yaml_node_s yaml_node_t;
844
845/** An element of a sequence node. */
846typedef int yaml_node_item_t;
847
848/** An element of a mapping node. */
849typedef struct yaml_node_pair_s {
850    /** The key of the element. */
851    int key;
852    /** The value of the element. */
853    int value;
854} yaml_node_pair_t;
855
856/** An element of a path in a YAML document. */
857typedef struct yaml_arc_s {
858    /** The arc type. */
859    yaml_arc_type_t type;
860    /** The collection node. */
861    int node;
862    /** A pointer in the collection node. */
863    int item;
864} yaml_arc_t;
865
866/** The node structure. */
867struct yaml_node_s {
868
869    /** The node type. */
870    yaml_node_type_t type;
871
872    /** The node anchor. */
873    yaml_char_t *anchor;
874    /** The node tag. */
875    yaml_char_t *tag;
876
877    /** The node data. */
878    union {
879       
880        /** The scalar parameters (for @c YAML_SCALAR_NODE). */
881        struct {
882            /** The scalar value. */
883            yaml_char_t *value;
884            /** The length of the scalar value. */
885            size_t length;
886            /** The scalar style. */
887            yaml_scalar_style_t style;
888        } scalar;
889
890        /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
891        struct {
892            /** The list of sequence items. */
893            struct {
894                /** The beginning of the list. */
895                yaml_node_item_t *list;
896                /** The length of the list. */
897                size_t length;
898                /** The capacity of the list. */
899                size_t capacity;
900            } items;
901            /** The sequence style. */
902            yaml_sequence_style_t style;
903        } sequence;
904
905        /** The mapping parameters (for @c YAML_MAPPING_NODE). */
906        struct {
907            /** The list of mapping pairs (key, value). */
908            struct {
909                /** The beginning of the list. */
910                yaml_node_pair_t *list;
911                /** The length of the list. */
912                size_t length;
913                /** The capacity of the list. */
914                size_t capacity;
915            } pairs;
916            /** The mapping style. */
917            yaml_mapping_style_t style;
918        } mapping;
919
920    } data;
921
922    /** The beginning of the node. */
923    yaml_mark_t start_mark;
924    /** The end of the node. */
925    yaml_mark_t end_mark;
926
927};
928
929/** The incomplete node structure. */
930typedef struct yaml_incomplete_node_s {
931
932    /** The node type. */
933    yaml_node_type_t type;
934
935    /** The path to the new node. */
936    struct {
937        /** The beginning of the list. */
938        yaml_arc_t *list;
939        /** The length of the list. */
940        size_t length;
941        /** The capacity of the list. */
942        size_t capacity;
943    } path;
944
945    /** The node data. */
946    union {
947
948        /** The scalar parameters (for @c YAML_SCALAR_NODE). */
949        struct {
950            /** The scalar value. */
951            yaml_char_t *value;
952            /** The length of the scalar value. */
953            size_t length;
954            /** Set if the scalar is plain. */
955            int is_plain;
956        } scalar;
957
958    } data;
959
960    /** The position of the node. */
961    yaml_mark_t mark;
962
963} yaml_incomplete_node_t;
964
965/** The document structure. */
966typedef struct yaml_document_s {
967
968    /** The document nodes. */
969    struct {
970        /** The beginning of the list. */
971        yaml_node_t *list;
972        /** The length of the list. */
973        size_t length;
974        /** The capacity of the list. */
975        size_t capacity;
976    } nodes;
977
978    /** The version directive. */
979    yaml_version_directive_t *version_directive;
980
981    /** The list of tag directives. */
982    struct {
983        /** The beginning of the tag directive list. */
984        yaml_tag_directive_t *list;
985        /** The length of the tag directive list. */
986        size_t length;
987        /** The capacity of the tag directive list. */
988        size_t capacity;
989    } tag_directives;
990
991    /** Is the document start indicator implicit? */
992    int is_start_implicit;
993    /** Is the document end indicator implicit? */
994    int is_end_implicit;
995
996    /** The beginning of the document. */
997    yaml_mark_t start_mark;
998    /** The end of the document. */
999    yaml_mark_t end_mark;
1000
1001} yaml_document_t;
1002
1003#if 0
1004
1005/**
1006 * Allocate a new empty document object.
1007 *
1008 * @returns a new document object or @c NULL on error.
1009 */
1010
1011YAML_DECLARE(yaml_document_t *)
1012yaml_document_new(void);
1013
1014/**
1015 * Delete and deallocatge a document object.
1016 *
1017 * @param[in,out]   document    A document object.
1018 */
1019
1020YAML_DECLARE(void)
1021yaml_document_delete(yaml_document_t *document);
1022
1023/**
1024 * Duplicate a document object.
1025 *
1026 * @param[in,out]   document   An empty document object.
1027 * @param[in]       model       A document to copy.
1028 *
1029 * @returns @c 1 if the function succeeded, @c 0 on error.
1030 */
1031
1032YAML_DECLARE(int)
1033yaml_document_duplicate(yaml_document_t *document, yaml_document_t *model);
1034
1035/**
1036 * Create a YAML document.
1037 *
1038 * @param[out]      document                An empty document object.
1039 * @param[in]       version_directive       The %YAML directive value or
1040 *                                          @c NULL.
1041 * @param[in]       tag_directives          The list of the %TAG directives or
1042 *                                          @c NULL.  The list must end with
1043 *                                          the pair @c (NULL,NULL).
1044 * @param[in]       is_start_implicit       If the document start indicator is
1045 *                                          implicit.
1046 * @param[in]       is_end_implicit         If the document end indicator is
1047 *                                          implicit.
1048 *
1049 * @returns @c 1 if the function succeeded, @c 0 on error.
1050 */
1051
1052YAML_DECLARE(int)
1053yaml_document_create(yaml_document_t *document,
1054        yaml_version_directive_t *version_directive,
1055        yaml_tag_directive_t *tag_directives,
1056        int is_start_implicit, int is_end_implicit);
1057
1058/**
1059 * Delete a YAML document and all its nodes.
1060 *
1061 * @param[in,out]   document        A document object.
1062 */
1063
1064YAML_DECLARE(void)
1065yaml_document_destroy(yaml_document_t *document);
1066
1067/**
1068 * Get a node of a YAML document.
1069 *
1070 * The pointer returned by this function is valid until any of the functions
1071 * modifying the documents is called.
1072 *
1073 * @param[in]       document        A document object.
1074 * @param[in]       index           The node id.
1075 *
1076 * @returns the node objct or @c NULL if @c node_id is out of range.
1077 */
1078
1079YAML_DECLARE(yaml_node_t *)
1080yaml_document_get_node(yaml_document_t *document, int index);
1081
1082/**
1083 * Get the root of a YAML document node.
1084 *
1085 * The root object is the first object added to the document.
1086 *
1087 * The pointer returned by this function is valid until any of the functions
1088 * modifying the documents is called.
1089 *
1090 * An empty document produced by the parser signifies the end of a YAML
1091 * stream.
1092 *
1093 * @param[in]       document        A document object.
1094 *
1095 * @returns the node object or @c NULL if the document is empty.
1096 */
1097
1098YAML_DECLARE(yaml_node_t *)
1099yaml_document_get_root_node(yaml_document_t *document);
1100
1101/**
1102 * Create a SCALAR node and attach it to the document.
1103 *
1104 * The @a style argument may be ignored by the emitter.
1105 *
1106 * @param[in,out]   document        A document object.
1107 * @param[in]       anchor          A preferred anchor for the node or @c NULL.
1108 * @param[in]       tag             The scalar tag.
1109 * @param[in]       value           The scalar value.
1110 * @param[in]       length          The length of the scalar value.
1111 * @param[in]       style           The scalar style.
1112 *
1113 * @returns the node id or @c 0 on error.
1114 */
1115
1116YAML_DECLARE(int)
1117yaml_document_add_scalar(yaml_document_t *document,
1118        yaml_char_t *anchor, yaml_char_t *tag, yaml_char_t *value,
1119        size_t length, yaml_scalar_style_t style);
1120
1121/**
1122 * Create a SEQUENCE node and attach it to the document.
1123 *
1124 * The @a style argument may be ignored by the emitter.
1125 *
1126 * @param[in,out]   document    A document object.
1127 * @param[in]       anchor      A preferred anchor for the node or @c NULL.
1128 * @param[in]       tag         The sequence tag.
1129 * @param[in]       style       The sequence style.
1130 *
1131 * @returns the node id or @c 0 on error.
1132 */
1133
1134YAML_DECLARE(int)
1135yaml_document_add_sequence(yaml_document_t *document,
1136        yaml_char_t *anchor, yaml_char_t *tag, yaml_sequence_style_t style);
1137
1138/**
1139 * Create a MAPPING node and attach it to the document.
1140 *
1141 * The @a style argument may be ignored by the emitter.
1142 *
1143 * @param[in,out]   document    A document object.
1144 * @param[in]       anchor      A preferred anchor for the node or @c NULL.
1145 * @param[in]       tag         The sequence tag.
1146 * @param[in]       style       The sequence style.
1147 *
1148 * @returns the node id or @c 0 on error.
1149 */
1150
1151YAML_DECLARE(int)
1152yaml_document_add_mapping(yaml_document_t *document,
1153        yaml_char_t *anchor, yaml_char_t *tag, yaml_mapping_style_t style);
1154
1155/**
1156 * Add an item to a SEQUENCE node.
1157 *
1158 * @param[in,out]   document    A document object.
1159 * @param[in]       sequence    The sequence node id.
1160 * @param[in]       item        The item node id.
1161*
1162 * @returns @c 1 if the function succeeded, @c 0 on error.
1163 */
1164
1165YAML_DECLARE(int)
1166yaml_document_append_sequence_item(yaml_document_t *document,
1167        int sequence, int item);
1168
1169/**
1170 * Add a pair of a key and a value to a MAPPING node.
1171 *
1172 * @param[in,out]   document    A document object.
1173 * @param[in]       mapping     The mapping node id.
1174 * @param[in]       key         The key node id.
1175 * @param[in]       value       The value node id.
1176*
1177 * @returns @c 1 if the function succeeded, @c 0 on error.
1178 */
1179
1180YAML_DECLARE(int)
1181yaml_document_append_mapping_pair(yaml_document_t *document,
1182        int mapping, int key, int value);
1183
1184#endif
1185
1186/**
1187 * @defgroup callbacks Callback Definitions
1188 * @{
1189 */
1190
1191/**
1192 * The prototype of a read handler.
1193 *
1194 * The read handler is called when the parser needs to read more bytes from the
1195 * source.  The handler should read no more than @a size bytes and write them
1196 * to the @a buffer.  The number of the read bytes should be returned using the
1197 * @a size_read variable.  If the handler reaches the stream end, @a size_read
1198 * must be set to @c 0.
1199 *
1200 * @param[in,out]   data        A pointer to an application data specified by
1201 *                              @c yaml_parser_set_reader().
1202 * @param[out]      buffer      The buffer to write the data from the source.
1203 * @param[in]       capacity    The maximum number of bytes the buffer can hold.
1204 * @param[out]      length      The actual number of bytes read from the source.
1205 *
1206 * @returns On success, the handler should return @c 1.  If the handler failed,
1207 * the returned value should be @c 0.  On EOF, the handler should set the
1208 * @a size_read to @c 0 and return @c 1.
1209 */
1210
1211typedef int yaml_reader_t(void *data, unsigned char *buffer, size_t capacity,
1212        size_t *length);
1213
1214/**
1215 * The prototype of a write handler.
1216 *
1217 * The write handler is called when the emitter needs to flush the accumulated
1218 * characters to the output.  The handler should write @a size bytes of the
1219 * @a buffer to the output.
1220 *
1221 * @param[in,out]   data        A pointer to an application data specified by
1222 *                              @c yaml_emitter_set_writer().
1223 * @param[in]       buffer      The buffer with bytes to be written.
1224 * @param[in]       length      The number of bytes to be written.
1225 *
1226 * @returns On success, the handler should return @c 1.  If the handler failed,
1227 * it should return @c 0.
1228 */
1229
1230typedef int yaml_writer_t(void *data, unsigned char *buffer, size_t length);
1231
1232/**
1233 * The prototype of a tag resolver.
1234 *
1235 * The resolve handler is called when the parser encounters a new node without
1236 * an explicit tag.  The handler should determine the correct tag of the node
1237 * basing on the node kind, the path to the node from the document root and,
1238 * in the case of the scalar node, the node value.  The handler is also called
1239 * by the emitter to determine whether the node tag could be omitted.
1240 *
1241 * @param[in,out]   data        A pointer to an application data specified by
1242 *                              @c yaml_parser_set_writter() or
1243 *                              @c yaml_emitter_set_writer().
1244 * @param[in]       node        Information about the new node.
1245 * @param[out]      tag         The guessed node tag.
1246 *
1247 * @returns On success, the handler should return @c 1.  If the handler failed,
1248 * it should return @c 0.
1249 */
1250
1251typedef int yaml_resolver_t(void *data, yaml_incomplete_node_t *node,
1252        yaml_char_t **tag);
1253
1254/** @} */
1255
1256/**
1257 * @defgroup parser Parser Definitions
1258 * @{
1259 */
1260
1261/** The parser object. */
1262typedef struct yaml_parser_s yaml_parser_t;
1263
1264/**
1265 * Create a new parser object.
1266 *
1267 * This function creates a new parser object.  An application is responsible
1268 * for destroying the object using the @c yaml_parser_delete() function.
1269 *
1270 * @returns a new parser object or @c NULL on error.
1271 */
1272
1273YAML_DECLARE(yaml_parser_t *)
1274yaml_parser_new(void);
1275
1276/**
1277 * Destroy a parser.
1278 *
1279 * @param[in,out]   parser  A parser object.
1280 */
1281
1282YAML_DECLARE(void)
1283yaml_parser_delete(yaml_parser_t *parser);
1284
1285/**
1286 * Get a parser error.
1287 *
1288 * @param[in]   parser  A parser object.
1289 * @param[out]  error   An error object.
1290 */
1291
1292YAML_DECLARE(void)
1293yaml_parser_get_error(yaml_parser_t *parser, yaml_error_t *error);
1294
1295/**
1296 * Set a string input.
1297 *
1298 * Note that the @a input pointer must be valid while the @a parser object
1299 * exists.  The application is responsible for destroing @a input after
1300 * destroying the @a parser.
1301 *
1302 * @param[in,out]   parser  A parser object.
1303 * @param[in]       buffer  A source data.
1304 * @param[in]       length  The length of the source data in bytes.
1305 */
1306
1307YAML_DECLARE(void)
1308yaml_parser_set_string_reader(yaml_parser_t *parser,
1309        const unsigned char *buffer, size_t length);
1310
1311/**
1312 * Set a file input.
1313 *
1314 * @a file should be a file object open for reading.  The application is
1315 * responsible for closing the @a file.
1316 *
1317 * @param[in,out]   parser  A parser object.
1318 * @param[in]       file    An open file.
1319 */
1320
1321YAML_DECLARE(void)
1322yaml_parser_set_file_reader(yaml_parser_t *parser, FILE *file);
1323
1324/**
1325 * Set a generic input handler.
1326 *
1327 * @param[in,out]   parser  A parser object.
1328 * @param[in]       reader  A read handler.
1329 * @param[in]       data    Any application data for passing to the read
1330 *                          handler.
1331 */
1332
1333YAML_DECLARE(void)
1334yaml_parser_set_reader(yaml_parser_t *parser,
1335        yaml_reader_t *reader, void *data);
1336
1337#if 0
1338
1339/**
1340 * Set the standard resolve handler.
1341 *
1342 * The standard resolver recognize the following scalar kinds: !!null, !!bool,
1343 * !!str, !!int and !!float.
1344 *
1345 * @param[in,out]   parser  A parser object.
1346 */
1347
1348YAML_DECLARE(void)
1349yaml_parser_set_standard_resolver(yaml_parser_t *parser);
1350
1351/**
1352 * Set the resolve handler.
1353 *
1354 * The standard resolver recognize the following scalar kinds: !!null, !!bool,
1355 * !!str, !!int and !!float.
1356 *
1357 * @param[in,out]   parser      A parser object.
1358 * @param[in]       resolver    A resolve handler.
1359 * @param[in]       data        Any application data for passing to the resolve
1360 *                              handler.
1361 */
1362
1363YAML_DECLARE(void)
1364yaml_parser_set_resolver(yaml_parser_t *parser,
1365        yaml_resolver_t *resolver, void *data);
1366
1367#endif
1368
1369/**
1370 * Set the source encoding.
1371 *
1372 * @param[in,out]   parser      A parser object.
1373 * @param[in]       encoding    The source encoding.
1374 */
1375
1376YAML_DECLARE(void)
1377yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1378
1379/**
1380 * Scan the input stream and produce the next token.
1381 *
1382 * Call the function subsequently to produce a sequence of tokens corresponding
1383 * to the input stream.  The initial token has the type
1384 * @c YAML_STREAM_START_TOKEN while the ending token has the type
1385 * @c YAML_STREAM_END_TOKEN.
1386 *
1387 * An application is responsible for freeing any buffers associated with the
1388 * produced token object using the @c yaml_token_delete() function.
1389 *
1390 * An application must not alternate the calls of @c yaml_parser_scan() with
1391 * the calls of @c yaml_parser_parse() or @c yaml_parser_load(). Doing this
1392 * will break the parser.
1393 *
1394 * @param[in,out]   parser      A parser object.
1395 * @param[out]      token       An empty token object.
1396 *
1397 * @returns @c 1 if the function succeeded, @c 0 on error.
1398 */
1399
1400YAML_DECLARE(int)
1401yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
1402
1403/**
1404 * Parse the input stream and produce the next parsing event.
1405 *
1406 * Call the function subsequently to produce a sequence of events corresponding
1407 * to the input stream.  The initial event has the type
1408 * @c YAML_STREAM_START_EVENT while the ending event has the type
1409 * @c YAML_STREAM_END_EVENT.
1410 *
1411 * An application is responsible for freeing any buffers associated with the
1412 * produced event object using the @c yaml_event_delete() function.
1413 *
1414 * An application must not alternate the calls of @c yaml_parser_parse() with
1415 * the calls of @c yaml_parser_scan() or @c yaml_parser_load(). Doing this will
1416 * break the parser.
1417 *
1418 * @param[in,out]   parser      A parser object.
1419 * @param[out]      event       An empty event object.
1420 *
1421 * @returns @c 1 if the function succeeded, @c 0 on error.
1422 */
1423
1424YAML_DECLARE(int)
1425yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
1426
1427#if 0
1428
1429/**
1430 * Parse the input stream and produce the next YAML document.
1431 *
1432 * Call this function subsequently to produce a sequence of documents
1433 * constituting the input stream.
1434 *
1435 * If the produced document has no root node, it means that the document
1436 * end has been reached.
1437 *
1438 * An application is responsible for freeing any data associated with the
1439 * produced document object using the @c yaml_document_delete() function.
1440 *
1441 * An application must not alternate the calls of @c yaml_parser_load() with
1442 * the calls of @c yaml_parser_scan() or @c yaml_parser_parse(). Doing this
1443 * will break the parser.
1444 *
1445 * @param[in,out]   parser      A parser object.
1446 * @param[out]      document    An empty document object.
1447 *
1448 * @return @c 1 if the function succeeded, @c 0 on error.
1449 */
1450
1451YAML_DECLARE(int)
1452yaml_parser_load(yaml_parser_t *parser, yaml_document_t *document);
1453
1454#endif
1455
1456/** @} */
1457
1458/**
1459 * @defgroup emitter Emitter Definitions
1460 * @{
1461 */
1462
1463/** The emitter object. */
1464typedef struct yaml_emitter_s yaml_emitter_t;
1465
1466/**
1467 * Create a new emitter object.
1468 *
1469 * This function creates a new emitter object.  An application is responsible
1470 * for destroying the object using the @c yaml_emitter_delete() function.
1471 *
1472 * @returns a new emitter object or @c NULL on error.
1473 */
1474
1475YAML_DECLARE(yaml_emitter_t *)
1476yaml_emitter_new(void);
1477
1478/**
1479 * Destroy an emitter.
1480 *
1481 * @param[in,out]   emitter     An emitter object.
1482 */
1483
1484YAML_DECLARE(void)
1485yaml_emitter_delete(yaml_emitter_t *emitter);
1486
1487/**
1488 * Get an emitter error.
1489 *
1490 * @param[in]   emitter An emitter object.
1491 * @param[out]  error   An error object.
1492 */
1493
1494YAML_DECLARE(void)
1495yaml_emitter_get_error(yaml_emitter_t *emitter, yaml_error_t *error);
1496
1497/**
1498 * Set a string output.
1499 *
1500 * The emitter will write the output characters to the @a output buffer of the
1501 * size @a size.  The emitter will set @a size_written to the number of written
1502 * bytes.  If the buffer is smaller than required, the emitter produces the
1503 * @c YAML_WRITE_ERROR error.
1504 *
1505 * @param[in,out]   emitter         An emitter object.
1506 * @param[in]       buffer          An output buffer.
1507 * @param[in]       length          The pointer to save the number of written
1508 *                                  bytes.
1509 * @param[in]       capacity        The buffer size.
1510 */
1511
1512YAML_DECLARE(void)
1513yaml_emitter_set_string_writer(yaml_emitter_t *emitter,
1514        unsigned char *buffer, size_t *length, size_t capacity);
1515
1516/**
1517 * Set a file output.
1518 *
1519 * @a file should be a file object open for writing.  The application is
1520 * responsible for closing the @a file.
1521 *
1522 * @param[in,out]   emitter     An emitter object.
1523 * @param[in]       file        An open file.
1524 */
1525
1526YAML_DECLARE(void)
1527yaml_emitter_set_file_writer(yaml_emitter_t *emitter, FILE *file);
1528
1529/**
1530 * Set a generic output handler.
1531 *
1532 * @param[in,out]   emitter     An emitter object.
1533 * @param[in]       writer      A write handler.
1534 * @param[in]       data        Any application data for passing to the write
1535 *                              handler.
1536 */
1537
1538YAML_DECLARE(void)
1539yaml_emitter_set_writer(yaml_emitter_t *emitter,
1540        yaml_writer_t *writer, void *data);
1541
1542#if 0
1543
1544/**
1545 * Set the standard resolve handler.
1546 *
1547 * The standard resolver recognize the following scalar kinds: !!null, !!bool,
1548 * !!str, !!int and !!float.
1549 *
1550 * @param[in,out]   emitter An emitter object.
1551 */
1552
1553YAML_DECLARE(void)
1554yaml_emitter_set_standard_resolver(yaml_emitter_t *emitter);
1555
1556/**
1557 * Set the resolve handler.
1558 *
1559 * The standard resolver recognize the following scalar kinds: !!null, !!bool,
1560 * !!str, !!int and !!float.
1561 *
1562 * @param[in,out]   emitter     An emitter object.
1563 * @param[in]       resolver    A resolve handler.
1564 * @param[in]       data        Any application data for passing to the resolve
1565 *                              handler.
1566 */
1567
1568YAML_DECLARE(void)
1569yaml_emitter_set_resolver(yaml_emitter_t *emitter,
1570        yaml_resolver_t *resolver, void *data);
1571
1572#endif
1573
1574/**
1575 * Set the output encoding.
1576 *
1577 * @param[in,out]   emitter     An emitter object.
1578 * @param[in]       encoding    The output encoding.
1579 */
1580
1581YAML_DECLARE(void)
1582yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1583
1584/**
1585 * Set if the output should be in the "canonical" format as in the YAML
1586 * specification.
1587 *
1588 * @param[in,out]   emitter         An emitter object.
1589 * @param[in]       is_canonical    If the output is canonical.
1590 */
1591
1592YAML_DECLARE(void)
1593yaml_emitter_set_canonical(yaml_emitter_t *emitter, int is_canonical);
1594
1595/**
1596 * Set the intendation increment.
1597 *
1598 * @param[in,out]   emitter     An emitter object.
1599 * @param[in]       indent      The indentation increment (1 < . < 10).
1600 */
1601
1602YAML_DECLARE(void)
1603yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1604
1605/**
1606 * Set the preferred line width. @c -1 means unlimited.
1607 *
1608 * @param[in,out]   emitter     An emitter object.
1609 * @param[in]       width       The preferred line width.
1610 */
1611
1612YAML_DECLARE(void)
1613yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1614
1615/**
1616 * Set if unescaped non-ASCII characters are allowed.
1617 *
1618 * @param[in,out]   emitter     An emitter object.
1619 * @param[in]       is_unicode  If unescaped Unicode characters are allowed.
1620 */
1621
1622YAML_DECLARE(void)
1623yaml_emitter_set_unicode(yaml_emitter_t *emitter, int is_unicode);
1624
1625/**
1626 * Set the preferred line break.
1627 *
1628 * @param[in,out]   emitter     An emitter object.
1629 * @param[in]       line_break  The preferred line break.
1630 */
1631
1632YAML_DECLARE(void)
1633yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1634
1635/**
1636 * Emit an event.
1637 *
1638 * The event object may be generated using the yaml_parser_parse() function.
1639 * The emitter takes the responsibility for the event object and destroys its
1640 * content after it is emitted. The event object is destroyed even if the
1641 * function fails.
1642 *
1643 * @param[in,out]   emitter     An emitter object.
1644 * @param[in,out]   event       An event object.
1645 *
1646 * @returns @c 1 if the function succeeded, @c 0 on error.
1647 */
1648
1649YAML_DECLARE(int)
1650yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
1651
1652#if 0
1653
1654/**
1655 * Start a YAML stream.
1656 *
1657 * This function should be used before the first @c yaml_emitter_dump() is
1658 * called.
1659 *
1660 * @param[in,out]   emitter     An emitter object.
1661 *
1662 * @returns @c 1 if the function succeeded, @c 0 on error.
1663 */
1664
1665YAML_DECLARE(int)
1666yaml_emitter_open(yaml_emitter_t *emitter);
1667
1668/**
1669 * Finish a YAML stream.
1670 *
1671 * This function should be used after the last @c yaml_emitter_dump() is
1672 * called.
1673 *
1674 * @param[in,out]   emitter     An emitter object.
1675 *
1676 * @returns @c 1 if the function succeeded, @c 0 on error.
1677 */
1678
1679YAML_DECLARE(int)
1680yaml_emitter_close(yaml_emitter_t *emitter);
1681
1682/**
1683 * Emit a YAML document.
1684 *
1685 * The document object may be generated using the @c yaml_parser_load()
1686 * function or the @c yaml_document_initialize() function.  The emitter takes
1687 * the responsibility for the document object and destoys its content after
1688 * it is emitted. The document object is destroyed even if the function fails.
1689 *
1690 * @param[in,out]   emitter     An emitter object.
1691 * @param[in,out]   document    A document object.
1692 *
1693 * @returns @c 1 if the function succeeded, @c 0 on error.
1694 */
1695
1696YAML_DECLARE(int)
1697yaml_emitter_dump(yaml_emitter_t *emitter, yaml_document_t *document);
1698
1699#endif
1700
1701/**
1702 * Flush the accumulated characters to the output stream.
1703 *
1704 * @param[in,out]   emitter     An emitter object.
1705 *
1706 * @returns @c 1 if the function succeeded, @c 0 on error.
1707 */
1708
1709YAML_DECLARE(int)
1710yaml_emitter_flush(yaml_emitter_t *emitter);
1711
1712/** @} */
1713
1714#ifdef __cplusplus
1715}
1716#endif
1717
1718#endif /* #ifndef YAML_H */
1719
Note: See TracBrowser for help on using the repository browser.