source: trunk/packages/libyaml/include/yaml.h @ 1685

Last change on this file since 1685 was 898, checked in by hartmans, 16 years ago

Add pyyaml and libyaml packages
backported from lenny.
There is discussion about how these should go in the repository; these are added in this form
in order to make forward progress.

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