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  * The emitter structure.
1522  *
1523  * All members are internal.  Manage the structure using the @c yaml_emitter_
1524  * family of functions.
1525  */
1526
1527 typedef struct yaml_emitter_s {
1528
1529     /**
1530      * @name Error handling
1531      * @{
1532      */
1533
1534     /** Error type. */
1535     yaml_error_type_t error;
1536     /** Error description. */
1537     const char *problem;
1538
1539     /**
1540      * @}
1541      */
1542
1543     /**
1544      * @name Writer stuff
1545      * @{
1546      */
1547
1548     /** Write handler. */
1549     yaml_write_handler_t *write_handler;
1550
1551     /** A pointer for passing to the white handler. */
1552     void *write_handler_data;
1553
1554     /** Standard (string or file) output data. */
1555     union {
1556         /** String output data. */
1557         struct {
1558             /** The buffer pointer. */
1559             unsigned char *buffer;
1560             /** The buffer size. */
1561             size_t size;
1562             /** The number of written bytes. */
1563             size_t *size_written;
1564         } string;
1565
1566         /** File output data. */
1567         FILE *file;
1568     } output;
1569
1570     /** The working buffer. */
1571     struct {
1572         /** The beginning of the buffer. */
1573         yaml_char_t *start;
1574         /** The end of the buffer. */
1575         yaml_char_t *end;
1576         /** The current position of the buffer. */
1577         yaml_char_t *pointer;
1578         /** The last filled position of the buffer. */
1579         yaml_char_t *last;
1580     } buffer;
1581
1582     /** The raw buffer. */
1583     struct {
1584         /** The beginning of the buffer. */
1585         unsigned char *start;
1586         /** The end of the buffer. */
1587         unsigned char *end;
1588         /** The current position of the buffer. */
1589         unsigned char *pointer;
1590         /** The last filled position of the buffer. */
1591         unsigned char *last;
1592     } raw_buffer;
1593
1594     /** The stream encoding. */
1595     yaml_encoding_t encoding;
1596
1597     /**
1598      * @}
1599      */
1600
1601     /**
1602      * @name Emitter stuff
1603      * @{
1604      */
1605
1606     /** If the output is in the canonical style? */
1607     int canonical;
1608     /** The number of indentation spaces. */
1609     int best_indent;
1610     /** The preferred width of the output lines. */
1611     int best_width;
1612     /** Allow unescaped non-ASCII characters? */
1613     int unicode;
1614     /** The preferred line break. */
1615     yaml_break_t line_break;
1616
1617     /** The stack of states. */
1618     struct {
1619         /** The beginning of the stack. */
1620         yaml_emitter_state_t *start;
1621         /** The end of the stack. */
1622         yaml_emitter_state_t *end;
1623         /** The top of the stack. */
1624         yaml_emitter_state_t *top;
1625     } states;
1626
1627     /** The current emitter state. */
1628     yaml_emitter_state_t state;
1629
1630     /** The event queue. */
1631     struct {
1632         /** The beginning of the event queue. */
1633         yaml_event_t *start;
1634         /** The end of the event queue. */
1635         yaml_event_t *end;
1636         /** The head of the event queue. */
1637         yaml_event_t *head;
1638         /** The tail of the event queue. */
1639         yaml_event_t *tail;
1640     } events;
1641
1642     /** The stack of indentation levels. */
1643     struct {
1644         /** The beginning of the stack. */
1645         int *start;
1646         /** The end of the stack. */
1647         int *end;
1648         /** The top of the stack. */
1649         int *top;
1650     } indents;
1651
1652     /** The list of tag directives. */
1653     struct {
1654         /** The beginning of the list. */
1655         yaml_tag_directive_t *start;
1656         /** The end of the list. */
1657         yaml_tag_directive_t *end;
1658         /** The top of the list. */
1659         yaml_tag_directive_t *top;
1660     } tag_directives;
1661
1662     /** The current indentation level. */
1663     int indent;
1664
1665     /** The current flow level. */
1666     int flow_level;
1667
1668     /** Is it the document root context? */
1669     int root_context;
1670     /** Is it a sequence context? */
1671     int sequence_context;
1672     /** Is it a mapping context? */
1673     int mapping_context;
1674     /** Is it a simple mapping key context? */
1675     int simple_key_context;
1676
1677     /** The current line. */
1678     int line;
1679     /** The current column. */
1680     int column;
1681     /** If the last character was a whitespace? */
1682     int whitespace;
1683     /** If the last character was an indentation character (' ', '-', '?', ':')? */
1684     int indention;
1685     /** If an explicit document end is required? */
1686     int open_ended;
1687
1688     /** Anchor analysis. */
1689     struct {
1690         /** The anchor value. */
1691         yaml_char_t *anchor;
1692         /** The anchor length. */
1693         size_t anchor_length;
1694         /** Is it an alias? */
1695         int alias;
1696     } anchor_data;
1697
1698     /** Tag analysis. */
1699     struct {
1700         /** The tag handle. */
1701         yaml_char_t *handle;
1702         /** The tag handle length. */
1703         size_t handle_length;
1704         /** The tag suffix. */
1705         yaml_char_t *suffix;
1706         /** The tag suffix length. */
1707         size_t suffix_length;
1708     } tag_data;
1709
1710     /** Scalar analysis. */
1711     struct {
1712         /** The scalar value. */
1713         yaml_char_t *value;
1714         /** The scalar length. */
1715         size_t length;
1716         /** Does the scalar contain line breaks? */
1717         int multiline;
1718         /** Can the scalar be expessed in the flow plain style? */
1719         int flow_plain_allowed;
1720         /** Can the scalar be expressed in the block plain style? */
1721         int block_plain_allowed;
1722         /** Can the scalar be expressed in the single quoted style? */
1723         int single_quoted_allowed;
1724         /** Can the scalar be expressed in the literal or folded styles? */
1725         int block_allowed;
1726         /** The output style. */
1727         yaml_scalar_style_t style;
1728     } scalar_data;
1729
1730     /**
1731      * @}
1732      */
1733
1734     /**
1735      * @name Dumper stuff
1736      * @{
1737      */
1738
1739     /** If the stream was already opened? */
1740     int opened;
1741     /** If the stream was already closed? */
1742     int closed;
1743
1744     /** The information associated with the document nodes. */
1745     struct {
1746         /** The number of references. */
1747         int references;
1748         /** The anchor id. */
1749         int anchor;
1750         /** If the node has been emitted? */
1751         int serialized;
1752     } *anchors;
1753
1754     /** The last assigned anchor id. */
1755     int last_anchor_id;
1756
1757     /** The currently emitted document. */
1758     yaml_document_t *document;
1759
1760     /**
1761      * @}
1762      */
1763
1764 } yaml_emitter_t;
1765
1766 /**
1767  * Initialize an emitter.
1768  *
1769  * This function creates a new emitter object.  An application is responsible
1770  * for destroying the object using the yaml_emitter_delete() function.
1771  *
1772  * @param[out]      emitter     An empty parser object.
1773  *
1774  * @returns @c 1 if the function succeeded, @c 0 on error.
1775  */
1776
1777 YAML_DECLARE(int)
1778 yaml_emitter_initialize(yaml_emitter_t *emitter);
1779
1780 /**
1781  * Destroy an emitter.
1782  *
1783  * @param[in,out]   emitter     An emitter object.
1784  */
1785
1786 YAML_DECLARE(void)
1787 yaml_emitter_delete(yaml_emitter_t *emitter);
1788
1789 /**
1790  * Set a string output.
1791  *
1792  * The emitter will write the output characters to the @a output buffer of the
1793  * size @a size.  The emitter will set @a size_written to the number of written
1794  * bytes.  If the buffer is smaller than required, the emitter produces the
1795  * YAML_WRITE_ERROR error.
1796  *
1797  * @param[in,out]   emitter         An emitter object.
1798  * @param[in]       output          An output buffer.
1799  * @param[in]       size            The buffer size.
1800  * @param[in]       size_written    The pointer to save the number of written
1801  *                                  bytes.
1802  */
1803
1804 YAML_DECLARE(void)
1805 yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1806         unsigned char *output, size_t size, size_t *size_written);
1807
1808 /**
1809  * Set a file output.
1810  *
1811  * @a file should be a file object open for writing.  The application is
1812  * responsible for closing the @a file.
1813  *
1814  * @param[in,out]   emitter     An emitter object.
1815  * @param[in]       file        An open file.
1816  */
1817
1818 YAML_DECLARE(void)
1819 yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1820
1821 /**
1822  * Set a generic output handler.
1823  *
1824  * @param[in,out]   emitter     An emitter object.
1825  * @param[in]       handler     A write handler.
1826  * @param[in]       data        Any application data for passing to the write
1827  *                              handler.
1828  */
1829
1830 YAML_DECLARE(void)
1831 yaml_emitter_set_output(yaml_emitter_t *emitter,
1832         yaml_write_handler_t *handler, void *data);
1833
1834 /**
1835  * Set the output encoding.
1836  *
1837  * @param[in,out]   emitter     An emitter object.
1838  * @param[in]       encoding    The output encoding.
1839  */
1840
1841 YAML_DECLARE(void)
1842 yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1843
1844 /**
1845  * Set if the output should be in the "canonical" format as in the YAML
1846  * specification.
1847  *
1848  * @param[in,out]   emitter     An emitter object.
1849  * @param[in]       canonical   If the output is canonical.
1850  */
1851
1852 YAML_DECLARE(void)
1853 yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1854
1855 /**
1856  * Set the intendation increment.
1857  *
1858  * @param[in,out]   emitter     An emitter object.
1859  * @param[in]       indent      The indentation increment (1 < . < 10).
1860  */
1861
1862 YAML_DECLARE(void)
1863 yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1864
1865 /**
1866  * Set the preferred line width. @c -1 means unlimited.
1867  *
1868  * @param[in,out]   emitter     An emitter object.
1869  * @param[in]       width       The preferred line width.
1870  */
1871
1872 YAML_DECLARE(void)
1873 yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1874
1875 /**
1876  * Set if unescaped non-ASCII characters are allowed.
1877  *
1878  * @param[in,out]   emitter     An emitter object.
1879  * @param[in]       unicode     If unescaped Unicode characters are allowed.
1880  */
1881
1882 YAML_DECLARE(void)
1883 yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1884
1885 /**
1886  * Set the preferred line break.
1887  *
1888  * @param[in,out]   emitter     An emitter object.
1889  * @param[in]       line_break  The preferred line break.
1890  */
1891
1892 YAML_DECLARE(void)
1893 yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1894
1895 /**
1896  * Emit an event.
1897  *
1898  * The event object may be generated using the yaml_parser_parse() function.
1899  * The emitter takes the responsibility for the event object and destroys its
1900  * content after it is emitted. The event object is destroyed even if the
1901  * function fails.
1902  *
1903  * @param[in,out]   emitter     An emitter object.
1904  * @param[in,out]   event       An event object.
1905  *
1906  * @returns @c 1 if the function succeeded, @c 0 on error.
1907  */
1908
1909 YAML_DECLARE(int)
1910 yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
1911
1912 /**
1913  * Start a YAML stream.
1914  *
1915  * This function should be used before yaml_emitter_dump() is called.
1916  *
1917  * @param[in,out]   emitter     An emitter object.
1918  *
1919  * @returns @c 1 if the function succeeded, @c 0 on error.
1920  */
1921
1922 YAML_DECLARE(int)
1923 yaml_emitter_open(yaml_emitter_t *emitter);
1924
1925 /**
1926  * Finish a YAML stream.
1927  *
1928  * This function should be used after yaml_emitter_dump() is called.
1929  *
1930  * @param[in,out]   emitter     An emitter object.
1931  *
1932  * @returns @c 1 if the function succeeded, @c 0 on error.
1933  */
1934
1935 YAML_DECLARE(int)
1936 yaml_emitter_close(yaml_emitter_t *emitter);
1937
1938 /**
1939  * Emit a YAML document.
1940  *
1941  * The documen object may be generated using the yaml_parser_load() function
1942  * or the yaml_document_initialize() function.  The emitter takes the
1943  * responsibility for the document object and destroys its content after
1944  * it is emitted. The document object is destroyed even if the function fails.
1945  *
1946  * @param[in,out]   emitter     An emitter object.
1947  * @param[in,out]   document    A document object.
1948  *
1949  * @returns @c 1 if the function succeeded, @c 0 on error.
1950  */
1951
1952 YAML_DECLARE(int)
1953 yaml_emitter_dump(yaml_emitter_t *emitter, yaml_document_t *document);
1954
1955 /**
1956  * Flush the accumulated characters to the output.
1957  *
1958  * @param[in,out]   emitter     An emitter object.
1959  *
1960  * @returns @c 1 if the function succeeded, @c 0 on error.
1961  */
1962
1963 YAML_DECLARE(int)
1964 yaml_emitter_flush(yaml_emitter_t *emitter);
1965
1966 /** @} */
1967
1968 #ifdef __cplusplus
1969 }
1970 #endif
1971
1972 #endif /* #ifndef YAML_H */
1973