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