3 * @brief Public interface for libyaml.
5 * Include the header file with the code:
7 * #include <yaml/yaml.h>
23 * @defgroup 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 stream encoding. */
84 YAML_UTF16LE_ENCODING,
88 /** Many bad things could happen with the parser and emitter. */
102 /** The pointer position. */
104 /** The position index. */
107 /** The position line. */
110 /** The position column. */
117 * @defgroup Node Styles
121 /** Scalar styles. */
123 YAML_ANY_SCALAR_STYLE,
125 YAML_PLAIN_SCALAR_STYLE,
127 YAML_SINGLE_QUOTED_SCALAR_STYLE,
128 YAML_DOUBLE_QUOTED_SCALAR_STYLE,
130 YAML_LITERAL_SCALAR_STYLE,
131 YAML_FOLDED_SCALAR_STYLE
132 } yaml_scalar_style_t;
135 /** Sequence styles. */
137 YAML_ANY_SEQUENCE_STYLE,
139 YAML_BLOCK_SEQUENCE_STYLE,
140 YAML_FLOW_SEQUENCE_STYLE
141 } yaml_sequence_style_t;
143 /** Mapping styles. */
145 YAML_ANY_MAPPING_STYLE,
147 YAML_BLOCK_MAPPING_STYLE,
148 YAML_FLOW_MAPPING_STYLE
149 } yaml_mapping_style_t;
160 YAML_STREAM_START_TOKEN,
161 YAML_STREAM_END_TOKEN,
163 YAML_VERSION_DIRECTIVE_TOKEN,
164 YAML_TAG_DIRECTIVE_TOKEN,
165 YAML_DOCUMENT_START_TOKEN,
166 YAML_DOCUMENT_END_TOKEN,
168 YAML_BLOCK_SEQUENCE_START_TOKEN,
169 YAML_BLOCK_MAPPING_START_TOKEN,
170 YAML_BLOCK_END_TOKEN,
172 YAML_FLOW_SEQUENCE_START_TOKEN,
173 YAML_FLOW_SEQUENCE_END_TOKEN,
174 YAML_FLOW_MAPPING_START_TOKEN,
175 YAML_FLOW_MAPPING_END_TOKEN,
177 YAML_BLOCK_ENTRY_TOKEN,
178 YAML_FLOW_ENTRY_TOKEN,
188 /** The token structure. */
191 /** The token type. */
192 yaml_token_type_t type;
194 /** The token data. */
197 /** The stream encoding (for @c YAML_STREAM_START_TOKEN). */
198 yaml_encoding_t encoding;
200 /** The anchor (for @c YAML_ALIAS_TOKEN and @c YAML_ANCHOR_TOKEN). */
203 /** The tag (for @c YAML_TAG_TOKEN). */
205 /** The tag handle. */
208 /** The tag suffix. */
212 /** The scalar value (for @c YAML_SCALAR_TOKEN). */
215 /** The scalar value. */
218 /** The length of the scalar value. */
221 /** The scalar style. */
222 yaml_scalar_style_t style;
225 /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
227 /** The major version number. */
230 /** The minor version number. */
234 /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
236 /** The tag handle. */
239 /** The tag prefix. */
244 /** The beginning of the token. */
245 yaml_mark_t start_mark;
247 /** The end of the token. */
248 yaml_mark_t end_mark;
253 * Create a new token without assigning any data.
255 * This function can be used for constructing indicator tokens:
256 * @c YAML_DOCUMENT_START, @c YAML_DOCUMENT_END,
257 * @c YAML_BLOCK_SEQUENCE_START_TOKEN, @c YAML_BLOCK_MAPPING_START_TOKEN,
258 * @c YAML_BLOCK_END_TOKEN,
259 * @c YAML_FLOW_SEQUENCE_START_TOKEN, @c YAML_FLOW_SEQUENCE_END_TOKEN,
260 * @c YAML_FLOW_MAPPING_START_TOKEN, @c YAML_FLOW_MAPPING_END_TOKEN,
261 * @c YAML_BLOCK_ENTRY_TOKEN, @c YAML_FLOW_ENTRY_TOKEN,
262 * @c YAML_KEY_TOKEN, @c YAML_VALUE_TOKEN.
264 * @param[in] type The token type.
265 * @param[in] start_mark The beginning of the token.
266 * @param[in] end_mark The end of the token.
268 * @returns A new token object, or @c NULL on error.
271 YAML_DECLARE(yaml_token_t *)
272 yaml_token_new(yaml_token_type_t type,
273 yaml_mark_t start_mark, yaml_mark_t end_mark);
276 * Create a new @c YAML_STREAM_START_TOKEN token with the specified encoding.
278 * @param[in] encoding The stream encoding.
279 * @param[in] start_mark The beginning of the token.
280 * @param[in] end_mark The end of the token.
282 * @returns A new token object, or @c NULL on error.
285 YAML_DECLARE(yaml_token_t *)
286 yaml_stream_start_token_new(yaml_encoding_t encoding,
287 yaml_mark_t start_mark, yaml_mark_t end_mark);
290 * Create a new @c YAML_STREAM_END_TOKEN token.
292 * @param[in] start_mark The beginning of the token.
293 * @param[in] end_mark The end of the token.
295 * @returns A new token object, or @c NULL on error.
298 YAML_DECLARE(yaml_token_t *)
299 yaml_stream_end_token_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
302 * Create a new @c YAML_VERSION_DIRECTIVE_TOKEN token with the specified
305 * @param[in] major The major version number.
306 * @param[in] minor The minor version number.
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_version_directive_token_new(int major, int minor,
315 yaml_mark_t start_mark, yaml_mark_t end_mark);
318 * Create a new @c YAML_TAG_DIRECTIVE_TOKEN token with the specified tag
321 * Note that the @a handle and the @a prefix pointers will be freed by
322 * the token descructor.
324 * @param[in] handle The tag handle.
325 * @param[in] prefix The tag prefix.
326 * @param[in] start_mark The beginning of the token.
327 * @param[in] end_mark The end of the token.
329 * @returns A new token object, or @c NULL on error.
332 YAML_DECLARE(yaml_token_t *)
333 yaml_tag_directive_token_new(yaml_char_t *handle, yaml_char_t *prefix,
334 yaml_mark_t start_mark, yaml_mark_t end_mark);
337 * Create a new @c YAML_ALIAS_TOKEN token with the specified anchor.
339 * Note that the @a anchor pointer will be freed by the token descructor.
341 * @param[in] anchor The anchor.
342 * @param[in] start_mark The beginning of the token.
343 * @param[in] end_mark The end of the token.
345 * @returns A new token object, or @c NULL on error.
348 YAML_DECLARE(yaml_token_t *)
349 yaml_alias_token_new(yaml_char_t *anchor,
350 yaml_mark_t start_mark, yaml_mark_t end_mark);
353 * Create a new @c YAML_ANCHOR_TOKEN token with the specified anchor.
355 * Note that the @a anchor pointer will be freed by the token descructor.
357 * @param[in] anchor The anchor.
358 * @param[in] start_mark The beginning of the token.
359 * @param[in] end_mark The end of the token.
361 * @returns A new token object, or @c NULL on error.
364 YAML_DECLARE(yaml_token_t *)
365 yaml_anchor_token_new(yaml_char_t *anchor,
366 yaml_mark_t start_mark, yaml_mark_t end_mark);
369 * Create a new @c YAML_TAG_TOKEN token with the specified tag handle and
372 * Note that the @a handle and the @a suffix pointers will be freed by
373 * the token descructor.
375 * @param[in] handle The tag handle.
376 * @param[in] suffix The tag suffix.
377 * @param[in] start_mark The beginning of the token.
378 * @param[in] end_mark The end of the token.
380 * @returns A new token object, or @c NULL on error.
383 YAML_DECLARE(yaml_token_t *)
384 yaml_tag_token_new(yaml_char_t *handle, yaml_char_t *suffix,
385 yaml_mark_t start_mark, yaml_mark_t end_mark);
388 * Create a new @c YAML_SCALAR_TOKEN token with the specified scalar value,
391 * Note that the scalar value may contain the @c NUL character, therefore
392 * the value length is also required. The scalar value always ends with
395 * Note that the @a value pointer will be freed by the token descructor.
397 * @param[in] value The scalar value.
398 * @param[in] length The value length.
399 * @param[in] style The scalar style.
400 * @param[in] start_mark The beginning of the token.
401 * @param[in] end_mark The end of the token.
403 * @returns A new token object, or @c NULL on error.
406 YAML_DECLARE(yaml_token_t *)
407 yaml_scalar_token_new(yaml_char_t *value, size_t length,
408 yaml_scalar_style_t style,
409 yaml_mark_t start_mark, yaml_mark_t end_mark);
412 * Destroy a token object.
414 * @param[in] token A token object.
418 yaml_token_delete(yaml_token_t *token);
425 YAML_STREAM_START_EVENT,
426 YAML_STREAM_END_EVENT,
428 YAML_DOCUMENT_START_EVENT,
429 YAML_DOCUMENT_END_EVENT,
434 YAML_SEQUENCE_START_EVENT,
435 YAML_SEQUENCE_END_EVENT,
437 YAML_MAPPING_START_EVENT,
438 YAML_MAPPING_END_EVENT
442 yaml_event_type_t type;
445 yaml_encoding_t encoding;
471 yaml_scalar_style_t style;
477 yaml_sequence_style_t style;
483 yaml_mapping_style_t style;
486 yaml_mark_t start_mark;
487 yaml_mark_t end_mark;
494 * @defgroup parser Parser Definitions
499 * The prototype of a read handler.
501 * The read handler is called when the parser needs to read more bytes from the
502 * source. The handler should write not more than @a size bytes to the @a
503 * buffer. The number of written bytes should be set to the @a length variable.
505 * @param[in] data A pointer to an application data specified by
506 * @c yaml_parser_set_read_handler.
507 * @param[out] buffer The buffer to write the data from the source.
508 * @param[in] size The size of the buffer.
509 * @param[out] size_read The actual number of bytes read from the source.
511 * @returns On success, the handler should return @c 1. If the handler failed,
512 * the returned value should be @c 0. On EOF, the handler should set the
513 * @a length to @c 0 and return @c 1.
516 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
520 * This structure holds a string input specified by
521 * @c yaml_parser_set_input_string.
525 /** The string start pointer. */
526 unsigned char *start;
528 /** The string end pointer. */
531 /** The string current position. */
532 unsigned char *current;
533 } yaml_string_input_t;
536 * The parser structure.
538 * All members are internal. Manage the structure using the @c yaml_parser_
539 * family of functions.
545 * @name Error handling
550 yaml_error_type_t error;
552 /** Error description. */
555 /** The byte about which the problem occured. */
556 size_t problem_offset;
558 /** The problematic value (@c -1 is none). */
571 yaml_read_handler_t *read_handler;
573 /** A pointer for passing to the read handler. */
574 void *read_handler_data;
579 /** The pointer to the beginning of the working buffer. */
582 /** The pointer to the end of the working buffer. */
583 yaml_char_t *buffer_end;
585 /** The pointer to the current character in the working buffer. */
586 yaml_char_t *pointer;
588 /** The number of unread characters in the working buffer. */
591 /** The pointer to the beginning of the raw buffer. */
592 unsigned char *raw_buffer;
594 /** The pointer to the current character in the raw buffer. */
595 unsigned char *raw_pointer;
597 /** The number of unread bytes in the raw buffer. */
600 /** The input encoding. */
601 yaml_encoding_t encoding;
603 /** The offset of the current position (in bytes). */
606 /** The index of the current position (in characters). */
609 /** The line of the current position (starting from @c 0). */
612 /** The column of the current position (starting from @c 0). */
615 /* String input structure. */
616 yaml_string_input_t string_input;
625 * Create a new parser.
627 * This function creates a new parser object. An application is responsible
628 * for destroying the object using the @c yaml_parser_delete function.
630 * @returns A new parser object; @c NULL on error.
633 YAML_DECLARE(yaml_parser_t *)
634 yaml_parser_new(void);
639 * @param[in] parser A parser object.
643 yaml_parser_delete(yaml_parser_t *parser);
646 * Set a string input.
648 * Note that the @a input pointer must be valid while the @a parser object
649 * exists. The application is responsible for destroing @a input after
650 * destroying the @a parser.
652 * @param[in] parser A parser object.
653 * @param[in] input A source data.
654 * @param[in] size The length of the source data in bytes.
658 yaml_parser_set_input_string(yaml_parser_t *parser,
659 unsigned char *input, size_t size);
665 * @a file should be a file object open for reading. The application is
666 * responsible for closing the @a file.
668 * @param[in] parser A parser object.
669 * @param[in] file An open file.
673 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
676 * Set a generic input handler.
678 * @param[in] parser A parser object.
679 * @param[in] handler A read handler.
680 * @param[in] data Any application data for passing to the read handler.
684 yaml_parser_set_input(yaml_parser_t *parser,
685 yaml_read_handler_t *handler, void *data);
688 * Set the source encoding.
690 * @param[in] parser A parser object.
691 * @param[in] encoding The source encoding.
695 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
705 * @defgroup internal Internal Definitions
710 * Allocate a dynamic memory block.
712 * @param[in] size Size of a memory block, \c 0 is valid.
714 * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
715 * or @c NULL if it failed.
719 yaml_malloc(size_t size);
722 * Reallocate a dynamic memory block.
724 * @param[in] ptr A pointer to an existing memory block, \c NULL is
726 * @param[in] size A size of a new block, \c 0 is valid.
728 * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
729 * or @c NULL if it failed.
733 yaml_realloc(void *ptr, size_t size);
736 * Free a dynamic memory block.
738 * @param[in] ptr A pointer to an existing memory block, \c NULL is
743 yaml_free(void *ptr);
745 /** The size of the raw buffer. */
747 #define YAML_RAW_BUFFER_SIZE 16384
750 * The size of the buffer.
752 * We allocate enough space for decoding the whole raw buffer.
755 #define YAML_BUFFER_SIZE (YAML_RAW_BUFFER_SIZE*3)
758 * Ensure that the buffer contains at least @a length characters.
760 * @param[in] parser A parser object.
761 * @param[in] length The number of characters in the buffer.
763 * @returns @c 1 on success, @c 0 on error.
767 yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
776 #endif /* #ifndef YAML_H */