]>
Commit | Line | Data |
---|---|---|
721c1923 KS |
1 | /** |
2 | * @file yaml.h | |
3 | * @brief Public interface for libyaml. | |
4 | * | |
a51447c9 | 5 | * Include the header file with the code: |
721c1923 KS |
6 | * @code |
7 | * #include <yaml/yaml.h> | |
8 | * @endcode | |
9 | */ | |
9e05b78c | 10 | |
cec6fc98 KS |
11 | #ifndef YAML_H |
12 | #define YAML_H | |
9e05b78c KS |
13 | |
14 | #ifdef __cplusplus | |
15 | extern "C" { | |
16 | #endif | |
17 | ||
cec6fc98 | 18 | #include <stdlib.h> |
95b98ba9 KS |
19 | #include <stdio.h> |
20 | #include <string.h> | |
cec6fc98 | 21 | |
a51447c9 KS |
22 | /** |
23 | * @defgroup version Version Information | |
24 | * @{ | |
25 | */ | |
26 | ||
27 | /** | |
28 | * Get the library version as a string. | |
29 | * | |
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. | |
33 | */ | |
34 | ||
35 | const char * | |
36 | yaml_get_version_string(void); | |
37 | ||
38 | /** | |
39 | * Get the library version numbers. | |
40 | * | |
41 | * @param[out] major Major version number. | |
42 | * @param[out] minor Minor version number. | |
43 | * @param[out] patch Patch version number. | |
44 | */ | |
45 | ||
46 | void | |
47 | yaml_get_version(int *major, int *minor, int *patch); | |
48 | ||
49 | /** @} */ | |
50 | ||
51 | /** | |
52 | * @defgroup basic Basic Types | |
53 | * @{ | |
54 | */ | |
55 | ||
56 | /** The character type. */ | |
57 | typedef unsigned char yaml_char_t; | |
9e05b78c | 58 | |
a51447c9 | 59 | /** The stream encoding. */ |
9e05b78c | 60 | typedef enum { |
a51447c9 | 61 | YAML_ANY_ENCODING, |
9e05b78c KS |
62 | YAML_UTF8_ENCODING, |
63 | YAML_UTF16LE_ENCODING, | |
64 | YAML_UTF16BE_ENCODING | |
65 | } yaml_encoding_t; | |
66 | ||
95b98ba9 | 67 | /** Many bad things could happen with the parser and emitter. */ |
a51447c9 KS |
68 | typedef enum { |
69 | YAML_NO_ERROR, | |
70 | ||
71 | YAML_MEMORY_ERROR, | |
72 | ||
73 | YAML_READER_ERROR, | |
74 | YAML_SCANNER_ERROR, | |
75 | YAML_PARSER_ERROR, | |
76 | ||
77 | YAML_WRITER_ERROR, | |
78 | YAML_EMITTER_ERROR | |
79 | } yaml_error_type_t; | |
80 | ||
95b98ba9 KS |
81 | /** @} */ |
82 | ||
83 | /* | |
84 | ||
9e05b78c | 85 | typedef enum { |
cec6fc98 | 86 | YAML_ANY_SCALAR_STYLE, |
9e05b78c KS |
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; | |
93 | ||
94 | typedef enum { | |
cec6fc98 | 95 | YAML_ANY_SEQUENCE_STYLE, |
9e05b78c KS |
96 | YAML_BLOCK_SEQUENCE_STYLE, |
97 | YAML_FLOW_SEQUENCE_STYLE | |
98 | } yaml_sequence_style_t; | |
99 | ||
100 | typedef enum { | |
cec6fc98 | 101 | YAML_ANY_MAPPING_STYLE, |
9e05b78c KS |
102 | YAML_BLOCK_MAPPING_STYLE, |
103 | YAML_FLOW_MAPPING_STYLE | |
104 | } yaml_mapping_style_t; | |
105 | ||
106 | typedef enum { | |
107 | YAML_STREAM_START_TOKEN, | |
108 | YAML_STREAM_END_TOKEN, | |
cec6fc98 | 109 | |
9e05b78c KS |
110 | YAML_VERSION_DIRECTIVE_TOKEN, |
111 | YAML_TAG_DIRECTIVE_TOKEN, | |
112 | YAML_DOCUMENT_START_TOKEN, | |
113 | YAML_DOCUMENT_END_TOKEN, | |
cec6fc98 | 114 | |
9e05b78c KS |
115 | YAML_BLOCK_SEQUENCE_START_TOKEN, |
116 | YAML_BLOCK_MAPPING_START_TOKEN, | |
117 | YAML_BLOCK_END_TOKEN, | |
cec6fc98 | 118 | |
9e05b78c KS |
119 | YAML_FLOW_SEQUENCE_START_TOKEN, |
120 | YAML_FLOW_SEQUENCE_END_TOKEN, | |
121 | YAML_FLOW_MAPPING_START_TOKEN, | |
122 | YAML_FLOW_MAPPING_END_TOKEN, | |
cec6fc98 | 123 | |
9e05b78c KS |
124 | YAML_BLOCK_ENTRY_TOKEN, |
125 | YAML_FLOW_ENTRY_TOKEN, | |
126 | YAML_KEY_TOKEN, | |
127 | YAML_VALUE_TOKEN, | |
cec6fc98 | 128 | |
9e05b78c KS |
129 | YAML_ALIAS_TOKEN, |
130 | YAML_ANCHOR_TOKEN, | |
131 | YAML_TAG_TOKEN, | |
132 | YAML_SCALAR_TOKEN | |
133 | } yaml_token_type_t; | |
134 | ||
135 | typedef enum { | |
136 | YAML_STREAM_START_EVENT, | |
137 | YAML_STREAM_END_EVENT, | |
cec6fc98 | 138 | |
9e05b78c KS |
139 | YAML_DOCUMENT_START_EVENT, |
140 | YAML_DOCUMENT_END_EVENT, | |
cec6fc98 | 141 | |
9e05b78c | 142 | YAML_ALIAS_EVENT, |
cec6fc98 KS |
143 | YAML_SCALAR_EVENT, |
144 | ||
9e05b78c KS |
145 | YAML_SEQUENCE_START_EVENT, |
146 | YAML_SEQUENCE_END_EVENT, | |
cec6fc98 | 147 | |
9e05b78c | 148 | YAML_MAPPING_START_EVENT, |
cec6fc98 | 149 | YAML_MAPPING_END_EVENT |
9e05b78c KS |
150 | } yaml_event_type_t; |
151 | ||
152 | typedef struct { | |
cec6fc98 | 153 | size_t offset; |
9e05b78c KS |
154 | size_t index; |
155 | size_t line; | |
156 | size_t column; | |
157 | } yaml_mark_t; | |
158 | ||
159 | typedef struct { | |
160 | yaml_error_type_t type; | |
161 | char *context; | |
162 | yaml_mark_t context_mark; | |
163 | char *problem; | |
164 | yaml_mark_t problem_mark; | |
165 | } yaml_error_t; | |
166 | ||
167 | typedef struct { | |
168 | yaml_token_type_t type; | |
169 | union { | |
170 | yaml_encoding_t encoding; | |
cec6fc98 KS |
171 | char *anchor; |
172 | char *tag; | |
9e05b78c | 173 | struct { |
cec6fc98 KS |
174 | char *value; |
175 | size_t length; | |
9e05b78c KS |
176 | yaml_scalar_style_t style; |
177 | } scalar; | |
178 | struct { | |
179 | int major; | |
180 | int minor; | |
181 | } version; | |
182 | struct { | |
cec6fc98 KS |
183 | char *handle; |
184 | char *prefix; | |
9e05b78c KS |
185 | } tag_pair; |
186 | } data; | |
187 | yaml_mark_t start_mark; | |
188 | yaml_mark_t end_mark; | |
189 | } yaml_token_t; | |
190 | ||
191 | typedef struct { | |
192 | yaml_event_type_t type; | |
193 | union { | |
194 | struct { | |
195 | yaml_encoding_t encoding; | |
196 | } stream_start; | |
197 | struct { | |
198 | struct { | |
199 | int major; | |
200 | int minor; | |
201 | } version; | |
202 | struct { | |
cec6fc98 KS |
203 | char *handle; |
204 | char *prefix; | |
9e05b78c KS |
205 | } **tag_pairs; |
206 | int implicit; | |
207 | } document_start; | |
208 | struct { | |
209 | int implicit; | |
210 | } document_end; | |
211 | struct { | |
cec6fc98 | 212 | char *anchor; |
9e05b78c KS |
213 | } alias; |
214 | struct { | |
cec6fc98 KS |
215 | char *anchor; |
216 | char *tag; | |
217 | char *value; | |
218 | size_t length; | |
9e05b78c KS |
219 | int plain_implicit; |
220 | int quoted_implicit; | |
221 | yaml_scalar_style_t style; | |
222 | } scalar; | |
223 | struct { | |
cec6fc98 KS |
224 | char *anchor; |
225 | char *tag; | |
9e05b78c KS |
226 | int implicit; |
227 | yaml_sequence_style_t style; | |
228 | } sequence_start; | |
229 | struct { | |
cec6fc98 KS |
230 | char *anchor; |
231 | char *tag; | |
9e05b78c KS |
232 | int implicit; |
233 | yaml_mapping_style_t style; | |
234 | } mapping_start; | |
235 | } data; | |
236 | yaml_mark_t start_mark; | |
237 | yaml_mark_t end_mark; | |
238 | } yaml_event_t; | |
239 | ||
a51447c9 KS |
240 | */ |
241 | ||
242 | ||
243 | /** | |
244 | * @defgroup parser Parser Definitions | |
245 | * @{ | |
246 | */ | |
247 | ||
248 | /** | |
249 | * The prototype of a read handler. | |
250 | * | |
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. | |
254 | * | |
6eb1ded4 | 255 | * @param[in] data A pointer to an application data specified by |
95b98ba9 KS |
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. | |
a51447c9 KS |
260 | * |
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. | |
264 | */ | |
6eb1ded4 KS |
265 | |
266 | typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size, | |
95b98ba9 | 267 | size_t *size_read); |
a51447c9 | 268 | |
6eb1ded4 KS |
269 | /** |
270 | * This structure holds a string input specified by | |
271 | * @c yaml_parser_set_input_string. | |
272 | */ | |
273 | ||
274 | typedef struct { | |
275 | unsigned char *start; | |
276 | unsigned char *end; | |
277 | unsigned char *current; | |
278 | } yaml_string_input_t; | |
279 | ||
a51447c9 KS |
280 | /** |
281 | * The parser structure. | |
282 | * | |
283 | * All members are internal. Manage the structure using the @c yaml_parser_ | |
284 | * family of functions. | |
285 | */ | |
286 | ||
9e05b78c | 287 | typedef struct { |
a51447c9 | 288 | |
95b98ba9 KS |
289 | /** |
290 | * @name Error handling | |
291 | * @{ | |
292 | */ | |
293 | ||
3d790dfd | 294 | /** Error type. */ |
6eb1ded4 | 295 | yaml_error_type_t error; |
95b98ba9 | 296 | |
3d790dfd KS |
297 | /** Error description. */ |
298 | const char *problem; | |
299 | ||
300 | /** The byte about which the problem occured. */ | |
301 | size_t problem_offset; | |
302 | ||
95b98ba9 KS |
303 | /** |
304 | * @} | |
305 | */ | |
306 | ||
a51447c9 KS |
307 | /** |
308 | * @name Reader stuff | |
309 | * @{ | |
310 | */ | |
311 | ||
3d790dfd | 312 | /** Read handler. */ |
95b98ba9 | 313 | yaml_read_handler_t *read_handler; |
a51447c9 KS |
314 | |
315 | /** A pointer for passing to the read handler. */ | |
95b98ba9 | 316 | void *read_handler_data; |
a51447c9 KS |
317 | |
318 | /** EOF flag */ | |
319 | int eof; | |
320 | ||
321 | /** The pointer to the beginning of the working buffer. */ | |
322 | yaml_char_t *buffer; | |
323 | ||
6eb1ded4 KS |
324 | /** The pointer to the end of the working buffer. */ |
325 | yaml_char_t *buffer_end; | |
95b98ba9 | 326 | |
a51447c9 | 327 | /** The pointer to the current character in the working buffer. */ |
6eb1ded4 | 328 | yaml_char_t *pointer; |
95b98ba9 | 329 | |
6eb1ded4 KS |
330 | /** The number of unread characters in the working buffer. */ |
331 | size_t unread; | |
a51447c9 | 332 | |
6eb1ded4 | 333 | /** The pointer to the beginning of the raw buffer. */ |
a51447c9 KS |
334 | unsigned char *raw_buffer; |
335 | ||
6eb1ded4 KS |
336 | /** The pointer to the current character in the raw buffer. */ |
337 | unsigned char *raw_pointer; | |
a51447c9 | 338 | |
6eb1ded4 KS |
339 | /** The number of unread bytes in the raw buffer. */ |
340 | size_t raw_unread; | |
95b98ba9 | 341 | |
a51447c9 KS |
342 | /** The input encoding. */ |
343 | yaml_encoding_t encoding; | |
344 | ||
95b98ba9 KS |
345 | /** The offset of the current position (in bytes). */ |
346 | size_t offset; | |
347 | ||
348 | /** The index of the current position (in characters). */ | |
349 | size_t index; | |
350 | ||
351 | /** The line of the current position (starting from @c 0). */ | |
352 | size_t line; | |
353 | ||
354 | /** The column of the current position (starting from @c 0). */ | |
355 | size_t column; | |
356 | ||
6eb1ded4 KS |
357 | /* String input structure. */ |
358 | yaml_string_input_t string_input; | |
359 | ||
a51447c9 KS |
360 | /** |
361 | * @} | |
362 | */ | |
363 | ||
9e05b78c KS |
364 | } yaml_parser_t; |
365 | ||
a51447c9 KS |
366 | /** |
367 | * Create a new parser. | |
368 | * | |
369 | * This function creates a new parser object. An application is responsible | |
370 | * for destroying the object using the @c yaml_parser_delete function. | |
371 | * | |
372 | * @returns A new parser object; @c NULL on error. | |
373 | */ | |
374 | ||
375 | yaml_parser_t * | |
376 | yaml_parser_new(void); | |
377 | ||
378 | /** | |
379 | * Destroy a parser. | |
380 | * | |
381 | * @param[in] parser A parser object. | |
382 | */ | |
383 | ||
384 | void | |
385 | yaml_parser_delete(yaml_parser_t *parser); | |
386 | ||
95b98ba9 KS |
387 | /** |
388 | * Set a string input. | |
389 | * | |
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. | |
393 | * | |
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. | |
397 | */ | |
398 | ||
399 | void | |
400 | yaml_parser_set_input_string(yaml_parser_t *parser, | |
401 | unsigned char *input, size_t size); | |
402 | ||
403 | ||
404 | /** | |
405 | * Set a file input. | |
406 | * | |
407 | * @a file should be a file object open for reading. The application is | |
408 | * responsible for closing the @a file. | |
409 | * | |
410 | * @param[in] parser A parser object. | |
411 | * @param[in] file An open file. | |
412 | */ | |
413 | ||
414 | void | |
415 | yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file); | |
416 | ||
417 | /** | |
418 | * Set a generic input handler. | |
419 | * | |
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. | |
423 | */ | |
424 | ||
425 | void | |
426 | yaml_parser_set_input(yaml_parser_t *parser, | |
427 | yaml_read_handler_t *handler, void *data); | |
428 | ||
429 | /** | |
430 | * Set the source encoding. | |
431 | * | |
432 | * @param[in] encoding The source encoding. | |
433 | */ | |
434 | ||
435 | void | |
436 | yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding); | |
437 | ||
a51447c9 KS |
438 | /** @} */ |
439 | ||
440 | /* | |
9e05b78c KS |
441 | typedef struct { |
442 | } yaml_emitter_t; | |
cec6fc98 | 443 | */ |
9e05b78c | 444 | |
95b98ba9 KS |
445 | /** |
446 | * @defgroup internal Internal Definitions | |
447 | * @{ | |
448 | */ | |
449 | ||
450 | /** | |
451 | * Allocate a dynamic memory block. | |
452 | * | |
453 | * @param[in] size Size of a memory block, \c 0 is valid. | |
454 | * | |
455 | * @returns @c yaml_malloc returns a pointer to a newly allocated memory block, | |
456 | * or @c NULL if it failed. | |
457 | */ | |
458 | ||
459 | void * | |
460 | yaml_malloc(size_t size); | |
461 | ||
462 | /** | |
463 | * Reallocate a dynamic memory block. | |
464 | * | |
465 | * @param[in] ptr A pointer to an existing memory block, \c NULL is | |
466 | * valid. | |
467 | * @param[in] size A size of a new block, \c 0 is valid. | |
468 | * | |
469 | * @returns @c yaml_realloc returns a pointer to a reallocated memory block, | |
470 | * or @c NULL if it failed. | |
471 | */ | |
472 | ||
473 | void * | |
474 | yaml_realloc(void *ptr, size_t size); | |
475 | ||
476 | /** | |
477 | * Free a dynamic memory block. | |
478 | * | |
479 | * @param[in] ptr A pointer to an existing memory block, \c NULL is | |
480 | * valid. | |
481 | */ | |
482 | ||
483 | void | |
484 | yaml_free(void *ptr); | |
485 | ||
6eb1ded4 KS |
486 | /** The size of the raw buffer. */ |
487 | ||
488 | #define YAML_RAW_BUFFER_SIZE 16384 | |
489 | ||
490 | /** | |
491 | * The size of the buffer. | |
492 | * | |
493 | * We allocate enough space for decoding the whole raw buffer. | |
494 | */ | |
495 | ||
496 | #define YAML_BUFFER_SIZE (YAML_RAW_BUFFER_SIZE*3) | |
497 | ||
3d790dfd KS |
498 | /** |
499 | * Ensure that the buffer contains at least @a length characters. | |
500 | * | |
501 | * @param[in] parser A parser object. | |
502 | * @param[in] length The number of characters in the buffer. | |
503 | * | |
504 | * @returns @c 1 on success, @c 0 on error. | |
505 | */ | |
506 | ||
507 | int | |
508 | yaml_parser_update_buffer(yaml_parser_t *parser, size_t length); | |
509 | ||
95b98ba9 KS |
510 | /** @} */ |
511 | ||
512 | ||
9e05b78c KS |
513 | #ifdef __cplusplus |
514 | } | |
515 | #endif | |
516 | ||
cec6fc98 | 517 | #endif /* #ifndef YAML_H */ |
9e05b78c | 518 |