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

Revision 238, 48.1 KB checked in by xi, 8 years ago (diff)

Add functions for constructing, parsing and emitting YAML documents.

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