contrib/libyaml/include/yaml.h

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