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/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]   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[in]   event       An empty event object.
 420  *
 421  * @returns @c 1 if the function succeeded, @c 0 on error.
 422  */
 423
 424 YAML_DECLARE(int)
 425 yaml_stream_start_event_initialize(yaml_event_t *event,
 426         yaml_encoding_t encoding);
 427
 428 /**
 429  * Create the STREAM-END event.
 430  *
 431  * @param[in]   event       An empty event object.
 432  *
 433  * @returns @c 1 if the function succeeded, @c 0 on error.
 434  */
 435
 436 YAML_DECLARE(int)
 437 yaml_stream_end_event_initialize(yaml_event_t *event);
 438
 439 /**
 440  * Create the DOCUMENT-START event.
 441  *
 442  * The @a implicit argument is considered as a stylistic parameter and may be
 443  * ignored by the emitter.
 444  *
 445  * @param[in]   event                   An empty event object.
 446  * @param[in]   version_directive       The %YAML directive value or @c NULL.
 447  * @param[in]   tag_directives_start    The beginning of the %TAG directives list.
 448  * @param[in]   tag_directives_end      The end of the %TAG directives list.
 449  * @param[in]   implicit                If the document start indicator is implicit.
 450  *
 451  * @returns @c 1 if the function succeeded, @c 0 on error.
 452  */
 453
 454 YAML_DECLARE(int)
 455 yaml_document_start_event_initialize(yaml_event_t *event,
 456         yaml_version_directive_t *version_directive,
 457         yaml_tag_directive_t *tag_directives_start,
 458         yaml_tag_directive_t *tag_directives_end,
 459         int implicit);
 460
 461 /**
 462  * Create the DOCUMENT-END event.
 463  *
 464  * The @a implicit argument is considered as a stylistic parameter and may be
 465  * ignored by the emitter.
 466  *
 467  * @param[in]   event       An empty event object.
 468  * @param[in]   implicit    If the document end indicator is implicit.
 469  *
 470  * @returns @c 1 if the function succeeded, @c 0 on error.
 471  */
 472
 473 YAML_DECLARE(int)
 474 yaml_document_end_event_initialize(yaml_event_t *event, int implicit);
 475
 476 /**
 477  * Create an ALIAS event.
 478  *
 479  * @param[in]   event       An empty event object.
 480  * @param[in]   anchor      The anchor value.
 481  *
 482  * @returns @c 1 if the function succeeded, @c 0 on error.
 483  */
 484
 485 YAML_DECLARE(int)
 486 yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor);
 487
 488 /**
 489  * Create a SCALAR event.
 490  *
 491  * The @a style argument may be ignored by the emitter.
 492  *
 493  * Either the @a tag attribute or one of the @a plain_implicit and
 494  * @a quoted_implicit flags must be set.
 495  *
 496  * @param[in]   event           An empty event object.
 497  * @param[in]   anchor          The scalar anchor or @c NULL.
 498  * @param[in]   tag             The scalar tag or @c NULL.
 499  * @param[in]   value           The scalar value.
 500  * @param[in]   length          The length of the scalar value.
 501  * @param[in]   plain_implicit  If the tag may be omitted for the plain style.
 502  * @param[in]   quoted_implicit If the tag may be omitted for any non-plain style.
 503  * @param[in]   style           The scalar style.
 504  *
 505  * @returns @c 1 if the function succeeded, @c 0 on error.
 506  */
 507
 508 YAML_DECLARE(int)
 509 yaml_scalar_event_initialize(yaml_event_t *event,
 510         yaml_char_t *anchor, yaml_char_t *tag,
 511         yaml_char_t *value, size_t length,
 512         int plain_implicit, int quoted_implicit,
 513         yaml_scalar_style_t style);
 514
 515 /**
 516  * Create a SEQUENCE-START event.
 517  *
 518  * The @a style argument may be ignored by the emitter.
 519  *
 520  * Either the @a tag attribute or the @a implicit flag must be set.
 521  *
 522  * @param[in]   event       An empty event object.
 523  * @param[in]   anchor      The sequence anchor or @c NULL.
 524  * @param[in]   tag         The sequence tag or @c NULL.
 525  * @param[in]   implicit    If the tag may be omitted.
 526  * @param[in]   style       The sequence style.
 527  *
 528  * @returns @c 1 if the function succeeded, @c 0 on error.
 529  */
 530
 531 YAML_DECLARE(int)
 532 yaml_sequence_start_event_initialize(yaml_event_t *event,
 533         yaml_char_t *anchor, yaml_char_t *tag, int implicit,
 534         yaml_sequence_style_t style);
 535
 536 /**
 537  * Create a SEQUENCE-END event.
 538  *
 539  * @param[in]   event       An empty event object.
 540  *
 541  * @returns @c 1 if the function succeeded, @c 0 on error.
 542  */
 543
 544 YAML_DECLARE(int)
 545 yaml_sequence_end_event_initialize(yaml_event_t *event);
 546
 547 /**
 548  * Create a MAPPING-START event.
 549  *
 550  * The @a style argument may be ignored by the emitter.
 551  *
 552  * Either the @a tag attribute or the @a implicit flag must be set.
 553  *
 554  * @param[in]   event       An empty event object.
 555  * @param[in]   anchor      The mapping anchor or @c NULL.
 556  * @param[in]   tag         The mapping tag or @c NULL.
 557  * @param[in]   implicit    If the tag may be omitted.
 558  * @param[in]   style       The mapping style.
 559  *
 560  * @returns @c 1 if the function succeeded, @c 0 on error.
 561  */
 562
 563 YAML_DECLARE(int)
 564 yaml_mapping_start_event_initialize(yaml_event_t *event,
 565         yaml_char_t *anchor, yaml_char_t *tag, int implicit,
 566         yaml_mapping_style_t style);
 567
 568 /**
 569  * Create a MAPPING-END event.
 570  *
 571  * @param[in]   event       An empty event object.
 572  *
 573  * @returns @c 1 if the function succeeded, @c 0 on error.
 574  */
 575
 576 YAML_DECLARE(int)
 577 yaml_mapping_end_event_initialize(yaml_event_t *event);
 578
 579 /**
 580  * Free any memory allocated for an event object.
 581  *
 582  * @param[in]   event   An event object.
 583  */
 584
 585 YAML_DECLARE(void)
 586 yaml_event_delete(yaml_event_t *event);
 587
 588 /** @} */
 589
 590 /**
 591  * @defgroup parser Parser Definitions
 592  * @{
 593  */
 594
 595 /**
 596  * The prototype of a read handler.
 597  *
 598  * The read handler is called when the parser needs to read more bytes from the
 599  * source.  The handler should write not more than @a size bytes to the @a
 600  * buffer.  The number of written bytes should be set to the @a length variable.
 601  *
 602  * @param[in]   data        A pointer to an application data specified by
 603  *                          @c yaml_parser_set_read_handler.
 604  * @param[out]  buffer      The buffer to write the data from the source.
 605  * @param[in]   size        The size of the buffer.
 606  * @param[out]  size_read   The actual number of bytes read from the source.
 607  *
 608  * @returns On success, the handler should return @c 1.  If the handler failed,
 609  * the returned value should be @c 0.  On EOF, the handler should set the
 610  * @a size_read to @c 0 and return @c 1.
 611  */
 612
 613 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
 614         size_t *size_read);
 615
 616 /**
 617  * This structure holds information about a potential simple key.
 618  */
 619
 620 typedef struct {
 621     /** Is a simple key possible? */
 622     int possible;
 623
 624     /** Is a simple key required? */
 625     int required;
 626
 627     /** The number of the token. */
 628     size_t token_number;
 629
 630     /** The position mark. */
 631     yaml_mark_t mark;
 632 } yaml_simple_key_t;
 633
 634 /**
 635  * The states of the parser.
 636  */
 637 typedef enum {
 638     YAML_PARSE_STREAM_START_STATE,
 639     YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
 640     YAML_PARSE_DOCUMENT_START_STATE,
 641     YAML_PARSE_DOCUMENT_CONTENT_STATE,
 642     YAML_PARSE_DOCUMENT_END_STATE,
 643     YAML_PARSE_BLOCK_NODE_STATE,
 644     YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
 645     YAML_PARSE_FLOW_NODE_STATE,
 646     YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
 647     YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
 648     YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
 649     YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
 650     YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
 651     YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
 652     YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
 653     YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
 654     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
 655     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
 656     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
 657     YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
 658     YAML_PARSE_FLOW_MAPPING_KEY_STATE,
 659     YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
 660     YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
 661     YAML_PARSE_END_STATE
 662 } yaml_parser_state_t;
 663
 664 /**
 665  * The parser structure.
 666  *
 667  * All members are internal.  Manage the structure using the @c yaml_parser_
 668  * family of functions.
 669  */
 670
 671 typedef struct {
 672
 673     /**
 674      * @name Error handling
 675      * @{
 676      */
 677
 678     /** Error type. */
 679     yaml_error_type_t error;
 680     /** Error description. */
 681     const char *problem;
 682     /** The byte about which the problem occured. */
 683     size_t problem_offset;
 684     /** The problematic value (@c -1 is none). */
 685     int problem_value;
 686     /** The problem position. */
 687     yaml_mark_t problem_mark;
 688     /** The error context. */
 689     const char *context;
 690     /** The context position. */
 691     yaml_mark_t context_mark;
 692
 693     /**
 694      * @}
 695      */
 696
 697     /**
 698      * @name Reader stuff
 699      * @{
 700      */
 701
 702     /** Read handler. */
 703     yaml_read_handler_t *read_handler;
 704
 705     /** A pointer for passing to the read handler. */
 706     void *read_handler_data;
 707
 708     /** Standard (string or file) input data. */
 709     union {
 710         /** String input data. */
 711         struct {
 712             /** The string start pointer. */
 713             unsigned char *start;
 714             /** The string end pointer. */
 715             unsigned char *end;
 716             /** The string current position. */
 717             unsigned char *current;
 718         } string;
 719
 720         /** File input data. */
 721         FILE *file;
 722     } input;
 723
 724     /** EOF flag */
 725     int eof;
 726
 727     /** The working buffer. */
 728     struct {
 729         /** The beginning of the buffer. */
 730         yaml_char_t *start;
 731         /** The end of the buffer. */
 732         yaml_char_t *end;
 733         /** The current position of the buffer. */
 734         yaml_char_t *pointer;
 735         /** The last filled position of the buffer. */
 736         yaml_char_t *last;
 737     } buffer;
 738
 739     /* The number of unread characters in the buffer. */
 740     size_t unread;
 741
 742     /** The raw buffer. */
 743     struct {
 744         /** The beginning of the buffer. */
 745         unsigned char *start;
 746         /** The end of the buffer. */
 747         unsigned char *end;
 748         /** The current position of the buffer. */
 749         unsigned char *pointer;
 750         /** The last filled position of the buffer. */
 751         unsigned char *last;
 752     } raw_buffer;
 753
 754     /** The input encoding. */
 755     yaml_encoding_t encoding;
 756
 757     /** The offset of the current position (in bytes). */
 758     size_t offset;
 759
 760     /** The mark of the current position. */
 761     yaml_mark_t mark;
 762
 763     /**
 764      * @}
 765      */
 766
 767     /**
 768      * @name Scanner stuff
 769      * @{
 770      */
 771
 772     /** Have we started to scan the input stream? */
 773     int stream_start_produced;
 774
 775     /** Have we reached the end of the input stream? */
 776     int stream_end_produced;
 777
 778     /** The number of unclosed '[' and '{' indicators. */
 779     int flow_level;
 780
 781     /** The tokens queue. */
 782     struct {
 783         /** The beginning of the tokens queue. */
 784         yaml_token_t *start;
 785         /** The end of the tokens queue. */
 786         yaml_token_t *end;
 787         /** The head of the tokens queue. */
 788         yaml_token_t *head;
 789         /** The tail of the tokens queue. */
 790         yaml_token_t *tail;
 791     } tokens;
 792
 793     /** The number of tokens fetched from the queue. */
 794     size_t tokens_parsed;
 795
 796     /* Does the tokens queue contain a token ready for dequeueing. */
 797     int token_available;
 798
 799     /** The indentation levels stack. */
 800     struct {
 801         /** The beginning of the stack. */
 802         int *start;
 803         /** The end of the stack. */
 804         int *end;
 805         /** The top of the stack. */
 806         int *top;
 807     } indents;
 808
 809     /** The current indentation level. */
 810     int indent;
 811
 812     /** May a simple key occur at the current position? */
 813     int simple_key_allowed;
 814
 815     /** The stack of simple keys. */
 816     struct {
 817         /** The beginning of the stack. */
 818         yaml_simple_key_t *start;
 819         /** The end of the stack. */
 820         yaml_simple_key_t *end;
 821         /** The top of the stack. */
 822         yaml_simple_key_t *top;
 823     } simple_keys;
 824
 825     /**
 826      * @}
 827      */
 828
 829     /**
 830      * @name Parser stuff
 831      * @{
 832      */
 833
 834     /** The parser states stack. */
 835     struct {
 836         /** The beginning of the stack. */
 837         yaml_parser_state_t *start;
 838         /** The end of the stack. */
 839         yaml_parser_state_t *end;
 840         /** The top of the stack. */
 841         yaml_parser_state_t *top;
 842     } states;
 843
 844     /** The current parser state. */
 845     yaml_parser_state_t state;
 846
 847     /** The stack of marks. */
 848     struct {
 849         /** The beginning of the stack. */
 850         yaml_mark_t *start;
 851         /** The end of the stack. */
 852         yaml_mark_t *end;
 853         /** The top of the stack. */
 854         yaml_mark_t *top;
 855     } marks;
 856
 857     /** The list of TAG directives. */
 858     struct {
 859         /** The beginning of the list. */
 860         yaml_tag_directive_t *start;
 861         /** The end of the list. */
 862         yaml_tag_directive_t *end;
 863         /** The top of the list. */
 864         yaml_tag_directive_t *top;
 865     } tag_directives;
 866
 867     /**
 868      * @}
 869      */
 870
 871 } yaml_parser_t;
 872
 873 /**
 874  * Initialize a parser.
 875  *
 876  * This function creates a new parser object.  An application is responsible
 877  * for destroying the object using the @c yaml_parser_delete function.
 878  *
 879  * @param[in]   parser  An empty parser object.
 880  *
 881  * @returns @c 1 if the function succeeded, @c 0 on error.
 882  */
 883
 884 YAML_DECLARE(int)
 885 yaml_parser_initialize(yaml_parser_t *parser);
 886
 887 /**
 888  * Destroy a parser.
 889  *
 890  * @param[in]   parser  A parser object.
 891  */
 892
 893 YAML_DECLARE(void)
 894 yaml_parser_delete(yaml_parser_t *parser);
 895
 896 /**
 897  * Set a string input.
 898  *
 899  * Note that the @a input pointer must be valid while the @a parser object
 900  * exists.  The application is responsible for destroing @a input after
 901  * destroying the @a parser.
 902  *
 903  * @param[in]   parser  A parser object.
 904  * @param[in]   input   A source data.
 905  * @param[in]   size    The length of the source data in bytes.
 906  */
 907
 908 YAML_DECLARE(void)
 909 yaml_parser_set_input_string(yaml_parser_t *parser,
 910         unsigned char *input, size_t size);
 911
 912 /**
 913  * Set a file input.
 914  *
 915  * @a file should be a file object open for reading.  The application is
 916  * responsible for closing the @a file.
 917  *
 918  * @param[in]   parser  A parser object.
 919  * @param[in]   file    An open file.
 920  */
 921
 922 YAML_DECLARE(void)
 923 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
 924
 925 /**
 926  * Set a generic input handler.
 927  *
 928  * @param[in]   parser  A parser object.
 929  * @param[in]   handler A read handler.
 930  * @param[in]   data    Any application data for passing to the read handler.
 931  */
 932
 933 YAML_DECLARE(void)
 934 yaml_parser_set_input(yaml_parser_t *parser,
 935         yaml_read_handler_t *handler, void *data);
 936
 937 /**
 938  * Set the source encoding.
 939  *
 940  * @param[in]   parser      A parser object.
 941  * @param[in]   encoding    The source encoding.
 942  */
 943
 944 YAML_DECLARE(void)
 945 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
 946
 947 /**
 948  * Scan the input stream and produce the next token.
 949  *
 950  * Call the function subsequently to produce a sequence of tokens corresponding
 951  * to the input stream.  The initial token has the type
 952  * @c YAML_STREAM_START_TOKEN while the ending token has the type
 953  * @c YAML_STREAM_END_TOKEN.
 954  *
 955  * An application is responsible for freeing any buffers associated with the
 956  * produced token object using the @c yaml_token_delete function.
 957  *
 958  * An application must not alternate the calls of @c yaml_parser_scan with the
 959  * calls of @c yaml_parser_parse. Doing this will break the parser.
 960  *
 961  * @param[in]   parser      A parser object.
 962  * @param[in]   token       An empty token object.
 963  *
 964  * @returns @c 1 if the function succeeded, @c 0 on error.
 965  */
 966
 967 YAML_DECLARE(int)
 968 yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
 969
 970 /**
 971  * Parse the input stream and produce the next parsing event.
 972  *
 973  * Call the function subsequently to produce a sequence of events corresponding
 974  * to the input stream.  The initial event has the type
 975  * @c YAML_STREAM_START_EVENT while the ending event has the type
 976  * @c YAML_STREAM_END_EVENT.
 977  *
 978  * An application is responsible for freeing any buffers associated with the
 979  * produced event object using the @c yaml_event_delete function.
 980  *
 981  * An application must not alternate the calls of @c yaml_parser_scan with the
 982  * calls of @c yaml_parser_parse. Doing this will break the parser.
 983  *
 984  * @param[in]   parser      A parser object.
 985  * @param[in]   event       An empty event object.
 986  *
 987  * @returns @c 1 if the function succeeded, @c 0 on error.
 988  */
 989
 990 YAML_DECLARE(int)
 991 yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
 992
 993 /** @} */
 994
 995 /**
 996  * @defgroup emitter Emitter Definitions
 997  * @{
 998  */
 999
