include/yaml.h

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