3 * @brief Public interface for libyaml.
5 * Include the header file with the code:
23 * @defgroup export Export Definitions
27 /** The public API declaration. */
30 # if defined(YAML_DECLARE_STATIC)
31 # define YAML_DECLARE(type) type
32 # elif defined(YAML_DECLARE_EXPORT)
33 # define YAML_DECLARE(type) __declspec(dllexport) type
35 # define YAML_DECLARE(type) __declspec(dllimport) type
38 # define YAML_DECLARE(type) type
44 * @defgroup version Version Information
49 * Get the library version as a string.
51 * @returns The function returns the pointer to a static string of the form
52 * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version
53 * number, and @c Z is the patch version number.
56 YAML_DECLARE(const char *)
57 yaml_get_version_string(void);
60 * Get the library version numbers.
62 * @param[out] major Major version number.
63 * @param[out] minor Minor version number.
64 * @param[out] patch Patch version number.
68 yaml_get_version(int *major, int *minor, int *patch);
73 * @defgroup basic Basic Types
77 /** The character type (UTF-8 octet). */
78 typedef unsigned char yaml_char_t;
80 /** The version directive data. */
81 typedef struct yaml_version_directive_s {
82 /** The major version number. */
84 /** The minor version number. */
86 } yaml_version_directive_t;
88 /** The tag directive data. */
89 typedef struct yaml_tag_directive_s {
90 /** The tag handle. */
92 /** The tag prefix. */
94 } yaml_tag_directive_t;
96 /** The stream encoding. */
97 typedef enum yaml_encoding_e {
98 /** Let the parser choose the encoding. */
100 /** The default UTF-8 encoding. */
102 /** The UTF-16-LE encoding with BOM. */
103 YAML_UTF16LE_ENCODING,
104 /** The UTF-16-BE encoding with BOM. */
105 YAML_UTF16BE_ENCODING
108 /** Line break types. */
110 typedef enum yaml_break_e {
111 /** Let the parser choose the break type. */
113 /** Use CR for line breaks (Mac style). */
115 /** Use LN for line breaks (Unix style). */
117 /** Use CR LN for line breaks (DOS style). */
121 /** Many bad things could happen with the parser and emitter. */
122 typedef enum yaml_error_type_e {
123 /** No error is produced. */
126 /** Cannot allocate or reallocate a block of memory. */
129 /** Cannot read or decode the input stream. */
131 /** Cannot scan the input stream. */
133 /** Cannot parse the input stream. */
135 /** Cannot compose a YAML document. */
138 /** Cannot write to the output stream. */
140 /** Cannot emit a YAML stream. */
144 /** The pointer position. */
145 typedef struct yaml_mark_s {
146 /** The position index. */
149 /** The position line. */
152 /** The position column. */
159 * @defgroup styles Node Styles
163 /** Scalar styles. */
164 typedef enum yaml_scalar_style_e {
165 /** Let the emitter choose the style. */
166 YAML_ANY_SCALAR_STYLE,
168 /** The plain scalar style. */
169 YAML_PLAIN_SCALAR_STYLE,
171 /** The single-quoted scalar style. */
172 YAML_SINGLE_QUOTED_SCALAR_STYLE,
173 /** The double-quoted scalar style. */
174 YAML_DOUBLE_QUOTED_SCALAR_STYLE,
176 /** The literal scalar style. */
177 YAML_LITERAL_SCALAR_STYLE,
178 /** The folded scalar style. */
179 YAML_FOLDED_SCALAR_STYLE
180 } yaml_scalar_style_t;
182 /** Sequence styles. */
183 typedef enum yaml_sequence_style_e {
184 /** Let the emitter choose the style. */
185 YAML_ANY_SEQUENCE_STYLE,
187 /** The block sequence style. */
188 YAML_BLOCK_SEQUENCE_STYLE,
189 /** The flow sequence style. */
190 YAML_FLOW_SEQUENCE_STYLE
191 } yaml_sequence_style_t;
193 /** Mapping styles. */
194 typedef enum yaml_mapping_style_e {
195 /** Let the emitter choose the style. */
196 YAML_ANY_MAPPING_STYLE,
198 /** The block mapping style. */
199 YAML_BLOCK_MAPPING_STYLE,
200 /** The flow mapping style. */
201 YAML_FLOW_MAPPING_STYLE
202 /* YAML_FLOW_SET_MAPPING_STYLE */
203 } yaml_mapping_style_t;
208 * @defgroup tokens Tokens
213 typedef enum yaml_token_type_e {
214 /** An empty token. */
217 /** A STREAM-START token. */
218 YAML_STREAM_START_TOKEN,
219 /** A STREAM-END token. */
220 YAML_STREAM_END_TOKEN,
222 /** A VERSION-DIRECTIVE token. */
223 YAML_VERSION_DIRECTIVE_TOKEN,
224 /** A TAG-DIRECTIVE token. */
225 YAML_TAG_DIRECTIVE_TOKEN,
226 /** A DOCUMENT-START token. */
227 YAML_DOCUMENT_START_TOKEN,
228 /** A DOCUMENT-END token. */
229 YAML_DOCUMENT_END_TOKEN,
231 /** A BLOCK-SEQUENCE-START token. */
232 YAML_BLOCK_SEQUENCE_START_TOKEN,
233 /** A BLOCK-SEQUENCE-END token. */
234 YAML_BLOCK_MAPPING_START_TOKEN,
235 /** A BLOCK-END token. */
236 YAML_BLOCK_END_TOKEN,
238 /** A FLOW-SEQUENCE-START token. */
239 YAML_FLOW_SEQUENCE_START_TOKEN,
240 /** A FLOW-SEQUENCE-END token. */
241 YAML_FLOW_SEQUENCE_END_TOKEN,
242 /** A FLOW-MAPPING-START token. */
243 YAML_FLOW_MAPPING_START_TOKEN,
244 /** A FLOW-MAPPING-END token. */
245 YAML_FLOW_MAPPING_END_TOKEN,
247 /** A BLOCK-ENTRY token. */
248 YAML_BLOCK_ENTRY_TOKEN,
249 /** A FLOW-ENTRY token. */
250 YAML_FLOW_ENTRY_TOKEN,
253 /** A VALUE token. */
256 /** An ALIAS token. */
258 /** An ANCHOR token. */
262 /** A SCALAR token. */
266 /** The token structure. */
267 typedef struct yaml_token_s {
269 /** The token type. */
270 yaml_token_type_t type;
272 /** The token data. */
275 /** The stream start (for @c YAML_STREAM_START_TOKEN). */
277 /** The stream encoding. */
278 yaml_encoding_t encoding;
281 /** The alias (for @c YAML_ALIAS_TOKEN). */
283 /** The alias value. */
287 /** The anchor (for @c YAML_ANCHOR_TOKEN). */
289 /** The anchor value. */
293 /** The tag (for @c YAML_TAG_TOKEN). */
295 /** The tag handle. */
297 /** The tag suffix. */
301 /** The scalar value (for @c YAML_SCALAR_TOKEN). */
303 /** The scalar value. */
305 /** The length of the scalar value. */
307 /** The scalar style. */
308 yaml_scalar_style_t style;
311 /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
313 /** The major version number. */
315 /** The minor version number. */
319 /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
321 /** The tag handle. */
323 /** The tag prefix. */
329 /** The beginning of the token. */
330 yaml_mark_t start_mark;
331 /** The end of the token. */
332 yaml_mark_t end_mark;
337 * Free any memory allocated for a token object.
339 * @param[in,out] token A token object.
343 yaml_token_delete(yaml_token_t *token);
348 * @defgroup events Events
353 typedef enum yaml_event_type_e {
354 /** An empty event. */
357 /** A STREAM-START event. */
358 YAML_STREAM_START_EVENT,
359 /** A STREAM-END event. */
360 YAML_STREAM_END_EVENT,
362 /** A DOCUMENT-START event. */
363 YAML_DOCUMENT_START_EVENT,
364 /** A DOCUMENT-END event. */
365 YAML_DOCUMENT_END_EVENT,
367 /** An ALIAS event. */
369 /** A SCALAR event. */
372 /** A SEQUENCE-START event. */
373 YAML_SEQUENCE_START_EVENT,
374 /** A SEQUENCE-END event. */
375 YAML_SEQUENCE_END_EVENT,
377 /** A MAPPING-START event. */
378 YAML_MAPPING_START_EVENT,
379 /** A MAPPING-END event. */
380 YAML_MAPPING_END_EVENT
383 /** The event structure. */
384 typedef struct yaml_event_s {
386 /** The event type. */
387 yaml_event_type_t type;
389 /** The event data. */
392 /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
394 /** The document encoding. */
395 yaml_encoding_t encoding;
398 /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
400 /** The version directive. */
401 yaml_version_directive_t *version_directive;
403 /** The list of tag directives. */
405 /** The beginning of the tag directives list. */
406 yaml_tag_directive_t *start;
407 /** The end of the tag directives list. */
408 yaml_tag_directive_t *end;
411 /** Is the document indicator implicit? */
415 /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
417 /** Is the document end indicator implicit? */
421 /** The alias parameters (for @c YAML_ALIAS_EVENT). */
427 /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
433 /** The scalar value. */
435 /** The length of the scalar value. */
437 /** Is the tag optional for the plain style? */
439 /** Is the tag optional for any non-plain style? */
441 /** The scalar style. */
442 yaml_scalar_style_t style;
445 /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
451 /** Is the tag optional? */
453 /** The sequence style. */
454 yaml_sequence_style_t style;
457 /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
463 /** Is the tag optional? */
465 /** The mapping style. */
466 yaml_mapping_style_t style;
471 /** The beginning of the event. */
472 yaml_mark_t start_mark;
473 /** The end of the event. */
474 yaml_mark_t end_mark;
479 * Create the STREAM-START event.
481 * @param[out] event An empty event object.
482 * @param[in] encoding The stream encoding.
484 * @returns @c 1 if the function succeeded, @c 0 on error.
488 yaml_stream_start_event_initialize(yaml_event_t *event,
489 yaml_encoding_t encoding);
492 * Create the STREAM-END event.
494 * @param[out] event An empty event object.
496 * @returns @c 1 if the function succeeded, @c 0 on error.
500 yaml_stream_end_event_initialize(yaml_event_t *event);
503 * Create the DOCUMENT-START event.
505 * The @a implicit argument is considered as a stylistic parameter and may be
506 * ignored by the emitter.
508 * @param[out] event An empty event object.
509 * @param[in] version_directive The %YAML directive value or
511 * @param[in] tag_directives_start The beginning of the %TAG
513 * @param[in] tag_directives_end The end of the %TAG directives
515 * @param[in] implicit If the document start indicator is
518 * @returns @c 1 if the function succeeded, @c 0 on error.
522 yaml_document_start_event_initialize(yaml_event_t *event,
523 yaml_version_directive_t *version_directive,
524 yaml_tag_directive_t *tag_directives_start,
525 yaml_tag_directive_t *tag_directives_end,
529 * Create the DOCUMENT-END event.
531 * The @a implicit argument is considered as a stylistic parameter and may be
532 * ignored by the emitter.
534 * @param[out] event An empty event object.
535 * @param[in] implicit If the document end indicator is implicit.
537 * @returns @c 1 if the function succeeded, @c 0 on error.
541 yaml_document_end_event_initialize(yaml_event_t *event, int implicit);
544 * Create an ALIAS event.
546 * @param[out] event An empty event object.
547 * @param[in] anchor The anchor value.
549 * @returns @c 1 if the function succeeded, @c 0 on error.
553 yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor);
556 * Create a SCALAR event.
558 * The @a style argument may be ignored by the emitter.
560 * Either the @a tag attribute or one of the @a plain_implicit and
561 * @a quoted_implicit flags must be set.
563 * @param[out] event An empty event object.
564 * @param[in] anchor The scalar anchor or @c NULL.
565 * @param[in] tag The scalar tag or @c NULL.
566 * @param[in] value The scalar value.
567 * @param[in] length The length of the scalar value.
568 * @param[in] plain_implicit If the tag may be omitted for the plain
570 * @param[in] quoted_implicit If the tag may be omitted for any
572 * @param[in] style The scalar style.
574 * @returns @c 1 if the function succeeded, @c 0 on error.
578 yaml_scalar_event_initialize(yaml_event_t *event,
579 yaml_char_t *anchor, yaml_char_t *tag,
580 yaml_char_t *value, int length,
581 int plain_implicit, int quoted_implicit,
582 yaml_scalar_style_t style);
585 * Create a SEQUENCE-START event.
587 * The @a style argument may be ignored by the emitter.
589 * Either the @a tag attribute or the @a implicit flag must be set.
591 * @param[out] event An empty event object.
592 * @param[in] anchor The sequence anchor or @c NULL.
593 * @param[in] tag The sequence tag or @c NULL.
594 * @param[in] implicit If the tag may be omitted.
595 * @param[in] style The sequence style.
597 * @returns @c 1 if the function succeeded, @c 0 on error.
601 yaml_sequence_start_event_initialize(yaml_event_t *event,
602 yaml_char_t *anchor, yaml_char_t *tag, int implicit,
603 yaml_sequence_style_t style);
606 * Create a SEQUENCE-END event.
608 * @param[out] event An empty event object.
610 * @returns @c 1 if the function succeeded, @c 0 on error.
614 yaml_sequence_end_event_initialize(yaml_event_t *event);
617 * Create a MAPPING-START event.
619 * The @a style argument may be ignored by the emitter.
621 * Either the @a tag attribute or the @a implicit flag must be set.
623 * @param[out] event An empty event object.
624 * @param[in] anchor The mapping anchor or @c NULL.
625 * @param[in] tag The mapping tag or @c NULL.
626 * @param[in] implicit If the tag may be omitted.
627 * @param[in] style The mapping style.
629 * @returns @c 1 if the function succeeded, @c 0 on error.
633 yaml_mapping_start_event_initialize(yaml_event_t *event,
634 yaml_char_t *anchor, yaml_char_t *tag, int implicit,
635 yaml_mapping_style_t style);
638 * Create a MAPPING-END event.
640 * @param[out] event An empty event object.
642 * @returns @c 1 if the function succeeded, @c 0 on error.
646 yaml_mapping_end_event_initialize(yaml_event_t *event);
649 * Free any memory allocated for an event object.
651 * @param[in,out] event An event object.
655 yaml_event_delete(yaml_event_t *event);
660 * @defgroup nodes Nodes
664 /** The tag @c !!null with the only possible value: @c null. */
665 #define YAML_NULL_TAG "tag:yaml.org,2002:null"
666 /** The tag @c !!bool with the values: @c true and @c falce. */
667 #define YAML_BOOL_TAG "tag:yaml.org,2002:bool"
668 /** The tag @c !!str for string values. */
669 #define YAML_STR_TAG "tag:yaml.org,2002:str"
670 /** The tag @c !!int for integer values. */
671 #define YAML_INT_TAG "tag:yaml.org,2002:int"
672 /** The tag @c !!float for float values. */
673 #define YAML_FLOAT_TAG "tag:yaml.org,2002:float"
674 /** The tag @c !!timestamp for date and time values. */
675 #define YAML_TIMESTAMP_TAG "tag:yaml.org,2002:timestamp"
677 /** The tag @c !!seq is used to denote sequences. */
678 #define YAML_SEQ_TAG "tag:yaml.org,2002:seq"
679 /** The tag @c !!map is used to denote mapping. */
680 #define YAML_MAP_TAG "tag:yaml.org,2002:map"
682 /** The default scalar tag is @c !!str. */
683 #define YAML_DEFAULT_SCALAR_TAG YAML_STR_TAG
684 /** The default sequence tag is @c !!seq. */
685 #define YAML_DEFAULT_SEQUENCE_TAG YAML_SEQ_TAG
686 /** The default mapping tag is @c !!map. */
687 #define YAML_DEFAULT_MAPPING_TAG YAML_MAP_TAG
690 typedef enum yaml_node_type_e {
691 /** An empty node. */
694 /** A scalar node. */
696 /** A sequence node. */
698 /** A mapping node. */
702 /** The forward definition of a document node structure. */
703 typedef struct yaml_node_s yaml_node_t;
705 /** An element of a sequence node. */
706 typedef int yaml_node_item_t;
708 /** An element of a mapping node. */
709 typedef struct yaml_node_pair_s {
710 /** The key of the element. */
712 /** The value of the element. */
716 /** The node structure. */
719 /** The node type. */
720 yaml_node_type_t type;
725 /** The node data. */
728 /** The scalar parameters (for @c YAML_SCALAR_NODE). */
730 /** The scalar value. */
732 /** The length of the scalar value. */
734 /** The scalar style. */
735 yaml_scalar_style_t style;
738 /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
740 /** The stack of sequence items. */
742 /** The beginning of the stack. */
743 yaml_node_item_t *start;
744 /** The end of the stack. */
745 yaml_node_item_t *end;
746 /** The top of the stack. */
747 yaml_node_item_t *top;
749 /** The sequence style. */
750 yaml_sequence_style_t style;
753 /** The mapping parameters (for @c YAML_MAPPING_NODE). */
755 /** The stack of mapping pairs (key, value). */
757 /** The beginning of the stack. */
758 yaml_node_pair_t *start;
759 /** The end of the stack. */
760 yaml_node_pair_t *end;
761 /** The top of the stack. */
762 yaml_node_pair_t *top;
764 /** The mapping style. */
765 yaml_mapping_style_t style;
770 /** The beginning of the node. */
771 yaml_mark_t start_mark;
772 /** The end of the node. */
773 yaml_mark_t end_mark;
777 /** The document structure. */
778 typedef struct yaml_document_s {
780 /** The document nodes. */
782 /** The beginning of the stack. */
784 /** The end of the stack. */
786 /** The top of the stack. */
790 /** The version directive. */
791 yaml_version_directive_t *version_directive;
793 /** The list of tag directives. */
795 /** The beginning of the tag directives list. */
796 yaml_tag_directive_t *start;
797 /** The end of the tag directives list. */
798 yaml_tag_directive_t *end;
801 /** Is the document start indicator implicit? */
803 /** Is the document end indicator implicit? */
806 /** The beginning of the document. */
807 yaml_mark_t start_mark;
808 /** The end of the document. */
809 yaml_mark_t end_mark;
814 * Create a YAML document.
816 * @param[out] document An empty document object.
817 * @param[in] version_directive The %YAML directive value or
819 * @param[in] tag_directives_start The beginning of the %TAG
821 * @param[in] tag_directives_end The end of the %TAG directives
823 * @param[in] start_implicit If the document start indicator is
825 * @param[in] end_implicit If the document end indicator is
828 * @returns @c 1 if the function succeeded, @c 0 on error.
832 yaml_document_initialize(yaml_document_t *document,
833 yaml_version_directive_t *version_directive,
834 yaml_tag_directive_t *tag_directives_start,
835 yaml_tag_directive_t *tag_directives_end,
836 int start_implicit, int end_implicit);
839 * Delete a YAML document and all its nodes.
841 * @param[in,out] document A document object.
845 yaml_document_delete(yaml_document_t *document);
848 * Get a node of a YAML document.
850 * The pointer returned by this function is valid until any of the functions
851 * modifying the documents are called.
853 * @param[in] document A document object.
854 * @param[in] index The node id.
856 * @returns the node objct or @c NULL if @c node_id is out of range.
859 YAML_DECLARE(yaml_node_t *)
860 yaml_document_get_node(yaml_document_t *document, int index);
863 * Get the root of a YAML document node.
865 * The root object is the first object added to the document.
867 * The pointer returned by this function is valid until any of the functions
868 * modifying the documents are called.
870 * An empty document produced by the parser signifies the end of a YAML
873 * @param[in] document A document object.
875 * @returns the node object or @c NULL if the document is empty.
878 YAML_DECLARE(yaml_node_t *)
879 yaml_document_get_root_node(yaml_document_t *document);
882 * Create a SCALAR node and attach it to the document.
884 * The @a style argument may be ignored by the emitter.
886 * @param[in,out] document A document object.
887 * @param[in] tag The scalar tag.
888 * @param[in] value The scalar value.
889 * @param[in] length The length of the scalar value.
890 * @param[in] style The scalar style.
892 * @returns the node id or @c 0 on error.
896 yaml_document_add_scalar(yaml_document_t *document,
897 yaml_char_t *tag, yaml_char_t *value, int length,
898 yaml_scalar_style_t style);
901 * Create a SEQUENCE node and attach it to the document.
903 * The @a style argument may be ignored by the emitter.
905 * @param[in,out] document A document object.
906 * @param[in] tag The sequence tag.
907 * @param[in] style The sequence style.
909 * @returns the node id or @c 0 on error.
913 yaml_document_add_sequence(yaml_document_t *document,
914 yaml_char_t *tag, yaml_sequence_style_t style);
917 * Create a MAPPING node and attach it to the document.
919 * The @a style argument may be ignored by the emitter.
921 * @param[in,out] document A document object.
922 * @param[in] tag The sequence tag.
923 * @param[in] style The sequence style.
925 * @returns the node id or @c 0 on error.
929 yaml_document_add_mapping(yaml_document_t *document,
930 yaml_char_t *tag, yaml_mapping_style_t style);
933 * Add an item to a SEQUENCE node.
935 * @param[in,out] document A document object.
936 * @param[in] sequence The sequence node id.
937 * @param[in] item The item node id.
939 * @returns @c 1 if the function succeeded, @c 0 on error.
943 yaml_document_append_sequence_item(yaml_document_t *document,
944 int sequence, int item);
947 * Add a pair of a key and a value to a MAPPING node.
949 * @param[in,out] document A document object.
950 * @param[in] mapping The mapping node id.
951 * @param[in] key The key node id.
952 * @param[in] value The value node id.
954 * @returns @c 1 if the function succeeded, @c 0 on error.
958 yaml_document_append_mapping_pair(yaml_document_t *document,
959 int mapping, int key, int value);
964 * @defgroup parser Parser Definitions
969 * The prototype of a read handler.
971 * The read handler is called when the parser needs to read more bytes from the
972 * source. The handler should write not more than @a size bytes to the @a
973 * buffer. The number of written bytes should be set to the @a length variable.
975 * @param[in,out] data A pointer to an application data specified by
976 * yaml_parser_set_input().
977 * @param[out] buffer The buffer to write the data from the source.
978 * @param[in] size The size of the buffer.
979 * @param[out] size_read The actual number of bytes read from the source.
981 * @returns On success, the handler should return @c 1. If the handler failed,
982 * the returned value should be @c 0. On EOF, the handler should set the
983 * @a size_read to @c 0 and return @c 1.
986 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
990 * This structure holds information about a potential simple key.
993 typedef struct yaml_simple_key_s {
994 /** Is a simple key possible? */
997 /** Is a simple key required? */
1000 /** The number of the token. */
1001 size_t token_number;
1003 /** The position mark. */
1005 } yaml_simple_key_t;
1008 * The states of the parser.
1010 typedef enum yaml_parser_state_e {
1011 /** Expect STREAM-START. */
1012 YAML_PARSE_STREAM_START_STATE,
1013 /** Expect the beginning of an implicit document. */
1014 YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
1015 /** Expect DOCUMENT-START. */
1016 YAML_PARSE_DOCUMENT_START_STATE,
1017 /** Expect the content of a document. */
1018 YAML_PARSE_DOCUMENT_CONTENT_STATE,
1019 /** Expect DOCUMENT-END. */
1020 YAML_PARSE_DOCUMENT_END_STATE,
1021 /** Expect a block node. */
1022 YAML_PARSE_BLOCK_NODE_STATE,
1023 /** Expect a block node or indentless sequence. */
1024 YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
1025 /** Expect a flow node. */
1026 YAML_PARSE_FLOW_NODE_STATE,
1027 /** Expect the first entry of a block sequence. */
1028 YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
1029 /** Expect an entry of a block sequence. */
1030 YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
1031 /** Expect an entry of an indentless sequence. */
1032 YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
1033 /** Expect the first key of a block mapping. */
1034 YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
1035 /** Expect a block mapping key. */
1036 YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
1037 /** Expect a block mapping value. */
1038 YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
1039 /** Expect the first entry of a flow sequence. */
1040 YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
1041 /** Expect an entry of a flow sequence. */
1042 YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
1043 /** Expect a key of an ordered mapping. */
1044 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
1045 /** Expect a value of an ordered mapping. */
1046 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
1047 /** Expect the and of an ordered mapping entry. */
1048 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
1049 /** Expect the first key of a flow mapping. */
1050 YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
1051 /** Expect a key of a flow mapping. */
1052 YAML_PARSE_FLOW_MAPPING_KEY_STATE,
1053 /** Expect a value of a flow mapping. */
1054 YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
1055 /** Expect an empty value of a flow mapping. */
1056 YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
1057 /** Expect nothing. */
1058 YAML_PARSE_END_STATE
1059 } yaml_parser_state_t;
1062 * This structure holds aliases data.
1065 typedef struct yaml_alias_data_s {
1067 yaml_char_t *anchor;
1070 /** The anchor mark. */
1072 } yaml_alias_data_t;
1075 * The parser structure.
1077 * All members are internal. Manage the structure using the @c yaml_parser_
1078 * family of functions.
1081 typedef struct yaml_parser_s {
1084 * @name Error handling
1089 yaml_error_type_t error;
1090 /** Error description. */
1091 const char *problem;
1092 /** The byte about which the problem occured. */
1093 size_t problem_offset;
1094 /** The problematic value (@c -1 is none). */
1096 /** The problem position. */
1097 yaml_mark_t problem_mark;
1098 /** The error context. */
1099 const char *context;
1100 /** The context position. */
1101 yaml_mark_t context_mark;
1108 * @name Reader stuff
1112 /** Read handler. */
1113 yaml_read_handler_t *read_handler;
1115 /** A pointer for passing to the read handler. */
1116 void *read_handler_data;
1118 /** Standard (string or file) input data. */
1120 /** String input data. */
1122 /** The string start pointer. */
1123 const unsigned char *start;
1124 /** The string end pointer. */
1125 const unsigned char *end;
1126 /** The string current position. */
1127 const unsigned char *current;
1130 /** File input data. */
1137 /** The working buffer. */
1139 /** The beginning of the buffer. */
1141 /** The end of the buffer. */
1143 /** The current position of the buffer. */
1144 yaml_char_t *pointer;
1145 /** The last filled position of the buffer. */
1149 /* The number of unread characters in the buffer. */
1152 /** The raw buffer. */
1154 /** The beginning of the buffer. */
1155 unsigned char *start;
1156 /** The end of the buffer. */
1158 /** The current position of the buffer. */
1159 unsigned char *pointer;
1160 /** The last filled position of the buffer. */
1161 unsigned char *last;
1164 /** The input encoding. */
1165 yaml_encoding_t encoding;
1167 /** The offset of the current position (in bytes). */
1170 /** The mark of the current position. */
1178 * @name Scanner stuff
1182 /** Have we started to scan the input stream? */
1183 int stream_start_produced;
1185 /** Have we reached the end of the input stream? */
1186 int stream_end_produced;
1188 /** The number of unclosed '[' and '{' indicators. */
1191 /** The tokens queue. */
1193 /** The beginning of the tokens queue. */
1194 yaml_token_t *start;
1195 /** The end of the tokens queue. */
1197 /** The head of the tokens queue. */
1199 /** The tail of the tokens queue. */
1203 /** The number of tokens fetched from the queue. */
1204 size_t tokens_parsed;
1206 /* Does the tokens queue contain a token ready for dequeueing. */
1207 int token_available;
1209 /** The indentation levels stack. */
1211 /** The beginning of the stack. */
1213 /** The end of the stack. */
1215 /** The top of the stack. */
1219 /** The current indentation level. */
1222 /** May a simple key occur at the current position? */
1223 int simple_key_allowed;
1225 /** The stack of simple keys. */
1227 /** The beginning of the stack. */
1228 yaml_simple_key_t *start;
1229 /** The end of the stack. */
1230 yaml_simple_key_t *end;
1231 /** The top of the stack. */
1232 yaml_simple_key_t *top;
1240 * @name Parser stuff
1244 /** The parser states stack. */
1246 /** The beginning of the stack. */
1247 yaml_parser_state_t *start;
1248 /** The end of the stack. */
1249 yaml_parser_state_t *end;
1250 /** The top of the stack. */
1251 yaml_parser_state_t *top;
1254 /** The current parser state. */
1255 yaml_parser_state_t state;
1257 /** The stack of marks. */
1259 /** The beginning of the stack. */
1261 /** The end of the stack. */
1263 /** The top of the stack. */
1267 /** The list of TAG directives. */
1269 /** The beginning of the list. */
1270 yaml_tag_directive_t *start;
1271 /** The end of the list. */
1272 yaml_tag_directive_t *end;
1273 /** The top of the list. */
1274 yaml_tag_directive_t *top;
1282 * @name Dumper stuff
1286 /** The alias data. */
1288 /** The beginning of the list. */
1289 yaml_alias_data_t *start;
1290 /** The end of the list. */
1291 yaml_alias_data_t *end;
1292 /** The top of the list. */
1293 yaml_alias_data_t *top;
1296 /** The currently parsed document. */
1297 yaml_document_t *document;
1306 * Initialize a parser.
1308 * This function creates a new parser object. An application is responsible
1309 * for destroying the object using the yaml_parser_delete() function.
1311 * @param[out] parser An empty parser object.
1313 * @returns @c 1 if the function succeeded, @c 0 on error.
1317 yaml_parser_initialize(yaml_parser_t *parser);
1322 * @param[in,out] parser A parser object.
1326 yaml_parser_delete(yaml_parser_t *parser);
1329 * Set a string input.
1331 * Note that the @a input pointer must be valid while the @a parser object
1332 * exists. The application is responsible for destroing @a input after
1333 * destroying the @a parser.
1335 * @param[in,out] parser A parser object.
1336 * @param[in] input A source data.
1337 * @param[in] size The length of the source data in bytes.
1341 yaml_parser_set_input_string(yaml_parser_t *parser,
1342 const unsigned char *input, size_t size);
1347 * @a file should be a file object open for reading. The application is
1348 * responsible for closing the @a file.
1350 * @param[in,out] parser A parser object.
1351 * @param[in] file An open file.
1355 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
1358 * Set a generic input handler.
1360 * @param[in,out] parser A parser object.
1361 * @param[in] handler A read handler.
1362 * @param[in] data Any application data for passing to the read
1367 yaml_parser_set_input(yaml_parser_t *parser,
1368 yaml_read_handler_t *handler, void *data);
1371 * Set the source encoding.
1373 * @param[in,out] parser A parser object.
1374 * @param[in] encoding The source encoding.
1378 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1381 * Scan the input stream and produce the next token.
1383 * Call the function subsequently to produce a sequence of tokens corresponding
1384 * to the input stream. The initial token has the type
1385 * @c YAML_STREAM_START_TOKEN while the ending token has the type
1386 * @c YAML_STREAM_END_TOKEN.
1388 * An application is responsible for freeing any buffers associated with the
1389 * produced token object using the @c yaml_token_delete function.
1391 * An application must not alternate the calls of yaml_parser_scan() with the
1392 * calls of yaml_parser_parse() or yaml_parser_load(). Doing this will break
1395 * @param[in,out] parser A parser object.
1396 * @param[out] token An empty token object.
1398 * @returns @c 1 if the function succeeded, @c 0 on error.
1402 yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
1405 * Parse the input stream and produce the next parsing event.
1407 * Call the function subsequently to produce a sequence of events corresponding
1408 * to the input stream. The initial event has the type
1409 * @c YAML_STREAM_START_EVENT while the ending event has the type
1410 * @c YAML_STREAM_END_EVENT.
1412 * An application is responsible for freeing any buffers associated with the
1413 * produced event object using the yaml_event_delete() function.
1415 * An application must not alternate the calls of yaml_parser_parse() with the
1416 * calls of yaml_parser_scan() or yaml_parser_load(). Doing this will break the
1419 * @param[in,out] parser A parser object.
1420 * @param[out] event An empty event object.
1422 * @returns @c 1 if the function succeeded, @c 0 on error.
1426 yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
1429 * Parse the input stream and produce the next YAML document.
1431 * Call this function subsequently to produce a sequence of documents
1432 * constituting the input stream.
1434 * If the produced document has no root node, it means that the document
1435 * end has been reached.
1437 * An application is responsible for freeing any data associated with the
1438 * produced document object using the yaml_document_delete() function.
1440 * An application must not alternate the calls of yaml_parser_load() with the
1441 * calls of yaml_parser_scan() or yaml_parser_parse(). Doing this will break
1444 * @param[in,out] parser A parser object.
1445 * @param[out] document An empty document object.
1447 * @return @c 1 if the function succeeded, @c 0 on error.
1451 yaml_parser_load(yaml_parser_t *parser, yaml_document_t *document);
1456 * @defgroup emitter Emitter Definitions
1461 * The prototype of a write handler.
1463 * The write handler is called when the emitter needs to flush the accumulated
1464 * characters to the output. The handler should write @a size bytes of the
1465 * @a buffer to the output.
1467 * @param[in,out] data A pointer to an application data specified by
1468 * yaml_emitter_set_output().
1469 * @param[in] buffer The buffer with bytes to be written.
1470 * @param[in] size The size of the buffer.
1472 * @returns On success, the handler should return @c 1. If the handler failed,
1473 * the returned value should be @c 0.
1476 typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size);
1478 /** The emitter states. */
1479 typedef enum yaml_emitter_state_e {
1480 /** Expect STREAM-START. */
1481 YAML_EMIT_STREAM_START_STATE,
1482 /** Expect the first DOCUMENT-START or STREAM-END. */
1483 YAML_EMIT_FIRST_DOCUMENT_START_STATE,
1484 /** Expect DOCUMENT-START or STREAM-END. */
1485 YAML_EMIT_DOCUMENT_START_STATE,
1486 /** Expect the content of a document. */
1487 YAML_EMIT_DOCUMENT_CONTENT_STATE,
1488 /** Expect DOCUMENT-END. */
1489 YAML_EMIT_DOCUMENT_END_STATE,
1490 /** Expect the first item of a flow sequence. */
1491 YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
1492 /** Expect an item of a flow sequence. */
1493 YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
1494 /** Expect the first key of a flow mapping. */
1495 YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
1496 /** Expect a key of a flow mapping. */
1497 YAML_EMIT_FLOW_MAPPING_KEY_STATE,
1498 /** Expect a value for a simple key of a flow mapping. */
1499 YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
1500 /** Expect a value of a flow mapping. */
1501 YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
1502 /** Expect the first item of a block sequence. */
1503 YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
1504 /** Expect an item of a block sequence. */
1505 YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
1506 /** Expect the first key of a block mapping. */
1507 YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
1508 /** Expect the key of a block mapping. */
1509 YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
1510 /** Expect a value for a simple key of a block mapping. */
1511 YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
1512 /** Expect a value of a block mapping. */
1513 YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
1514 /** Expect nothing. */
1516 } yaml_emitter_state_t;
1519 * The emitter structure.
1521 * All members are internal. Manage the structure using the @c yaml_emitter_
1522 * family of functions.
1525 typedef struct yaml_emitter_s {
1528 * @name Error handling
1533 yaml_error_type_t error;
1534 /** Error description. */
1535 const char *problem;
1542 * @name Writer stuff
1546 /** Write handler. */
1547 yaml_write_handler_t *write_handler;
1549 /** A pointer for passing to the white handler. */
1550 void *write_handler_data;
1552 /** Standard (string or file) output data. */
1554 /** String output data. */
1556 /** The buffer pointer. */
1557 unsigned char *buffer;
1558 /** The buffer size. */
1560 /** The number of written bytes. */
1561 size_t *size_written;
1564 /** File output data. */
1568 /** The working buffer. */
1570 /** The beginning of the buffer. */
1572 /** The end of the buffer. */
1574 /** The current position of the buffer. */
1575 yaml_char_t *pointer;
1576 /** The last filled position of the buffer. */
1580 /** The raw buffer. */
1582 /** The beginning of the buffer. */
1583 unsigned char *start;
1584 /** The end of the buffer. */
1586 /** The current position of the buffer. */
1587 unsigned char *pointer;
1588 /** The last filled position of the buffer. */
1589 unsigned char *last;
1592 /** The stream encoding. */
1593 yaml_encoding_t encoding;
1600 * @name Emitter stuff
1604 /** If the output is in the canonical style? */
1606 /** The number of indentation spaces. */
1608 /** The preferred width of the output lines. */
1610 /** Allow unescaped non-ASCII characters? */
1612 /** The preferred line break. */
1613 yaml_break_t line_break;
1615 /** The stack of states. */
1617 /** The beginning of the stack. */
1618 yaml_emitter_state_t *start;
1619 /** The end of the stack. */
1620 yaml_emitter_state_t *end;
1621 /** The top of the stack. */
1622 yaml_emitter_state_t *top;
1625 /** The current emitter state. */
1626 yaml_emitter_state_t state;
1628 /** The event queue. */
1630 /** The beginning of the event queue. */
1631 yaml_event_t *start;
1632 /** The end of the event queue. */
1634 /** The head of the event queue. */
1636 /** The tail of the event queue. */
1640 /** The stack of indentation levels. */
1642 /** The beginning of the stack. */
1644 /** The end of the stack. */
1646 /** The top of the stack. */
1650 /** The list of tag directives. */
1652 /** The beginning of the list. */
1653 yaml_tag_directive_t *start;
1654 /** The end of the list. */
1655 yaml_tag_directive_t *end;
1656 /** The top of the list. */
1657 yaml_tag_directive_t *top;
1660 /** The current indentation level. */
1663 /** The current flow level. */
1666 /** Is it the document root context? */
1668 /** Is it a sequence context? */
1669 int sequence_context;
1670 /** Is it a mapping context? */
1671 int mapping_context;
1672 /** Is it a simple mapping key context? */
1673 int simple_key_context;
1675 /** The current line. */
1677 /** The current column. */
1679 /** If the last character was a whitespace? */
1681 /** If the last character was an indentation character (' ', '-', '?', ':')? */
1683 /** If an explicit document end is required? */
1686 /** Anchor analysis. */
1688 /** The anchor value. */
1689 yaml_char_t *anchor;
1690 /** The anchor length. */
1691 size_t anchor_length;
1692 /** Is it an alias? */
1696 /** Tag analysis. */
1698 /** The tag handle. */
1699 yaml_char_t *handle;
1700 /** The tag handle length. */
1701 size_t handle_length;
1702 /** The tag suffix. */
1703 yaml_char_t *suffix;
1704 /** The tag suffix length. */
1705 size_t suffix_length;
1708 /** Scalar analysis. */
1710 /** The scalar value. */
1712 /** The scalar length. */
1714 /** Does the scalar contain line breaks? */
1716 /** Can the scalar be expessed in the flow plain style? */
1717 int flow_plain_allowed;
1718 /** Can the scalar be expressed in the block plain style? */
1719 int block_plain_allowed;
1720 /** Can the scalar be expressed in the single quoted style? */
1721 int single_quoted_allowed;
1722 /** Can the scalar be expressed in the literal or folded styles? */
1724 /** The output style. */
1725 yaml_scalar_style_t style;
1733 * @name Dumper stuff
1737 /** If the stream was already opened? */
1739 /** If the stream was already closed? */
1742 /** The information associated with the document nodes. */
1744 /** The number of references. */
1746 /** The anchor id. */
1748 /** If the node has been emitted? */
1752 /** The last assigned anchor id. */
1755 /** The currently emitted document. */
1756 yaml_document_t *document;
1765 * Initialize an emitter.
1767 * This function creates a new emitter object. An application is responsible
1768 * for destroying the object using the yaml_emitter_delete() function.
1770 * @param[out] emitter An empty parser object.
1772 * @returns @c 1 if the function succeeded, @c 0 on error.
1776 yaml_emitter_initialize(yaml_emitter_t *emitter);
1779 * Destroy an emitter.
1781 * @param[in,out] emitter An emitter object.
1785 yaml_emitter_delete(yaml_emitter_t *emitter);
1788 * Set a string output.
1790 * The emitter will write the output characters to the @a output buffer of the
1791 * size @a size. The emitter will set @a size_written to the number of written
1792 * bytes. If the buffer is smaller than required, the emitter produces the
1793 * YAML_WRITE_ERROR error.
1795 * @param[in,out] emitter An emitter object.
1796 * @param[in] output An output buffer.
1797 * @param[in] size The buffer size.
1798 * @param[in] size_written The pointer to save the number of written
1803 yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1804 unsigned char *output, size_t size, size_t *size_written);
1807 * Set a file output.
1809 * @a file should be a file object open for writing. The application is
1810 * responsible for closing the @a file.
1812 * @param[in,out] emitter An emitter object.
1813 * @param[in] file An open file.
1817 yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1820 * Set a generic output handler.
1822 * @param[in,out] emitter An emitter object.
1823 * @param[in] handler A write handler.
1824 * @param[in] data Any application data for passing to the write
1829 yaml_emitter_set_output(yaml_emitter_t *emitter,
1830 yaml_write_handler_t *handler, void *data);
1833 * Set the output encoding.
1835 * @param[in,out] emitter An emitter object.
1836 * @param[in] encoding The output encoding.
1840 yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1843 * Set if the output should be in the "canonical" format as in the YAML
1846 * @param[in,out] emitter An emitter object.
1847 * @param[in] canonical If the output is canonical.
1851 yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1854 * Set the intendation increment.
1856 * @param[in,out] emitter An emitter object.
1857 * @param[in] indent The indentation increment (1 < . < 10).
1861 yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1864 * Set the preferred line width. @c -1 means unlimited.
1866 * @param[in,out] emitter An emitter object.
1867 * @param[in] width The preferred line width.
1871 yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1874 * Set if unescaped non-ASCII characters are allowed.
1876 * @param[in,out] emitter An emitter object.
1877 * @param[in] unicode If unescaped Unicode characters are allowed.
1881 yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1884 * Set the preferred line break.
1886 * @param[in,out] emitter An emitter object.
1887 * @param[in] line_break The preferred line break.
1891 yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1896 * The event object may be generated using the yaml_parser_parse() function.
1897 * The emitter takes the responsibility for the event object and destroys its
1898 * content after it is emitted. The event object is destroyed even if the
1901 * @param[in,out] emitter An emitter object.
1902 * @param[in,out] event An event object.
1904 * @returns @c 1 if the function succeeded, @c 0 on error.
1908 yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
1911 * Start a YAML stream.
1913 * This function should be used before yaml_emitter_dump() is called.
1915 * @param[in,out] emitter An emitter object.
1917 * @returns @c 1 if the function succeeded, @c 0 on error.
1921 yaml_emitter_open(yaml_emitter_t *emitter);
1924 * Finish a YAML stream.
1926 * This function should be used after yaml_emitter_dump() is called.
1928 * @param[in,out] emitter An emitter object.
1930 * @returns @c 1 if the function succeeded, @c 0 on error.
1934 yaml_emitter_close(yaml_emitter_t *emitter);
1937 * Emit a YAML document.
1939 * The documen object may be generated using the yaml_parser_load() function
1940 * or the yaml_document_initialize() function. The emitter takes the
1941 * responsibility for the document object and destoys its content after
1942 * it is emitted. The document object is destroyedeven if the function fails.
1944 * @param[in,out] emitter An emitter object.
1945 * @param[in,out] document A document object.
1947 * @returns @c 1 if the function succeeded, @c 0 on error.
1951 yaml_emitter_dump(yaml_emitter_t *emitter, yaml_document_t *document);
1954 * Flush the accumulated characters to the output.
1956 * @param[in,out] emitter An emitter object.
1958 * @returns @c 1 if the function succeeded, @c 0 on error.
1962 yaml_emitter_flush(yaml_emitter_t *emitter);
1970 #endif /* #ifndef YAML_H */