3 * @brief Public interface for libyaml.
5 * Include the header file with the code:
7 * #include <yaml/yaml.h>
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. */
82 /** The major version number. */
84 /** The minor version number. */
86 } yaml_version_directive_t;
88 /** The tag directive data. */
90 /** The tag handle. */
92 /** The tag prefix. */
94 } yaml_tag_directive_t;
96 /** The stream encoding. */
100 YAML_UTF16LE_ENCODING,
101 YAML_UTF16BE_ENCODING
104 /** Many bad things could happen with the parser and emitter. */
118 /** The pointer position. */
120 /** The position index. */
123 /** The position line. */
126 /** The position column. */
133 * @defgroup styles Node Styles
137 /** Scalar styles. */
139 YAML_ANY_SCALAR_STYLE,
141 YAML_PLAIN_SCALAR_STYLE,
143 YAML_SINGLE_QUOTED_SCALAR_STYLE,
144 YAML_DOUBLE_QUOTED_SCALAR_STYLE,
146 YAML_LITERAL_SCALAR_STYLE,
147 YAML_FOLDED_SCALAR_STYLE
148 } yaml_scalar_style_t;
151 /** Sequence styles. */
153 YAML_ANY_SEQUENCE_STYLE,
155 YAML_BLOCK_SEQUENCE_STYLE,
156 YAML_FLOW_SEQUENCE_STYLE
157 } yaml_sequence_style_t;
159 /** Mapping styles. */
161 YAML_ANY_MAPPING_STYLE,
163 YAML_BLOCK_MAPPING_STYLE,
164 YAML_FLOW_MAPPING_STYLE
165 } yaml_mapping_style_t;
170 * @defgroup tokens Tokens
176 YAML_STREAM_START_TOKEN,
177 YAML_STREAM_END_TOKEN,
179 YAML_VERSION_DIRECTIVE_TOKEN,
180 YAML_TAG_DIRECTIVE_TOKEN,
181 YAML_DOCUMENT_START_TOKEN,
182 YAML_DOCUMENT_END_TOKEN,
184 YAML_BLOCK_SEQUENCE_START_TOKEN,
185 YAML_BLOCK_MAPPING_START_TOKEN,
186 YAML_BLOCK_END_TOKEN,
188 YAML_FLOW_SEQUENCE_START_TOKEN,
189 YAML_FLOW_SEQUENCE_END_TOKEN,
190 YAML_FLOW_MAPPING_START_TOKEN,
191 YAML_FLOW_MAPPING_END_TOKEN,
193 YAML_BLOCK_ENTRY_TOKEN,
194 YAML_FLOW_ENTRY_TOKEN,
204 /** The token structure. */
207 /** The token type. */
208 yaml_token_type_t type;
210 /** The token data. */
213 /** The stream start (for @c YAML_STREAM_START_TOKEN). */
215 /** The stream encoding. */
216 yaml_encoding_t encoding;
219 /** The alias (for @c YAML_ALIAS_TOKEN). */
221 /** The alias value. */
225 /** The anchor (for @c YAML_ANCHOR_TOKEN). */
227 /** The anchor value. */
231 /** The tag (for @c YAML_TAG_TOKEN). */
233 /** The tag handle. */
236 /** The tag suffix. */
240 /** The scalar value (for @c YAML_SCALAR_TOKEN). */
243 /** The scalar value. */
246 /** The length of the scalar value. */
249 /** The scalar style. */
250 yaml_scalar_style_t style;
253 /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
255 /** The major version number. */
258 /** The minor version number. */
262 /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
264 /** The tag handle. */
267 /** The tag prefix. */
272 /** The beginning of the token. */
273 yaml_mark_t start_mark;
275 /** The end of the token. */
276 yaml_mark_t end_mark;
281 * Create a new token without assigning any data.
283 * This function can be used for constructing indicator tokens:
284 * @c YAML_DOCUMENT_START, @c YAML_DOCUMENT_END,
285 * @c YAML_BLOCK_SEQUENCE_START_TOKEN, @c YAML_BLOCK_MAPPING_START_TOKEN,
286 * @c YAML_BLOCK_END_TOKEN,
287 * @c YAML_FLOW_SEQUENCE_START_TOKEN, @c YAML_FLOW_SEQUENCE_END_TOKEN,
288 * @c YAML_FLOW_MAPPING_START_TOKEN, @c YAML_FLOW_MAPPING_END_TOKEN,
289 * @c YAML_BLOCK_ENTRY_TOKEN, @c YAML_FLOW_ENTRY_TOKEN,
290 * @c YAML_KEY_TOKEN, @c YAML_VALUE_TOKEN.
292 * @param[in] type The token type.
293 * @param[in] start_mark The beginning of the token.
294 * @param[in] end_mark The end of the token.
296 * @returns A new token object, or @c NULL on error.
299 YAML_DECLARE(yaml_token_t *)
300 yaml_token_new(yaml_token_type_t type,
301 yaml_mark_t start_mark, yaml_mark_t end_mark);
304 * Create a new @c YAML_STREAM_START_TOKEN token with the specified encoding.
306 * @param[in] encoding The stream encoding.
307 * @param[in] start_mark The beginning of the token.
308 * @param[in] end_mark The end of the token.
310 * @returns A new token object, or @c NULL on error.
313 YAML_DECLARE(yaml_token_t *)
314 yaml_stream_start_token_new(yaml_encoding_t encoding,
315 yaml_mark_t start_mark, yaml_mark_t end_mark);
318 * Create a new @c YAML_STREAM_END_TOKEN token.
320 * @param[in] start_mark The beginning of the token.
321 * @param[in] end_mark The end of the token.
323 * @returns A new token object, or @c NULL on error.
326 YAML_DECLARE(yaml_token_t *)
327 yaml_stream_end_token_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
330 * Create a new @c YAML_VERSION_DIRECTIVE_TOKEN token with the specified
333 * @param[in] major The major version number.
334 * @param[in] minor The minor version number.
335 * @param[in] start_mark The beginning of the token.
336 * @param[in] end_mark The end of the token.
338 * @returns A new token object, or @c NULL on error.
341 YAML_DECLARE(yaml_token_t *)
342 yaml_version_directive_token_new(int major, int minor,
343 yaml_mark_t start_mark, yaml_mark_t end_mark);
346 * Create a new @c YAML_TAG_DIRECTIVE_TOKEN token with the specified tag
349 * Note that the @a handle and the @a prefix pointers will be freed by
350 * the token descructor.
352 * @param[in] handle The tag handle.
353 * @param[in] prefix The tag prefix.
354 * @param[in] start_mark The beginning of the token.
355 * @param[in] end_mark The end of the token.
357 * @returns A new token object, or @c NULL on error.
360 YAML_DECLARE(yaml_token_t *)
361 yaml_tag_directive_token_new(yaml_char_t *handle, yaml_char_t *prefix,
362 yaml_mark_t start_mark, yaml_mark_t end_mark);
365 * Create a new @c YAML_ALIAS_TOKEN token with the specified anchor.
367 * Note that the @a anchor pointer will be freed by the token descructor.
369 * @param[in] anchor The anchor.
370 * @param[in] start_mark The beginning of the token.
371 * @param[in] end_mark The end of the token.
373 * @returns A new token object, or @c NULL on error.
376 YAML_DECLARE(yaml_token_t *)
377 yaml_alias_token_new(yaml_char_t *anchor,
378 yaml_mark_t start_mark, yaml_mark_t end_mark);
381 * Create a new @c YAML_ANCHOR_TOKEN token with the specified anchor.
383 * Note that the @a anchor pointer will be freed by the token descructor.
385 * @param[in] anchor The anchor.
386 * @param[in] start_mark The beginning of the token.
387 * @param[in] end_mark The end of the token.
389 * @returns A new token object, or @c NULL on error.
392 YAML_DECLARE(yaml_token_t *)
393 yaml_anchor_token_new(yaml_char_t *anchor,
394 yaml_mark_t start_mark, yaml_mark_t end_mark);
397 * Create a new @c YAML_TAG_TOKEN token with the specified tag handle and
400 * Note that the @a handle and the @a suffix pointers will be freed by
401 * the token descructor.
403 * @param[in] handle The tag handle.
404 * @param[in] suffix The tag suffix.
405 * @param[in] start_mark The beginning of the token.
406 * @param[in] end_mark The end of the token.
408 * @returns A new token object, or @c NULL on error.
411 YAML_DECLARE(yaml_token_t *)
412 yaml_tag_token_new(yaml_char_t *handle, yaml_char_t *suffix,
413 yaml_mark_t start_mark, yaml_mark_t end_mark);
416 * Create a new @c YAML_SCALAR_TOKEN token with the specified scalar value,
419 * Note that the scalar value may contain the @c NUL character, therefore
420 * the value length is also required. The scalar value always ends with
423 * Note that the @a value pointer will be freed by the token descructor.
425 * @param[in] value The scalar value.
426 * @param[in] length The value length.
427 * @param[in] style The scalar style.
428 * @param[in] start_mark The beginning of the token.
429 * @param[in] end_mark The end of the token.
431 * @returns A new token object, or @c NULL on error.
434 YAML_DECLARE(yaml_token_t *)
435 yaml_scalar_token_new(yaml_char_t *value, size_t length,
436 yaml_scalar_style_t style,
437 yaml_mark_t start_mark, yaml_mark_t end_mark);
440 * Destroy a token object.
442 * @param[in] token A token object.
446 yaml_token_delete(yaml_token_t *token);
451 * @defgroup events Events
457 YAML_STREAM_START_EVENT,
458 YAML_STREAM_END_EVENT,
460 YAML_DOCUMENT_START_EVENT,
461 YAML_DOCUMENT_END_EVENT,
466 YAML_SEQUENCE_START_EVENT,
467 YAML_SEQUENCE_END_EVENT,
469 YAML_MAPPING_START_EVENT,
470 YAML_MAPPING_END_EVENT
473 /** The event structure. */
476 /** The event type. */
477 yaml_event_type_t type;
479 /** The event data. */
482 /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
484 /** The document encoding. */
485 yaml_encoding_t encoding;
488 /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
490 /** The version directive. */
491 yaml_version_directive_t *version_directive;
492 /** The list of tag directives. */
493 yaml_tag_directive_t **tag_directives;
494 /** Is the document indicator implicit? */
498 /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
500 /** Is the document end indicator implicit? */
504 /** The alias parameters (for @c YAML_ALIAS_EVENT). */
510 /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
516 /** The scalar value. */
518 /** The length of the scalar value. */
520 /** Is the tag optional for the plain style? */
522 /** Is the tag optional for any non-plain style? */
524 /** The scalar style. */
525 yaml_scalar_style_t style;
528 /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
534 /** Is the tag optional? */
536 /** The sequence style. */
537 yaml_sequence_style_t style;
540 /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
546 /** Is the tag optional? */
548 /** The mapping style. */
549 yaml_mapping_style_t style;
554 /** The beginning of the token. */
555 yaml_mark_t start_mark;
557 /** The end of the token. */
558 yaml_mark_t end_mark;
562 * Create a new @c YAML_STREAM_START_EVENT event.
564 * @param[in] encoding The stream encoding.
565 * @param[in] start_mark The beginning of the event.
566 * @param[in] end_mark The end of the event.
568 * @returns A new event object, or @c NULL on error.
571 YAML_DECLARE(yaml_event_t *)
572 yaml_stream_start_event_new(yaml_encoding_t encoding,
573 yaml_mark_t start_mark, yaml_mark_t end_mark);
576 * Create a new @c YAML_STREAM_END_TOKEN event.
578 * @param[in] start_mark The beginning of the event.
579 * @param[in] end_mark The end of the event.
581 * @returns A new event object, or @c NULL on error.
584 YAML_DECLARE(yaml_event_t *)
585 yaml_stream_end_event_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
588 * Create a new @c YAML_DOCUMENT_START_EVENT event.
590 * @param[in] version_directive The version directive or @c NULL.
591 * @param[in] tag_directives A list of tag directives or @c NULL.
592 * @param[in] implicit Is the document indicator present?
593 * @param[in] start_mark The beginning of the event.
594 * @param[in] end_mark The end of the event.
596 * @returns A new event object, or @c NULL on error.
599 YAML_DECLARE(yaml_event_t *)
600 yaml_document_start_event_new(yaml_version_directive_t *version_directive,
601 yaml_tag_directive_t **tag_directives, int implicit,
602 yaml_mark_t start_mark, yaml_mark_t end_mark);
605 * Create a new @c YAML_DOCUMENT_END_EVENT event.
607 * @param[in] implicit Is the document end indicator present?
608 * @param[in] start_mark The beginning of the event.
609 * @param[in] end_mark The end of the event.
611 * @returns A new event object, or @c NULL on error.
614 YAML_DECLARE(yaml_event_t *)
615 yaml_document_end_event_new(int implicit,
616 yaml_mark_t start_mark, yaml_mark_t end_mark);
619 * Create a new @c YAML_ALIAS_EVENT event.
621 * @param[in] anchor The anchor value.
622 * @param[in] start_mark The beginning of the event.
623 * @param[in] end_mark The end of the event.
625 * @returns A new event object, or @c NULL on error.
628 YAML_DECLARE(yaml_event_t *)
629 yaml_alias_event_new(yaml_char_t *anchor,
630 yaml_mark_t start_mark, yaml_mark_t end_mark);
633 * Create a new @c YAML_SCALAR_EVENT event.
635 * @param[in] anchor The anchor value or @c NULL.
636 * @param[in] tag The tag value or @c NULL.
637 * @param[in] value The scalar value.
638 * @param[in] length The length of the scalar value.
639 * @param[in] plain_implicit Is the tag optional for the plain style?
640 * @param[in] quoted_implicit Is the tag optional for any non-plain style?
641 * @param[in] style The scalar style.
642 * @param[in] start_mark The beginning of the event.
643 * @param[in] end_mark The end of the event.
645 * @returns A new event object, or @c NULL on error.
648 YAML_DECLARE(yaml_event_t *)
649 yaml_scalar_event_new(yaml_char_t *anchor, yaml_char_t *tag,
650 yaml_char_t *value, size_t length,
651 int plain_implicit, int quoted_implicit,
652 yaml_scalar_style_t style,
653 yaml_mark_t start_mark, yaml_mark_t end_mark);
656 * Create a new @c YAML_SEQUENCE_START_EVENT event.
658 * @param[in] anchor The anchor value or @c NULL.
659 * @param[in] tag The tag value or @c NULL.
660 * @param[in] implicit Is the tag optional?
661 * @param[in] style The sequence style.
662 * @param[in] start_mark The beginning of the event.
663 * @param[in] end_mark The end of the event.
665 * @returns A new event object, or @c NULL on error.
668 YAML_DECLARE(yaml_event_t *)
669 yaml_sequence_start_event_new(yaml_char_t *anchor, yaml_char_t *tag,
670 int implicit, yaml_sequence_style_t style,
671 yaml_mark_t start_mark, yaml_mark_t end_mark);
674 * Create a new @c YAML_SEQUENCE_END_EVENT event.
676 * @param[in] start_mark The beginning of the event.
677 * @param[in] end_mark The end of the event.
679 * @returns A new event object, or @c NULL on error.
682 YAML_DECLARE(yaml_event_t *)
683 yaml_sequence_end_event_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
686 * Create a new @c YAML_MAPPING_START_EVENT event.
688 * @param[in] anchor The anchor value or @c NULL.
689 * @param[in] tag The tag value or @c NULL.
690 * @param[in] implicit Is the tag optional?
691 * @param[in] style The mapping style.
692 * @param[in] start_mark The beginning of the event.
693 * @param[in] end_mark The end of the event.
695 * @returns A new event object, or @c NULL on error.
698 YAML_DECLARE(yaml_event_t *)
699 yaml_mapping_start_event_new(yaml_char_t *anchor, yaml_char_t *tag,
700 int implicit, yaml_mapping_style_t style,
701 yaml_mark_t start_mark, yaml_mark_t end_mark);
704 * Create a new @c YAML_MAPPING_END_EVENT event.
706 * @param[in] start_mark The beginning of the event.
707 * @param[in] end_mark The end of the event.
709 * @returns A new event object, or @c NULL on error.
712 YAML_DECLARE(yaml_event_t *)
713 yaml_mapping_end_event_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
716 * Destroy an event object.
718 * @param[in] event An event object.
722 yaml_event_delete(yaml_event_t *event);
727 * @defgroup parser Parser Definitions
732 * The prototype of a read handler.
734 * The read handler is called when the parser needs to read more bytes from the
735 * source. The handler should write not more than @a size bytes to the @a
736 * buffer. The number of written bytes should be set to the @a length variable.
738 * @param[in] data A pointer to an application data specified by
739 * @c yaml_parser_set_read_handler.
740 * @param[out] buffer The buffer to write the data from the source.
741 * @param[in] size The size of the buffer.
742 * @param[out] size_read The actual number of bytes read from the source.
744 * @returns On success, the handler should return @c 1. If the handler failed,
745 * the returned value should be @c 0. On EOF, the handler should set the
746 * @a length to @c 0 and return @c 1.
749 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
753 * This structure holds a string input specified by
754 * @c yaml_parser_set_input_string.
758 /** The string start pointer. */
759 unsigned char *start;
761 /** The string end pointer. */
764 /** The string current position. */
765 unsigned char *current;
766 } yaml_string_input_t;
769 * This structure holds information about a potential simple key.
773 /** Is a simple key required? */
776 /** The number of the token. */
779 /** The position index. */
782 /** The position line. */
785 /** The position column. */
788 /** The position mark. */
793 * The states of the parser.
796 YAML_PARSE_END_STATE,
797 YAML_PARSE_STREAM_START_STATE,
798 YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
799 YAML_PARSE_DOCUMENT_START_STATE,
800 YAML_PARSE_DOCUMENT_CONTENT_STATE,
801 YAML_PARSE_DOCUMENT_END_STATE,
802 YAML_PARSE_BLOCK_NODE_STATE,
803 YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
804 YAML_PARSE_FLOW_NODE_STATE,
805 YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
806 YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
807 YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
808 YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
809 YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
810 YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
811 YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
812 YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
813 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
814 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
815 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
816 YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
817 YAML_PARSE_FLOW_MAPPING_KEY_STATE,
818 YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
819 YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE
820 } yaml_parser_state_t;
823 * The parser structure.
825 * All members are internal. Manage the structure using the @c yaml_parser_
826 * family of functions.
832 * @name Error handling
837 yaml_error_type_t error;
839 /** Error description. */
842 /** The byte about which the problem occured. */
843 size_t problem_offset;
845 /** The problematic value (@c -1 is none). */
848 /** The problem position. */
849 yaml_mark_t problem_mark;
851 /** The error context. */
854 /** The context position. */
855 yaml_mark_t context_mark;
867 yaml_read_handler_t *read_handler;
869 /** A pointer for passing to the read handler. */
870 void *read_handler_data;
875 /** The pointer to the beginning of the working buffer. */
878 /** The pointer to the end of the working buffer. */
879 yaml_char_t *buffer_end;
881 /** The pointer to the current character in the working buffer. */
882 yaml_char_t *pointer;
884 /** The number of unread characters in the working buffer. */
887 /** The pointer to the beginning of the raw buffer. */
888 unsigned char *raw_buffer;
890 /** The pointer to the current character in the raw buffer. */
891 unsigned char *raw_pointer;
893 /** The number of unread bytes in the raw buffer. */
896 /** The input encoding. */
897 yaml_encoding_t encoding;
899 /** The offset of the current position (in bytes). */
902 /** The index of the current position (in characters). */
905 /** The line of the current position (starting from @c 0). */
908 /** The column of the current position (starting from @c 0). */
911 /* String input structure. */
912 yaml_string_input_t string_input;
919 * @name Scanner stuff
923 /** Have we started to scan the input stream? */
924 int stream_start_produced;
926 /** Have we reached the end of the input stream? */
927 int stream_end_produced;
929 /** The number of unclosed '[' and '{' indicators. */
932 /** The tokens queue, which contains the current produced tokens. */
933 yaml_token_t **tokens;
935 /** The size of the tokens queue. */
938 /** The head of the tokens queue. */
941 /** The tail of the tokens queue. */
944 /** The number of tokens fetched from the tokens queue. */
945 size_t tokens_parsed;
947 /** The stack of indentation levels. */
950 /** The size of the indents stack. */
953 /** The number of items in the indents stack. */
954 size_t indents_length;
956 /** The current indentation level. */
959 /** May a simple key occur at the current position? */
960 int simple_key_allowed;
962 /** The stack of potential simple keys. */
963 yaml_simple_key_t **simple_keys;
965 /** The size of the simple keys stack. */
966 size_t simple_keys_size;
977 /** The parser states stack. */
978 yaml_parser_state_t *states;
980 /** The size of the parser states stack. */
983 /** The number of items in the parser states stack. */
984 size_t states_length;
986 /** The current parser state. */
987 yaml_parser_state_t state;
989 /** The stack of marks. */
992 /** The size of the marks stack. */
995 /** The number of items in the marks stack. */
998 /** The current event. */
999 yaml_event_t *current_event;
1001 /** The YAML version directive. */
1002 yaml_version_directive_t *version_directive;
1004 /** The list of TAG directives. */
1005 yaml_tag_directive_t **tag_directives;
1007 /** The size of the TAG directives list. */
1008 size_t tag_directives_size;
1010 /** The number of items in the TAG directives list. */
1011 size_t tag_directives_length;
1020 * Create a new parser.
1022 * This function creates a new parser object. An application is responsible
1023 * for destroying the object using the @c yaml_parser_delete function.
1025 * @returns A new parser object; @c NULL on error.
1028 YAML_DECLARE(yaml_parser_t *)
1029 yaml_parser_new(void);
1034 * @param[in] parser A parser object.
1038 yaml_parser_delete(yaml_parser_t *parser);
1041 * Set a string input.
1043 * Note that the @a input pointer must be valid while the @a parser object
1044 * exists. The application is responsible for destroing @a input after
1045 * destroying the @a parser.
1047 * @param[in] parser A parser object.
1048 * @param[in] input A source data.
1049 * @param[in] size The length of the source data in bytes.
1053 yaml_parser_set_input_string(yaml_parser_t *parser,
1054 unsigned char *input, size_t size);
1060 * @a file should be a file object open for reading. The application is
1061 * responsible for closing the @a file.
1063 * @param[in] parser A parser object.
1064 * @param[in] file An open file.
1068 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
1071 * Set a generic input handler.
1073 * @param[in] parser A parser object.
1074 * @param[in] handler A read handler.
1075 * @param[in] data Any application data for passing to the read handler.
1079 yaml_parser_set_input(yaml_parser_t *parser,
1080 yaml_read_handler_t *handler, void *data);
1083 * Set the source encoding.
1085 * @param[in] parser A parser object.
1086 * @param[in] encoding The source encoding.
1090 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1093 * Get the next token.
1095 * The token is removed from the internal token queue and the application is
1096 * responsible for destroing the token object.
1098 * @param[in] parser A parser object.
1100 * @returns A token object, or @c NULL on error.
1103 YAML_DECLARE(yaml_token_t *)
1104 yaml_parser_get_token(yaml_parser_t *parser);
1107 * Peek the next token.
1109 * The token is not removed from the internal token queue and will be returned
1110 * again on a subsequent call of @c yaml_parser_get_token or
1111 * @c yaml_parser_peek_token. The application should not destroy the token
1114 * @param[in] parser A parser object.
1116 * @returns A token object, or @c NULL on error.
1119 YAML_DECLARE(yaml_token_t *)
1120 yaml_parser_peek_token(yaml_parser_t *parser);
1123 * Get the next event.
1125 * The application is responsible for destroing the event object.
1127 * @param[in] parser A parser object.
1129 * @returns An event object, or @c NULL on error.
1132 YAML_DECLARE(yaml_event_t *)
1133 yaml_parser_get_event(yaml_parser_t *parser);
1136 * Peek the next event.
1138 * The event will be returned again on a subsequent call of
1139 * @c yaml_parser_get_event or @c yaml_parser_peek_event. The application
1140 * should not destroy the event object.
1142 * @param[in] parser A parser object.
1144 * @returns An event object, or @c NULL on error.
1147 YAML_DECLARE(yaml_event_t *)
1148 yaml_parser_peek_event(yaml_parser_t *parser);
1158 * @defgroup internal Internal Definitions
1163 * Allocate a dynamic memory block.
1165 * @param[in] size Size of a memory block, \c 0 is valid.
1167 * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
1168 * or @c NULL if it failed.
1171 YAML_DECLARE(void *)
1172 yaml_malloc(size_t size);
1175 * Reallocate a dynamic memory block.
1177 * @param[in] ptr A pointer to an existing memory block, \c NULL is
1179 * @param[in] size A size of a new block, \c 0 is valid.
1181 * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
1182 * or @c NULL if it failed.
1185 YAML_DECLARE(void *)
1186 yaml_realloc(void *ptr, size_t size);
1189 * Free a dynamic memory block.
1191 * @param[in] ptr A pointer to an existing memory block, \c NULL is
1196 yaml_free(void *ptr);
1198 /** The initial size for various buffers. */
1200 #define YAML_DEFAULT_SIZE 16
1202 /** The size of the raw buffer. */
1204 #define YAML_RAW_BUFFER_SIZE 16384
1207 * The size of the buffer.
1209 * We allocate enough space for decoding the whole raw buffer.
1212 #define YAML_BUFFER_SIZE (YAML_RAW_BUFFER_SIZE*3)
1215 * Ensure that the buffer contains at least @a length characters.
1217 * @param[in] parser A parser object.
1218 * @param[in] length The number of characters in the buffer.
1220 * @returns @c 1 on success, @c 0 on error.
1224 yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
1233 #endif /* #ifndef YAML_H */