4 yaml_get_version_string(void);
7 yaml_get_version(int *major, int *minor, int *patch);
9 typedef unsigned char yaml_char_t;
11 /** The version directive data. */
12 typedef struct yaml_version_directive_s {
13 /** The major version number. */
15 /** The minor version number. */
17 } yaml_version_directive_t;
19 /** The tag directive data. */
20 typedef struct yaml_tag_directive_s {
21 /** The tag handle. */
23 /** The tag prefix. */
25 } yaml_tag_directive_t;
27 /** The stream encoding. */
28 typedef enum yaml_encoding_e {
29 /** Let the parser choose the encoding. */
31 /** The default UTF-8 encoding. */
33 /** The UTF-16-LE encoding with BOM. */
34 YAML_UTF16LE_ENCODING,
35 /** The UTF-16-BE encoding with BOM. */
39 /** Line break types. */
41 typedef enum yaml_break_e {
42 /** Let the parser choose the break type. */
44 /** Use CR for line breaks (Mac style). */
46 /** Use LN for line breaks (Unix style). */
48 /** Use CR LN for line breaks (DOS style). */
52 /** Many bad things could happen with the parser and emitter. */
53 typedef enum yaml_error_type_e {
54 /** No error is produced. */
57 /** Cannot allocate or reallocate a block of memory. */
60 /** Cannot read or decode the input stream. */
62 /** Cannot scan the input stream. */
64 /** Cannot parse the input stream. */
66 /** Cannot compose a YAML document. */
69 /** Cannot write to the output stream. */
71 /** Cannot emit a YAML stream. */
75 /** The pointer position. */
76 typedef struct yaml_mark_s {
77 /** The position index. */
80 /** The position line. */
83 /** The position column. */
88 typedef enum yaml_scalar_style_e {
89 /** Let the emitter choose the style. */
90 YAML_ANY_SCALAR_STYLE,
92 /** The plain scalar style. */
93 YAML_PLAIN_SCALAR_STYLE,
95 /** The single-quoted scalar style. */
96 YAML_SINGLE_QUOTED_SCALAR_STYLE,
97 /** The double-quoted scalar style. */
98 YAML_DOUBLE_QUOTED_SCALAR_STYLE,
100 /** The literal scalar style. */
101 YAML_LITERAL_SCALAR_STYLE,
102 /** The folded scalar style. */
103 YAML_FOLDED_SCALAR_STYLE
104 } yaml_scalar_style_t;
106 /** Sequence styles. */
107 typedef enum yaml_sequence_style_e {
108 /** Let the emitter choose the style. */
109 YAML_ANY_SEQUENCE_STYLE,
111 /** The block sequence style. */
112 YAML_BLOCK_SEQUENCE_STYLE,
113 /** The flow sequence style. */
114 YAML_FLOW_SEQUENCE_STYLE
115 } yaml_sequence_style_t;
117 /** Mapping styles. */
118 typedef enum yaml_mapping_style_e {
119 /** Let the emitter choose the style. */
120 YAML_ANY_MAPPING_STYLE,
122 /** The block mapping style. */
123 YAML_BLOCK_MAPPING_STYLE,
124 /** The flow mapping style. */
125 YAML_FLOW_MAPPING_STYLE
126 /* YAML_FLOW_SET_MAPPING_STYLE */
127 } yaml_mapping_style_t;
131 typedef enum yaml_token_type_e {
132 /** An empty token. */
135 /** A STREAM-START token. */
136 YAML_STREAM_START_TOKEN,
137 /** A STREAM-END token. */
138 YAML_STREAM_END_TOKEN,
140 /** A VERSION-DIRECTIVE token. */
141 YAML_VERSION_DIRECTIVE_TOKEN,
142 /** A TAG-DIRECTIVE token. */
143 YAML_TAG_DIRECTIVE_TOKEN,
144 /** A DOCUMENT-START token. */
145 YAML_DOCUMENT_START_TOKEN,
146 /** A DOCUMENT-END token. */
147 YAML_DOCUMENT_END_TOKEN,
149 /** A BLOCK-SEQUENCE-START token. */
150 YAML_BLOCK_SEQUENCE_START_TOKEN,
151 /** A BLOCK-SEQUENCE-END token. */
152 YAML_BLOCK_MAPPING_START_TOKEN,
153 /** A BLOCK-END token. */
154 YAML_BLOCK_END_TOKEN,
156 /** A FLOW-SEQUENCE-START token. */
157 YAML_FLOW_SEQUENCE_START_TOKEN,
158 /** A FLOW-SEQUENCE-END token. */
159 YAML_FLOW_SEQUENCE_END_TOKEN,
160 /** A FLOW-MAPPING-START token. */
161 YAML_FLOW_MAPPING_START_TOKEN,
162 /** A FLOW-MAPPING-END token. */
163 YAML_FLOW_MAPPING_END_TOKEN,
165 /** A BLOCK-ENTRY token. */
166 YAML_BLOCK_ENTRY_TOKEN,
167 /** A FLOW-ENTRY token. */
168 YAML_FLOW_ENTRY_TOKEN,
171 /** A VALUE token. */
174 /** An ALIAS token. */
176 /** An ANCHOR token. */
180 /** A SCALAR token. */
184 /** The token structure. */
185 typedef struct yaml_token_s {
187 /** The token type. */
188 yaml_token_type_t type;
190 /** The token data. */
193 /** The stream start (for @c YAML_STREAM_START_TOKEN). */
195 /** The stream encoding. */
196 yaml_encoding_t encoding;
199 /** The alias (for @c YAML_ALIAS_TOKEN). */
201 /** The alias value. */
205 /** The anchor (for @c YAML_ANCHOR_TOKEN). */
207 /** The anchor value. */
211 /** The tag (for @c YAML_TAG_TOKEN). */
213 /** The tag handle. */
215 /** The tag suffix. */
219 /** The scalar value (for @c YAML_SCALAR_TOKEN). */
221 /** The scalar value. */
223 /** The length of the scalar value. */
225 /** The scalar style. */
226 yaml_scalar_style_t style;
229 /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
231 /** The major version number. */
233 /** The minor version number. */
237 /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
239 /** The tag handle. */
241 /** The tag prefix. */
247 /** The beginning of the token. */
248 yaml_mark_t start_mark;
249 /** The end of the token. */
250 yaml_mark_t end_mark;
255 yaml_token_delete(yaml_token_t *token);
258 typedef enum yaml_event_type_e {
259 /** An empty event. */
262 /** A STREAM-START event. */
263 YAML_STREAM_START_EVENT,
264 /** A STREAM-END event. */
265 YAML_STREAM_END_EVENT,
267 /** A DOCUMENT-START event. */
268 YAML_DOCUMENT_START_EVENT,
269 /** A DOCUMENT-END event. */
270 YAML_DOCUMENT_END_EVENT,
272 /** An ALIAS event. */
274 /** A SCALAR event. */
277 /** A SEQUENCE-START event. */
278 YAML_SEQUENCE_START_EVENT,
279 /** A SEQUENCE-END event. */
280 YAML_SEQUENCE_END_EVENT,
282 /** A MAPPING-START event. */
283 YAML_MAPPING_START_EVENT,
284 /** A MAPPING-END event. */
285 YAML_MAPPING_END_EVENT
288 /** The event structure. */
289 typedef struct yaml_event_s {
291 /** The event type. */
292 yaml_event_type_t type;
294 /** The event data. */
297 /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
299 /** The document encoding. */
300 yaml_encoding_t encoding;
303 /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
305 /** The version directive. */
306 yaml_version_directive_t *version_directive;
308 /** The list of tag directives. */
310 /** The beginning of the tag directives list. */
311 yaml_tag_directive_t *start;
312 /** The end of the tag directives list. */
313 yaml_tag_directive_t *end;
316 /** Is the document indicator implicit? */
320 /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
322 /** Is the document end indicator implicit? */
326 /** The alias parameters (for @c YAML_ALIAS_EVENT). */
332 /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
338 /** The scalar value. */
340 /** The length of the scalar value. */
342 /** Is the tag optional for the plain style? */
344 /** Is the tag optional for any non-plain style? */
346 /** The scalar style. */
347 yaml_scalar_style_t style;
350 /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
356 /** Is the tag optional? */
358 /** The sequence style. */
359 yaml_sequence_style_t style;
362 /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
368 /** Is the tag optional? */
370 /** The mapping style. */
371 yaml_mapping_style_t style;
376 /** The beginning of the event. */
377 yaml_mark_t start_mark;
378 /** The end of the event. */
379 yaml_mark_t end_mark;
384 * Create the STREAM-START event.
386 * @param[out] event An empty event object.
387 * @param[in] encoding The stream encoding.
389 * @returns @c 1 if the function succeeded, @c 0 on error.
393 yaml_stream_start_event_initialize(yaml_event_t *event,
394 yaml_encoding_t encoding);
397 * Create the STREAM-END event.
399 * @param[out] event An empty event object.
401 * @returns @c 1 if the function succeeded, @c 0 on error.
405 yaml_stream_end_event_initialize(yaml_event_t *event);
408 * Create the DOCUMENT-START event.
410 * The @a implicit argument is considered as a stylistic parameter and may be
411 * ignored by the emitter.
413 * @param[out] event An empty event object.
414 * @param[in] version_directive The %YAML directive value or
416 * @param[in] tag_directives_start The beginning of the %TAG
418 * @param[in] tag_directives_end The end of the %TAG directives
420 * @param[in] implicit If the document start indicator is
423 * @returns @c 1 if the function succeeded, @c 0 on error.
427 yaml_document_start_event_initialize(yaml_event_t *event,
428 yaml_version_directive_t *version_directive,
429 yaml_tag_directive_t *tag_directives_start,
430 yaml_tag_directive_t *tag_directives_end,
434 * Create the DOCUMENT-END event.
436 * The @a implicit argument is considered as a stylistic parameter and may be
437 * ignored by the emitter.
439 * @param[out] event An empty event object.
440 * @param[in] implicit If the document end indicator is implicit.
442 * @returns @c 1 if the function succeeded, @c 0 on error.
446 yaml_document_end_event_initialize(yaml_event_t *event, int implicit);
449 * Create an ALIAS event.
451 * @param[out] event An empty event object.
452 * @param[in] anchor The anchor value.
454 * @returns @c 1 if the function succeeded, @c 0 on error.
458 yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor);
461 * Create a SCALAR event.
463 * The @a style argument may be ignored by the emitter.
465 * Either the @a tag attribute or one of the @a plain_implicit and
466 * @a quoted_implicit flags must be set.
468 * @param[out] event An empty event object.
469 * @param[in] anchor The scalar anchor or @c NULL.
470 * @param[in] tag The scalar tag or @c NULL.
471 * @param[in] value The scalar value.
472 * @param[in] length The length of the scalar value.
473 * @param[in] plain_implicit If the tag may be omitted for the plain
475 * @param[in] quoted_implicit If the tag may be omitted for any
477 * @param[in] style The scalar style.
479 * @returns @c 1 if the function succeeded, @c 0 on error.
483 yaml_scalar_event_initialize(yaml_event_t *event,
484 yaml_char_t *anchor, yaml_char_t *tag,
485 yaml_char_t *value, int length,
486 int plain_implicit, int quoted_implicit,
487 yaml_scalar_style_t style);
490 * Create a SEQUENCE-START event.
492 * The @a style argument may be ignored by the emitter.
494 * Either the @a tag attribute or the @a implicit flag must be set.
496 * @param[out] event An empty event object.
497 * @param[in] anchor The sequence anchor or @c NULL.
498 * @param[in] tag The sequence tag or @c NULL.
499 * @param[in] implicit If the tag may be omitted.
500 * @param[in] style The sequence style.
502 * @returns @c 1 if the function succeeded, @c 0 on error.
506 yaml_sequence_start_event_initialize(yaml_event_t *event,
507 yaml_char_t *anchor, yaml_char_t *tag, int implicit,
508 yaml_sequence_style_t style);
511 * Create a SEQUENCE-END event.
513 * @param[out] event An empty event object.
515 * @returns @c 1 if the function succeeded, @c 0 on error.
519 yaml_sequence_end_event_initialize(yaml_event_t *event);
522 * Create a MAPPING-START event.
524 * The @a style argument may be ignored by the emitter.
526 * Either the @a tag attribute or the @a implicit flag must be set.
528 * @param[out] event An empty event object.
529 * @param[in] anchor The mapping anchor or @c NULL.
530 * @param[in] tag The mapping tag or @c NULL.
531 * @param[in] implicit If the tag may be omitted.
532 * @param[in] style The mapping style.
534 * @returns @c 1 if the function succeeded, @c 0 on error.
538 yaml_mapping_start_event_initialize(yaml_event_t *event,
539 yaml_char_t *anchor, yaml_char_t *tag, int implicit,
540 yaml_mapping_style_t style);
543 * Create a MAPPING-END event.
545 * @param[out] event An empty event object.
547 * @returns @c 1 if the function succeeded, @c 0 on error.
551 yaml_mapping_end_event_initialize(yaml_event_t *event);
554 * Free any memory allocated for an event object.
556 * @param[in,out] event An event object.
560 yaml_event_delete(yaml_event_t *event);
565 * @defgroup nodes Nodes
569 /** The tag @c !!null with the only possible value: @c null. */
570 #define YAML_NULL_TAG "tag:yaml.org,2002:null"
571 /** The tag @c !!bool with the values: @c true and @c falce. */
572 #define YAML_BOOL_TAG "tag:yaml.org,2002:bool"
573 /** The tag @c !!str for string values. */
574 #define YAML_STR_TAG "tag:yaml.org,2002:str"
575 /** The tag @c !!int for integer values. */
576 #define YAML_INT_TAG "tag:yaml.org,2002:int"
577 /** The tag @c !!float for float values. */
578 #define YAML_FLOAT_TAG "tag:yaml.org,2002:float"
579 /** The tag @c !!timestamp for date and time values. */
580 #define YAML_TIMESTAMP_TAG "tag:yaml.org,2002:timestamp"
582 /** The tag @c !!seq is used to denote sequences. */
583 #define YAML_SEQ_TAG "tag:yaml.org,2002:seq"
584 /** The tag @c !!map is used to denote mapping. */
585 #define YAML_MAP_TAG "tag:yaml.org,2002:map"
587 /** The default scalar tag is @c !!str. */
588 #define YAML_DEFAULT_SCALAR_TAG YAML_STR_TAG
589 /** The default sequence tag is @c !!seq. */
590 #define YAML_DEFAULT_SEQUENCE_TAG YAML_SEQ_TAG
591 /** The default mapping tag is @c !!map. */
592 #define YAML_DEFAULT_MAPPING_TAG YAML_MAP_TAG
595 typedef enum yaml_node_type_e {
596 /** An empty node. */
599 /** A scalar node. */
601 /** A sequence node. */
603 /** A mapping node. */
607 /** The forward definition of a document node structure. */
608 typedef struct yaml_node_s yaml_node_t;
610 /** An element of a sequence node. */
611 typedef int yaml_node_item_t;
613 /** An element of a mapping node. */
614 typedef struct yaml_node_pair_s {
615 /** The key of the element. */
617 /** The value of the element. */
621 /** The node structure. */
624 /** The node type. */
625 yaml_node_type_t type;
630 /** The node data. */
633 /** The scalar parameters (for @c YAML_SCALAR_NODE). */
635 /** The scalar value. */
637 /** The length of the scalar value. */
639 /** The scalar style. */
640 yaml_scalar_style_t style;
643 /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
645 /** The stack of sequence items. */
647 /** The beginning of the stack. */
648 yaml_node_item_t *start;
649 /** The end of the stack. */
650 yaml_node_item_t *end;
651 /** The top of the stack. */
652 yaml_node_item_t *top;
654 /** The sequence style. */
655 yaml_sequence_style_t style;
658 /** The mapping parameters (for @c YAML_MAPPING_NODE). */
660 /** The stack of mapping pairs (key, value). */
662 /** The beginning of the stack. */
663 yaml_node_pair_t *start;
664 /** The end of the stack. */
665 yaml_node_pair_t *end;
666 /** The top of the stack. */
667 yaml_node_pair_t *top;
669 /** The mapping style. */
670 yaml_mapping_style_t style;
675 /** The beginning of the node. */
676 yaml_mark_t start_mark;
677 /** The end of the node. */
678 yaml_mark_t end_mark;
682 /** The document structure. */
683 typedef struct yaml_document_s {
685 /** The document nodes. */
687 /** The beginning of the stack. */
689 /** The end of the stack. */
691 /** The top of the stack. */
695 /** The version directive. */
696 yaml_version_directive_t *version_directive;
698 /** The list of tag directives. */
700 /** The beginning of the tag directives list. */
701 yaml_tag_directive_t *start;
702 /** The end of the tag directives list. */
703 yaml_tag_directive_t *end;
706 /** Is the document start indicator implicit? */
708 /** Is the document end indicator implicit? */
711 /** The beginning of the document. */
712 yaml_mark_t start_mark;
713 /** The end of the document. */
714 yaml_mark_t end_mark;
719 * Create a YAML document.
721 * @param[out] document An empty document object.
722 * @param[in] version_directive The %YAML directive value or
724 * @param[in] tag_directives_start The beginning of the %TAG
726 * @param[in] tag_directives_end The end of the %TAG directives
728 * @param[in] start_implicit If the document start indicator is
730 * @param[in] end_implicit If the document end indicator is
733 * @returns @c 1 if the function succeeded, @c 0 on error.
737 yaml_document_initialize(yaml_document_t *document,
738 yaml_version_directive_t *version_directive,
739 yaml_tag_directive_t *tag_directives_start,
740 yaml_tag_directive_t *tag_directives_end,
741 int start_implicit, int end_implicit);
744 * Delete a YAML document and all its nodes.
746 * @param[in,out] document A document object.
750 yaml_document_delete(yaml_document_t *document);
753 * Get a node of a YAML document.
755 * The pointer returned by this function is valid until any of the functions
756 * modifying the documents are called.
758 * @param[in] document A document object.
759 * @param[in] index The node id.
761 * @returns the node objct or @c NULL if @c node_id is out of range.
765 yaml_document_get_node(yaml_document_t *document, int index);
768 * Get the root of a YAML document node.
770 * The root object is the first object added to the document.
772 * The pointer returned by this function is valid until any of the functions
773 * modifying the documents are called.
775 * An empty document produced by the parser signifies the end of a YAML
778 * @param[in] document A document object.
780 * @returns the node object or @c NULL if the document is empty.
784 yaml_document_get_root_node(yaml_document_t *document);
787 * Create a SCALAR node and attach it to the document.
789 * The @a style argument may be ignored by the emitter.
791 * @param[in,out] document A document object.
792 * @param[in] tag The scalar tag.
793 * @param[in] value The scalar value.
794 * @param[in] length The length of the scalar value.
795 * @param[in] style The scalar style.
797 * @returns the node id or @c 0 on error.
801 yaml_document_add_scalar(yaml_document_t *document,
802 yaml_char_t *tag, yaml_char_t *value, int length,
803 yaml_scalar_style_t style);
806 * Create a SEQUENCE node and attach it to the document.
808 * The @a style argument may be ignored by the emitter.
810 * @param[in,out] document A document object.
811 * @param[in] tag The sequence tag.
812 * @param[in] style The sequence style.
814 * @returns the node id or @c 0 on error.
818 yaml_document_add_sequence(yaml_document_t *document,
819 yaml_char_t *tag, yaml_sequence_style_t style);
822 * Create a MAPPING node and attach it to the document.
824 * The @a style argument may be ignored by the emitter.
826 * @param[in,out] document A document object.
827 * @param[in] tag The sequence tag.
828 * @param[in] style The sequence style.
830 * @returns the node id or @c 0 on error.
834 yaml_document_add_mapping(yaml_document_t *document,
835 yaml_char_t *tag, yaml_mapping_style_t style);
838 * Add an item to a SEQUENCE node.
840 * @param[in,out] document A document object.
841 * @param[in] sequence The sequence node id.
842 * @param[in] item The item node id.
844 * @returns @c 1 if the function succeeded, @c 0 on error.
848 yaml_document_append_sequence_item(yaml_document_t *document,
849 int sequence, int item);
852 * Add a pair of a key and a value to a MAPPING node.
854 * @param[in,out] document A document object.
855 * @param[in] mapping The mapping node id.
856 * @param[in] key The key node id.
857 * @param[in] value The value node id.
859 * @returns @c 1 if the function succeeded, @c 0 on error.
863 yaml_document_append_mapping_pair(yaml_document_t *document,
864 int mapping, int key, int value);
869 * @defgroup parser Parser Definitions
874 * The prototype of a read handler.
876 * The read handler is called when the parser needs to read more bytes from the
877 * source. The handler should write not more than @a size bytes to the @a
878 * buffer. The number of written bytes should be set to the @a length variable.
880 * @param[in,out] data A pointer to an application data specified by
881 * yaml_parser_set_input().
882 * @param[out] buffer The buffer to write the data from the source.
883 * @param[in] size The size of the buffer.
884 * @param[out] size_read The actual number of bytes read from the source.
886 * @returns On success, the handler should return @c 1. If the handler failed,
887 * the returned value should be @c 0. On EOF, the handler should set the
888 * @a size_read to @c 0 and return @c 1.
891 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
895 * This structure holds information about a potential simple key.
898 typedef struct yaml_simple_key_s {
899 /** Is a simple key possible? */
902 /** Is a simple key required? */
905 /** The number of the token. */
908 /** The position mark. */
913 * The states of the parser.
915 typedef enum yaml_parser_state_e {
916 /** Expect STREAM-START. */
917 YAML_PARSE_STREAM_START_STATE,
918 /** Expect the beginning of an implicit document. */
919 YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
920 /** Expect DOCUMENT-START. */
921 YAML_PARSE_DOCUMENT_START_STATE,
922 /** Expect the content of a document. */
923 YAML_PARSE_DOCUMENT_CONTENT_STATE,
924 /** Expect DOCUMENT-END. */
925 YAML_PARSE_DOCUMENT_END_STATE,
926 /** Expect a block node. */
927 YAML_PARSE_BLOCK_NODE_STATE,
928 /** Expect a block node or indentless sequence. */
929 YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
930 /** Expect a flow node. */
931 YAML_PARSE_FLOW_NODE_STATE,
932 /** Expect the first entry of a block sequence. */
933 YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
934 /** Expect an entry of a block sequence. */
935 YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
936 /** Expect an entry of an indentless sequence. */
937 YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
938 /** Expect the first key of a block mapping. */
939 YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
940 /** Expect a block mapping key. */
941 YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
942 /** Expect a block mapping value. */
943 YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
944 /** Expect the first entry of a flow sequence. */
945 YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
946 /** Expect an entry of a flow sequence. */
947 YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
948 /** Expect a key of an ordered mapping. */
949 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
950 /** Expect a value of an ordered mapping. */
951 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
952 /** Expect the and of an ordered mapping entry. */
953 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
954 /** Expect the first key of a flow mapping. */
955 YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
956 /** Expect a key of a flow mapping. */
957 YAML_PARSE_FLOW_MAPPING_KEY_STATE,
958 /** Expect a value of a flow mapping. */
959 YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
960 /** Expect an empty value of a flow mapping. */
961 YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
962 /** Expect nothing. */
964 } yaml_parser_state_t;
967 * This structure holds aliases data.
970 typedef struct yaml_alias_data_s {
975 /** The anchor mark. */
980 * The parser structure.
982 * All members are internal. Manage the structure using the @c yaml_parser_
983 * family of functions.
986 typedef struct yaml_parser_s {
989 * @name Error handling
994 yaml_error_type_t error;
995 /** Error description. */
997 /** The byte about which the problem occured. */
998 size_t problem_offset;
999 /** The problematic value (@c -1 is none). */
1001 /** The problem position. */
1002 yaml_mark_t problem_mark;
1003 /** The error context. */
1004 const char *context;
1005 /** The context position. */
1006 yaml_mark_t context_mark;
1013 * @name Reader stuff
1017 /** Read handler. */
1018 yaml_read_handler_t *read_handler;
1020 /** A pointer for passing to the read handler. */
1021 void *read_handler_data;
1023 /** Standard (string or file) input data. */
1025 /** String input data. */
1027 /** The string start pointer. */
1028 const unsigned char *start;
1029 /** The string end pointer. */
1030 const unsigned char *end;
1031 /** The string current position. */
1032 const unsigned char *current;
1035 /** File input data. */
1042 /** The working buffer. */
1044 /** The beginning of the buffer. */
1046 /** The end of the buffer. */
1048 /** The current position of the buffer. */
1049 yaml_char_t *pointer;
1050 /** The last filled position of the buffer. */
1054 /* The number of unread characters in the buffer. */
1057 /** The raw buffer. */
1059 /** The beginning of the buffer. */
1060 unsigned char *start;
1061 /** The end of the buffer. */
1063 /** The current position of the buffer. */
1064 unsigned char *pointer;
1065 /** The last filled position of the buffer. */
1066 unsigned char *last;
1069 /** The input encoding. */
1070 yaml_encoding_t encoding;
1072 /** The offset of the current position (in bytes). */
1075 /** The mark of the current position. */
1083 * @name Scanner stuff
1087 /** Have we started to scan the input stream? */
1088 int stream_start_produced;
1090 /** Have we reached the end of the input stream? */
1091 int stream_end_produced;
1093 /** The number of unclosed '[' and '{' indicators. */
1096 /** The tokens queue. */
1098 /** The beginning of the tokens queue. */
1099 yaml_token_t *start;
1100 /** The end of the tokens queue. */
1102 /** The head of the tokens queue. */
1104 /** The tail of the tokens queue. */
1108 /** The number of tokens fetched from the queue. */
1109 size_t tokens_parsed;
1111 /* Does the tokens queue contain a token ready for dequeueing. */
1112 int token_available;
1114 /** The indentation levels stack. */
1116 /** The beginning of the stack. */
1118 /** The end of the stack. */
1120 /** The top of the stack. */
1124 /** The current indentation level. */
1127 /** May a simple key occur at the current position? */
1128 int simple_key_allowed;
1130 /** The stack of simple keys. */
1132 /** The beginning of the stack. */
1133 yaml_simple_key_t *start;
1134 /** The end of the stack. */
1135 yaml_simple_key_t *end;
1136 /** The top of the stack. */
1137 yaml_simple_key_t *top;
1145 * @name Parser stuff
1149 /** The parser states stack. */
1151 /** The beginning of the stack. */
1152 yaml_parser_state_t *start;
1153 /** The end of the stack. */
1154 yaml_parser_state_t *end;
1155 /** The top of the stack. */
1156 yaml_parser_state_t *top;
1159 /** The current parser state. */
1160 yaml_parser_state_t state;
1162 /** The stack of marks. */
1164 /** The beginning of the stack. */
1166 /** The end of the stack. */
1168 /** The top of the stack. */
1172 /** The list of TAG directives. */
1174 /** The beginning of the list. */
1175 yaml_tag_directive_t *start;
1176 /** The end of the list. */
1177 yaml_tag_directive_t *end;
1178 /** The top of the list. */
1179 yaml_tag_directive_t *top;
1187 * @name Dumper stuff
1191 /** The alias data. */
1193 /** The beginning of the list. */
1194 yaml_alias_data_t *start;
1195 /** The end of the list. */
1196 yaml_alias_data_t *end;
1197 /** The top of the list. */
1198 yaml_alias_data_t *top;
1201 /** The currently parsed document. */
1202 yaml_document_t *document;
1211 * Initialize a parser.
1213 * This function creates a new parser object. An application is responsible
1214 * for destroying the object using the yaml_parser_delete() function.
1216 * @param[out] parser An empty parser object.
1218 * @returns @c 1 if the function succeeded, @c 0 on error.
1222 yaml_parser_initialize(yaml_parser_t *parser);
1227 * @param[in,out] parser A parser object.
1231 yaml_parser_delete(yaml_parser_t *parser);
1234 * Set a string input.
1236 * Note that the @a input pointer must be valid while the @a parser object
1237 * exists. The application is responsible for destroing @a input after
1238 * destroying the @a parser.
1240 * @param[in,out] parser A parser object.
1241 * @param[in] input A source data.
1242 * @param[in] size The length of the source data in bytes.
1246 yaml_parser_set_input_string(yaml_parser_t *parser,
1247 const unsigned char *input, size_t size);
1252 * @a file should be a file object open for reading. The application is
1253 * responsible for closing the @a file.
1255 * @param[in,out] parser A parser object.
1256 * @param[in] file An open file.
1260 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
1263 * Set a generic input handler.
1265 * @param[in,out] parser A parser object.
1266 * @param[in] handler A read handler.
1267 * @param[in] data Any application data for passing to the read
1272 yaml_parser_set_input(yaml_parser_t *parser,
1273 yaml_read_handler_t *handler, void *data);
1276 * Set the source encoding.
1278 * @param[in,out] parser A parser object.
1279 * @param[in] encoding The source encoding.
1283 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1286 * Scan the input stream and produce the next token.
1288 * Call the function subsequently to produce a sequence of tokens corresponding
1289 * to the input stream. The initial token has the type
1290 * @c YAML_STREAM_START_TOKEN while the ending token has the type
1291 * @c YAML_STREAM_END_TOKEN.
1293 * An application is responsible for freeing any buffers associated with the
1294 * produced token object using the @c yaml_token_delete function.
1296 * An application must not alternate the calls of yaml_parser_scan() with the
1297 * calls of yaml_parser_parse() or yaml_parser_load(). Doing this will break
1300 * @param[in,out] parser A parser object.
1301 * @param[out] token An empty token object.
1303 * @returns @c 1 if the function succeeded, @c 0 on error.
1307 yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
1310 * Parse the input stream and produce the next parsing event.
1312 * Call the function subsequently to produce a sequence of events corresponding
1313 * to the input stream. The initial event has the type
1314 * @c YAML_STREAM_START_EVENT while the ending event has the type
1315 * @c YAML_STREAM_END_EVENT.
1317 * An application is responsible for freeing any buffers associated with the
1318 * produced event object using the yaml_event_delete() function.
1320 * An application must not alternate the calls of yaml_parser_parse() with the
1321 * calls of yaml_parser_scan() or yaml_parser_load(). Doing this will break the
1324 * @param[in,out] parser A parser object.
1325 * @param[out] event An empty event object.
1327 * @returns @c 1 if the function succeeded, @c 0 on error.
1331 yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
1334 * Parse the input stream and produce the next YAML document.
1336 * Call this function subsequently to produce a sequence of documents
1337 * constituting the input stream.
1339 * If the produced document has no root node, it means that the document
1340 * end has been reached.
1342 * An application is responsible for freeing any data associated with the
1343 * produced document object using the yaml_document_delete() function.
1345 * An application must not alternate the calls of yaml_parser_load() with the
1346 * calls of yaml_parser_scan() or yaml_parser_parse(). Doing this will break
1349 * @param[in,out] parser A parser object.
1350 * @param[out] document An empty document object.
1352 * @return @c 1 if the function succeeded, @c 0 on error.
1356 yaml_parser_load(yaml_parser_t *parser, yaml_document_t *document);
1361 * @defgroup emitter Emitter Definitions
1366 * The prototype of a write handler.
1368 * The write handler is called when the emitter needs to flush the accumulated
1369 * characters to the output. The handler should write @a size bytes of the
1370 * @a buffer to the output.
1372 * @param[in,out] data A pointer to an application data specified by
1373 * yaml_emitter_set_output().
1374 * @param[in] buffer The buffer with bytes to be written.
1375 * @param[in] size The size of the buffer.
1377 * @returns On success, the handler should return @c 1. If the handler failed,
1378 * the returned value should be @c 0.
1381 typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size);
1383 /** The emitter states. */
1384 typedef enum yaml_emitter_state_e {
1385 /** Expect STREAM-START. */
1386 YAML_EMIT_STREAM_START_STATE,
1387 /** Expect the first DOCUMENT-START or STREAM-END. */
1388 YAML_EMIT_FIRST_DOCUMENT_START_STATE,
1389 /** Expect DOCUMENT-START or STREAM-END. */
1390 YAML_EMIT_DOCUMENT_START_STATE,
1391 /** Expect the content of a document. */
1392 YAML_EMIT_DOCUMENT_CONTENT_STATE,
1393 /** Expect DOCUMENT-END. */
1394 YAML_EMIT_DOCUMENT_END_STATE,
1395 /** Expect the first item of a flow sequence. */
1396 YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
1397 /** Expect an item of a flow sequence. */
1398 YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
1399 /** Expect the first key of a flow mapping. */
1400 YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
1401 /** Expect a key of a flow mapping. */
1402 YAML_EMIT_FLOW_MAPPING_KEY_STATE,
1403 /** Expect a value for a simple key of a flow mapping. */
1404 YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
1405 /** Expect a value of a flow mapping. */
1406 YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
1407 /** Expect the first item of a block sequence. */
1408 YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
1409 /** Expect an item of a block sequence. */
1410 YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
1411 /** Expect the first key of a block mapping. */
1412 YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
1413 /** Expect the key of a block mapping. */
1414 YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
1415 /** Expect a value for a simple key of a block mapping. */
1416 YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
1417 /** Expect a value of a block mapping. */
1418 YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
1419 /** Expect nothing. */
1421 } yaml_emitter_state_t;
1424 * The emitter structure.
1426 * All members are internal. Manage the structure using the @c yaml_emitter_
1427 * family of functions.
1430 typedef struct yaml_emitter_s {
1433 * @name Error handling
1438 yaml_error_type_t error;
1439 /** Error description. */
1440 const char *problem;
1447 * @name Writer stuff
1451 /** Write handler. */
1452 yaml_write_handler_t *write_handler;
1454 /** A pointer for passing to the white handler. */
1455 void *write_handler_data;
1457 /** Standard (string or file) output data. */
1459 /** String output data. */
1461 /** The buffer pointer. */
1462 unsigned char *buffer;
1463 /** The buffer size. */
1465 /** The number of written bytes. */
1466 size_t *size_written;
1469 /** File output data. */
1473 /** The working buffer. */
1475 /** The beginning of the buffer. */
1477 /** The end of the buffer. */
1479 /** The current position of the buffer. */
1480 yaml_char_t *pointer;
1481 /** The last filled position of the buffer. */
1485 /** The raw buffer. */
1487 /** The beginning of the buffer. */
1488 unsigned char *start;
1489 /** The end of the buffer. */
1491 /** The current position of the buffer. */
1492 unsigned char *pointer;
1493 /** The last filled position of the buffer. */
1494 unsigned char *last;
1497 /** The stream encoding. */
1498 yaml_encoding_t encoding;
1505 * @name Emitter stuff
1509 /** If the output is in the canonical style? */
1511 /** The number of indentation spaces. */
1513 /** The preferred width of the output lines. */
1515 /** Allow unescaped non-ASCII characters? */
1517 /** The preferred line break. */
1518 yaml_break_t line_break;
1520 /** The stack of states. */
1522 /** The beginning of the stack. */
1523 yaml_emitter_state_t *start;
1524 /** The end of the stack. */
1525 yaml_emitter_state_t *end;
1526 /** The top of the stack. */
1527 yaml_emitter_state_t *top;
1530 /** The current emitter state. */
1531 yaml_emitter_state_t state;
1533 /** The event queue. */
1535 /** The beginning of the event queue. */
1536 yaml_event_t *start;
1537 /** The end of the event queue. */
1539 /** The head of the event queue. */
1541 /** The tail of the event queue. */
1545 /** The stack of indentation levels. */
1547 /** The beginning of the stack. */
1549 /** The end of the stack. */
1551 /** The top of the stack. */
1555 /** The list of tag directives. */
1557 /** The beginning of the list. */
1558 yaml_tag_directive_t *start;
1559 /** The end of the list. */
1560 yaml_tag_directive_t *end;
1561 /** The top of the list. */
1562 yaml_tag_directive_t *top;
1565 /** The current indentation level. */
1568 /** The current flow level. */
1571 /** Is it the document root context? */
1573 /** Is it a sequence context? */
1574 int sequence_context;
1575 /** Is it a mapping context? */
1576 int mapping_context;
1577 /** Is it a simple mapping key context? */
1578 int simple_key_context;
1580 /** The current line. */
1582 /** The current column. */
1584 /** If the last character was a whitespace? */
1586 /** If the last character was an indentation character (' ', '-', '?', ':')? */
1588 /** If an explicit document end is required? */
1591 /** Anchor analysis. */
1593 /** The anchor value. */
1594 yaml_char_t *anchor;
1595 /** The anchor length. */
1596 size_t anchor_length;
1597 /** Is it an alias? */
1601 /** Tag analysis. */
1603 /** The tag handle. */
1604 yaml_char_t *handle;
1605 /** The tag handle length. */
1606 size_t handle_length;
1607 /** The tag suffix. */
1608 yaml_char_t *suffix;
1609 /** The tag suffix length. */
1610 size_t suffix_length;
1613 /** Scalar analysis. */
1615 /** The scalar value. */
1617 /** The scalar length. */
1619 /** Does the scalar contain line breaks? */
1621 /** Can the scalar be expessed in the flow plain style? */
1622 int flow_plain_allowed;
1623 /** Can the scalar be expressed in the block plain style? */
1624 int block_plain_allowed;
1625 /** Can the scalar be expressed in the single quoted style? */
1626 int single_quoted_allowed;
1627 /** Can the scalar be expressed in the literal or folded styles? */
1629 /** The output style. */
1630 yaml_scalar_style_t style;
1638 * @name Dumper stuff
1642 /** If the stream was already opened? */
1644 /** If the stream was already closed? */
1647 /** The information associated with the document nodes. */
1649 /** The number of references. */
1651 /** The anchor id. */
1653 /** If the node has been emitted? */
1657 /** The last assigned anchor id. */
1660 /** The currently emitted document. */
1661 yaml_document_t *document;
1670 * Initialize an emitter.
1672 * This function creates a new emitter object. An application is responsible
1673 * for destroying the object using the yaml_emitter_delete() function.
1675 * @param[out] emitter An empty parser object.
1677 * @returns @c 1 if the function succeeded, @c 0 on error.
1681 yaml_emitter_initialize(yaml_emitter_t *emitter);
1684 * Destroy an emitter.
1686 * @param[in,out] emitter An emitter object.
1690 yaml_emitter_delete(yaml_emitter_t *emitter);
1693 * Set a string output.
1695 * The emitter will write the output characters to the @a output buffer of the
1696 * size @a size. The emitter will set @a size_written to the number of written
1697 * bytes. If the buffer is smaller than required, the emitter produces the
1698 * YAML_WRITE_ERROR error.
1700 * @param[in,out] emitter An emitter object.
1701 * @param[in] output An output buffer.
1702 * @param[in] size The buffer size.
1703 * @param[in] size_written The pointer to save the number of written
1708 yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1709 unsigned char *output, size_t size, size_t *size_written);
1712 * Set a file output.
1714 * @a file should be a file object open for writing. The application is
1715 * responsible for closing the @a file.
1717 * @param[in,out] emitter An emitter object.
1718 * @param[in] file An open file.
1722 yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1725 * Set a generic output handler.
1727 * @param[in,out] emitter An emitter object.
1728 * @param[in] handler A write handler.
1729 * @param[in] data Any application data for passing to the write
1734 yaml_emitter_set_output(yaml_emitter_t *emitter,
1735 yaml_write_handler_t *handler, void *data);
1738 * Set the output encoding.
1740 * @param[in,out] emitter An emitter object.
1741 * @param[in] encoding The output encoding.
1745 yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1748 * Set if the output should be in the "canonical" format as in the YAML
1751 * @param[in,out] emitter An emitter object.
1752 * @param[in] canonical If the output is canonical.
1756 yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1759 * Set the intendation increment.
1761 * @param[in,out] emitter An emitter object.
1762 * @param[in] indent The indentation increment (1 < . < 10).
1766 yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1769 * Set the preferred line width. @c -1 means unlimited.
1771 * @param[in,out] emitter An emitter object.
1772 * @param[in] width The preferred line width.
1776 yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1779 * Set if unescaped non-ASCII characters are allowed.
1781 * @param[in,out] emitter An emitter object.
1782 * @param[in] unicode If unescaped Unicode characters are allowed.
1786 yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1789 * Set the preferred line break.
1791 * @param[in,out] emitter An emitter object.
1792 * @param[in] line_break The preferred line break.
1796 yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1801 * The event object may be generated using the yaml_parser_parse() function.
1802 * The emitter takes the responsibility for the event object and destroys its
1803 * content after it is emitted. The event object is destroyed even if the
1806 * @param[in,out] emitter An emitter object.
1807 * @param[in,out] event An event object.
1809 * @returns @c 1 if the function succeeded, @c 0 on error.
1813 yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
1816 * Start a YAML stream.
1818 * This function should be used before yaml_emitter_dump() is called.
1820 * @param[in,out] emitter An emitter object.
1822 * @returns @c 1 if the function succeeded, @c 0 on error.
1826 yaml_emitter_open(yaml_emitter_t *emitter);
1829 * Finish a YAML stream.
1831 * This function should be used after yaml_emitter_dump() is called.
1833 * @param[in,out] emitter An emitter object.
1835 * @returns @c 1 if the function succeeded, @c 0 on error.
1839 yaml_emitter_close(yaml_emitter_t *emitter);
1842 * Emit a YAML document.
1844 * The documen object may be generated using the yaml_parser_load() function
1845 * or the yaml_document_initialize() function. The emitter takes the
1846 * responsibility for the document object and destoys its content after
1847 * it is emitted. The document object is destroyedeven if the function fails.
1849 * @param[in,out] emitter An emitter object.
1850 * @param[in,out] document A document object.
1852 * @returns @c 1 if the function succeeded, @c 0 on error.
1856 yaml_emitter_dump(yaml_emitter_t *emitter, yaml_document_t *document);
1859 * Flush the accumulated characters to the output.
1861 * @param[in,out] emitter An emitter object.
1863 * @returns @c 1 if the function succeeded, @c 0 on error.
1867 yaml_emitter_flush(yaml_emitter_t *emitter);