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

Revision 265, 47.7 KB checked in by xi, 6 years ago (diff)

Fixed bugs and updated tests.

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