include/yaml.h

   1 /**
   2  * @file yaml.h
   3  * @brief Public interface for libyaml.
   4  *
   5  * Include the header file with the code:
   6  * @code
   7  * #include <yaml.h>
   8  * @endcode
   9  */
  10
  11 #ifndef YAML_H
  12 #define YAML_H
  13
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 #include <stdlib.h>
  19 #include <stdio.h>
  20 #include <string.h>
  21
  22 /**
  23  * @defgroup export Export Definitions
  24  * @{
  25  */
  26
  27 /** The public API declaration. */
  28
  29 #ifdef WIN32
  30 #   if defined(YAML_DECLARE_STATIC)
  31 #       define  YAML_DECLARE(type)  type
  32 #   elif defined(YAML_DECLARE_EXPORT)
  33 #       define  YAML_DECLARE(type)  __declspec(dllexport) type
  34 #   else
  35 #       define  YAML_DECLARE(type)  __declspec(dllimport) type
  36 #   endif
  37 #else
  38 #   define  YAML_DECLARE(type)  type
  39 #endif
  40
  41 /** @} */
  42
  43 /**
  44  * @defgroup version Version Information
  45  * @{
  46  */
  47
  48 /**
  49  * Get the library version as a string.
  50  *
  51  * @returns The function returns the pointer to a static string of the form
  52  * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version
  53  * number, and @c Z is the patch version number.
  54  */
  55
  56 YAML_DECLARE(const char *)
  57 yaml_get_version_string(void);
  58
  59 /**
  60  * Get the library version numbers.
  61  *
  62  * @param[out]  major   Major version number.
  63  * @param[out]  minor   Minor version number.
  64  * @param[out]  patch   Patch version number.
  65  */
  66
  67 YAML_DECLARE(void)
  68 yaml_get_version(int *major, int *minor, int *patch);
  69
  70 /** @} */
  71
  72 /**
  73  * @defgroup basic Basic Types
  74  * @{
  75  */
  76
  77 /** The character type (UTF-8 octet). */
  78 typedef unsigned char yaml_char_t;
  79
  80 /** The version directive data. */
  81 typedef struct {
  82     /** The major version number. */
  83     int major;
  84     /** The minor version number. */
  85     int minor;
  86 } yaml_version_directive_t;
  87
  88 /** The tag directive data. */
  89 typedef struct {
  90     /** The tag handle. */
  91     yaml_char_t *handle;
  92     /** The tag prefix. */
  93     yaml_char_t *prefix;
  94 } yaml_tag_directive_t;
  95
  96 /** The stream encoding. */
  97 typedef enum {
  98     YAML_ANY_ENCODING,
  99     YAML_UTF8_ENCODING,
 100     YAML_UTF16LE_ENCODING,
 101     YAML_UTF16BE_ENCODING
 102 } yaml_encoding_t;
 103
 104 /** Line break types. */
 105
 106 typedef enum {
 107     YAML_ANY_BREAK,
 108     YAML_CR_BREAK,
 109     YAML_LN_BREAK,
 110     YAML_CRLN_BREAK
 111 } yaml_break_t;
 112
 113 /** Many bad things could happen with the parser and emitter. */
 114 typedef enum {
 115     YAML_NO_ERROR,
 116
 117     YAML_MEMORY_ERROR,
 118
 119     YAML_READER_ERROR,
 120     YAML_SCANNER_ERROR,
 121     YAML_PARSER_ERROR,
 122
 123     YAML_WRITER_ERROR,
 124     YAML_EMITTER_ERROR
 125 } yaml_error_type_t;
 126
 127 /** The pointer position. */
 128 typedef struct {
 129     /** The position index. */
 130     size_t index;
 131
 132     /** The position line. */
 133     size_t line;
 134
 135     /** The position column. */
 136     size_t column;
 137 } yaml_mark_t;
 138
 139 /** @} */
 140
 141 /**
 142  * @defgroup styles Node Styles
 143  * @{
 144  */
 145
 146 /** Scalar styles. */
 147 typedef enum {
 148     YAML_ANY_SCALAR_STYLE,
 149
 150     YAML_PLAIN_SCALAR_STYLE,
 151
 152     YAML_SINGLE_QUOTED_SCALAR_STYLE,
 153     YAML_DOUBLE_QUOTED_SCALAR_STYLE,
 154
 155     YAML_LITERAL_SCALAR_STYLE,
 156     YAML_FOLDED_SCALAR_STYLE
 157 } yaml_scalar_style_t;
 158
 159 /** Sequence styles. */
 160 typedef enum {
 161     YAML_ANY_SEQUENCE_STYLE,
 162
 163     YAML_BLOCK_SEQUENCE_STYLE,
 164     YAML_FLOW_SEQUENCE_STYLE
 165 } yaml_sequence_style_t;
 166
 167 /** Mapping styles. */
 168 typedef enum {
 169     YAML_ANY_MAPPING_STYLE,
 170
 171     YAML_BLOCK_MAPPING_STYLE,
 172     YAML_FLOW_MAPPING_STYLE
 173 /*    YAML_FLOW_SET_MAPPING_STYLE   */
 174 } yaml_mapping_style_t;
 175
 176 /** @} */
 177
 178 /**
 179  * @defgroup tokens Tokens
 180  * @{
 181  */
 182
 183 /** Token types. */
 184 typedef enum {
 185     YAML_NO_TOKEN,
 186
 187     YAML_STREAM_START_TOKEN,
 188     YAML_STREAM_END_TOKEN,
 189
 190     YAML_VERSION_DIRECTIVE_TOKEN,
 191     YAML_TAG_DIRECTIVE_TOKEN,
 192     YAML_DOCUMENT_START_TOKEN,
 193     YAML_DOCUMENT_END_TOKEN,
 194
 195     YAML_BLOCK_SEQUENCE_START_TOKEN,
 196     YAML_BLOCK_MAPPING_START_TOKEN,
 197     YAML_BLOCK_END_TOKEN,
 198
 199     YAML_FLOW_SEQUENCE_START_TOKEN,
 200     YAML_FLOW_SEQUENCE_END_TOKEN,
 201     YAML_FLOW_MAPPING_START_TOKEN,
 202     YAML_FLOW_MAPPING_END_TOKEN,
 203
 204     YAML_BLOCK_ENTRY_TOKEN,
 205     YAML_FLOW_ENTRY_TOKEN,
 206     YAML_KEY_TOKEN,
 207     YAML_VALUE_TOKEN,
 208
 209     YAML_ALIAS_TOKEN,
 210     YAML_ANCHOR_TOKEN,
 211     YAML_TAG_TOKEN,
 212     YAML_SCALAR_TOKEN
 213 } yaml_token_type_t;
 214
 215 /** The token structure. */
 216 typedef struct {
 217
 218     /** The token type. */
 219     yaml_token_type_t type;
 220
 221     /** The token data. */
 222     union {
 223
 224         /** The stream start (for @c YAML_STREAM_START_TOKEN). */
 225         struct {
 226             /** The stream encoding. */
 227             yaml_encoding_t encoding;
 228         } stream_start;
 229
 230         /** The alias (for @c YAML_ALIAS_TOKEN). */
 231         struct {
 232             /** The alias value. */
 233             yaml_char_t *value;
 234         } alias;
 235
 236         /** The anchor (for @c YAML_ANCHOR_TOKEN). */
 237         struct {
 238             /** The anchor value. */
 239             yaml_char_t *value;
 240         } anchor;
 241
 242         /** The tag (for @c YAML_TAG_TOKEN). */
 243         struct {
 244             /** The tag handle. */
 245             yaml_char_t *handle;
 246             /** The tag suffix. */
 247             yaml_char_t *suffix;
 248         } tag;
 249
 250         /** The scalar value (for @c YAML_SCALAR_TOKEN). */
 251         struct {
 252             /** The scalar value. */
 253             yaml_char_t *value;
 254             /** The length of the scalar value. */
 255             size_t length;
 256             /** The scalar style. */
 257             yaml_scalar_style_t style;
 258         } scalar;
 259
 260         /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
 261         struct {
 262             /** The major version number. */
 263             int major;
 264             /** The minor version number. */
 265             int minor;
 266         } version_directive;
 267
 268         /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
 269         struct {
 270             /** The tag handle. */
 271             yaml_char_t *handle;
 272             /** The tag prefix. */
 273             yaml_char_t *prefix;
 274         } tag_directive;
 275
 276     } data;
 277
 278     /** The beginning of the token. */
 279     yaml_mark_t start_mark;
 280     /** The end of the token. */
 281     yaml_mark_t end_mark;
 282
 283 } yaml_token_t;
 284
 285 /**
 286  * Free any memory allocated for a token object.
 287  *
 288  * @param[in,out]   token   A token object.
 289  */
 290
 291 YAML_DECLARE(void)
 292 yaml_token_delete(yaml_token_t *token);
 293
 294 /** @} */
 295
 296 /**
 297  * @defgroup events Events
 298  * @{
 299  */
 300
 301 /** Event types. */
 302 typedef enum {
 303     YAML_NO_EVENT,
 304
 305     YAML_STREAM_START_EVENT,
 306     YAML_STREAM_END_EVENT,
 307
 308     YAML_DOCUMENT_START_EVENT,
 309     YAML_DOCUMENT_END_EVENT,
 310
 311     YAML_ALIAS_EVENT,
 312     YAML_SCALAR_EVENT,
 313
 314     YAML_SEQUENCE_START_EVENT,
 315     YAML_SEQUENCE_END_EVENT,
 316
 317     YAML_MAPPING_START_EVENT,
 318     YAML_MAPPING_END_EVENT
 319 } yaml_event_type_t;
 320
 321 /** The event structure. */
 322 typedef struct {
 323
 324     /** The event type. */
 325     yaml_event_type_t type;
 326
 327     /** The event data. */
 328     union {
 329
 330         /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
 331         struct {
 332             /** The document encoding. */
 333             yaml_encoding_t encoding;
 334         } stream_start;
 335
 336         /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
 337         struct {
 338             /** The version directive. */
 339             yaml_version_directive_t *version_directive;
 340
 341             /** The list of tag directives. */
 342             struct {
 343                 /** The beginning of the tag directives list. */
 344                 yaml_tag_directive_t *start;
 345                 /** The end of the tag directives list. */
 346                 yaml_tag_directive_t *end;
 347             } tag_directives;
 348
 349             /** Is the document indicator implicit? */
 350             int implicit;
 351         } document_start;
 352
 353         /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
 354         struct {
 355             /** Is the document end indicator implicit? */
 356             int implicit;
 357         } document_end;
 358
 359         /** The alias parameters (for @c YAML_ALIAS_EVENT). */
 360         struct {
 361             /** The anchor. */
 362             yaml_char_t *anchor;
 363         } alias;
 364
 365         /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
 366         struct {
 367             /** The anchor. */
 368             yaml_char_t *anchor;
 369             /** The tag. */
 370             yaml_char_t *tag;
 371             /** The scalar value. */
 372             yaml_char_t *value;
 373             /** The length of the scalar value. */
 374             size_t length;
 375             /** Is the tag optional for the plain style? */
 376             int plain_implicit;
 377             /** Is the tag optional for any non-plain style? */
 378             int quoted_implicit;
 379             /** The scalar style. */
 380             yaml_scalar_style_t style;
 381         } scalar;
 382
 383         /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
 384         struct {
 385             /** The anchor. */
 386             yaml_char_t *anchor;
 387             /** The tag. */
 388             yaml_char_t *tag;
 389             /** Is the tag optional? */
 390             int implicit;
 391             /** The sequence style. */
 392             yaml_sequence_style_t style;
 393         } sequence_start;
 394
 395         /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
 396         struct {
 397             /** The anchor. */
 398             yaml_char_t *anchor;
 399             /** The tag. */
 400             yaml_char_t *tag;
 401             /** Is the tag optional? */
 402             int implicit;
 403             /** The mapping style. */
 404             yaml_mapping_style_t style;
 405         } mapping_start;
 406
 407     } data;
 408
 409     /** The beginning of the token. */
 410     yaml_mark_t start_mark;
 411     /** The end of the token. */
 412     yaml_mark_t end_mark;
 413
 414 } yaml_event_t;
 415
 416 /**
 417  * Create the STREAM-START event.
 418  *
 419  * @param[out]  event       An empty event object.
 420  * @param[in]   encoding    The stream encoding.
 421  *
 422  * @returns @c 1 if the function succeeded, @c 0 on error.
 423  */
 424
 425 YAML_DECLARE(int)
 426 yaml_stream_start_event_initialize(yaml_event_t *event,
 427         yaml_encoding_t encoding);
 428
 429 /**
 430  * Create the STREAM-END event.
 431  *
 432  * @param[out]  event       An empty event object.
 433  *
 434  * @returns @c 1 if the function succeeded, @c 0 on error.
 435  */
 436
 437 YAML_DECLARE(int)
 438 yaml_stream_end_event_initialize(yaml_event_t *event);
 439
 440 /**
 441  * Create the DOCUMENT-START event.
 442  *
 443  * The @a implicit argument is considered as a stylistic parameter and may be
 444  * ignored by the emitter.
 445  *
 446  * @param[out]  event                   An empty event object.
 447  * @param[in]   version_directive       The %YAML directive value or @c NULL.
 448  * @param[in]   tag_directives_start    The beginning of the %TAG directives list.
 449  * @param[in]   tag_directives_end      The end of the %TAG directives list.
 450  * @param[in]   implicit                If the document start indicator is implicit.
 451  *
 452  * @returns @c 1 if the function succeeded, @c 0 on error.
 453  */
 454
 455 YAML_DECLARE(int)
 456 yaml_document_start_event_initialize(yaml_event_t *event,
 457         yaml_version_directive_t *version_directive,
 458         yaml_tag_directive_t *tag_directives_start,
 459         yaml_tag_directive_t *tag_directives_end,
 460         int implicit);
 461
 462 /**
 463  * Create the DOCUMENT-END event.
 464  *
 465  * The @a implicit argument is considered as a stylistic parameter and may be
 466  * ignored by the emitter.
 467  *
 468  * @param[out]  event       An empty event object.
 469  * @param[in]   implicit    If the document end indicator is implicit.
 470  *
 471  * @returns @c 1 if the function succeeded, @c 0 on error.
 472  */
 473
 474 YAML_DECLARE(int)
 475 yaml_document_end_event_initialize(yaml_event_t *event, int implicit);
 476
 477 /**
 478  * Create an ALIAS event.
 479  *
 480  * @param[out]  event       An empty event object.
 481  * @param[in]   anchor      The anchor value.
 482  *
 483  * @returns @c 1 if the function succeeded, @c 0 on error.
 484  */
 485
 486 YAML_DECLARE(int)
 487 yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor);
 488
 489 /**
 490  * Create a SCALAR event.
 491  *
 492  * The @a style argument may be ignored by the emitter.
 493  *
 494  * Either the @a tag attribute or one of the @a plain_implicit and
 495  * @a quoted_implicit flags must be set.
 496  *
 497  * @param[out]  event           An empty event object.
 498  * @param[in]   anchor          The scalar anchor or @c NULL.
 499  * @param[in]   tag             The scalar tag or @c NULL.
 500  * @param[in]   value           The scalar value.
 501  * @param[in]   length          The length of the scalar value.
 502  * @param[in]   plain_implicit  If the tag may be omitted for the plain style.
 503  * @param[in]   quoted_implicit If the tag may be omitted for any non-plain style.
 504  * @param[in]   style           The scalar style.
 505  *
 506  * @returns @c 1 if the function succeeded, @c 0 on error.
 507  */
 508
 509 YAML_DECLARE(int)
 510 yaml_scalar_event_initialize(yaml_event_t *event,
 511         yaml_char_t *anchor, yaml_char_t *tag,
 512         yaml_char_t *value, int length,
 513         int plain_implicit, int quoted_implicit,
 514         yaml_scalar_style_t style);
 515
 516 /**
 517  * Create a SEQUENCE-START event.
 518  *
 519  * The @a style argument may be ignored by the emitter.
 520  *
 521  * Either the @a tag attribute or the @a implicit flag must be set.
 522  *
 523  * @param[out]  event       An empty event object.
 524  * @param[in]   anchor      The sequence anchor or @c NULL.
 525  * @param[in]   tag         The sequence tag or @c NULL.
 526  * @param[in]   implicit    If the tag may be omitted.
 527  * @param[in]   style       The sequence style.
 528  *
 529  * @returns @c 1 if the function succeeded, @c 0 on error.
 530  */
 531
 532 YAML_DECLARE(int)
 533 yaml_sequence_start_event_initialize(yaml_event_t *event,
 534         yaml_char_t *anchor, yaml_char_t *tag, int implicit,
 535         yaml_sequence_style_t style);
 536
 537 /**
 538  * Create a SEQUENCE-END event.
 539  *
 540  * @param[out]  event       An empty event object.
 541  *
 542  * @returns @c 1 if the function succeeded, @c 0 on error.
 543  */
 544
 545 YAML_DECLARE(int)
 546 yaml_sequence_end_event_initialize(yaml_event_t *event);
 547
 548 /**
 549  * Create a MAPPING-START event.
 550  *
 551  * The @a style argument may be ignored by the emitter.
 552  *
 553  * Either the @a tag attribute or the @a implicit flag must be set.
 554  *
 555  * @param[out]  event       An empty event object.
 556  * @param[in]   anchor      The mapping anchor or @c NULL.
 557  * @param[in]   tag         The mapping tag or @c NULL.
 558  * @param[in]   implicit    If the tag may be omitted.
 559  * @param[in]   style       The mapping style.
 560  *
 561  * @returns @c 1 if the function succeeded, @c 0 on error.
 562  */
 563
 564 YAML_DECLARE(int)
 565 yaml_mapping_start_event_initialize(yaml_event_t *event,
 566         yaml_char_t *anchor, yaml_char_t *tag, int implicit,
 567         yaml_mapping_style_t style);
 568
 569 /**
 570  * Create a MAPPING-END event.
 571  *
 572  * @param[out]  event       An empty event object.
 573  *
 574  * @returns @c 1 if the function succeeded, @c 0 on error.
 575  */
 576
 577 YAML_DECLARE(int)
 578 yaml_mapping_end_event_initialize(yaml_event_t *event);
 579
 580 /**
 581  * Free any memory allocated for an event object.
 582  *
 583  * @param[out]  event   An event object.
 584  */
 585
 586 YAML_DECLARE(void)
 587 yaml_event_delete(yaml_event_t *event);
 588
 589 /** @} */
 590
 591 /**
 592  * @defgroup parser Parser Definitions
 593  * @{
 594  */
 595
 596 /**
 597  * The prototype of a read handler.
 598  *
 599  * The read handler is called when the parser needs to read more bytes from the
 600  * source.  The handler should write not more than @a size bytes to the @a
 601  * buffer.  The number of written bytes should be set to the @a length variable.
 602  *
 603  * @param[in,out]   data        A pointer to an application data specified by
 604  *                              yaml_parser_set_input().
 605  * @param[out]      buffer      The buffer to write the data from the source.
 606  * @param[in]       size        The size of the buffer.
 607  * @param[out]      size_read   The actual number of bytes read from the source.
 608  *
 609  * @returns On success, the handler should return @c 1.  If the handler failed,
 610  * the returned value should be @c 0.  On EOF, the handler should set the
 611  * @a size_read to @c 0 and return @c 1.
 612  */
 613
 614 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
 615         size_t *size_read);
 616
 617 /**
 618  * This structure holds information about a potential simple key.
 619  */
 620
 621 typedef struct {
 622     /** Is a simple key possible? */
 623     int possible;
 624
 625     /** Is a simple key required? */
 626     int required;
 627
 628     /** The number of the token. */
 629     size_t token_number;
 630
 631     /** The position mark. */
 632     yaml_mark_t mark;
 633 } yaml_simple_key_t;
 634
 635 /**
 636  * The states of the parser.
 637  */
 638 typedef enum {
 639     YAML_PARSE_STREAM_START_STATE,
 640     YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
 641     YAML_PARSE_DOCUMENT_START_STATE,
 642     YAML_PARSE_DOCUMENT_CONTENT_STATE,
 643     YAML_PARSE_DOCUMENT_END_STATE,
 644     YAML_PARSE_BLOCK_NODE_STATE,
 645     YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
 646     YAML_PARSE_FLOW_NODE_STATE,
 647     YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
 648     YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
 649     YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
 650     YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
 651     YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
 652     YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
 653     YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
 654     YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
 655     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
 656     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
 657     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
 658     YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
 659     YAML_PARSE_FLOW_MAPPING_KEY_STATE,
 660     YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
 661     YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
 662     YAML_PARSE_END_STATE
 663 } yaml_parser_state_t;
 664
 665 /**
 666  * The parser structure.
 667  *
 668  * All members are internal.  Manage the structure using the @c yaml_parser_
 669  * family of functions.
 670  */
 671
 672 typedef struct {
 673
 674     /**
 675      * @name Error handling
 676      * @{
 677      */
 678
 679     /** Error type. */
 680     yaml_error_type_t error;
 681     /** Error description. */
 682     const char *problem;
 683     /** The byte about which the problem occured. */
 684     size_t problem_offset;
 685     /** The problematic value (@c -1 is none). */
 686     int problem_value;
 687     /** The problem position. */
 688     yaml_mark_t problem_mark;
 689     /** The error context. */
 690     const char *context;
 691     /** The context position. */
 692     yaml_mark_t context_mark;
 693
 694     /**
 695      * @}
 696      */
 697
 698     /**
 699      * @name Reader stuff
 700      * @{
 701      */
 702
 703     /** Read handler. */
 704     yaml_read_handler_t *read_handler;
 705
 706     /** A pointer for passing to the read handler. */
 707     void *read_handler_data;
 708
 709     /** Standard (string or file) input data. */
 710     union {
 711         /** String input data. */
 712         struct {
 713             /** The string start pointer. */
 714             unsigned char *start;
 715             /** The string end pointer. */
 716             unsigned char *end;
 717             /** The string current position. */
 718             unsigned char *current;
 719         } string;
 720
 721         /** File input data. */
 722         FILE *file;
 723     } input;
 724
 725     /** EOF flag */
 726     int eof;
 727
 728     /** The working buffer. */
 729     struct {
 730         /** The beginning of the buffer. */
 731         yaml_char_t *start;
 732         /** The end of the buffer. */
 733         yaml_char_t *end;
 734         /** The current position of the buffer. */
 735         yaml_char_t *pointer;
 736         /** The last filled position of the buffer. */
 737         yaml_char_t *last;
 738     } buffer;
 739
 740     /* The number of unread characters in the buffer. */
 741     size_t unread;
 742
 743     /** The raw buffer. */
 744     struct {
 745         /** The beginning of the buffer. */
 746         unsigned char *start;
 747         /** The end of the buffer. */
 748         unsigned char *end;
 749         /** The current position of the buffer. */
 750         unsigned char *pointer;
 751         /** The last filled position of the buffer. */
 752         unsigned char *last;
 753     } raw_buffer;
 754
 755     /** The input encoding. */
 756     yaml_encoding_t encoding;
 757
 758     /** The offset of the current position (in bytes). */
 759     size_t offset;
 760
 761     /** The mark of the current position. */
 762     yaml_mark_t mark;
 763
 764     /**
 765      * @}
 766      */
 767
 768     /**
 769      * @name Scanner stuff
 770      * @{
 771      */
 772
 773     /** Have we started to scan the input stream? */
 774     int stream_start_produced;
 775
 776     /** Have we reached the end of the input stream? */
 777     int stream_end_produced;
 778
 779     /** The number of unclosed '[' and '{' indicators. */
 780     int flow_level;
 781
 782     /** The tokens queue. */
 783     struct {
 784         /** The beginning of the tokens queue. */
 785         yaml_token_t *start;
 786         /** The end of the tokens queue. */
 787         yaml_token_t *end;
 788         /** The head of the tokens queue. */
 789         yaml_token_t *head;
 790         /** The tail of the tokens queue. */
 791         yaml_token_t *tail;
 792     } tokens;
 793
 794     /** The number of tokens fetched from the queue. */
 795     size_t tokens_parsed;
 796
 797     /* Does the tokens queue contain a token ready for dequeueing. */
 798     int token_available;
 799
 800     /** The indentation levels stack. */
 801     struct {
 802         /** The beginning of the stack. */
 803         int *start;
 804         /** The end of the stack. */
 805         int *end;
 806         /** The top of the stack. */
 807         int *top;
 808     } indents;
 809
 810     /** The current indentation level. */
 811     int indent;
 812
 813     /** May a simple key occur at the current position? */
 814     int simple_key_allowed;
 815
 816     /** The stack of simple keys. */
 817     struct {
 818         /** The beginning of the stack. */
 819         yaml_simple_key_t *start;
 820         /** The end of the stack. */
 821         yaml_simple_key_t *end;
 822         /** The top of the stack. */
 823         yaml_simple_key_t *top;
 824     } simple_keys;
 825
 826     /**
 827      * @}
 828      */
 829
 830     /**
 831      * @name Parser stuff
 832      * @{
 833      */
 834
 835     /** The parser states stack. */
 836     struct {
 837         /** The beginning of the stack. */
 838         yaml_parser_state_t *start;
 839         /** The end of the stack. */
 840         yaml_parser_state_t *end;
 841         /** The top of the stack. */
 842         yaml_parser_state_t *top;
 843     } states;
 844
 845     /** The current parser state. */
 846     yaml_parser_state_t state;
 847
 848     /** The stack of marks. */
 849     struct {
 850         /** The beginning of the stack. */
 851         yaml_mark_t *start;
 852         /** The end of the stack. */
 853         yaml_mark_t *end;
 854         /** The top of the stack. */
 855         yaml_mark_t *top;
 856     } marks;
 857
 858     /** The list of TAG directives. */
 859     struct {
 860         /** The beginning of the list. */
 861         yaml_tag_directive_t *start;
 862         /** The end of the list. */
 863         yaml_tag_directive_t *end;
 864         /** The top of the list. */
 865         yaml_tag_directive_t *top;
 866     } tag_directives;
 867
 868     /**
 869      * @}
 870      */
 871
 872 } yaml_parser_t;
 873
 874 /**
 875  * Initialize a parser.
 876  *
 877  * This function creates a new parser object.  An application is responsible
 878  * for destroying the object using the yaml_parser_delete() function.
 879  *
 880  * @param[out]  parser  An empty parser object.
 881  *
 882  * @returns @c 1 if the function succeeded, @c 0 on error.
 883  */
 884
 885 YAML_DECLARE(int)
 886 yaml_parser_initialize(yaml_parser_t *parser);
 887
 888 /**
 889  * Destroy a parser.
 890  *
 891  * @param[in,out]   parser  A parser object.
 892  */
 893
 894 YAML_DECLARE(void)
 895 yaml_parser_delete(yaml_parser_t *parser);
 896
 897 /**
 898  * Set a string input.
 899  *
 900  * Note that the @a input pointer must be valid while the @a parser object
 901  * exists.  The application is responsible for destroing @a input after
 902  * destroying the @a parser.
 903  *
 904  * @param[in,out]   parser  A parser object.
 905  * @param[in]       input   A source data.
 906  * @param[in]       size    The length of the source data in bytes.
 907  */
 908
 909 YAML_DECLARE(void)
 910 yaml_parser_set_input_string(yaml_parser_t *parser,
 911         unsigned char *input, size_t size);
 912
 913 /**
 914  * Set a file input.
 915  *
 916  * @a file should be a file object open for reading.  The application is
 917  * responsible for closing the @a file.
 918  *
 919  * @param[in,out]   parser  A parser object.
 920  * @param[in]       file    An open file.
 921  */
 922
 923 YAML_DECLARE(void)
 924 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
 925
 926 /**
 927  * Set a generic input handler.
 928  *
 929  * @param[in,out]   parser  A parser object.
 930  * @param[in]       handler A read handler.
 931  * @param[in]       data    Any application data for passing to the read
 932  *                          handler.
 933  */
 934
 935 YAML_DECLARE(void)
 936 yaml_parser_set_input(yaml_parser_t *parser,
 937         yaml_read_handler_t *handler, void *data);
 938
 939 /**
 940  * Set the source encoding.
 941  *
 942  * @param[in,out]   parser      A parser object.
 943  * @param[in]       encoding    The source encoding.
 944  */
 945
 946 YAML_DECLARE(void)
 947 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
 948
 949 /**
 950  * Scan the input stream and produce the next token.
 951  *
 952  * Call the function subsequently to produce a sequence of tokens corresponding
 953  * to the input stream.  The initial token has the type
 954  * @c YAML_STREAM_START_TOKEN while the ending token has the type
 955  * @c YAML_STREAM_END_TOKEN.
 956  *
 957  * An application is responsible for freeing any buffers associated with the
 958  * produced token object using the @c yaml_token_delete function.
 959  *
 960  * An application must not alternate the calls of yaml_parser_scan() with the
 961  * calls of yaml_parser_parse(). Doing this will break the parser.
 962  *
 963  * @param[in,out]   parser      A parser object.
 964  * @param[out]      token       An empty token object.
 965  *
 966  * @returns @c 1 if the function succeeded, @c 0 on error.
 967  */
 968
 969 YAML_DECLARE(int)
 970 yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
 971
 972 /**
 973  * Parse the input stream and produce the next parsing event.
 974  *
 975  * Call the function subsequently to produce a sequence of events corresponding
 976  * to the input stream.  The initial event has the type
 977  * @c YAML_STREAM_START_EVENT while the ending event has the type
 978  * @c YAML_STREAM_END_EVENT.
 979  *
 980  * An application is responsible for freeing any buffers associated with the
 981  * produced event object using the yaml_event_delete() function.
 982  *
 983  * An application must not alternate the calls of yaml_parser_scan() with the
 984  * calls of yaml_parser_parse(). Doing this will break the parser.
 985  *
 986  * @param[in,out]   parser      A parser object.
 987  * @param[out]      event       An empty event object.
 988  *
 989  * @returns @c 1 if the function succeeded, @c 0 on error.
 990  */
 991
 992 YAML_DECLARE(int)
 993 yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
 994
 995 /** @} */
 996
 997 /**
 998  * @defgroup emitter Emitter Definitions
 999  * @{
1000  */
1001
1002 /**
1003  * The prototype of a write handler.
1004  *
1005  * The write handler is called when the emitter needs to flush the accumulated
1006  * characters to the output.  The handler should write @a size bytes of the
1007  * @a buffer to the output.
1008  *
1009  * @param[in,out]   data        A pointer to an application data specified by
1010  *                              yaml_emitter_set_output().
1011  * @param[in]       buffer      The buffer with bytes to be written.
1012  * @param[in]       size        The size of the buffer.
1013  *
1014  * @returns On success, the handler should return @c 1.  If the handler failed,
1015  * the returned value should be @c 0.
1016  */
1017
1018 typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size);
1019
1020 /** The emitter states. */
1021 typedef enum {
1022     YAML_EMIT_STREAM_START_STATE,
1023     YAML_EMIT_FIRST_DOCUMENT_START_STATE,
1024     YAML_EMIT_DOCUMENT_START_STATE,
1025     YAML_EMIT_DOCUMENT_CONTENT_STATE,
1026     YAML_EMIT_DOCUMENT_END_STATE,
1027     YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
1028     YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
1029     YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
1030     YAML_EMIT_FLOW_MAPPING_KEY_STATE,
1031     YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
1032     YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
1033     YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
1034     YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
1035     YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
1036     YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
1037     YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
1038     YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
1039     YAML_EMIT_END_STATE
1040 } yaml_emitter_state_t;
1041
1042 /**
1043  * The emitter structure.
1044  *
1045  * All members are internal.  Manage the structure using the @c yaml_emitter_
1046  * family of functions.
1047  */
1048
1049 typedef struct {
1050
1051     /**
1052      * @name Error handling
1053      * @{
1054      */
1055
1056     /** Error type. */
1057     yaml_error_type_t error;
1058     /** Error description. */
1059     const char *problem;
1060
1061     /**
1062      * @}
1063      */
1064
1065     /**
1066      * @name Writer stuff
1067      * @{
1068      */
1069
1070     /** Write handler. */
1071     yaml_write_handler_t *write_handler;
1072
1073     /** A pointer for passing to the white handler. */
1074     void *write_handler_data;
1075
1076     /** Standard (string or file) output data. */
1077     union {
1078         /** String output data. */
1079         struct {
1080             /** The buffer pointer. */
1081             unsigned char *buffer;
1082             /** The buffer size. */
1083             size_t size;
1084             /** The number of written bytes. */
1085             size_t *size_written;
1086         } string;
1087
1088         /** File output data. */
1089         FILE *file;
1090     } output;
1091
1092     /** The working buffer. */
1093     struct {
1094         /** The beginning of the buffer. */
1095         yaml_char_t *start;
1096         /** The end of the buffer. */
1097         yaml_char_t *end;
1098         /** The current position of the buffer. */
1099         yaml_char_t *pointer;
1100         /** The last filled position of the buffer. */
1101         yaml_char_t *last;
1102     } buffer;
1103
1104     /** The raw buffer. */
1105     struct {
1106         /** The beginning of the buffer. */
1107         unsigned char *start;
1108         /** The end of the buffer. */
1109         unsigned char *end;
1110         /** The current position of the buffer. */
1111         unsigned char *pointer;
1112         /** The last filled position of the buffer. */
1113         unsigned char *last;
1114     } raw_buffer;
1115
1116     /** The stream encoding. */
1117     yaml_encoding_t encoding;
1118
1119     /**
1120      * @}
1121      */
1122
1123     /**
1124      * @name Emitter stuff
1125      * @{
1126      */
1127
1128     /** If the output is in the canonical style? */
1129     int canonical;
1130     /** The number of indentation spaces. */
1131     int best_indent;
1132     /** The preferred width of the output lines. */
1133     int best_width;
1134     /** Allow unescaped non-ASCII characters? */
1135     int unicode;
1136     /** The preferred line break. */
1137     yaml_break_t line_break;
1138
1139     /** The stack of states. */
1140     struct {
1141         /** The beginning of the stack. */
1142         yaml_emitter_state_t *start;
1143         /** The end of the stack. */
1144         yaml_emitter_state_t *end;
1145         /** The top of the stack. */
1146         yaml_emitter_state_t *top;
1147     } states;
1148
1149     /** The current emitter state. */
1150     yaml_emitter_state_t state;
1151
1152     /** The event queue. */
1153     struct {
1154         /** The beginning of the event queue. */
1155         yaml_event_t *start;
1156         /** The end of the event queue. */
1157         yaml_event_t *end;
1158         /** The head of the event queue. */
1159         yaml_event_t *head;
1160         /** The tail of the event queue. */
1161         yaml_event_t *tail;
1162     } events;
1163
1164     /** The stack of indentation levels. */
1165     struct {
1166         /** The beginning of the stack. */
1167         int *start;
1168         /** The end of the stack. */
1169         int *end;
1170         /** The top of the stack. */
1171         int *top;
1172     } indents;
1173
1174     /** The list of tag directives. */
1175     struct {
1176         /** The beginning of the list. */
1177         yaml_tag_directive_t *start;
1178         /** The end of the list. */
1179         yaml_tag_directive_t *end;
1180         /** The top of the list. */
1181         yaml_tag_directive_t *top;
1182     } tag_directives;
1183
1184     /** The current indentation level. */
1185     int indent;
1186
1187     /** The current flow level. */
1188     int flow_level;
1189
1190     /** Is it the document root context? */
1191     int root_context;
1192     /** Is it a sequence context? */
1193     int sequence_context;
1194     /** Is it a mapping context? */
1195     int mapping_context;
1196     /** Is it a simple mapping key context? */
1197     int simple_key_context;
1198
1199     /** The current line. */
1200     int line;
1201     /** The current column. */
1202     int column;
1203     /** If the last character was a whitespace? */
1204     int whitespace;
1205     /** If the last character was an indentation character (' ', '-', '?', ':')? */
1206     int indention;
1207
1208     /** Anchor analysis. */
1209     struct {
1210         /** The anchor value. */
1211         yaml_char_t *anchor;
1212         /** The anchor length. */
1213         size_t anchor_length;
1214         /** Is it an alias? */
1215         int alias;
1216     } anchor_data;
1217
1218     /** Tag analysis. */
1219     struct {
1220         /** The tag handle. */
1221         yaml_char_t *handle;
1222         /** The tag handle length. */
1223         size_t handle_length;
1224         /** The tag suffix. */
1225         yaml_char_t *suffix;
1226         /** The tag suffix length. */
1227         size_t suffix_length;
1228     } tag_data;
1229
1230     /** Scalar analysis. */
1231     struct {
1232         /** The scalar value. */
1233         yaml_char_t *value;
1234         /** The scalar length. */
1235         size_t length;
1236         /** Does the scalar contain line breaks? */
1237         int multiline;
1238         /** Can the scalar be expessed in the flow plain style? */
1239         int flow_plain_allowed;
1240         /** Can the scalar be expressed in the block plain style? */
1241         int block_plain_allowed;
1242         /** Can the scalar be expressed in the single quoted style? */
1243         int single_quoted_allowed;
1244         /** Can the scalar be expressed in the literal or folded styles? */
1245         int block_allowed;
1246         /** The output style. */
1247         yaml_scalar_style_t style;
1248     } scalar_data;
1249
1250     /**
1251      * @}
1252      */
1253
1254 } yaml_emitter_t;
1255
1256 /**
1257  * Initialize an emitter.
1258  *
1259  * This function creates a new emitter object.  An application is responsible
1260  * for destroying the object using the yaml_emitter_delete() function.
1261  *
1262  * @param[out]      emitter     An empty parser object.
1263  *
1264  * @returns @c 1 if the function succeeded, @c 0 on error.
1265  */
1266
1267 YAML_DECLARE(int)
1268 yaml_emitter_initialize(yaml_emitter_t *emitter);
1269
1270 /**
1271  * Destroy an emitter.
1272  *
1273  * @param[in,out]   emitter     An emitter object.
1274  */
1275
1276 YAML_DECLARE(void)
1277 yaml_emitter_delete(yaml_emitter_t *emitter);
1278
1279 /**
1280  * Set a string output.
1281  *
1282  * The emitter will write the output characters to the @a output buffer of the
1283  * size @a size.  The emitter will set @a size_written to the number of written
1284  * bytes.  If the buffer is smaller than required, the emitter produces the
1285  * YAML_WRITE_ERROR error.
1286  *
1287  * @param[in,out]   emitter         An emitter object.
1288  * @param[in]       output          An output buffer.
1289  * @param[in]       size            The buffer size.
1290  * @param[in]       size_written    The pointer to save the number of written
1291  *                                  bytes.
1292  */
1293
1294 YAML_DECLARE(void)
1295 yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1296         unsigned char *output, size_t size, size_t *size_written);
1297
1298 /**
1299  * Set a file output.
1300  *
1301  * @a file should be a file object open for writing.  The application is
1302  * responsible for closing the @a file.
1303  *
1304  * @param[in,out]   emitter     An emitter object.
1305  * @param[in]       file        An open file.
1306  */
1307
1308 YAML_DECLARE(void)
1309 yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1310
1311 /**
1312  * Set a generic output handler.
1313  *
1314  * @param[in,out]   emitter     An emitter object.
1315  * @param[in]       handler     A write handler.
1316  * @param[in]       data        Any application data for passing to the write
1317  *                              handler.
1318  */
1319
1320 YAML_DECLARE(void)
1321 yaml_emitter_set_output(yaml_emitter_t *emitter,
1322         yaml_write_handler_t *handler, void *data);
1323
1324 /**
1325  * Set the output encoding.
1326  *
1327  * @param[in,out]   emitter     An emitter object.
1328  * @param[in]       encoding    The output encoding.
1329  */
1330
1331 YAML_DECLARE(void)
1332 yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1333
1334 /**
1335  * Set if the output should be in the "canonical" format as in the YAML
1336  * specification.
1337  *
1338  * @param[in,out]   emitter     An emitter object.
1339  * @param[in]       canonical   If the output is canonical.
1340  */
1341
1342 YAML_DECLARE(void)
1343 yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1344
1345 /**
1346  * Set the intendation increment.
1347  *
1348  * @param[in,out]   emitter     An emitter object.
1349  * @param[in]       indent      The indentation increment (1 < . < 10).
1350  */
1351
1352 YAML_DECLARE(void)
1353 yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1354
1355 /**
1356  * Set the preferred line width. @c -1 means unlimited.
1357  *
1358  * @param[in,out]   emitter     An emitter object.
1359  * @param[in]       width       The preferred line width.
1360  */
1361
1362 YAML_DECLARE(void)
1363 yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1364
1365 /**
1366  * Set if unescaped non-ASCII characters are allowed.
1367  *
1368  * @param[in,out]   emitter     An emitter object.
1369  * @param[in]       unicode     If unescaped Unicode characters are allowed.
1370  */
1371
1372 YAML_DECLARE(void)
1373 yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1374
1375 /**
1376  * Set the preferred line break.
1377  *
1378  * @param[in,out]   emitter     An emitter object.
1379  * @param[in]       line_break  The preferred line break.
1380  */
1381
1382 YAML_DECLARE(void)
1383 yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1384
1385 /**
1386  * Emit an event.
1387  *
1388  * The event object may be generated using the yaml_parser_parse() function.
1389  * The emitter takes the responsibility for the event object and destroys its
1390  * content after it is emitted. The event object is destroyed even if the
1391  * function fails.
1392  *
1393  * @param[in,out]   emitter     An emitter object.
1394  * @param[in,out]   event       An event object.
1395  *
1396  * @returns @c 1 if the function succeeded, @c 0 on error.
1397  */
1398
1399 YAML_DECLARE(int)
1400 yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
1401
1402 /**
1403  * Flush the accumulated characters to the output.
1404  *
1405  * @param[in,out]   emitter     An emitter object.
1406  *
1407  * @returns @c 1 if the function succeeded, @c 0 on error.
1408  */
1409
1410 YAML_DECLARE(int)
1411 yaml_emitter_flush(yaml_emitter_t *emitter);
1412
1413 /** @} */
1414
1415 #ifdef __cplusplus
1416 }
1417 #endif
1418
1419 #endif /* #ifndef YAML_H */
1420