yaml.h (54439B)
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-MAPPING-START 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, const 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 const yaml_char_t *anchor, const yaml_char_t *tag, 582 const 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 const yaml_char_t *anchor, const 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 const yaml_char_t *anchor, const 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 const yaml_char_t *tag, const 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 const 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 const 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 1024 /** Expect a block node. */ 1025 YAML_PARSE_BLOCK_NODE_STATE, 1026 /** Expect a block node or indentless sequence. */ 1027 YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE, 1028 /** Expect a flow node. */ 1029 YAML_PARSE_FLOW_NODE_STATE, 1030 /** Expect the first entry of a block sequence. */ 1031 YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE, 1032 /** Expect an entry of a block sequence. */ 1033 YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE, 1034 1035 /** Expect an entry of an indentless sequence. */ 1036 YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE, 1037 /** Expect the first key of a block mapping. */ 1038 YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE, 1039 /** Expect a block mapping key. */ 1040 YAML_PARSE_BLOCK_MAPPING_KEY_STATE, 1041 /** Expect a block mapping value. */ 1042 YAML_PARSE_BLOCK_MAPPING_VALUE_STATE, 1043 /** Expect the first entry of a flow sequence. */ 1044 YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE, 1045 1046 /** Expect an entry of a flow sequence. */ 1047 YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE, 1048 /** Expect a key of an ordered mapping. */ 1049 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE, 1050 /** Expect a value of an ordered mapping. */ 1051 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE, 1052 /** Expect the and of an ordered mapping entry. */ 1053 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE, 1054 /** Expect the first key of a flow mapping. */ 1055 YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE, 1056 /** Expect a key of a flow mapping. */ 1057 1058 YAML_PARSE_FLOW_MAPPING_KEY_STATE, 1059 /** Expect a value of a flow mapping. */ 1060 YAML_PARSE_FLOW_MAPPING_VALUE_STATE, 1061 /** Expect an empty value of a flow mapping. */ 1062 YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE, 1063 /** Expect nothing. */ 1064 YAML_PARSE_END_STATE 1065 } yaml_parser_state_t; 1066 1067 /** 1068 * This structure holds aliases data. 1069 */ 1070 1071 typedef struct yaml_alias_data_s { 1072 /** The anchor. */ 1073 yaml_char_t *anchor; 1074 /** The node id. */ 1075 int index; 1076 /** The anchor mark. */ 1077 yaml_mark_t mark; 1078 } yaml_alias_data_t; 1079 1080 /** 1081 * The parser structure. 1082 * 1083 * All members are internal. Manage the structure using the @c yaml_parser_ 1084 * family of functions. 1085 */ 1086 1087 typedef struct yaml_parser_s { 1088 1089 /** 1090 * @name Error handling 1091 * @{ 1092 */ 1093 1094 /** Error type. */ 1095 yaml_error_type_t error; 1096 /** Error description. */ 1097 const char *problem; 1098 /** The byte about which the problem occured. */ 1099 size_t problem_offset; 1100 /** The problematic value (@c -1 is none). */ 1101 int problem_value; 1102 /** The problem position. */ 1103 yaml_mark_t problem_mark; 1104 /** The error context. */ 1105 const char *context; 1106 /** The context position. */ 1107 yaml_mark_t context_mark; 1108 1109 /** 1110 * @} 1111 */ 1112 1113 /** 1114 * @name Reader stuff 1115 * @{ 1116 */ 1117 1118 /** Read handler. */ 1119 yaml_read_handler_t *read_handler; 1120 1121 /** A pointer for passing to the read handler. */ 1122 void *read_handler_data; 1123 1124 /** Standard (string or file) input data. */ 1125 union { 1126 /** String input data. */ 1127 struct { 1128 /** The string start pointer. */ 1129 const unsigned char *start; 1130 /** The string end pointer. */ 1131 const unsigned char *end; 1132 /** The string current position. */ 1133 const unsigned char *current; 1134 } string; 1135 1136 /** File input data. */ 1137 FILE *file; 1138 } input; 1139 1140 /** EOF flag */ 1141 int eof; 1142 1143 /** The working buffer. */ 1144 struct { 1145 /** The beginning of the buffer. */ 1146 yaml_char_t *start; 1147 /** The end of the buffer. */ 1148 yaml_char_t *end; 1149 /** The current position of the buffer. */ 1150 yaml_char_t *pointer; 1151 /** The last filled position of the buffer. */ 1152 yaml_char_t *last; 1153 } buffer; 1154 1155 /* The number of unread characters in the buffer. */ 1156 size_t unread; 1157 1158 /** The raw buffer. */ 1159 struct { 1160 /** The beginning of the buffer. */ 1161 unsigned char *start; 1162 /** The end of the buffer. */ 1163 unsigned char *end; 1164 /** The current position of the buffer. */ 1165 unsigned char *pointer; 1166 /** The last filled position of the buffer. */ 1167 unsigned char *last; 1168 } raw_buffer; 1169 1170 /** The input encoding. */ 1171 yaml_encoding_t encoding; 1172 1173 /** The offset of the current position (in bytes). */ 1174 size_t offset; 1175 1176 /** The mark of the current position. */ 1177 yaml_mark_t mark; 1178 1179 /** 1180 * @} 1181 */ 1182 1183 /** 1184 * @name Scanner stuff 1185 * @{ 1186 */ 1187 1188 /** Have we started to scan the input stream? */ 1189 int stream_start_produced; 1190 1191 /** Have we reached the end of the input stream? */ 1192 int stream_end_produced; 1193 1194 /** The number of unclosed '[' and '{' indicators. */ 1195 int flow_level; 1196 1197 /** The tokens queue. */ 1198 struct { 1199 /** The beginning of the tokens queue. */ 1200 yaml_token_t *start; 1201 /** The end of the tokens queue. */ 1202 yaml_token_t *end; 1203 /** The head of the tokens queue. */ 1204 yaml_token_t *head; 1205 /** The tail of the tokens queue. */ 1206 yaml_token_t *tail; 1207 } tokens; 1208 1209 /** The number of tokens fetched from the queue. */ 1210 size_t tokens_parsed; 1211 1212 /** Does the tokens queue contain a token ready for dequeueing. */ 1213 int token_available; 1214 1215 /** The indentation levels stack. */ 1216 struct { 1217 /** The beginning of the stack. */ 1218 int *start; 1219 /** The end of the stack. */ 1220 int *end; 1221 /** The top of the stack. */ 1222 int *top; 1223 } indents; 1224 1225 /** The current indentation level. */ 1226 int indent; 1227 1228 /** May a simple key occur at the current position? */ 1229 int simple_key_allowed; 1230 1231 /** The stack of simple keys. */ 1232 struct { 1233 /** The beginning of the stack. */ 1234 yaml_simple_key_t *start; 1235 /** The end of the stack. */ 1236 yaml_simple_key_t *end; 1237 /** The top of the stack. */ 1238 yaml_simple_key_t *top; 1239 } simple_keys; 1240 1241 /** 1242 * @} 1243 */ 1244 1245 /** 1246 * @name Parser stuff 1247 * @{ 1248 */ 1249 1250 /** The parser states stack. */ 1251 struct { 1252 /** The beginning of the stack. */ 1253 yaml_parser_state_t *start; 1254 /** The end of the stack. */ 1255 yaml_parser_state_t *end; 1256 /** The top of the stack. */ 1257 yaml_parser_state_t *top; 1258 } states; 1259 1260 /** The current parser state. */ 1261 yaml_parser_state_t state; 1262 1263 /** The stack of marks. */ 1264 struct { 1265 /** The beginning of the stack. */ 1266 yaml_mark_t *start; 1267 /** The end of the stack. */ 1268 yaml_mark_t *end; 1269 /** The top of the stack. */ 1270 yaml_mark_t *top; 1271 } marks; 1272 1273 /** The list of TAG directives. */ 1274 struct { 1275 /** The beginning of the list. */ 1276 yaml_tag_directive_t *start; 1277 /** The end of the list. */ 1278 yaml_tag_directive_t *end; 1279 /** The top of the list. */ 1280 yaml_tag_directive_t *top; 1281 } tag_directives; 1282 1283 /** 1284 * @} 1285 */ 1286 1287 /** 1288 * @name Dumper stuff 1289 * @{ 1290 */ 1291 1292 /** The alias data. */ 1293 struct { 1294 /** The beginning of the list. */ 1295 yaml_alias_data_t *start; 1296 /** The end of the list. */ 1297 yaml_alias_data_t *end; 1298 /** The top of the list. */ 1299 yaml_alias_data_t *top; 1300 } aliases; 1301 1302 /** The currently parsed document. */ 1303 yaml_document_t *document; 1304 1305 /** 1306 * @} 1307 */ 1308 1309 } yaml_parser_t; 1310 1311 /** 1312 * Initialize a parser. 1313 * 1314 * This function creates a new parser object. An application is responsible 1315 * for destroying the object using the yaml_parser_delete() function. 1316 * 1317 * @param[out] parser An empty parser object. 1318 * 1319 * @returns @c 1 if the function succeeded, @c 0 on error. 1320 */ 1321 1322 YAML_DECLARE(int) 1323 yaml_parser_initialize(yaml_parser_t *parser); 1324 1325 /** 1326 * Destroy a parser. 1327 * 1328 * @param[in,out] parser A parser object. 1329 */ 1330 1331 YAML_DECLARE(void) 1332 yaml_parser_delete(yaml_parser_t *parser); 1333 1334 /** 1335 * Set a string input. 1336 * 1337 * Note that the @a input pointer must be valid while the @a parser object 1338 * exists. The application is responsible for destroing @a input after 1339 * destroying the @a parser. 1340 * 1341 * @param[in,out] parser A parser object. 1342 * @param[in] input A source data. 1343 * @param[in] size The length of the source data in bytes. 1344 */ 1345 1346 YAML_DECLARE(void) 1347 yaml_parser_set_input_string(yaml_parser_t *parser, 1348 const unsigned char *input, size_t size); 1349 1350 /** 1351 * Set a file input. 1352 * 1353 * @a file should be a file object open for reading. The application is 1354 * responsible for closing the @a file. 1355 * 1356 * @param[in,out] parser A parser object. 1357 * @param[in] file An open file. 1358 */ 1359 1360 YAML_DECLARE(void) 1361 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file); 1362 1363 /** 1364 * Set a generic input handler. 1365 * 1366 * @param[in,out] parser A parser object. 1367 * @param[in] handler A read handler. 1368 * @param[in] data Any application data for passing to the read 1369 * handler. 1370 */ 1371 1372 YAML_DECLARE(void) 1373 yaml_parser_set_input(yaml_parser_t *parser, 1374 yaml_read_handler_t *handler, void *data); 1375 1376 /** 1377 * Set the source encoding. 1378 * 1379 * @param[in,out] parser A parser object. 1380 * @param[in] encoding The source encoding. 1381 */ 1382 1383 YAML_DECLARE(void) 1384 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding); 1385 1386 /** 1387 * Scan the input stream and produce the next token. 1388 * 1389 * Call the function subsequently to produce a sequence of tokens corresponding 1390 * to the input stream. The initial token has the type 1391 * @c YAML_STREAM_START_TOKEN while the ending token has the type 1392 * @c YAML_STREAM_END_TOKEN. 1393 * 1394 * An application is responsible for freeing any buffers associated with the 1395 * produced token object using the @c yaml_token_delete function. 1396 * 1397 * An application must not alternate the calls of yaml_parser_scan() with the 1398 * calls of yaml_parser_parse() or yaml_parser_load(). Doing this will break 1399 * the parser. 1400 * 1401 * @param[in,out] parser A parser object. 1402 * @param[out] token An empty token object. 1403 * 1404 * @returns @c 1 if the function succeeded, @c 0 on error. 1405 */ 1406 1407 YAML_DECLARE(int) 1408 yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token); 1409 1410 /** 1411 * Parse the input stream and produce the next parsing event. 1412 * 1413 * Call the function subsequently to produce a sequence of events corresponding 1414 * to the input stream. The initial event has the type 1415 * @c YAML_STREAM_START_EVENT while the ending event has the type 1416 * @c YAML_STREAM_END_EVENT. 1417 * 1418 * An application is responsible for freeing any buffers associated with the 1419 * produced event object using the yaml_event_delete() function. 1420 * 1421 * An application must not alternate the calls of yaml_parser_parse() with the 1422 * calls of yaml_parser_scan() or yaml_parser_load(). Doing this will break the 1423 * parser. 1424 * 1425 * @param[in,out] parser A parser object. 1426 * @param[out] event An empty event object. 1427 * 1428 * @returns @c 1 if the function succeeded, @c 0 on error. 1429 */ 1430 1431 YAML_DECLARE(int) 1432 yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event); 1433 1434 /** 1435 * Parse the input stream and produce the next YAML document. 1436 * 1437 * Call this function subsequently to produce a sequence of documents 1438 * constituting the input stream. 1439 * 1440 * If the produced document has no root node, it means that the document 1441 * end has been reached. 1442 * 1443 * An application is responsible for freeing any data associated with the 1444 * produced document object using the yaml_document_delete() function. 1445 * 1446 * An application must not alternate the calls of yaml_parser_load() with the 1447 * calls of yaml_parser_scan() or yaml_parser_parse(). Doing this will break 1448 * the parser. 1449 * 1450 * @param[in,out] parser A parser object. 1451 * @param[out] document An empty document object. 1452 * 1453 * @returns @c 1 if the function succeeded, @c 0 on error. 1454 */ 1455 1456 YAML_DECLARE(int) 1457 yaml_parser_load(yaml_parser_t *parser, yaml_document_t *document); 1458 1459 /** @} */ 1460 1461 /** 1462 * @defgroup emitter Emitter Definitions 1463 * @{ 1464 */ 1465 1466 /** 1467 * The prototype of a write handler. 1468 * 1469 * The write handler is called when the emitter needs to flush the accumulated 1470 * characters to the output. The handler should write @a size bytes of the 1471 * @a buffer to the output. 1472 * 1473 * @param[in,out] data A pointer to an application data specified by 1474 * yaml_emitter_set_output(). 1475 * @param[in] buffer The buffer with bytes to be written. 1476 * @param[in] size The size of the buffer. 1477 * 1478 * @returns On success, the handler should return @c 1. If the handler failed, 1479 * the returned value should be @c 0. 1480 */ 1481 1482 typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size); 1483 1484 /** The emitter states. */ 1485 typedef enum yaml_emitter_state_e { 1486 /** Expect STREAM-START. */ 1487 YAML_EMIT_STREAM_START_STATE, 1488 /** Expect the first DOCUMENT-START or STREAM-END. */ 1489 YAML_EMIT_FIRST_DOCUMENT_START_STATE, 1490 /** Expect DOCUMENT-START or STREAM-END. */ 1491 YAML_EMIT_DOCUMENT_START_STATE, 1492 /** Expect the content of a document. */ 1493 YAML_EMIT_DOCUMENT_CONTENT_STATE, 1494 /** Expect DOCUMENT-END. */ 1495 YAML_EMIT_DOCUMENT_END_STATE, 1496 1497 /** Expect the first item of a flow sequence. */ 1498 YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE, 1499 /** Expect an item of a flow sequence. */ 1500 YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE, 1501 /** Expect the first key of a flow mapping. */ 1502 YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE, 1503 /** Expect a key of a flow mapping. */ 1504 YAML_EMIT_FLOW_MAPPING_KEY_STATE, 1505 /** Expect a value for a simple key of a flow mapping. */ 1506 YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE, 1507 1508 /** Expect a value of a flow mapping. */ 1509 YAML_EMIT_FLOW_MAPPING_VALUE_STATE, 1510 /** Expect the first item of a block sequence. */ 1511 YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE, 1512 /** Expect an item of a block sequence. */ 1513 YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE, 1514 /** Expect the first key of a block mapping. */ 1515 YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE, 1516 /** Expect the key of a block mapping. */ 1517 YAML_EMIT_BLOCK_MAPPING_KEY_STATE, 1518 1519 /** Expect a value for a simple key of a block mapping. */ 1520 YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE, 1521 /** Expect a value of a block mapping. */ 1522 YAML_EMIT_BLOCK_MAPPING_VALUE_STATE, 1523 /** Expect nothing. */ 1524 YAML_EMIT_END_STATE 1525 } yaml_emitter_state_t; 1526 1527 1528 /* This is needed for C++ */ 1529 1530 typedef struct yaml_anchors_s { 1531 /** The number of references. */ 1532 int references; 1533 /** The anchor id. */ 1534 int anchor; 1535 /** If the node has been emitted? */ 1536 int serialized; 1537 } yaml_anchors_t; 1538 1539 /** 1540 * The emitter structure. 1541 * 1542 * All members are internal. Manage the structure using the @c yaml_emitter_ 1543 * family of functions. 1544 */ 1545 1546 typedef struct yaml_emitter_s { 1547 1548 /** 1549 * @name Error handling 1550 * @{ 1551 */ 1552 1553 /** Error type. */ 1554 yaml_error_type_t error; 1555 /** Error description. */ 1556 const char *problem; 1557 1558 /** 1559 * @} 1560 */ 1561 1562 /** 1563 * @name Writer stuff 1564 * @{ 1565 */ 1566 1567 /** Write handler. */ 1568 yaml_write_handler_t *write_handler; 1569 1570 /** A pointer for passing to the write handler. */ 1571 void *write_handler_data; 1572 1573 /** Standard (string or file) output data. */ 1574 union { 1575 /** String output data. */ 1576 struct { 1577 /** The buffer pointer. */ 1578 unsigned char *buffer; 1579 /** The buffer size. */ 1580 size_t size; 1581 /** The number of written bytes. */ 1582 size_t *size_written; 1583 } string; 1584 1585 /** File output data. */ 1586 FILE *file; 1587 } output; 1588 1589 /** The working buffer. */ 1590 struct { 1591 /** The beginning of the buffer. */ 1592 yaml_char_t *start; 1593 /** The end of the buffer. */ 1594 yaml_char_t *end; 1595 /** The current position of the buffer. */ 1596 yaml_char_t *pointer; 1597 /** The last filled position of the buffer. */ 1598 yaml_char_t *last; 1599 } buffer; 1600 1601 /** The raw buffer. */ 1602 struct { 1603 /** The beginning of the buffer. */ 1604 unsigned char *start; 1605 /** The end of the buffer. */ 1606 unsigned char *end; 1607 /** The current position of the buffer. */ 1608 unsigned char *pointer; 1609 /** The last filled position of the buffer. */ 1610 unsigned char *last; 1611 } raw_buffer; 1612 1613 /** The stream encoding. */ 1614 yaml_encoding_t encoding; 1615 1616 /** 1617 * @} 1618 */ 1619 1620 /** 1621 * @name Emitter stuff 1622 * @{ 1623 */ 1624 1625 /** If the output is in the canonical style? */ 1626 int canonical; 1627 /** The number of indentation spaces. */ 1628 int best_indent; 1629 /** The preferred width of the output lines. */ 1630 int best_width; 1631 /** Allow unescaped non-ASCII characters? */ 1632 int unicode; 1633 /** The preferred line break. */ 1634 yaml_break_t line_break; 1635 1636 /** The stack of states. */ 1637 struct { 1638 /** The beginning of the stack. */ 1639 yaml_emitter_state_t *start; 1640 /** The end of the stack. */ 1641 yaml_emitter_state_t *end; 1642 /** The top of the stack. */ 1643 yaml_emitter_state_t *top; 1644 } states; 1645 1646 /** The current emitter state. */ 1647 yaml_emitter_state_t state; 1648 1649 /** The event queue. */ 1650 struct { 1651 /** The beginning of the event queue. */ 1652 yaml_event_t *start; 1653 /** The end of the event queue. */ 1654 yaml_event_t *end; 1655 /** The head of the event queue. */ 1656 yaml_event_t *head; 1657 /** The tail of the event queue. */ 1658 yaml_event_t *tail; 1659 } events; 1660 1661 /** The stack of indentation levels. */ 1662 struct { 1663 /** The beginning of the stack. */ 1664 int *start; 1665 /** The end of the stack. */ 1666 int *end; 1667 /** The top of the stack. */ 1668 int *top; 1669 } indents; 1670 1671 /** The list of tag directives. */ 1672 struct { 1673 /** The beginning of the list. */ 1674 yaml_tag_directive_t *start; 1675 /** The end of the list. */ 1676 yaml_tag_directive_t *end; 1677 /** The top of the list. */ 1678 yaml_tag_directive_t *top; 1679 } tag_directives; 1680 1681 /** The current indentation level. */ 1682 int indent; 1683 1684 /** The current flow level. */ 1685 int flow_level; 1686 1687 /** Is it the document root context? */ 1688 int root_context; 1689 /** Is it a sequence context? */ 1690 int sequence_context; 1691 /** Is it a mapping context? */ 1692 int mapping_context; 1693 /** Is it a simple mapping key context? */ 1694 int simple_key_context; 1695 1696 /** The current line. */ 1697 int line; 1698 /** The current column. */ 1699 int column; 1700 /** If the last character was a whitespace? */ 1701 int whitespace; 1702 /** If the last character was an indentation character (' ', '-', '?', ':')? */ 1703 int indention; 1704 /** If an explicit document end is required? */ 1705 int open_ended; 1706 1707 /** Anchor analysis. */ 1708 struct { 1709 /** The anchor value. */ 1710 yaml_char_t *anchor; 1711 /** The anchor length. */ 1712 size_t anchor_length; 1713 /** Is it an alias? */ 1714 int alias; 1715 } anchor_data; 1716 1717 /** Tag analysis. */ 1718 struct { 1719 /** The tag handle. */ 1720 yaml_char_t *handle; 1721 /** The tag handle length. */ 1722 size_t handle_length; 1723 /** The tag suffix. */ 1724 yaml_char_t *suffix; 1725 /** The tag suffix length. */ 1726 size_t suffix_length; 1727 } tag_data; 1728 1729 /** Scalar analysis. */ 1730 struct { 1731 /** The scalar value. */ 1732 yaml_char_t *value; 1733 /** The scalar length. */ 1734 size_t length; 1735 /** Does the scalar contain line breaks? */ 1736 int multiline; 1737 /** Can the scalar be expessed in the flow plain style? */ 1738 int flow_plain_allowed; 1739 /** Can the scalar be expressed in the block plain style? */ 1740 int block_plain_allowed; 1741 /** Can the scalar be expressed in the single quoted style? */ 1742 int single_quoted_allowed; 1743 /** Can the scalar be expressed in the literal or folded styles? */ 1744 int block_allowed; 1745 /** The output style. */ 1746 yaml_scalar_style_t style; 1747 } scalar_data; 1748 1749 /** 1750 * @} 1751 */ 1752 1753 /** 1754 * @name Dumper stuff 1755 * @{ 1756 */ 1757 1758 /** If the stream was already opened? */ 1759 int opened; 1760 /** If the stream was already closed? */ 1761 int closed; 1762 1763 /** The information associated with the document nodes. */ 1764 yaml_anchors_t *anchors; 1765 1766 /** The last assigned anchor id. */ 1767 int last_anchor_id; 1768 1769 /** The currently emitted document. */ 1770 yaml_document_t *document; 1771 1772 /** 1773 * @} 1774 */ 1775 1776 } yaml_emitter_t; 1777 1778 /** 1779 * Initialize an emitter. 1780 * 1781 * This function creates a new emitter object. An application is responsible 1782 * for destroying the object using the yaml_emitter_delete() function. 1783 * 1784 * @param[out] emitter An empty parser object. 1785 * 1786 * @returns @c 1 if the function succeeded, @c 0 on error. 1787 */ 1788 1789 YAML_DECLARE(int) 1790 yaml_emitter_initialize(yaml_emitter_t *emitter); 1791 1792 /** 1793 * Destroy an emitter. 1794 * 1795 * @param[in,out] emitter An emitter object. 1796 */ 1797 1798 YAML_DECLARE(void) 1799 yaml_emitter_delete(yaml_emitter_t *emitter); 1800 1801 /** 1802 * Set a string output. 1803 * 1804 * The emitter will write the output characters to the @a output buffer of the 1805 * size @a size. The emitter will set @a size_written to the number of written 1806 * bytes. If the buffer is smaller than required, the emitter produces the 1807 * YAML_WRITE_ERROR error. 1808 * 1809 * @param[in,out] emitter An emitter object. 1810 * @param[in] output An output buffer. 1811 * @param[in] size The buffer size. 1812 * @param[in] size_written The pointer to save the number of written 1813 * bytes. 1814 */ 1815 1816 YAML_DECLARE(void) 1817 yaml_emitter_set_output_string(yaml_emitter_t *emitter, 1818 unsigned char *output, size_t size, size_t *size_written); 1819 1820 /** 1821 * Set a file output. 1822 * 1823 * @a file should be a file object open for writing. The application is 1824 * responsible for closing the @a file. 1825 * 1826 * @param[in,out] emitter An emitter object. 1827 * @param[in] file An open file. 1828 */ 1829 1830 YAML_DECLARE(void) 1831 yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file); 1832 1833 /** 1834 * Set a generic output handler. 1835 * 1836 * @param[in,out] emitter An emitter object. 1837 * @param[in] handler A write handler. 1838 * @param[in] data Any application data for passing to the write 1839 * handler. 1840 */ 1841 1842 YAML_DECLARE(void) 1843 yaml_emitter_set_output(yaml_emitter_t *emitter, 1844 yaml_write_handler_t *handler, void *data); 1845 1846 /** 1847 * Set the output encoding. 1848 * 1849 * @param[in,out] emitter An emitter object. 1850 * @param[in] encoding The output encoding. 1851 */ 1852 1853 YAML_DECLARE(void) 1854 yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding); 1855 1856 /** 1857 * Set if the output should be in the "canonical" format as in the YAML 1858 * specification. 1859 * 1860 * @param[in,out] emitter An emitter object. 1861 * @param[in] canonical If the output is canonical. 1862 */ 1863 1864 YAML_DECLARE(void) 1865 yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical); 1866 1867 /** 1868 * Set the indentation increment. 1869 * 1870 * @param[in,out] emitter An emitter object. 1871 * @param[in] indent The indentation increment (1 < . < 10). 1872 */ 1873 1874 YAML_DECLARE(void) 1875 yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent); 1876 1877 /** 1878 * Set the preferred line width. @c -1 means unlimited. 1879 * 1880 * @param[in,out] emitter An emitter object. 1881 * @param[in] width The preferred line width. 1882 */ 1883 1884 YAML_DECLARE(void) 1885 yaml_emitter_set_width(yaml_emitter_t *emitter, int width); 1886 1887 /** 1888 * Set if unescaped non-ASCII characters are allowed. 1889 * 1890 * @param[in,out] emitter An emitter object. 1891 * @param[in] unicode If unescaped Unicode characters are allowed. 1892 */ 1893 1894 YAML_DECLARE(void) 1895 yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode); 1896 1897 /** 1898 * Set the preferred line break. 1899 * 1900 * @param[in,out] emitter An emitter object. 1901 * @param[in] line_break The preferred line break. 1902 */ 1903 1904 YAML_DECLARE(void) 1905 yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break); 1906 1907 /** 1908 * Emit an event. 1909 * 1910 * The event object may be generated using the yaml_parser_parse() function. 1911 * The emitter takes the responsibility for the event object and destroys its 1912 * content after it is emitted. The event object is destroyed even if the 1913 * function fails. 1914 * 1915 * @param[in,out] emitter An emitter object. 1916 * @param[in,out] event An event object. 1917 * 1918 * @returns @c 1 if the function succeeded, @c 0 on error. 1919 */ 1920 1921 YAML_DECLARE(int) 1922 yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event); 1923 1924 /** 1925 * Start a YAML stream. 1926 * 1927 * This function should be used before yaml_emitter_dump() is called. 1928 * 1929 * @param[in,out] emitter An emitter object. 1930 * 1931 * @returns @c 1 if the function succeeded, @c 0 on error. 1932 */ 1933 1934 YAML_DECLARE(int) 1935 yaml_emitter_open(yaml_emitter_t *emitter); 1936 1937 /** 1938 * Finish a YAML stream. 1939 * 1940 * This function should be used after yaml_emitter_dump() is called. 1941 * 1942 * @param[in,out] emitter An emitter object. 1943 * 1944 * @returns @c 1 if the function succeeded, @c 0 on error. 1945 */ 1946 1947 YAML_DECLARE(int) 1948 yaml_emitter_close(yaml_emitter_t *emitter); 1949 1950 /** 1951 * Emit a YAML document. 1952 * 1953 * The documen object may be generated using the yaml_parser_load() function 1954 * or the yaml_document_initialize() function. The emitter takes the 1955 * responsibility for the document object and destroys its content after 1956 * it is emitted. The document object is destroyed even if the function fails. 1957 * 1958 * @param[in,out] emitter An emitter object. 1959 * @param[in,out] document A document object. 1960 * 1961 * @returns @c 1 if the function succeeded, @c 0 on error. 1962 */ 1963 1964 YAML_DECLARE(int) 1965 yaml_emitter_dump(yaml_emitter_t *emitter, yaml_document_t *document); 1966 1967 /** 1968 * Flush the accumulated characters to the output. 1969 * 1970 * @param[in,out] emitter An emitter object. 1971 * 1972 * @returns @c 1 if the function succeeded, @c 0 on error. 1973 */ 1974 1975 YAML_DECLARE(int) 1976 yaml_emitter_flush(yaml_emitter_t *emitter); 1977 1978 /** @} */ 1979 1980 #ifdef __cplusplus 1981 } 1982 #endif 1983 1984 #endif /* #ifndef YAML_H */ 1985