1000 /**
1001  * The prototype of a write handler.
1002  *
1003  * The write handler is called when the emitter needs to flush the accumulated
1004  * characters to the output.  The handler should write @a size bytes of the
1005  * @a buffer to the output.
1006  *
1007  * @param[in]   data        A pointer to an application data specified by
1008  *                          @c yaml_emitter_set_write_handler.
1009  * @param[out]  buffer      The buffer with bytes to be written.
1010  * @param[in]   size        The size of the buffer.
1011  *
1012  * @returns On success, the handler should return @c 1.  If the handler failed,
1013  * the returned value should be @c 0.
1014  */
1015
1016 typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size);
1017
1018 /** The emitter states. */
1019 typedef enum {
1020     YAML_EMIT_STREAM_START_STATE,
1021     YAML_EMIT_FIRST_DOCUMENT_START_STATE,
1022     YAML_EMIT_DOCUMENT_START_STATE,
1023     YAML_EMIT_DOCUMENT_CONTENT_STATE,
1024     YAML_EMIT_DOCUMENT_END_STATE,
1025     YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
1026     YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
1027     YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
1028     YAML_EMIT_FLOW_MAPPING_KEY_STATE,
1029     YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
1030     YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
1031     YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
1032     YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
1033     YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
1034     YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
1035     YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
1036     YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
1037     YAML_EMIT_END_STATE
1038 } yaml_emitter_state_t;
1039
1040 /**
1041  * The emitter structure.
1042  *
1043  * All members are internal.  Manage the structure using the @c yaml_emitter_
1044  * family of functions.
1045  */
1046
1047 typedef struct {
1048
1049     /**
1050      * @name Error handling
1051      * @{
1052      */
1053
1054     /** Error type. */
1055     yaml_error_type_t error;
1056     /** Error description. */
1057     const char *problem;
1058
1059     /**
1060      * @}
1061      */
1062
1063     /**
1064      * @name Writer stuff
1065      * @{
1066      */
1067
1068     /** Write handler. */
1069     yaml_write_handler_t *write_handler;
1070
1071     /** A pointer for passing to the white handler. */
1072     void *write_handler_data;
1073
1074     /** Standard (string or file) output data. */
1075     union {
1076         /** String output data. */
1077         struct {
1078             /** The buffer pointer. */
1079             unsigned char *buffer;
1080             /** The buffer size. */
1081             size_t size;
1082             /** The number of written bytes. */
1083             size_t *size_written;
1084         } string;
1085
1086         /** File output data. */
1087         FILE *file;
1088     } output;
1089
1090     /** The working buffer. */
1091     struct {
1092         /** The beginning of the buffer. */
1093         yaml_char_t *start;
1094         /** The end of the buffer. */
1095         yaml_char_t *end;
1096         /** The current position of the buffer. */
1097         yaml_char_t *pointer;
1098         /** The last filled position of the buffer. */
1099         yaml_char_t *last;
1100     } buffer;
1101
1102     /** The raw buffer. */
1103     struct {
1104         /** The beginning of the buffer. */
1105         unsigned char *start;
1106         /** The end of the buffer. */
1107         unsigned char *end;
1108         /** The current position of the buffer. */
1109         unsigned char *pointer;
1110         /** The last filled position of the buffer. */
1111         unsigned char *last;
1112     } raw_buffer;
1113
1114     /** The stream encoding. */
1115     yaml_encoding_t encoding;
1116
1117     /**
1118      * @}
1119      */
1120
1121     /**
1122      * @name Emitter stuff
1123      * @{
1124      */
1125
1126     /** If the output is in the canonical style? */
1127     int canonical;
1128     /** The number of indentation spaces. */
1129     int best_indent;
1130     /** The preferred width of the output lines. */
1131     int best_width;
1132     /** Allow unescaped non-ASCII characters? */
1133     int unicode;
1134     /** The preferred line break. */
1135     yaml_break_t line_break;
1136
1137     /** The stack of states. */
1138     struct {
1139         /** The beginning of the stack. */
1140         yaml_emitter_state_t *start;
1141         /** The end of the stack. */
1142         yaml_emitter_state_t *end;
1143         /** The top of the stack. */
1144         yaml_emitter_state_t *top;
1145     } states;
1146
1147     /** The current emitter state. */
1148     yaml_emitter_state_t state;
1149
1150     /** The event queue. */
1151     struct {
1152         /** The beginning of the event queue. */
1153         yaml_event_t *start;
1154         /** The end of the event queue. */
1155         yaml_event_t *end;
1156         /** The head of the event queue. */
1157         yaml_event_t *head;
1158         /** The tail of the event queue. */
1159         yaml_event_t *tail;
1160     } events;
1161
1162     /** The stack of indentation levels. */
1163     struct {
1164         /** The beginning of the stack. */
1165         int *start;
1166         /** The end of the stack. */
1167         int *end;
1168         /** The top of the stack. */
1169         int *top;
1170     } indents;
1171
1172     /** The list of tag directives. */
1173     struct {
1174         /** The beginning of the list. */
1175         yaml_tag_directive_t *start;
1176         /** The end of the list. */
1177         yaml_tag_directive_t *end;
1178         /** The top of the list. */
1179         yaml_tag_directive_t *top;
1180     } tag_directives;
1181
1182     /** The current indentation level. */
1183     int indent;
1184
1185     /** The current flow level. */
1186     int flow_level;
1187
1188     /** Is it the document root context? */
1189     int root_context;
1190     /** Is it a sequence context? */
1191     int sequence_context;
1192     /** Is it a mapping context? */
1193     int mapping_context;
1194     /** Is it a simple mapping key context? */
1195     int simple_key_context;
1196
1197     /** The current line. */
1198     int line;
1199     /** The current column. */
1200     int column;
1201     /** If the last character was a whitespace? */
1202     int whitespace;
1203     /** If the last character was an indentation character (' ', '-', '?', ':')? */
1204     int indention;
1205
1206     /**
1207      * @}
1208      */
1209
1210 } yaml_emitter_t;
1211
1212 /**
1213  * Initialize an emitter.
1214  *
1215  * This function creates a new emitter object.  An application is responsible
1216  * for destroying the object using the @c yaml_emitter_delete function.
1217  *
1218  * @param[in]   emitter An empty parser object.
1219  *
1220  * @returns @c 1 if the function succeeded, @c 0 on error.
1221  */
1222
1223 YAML_DECLARE(int)
1224 yaml_emitter_initialize(yaml_emitter_t *emitter);
1225
1226 /**
1227  * Destroy an emitter.
1228  *
1229  * @param[in]   emitter An emitter object.
1230  */
1231
1232 YAML_DECLARE(void)
1233 yaml_emitter_delete(yaml_emitter_t *emitter);
1234
1235 /**
1236  * Set a string output.
1237  *
1238  * The emitter will write the output characters to the @a output buffer of the
1239  * size @a size.  The emitter will set @a size_written to the number of written
1240  * bytes.  If the buffer is smaller than required, the emitter produces the
1241  * YAML_WRITE_ERROR error.
1242  *
1243  * @param[in]   emitter         An emitter object.
1244  * @param[in]   output          An output buffer.
1245  * @param[in]   size            The buffer size.
1246  * @param[in]   size_written    The pointer to save the number of written bytes.
1247  */
1248
1249 YAML_DECLARE(void)
1250 yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1251         unsigned char *output, size_t size, size_t *size_written);
1252
1253 /**
1254  * Set a file output.
1255  *
1256  * @a file should be a file object open for writing.  The application is
1257  * responsible for closing the @a file.
1258  *
1259  * @param[in]   emitter An emitter object.
1260  * @param[in]   file    An open file.
1261  */
1262
1263 YAML_DECLARE(void)
1264 yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1265
1266 /**
1267  * Set a generic output handler.
1268  *
1269  * @param[in]   emitter An emitter object.
1270  * @param[in]   handler A write handler.
1271  * @param[in]   data    Any application data for passing to the write handler.
1272  */
1273
1274 YAML_DECLARE(void)
1275 yaml_emitter_set_output(yaml_emitter_t *emitter,
1276         yaml_write_handler_t *handler, void *data);
1277
1278 /**
1279  * Set the output encoding.
1280  *
1281  * @param[in]   emitter     An emitter object.
1282  * @param[in]   encoding    The output encoding.
1283  */
1284
1285 YAML_DECLARE(void)
1286 yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1287
1288 /**
1289  * Set if the output should be in the "canonical" format as in the YAML
1290  * specification.
1291  *
1292  * @param[in]   emitter     An emitter object.
1293  * @param[in]   canonical   If the output is canonical.
1294  */
1295
1296 YAML_DECLARE(void)
1297 yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1298
1299 /**
1300  * Set the intendation increment.
1301  *
1302  * @param[in]   emitter     An emitter object.
1303  * @param[in]   indent      The indentation increment (1 < . < 10).
1304  */
1305
1306 YAML_DECLARE(void)
1307 yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1308
1309 /**
1310  * Set the preferred line width. @c -1 means unlimited.
1311  *
1312  * @param[in]   emitter     An emitter object.
1313  * @param[in]   width       The preferred line width.
1314  */
1315
1316 YAML_DECLARE(void)
1317 yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1318
1319 /**
1320  * Set if unescaped non-ASCII characters are allowed.
1321  *
1322  * @param[in]   emitter     An emitter object.
1323  * @param[in]   unicode     If unescaped Unicode characters are allowed.
1324  */
1325
1326 YAML_DECLARE(void)
1327 yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1328
1329 /**
1330  * Set the preferred line break.
1331  *
1332  * @param[in]   emitter     An emitter object.
1333  * @param[in]   line_break  The preferred line break.
1334  */
1335
1336 YAML_DECLARE(void)
1337 yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1338
1339 /**
1340  * Emit an event.
1341  *
1342  * The event object may be generated using the @c yaml_parser_parse function.
1343  * The emitter takes the responsibility for the event object and destroys its
1344  * content after it is emitted. The event object is destroyed even if the
1345  * function fails.
1346  *
1347  * @param[in]   emitter     An emitter object.
1348  * @param[in]   event       An event object.
1349  *
1350  * @returns @c 1 if the function succeeded, @c 0 on error.
1351  */
1352
1353 YAML_DECLARE(int)
1354 yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
1355
1356 /**
1357  * Flush the accumulated characters to the output.
1358  *
1359  * @param[in]   emitter     An emitter object.
1360  *
1361  * @returns @c 1 if the function succeeded, @c 0 on error.
1362  */
1363
1364 YAML_DECLARE(int)
1365 yaml_emitter_flush(yaml_emitter_t *emitter);
1366
1367 /** @} */
1368
1369 #ifdef __cplusplus
1370 }
1371 #endif
1372
1373 #endif /* #ifndef YAML_H */
1374