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