]>
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 | |
f642fd11 | 22 | /** |
03be97ab | 23 | * @defgroup export Export Definitions |
f642fd11 KS |
24 | * @{ |
25 | */ | |
26 | ||
27 | /** The public API declaration. */ | |
28 | ||
29 | #ifdef WIN32 | |
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 | |
34 | # else | |
35 | # define YAML_DECLARE(type) __declspec(dllimport) type | |
36 | # endif | |
37 | #else | |
38 | # define YAML_DECLARE(type) type | |
39 | #endif | |
40 | ||
41 | /** @} */ | |
42 | ||
a51447c9 KS |
43 | /** |
44 | * @defgroup version Version Information | |
45 | * @{ | |
46 | */ | |
47 | ||
48 | /** | |
49 | * Get the library version as a string. | |
50 | * | |
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. | |
54 | */ | |
55 | ||
f642fd11 | 56 | YAML_DECLARE(const char *) |
a51447c9 KS |
57 | yaml_get_version_string(void); |
58 | ||
59 | /** | |
60 | * Get the library version numbers. | |
61 | * | |
62 | * @param[out] major Major version number. | |
63 | * @param[out] minor Minor version number. | |
64 | * @param[out] patch Patch version number. | |
65 | */ | |
66 | ||
f642fd11 | 67 | YAML_DECLARE(void) |
a51447c9 KS |
68 | yaml_get_version(int *major, int *minor, int *patch); |
69 | ||
70 | /** @} */ | |
71 | ||
72 | /** | |
73 | * @defgroup basic Basic Types | |
74 | * @{ | |
75 | */ | |
76 | ||
f642fd11 | 77 | /** The character type (UTF-8 octet). */ |
a51447c9 | 78 | typedef unsigned char yaml_char_t; |
9e05b78c | 79 | |
26687d7d KS |
80 | /** The version directive data. */ |
81 | typedef struct { | |
82 | /** The major version number. */ | |
83 | int major; | |
84 | /** The minor version number. */ | |
85 | int minor; | |
86 | } yaml_version_directive_t; | |
87 | ||
88 | /** The tag directive data. */ | |
89 | typedef struct { | |
90 | /** The tag handle. */ | |
91 | yaml_char_t *handle; | |
92 | /** The tag prefix. */ | |
93 | yaml_char_t *prefix; | |
94 | } yaml_tag_directive_t; | |
95 | ||
a51447c9 | 96 | /** The stream encoding. */ |
9e05b78c | 97 | typedef enum { |
a51447c9 | 98 | YAML_ANY_ENCODING, |
9e05b78c KS |
99 | YAML_UTF8_ENCODING, |
100 | YAML_UTF16LE_ENCODING, | |
101 | YAML_UTF16BE_ENCODING | |
102 | } yaml_encoding_t; | |
103 | ||
95b98ba9 | 104 | /** Many bad things could happen with the parser and emitter. */ |
a51447c9 KS |
105 | typedef enum { |
106 | YAML_NO_ERROR, | |
107 | ||
108 | YAML_MEMORY_ERROR, | |
109 | ||
110 | YAML_READER_ERROR, | |
111 | YAML_SCANNER_ERROR, | |
112 | YAML_PARSER_ERROR, | |
113 | ||
114 | YAML_WRITER_ERROR, | |
115 | YAML_EMITTER_ERROR | |
116 | } yaml_error_type_t; | |
117 | ||
f642fd11 KS |
118 | /** The pointer position. */ |
119 | typedef struct { | |
120 | /** The position index. */ | |
121 | size_t index; | |
122 | ||
123 | /** The position line. */ | |
124 | size_t line; | |
125 | ||
126 | /** The position column. */ | |
127 | size_t column; | |
128 | } yaml_mark_t; | |
129 | ||
95b98ba9 KS |
130 | /** @} */ |
131 | ||
f642fd11 | 132 | /** |
03be97ab | 133 | * @defgroup styles Node Styles |
f642fd11 KS |
134 | * @{ |
135 | */ | |
95b98ba9 | 136 | |
f642fd11 | 137 | /** Scalar styles. */ |
9e05b78c | 138 | typedef enum { |
cec6fc98 | 139 | YAML_ANY_SCALAR_STYLE, |
f642fd11 | 140 | |
9e05b78c | 141 | YAML_PLAIN_SCALAR_STYLE, |
f642fd11 | 142 | |
9e05b78c KS |
143 | YAML_SINGLE_QUOTED_SCALAR_STYLE, |
144 | YAML_DOUBLE_QUOTED_SCALAR_STYLE, | |
f642fd11 | 145 | |
9e05b78c KS |
146 | YAML_LITERAL_SCALAR_STYLE, |
147 | YAML_FOLDED_SCALAR_STYLE | |
148 | } yaml_scalar_style_t; | |
149 | ||
f642fd11 KS |
150 | |
151 | /** Sequence styles. */ | |
9e05b78c | 152 | typedef enum { |
cec6fc98 | 153 | YAML_ANY_SEQUENCE_STYLE, |
f642fd11 | 154 | |
9e05b78c KS |
155 | YAML_BLOCK_SEQUENCE_STYLE, |
156 | YAML_FLOW_SEQUENCE_STYLE | |
157 | } yaml_sequence_style_t; | |
158 | ||
f642fd11 | 159 | /** Mapping styles. */ |
9e05b78c | 160 | typedef enum { |
cec6fc98 | 161 | YAML_ANY_MAPPING_STYLE, |
f642fd11 | 162 | |
9e05b78c KS |
163 | YAML_BLOCK_MAPPING_STYLE, |
164 | YAML_FLOW_MAPPING_STYLE | |
165 | } yaml_mapping_style_t; | |
166 | ||
f642fd11 KS |
167 | /** @} */ |
168 | ||
169 | /** | |
03be97ab | 170 | * @defgroup tokens Tokens |
f642fd11 KS |
171 | * @{ |
172 | */ | |
173 | ||
174 | /** Token types. */ | |
9e05b78c KS |
175 | typedef enum { |
176 | YAML_STREAM_START_TOKEN, | |
177 | YAML_STREAM_END_TOKEN, | |
cec6fc98 | 178 | |
9e05b78c KS |
179 | YAML_VERSION_DIRECTIVE_TOKEN, |
180 | YAML_TAG_DIRECTIVE_TOKEN, | |
181 | YAML_DOCUMENT_START_TOKEN, | |
182 | YAML_DOCUMENT_END_TOKEN, | |
cec6fc98 | 183 | |
9e05b78c KS |
184 | YAML_BLOCK_SEQUENCE_START_TOKEN, |
185 | YAML_BLOCK_MAPPING_START_TOKEN, | |
186 | YAML_BLOCK_END_TOKEN, | |
cec6fc98 | 187 | |
9e05b78c KS |
188 | YAML_FLOW_SEQUENCE_START_TOKEN, |
189 | YAML_FLOW_SEQUENCE_END_TOKEN, | |
190 | YAML_FLOW_MAPPING_START_TOKEN, | |
191 | YAML_FLOW_MAPPING_END_TOKEN, | |
cec6fc98 | 192 | |
9e05b78c KS |
193 | YAML_BLOCK_ENTRY_TOKEN, |
194 | YAML_FLOW_ENTRY_TOKEN, | |
195 | YAML_KEY_TOKEN, | |
196 | YAML_VALUE_TOKEN, | |
cec6fc98 | 197 | |
9e05b78c KS |
198 | YAML_ALIAS_TOKEN, |
199 | YAML_ANCHOR_TOKEN, | |
200 | YAML_TAG_TOKEN, | |
201 | YAML_SCALAR_TOKEN | |
202 | } yaml_token_type_t; | |
203 | ||
f642fd11 KS |
204 | /** The token structure. */ |
205 | typedef struct { | |
cec6fc98 | 206 | |
f642fd11 KS |
207 | /** The token type. */ |
208 | yaml_token_type_t type; | |
cec6fc98 | 209 | |
f642fd11 KS |
210 | /** The token data. */ |
211 | union { | |
cec6fc98 | 212 | |
26687d7d KS |
213 | /** The stream start (for @c YAML_STREAM_START_TOKEN). */ |
214 | struct { | |
215 | /** The stream encoding. */ | |
216 | yaml_encoding_t encoding; | |
217 | } stream_start; | |
218 | ||
219 | /** The alias (for @c YAML_ALIAS_TOKEN). */ | |
220 | struct { | |
221 | /** The alias value. */ | |
222 | yaml_char_t *value; | |
223 | } alias; | |
cec6fc98 | 224 | |
26687d7d KS |
225 | /** The anchor (for @c YAML_ANCHOR_TOKEN). */ |
226 | struct { | |
227 | /** The anchor value. */ | |
228 | yaml_char_t *value; | |
229 | } anchor; | |
9e05b78c | 230 | |
f642fd11 KS |
231 | /** The tag (for @c YAML_TAG_TOKEN). */ |
232 | struct { | |
233 | /** The tag handle. */ | |
234 | yaml_char_t *handle; | |
9e05b78c | 235 | |
f642fd11 KS |
236 | /** The tag suffix. */ |
237 | yaml_char_t *suffix; | |
238 | } tag; | |
9e05b78c | 239 | |
f642fd11 | 240 | /** The scalar value (for @c YAML_SCALAR_TOKEN). */ |
9e05b78c | 241 | struct { |
f642fd11 KS |
242 | |
243 | /** The scalar value. */ | |
244 | yaml_char_t *value; | |
245 | ||
246 | /** The length of the scalar value. */ | |
cec6fc98 | 247 | size_t length; |
f642fd11 KS |
248 | |
249 | /** The scalar style. */ | |
9e05b78c KS |
250 | yaml_scalar_style_t style; |
251 | } scalar; | |
f642fd11 KS |
252 | |
253 | /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */ | |
9e05b78c | 254 | struct { |
f642fd11 | 255 | /** The major version number. */ |
9e05b78c | 256 | int major; |
f642fd11 KS |
257 | |
258 | /** The minor version number. */ | |
9e05b78c | 259 | int minor; |
f642fd11 KS |
260 | } version_directive; |
261 | ||
262 | /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */ | |
9e05b78c | 263 | struct { |
f642fd11 KS |
264 | /** The tag handle. */ |
265 | yaml_char_t *handle; | |
266 | ||
267 | /** The tag prefix. */ | |
268 | yaml_char_t *prefix; | |
269 | } tag_directive; | |
9e05b78c | 270 | } data; |
f642fd11 KS |
271 | |
272 | /** The beginning of the token. */ | |
9e05b78c | 273 | yaml_mark_t start_mark; |
f642fd11 KS |
274 | |
275 | /** The end of the token. */ | |
9e05b78c | 276 | yaml_mark_t end_mark; |
f642fd11 | 277 | |
9e05b78c KS |
278 | } yaml_token_t; |
279 | ||
f642fd11 KS |
280 | /** |
281 | * Create a new token without assigning any data. | |
282 | * | |
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. | |
291 | * | |
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. | |
295 | * | |
296 | * @returns A new token object, or @c NULL on error. | |
297 | */ | |
298 | ||
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); | |
302 | ||
303 | /** | |
304 | * Create a new @c YAML_STREAM_START_TOKEN token with the specified encoding. | |
305 | * | |
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. | |
309 | * | |
310 | * @returns A new token object, or @c NULL on error. | |
311 | */ | |
312 | ||
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); | |
316 | ||
317 | /** | |
318 | * Create a new @c YAML_STREAM_END_TOKEN token. | |
319 | * | |
320 | * @param[in] start_mark The beginning of the token. | |
321 | * @param[in] end_mark The end of the token. | |
322 | * | |
323 | * @returns A new token object, or @c NULL on error. | |
324 | */ | |
325 | ||
326 | YAML_DECLARE(yaml_token_t *) | |
327 | yaml_stream_end_token_new(yaml_mark_t start_mark, yaml_mark_t end_mark); | |
328 | ||
329 | /** | |
330 | * Create a new @c YAML_VERSION_DIRECTIVE_TOKEN token with the specified | |
331 | * version numbers. | |
332 | * | |
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. | |
337 | * | |
338 | * @returns A new token object, or @c NULL on error. | |
339 | */ | |
340 | ||
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); | |
344 | ||
345 | /** | |
346 | * Create a new @c YAML_TAG_DIRECTIVE_TOKEN token with the specified tag | |
347 | * handle and prefix. | |
348 | * | |
349 | * Note that the @a handle and the @a prefix pointers will be freed by | |
350 | * the token descructor. | |
351 | * | |
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. | |
356 | * | |
357 | * @returns A new token object, or @c NULL on error. | |
358 | */ | |
359 | ||
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); | |
363 | ||
364 | /** | |
365 | * Create a new @c YAML_ALIAS_TOKEN token with the specified anchor. | |
366 | * | |
367 | * Note that the @a anchor pointer will be freed by the token descructor. | |
368 | * | |
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. | |
372 | * | |
373 | * @returns A new token object, or @c NULL on error. | |
374 | */ | |
375 | ||
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); | |
379 | ||
380 | /** | |
381 | * Create a new @c YAML_ANCHOR_TOKEN token with the specified anchor. | |
382 | * | |
383 | * Note that the @a anchor pointer will be freed by the token descructor. | |
384 | * | |
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. | |
388 | * | |
389 | * @returns A new token object, or @c NULL on error. | |
390 | */ | |
391 | ||
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); | |
395 | ||
396 | /** | |
397 | * Create a new @c YAML_TAG_TOKEN token with the specified tag handle and | |
398 | * suffix. | |
399 | * | |
400 | * Note that the @a handle and the @a suffix pointers will be freed by | |
401 | * the token descructor. | |
402 | * | |
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. | |
407 | * | |
408 | * @returns A new token object, or @c NULL on error. | |
409 | */ | |
410 | ||
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); | |
414 | ||
415 | /** | |
416 | * Create a new @c YAML_SCALAR_TOKEN token with the specified scalar value, | |
417 | * length, and style. | |
418 | * | |
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 | |
421 | * @c NUL. | |
422 | * | |
423 | * Note that the @a value pointer will be freed by the token descructor. | |
424 | * | |
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. | |
430 | * | |
431 | * @returns A new token object, or @c NULL on error. | |
432 | */ | |
433 | ||
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); | |
438 | ||
439 | /** | |
440 | * Destroy a token object. | |
441 | * | |
442 | * @param[in] token A token object. | |
443 | */ | |
444 | ||
445 | YAML_DECLARE(void) | |
446 | yaml_token_delete(yaml_token_t *token); | |
447 | ||
448 | /** @} */ | |
449 | ||
26687d7d KS |
450 | /** |
451 | * @defgroup events Events | |
452 | * @{ | |
453 | */ | |
f642fd11 | 454 | |
26687d7d | 455 | /** Event types. */ |
f642fd11 KS |
456 | typedef enum { |
457 | YAML_STREAM_START_EVENT, | |
458 | YAML_STREAM_END_EVENT, | |
459 | ||
460 | YAML_DOCUMENT_START_EVENT, | |
461 | YAML_DOCUMENT_END_EVENT, | |
462 | ||
463 | YAML_ALIAS_EVENT, | |
464 | YAML_SCALAR_EVENT, | |
465 | ||
466 | YAML_SEQUENCE_START_EVENT, | |
467 | YAML_SEQUENCE_END_EVENT, | |
468 | ||
469 | YAML_MAPPING_START_EVENT, | |
470 | YAML_MAPPING_END_EVENT | |
471 | } yaml_event_type_t; | |
472 | ||
26687d7d | 473 | /** The event structure. */ |
9e05b78c | 474 | typedef struct { |
26687d7d KS |
475 | |
476 | /** The event type. */ | |
9e05b78c | 477 | yaml_event_type_t type; |
26687d7d KS |
478 | |
479 | /** The event data. */ | |
9e05b78c | 480 | union { |
26687d7d KS |
481 | |
482 | /** The stream parameters (for @c YAML_STREAM_START_EVENT). */ | |
9e05b78c | 483 | struct { |
26687d7d | 484 | /** The document encoding. */ |
9e05b78c KS |
485 | yaml_encoding_t encoding; |
486 | } stream_start; | |
26687d7d KS |
487 | |
488 | /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */ | |
9e05b78c | 489 | struct { |
26687d7d KS |
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? */ | |
9e05b78c KS |
495 | int implicit; |
496 | } document_start; | |
26687d7d KS |
497 | |
498 | /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */ | |
9e05b78c | 499 | struct { |
26687d7d | 500 | /** Is the document end indicator implicit? */ |
9e05b78c KS |
501 | int implicit; |
502 | } document_end; | |
26687d7d KS |
503 | |
504 | /** The alias parameters (for @c YAML_ALIAS_EVENT). */ | |
9e05b78c | 505 | struct { |
26687d7d KS |
506 | /** The anchor. */ |
507 | yaml_char_t *anchor; | |
9e05b78c | 508 | } alias; |
26687d7d KS |
509 | |
510 | /** The scalar parameters (for @c YAML_SCALAR_EVENT). */ | |
9e05b78c | 511 | struct { |
26687d7d KS |
512 | /** The anchor. */ |
513 | yaml_char_t *anchor; | |
514 | /** The tag. */ | |
515 | yaml_char_t *tag; | |
516 | /** The scalar value. */ | |
517 | yaml_char_t *value; | |
518 | /** The length of the scalar value. */ | |
cec6fc98 | 519 | size_t length; |
26687d7d | 520 | /** Is the tag optional for the plain style? */ |
9e05b78c | 521 | int plain_implicit; |
26687d7d | 522 | /** Is the tag optional for any non-plain style? */ |
9e05b78c | 523 | int quoted_implicit; |
26687d7d | 524 | /** The scalar style. */ |
9e05b78c KS |
525 | yaml_scalar_style_t style; |
526 | } scalar; | |
26687d7d KS |
527 | |
528 | /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */ | |
9e05b78c | 529 | struct { |
26687d7d KS |
530 | /** The anchor. */ |
531 | yaml_char_t *anchor; | |
532 | /** The tag. */ | |
533 | yaml_char_t *tag; | |
534 | /** Is the tag optional? */ | |
9e05b78c | 535 | int implicit; |
26687d7d | 536 | /** The sequence style. */ |
9e05b78c KS |
537 | yaml_sequence_style_t style; |
538 | } sequence_start; | |
26687d7d KS |
539 | |
540 | /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */ | |
9e05b78c | 541 | struct { |
26687d7d KS |
542 | /** The anchor. */ |
543 | yaml_char_t *anchor; | |
544 | /** The tag. */ | |
545 | yaml_char_t *tag; | |
546 | /** Is the tag optional? */ | |
9e05b78c | 547 | int implicit; |
26687d7d | 548 | /** The mapping style. */ |
9e05b78c KS |
549 | yaml_mapping_style_t style; |
550 | } mapping_start; | |
26687d7d | 551 | |
9e05b78c | 552 | } data; |
26687d7d KS |
553 | |
554 | /** The beginning of the token. */ | |
9e05b78c | 555 | yaml_mark_t start_mark; |
26687d7d KS |
556 | |
557 | /** The end of the token. */ | |
9e05b78c KS |
558 | yaml_mark_t end_mark; |
559 | } yaml_event_t; | |
560 | ||
26687d7d KS |
561 | /** |
562 | * Create a new @c YAML_STREAM_START_EVENT event. | |
563 | * | |
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. | |
567 | * | |
568 | * @returns A new event object, or @c NULL on error. | |
569 | */ | |
570 | ||
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); | |
574 | ||
575 | /** | |
576 | * Create a new @c YAML_STREAM_END_TOKEN event. | |
577 | * | |
578 | * @param[in] start_mark The beginning of the event. | |
579 | * @param[in] end_mark The end of the event. | |
580 | * | |
581 | * @returns A new event object, or @c NULL on error. | |
582 | */ | |
583 | ||
584 | YAML_DECLARE(yaml_event_t *) | |
585 | yaml_stream_end_event_new(yaml_mark_t start_mark, yaml_mark_t end_mark); | |
586 | ||
587 | /** | |
588 | * Create a new @c YAML_DOCUMENT_START_EVENT event. | |
589 | * | |
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. | |
595 | * | |
596 | * @returns A new event object, or @c NULL on error. | |
597 | */ | |
598 | ||
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); | |
603 | ||
604 | /** | |
605 | * Create a new @c YAML_DOCUMENT_END_EVENT event. | |
606 | * | |
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. | |
610 | * | |
611 | * @returns A new event object, or @c NULL on error. | |
612 | */ | |
613 | ||
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); | |
617 | ||
618 | /** | |
619 | * Create a new @c YAML_ALIAS_EVENT event. | |
620 | * | |
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. | |
624 | * | |
625 | * @returns A new event object, or @c NULL on error. | |
626 | */ | |
627 | ||
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); | |
631 | ||
632 | /** | |
633 | * Create a new @c YAML_SCALAR_EVENT event. | |
634 | * | |
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. | |
644 | * | |
645 | * @returns A new event object, or @c NULL on error. | |
646 | */ | |
647 | ||
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); | |
654 | ||
655 | /** | |
656 | * Create a new @c YAML_SEQUENCE_START_EVENT event. | |
657 | * | |
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. | |
664 | * | |
665 | * @returns A new event object, or @c NULL on error. | |
666 | */ | |
667 | ||
668 | YAML_DECLARE(yaml_event_t *) | |
669 | yaml_sequence_start_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); | |
672 | ||
673 | /** | |
674 | * Create a new @c YAML_SEQUENCE_END_EVENT event. | |
675 | * | |
676 | * @param[in] start_mark The beginning of the event. | |
677 | * @param[in] end_mark The end of the event. | |
678 | * | |
679 | * @returns A new event object, or @c NULL on error. | |
680 | */ | |
681 | ||
682 | YAML_DECLARE(yaml_event_t *) | |
683 | yaml_sequence_end_new(yaml_mark_t start_mark, yaml_mark_t end_mark); | |
684 | ||
685 | /** | |
686 | * Create a new @c YAML_MAPPING_START_EVENT event. | |
687 | * | |
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. | |
694 | * | |
695 | * @returns A new event object, or @c NULL on error. | |
696 | */ | |
697 | ||
698 | YAML_DECLARE(yaml_event_t *) | |
699 | yaml_mapping_start_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); | |
a51447c9 | 702 | |
26687d7d KS |
703 | /** |
704 | * Create a new @c YAML_MAPPING_END_EVENT event. | |
705 | * | |
706 | * @param[in] start_mark The beginning of the event. | |
707 | * @param[in] end_mark The end of the event. | |
708 | * | |
709 | * @returns A new event object, or @c NULL on error. | |
710 | */ | |
711 | ||
712 | YAML_DECLARE(yaml_event_t *) | |
713 | yaml_mapping_end_new(yaml_mark_t start_mark, yaml_mark_t end_mark); | |
714 | ||
715 | /** | |
716 | * Destroy an event object. | |
717 | * | |
718 | * @param[in] event An event object. | |
719 | */ | |
720 | ||
721 | YAML_DECLARE(void) | |
722 | yaml_event_delete(yaml_event_t *event); | |
723 | ||
724 | /** @} */ | |
a51447c9 KS |
725 | |
726 | /** | |
727 | * @defgroup parser Parser Definitions | |
728 | * @{ | |
729 | */ | |
730 | ||
731 | /** | |
732 | * The prototype of a read handler. | |
733 | * | |
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. | |
737 | * | |
6eb1ded4 | 738 | * @param[in] data A pointer to an application data specified by |
95b98ba9 KS |
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. | |
a51447c9 KS |
743 | * |
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. | |
747 | */ | |
6eb1ded4 KS |
748 | |
749 | typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size, | |
95b98ba9 | 750 | size_t *size_read); |
a51447c9 | 751 | |
6eb1ded4 KS |
752 | /** |
753 | * This structure holds a string input specified by | |
754 | * @c yaml_parser_set_input_string. | |
755 | */ | |
756 | ||
757 | typedef struct { | |
f642fd11 | 758 | /** The string start pointer. */ |
6eb1ded4 | 759 | unsigned char *start; |
f642fd11 KS |
760 | |
761 | /** The string end pointer. */ | |
6eb1ded4 | 762 | unsigned char *end; |
f642fd11 KS |
763 | |
764 | /** The string current position. */ | |
6eb1ded4 KS |
765 | unsigned char *current; |
766 | } yaml_string_input_t; | |
767 | ||
03be97ab KS |
768 | /** |
769 | * This structure holds information about a potential simple key. | |
770 | */ | |
771 | ||
772 | typedef struct { | |
03be97ab KS |
773 | /** Is a simple key required? */ |
774 | int required; | |
775 | ||
776 | /** The number of the token. */ | |
777 | size_t token_number; | |
778 | ||
779 | /** The position index. */ | |
780 | size_t index; | |
781 | ||
782 | /** The position line. */ | |
783 | size_t line; | |
784 | ||
785 | /** The position column. */ | |
786 | size_t column; | |
787 | ||
788 | /** The position mark. */ | |
789 | yaml_mark_t mark; | |
790 | } yaml_simple_key_t; | |
791 | ||
a51447c9 KS |
792 | /** |
793 | * The parser structure. | |
794 | * | |
795 | * All members are internal. Manage the structure using the @c yaml_parser_ | |
796 | * family of functions. | |
797 | */ | |
798 | ||
9e05b78c | 799 | typedef struct { |
a51447c9 | 800 | |
95b98ba9 KS |
801 | /** |
802 | * @name Error handling | |
803 | * @{ | |
804 | */ | |
805 | ||
3d790dfd | 806 | /** Error type. */ |
6eb1ded4 | 807 | yaml_error_type_t error; |
95b98ba9 | 808 | |
3d790dfd KS |
809 | /** Error description. */ |
810 | const char *problem; | |
811 | ||
812 | /** The byte about which the problem occured. */ | |
813 | size_t problem_offset; | |
814 | ||
2fa16060 KS |
815 | /** The problematic value (@c -1 is none). */ |
816 | int problem_value; | |
817 | ||
f2b59d4d KS |
818 | /** The problem position. */ |
819 | yaml_mark_t problem_mark; | |
820 | ||
821 | /** The error context. */ | |
822 | const char *context; | |
823 | ||
824 | /** The context position. */ | |
825 | yaml_mark_t context_mark; | |
826 | ||
95b98ba9 KS |
827 | /** |
828 | * @} | |
829 | */ | |
830 | ||
a51447c9 KS |
831 | /** |
832 | * @name Reader stuff | |
833 | * @{ | |
834 | */ | |
835 | ||
3d790dfd | 836 | /** Read handler. */ |
95b98ba9 | 837 | yaml_read_handler_t *read_handler; |
a51447c9 KS |
838 | |
839 | /** A pointer for passing to the read handler. */ | |
95b98ba9 | 840 | void *read_handler_data; |
a51447c9 KS |
841 | |
842 | /** EOF flag */ | |
843 | int eof; | |
844 | ||
845 | /** The pointer to the beginning of the working buffer. */ | |
846 | yaml_char_t *buffer; | |
847 | ||
6eb1ded4 KS |
848 | /** The pointer to the end of the working buffer. */ |
849 | yaml_char_t *buffer_end; | |
95b98ba9 | 850 | |
a51447c9 | 851 | /** The pointer to the current character in the working buffer. */ |
6eb1ded4 | 852 | yaml_char_t *pointer; |
95b98ba9 | 853 | |
6eb1ded4 KS |
854 | /** The number of unread characters in the working buffer. */ |
855 | size_t unread; | |
a51447c9 | 856 | |
6eb1ded4 | 857 | /** The pointer to the beginning of the raw buffer. */ |
a51447c9 KS |
858 | unsigned char *raw_buffer; |
859 | ||
6eb1ded4 KS |
860 | /** The pointer to the current character in the raw buffer. */ |
861 | unsigned char *raw_pointer; | |
a51447c9 | 862 | |
6eb1ded4 KS |
863 | /** The number of unread bytes in the raw buffer. */ |
864 | size_t raw_unread; | |
95b98ba9 | 865 | |
a51447c9 KS |
866 | /** The input encoding. */ |
867 | yaml_encoding_t encoding; | |
868 | ||
95b98ba9 KS |
869 | /** The offset of the current position (in bytes). */ |
870 | size_t offset; | |
871 | ||
872 | /** The index of the current position (in characters). */ | |
873 | size_t index; | |
874 | ||
875 | /** The line of the current position (starting from @c 0). */ | |
876 | size_t line; | |
877 | ||
878 | /** The column of the current position (starting from @c 0). */ | |
879 | size_t column; | |
880 | ||
6eb1ded4 KS |
881 | /* String input structure. */ |
882 | yaml_string_input_t string_input; | |
883 | ||
a51447c9 KS |
884 | /** |
885 | * @} | |
886 | */ | |
887 | ||
03be97ab KS |
888 | /** |
889 | * @name Scanner stuff | |
890 | * @{ | |
891 | */ | |
892 | ||
893 | /** Have we started to scan the input stream? */ | |
894 | int stream_start_produced; | |
895 | ||
896 | /** Have we reached the end of the input stream? */ | |
897 | int stream_end_produced; | |
898 | ||
899 | /** The number of unclosed '[' and '{' indicators. */ | |
900 | int flow_level; | |
901 | ||
902 | /** The tokens queue, which contains the current produced tokens. */ | |
f2b59d4d | 903 | yaml_token_t **tokens; |
03be97ab KS |
904 | |
905 | /** The size of the tokens queue. */ | |
906 | size_t tokens_size; | |
907 | ||
908 | /** The head of the tokens queue. */ | |
909 | size_t tokens_head; | |
910 | ||
911 | /** The tail of the tokens queue. */ | |
912 | size_t tokens_tail; | |
913 | ||
914 | /** The number of tokens fetched from the tokens queue. */ | |
915 | size_t tokens_parsed; | |
916 | ||
917 | /** The stack of indentation levels. */ | |
918 | int *indents; | |
919 | ||
920 | /** The size of the indents stack. */ | |
921 | size_t indents_size; | |
922 | ||
923 | /** The number of items in the indents stack. */ | |
924 | size_t indents_length; | |
925 | ||
926 | /** The current indentation level. */ | |
927 | int indent; | |
928 | ||
929 | /** May a simple key occur at the current position? */ | |
930 | int simple_key_allowed; | |
931 | ||
932 | /** The stack of potential simple keys. */ | |
f2b59d4d | 933 | yaml_simple_key_t **simple_keys; |
03be97ab KS |
934 | |
935 | /** The size of the simple keys stack. */ | |
936 | size_t simple_keys_size; | |
937 | ||
938 | /** | |
939 | * @} | |
940 | */ | |
941 | ||
9e05b78c KS |
942 | } yaml_parser_t; |
943 | ||
a51447c9 KS |
944 | /** |
945 | * Create a new parser. | |
946 | * | |
947 | * This function creates a new parser object. An application is responsible | |
948 | * for destroying the object using the @c yaml_parser_delete function. | |
949 | * | |
950 | * @returns A new parser object; @c NULL on error. | |
951 | */ | |
952 | ||
f642fd11 | 953 | YAML_DECLARE(yaml_parser_t *) |
a51447c9 KS |
954 | yaml_parser_new(void); |
955 | ||
956 | /** | |
957 | * Destroy a parser. | |
958 | * | |
959 | * @param[in] parser A parser object. | |
960 | */ | |
961 | ||
f642fd11 | 962 | YAML_DECLARE(void) |
a51447c9 KS |
963 | yaml_parser_delete(yaml_parser_t *parser); |
964 | ||
95b98ba9 KS |
965 | /** |
966 | * Set a string input. | |
967 | * | |
968 | * Note that the @a input pointer must be valid while the @a parser object | |
969 | * exists. The application is responsible for destroing @a input after | |
970 | * destroying the @a parser. | |
971 | * | |
972 | * @param[in] parser A parser object. | |
973 | * @param[in] input A source data. | |
f642fd11 | 974 | * @param[in] size The length of the source data in bytes. |
95b98ba9 KS |
975 | */ |
976 | ||
f642fd11 | 977 | YAML_DECLARE(void) |
95b98ba9 KS |
978 | yaml_parser_set_input_string(yaml_parser_t *parser, |
979 | unsigned char *input, size_t size); | |
980 | ||
981 | ||
982 | /** | |
983 | * Set a file input. | |
984 | * | |
985 | * @a file should be a file object open for reading. The application is | |
986 | * responsible for closing the @a file. | |
987 | * | |
988 | * @param[in] parser A parser object. | |
989 | * @param[in] file An open file. | |
990 | */ | |
991 | ||
f642fd11 | 992 | YAML_DECLARE(void) |
95b98ba9 KS |
993 | yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file); |
994 | ||
995 | /** | |
996 | * Set a generic input handler. | |
997 | * | |
998 | * @param[in] parser A parser object. | |
999 | * @param[in] handler A read handler. | |
1000 | * @param[in] data Any application data for passing to the read handler. | |
1001 | */ | |
1002 | ||
f642fd11 | 1003 | YAML_DECLARE(void) |
95b98ba9 KS |
1004 | yaml_parser_set_input(yaml_parser_t *parser, |
1005 | yaml_read_handler_t *handler, void *data); | |
1006 | ||
1007 | /** | |
1008 | * Set the source encoding. | |
1009 | * | |
f642fd11 | 1010 | * @param[in] parser A parser object. |
95b98ba9 KS |
1011 | * @param[in] encoding The source encoding. |
1012 | */ | |
1013 | ||
f642fd11 | 1014 | YAML_DECLARE(void) |
95b98ba9 KS |
1015 | yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding); |
1016 | ||
03be97ab KS |
1017 | /** |
1018 | * Get the next token. | |
1019 | * | |
1020 | * The token is removed from the internal token queue and the application is | |
1021 | * responsible for destroing the token object. | |
1022 | * | |
1023 | * @param[in] parser A parser object. | |
1024 | * | |
1025 | * @returns A token object, or @c NULL on error. | |
1026 | */ | |
1027 | ||
1028 | YAML_DECLARE(yaml_token_t *) | |
1029 | yaml_parser_get_token(yaml_parser_t *parser); | |
1030 | ||
1031 | /** | |
1032 | * Peek the next token. | |
1033 | * | |
1034 | * The token is not removed from the internal token queue and will be returned | |
1035 | * again on a subsequent call of @c yaml_parser_get_token or | |
1036 | * @c yaml_parser_peek_token. The application should not destroy the token | |
1037 | * object. | |
1038 | * | |
1039 | * @param[in] parser A parser object. | |
1040 | * | |
1041 | * @returns A token object, or @c NULL on error. | |
1042 | */ | |
1043 | ||
1044 | YAML_DECLARE(yaml_token_t *) | |
1045 | yaml_parser_peek_token(yaml_parser_t *parser); | |
1046 | ||
a51447c9 KS |
1047 | /** @} */ |
1048 | ||
1049 | /* | |
9e05b78c KS |
1050 | typedef struct { |
1051 | } yaml_emitter_t; | |
cec6fc98 | 1052 | */ |
9e05b78c | 1053 | |
95b98ba9 KS |
1054 | /** |
1055 | * @defgroup internal Internal Definitions | |
1056 | * @{ | |
1057 | */ | |
1058 | ||
1059 | /** | |
1060 | * Allocate a dynamic memory block. | |
1061 | * | |
1062 | * @param[in] size Size of a memory block, \c 0 is valid. | |
1063 | * | |
1064 | * @returns @c yaml_malloc returns a pointer to a newly allocated memory block, | |
1065 | * or @c NULL if it failed. | |
1066 | */ | |
1067 | ||
f642fd11 | 1068 | YAML_DECLARE(void *) |
95b98ba9 KS |
1069 | yaml_malloc(size_t size); |
1070 | ||
1071 | /** | |
1072 | * Reallocate a dynamic memory block. | |
1073 | * | |
1074 | * @param[in] ptr A pointer to an existing memory block, \c NULL is | |
1075 | * valid. | |
1076 | * @param[in] size A size of a new block, \c 0 is valid. | |
1077 | * | |
1078 | * @returns @c yaml_realloc returns a pointer to a reallocated memory block, | |
1079 | * or @c NULL if it failed. | |
1080 | */ | |
1081 | ||
f642fd11 | 1082 | YAML_DECLARE(void *) |
95b98ba9 KS |
1083 | yaml_realloc(void *ptr, size_t size); |
1084 | ||
1085 | /** | |
1086 | * Free a dynamic memory block. | |
1087 | * | |
1088 | * @param[in] ptr A pointer to an existing memory block, \c NULL is | |
1089 | * valid. | |
1090 | */ | |
1091 | ||
f642fd11 | 1092 | YAML_DECLARE(void) |
95b98ba9 KS |
1093 | yaml_free(void *ptr); |
1094 | ||
f2b59d4d KS |
1095 | /** The initial size for various buffers. */ |
1096 | ||
1097 | #define YAML_DEFAULT_SIZE 16 | |
1098 | ||
6eb1ded4 KS |
1099 | /** The size of the raw buffer. */ |
1100 | ||
1101 | #define YAML_RAW_BUFFER_SIZE 16384 | |
1102 | ||
1103 | /** | |
1104 | * The size of the buffer. | |
1105 | * | |
1106 | * We allocate enough space for decoding the whole raw buffer. | |
1107 | */ | |
1108 | ||
1109 | #define YAML_BUFFER_SIZE (YAML_RAW_BUFFER_SIZE*3) | |
1110 | ||
3d790dfd KS |
1111 | /** |
1112 | * Ensure that the buffer contains at least @a length characters. | |
1113 | * | |
1114 | * @param[in] parser A parser object. | |
1115 | * @param[in] length The number of characters in the buffer. | |
1116 | * | |
1117 | * @returns @c 1 on success, @c 0 on error. | |
1118 | */ | |
1119 | ||
f642fd11 | 1120 | YAML_DECLARE(int) |
3d790dfd KS |
1121 | yaml_parser_update_buffer(yaml_parser_t *parser, size_t length); |
1122 | ||
95b98ba9 KS |
1123 | /** @} */ |
1124 | ||
1125 | ||
9e05b78c KS |
1126 | #ifdef __cplusplus |
1127 | } | |
1128 | #endif | |
1129 | ||
cec6fc98 | 1130 | #endif /* #ifndef YAML_H */ |
9e05b78c | 1131 |