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