1 /** 2 * @file yaml.h 3 * @brief Public interface for libyaml. 4 * 5 * Include the header file with the code: 6 * @code 7 * #include <yaml.h> 8 * @endcode 9 */ 10 11 #ifndef YAML_H 12 #define YAML_H 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 #include <stdlib.h> 19 #include <stdio.h> 20 #include <string.h> 21 22 /** 23 * @defgroup export Export Definitions 24 * @{ 25 */ 26 27 /** The public API declaration. */ 28 29 #if defined(__MINGW32__) 30 # define YAML_DECLARE(type) type 31 #elif defined(WIN32) 32 # if defined(YAML_DECLARE_STATIC) 33 # define YAML_DECLARE(type) type 34 # elif defined(YAML_DECLARE_EXPORT) 35 # define YAML_DECLARE(type) __declspec(dllexport) type 36 # else 37 # define YAML_DECLARE(type) __declspec(dllimport) type 38 # endif 39 #else 40 # define YAML_DECLARE(type) type 41 #endif 42 43 /** @} */ 44 45 /** 46 * @defgroup version Version Information 47 * @{ 48 */ 49 50 /** 51 * Get the library version as a string. 52 * 53 * @returns The function returns the pointer to a static string of the form 54 * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version 55 * number, and @c Z is the patch version number. 56 */ 57 58 YAML_DECLARE(const char *) 59 yaml_get_version_string(void); 60 61 /** 62 * Get the library version numbers. 63 * 64 * @param[out] major Major version number. 65 * @param[out] minor Minor version number. 66 * @param[out] patch Patch version number. 67 */ 68 69 YAML_DECLARE(void) 70 yaml_get_version(int *major, int *minor, int *patch); 71 72 /** @} */ 73 74 /** 75 * @defgroup basic Basic Types 76 * @{ 77 */ 78 79 /** The character type (UTF-8 octet). */ 80 typedef unsigned char yaml_char_t; 81 82 /** The version directive data. */ 83 typedef struct yaml_version_directive_s { 84 /** The major version number. */ 85 int major; 86 /** The minor version number. */ 87 int minor; 88 } yaml_version_directive_t; 89 90 /** The tag directive data. */ 91 typedef struct yaml_tag_directive_s { 92 /** The tag handle. */ 93 yaml_char_t *handle; 94 /** The tag prefix. */ 95 yaml_char_t *prefix; 96 } yaml_tag_directive_t; 97 98 /** The stream encoding. */ 99 typedef enum yaml_encoding_e { 100 /** Let the parser choose the encoding. */ 101 YAML_ANY_ENCODING, 102 /** The default UTF-8 encoding. */ 103 YAML_UTF8_ENCODING, 104 /** The UTF-16-LE encoding with BOM. */ 105 YAML_UTF16LE_ENCODING, 106 /** The UTF-16-BE encoding with BOM. */ 107 YAML_UTF16BE_ENCODING 108 } yaml_encoding_t; 109 110 /** Line break types. */ 111 112 typedef enum yaml_break_e { 113 /** Let the parser choose the break type. */ 114 YAML_ANY_BREAK, 115 /** Use CR for line breaks (Mac style). */ 116 YAML_CR_BREAK, 117 /** Use LN for line breaks (Unix style). */ 118 YAML_LN_BREAK, 119 /** Use CR LN for line breaks (DOS style). */ 120 YAML_CRLN_BREAK 121 } yaml_break_t; 122 123 /** Many bad things could happen with the parser and emitter. */ 124 typedef enum yaml_error_type_e { 125 /** No error is produced. */ 126 YAML_NO_ERROR, 127 128 /** Cannot allocate or reallocate a block of memory. */ 129 YAML_MEMORY_ERROR, 130 131 /** Cannot read or decode the input stream. */ 132 YAML_READER_ERROR, 133 /** Cannot scan the input stream. */ 134 YAML_SCANNER_ERROR, 135 /** Cannot parse the input stream. */ 136 YAML_PARSER_ERROR, 137 /** Cannot compose a YAML document. */ 138 YAML_COMPOSER_ERROR, 139 140 /** Cannot write to the output stream. */ 141 YAML_WRITER_ERROR, 142 /** Cannot emit a YAML stream. */ 143 YAML_EMITTER_ERROR 144 } yaml_error_type_t; 145 146 /** The pointer position. */ 147 typedef struct yaml_mark_s { 148 /** The position index. */ 149 size_t index; 150 151 /** The position line. */ 152 size_t line; 153 154 /** The position column. */ 155 size_t column; 156 } yaml_mark_t; 157 158 /** @} */ 159 160 /** 161 * @defgroup styles Node Styles 162 * @{ 163 */ 164 165 /** Scalar styles. */ 166 typedef enum yaml_scalar_style_e { 167 /** Let the emitter choose the style. */ 168 YAML_ANY_SCALAR_STYLE, 169 170 /** The plain scalar style. */ 171 YAML_PLAIN_SCALAR_STYLE, 172 173 /** The single-quoted scalar style. */ 174 YAML_SINGLE_QUOTED_SCALAR_STYLE, 175 /** The double-quoted scalar style. */ 176 YAML_DOUBLE_QUOTED_SCALAR_STYLE, 177 178 /** The literal scalar style. */ 179 YAML_LITERAL_SCALAR_STYLE, 180 /** The folded scalar style. */ 181 YAML_FOLDED_SCALAR_STYLE 182 } yaml_scalar_style_t; 183 184 /** Sequence styles. */ 185 typedef enum yaml_sequence_style_e { 186 /** Let the emitter choose the style. */ 187 YAML_ANY_SEQUENCE_STYLE, 188 189 /** The block sequence style. */ 190 YAML_BLOCK_SEQUENCE_STYLE, 191 /** The flow sequence style. */ 192 YAML_FLOW_SEQUENCE_STYLE 193 } yaml_sequence_style_t; 194 195 /** Mapping styles. */ 196 typedef enum yaml_mapping_style_e { 197 /** Let the emitter choose the style. */ 198 YAML_ANY_MAPPING_STYLE, 199 200 /** The block mapping style. */ 201 YAML_BLOCK_MAPPING_STYLE, 202 /** The flow mapping style. */ 203 YAML_FLOW_MAPPING_STYLE 204 /* YAML_FLOW_SET_MAPPING_STYLE */ 205 } yaml_mapping_style_t; 206 207 /** @} */ 208 209 /** 210 * @defgroup tokens Tokens 211 * @{ 212 */ 213 214 /** Token types. */ 215 typedef enum yaml_token_type_e { 216 /** An empty token. */ 217 YAML_NO_TOKEN, 218 219 /** A STREAM-START token. */ 220 YAML_STREAM_START_TOKEN, 221 /** A STREAM-END token. */ 222 YAML_STREAM_END_TOKEN, 223 224 /** A VERSION-DIRECTIVE token. */ 225 YAML_VERSION_DIRECTIVE_TOKEN, 226 /** A TAG-DIRECTIVE token. */ 227 YAML_TAG_DIRECTIVE_TOKEN, 228 /** A DOCUMENT-START token. */ 229 YAML_DOCUMENT_START_TOKEN, 230 /** A DOCUMENT-END token. */ 231 YAML_DOCUMENT_END_TOKEN, 232 233 /** A BLOCK-SEQUENCE-START token. */ 234 YAML_BLOCK_SEQUENCE_START_TOKEN, 235 /** A BLOCK-SEQUENCE-END token. */ 236 YAML_BLOCK_MAPPING_START_TOKEN, 237 /** A BLOCK-END token. */ 238 YAML_BLOCK_END_TOKEN, 239 240 /** A FLOW-SEQUENCE-START token. */ 241 YAML_FLOW_SEQUENCE_START_TOKEN, 242 /** A FLOW-SEQUENCE-END token. */ 243 YAML_FLOW_SEQUENCE_END_TOKEN, 244 /** A FLOW-MAPPING-START token. */ 245 YAML_FLOW_MAPPING_START_TOKEN, 246 /** A FLOW-MAPPING-END token. */ 247 YAML_FLOW_MAPPING_END_TOKEN, 248 249 /** A BLOCK-ENTRY token. */ 250 YAML_BLOCK_ENTRY_TOKEN, 251 /** A FLOW-ENTRY token. */ 252 YAML_FLOW_ENTRY_TOKEN, 253 /** A KEY token. */ 254 YAML_KEY_TOKEN, 255 /** A VALUE token. */ 256 YAML_VALUE_TOKEN, 257 258 /** An ALIAS token. */ 259 YAML_ALIAS_TOKEN, 260 /** An ANCHOR token. */ 261 YAML_ANCHOR_TOKEN, 262 /** A TAG token. */ 263 YAML_TAG_TOKEN, 264 /** A SCALAR token. */ 265 YAML_SCALAR_TOKEN 266 } yaml_token_type_t; 267 268 /** The token structure. */ 269 typedef struct yaml_token_s { 270 271 /** The token type. */ 272 yaml_token_type_t type; 273 274 /** The token data. */ 275 union { 276 277 /** The stream start (for @c YAML_STREAM_START_TOKEN). */ 278 struct { 279 /** The stream encoding. */ 280 yaml_encoding_t encoding; 281 } stream_start; 282 283 /** The alias (for @c YAML_ALIAS_TOKEN). */ 284 struct { 285 /** The alias value. */ 286 yaml_char_t *value; 287 } alias; 288 289 /** The anchor (for @c YAML_ANCHOR_TOKEN). */ 290 struct { 291 /** The anchor value. */ 292 yaml_char_t *value; 293 } anchor; 294 295 /** The tag (for @c YAML_TAG_TOKEN). */ 296 struct { 297 /** The tag handle. */ 298 yaml_char_t *handle; 299 /** The tag suffix. */ 300 yaml_char_t *suffix; 301 } tag; 302 303 /** The scalar value (for @c YAML_SCALAR_TOKEN). */ 304 struct { 305 /** The scalar value. */ 306 yaml_char_t *value; 307 /** The length of the scalar value. */ 308 size_t length; 309 /** The scalar style. */ 310 yaml_scalar_style_t style; 311 } scalar; 312 313 /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */ 314 struct { 315 /** The major version number. */ 316 int major; 317 /** The minor version number. */ 318 int minor; 319 } version_directive; 320 321 /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */ 322 struct { 323 /** The tag handle. */ 324 yaml_char_t *handle; 325 /** The tag prefix. */ 326 yaml_char_t *prefix; 327 } tag_directive; 328 329 } data; 330 331 /** The beginning of the token. */ 332 yaml_mark_t start_mark; 333 /** The end of the token. */ 334 yaml_mark_t end_mark; 335 336 } yaml_token_t; 337 338 /** 339 * Free any memory allocated for a token object. 340 * 341 * @param[in,out] token A token object. 342 */ 343 344 YAML_DECLARE(void) 345 yaml_token_delete(yaml_token_t *token); 346 347 /** @} */ 348 349 /** 350 * @defgroup events Events 351 * @{ 352 */ 353 354 /** Event types. */ 355 typedef enum yaml_event_type_e { 356 /** An empty event. */ 357 YAML_NO_EVENT, 358 359 /** A STREAM-START event. */ 360 YAML_STREAM_START_EVENT, 361 /** A STREAM-END event. */ 362 YAML_STREAM_END_EVENT, 363 364 /** A DOCUMENT-START event. */ 365 YAML_DOCUMENT_START_EVENT, 366 /** A DOCUMENT-END event. */ 367 YAML_DOCUMENT_END_EVENT, 368 369 /** An ALIAS event. */ 370 YAML_ALIAS_EVENT, 371 /** A SCALAR event. */ 372 YAML_SCALAR_EVENT, 373 374 /** A SEQUENCE-START event. */ 375 YAML_SEQUENCE_START_EVENT, 376 /** A SEQUENCE-END event. */ 377 YAML_SEQUENCE_END_EVENT, 378 379 /** A MAPPING-START event. */ 380 YAML_MAPPING_START_EVENT, 381 /** A MAPPING-END event. */ 382 YAML_MAPPING_END_EVENT 383 } yaml_event_type_t; 384 385 /** The event structure. */ 386 typedef struct yaml_event_s { 387 388 /** The event type. */ 389 yaml_event_type_t type; 390 391 /** The event data. */ 392 union { 393 394 /** The stream parameters (for @c YAML_STREAM_START_EVENT). */ 395 struct { 396 /** The document encoding. */ 397 yaml_encoding_t encoding; 398 } stream_start; 399 400 /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */ 401 struct { 402 /** The version directive. */ 403 yaml_version_directive_t *version_directive; 404 405 /** The list of tag directives. */ 406 struct { 407 /** The beginning of the tag directives list. */ 408 yaml_tag_directive_t *start; 409 /** The end of the tag directives list. */ 410 yaml_tag_directive_t *end; 411 } tag_directives; 412 413 /** Is the document indicator implicit? */ 414 int implicit; 415 } document_start; 416 417 /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */ 418 struct { 419 /** Is the document end indicator implicit? */ 420 int implicit; 421 } document_end; 422 423 /** The alias parameters (for @c YAML_ALIAS_EVENT). */ 424 struct { 425 /** The anchor. */ 426 yaml_char_t *anchor; 427 } alias; 428 429 /** The scalar parameters (for @c YAML_SCALAR_EVENT). */ 430 struct { 431 /** The anchor. */ 432 yaml_char_t *anchor; 433 /** The tag. */ 434 yaml_char_t *tag; 435 /** The scalar value. */ 436 yaml_char_t *value; 437 /** The length of the scalar value. */ 438 size_t length; 439 /** Is the tag optional for the plain style? */ 440 int plain_implicit; 441 /** Is the tag optional for any non-plain style? */ 442 int quoted_implicit; 443 /** The scalar style. */ 444 yaml_scalar_style_t style; 445 } scalar; 446 447 /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */ 448 struct { 449 /** The anchor. */ 450 yaml_char_t *anchor; 451 /** The tag. */ 452 yaml_char_t *tag; 453 /** Is the tag optional? */ 454 int implicit; 455 /** The sequence style. */ 456 yaml_sequence_style_t style; 457 } sequence_start; 458 459 /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */ 460 struct { 461 /** The anchor. */ 462 yaml_char_t *anchor; 463 /** The tag. */ 464 yaml_char_t *tag; 465 /** Is the tag optional? */ 466 int implicit; 467 /** The mapping style. */ 468 yaml_mapping_style_t style; 469 } mapping_start; 470 471 } data; 472 473 /** The beginning of the event. */ 474 yaml_mark_t start_mark; 475 /** The end of the event. */ 476 yaml_mark_t end_mark; 477 478 } yaml_event_t; 479 480 /** 481 * Create the STREAM-START event. 482 * 483 * @param[out] event An empty event object. 484 * @param[in] encoding The stream encoding. 485 * 486 * @returns @c 1 if the function succeeded, @c 0 on error. 487 */ 488 489 YAML_DECLARE(int) 490 yaml_stream_start_event_initialize(yaml_event_t *event, 491 yaml_encoding_t encoding); 492 493 /** 494 * Create the STREAM-END event. 495 * 496 * @param[out] event An empty event object. 497 * 498 * @returns @c 1 if the function succeeded, @c 0 on error. 499 */ 500 501 YAML_DECLARE(int) 502 yaml_stream_end_event_initialize(yaml_event_t *event); 503 504 /** 505 * Create the DOCUMENT-START event. 506 * 507 * The @a implicit argument is considered as a stylistic parameter and may be 508 * ignored by the emitter. 509 * 510 * @param[out] event An empty event object. 511 * @param[in] version_directive The %YAML directive value or 512 * @c NULL. 513 * @param[in] tag_directives_start The beginning of the %TAG 514 * directives list. 515 * @param[in] tag_directives_end The end of the %TAG directives 516 * list. 517 * @param[in] implicit If the document start indicator is 518 * implicit. 519 * 520 * @returns @c 1 if the function succeeded, @c 0 on error. 521 */ 522 523 YAML_DECLARE(int) 524 yaml_document_start_event_initialize(yaml_event_t *event, 525 yaml_version_directive_t *version_directive, 526 yaml_tag_directive_t *tag_directives_start, 527 yaml_tag_directive_t *tag_directives_end, 528 int implicit); 529 530 /** 531 * Create the DOCUMENT-END event. 532 * 533 * The @a implicit argument is considered as a stylistic parameter and may be 534 * ignored by the emitter. 535 * 536 * @param[out] event An empty event object. 537 * @param[in] implicit If the document end indicator is implicit. 538 * 539 * @returns @c 1 if the function succeeded, @c 0 on error. 540 */ 541 542 YAML_DECLARE(int) 543 yaml_document_end_event_initialize(yaml_event_t *event, int implicit); 544 545 /** 546 * Create an ALIAS event. 547 * 548 * @param[out] event An empty event object. 549 * @param[in] anchor The anchor value. 550 * 551 * @returns @c 1 if the function succeeded, @c 0 on error. 552 */ 553 554 YAML_DECLARE(int) 555 yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor); 556 557 /** 558 * Create a SCALAR event. 559 * 560 * The @a style argument may be ignored by the emitter. 561 * 562 * Either the @a tag attribute or one of the @a plain_implicit and 563 * @a quoted_implicit flags must be set. 564 * 565 * @param[out] event An empty event object. 566 * @param[in] anchor The scalar anchor or @c NULL. 567 * @param[in] tag The scalar tag or @c NULL. 568 * @param[in] value The scalar value. 569 * @param[in] length The length of the scalar value. 570 * @param[in] plain_implicit If the tag may be omitted for the plain 571 * style. 572 * @param[in] quoted_implicit If the tag may be omitted for any 573 * non-plain style. 574 * @param[in] style The scalar style. 575 * 576 * @returns @c 1 if the function succeeded, @c 0 on error. 577 */ 578 579 YAML_DECLARE(int) 580 yaml_scalar_event_initialize(yaml_event_t *event, 581 yaml_char_t *anchor, yaml_char_t *tag, 582 yaml_char_t *value, int length, 583 int plain_implicit, int quoted_implicit, 584 yaml_scalar_style_t style); 585 586 /** 587 * Create a SEQUENCE-START event. 588 * 589 * The @a style argument may be ignored by the emitter. 590 * 591 * Either the @a tag attribute or the @a implicit flag must be set. 592 * 593 * @param[out] event An empty event object. 594 * @param[in] anchor The sequence anchor or @c NULL. 595 * @param[in] tag The sequence tag or @c NULL. 596 * @param[in] implicit If the tag may be omitted. 597 * @param[in] style The sequence style. 598 * 599 * @returns @c 1 if the function succeeded, @c 0 on error. 600 */ 601 602 YAML_DECLARE(int) 603 yaml_sequence_start_event_initialize(yaml_event_t *event, 604 yaml_char_t *anchor, yaml_char_t *tag, int implicit, 605 yaml_sequence_style_t style); 606 607 /** 608 * Create a SEQUENCE-END event. 609 * 610 * @param[out] event An empty event object. 611 * 612 * @returns @c 1 if the function succeeded, @c 0 on error. 613 */ 614 615 YAML_DECLARE(int) 616 yaml_sequence_end_event_initialize(yaml_event_t *event); 617 618 /** 619 * Create a MAPPING-START event. 620 * 621 * The @a style argument may be ignored by the emitter. 622 * 623 * Either the @a tag attribute or the @a implicit flag must be set. 624 * 625 * @param[out] event An empty event object. 626 * @param[in] anchor The mapping anchor or @c NULL. 627 * @param[in] tag The mapping tag or @c NULL. 628 * @param[in] implicit If the tag may be omitted. 629 * @param[in] style The mapping style. 630 * 631 * @returns @c 1 if the function succeeded, @c 0 on error. 632 */ 633 634 YAML_DECLARE(int) 635 yaml_mapping_start_event_initialize(yaml_event_t *event, 636 yaml_char_t *anchor, yaml_char_t *tag, int implicit, 637 yaml_mapping_style_t style); 638 639 /** 640 * Create a MAPPING-END event. 641 * 642 * @param[out] event An empty event object. 643 * 644 * @returns @c 1 if the function succeeded, @c 0 on error. 645 */ 646 647 YAML_DECLARE(int) 648 yaml_mapping_end_event_initialize(yaml_event_t *event); 649 650 /** 651 * Free any memory allocated for an event object. 652 * 653 * @param[in,out] event An event object. 654 */ 655 656 YAML_DECLARE(void) 657 yaml_event_delete(yaml_event_t *event); 658 659 /** @} */ 660 661 /** 662 * @defgroup nodes Nodes 663 * @{ 664 */ 665 666 /** The tag @c !!null with the only possible value: @c null. */ 667 #define YAML_NULL_TAG "tag:yaml.org,2002:null" 668 /** The tag @c !!bool with the values: @c true and @c false. */ 669 #define YAML_BOOL_TAG "tag:yaml.org,2002:bool" 670 /** The tag @c !!str for string values. */ 671 #define YAML_STR_TAG "tag:yaml.org,2002:str" 672 /** The tag @c !!int for integer values. */ 673 #define YAML_INT_TAG "tag:yaml.org,2002:int" 674 /** The tag @c !!float for float values. */ 675 #define YAML_FLOAT_TAG "tag:yaml.org,2002:float" 676 /** The tag @c !!timestamp for date and time values. */ 677 #define YAML_TIMESTAMP_TAG "tag:yaml.org,2002:timestamp" 678 679 /** The tag @c !!seq is used to denote sequences. */ 680 #define YAML_SEQ_TAG "tag:yaml.org,2002:seq" 681 /** The tag @c !!map is used to denote mapping. */ 682 #define YAML_MAP_TAG "tag:yaml.org,2002:map" 683 684 /** The default scalar tag is @c !!str. */ 685 #define YAML_DEFAULT_SCALAR_TAG YAML_STR_TAG 686 /** The default sequence tag is @c !!seq. */ 687 #define YAML_DEFAULT_SEQUENCE_TAG YAML_SEQ_TAG 688 /** The default mapping tag is @c !!map. */ 689 #define YAML_DEFAULT_MAPPING_TAG YAML_MAP_TAG 690 691 /** Node types. */ 692 typedef enum yaml_node_type_e { 693 /** An empty node. */ 694 YAML_NO_NODE, 695 696 /** A scalar node. */ 697 YAML_SCALAR_NODE, 698 /** A sequence node. */ 699 YAML_SEQUENCE_NODE, 700 /** A mapping node. */ 701 YAML_MAPPING_NODE 702 } yaml_node_type_t; 703 704 /** The forward definition of a document node structure. */ 705 typedef struct yaml_node_s yaml_node_t; 706 707 /** An element of a sequence node. */ 708 typedef int yaml_node_item_t; 709 710 /** An element of a mapping node. */ 711 typedef struct yaml_node_pair_s { 712 /** The key of the element. */ 713 int key; 714 /** The value of the element. */ 715 int value; 716 } yaml_node_pair_t; 717 718 /** The node structure. */ 719 struct yaml_node_s { 720 721 /** The node type. */ 722 yaml_node_type_t type; 723 724 /** The node tag. */ 725 yaml_char_t *tag; 726 727 /** The node data. */ 728 union { 729 730 /** The scalar parameters (for @c YAML_SCALAR_NODE). */ 731 struct { 732 /** The scalar value. */ 733 yaml_char_t *value; 734 /** The length of the scalar value. */ 735 size_t length; 736 /** The scalar style. */ 737 yaml_scalar_style_t style; 738 } scalar; 739 740 /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */ 741 struct { 742 /** The stack of sequence items. */ 743 struct { 744 /** The beginning of the stack. */ 745 yaml_node_item_t *start; 746 /** The end of the stack. */ 747 yaml_node_item_t *end; 748 /** The top of the stack. */ 749 yaml_node_item_t *top; 750 } items; 751 /** The sequence style. */ 752 yaml_sequence_style_t style; 753 } sequence; 754 755 /** The mapping parameters (for @c YAML_MAPPING_NODE). */ 756 struct { 757 /** The stack of mapping pairs (key, value). */ 758 struct { 759 /** The beginning of the stack. */ 760 yaml_node_pair_t *start; 761 /** The end of the stack. */ 762 yaml_node_pair_t *end; 763 /** The top of the stack. */ 764 yaml_node_pair_t *top; 765 } pairs; 766 /** The mapping style. */ 767 yaml_mapping_style_t style; 768 } mapping; 769 770 } data; 771 772 /** The beginning of the node. */ 773 yaml_mark_t start_mark; 774 /** The end of the node. */ 775 yaml_mark_t end_mark; 776 777 }; 778 779 /** The document structure. */ 780 typedef struct yaml_document_s { 781 782 /** The document nodes. */ 783 struct { 784 /** The beginning of the stack. */ 785 yaml_node_t *start; 786 /** The end of the stack. */ 787 yaml_node_t *end; 788 /** The top of the stack. */ 789 yaml_node_t *top; 790 } nodes; 791 792 /** The version directive. */ 793 yaml_version_directive_t *version_directive; 794 795 /** The list of tag directives. */ 796 struct { 797 /** The beginning of the tag directives list. */ 798 yaml_tag_directive_t *start; 799 /** The end of the tag directives list. */ 800 yaml_tag_directive_t *end; 801 } tag_directives; 802 803 /** Is the document start indicator implicit? */ 804 int start_implicit; 805 /** Is the document end indicator implicit? */ 806 int end_implicit; 807 808 /** The beginning of the document. */ 809 yaml_mark_t start_mark; 810 /** The end of the document. */ 811 yaml_mark_t end_mark; 812 813 } yaml_document_t; 814 815 /** 816 * Create a YAML document. 817 * 818 * @param[out] document An empty document object. 819 * @param[in] version_directive The %YAML directive value or 820 * @c NULL. 821 * @param[in] tag_directives_start The beginning of the %TAG 822 * directives list. 823 * @param[in] tag_directives_end The end of the %TAG directives 824 * list. 825 * @param[in] start_implicit If the document start indicator is 826 * implicit. 827 * @param[in] end_implicit If the document end indicator is 828 * implicit. 829 * 830 * @returns @c 1 if the function succeeded, @c 0 on error. 831 */ 832 833 YAML_DECLARE(int) 834 yaml_document_initialize(yaml_document_t *document, 835 yaml_version_directive_t *version_directive, 836 yaml_tag_directive_t *tag_directives_start, 837 yaml_tag_directive_t *tag_directives_end, 838 int start_implicit, int end_implicit); 839 840 /** 841 * Delete a YAML document and all its nodes. 842 * 843 * @param[in,out] document A document object. 844 */ 845 846 YAML_DECLARE(void) 847 yaml_document_delete(yaml_document_t *document); 848 849 /** 850 * Get a node of a YAML document. 851 * 852 * The pointer returned by this function is valid until any of the functions 853 * modifying the documents are called. 854 * 855 * @param[in] document A document object. 856 * @param[in] index The node id. 857 * 858 * @returns the node objct or @c NULL if @c node_id is out of range. 859 */ 860 861 YAML_DECLARE(yaml_node_t *) 862 yaml_document_get_node(yaml_document_t *document, int index); 863 864 /** 865 * Get the root of a YAML document node. 866 * 867 * The root object is the first object added to the document. 868 * 869 * The pointer returned by this function is valid until any of the functions 870 * modifying the documents are called. 871 * 872 * An empty document produced by the parser signifies the end of a YAML 873 * stream. 874 * 875 * @param[in] document A document object. 876 * 877 * @returns the node object or @c NULL if the document is empty. 878 */ 879 880 YAML_DECLARE(yaml_node_t *) 881 yaml_document_get_root_node(yaml_document_t *document); 882 883 /** 884 * Create a SCALAR node and attach it to the document. 885 * 886 * The @a style argument may be ignored by the emitter. 887 * 888 * @param[in,out] document A document object. 889 * @param[in] tag The scalar tag. 890 * @param[in] value The scalar value. 891 * @param[in] length The length of the scalar value. 892 * @param[in] style The scalar style. 893 * 894 * @returns the node id or @c 0 on error. 895 */ 896 897 YAML_DECLARE(int) 898 yaml_document_add_scalar(yaml_document_t *document, 899 yaml_char_t *tag, yaml_char_t *value, int length, 900 yaml_scalar_style_t style); 901 902 /** 903 * Create a SEQUENCE node and attach it to the document. 904 * 905 * The @a style argument may be ignored by the emitter. 906 * 907 * @param[in,out] document A document object. 908 * @param[in] tag The sequence tag. 909 * @param[in] style The sequence style. 910 * 911 * @returns the node id or @c 0 on error. 912 */ 913 914 YAML_DECLARE(int) 915 yaml_document_add_sequence(yaml_document_t *document, 916 yaml_char_t *tag, yaml_sequence_style_t style); 917 918 /** 919 * Create a MAPPING node and attach it to the document. 920 * 921 * The @a style argument may be ignored by the emitter. 922 * 923 * @param[in,out] document A document object. 924 * @param[in] tag The sequence tag. 925 * @param[in] style The sequence style. 926 * 927 * @returns the node id or @c 0 on error. 928 */ 929 930 YAML_DECLARE(int) 931 yaml_document_add_mapping(yaml_document_t *document, 932 yaml_char_t *tag, yaml_mapping_style_t style); 933 934 /** 935 * Add an item to a SEQUENCE node. 936 * 937 * @param[in,out] document A document object. 938 * @param[in] sequence The sequence node id. 939 * @param[in] item The item node id. 940 * 941 * @returns @c 1 if the function succeeded, @c 0 on error. 942 */ 943 944 YAML_DECLARE(int) 945 yaml_document_append_sequence_item(yaml_document_t *document, 946 int sequence, int item); 947 948 /** 949 * Add a pair of a key and a value to a MAPPING node. 950 * 951 * @param[in,out] document A document object. 952 * @param[in] mapping The mapping node id. 953 * @param[in] key The key node id. 954 * @param[in] value The value node id. 955 * 956 * @returns @c 1 if the function succeeded, @c 0 on error. 957 */ 958 959 YAML_DECLARE(int) 960 yaml_document_append_mapping_pair(yaml_document_t *document, 961 int mapping, int key, int value); 962 963 /** @} */ 964 965 /** 966 * @defgroup parser Parser Definitions 967 * @{ 968 */ 969 970 /** 971 * The prototype of a read handler. 972 * 973 * The read handler is called when the parser needs to read more bytes from the 974 * source. The handler should write not more than @a size bytes to the @a 975 * buffer. The number of written bytes should be set to the @a length variable. 976 * 977 * @param[in,out] data A pointer to an application data specified by 978 * yaml_parser_set_input(). 979 * @param[out] buffer The buffer to write the data from the source. 980 * @param[in] size The size of the buffer. 981 * @param[out] size_read The actual number of bytes read from the source. 982 * 983 * @returns On success, the handler should return @c 1. If the handler failed, 984 * the returned value should be @c 0. On EOF, the handler should set the 985 * @a size_read to @c 0 and return @c 1. 986 */ 987 988 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size, 989 size_t *size_read); 990 991 /** 992 * This structure holds information about a potential simple key. 993 */ 994 995 typedef struct yaml_simple_key_s { 996 /** Is a simple key possible? */ 997 int possible; 998 999 /** Is a simple key required? */ 1000 int required; 1001 1002 /** The number of the token. */ 1003 size_t token_number; 1004 1005 /** The position mark. */ 1006 yaml_mark_t mark; 1007 } yaml_simple_key_t; 1008 1009 /** 1010 * The states of the parser. 1011 */ 1012 typedef enum yaml_parser_state_e { 1013 /** Expect STREAM-START. */ 1014 YAML_PARSE_STREAM_START_STATE, 1015 /** Expect the beginning of an implicit document. */ 1016 YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE, 1017 /** Expect DOCUMENT-START. */ 1018 YAML_PARSE_DOCUMENT_START_STATE, 1019 /** Expect the content of a document. */ 1020 YAML_PARSE_DOCUMENT_CONTENT_STATE, 1021 /** Expect DOCUMENT-END. */ 1022 YAML_PARSE_DOCUMENT_END_STATE, 1023 /** Expect a block node. */ 1024 YAML_PARSE_BLOCK_NODE_STATE, 1025 /** Expect a block node or indentless sequence. */ 1026 YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE, 1027 /** Expect a flow node. */ 1028 YAML_PARSE_FLOW_NODE_STATE, 1029 /** Expect the first entry of a block sequence. */ 1030 YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE, 1031 /** Expect an entry of a block sequence. */ 1032 YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE, 1033 /** Expect an entry of an indentless sequence. */ 1034 YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE, 1035 /** Expect the first key of a block mapping. */ 1036 YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE, 1037 /** Expect a block mapping key. */ 1038 YAML_PARSE_BLOCK_MAPPING_KEY_STATE, 1039 /** Expect a block mapping value. */ 1040 YAML_PARSE_BLOCK_MAPPING_VALUE_STATE, 1041 /** Expect the first entry of a flow sequence. */ 1042 YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE, 1043 /** Expect an entry of a flow sequence. */ 1044 YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE, 1045 /** Expect a key of an ordered mapping. */ 1046 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE, 1047 /** Expect a value of an ordered mapping. */ 1048 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE, 1049 /** Expect the and of an ordered mapping entry. */ 1050 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE, 1051 /** Expect the first key of a flow mapping. */ 1052 YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE, 1053 /** Expect a key of a flow mapping. */ 1054 YAML_PARSE_FLOW_MAPPING_KEY_STATE, 1055 /** Expect a value of a flow mapping. */ 1056 YAML_PARSE_FLOW_MAPPING_VALUE_STATE, 1057 /** Expect an empty value of a flow mapping. */ 1058 YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE, 1059 /** Expect nothing. */ 1060 YAML_PARSE_END_STATE 1061 } yaml_parser_state_t; 1062 1063 /** 1064 * This structure holds aliases data. 1065 */ 1066 1067 typedef struct yaml_alias_data_s { 1068 /** The anchor. */ 1069 yaml_char_t *anchor; 1070 /** The node id. */ 1071 int index; 1072 /** The anchor mark. */ 1073 yaml_mark_t mark; 1074 } yaml_alias_data_t; 1075 1076 /** 1077 * The parser structure. 1078 * 1079 * All members are internal. Manage the structure using the @c yaml_parser_ 1080 * family of functions. 1081 */ 1082 1083 typedef struct yaml_parser_s { 1084 1085 /** 1086 * @name Error handling 1087 * @{ 1088 */ 1089 1090 /** Error type. */ 1091 yaml_error_type_t error; 1092 /** Error description. */ 1093 const char *problem; 1094 /** The byte about which the problem occured. */ 1095 size_t problem_offset; 1096 /** The problematic value (@c -1 is none). */ 1097 int problem_value; 1098 /** The problem position. */ 1099 yaml_mark_t problem_mark; 1100 /** The error context. */ 1101 const char *context; 1102 /** The context position. */ 1103 yaml_mark_t context_mark; 1104 1105 /** 1106 * @} 1107 */ 1108 1109 /** 1110 * @name Reader stuff 1111 * @{ 1112 */ 1113 1114 /** Read handler. */ 1115 yaml_read_handler_t *read_handler; 1116 1117 /** A pointer for passing to the read handler. */ 1118 void *read_handler_data; 1119 1120 /** Standard (string or file) input data. */ 1121 union { 1122 /** String input data. */ 1123 struct { 1124 /** The string start pointer. */ 1125 const unsigned char *start; 1126 /** The string end pointer. */ 1127 const unsigned char *end; 1128 /** The string current position. */ 1129 const unsigned char *current; 1130 } string; 1131 1132 /** File input data. */ 1133 FILE *file; 1134 } input; 1135 1136 /** EOF flag */ 1137 int eof; 1138 1139 /** The working buffer. */ 1140 struct { 1141 /** The beginning of the buffer. */ 1142 yaml_char_t *start; 1143 /** The end of the buffer. */ 1144 yaml_char_t *end; 1145 /** The current position of the buffer. */ 1146 yaml_char_t *pointer; 1147 /** The last filled position of the buffer. */ 1148 yaml_char_t *last; 1149 } buffer; 1150 1151 /* The number of unread characters in the buffer. */ 1152 size_t unread; 1153 1154 /** The raw buffer. */ 1155 struct { 1156 /** The beginning of the buffer. */ 1157 unsigned char *start; 1158 /** The end of the buffer. */ 1159 unsigned char *end; 1160 /** The current position of the buffer. */ 1161 unsigned char *pointer; 1162 /** The last filled position of the buffer. */ 1163 unsigned char *last; 1164 } raw_buffer; 1165 1166 /** The input encoding. */ 1167 yaml_encoding_t encoding; 1168 1169 /** The offset of the current position (in bytes). */ 1170 size_t offset; 1171 1172 /** The mark of the current position. */ 1173 yaml_mark_t mark; 1174 1175 /** 1176 * @} 1177 */ 1178 1179 /** 1180 * @name Scanner stuff 1181 * @{ 1182 */ 1183 1184 /** Have we started to scan the input stream? */ 1185 int stream_start_produced; 1186 1187 /** Have we reached the end of the input stream? */ 1188 int stream_end_produced; 1189 1190 /** The number of unclosed '[' and '{' indicators. */ 1191 int flow_level; 1192 1193 /** The tokens queue. */ 1194 struct { 1195 /** The beginning of the tokens queue. */ 1196 yaml_token_t *start; 1197 /** The end of the tokens queue. */ 1198 yaml_token_t *end; 1199 /** The head of the tokens queue. */ 1200 yaml_token_t *head; 1201 /** The tail of the tokens queue. */ 1202 yaml_token_t *tail; 1203 } tokens; 1204 1205 /** The number of tokens fetched from the queue. */ 1206 size_t tokens_parsed; 1207 1208 /* Does the tokens queue contain a token ready for dequeueing. */ 1209 int token_available; 1210 1211 /** The indentation levels stack. */ 1212 struct { 1213 /** The beginning of the stack. */ 1214 int *start; 1215 /** The end of the stack. */ 1216 int *end; 1217 /** The top of the stack. */ 1218 int *top; 1219 } indents; 1220 1221 /** The current indentation level. */ 1222 int indent; 1223 1224 /** May a simple key occur at the current position? */ 1225 int simple_key_allowed; 1226 1227 /** The stack of simple keys. */ 1228 struct { 1229 /** The beginning of the stack. */ 1230 yaml_simple_key_t *start; 1231 /** The end of the stack. */ 1232 yaml_simple_key_t *end; 1233 /** The top of the stack. */ 1234 yaml_simple_key_t *top; 1235 } simple_keys; 1236 1237 /** 1238 * @} 1239 */ 1240 1241 /** 1242 * @name Parser stuff 1243 * @{ 1244 */ 1245 1246 /** The parser states stack. */ 1247 struct { 1248 /** The beginning of the stack. */ 1249 yaml_parser_state_t *start; 1250 /** The end of the stack. */ 1251 yaml_parser_state_t *end; 1252 /** The top of the stack. */ 1253 yaml_parser_state_t *top; 1254 } states; 1255 1256 /** The current parser state. */ 1257 yaml_parser_state_t state; 1258 1259 /** The stack of marks. */ 1260 struct { 1261 /** The beginning of the stack. */ 1262 yaml_mark_t *start; 1263 /** The end of the stack. */ 1264 yaml_mark_t *end; 1265 /** The top of the stack. */ 1266 yaml_mark_t *top; 1267 } marks; 1268 1269 /** The list of TAG directives. */ 1270 struct { 1271 /** The beginning of the list. */ 1272 yaml_tag_directive_t *start; 1273 /** The end of the list. */ 1274 yaml_tag_directive_t *end; 1275 /** The top of the list. */ 1276 yaml_tag_directive_t *top; 1277 } tag_directives; 1278 1279 /** 1280 * @} 1281 */ 1282 1283 /** 1284 * @name Dumper stuff 1285 * @{ 1286 */ 1287 1288 /** The alias data. */ 1289 struct { 1290 /** The beginning of the list. */ 1291 yaml_alias_data_t *start; 1292 /** The end of the list. */ 1293 yaml_alias_data_t *end; 1294 /** The top of the list. */ 1295 yaml_alias_data_t *top; 1296 } aliases; 1297 1298 /** The currently parsed document. */ 1299 yaml_document_t *document; 1300 1301 /** 1302 * @} 1303 */ 1304 1305 } yaml_parser_t; 1306 1307 /** 1308 * Initialize a parser. 1309 * 1310 * This function creates a new parser object. An application is responsible 1311 * for destroying the object using the yaml_parser_delete() function. 1312 * 1313 * @param[out] parser An empty parser object. 1314 * 1315 * @returns @c 1 if the function succeeded, @c 0 on error. 1316 */ 1317 1318 YAML_DECLARE(int) 1319 yaml_parser_initialize(yaml_parser_t *parser); 1320 1321 /** 1322 * Destroy a parser. 1323 * 1324 * @param[in,out] parser A parser object. 1325 */ 1326 1327 YAML_DECLARE(void) 1328 yaml_parser_delete(yaml_parser_t *parser); 1329 1330 /** 1331 * Set a string input. 1332 * 1333 * Note that the @a input pointer must be valid while the @a parser object 1334 * exists. The application is responsible for destroing @a input after 1335 * destroying the @a parser. 1336 * 1337 * @param[in,out] parser A parser object. 1338 * @param[in] input A source data. 1339 * @param[in] size The length of the source data in bytes. 1340 */ 1341 1342 YAML_DECLARE(void) 1343 yaml_parser_set_input_string(yaml_parser_t *parser, 1344 const unsigned char *input, size_t size); 1345 1346 /** 1347 * Set a file input. 1348 * 1349 * @a file should be a file object open for reading. The application is 1350 * responsible for closing the @a file. 1351 * 1352 * @param[in,out] parser A parser object. 1353 * @param[in] file An open file. 1354 */ 1355 1356 YAML_DECLARE(void) 1357 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file); 1358 1359 /** 1360 * Set a generic input handler. 1361 * 1362 * @param[in,out] parser A parser object. 1363 * @param[in] handler A read handler. 1364 * @param[in] data Any application data for passing to the read 1365 * handler. 1366 */ 1367 1368 YAML_DECLARE(void) 1369 yaml_parser_set_input(yaml_parser_t *parser, 1370 yaml_read_handler_t *handler, void *data); 1371 1372 /** 1373 * Set the source encoding. 1374 * 1375 * @param[in,out] parser A parser object. 1376 * @param[in] encoding The source encoding. 1377 */ 1378 1379 YAML_DECLARE(void) 1380 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding); 1381 1382 /** 1383 * Scan the input stream and produce the next token. 1384 * 1385 * Call the function subsequently to produce a sequence of tokens corresponding 1386 * to the input stream. The initial token has the type 1387 * @c YAML_STREAM_START_TOKEN while the ending token has the type 1388 * @c YAML_STREAM_END_TOKEN. 1389 * 1390 * An application is responsible for freeing any buffers associated with the 1391 * produced token object using the @c yaml_token_delete function. 1392 * 1393 * An application must not alternate the calls of yaml_parser_scan() with the 1394 * calls of yaml_parser_parse() or yaml_parser_load(). Doing this will break 1395 * the parser. 1396 * 1397 * @param[in,out] parser A parser object. 1398 * @param[out] token An empty token object. 1399 * 1400 * @returns @c 1 if the function succeeded, @c 0 on error. 1401 */ 1402 1403 YAML_DECLARE(int) 1404 yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token); 1405 1406 /** 1407 * Parse the input stream and produce the next parsing event. 1408 * 1409 * Call the function subsequently to produce a sequence of events corresponding 1410 * to the input stream. The initial event has the type 1411 * @c YAML_STREAM_START_EVENT while the ending event has the type 1412 * @c YAML_STREAM_END_EVENT. 1413 * 1414 * An application is responsible for freeing any buffers associated with the 1415 * produced event object using the yaml_event_delete() function. 1416 * 1417 * An application must not alternate the calls of yaml_parser_parse() with the 1418 * calls of yaml_parser_scan() or yaml_parser_load(). Doing this will break the 1419 * parser. 1420 * 1421 * @param[in,out] parser A parser object. 1422 * @param[out] event An empty event object. 1423 * 1424 * @returns @c 1 if the function succeeded, @c 0 on error. 1425 */ 1426 1427 YAML_DECLARE(int) 1428 yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event); 1429 1430 /** 1431 * Parse the input stream and produce the next YAML document. 1432 * 1433 * Call this function subsequently to produce a sequence of documents 1434 * constituting the input stream. 1435 * 1436 * If the produced document has no root node, it means that the document 1437 * end has been reached. 1438 * 1439 * An application is responsible for freeing any data associated with the 1440 * produced document object using the yaml_document_delete() function. 1441 * 1442 * An application must not alternate the calls of yaml_parser_load() with the 1443 * calls of yaml_parser_scan() or yaml_parser_parse(). Doing this will break 1444 * the parser. 1445 * 1446 * @param[in,out] parser A parser object. 1447 * @param[out] document An empty document object. 1448 * 1449 * @return @c 1 if the function succeeded, @c 0 on error. 1450 */ 1451 1452 YAML_DECLARE(int) 1453 yaml_parser_load(yaml_parser_t *parser, yaml_document_t *document); 1454 1455 /** @} */ 1456 1457 /** 1458 * @defgroup emitter Emitter Definitions 1459 * @{ 1460 */ 1461 1462 /** 1463 * The prototype of a write handler. 1464 * 1465 * The write handler is called when the emitter needs to flush the accumulated 1466 * characters to the output. The handler should write @a size bytes of the 1467 * @a buffer to the output. 1468 * 1469 * @param[in,out] data A pointer to an application data specified by 1470 * yaml_emitter_set_output(). 1471 * @param[in] buffer The buffer with bytes to be written. 1472 * @param[in] size The size of the buffer. 1473 * 1474 * @returns On success, the handler should return @c 1. If the handler failed, 1475 * the returned value should be @c 0. 1476 */ 1477 1478 typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size); 1479 1480 /** The emitter states. */ 1481 typedef enum yaml_emitter_state_e { 1482 /** Expect STREAM-START. */ 1483 YAML_EMIT_STREAM_START_STATE, 1484 /** Expect the first DOCUMENT-START or STREAM-END. */ 1485 YAML_EMIT_FIRST_DOCUMENT_START_STATE, 1486 /** Expect DOCUMENT-START or STREAM-END. */ 1487 YAML_EMIT_DOCUMENT_START_STATE, 1488 /** Expect the content of a document. */ 1489 YAML_EMIT_DOCUMENT_CONTENT_STATE, 1490 /** Expect DOCUMENT-END. */ 1491 YAML_EMIT_DOCUMENT_END_STATE, 1492 /** Expect the first item of a flow sequence. */ 1493 YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE, 1494 /** Expect an item of a flow sequence. */ 1495 YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE, 1496 /** Expect the first key of a flow mapping. */ 1497 YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE, 1498 /** Expect a key of a flow mapping. */ 1499 YAML_EMIT_FLOW_MAPPING_KEY_STATE, 1500 /** Expect a value for a simple key of a flow mapping. */ 1501 YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE, 1502 /** Expect a value of a flow mapping. */ 1503 YAML_EMIT_FLOW_MAPPING_VALUE_STATE, 1504 /** Expect the first item of a block sequence. */ 1505 YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE, 1506 /** Expect an item of a block sequence. */ 1507 YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE, 1508 /** Expect the first key of a block mapping. */ 1509 YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE, 1510 /** Expect the key of a block mapping. */ 1511 YAML_EMIT_BLOCK_MAPPING_KEY_STATE, 1512 /** Expect a value for a simple key of a block mapping. */ 1513 YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE, 1514 /** Expect a value of a block mapping. */ 1515 YAML_EMIT_BLOCK_MAPPING_VALUE_STATE, 1516 /** Expect nothing. */ 1517 YAML_EMIT_END_STATE 1518 } yaml_emitter_state_t; 1519 1520 /** 1521 * The emitter structure. 1522 * 1523 * All members are internal. Manage the structure using the @c yaml_emitter_ 1524 * family of functions. 1525 */ 1526 1527 typedef struct yaml_emitter_s { 1528 1529 /** 1530 * @name Error handling 1531 * @{ 1532 */ 1533 1534 /** Error type. */ 1535 yaml_error_type_t error; 1536 /** Error description. */ 1537 const char *problem; 1538 1539 /** 1540 * @} 1541 */ 1542 1543 /** 1544 * @name Writer stuff 1545 * @{ 1546 */ 1547 1548 /** Write handler. */ 1549 yaml_write_handler_t *write_handler; 1550 1551 /** A pointer for passing to the white handler. */ 1552 void *write_handler_data; 1553 1554 /** Standard (string or file) output data. */ 1555 union { 1556 /** String output data. */ 1557 struct { 1558 /** The buffer pointer. */ 1559 unsigned char *buffer; 1560 /** The buffer size. */ 1561 size_t size; 1562 /** The number of written bytes. */ 1563 size_t *size_written; 1564 } string; 1565 1566 /** File output data. */ 1567 FILE *file; 1568 } output; 1569 1570 /** The working buffer. */ 1571 struct { 1572 /** The beginning of the buffer. */ 1573 yaml_char_t *start; 1574 /** The end of the buffer. */ 1575 yaml_char_t *end; 1576 /** The current position of the buffer. */ 1577 yaml_char_t *pointer; 1578 /** The last filled position of the buffer. */ 1579 yaml_char_t *last; 1580 } buffer; 1581 1582 /** The raw buffer. */ 1583 struct { 1584 /** The beginning of the buffer. */ 1585 unsigned char *start; 1586 /** The end of the buffer. */ 1587 unsigned char *end; 1588 /** The current position of the buffer. */ 1589 unsigned char *pointer; 1590 /** The last filled position of the buffer. */ 1591 unsigned char *last; 1592 } raw_buffer; 1593 1594 /** The stream encoding. */ 1595 yaml_encoding_t encoding; 1596 1597 /** 1598 * @} 1599 */ 1600 1601 /** 1602 * @name Emitter stuff 1603 * @{ 1604 */ 1605 1606 /** If the output is in the canonical style? */ 1607 int canonical; 1608 /** The number of indentation spaces. */ 1609 int best_indent; 1610 /** The preferred width of the output lines. */ 1611 int best_width; 1612 /** Allow unescaped non-ASCII characters? */ 1613 int unicode; 1614 /** The preferred line break. */ 1615 yaml_break_t line_break; 1616 1617 /** The stack of states. */ 1618 struct { 1619 /** The beginning of the stack. */ 1620 yaml_emitter_state_t *start; 1621 /** The end of the stack. */ 1622 yaml_emitter_state_t *end; 1623 /** The top of the stack. */ 1624 yaml_emitter_state_t *top; 1625 } states; 1626 1627 /** The current emitter state. */ 1628 yaml_emitter_state_t state; 1629 1630 /** The event queue. */ 1631 struct { 1632 /** The beginning of the event queue. */ 1633 yaml_event_t *start; 1634 /** The end of the event queue. */ 1635 yaml_event_t *end; 1636 /** The head of the event queue. */ 1637 yaml_event_t *head; 1638 /** The tail of the event queue. */ 1639 yaml_event_t *tail; 1640 } events; 1641 1642 /** The stack of indentation levels. */ 1643 struct { 1644 /** The beginning of the stack. */ 1645 int *start; 1646 /** The end of the stack. */ 1647 int *end; 1648 /** The top of the stack. */ 1649 int *top; 1650 } indents; 1651 1652 /** The list of tag directives. */ 1653 struct { 1654 /** The beginning of the list. */ 1655 yaml_tag_directive_t *start; 1656 /** The end of the list. */ 1657 yaml_tag_directive_t *end; 1658 /** The top of the list. */ 1659 yaml_tag_directive_t *top; 1660 } tag_directives; 1661 1662 /** The current indentation level. */ 1663 int indent; 1664 1665 /** The current flow level. */ 1666 int flow_level; 1667 1668 /** Is it the document root context? */ 1669 int root_context; 1670 /** Is it a sequence context? */ 1671 int sequence_context; 1672 /** Is it a mapping context? */ 1673 int mapping_context; 1674 /** Is it a simple mapping key context? */ 1675 int simple_key_context; 1676 1677 /** The current line. */ 1678 int line; 1679 /** The current column. */ 1680 int column; 1681 /** If the last character was a whitespace? */ 1682 int whitespace; 1683 /** If the last character was an indentation character (' ', '-', '?', ':')? */ 1684 int indention; 1685 /** If an explicit document end is required? */ 1686 int open_ended; 1687 1688 /** Anchor analysis. */ 1689 struct { 1690 /** The anchor value. */ 1691 yaml_char_t *anchor; 1692 /** The anchor length. */ 1693 size_t anchor_length; 1694 /** Is it an alias? */ 1695 int alias; 1696 } anchor_data; 1697 1698 /** Tag analysis. */ 1699 struct { 1700 /** The tag handle. */ 1701 yaml_char_t *handle; 1702 /** The tag handle length. */ 1703 size_t handle_length; 1704 /** The tag suffix. */ 1705 yaml_char_t *suffix; 1706 /** The tag suffix length. */ 1707 size_t suffix_length; 1708 } tag_data; 1709 1710 /** Scalar analysis. */ 1711 struct { 1712 /** The scalar value. */ 1713 yaml_char_t *value; 1714 /** The scalar length. */ 1715 size_t length; 1716 /** Does the scalar contain line breaks? */ 1717 int multiline; 1718 /** Can the scalar be expessed in the flow plain style? */ 1719 int flow_plain_allowed; 1720 /** Can the scalar be expressed in the block plain style? */ 1721 int block_plain_allowed; 1722 /** Can the scalar be expressed in the single quoted style? */ 1723 int single_quoted_allowed; 1724 /** Can the scalar be expressed in the literal or folded styles? */ 1725 int block_allowed; 1726 /** The output style. */ 1727 yaml_scalar_style_t style; 1728 } scalar_data; 1729 1730 /** 1731 * @} 1732 */ 1733 1734 /** 1735 * @name Dumper stuff 1736 * @{ 1737 */ 1738 1739 /** If the stream was already opened? */ 1740 int opened; 1741 /** If the stream was already closed? */ 1742 int closed; 1743 1744 /** The information associated with the document nodes. */ 1745 struct { 1746 /** The number of references. */ 1747 int references; 1748 /** The anchor id. */ 1749 int anchor; 1750 /** If the node has been emitted? */ 1751 int serialized; 1752 } *anchors; 1753 1754 /** The last assigned anchor id. */ 1755 int last_anchor_id; 1756 1757 /** The currently emitted document. */ 1758 yaml_document_t *document; 1759 1760 /** 1761 * @} 1762 */ 1763 1764 } yaml_emitter_t; 1765 1766 /** 1767 * Initialize an emitter. 1768 * 1769 * This function creates a new emitter object. An application is responsible 1770 * for destroying the object using the yaml_emitter_delete() function. 1771 * 1772 * @param[out] emitter An empty parser object. 1773 * 1774 * @returns @c 1 if the function succeeded, @c 0 on error. 1775 */ 1776 1777 YAML_DECLARE(int) 1778 yaml_emitter_initialize(yaml_emitter_t *emitter); 1779 1780 /** 1781 * Destroy an emitter. 1782 * 1783 * @param[in,out] emitter An emitter object. 1784 */ 1785 1786 YAML_DECLARE(void) 1787 yaml_emitter_delete(yaml_emitter_t *emitter); 1788 1789 /** 1790 * Set a string output. 1791 * 1792 * The emitter will write the output characters to the @a output buffer of the 1793 * size @a size. The emitter will set @a size_written to the number of written 1794 * bytes. If the buffer is smaller than required, the emitter produces the 1795 * YAML_WRITE_ERROR error. 1796 * 1797 * @param[in,out] emitter An emitter object. 1798 * @param[in] output An output buffer. 1799 * @param[in] size The buffer size. 1800 * @param[in] size_written The pointer to save the number of written 1801 * bytes. 1802 */ 1803 1804 YAML_DECLARE(void) 1805 yaml_emitter_set_output_string(yaml_emitter_t *emitter, 1806 unsigned char *output, size_t size, size_t *size_written); 1807 1808 /** 1809 * Set a file output. 1810 * 1811 * @a file should be a file object open for writing. The application is 1812 * responsible for closing the @a file. 1813 * 1814 * @param[in,out] emitter An emitter object. 1815 * @param[in] file An open file. 1816 */ 1817 1818 YAML_DECLARE(void) 1819 yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file); 1820 1821 /** 1822 * Set a generic output handler. 1823 * 1824 * @param[in,out] emitter An emitter object. 1825 * @param[in] handler A write handler. 1826 * @param[in] data Any application data for passing to the write 1827 * handler. 1828 */ 1829 1830 YAML_DECLARE(void) 1831 yaml_emitter_set_output(yaml_emitter_t *emitter, 1832 yaml_write_handler_t *handler, void *data); 1833 1834 /** 1835 * Set the output encoding. 1836 * 1837 * @param[in,out] emitter An emitter object. 1838 * @param[in] encoding The output encoding. 1839 */ 1840 1841 YAML_DECLARE(void) 1842 yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding); 1843 1844 /** 1845 * Set if the output should be in the "canonical" format as in the YAML 1846 * specification. 1847 * 1848 * @param[in,out] emitter An emitter object. 1849 * @param[in] canonical If the output is canonical. 1850 */ 1851 1852 YAML_DECLARE(void) 1853 yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical); 1854 1855 /** 1856 * Set the intendation increment. 1857 * 1858 * @param[in,out] emitter An emitter object. 1859 * @param[in] indent The indentation increment (1 < . < 10). 1860 */ 1861 1862 YAML_DECLARE(void) 1863 yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent); 1864 1865 /** 1866 * Set the preferred line width. @c -1 means unlimited. 1867 * 1868 * @param[in,out] emitter An emitter object. 1869 * @param[in] width The preferred line width. 1870 */ 1871 1872 YAML_DECLARE(void) 1873 yaml_emitter_set_width(yaml_emitter_t *emitter, int width); 1874 1875 /** 1876 * Set if unescaped non-ASCII characters are allowed. 1877 * 1878 * @param[in,out] emitter An emitter object. 1879 * @param[in] unicode If unescaped Unicode characters are allowed. 1880 */ 1881 1882 YAML_DECLARE(void) 1883 yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode); 1884 1885 /** 1886 * Set the preferred line break. 1887 * 1888 * @param[in,out] emitter An emitter object. 1889 * @param[in] line_break The preferred line break. 1890 */ 1891 1892 YAML_DECLARE(void) 1893 yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break); 1894 1895 /** 1896 * Emit an event. 1897 * 1898 * The event object may be generated using the yaml_parser_parse() function. 1899 * The emitter takes the responsibility for the event object and destroys its 1900 * content after it is emitted. The event object is destroyed even if the 1901 * function fails. 1902 * 1903 * @param[in,out] emitter An emitter object. 1904 * @param[in,out] event An event object. 1905 * 1906 * @returns @c 1 if the function succeeded, @c 0 on error. 1907 */ 1908 1909 YAML_DECLARE(int) 1910 yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event); 1911 1912 /** 1913 * Start a YAML stream. 1914 * 1915 * This function should be used before yaml_emitter_dump() is called. 1916 * 1917 * @param[in,out] emitter An emitter object. 1918 * 1919 * @returns @c 1 if the function succeeded, @c 0 on error. 1920 */ 1921 1922 YAML_DECLARE(int) 1923 yaml_emitter_open(yaml_emitter_t *emitter); 1924 1925 /** 1926 * Finish a YAML stream. 1927 * 1928 * This function should be used after yaml_emitter_dump() is called. 1929 * 1930 * @param[in,out] emitter An emitter object. 1931 * 1932 * @returns @c 1 if the function succeeded, @c 0 on error. 1933 */ 1934 1935 YAML_DECLARE(int) 1936 yaml_emitter_close(yaml_emitter_t *emitter); 1937 1938 /** 1939 * Emit a YAML document. 1940 * 1941 * The documen object may be generated using the yaml_parser_load() function 1942 * or the yaml_document_initialize() function. The emitter takes the 1943 * responsibility for the document object and destoys its content after 1944 * it is emitted. The document object is destroyedeven if the function fails. 1945 * 1946 * @param[in,out] emitter An emitter object. 1947 * @param[in,out] document A document object. 1948 * 1949 * @returns @c 1 if the function succeeded, @c 0 on error. 1950 */ 1951 1952 YAML_DECLARE(int) 1953 yaml_emitter_dump(yaml_emitter_t *emitter, yaml_document_t *document); 1954 1955 /** 1956 * Flush the accumulated characters to the output. 1957 * 1958 * @param[in,out] emitter An emitter object. 1959 * 1960 * @returns @c 1 if the function succeeded, @c 0 on error. 1961 */ 1962 1963 YAML_DECLARE(int) 1964 yaml_emitter_flush(yaml_emitter_t *emitter); 1965 1966 /** @} */ 1967 1968 #ifdef __cplusplus 1969 } 1970 #endif 1971 1972 #endif /* #ifndef YAML_H */ 1973 1974