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