3 * @brief Public interface for libyaml.
5 * Include the header file with the code:
7 * #include <yaml/yaml.h>
23 * @defgroup version Version Information
28 * Get the library version as a string.
30 * @returns The function returns the pointer to a static string of the form
31 * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version
32 * number, and @c Z is the patch version number.
36 yaml_get_version_string(void);
39 * Get the library version numbers.
41 * @param[out] major Major version number.
42 * @param[out] minor Minor version number.
43 * @param[out] patch Patch version number.
47 yaml_get_version(int *major, int *minor, int *patch);
52 * @defgroup basic Basic Types
56 /** The character type. */
57 typedef unsigned char yaml_char_t;
59 /** The stream encoding. */
63 YAML_UTF16LE_ENCODING,
67 /** Many bad things could happen with the parser and emitter. */
86 YAML_ANY_SCALAR_STYLE,
87 YAML_PLAIN_SCALAR_STYLE,
88 YAML_SINGLE_QUOTED_SCALAR_STYLE,
89 YAML_DOUBLE_QUOTED_SCALAR_STYLE,
90 YAML_LITERAL_SCALAR_STYLE,
91 YAML_FOLDED_SCALAR_STYLE
92 } yaml_scalar_style_t;
95 YAML_ANY_SEQUENCE_STYLE,
96 YAML_BLOCK_SEQUENCE_STYLE,
97 YAML_FLOW_SEQUENCE_STYLE
98 } yaml_sequence_style_t;
101 YAML_ANY_MAPPING_STYLE,
102 YAML_BLOCK_MAPPING_STYLE,
103 YAML_FLOW_MAPPING_STYLE
104 } yaml_mapping_style_t;
107 YAML_STREAM_START_TOKEN,
108 YAML_STREAM_END_TOKEN,
110 YAML_VERSION_DIRECTIVE_TOKEN,
111 YAML_TAG_DIRECTIVE_TOKEN,
112 YAML_DOCUMENT_START_TOKEN,
113 YAML_DOCUMENT_END_TOKEN,
115 YAML_BLOCK_SEQUENCE_START_TOKEN,
116 YAML_BLOCK_MAPPING_START_TOKEN,
117 YAML_BLOCK_END_TOKEN,
119 YAML_FLOW_SEQUENCE_START_TOKEN,
120 YAML_FLOW_SEQUENCE_END_TOKEN,
121 YAML_FLOW_MAPPING_START_TOKEN,
122 YAML_FLOW_MAPPING_END_TOKEN,
124 YAML_BLOCK_ENTRY_TOKEN,
125 YAML_FLOW_ENTRY_TOKEN,
136 YAML_STREAM_START_EVENT,
137 YAML_STREAM_END_EVENT,
139 YAML_DOCUMENT_START_EVENT,
140 YAML_DOCUMENT_END_EVENT,
145 YAML_SEQUENCE_START_EVENT,
146 YAML_SEQUENCE_END_EVENT,
148 YAML_MAPPING_START_EVENT,
149 YAML_MAPPING_END_EVENT
160 yaml_error_type_t type;
162 yaml_mark_t context_mark;
164 yaml_mark_t problem_mark;
168 yaml_token_type_t type;
170 yaml_encoding_t encoding;
176 yaml_scalar_style_t style;
187 yaml_mark_t start_mark;
188 yaml_mark_t end_mark;
192 yaml_event_type_t type;
195 yaml_encoding_t encoding;
221 yaml_scalar_style_t style;
227 yaml_sequence_style_t style;
233 yaml_mapping_style_t style;
236 yaml_mark_t start_mark;
237 yaml_mark_t end_mark;
244 * @defgroup parser Parser Definitions
249 * The prototype of a read handler.
251 * The read handler is called when the parser needs to read more bytes from the
252 * source. The handler should write not more than @a size bytes to the @a
253 * buffer. The number of written bytes should be set to the @a length variable.
255 * @param[in] data A pointer to an application data specified by
256 * @c yaml_parser_set_read_handler.
257 * @param[out] buffer The buffer to write the data from the source.
258 * @param[in] size The size of the buffer.
259 * @param[out] size_read The actual number of bytes read from the source.
261 * @returns On success, the handler should return @c 1. If the handler failed,
262 * the returned value should be @c 0. On EOF, the handler should set the
263 * @a length to @c 0 and return @c 1.
266 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
270 * This structure holds a string input specified by
271 * @c yaml_parser_set_input_string.
275 unsigned char *start;
277 unsigned char *current;
278 } yaml_string_input_t;
281 * The parser structure.
283 * All members are internal. Manage the structure using the @c yaml_parser_
284 * family of functions.
290 * @name Error handling
295 yaml_error_type_t error;
297 /** Error description. */
300 /** The byte about which the problem occured. */
301 size_t problem_offset;
313 yaml_read_handler_t *read_handler;
315 /** A pointer for passing to the read handler. */
316 void *read_handler_data;
321 /** The pointer to the beginning of the working buffer. */
324 /** The pointer to the end of the working buffer. */
325 yaml_char_t *buffer_end;
327 /** The pointer to the current character in the working buffer. */
328 yaml_char_t *pointer;
330 /** The number of unread characters in the working buffer. */
333 /** The pointer to the beginning of the raw buffer. */
334 unsigned char *raw_buffer;
336 /** The pointer to the current character in the raw buffer. */
337 unsigned char *raw_pointer;
339 /** The number of unread bytes in the raw buffer. */
342 /** The input encoding. */
343 yaml_encoding_t encoding;
345 /** The offset of the current position (in bytes). */
348 /** The index of the current position (in characters). */
351 /** The line of the current position (starting from @c 0). */
354 /** The column of the current position (starting from @c 0). */
357 /* String input structure. */
358 yaml_string_input_t string_input;
367 * Create a new parser.
369 * This function creates a new parser object. An application is responsible
370 * for destroying the object using the @c yaml_parser_delete function.
372 * @returns A new parser object; @c NULL on error.
376 yaml_parser_new(void);
381 * @param[in] parser A parser object.
385 yaml_parser_delete(yaml_parser_t *parser);
388 * Set a string input.
390 * Note that the @a input pointer must be valid while the @a parser object
391 * exists. The application is responsible for destroing @a input after
392 * destroying the @a parser.
394 * @param[in] parser A parser object.
395 * @param[in] input A source data.
396 * @param[in] length The length of the source data in bytes.
400 yaml_parser_set_input_string(yaml_parser_t *parser,
401 unsigned char *input, size_t size);
407 * @a file should be a file object open for reading. The application is
408 * responsible for closing the @a file.
410 * @param[in] parser A parser object.
411 * @param[in] file An open file.
415 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
418 * Set a generic input handler.
420 * @param[in] parser A parser object.
421 * @param[in] handler A read handler.
422 * @param[in] data Any application data for passing to the read handler.
426 yaml_parser_set_input(yaml_parser_t *parser,
427 yaml_read_handler_t *handler, void *data);
430 * Set the source encoding.
432 * @param[in] encoding The source encoding.
436 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
446 * @defgroup internal Internal Definitions
451 * Allocate a dynamic memory block.
453 * @param[in] size Size of a memory block, \c 0 is valid.
455 * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
456 * or @c NULL if it failed.
460 yaml_malloc(size_t size);
463 * Reallocate a dynamic memory block.
465 * @param[in] ptr A pointer to an existing memory block, \c NULL is
467 * @param[in] size A size of a new block, \c 0 is valid.
469 * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
470 * or @c NULL if it failed.
474 yaml_realloc(void *ptr, size_t size);
477 * Free a dynamic memory block.
479 * @param[in] ptr A pointer to an existing memory block, \c NULL is
484 yaml_free(void *ptr);
486 /** The size of the raw buffer. */
488 #define YAML_RAW_BUFFER_SIZE 16384
491 * The size of the buffer.
493 * We allocate enough space for decoding the whole raw buffer.
496 #define YAML_BUFFER_SIZE (YAML_RAW_BUFFER_SIZE*3)
499 * Ensure that the buffer contains at least @a length characters.
501 * @param[in] parser A parser object.
502 * @param[in] length The number of characters in the buffer.
504 * @returns @c 1 on success, @c 0 on error.
508 yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
517 #endif /* #ifndef YAML_H */