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 /** Many bad things could happen with the parser and emitter. */
 105 typedef enum {
 106     YAML_NO_ERROR,
 107
 108     YAML_MEMORY_ERROR,
 109
 110     YAML_READER_ERROR,
 111     YAML_SCANNER_ERROR,
 112     YAML_PARSER_ERROR,
 113
 114     YAML_WRITER_ERROR,
 115     YAML_EMITTER_ERROR
 116 } yaml_error_type_t;
 117
 118 /** The pointer position. */
 119 typedef struct {
 120     /** The position index. */
 121     size_t index;
 122
 123     /** The position line. */
 124     size_t line;
 125
 126     /** The position column. */
 127     size_t column;
 128 } yaml_mark_t;
 129
 130 /** @} */
 131
 132 /**
 133  * @defgroup styles Node Styles
 134  * @{
 135  */
 136
 137 /** Scalar styles. */
 138 typedef enum {
 139     YAML_ANY_SCALAR_STYLE,
 140
 141     YAML_PLAIN_SCALAR_STYLE,
 142
 143     YAML_SINGLE_QUOTED_SCALAR_STYLE,
 144     YAML_DOUBLE_QUOTED_SCALAR_STYLE,
 145
 146     YAML_LITERAL_SCALAR_STYLE,
 147     YAML_FOLDED_SCALAR_STYLE
 148 } yaml_scalar_style_t;
 149
 150
 151 /** Sequence styles. */
 152 typedef enum {
 153     YAML_ANY_SEQUENCE_STYLE,
 154
 155     YAML_BLOCK_SEQUENCE_STYLE,
 156     YAML_FLOW_SEQUENCE_STYLE
 157 } yaml_sequence_style_t;
 158
 159 /** Mapping styles. */
 160 typedef enum {
 161     YAML_ANY_MAPPING_STYLE,
 162
 163     YAML_BLOCK_MAPPING_STYLE,
 164     YAML_FLOW_MAPPING_STYLE
 165 } yaml_mapping_style_t;
 166
 167 /** @} */
 168
 169 /**
 170  * @defgroup tokens Tokens
 171  * @{
 172  */
 173
 174 /** Token types. */
 175 typedef enum {
 176     YAML_STREAM_START_TOKEN,
 177     YAML_STREAM_END_TOKEN,
 178
 179     YAML_VERSION_DIRECTIVE_TOKEN,
 180     YAML_TAG_DIRECTIVE_TOKEN,
 181     YAML_DOCUMENT_START_TOKEN,
 182     YAML_DOCUMENT_END_TOKEN,
 183
 184     YAML_BLOCK_SEQUENCE_START_TOKEN,
 185     YAML_BLOCK_MAPPING_START_TOKEN,
 186     YAML_BLOCK_END_TOKEN,
 187
 188     YAML_FLOW_SEQUENCE_START_TOKEN,
 189     YAML_FLOW_SEQUENCE_END_TOKEN,
 190     YAML_FLOW_MAPPING_START_TOKEN,
 191     YAML_FLOW_MAPPING_END_TOKEN,
 192
 193     YAML_BLOCK_ENTRY_TOKEN,
 194     YAML_FLOW_ENTRY_TOKEN,
 195     YAML_KEY_TOKEN,
 196     YAML_VALUE_TOKEN,
 197
 198     YAML_ALIAS_TOKEN,
 199     YAML_ANCHOR_TOKEN,
 200     YAML_TAG_TOKEN,
 201     YAML_SCALAR_TOKEN
 202 } yaml_token_type_t;
 203
 204 /** The token structure. */
 205 typedef struct {
 206
 207     /** The token type. */
 208     yaml_token_type_t type;
 209
 210     /** The token data. */
 211     union {
 212
 213         /** The stream start (for @c YAML_STREAM_START_TOKEN). */
 214         struct {
 215             /** The stream encoding. */
 216             yaml_encoding_t encoding;
 217         } stream_start;
 218
 219         /** The alias (for @c YAML_ALIAS_TOKEN). */
 220         struct {
 221             /** The alias value. */
 222             yaml_char_t *value;
 223         } alias;
 224
 225         /** The anchor (for @c YAML_ANCHOR_TOKEN). */
 226         struct {
 227             /** The anchor value. */
 228             yaml_char_t *value;
 229         } anchor;
 230
 231         /** The tag (for @c YAML_TAG_TOKEN). */
 232         struct {
 233             /** The tag handle. */
 234             yaml_char_t *handle;
 235
 236             /** The tag suffix. */
 237             yaml_char_t *suffix;
 238         } tag;
 239
 240         /** The scalar value (for @c YAML_SCALAR_TOKEN). */
 241         struct {
 242
 243             /** The scalar value. */
 244             yaml_char_t *value;
 245
 246             /** The length of the scalar value. */
 247             size_t length;
 248
 249             /** The scalar style. */
 250             yaml_scalar_style_t style;
 251         } scalar;
 252
 253         /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
 254         struct {
 255             /** The major version number. */
 256             int major;
 257
 258             /** The minor version number. */
 259             int minor;
 260         } version_directive;
 261
 262         /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
 263         struct {
 264             /** The tag handle. */
 265             yaml_char_t *handle;
 266
 267             /** The tag prefix. */
 268             yaml_char_t *prefix;
 269         } tag_directive;
 270     } data;
 271
 272     /** The beginning of the token. */
 273     yaml_mark_t start_mark;
 274
 275     /** The end of the token. */
 276     yaml_mark_t end_mark;
 277
 278 } yaml_token_t;
 279
 280 /**
 281  * Create a new token without assigning any data.
 282  *
 283  * This function can be used for constructing indicator tokens:
 284  * @c YAML_DOCUMENT_START, @c YAML_DOCUMENT_END,
 285  * @c YAML_BLOCK_SEQUENCE_START_TOKEN, @c YAML_BLOCK_MAPPING_START_TOKEN,
 286  * @c YAML_BLOCK_END_TOKEN,
 287  * @c YAML_FLOW_SEQUENCE_START_TOKEN, @c YAML_FLOW_SEQUENCE_END_TOKEN,
 288  * @c YAML_FLOW_MAPPING_START_TOKEN, @c YAML_FLOW_MAPPING_END_TOKEN,
 289  * @c YAML_BLOCK_ENTRY_TOKEN, @c YAML_FLOW_ENTRY_TOKEN,
 290  * @c YAML_KEY_TOKEN, @c YAML_VALUE_TOKEN.
 291  *
 292  * @param[in]   type        The token type.
 293  * @param[in]   start_mark  The beginning of the token.
 294  * @param[in]   end_mark    The end of the token.
 295  *
 296  * @returns A new token object, or @c NULL on error.
 297  */
 298
 299 YAML_DECLARE(yaml_token_t *)
 300 yaml_token_new(yaml_token_type_t type,
 301         yaml_mark_t start_mark, yaml_mark_t end_mark);
 302
 303 /**
 304  * Create a new @c YAML_STREAM_START_TOKEN token with the specified encoding.
 305  *
 306  * @param[in]   encoding    The stream encoding.
 307  * @param[in]   start_mark  The beginning of the token.
 308  * @param[in]   end_mark    The end of the token.
 309  *
 310  * @returns A new token object, or @c NULL on error.
 311  */
 312
 313 YAML_DECLARE(yaml_token_t *)
 314 yaml_stream_start_token_new(yaml_encoding_t encoding,
 315         yaml_mark_t start_mark, yaml_mark_t end_mark);
 316
 317 /**
 318  * Create a new @c YAML_STREAM_END_TOKEN token.
 319  *
 320  * @param[in]   start_mark  The beginning of the token.
 321  * @param[in]   end_mark    The end of the token.
 322  *
 323  * @returns A new token object, or @c NULL on error.
 324  */
 325
 326 YAML_DECLARE(yaml_token_t *)
 327 yaml_stream_end_token_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
 328
 329 /**
 330  * Create a new @c YAML_VERSION_DIRECTIVE_TOKEN token with the specified
 331  * version numbers.
 332  *
 333  * @param[in]   major       The major version number.
 334  * @param[in]   minor       The minor version number.
 335  * @param[in]   start_mark  The beginning of the token.
 336  * @param[in]   end_mark    The end of the token.
 337  *
 338  * @returns A new token object, or @c NULL on error.
 339  */
 340
 341 YAML_DECLARE(yaml_token_t *)
 342 yaml_version_directive_token_new(int major, int minor,
 343         yaml_mark_t start_mark, yaml_mark_t end_mark);
 344
 345 /**
 346  * Create a new @c YAML_TAG_DIRECTIVE_TOKEN token with the specified tag
 347  * handle and prefix.
 348  *
 349  * Note that the @a handle and the @a prefix pointers will be freed by
 350  * the token descructor.
 351  *
 352  * @param[in]   handle      The tag handle.
 353  * @param[in]   prefix      The tag prefix.
 354  * @param[in]   start_mark  The beginning of the token.
 355  * @param[in]   end_mark    The end of the token.
 356  *
 357  * @returns A new token object, or @c NULL on error.
 358  */
 359
 360 YAML_DECLARE(yaml_token_t *)
 361 yaml_tag_directive_token_new(yaml_char_t *handle, yaml_char_t *prefix,
 362         yaml_mark_t start_mark, yaml_mark_t end_mark);
 363
 364 /**
 365  * Create a new @c YAML_ALIAS_TOKEN token with the specified anchor.
 366  *
 367  * Note that the @a anchor pointer will be freed by the token descructor.
 368  *
 369  * @param[in]   anchor      The anchor.
 370  * @param[in]   start_mark  The beginning of the token.
 371  * @param[in]   end_mark    The end of the token.
 372  *
 373  * @returns A new token object, or @c NULL on error.
 374  */
 375
 376 YAML_DECLARE(yaml_token_t *)
 377 yaml_alias_token_new(yaml_char_t *anchor,
 378         yaml_mark_t start_mark, yaml_mark_t end_mark);
 379
 380 /**
 381  * Create a new @c YAML_ANCHOR_TOKEN token with the specified anchor.
 382  *
 383  * Note that the @a anchor pointer will be freed by the token descructor.
 384  *
 385  * @param[in]   anchor      The anchor.
 386  * @param[in]   start_mark  The beginning of the token.
 387  * @param[in]   end_mark    The end of the token.
 388  *
 389  * @returns A new token object, or @c NULL on error.
 390  */
 391
 392 YAML_DECLARE(yaml_token_t *)
 393 yaml_anchor_token_new(yaml_char_t *anchor,
 394         yaml_mark_t start_mark, yaml_mark_t end_mark);
 395
 396 /**
 397  * Create a new @c YAML_TAG_TOKEN token with the specified tag handle and
 398  * suffix.
 399  *
 400  * Note that the @a handle and the @a suffix pointers will be freed by
 401  * the token descructor.
 402  *
 403  * @param[in]   handle      The tag handle.
 404  * @param[in]   suffix      The tag suffix.
 405  * @param[in]   start_mark  The beginning of the token.
 406  * @param[in]   end_mark    The end of the token.
 407  *
 408  * @returns A new token object, or @c NULL on error.
 409  */
 410
 411 YAML_DECLARE(yaml_token_t *)
 412 yaml_tag_token_new(yaml_char_t *handle, yaml_char_t *suffix,
 413         yaml_mark_t start_mark, yaml_mark_t end_mark);
 414
 415 /**
 416  * Create a new @c YAML_SCALAR_TOKEN token with the specified scalar value,
 417  * length, and style.
 418  *
 419  * Note that the scalar value may contain the @c NUL character, therefore
 420  * the value length is also required.  The scalar value always ends with
 421  * @c NUL.
 422  *
 423  * Note that the @a value pointer will be freed by the token descructor.
 424  *
 425  * @param[in]   value       The scalar value.
 426  * @param[in]   length      The value length.
 427  * @param[in]   style       The scalar style.
 428  * @param[in]   start_mark  The beginning of the token.
 429  * @param[in]   end_mark    The end of the token.
 430  *
 431  * @returns A new token object, or @c NULL on error.
 432  */
 433
 434 YAML_DECLARE(yaml_token_t *)
 435 yaml_scalar_token_new(yaml_char_t *value, size_t length,
 436         yaml_scalar_style_t style,
 437         yaml_mark_t start_mark, yaml_mark_t end_mark);
 438
 439 /**
 440  * Destroy a token object.
 441  *
 442  * @param[in]   token   A token object.
 443  */
 444
 445 YAML_DECLARE(void)
 446 yaml_token_delete(yaml_token_t *token);
 447
 448 /** @} */
 449
 450 /**
 451  * @defgroup events Events
 452  * @{
 453  */
 454
 455 /** Event types. */
 456 typedef enum {
 457     YAML_STREAM_START_EVENT,
 458     YAML_STREAM_END_EVENT,
 459
 460     YAML_DOCUMENT_START_EVENT,
 461     YAML_DOCUMENT_END_EVENT,
 462
 463     YAML_ALIAS_EVENT,
 464     YAML_SCALAR_EVENT,
 465
 466     YAML_SEQUENCE_START_EVENT,
 467     YAML_SEQUENCE_END_EVENT,
 468
 469     YAML_MAPPING_START_EVENT,
 470     YAML_MAPPING_END_EVENT
 471 } yaml_event_type_t;
 472
 473 /** The event structure. */
 474 typedef struct {
 475
 476     /** The event type. */
 477     yaml_event_type_t type;
 478
 479     /** The event data. */
 480     union {
 481
 482         /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
 483         struct {
 484             /** The document encoding. */
 485             yaml_encoding_t encoding;
 486         } stream_start;
 487
 488         /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
 489         struct {
 490             /** The version directive. */
 491             yaml_version_directive_t *version_directive;
 492             /** The list of tag directives. */
 493             yaml_tag_directive_t **tag_directives;
 494             /** Is the document indicator implicit? */
 495             int implicit;
 496         } document_start;
 497
 498         /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
 499         struct {
 500             /** Is the document end indicator implicit? */
 501             int implicit;
 502         } document_end;
 503
 504         /** The alias parameters (for @c YAML_ALIAS_EVENT). */
 505         struct {
 506             /** The anchor. */
 507             yaml_char_t *anchor;
 508         } alias;
 509
 510         /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
 511         struct {
 512             /** The anchor. */
 513             yaml_char_t *anchor;
 514             /** The tag. */
 515             yaml_char_t *tag;
 516             /** The scalar value. */
 517             yaml_char_t *value;
 518             /** The length of the scalar value. */
 519             size_t length;
 520             /** Is the tag optional for the plain style? */
 521             int plain_implicit;
 522             /** Is the tag optional for any non-plain style? */
 523             int quoted_implicit;
 524             /** The scalar style. */
 525             yaml_scalar_style_t style;
 526         } scalar;
 527
 528         /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
 529         struct {
 530             /** The anchor. */
 531             yaml_char_t *anchor;
 532             /** The tag. */
 533             yaml_char_t *tag;
 534             /** Is the tag optional? */
 535             int implicit;
 536             /** The sequence style. */
 537             yaml_sequence_style_t style;
 538         } sequence_start;
 539
 540         /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
 541         struct {
 542             /** The anchor. */
 543             yaml_char_t *anchor;
 544             /** The tag. */
 545             yaml_char_t *tag;
 546             /** Is the tag optional? */
 547             int implicit;
 548             /** The mapping style. */
 549             yaml_mapping_style_t style;
 550         } mapping_start;
 551
 552     } data;
 553
 554     /** The beginning of the token. */
 555     yaml_mark_t start_mark;
 556
 557     /** The end of the token. */
 558     yaml_mark_t end_mark;
 559 } yaml_event_t;
 560
 561 /**
 562  * Create a new @c YAML_STREAM_START_EVENT event.
 563  *
 564  * @param[in]   encoding    The stream encoding.
 565  * @param[in]   start_mark  The beginning of the event.
 566  * @param[in]   end_mark    The end of the event.
 567  *
 568  * @returns A new event object, or @c NULL on error.
 569  */
 570
 571 YAML_DECLARE(yaml_event_t *)
 572 yaml_stream_start_event_new(yaml_encoding_t encoding,
 573         yaml_mark_t start_mark, yaml_mark_t end_mark);
 574
 575 /**
 576  * Create a new @c YAML_STREAM_END_TOKEN event.
 577  *
 578  * @param[in]   start_mark  The beginning of the event.
 579  * @param[in]   end_mark    The end of the event.
 580  *
 581  * @returns A new event object, or @c NULL on error.
 582  */
 583
 584 YAML_DECLARE(yaml_event_t *)
 585 yaml_stream_end_event_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
 586
 587 /**
 588  * Create a new @c YAML_DOCUMENT_START_EVENT event.
 589  *
 590  * @param[in]   version_directive   The version directive or @c NULL.
 591  * @param[in]   tag_directives      A list of tag directives or @c NULL.
 592  * @param[in]   implicit            Is the document indicator present?
 593  * @param[in]   start_mark          The beginning of the event.
 594  * @param[in]   end_mark            The end of the event.
 595  *
 596  * @returns A new event object, or @c NULL on error.
 597  */
 598
 599 YAML_DECLARE(yaml_event_t *)
 600 yaml_document_start_event_new(yaml_version_directive_t *version_directive,
 601         yaml_tag_directive_t **tag_directives, int implicit,
 602         yaml_mark_t start_mark, yaml_mark_t end_mark);
 603
 604 /**
 605  * Create a new @c YAML_DOCUMENT_END_EVENT event.
 606  *
 607  * @param[in]   implicit    Is the document end indicator present?
 608  * @param[in]   start_mark  The beginning of the event.
 609  * @param[in]   end_mark    The end of the event.
 610  *
 611  * @returns A new event object, or @c NULL on error.
 612  */
 613
 614 YAML_DECLARE(yaml_event_t *)
 615 yaml_document_end_event_new(int implicit,
 616         yaml_mark_t start_mark, yaml_mark_t end_mark);
 617
 618 /**
 619  * Create a new @c YAML_ALIAS_EVENT event.
 620  *
 621  * @param[in]   anchor      The anchor value.
 622  * @param[in]   start_mark  The beginning of the event.
 623  * @param[in]   end_mark    The end of the event.
 624  *
 625  * @returns A new event object, or @c NULL on error.
 626  */
 627
 628 YAML_DECLARE(yaml_event_t *)
 629 yaml_alias_event_new(yaml_char_t *anchor,
 630         yaml_mark_t start_mark, yaml_mark_t end_mark);
 631
 632 /**
 633  * Create a new @c YAML_SCALAR_EVENT event.
 634  *
 635  * @param[in]   anchor          The anchor value or @c NULL.
 636  * @param[in]   tag             The tag value or @c NULL.
 637  * @param[in]   value           The scalar value.
 638  * @param[in]   length          The length of the scalar value.
 639  * @param[in]   plain_implicit  Is the tag optional for the plain style?
 640  * @param[in]   quoted_implicit Is the tag optional for any non-plain style?
 641  * @param[in]   style           The scalar style.
 642  * @param[in]   start_mark      The beginning of the event.
 643  * @param[in]   end_mark        The end of the event.
 644  *
 645  * @returns A new event object, or @c NULL on error.
 646  */
 647
 648 YAML_DECLARE(yaml_event_t *)
 649 yaml_scalar_event_new(yaml_char_t *anchor, yaml_char_t *tag,
 650         yaml_char_t *value, size_t length,
 651         int plain_implicit, int quoted_implicit,
 652         yaml_scalar_style_t style,
 653         yaml_mark_t start_mark, yaml_mark_t end_mark);
 654
 655 /**
 656  * Create a new @c YAML_SEQUENCE_START_EVENT event.
 657  *
 658  * @param[in]   anchor      The anchor value or @c NULL.
 659  * @param[in]   tag         The tag value or @c NULL.
 660  * @param[in]   implicit    Is the tag optional?
 661  * @param[in]   style       The sequence style.
 662  * @param[in]   start_mark  The beginning of the event.
 663  * @param[in]   end_mark    The end of the event.
 664  *
 665  * @returns A new event object, or @c NULL on error.
 666  */
 667
 668 YAML_DECLARE(yaml_event_t *)
 669 yaml_sequence_start_new(yaml_char_t *anchor, yaml_char_t *tag,
 670         int implicit, yaml_sequence_style_t style,
 671         yaml_mark_t start_mark, yaml_mark_t end_mark);
 672
 673 /**
 674  * Create a new @c YAML_SEQUENCE_END_EVENT event.
 675  *
 676  * @param[in]   start_mark  The beginning of the event.
 677  * @param[in]   end_mark    The end of the event.
 678  *
 679  * @returns A new event object, or @c NULL on error.
 680  */
 681
 682 YAML_DECLARE(yaml_event_t *)
 683 yaml_sequence_end_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
 684
 685 /**
 686  * Create a new @c YAML_MAPPING_START_EVENT event.
 687  *
 688  * @param[in]   anchor      The anchor value or @c NULL.
 689  * @param[in]   tag         The tag value or @c NULL.
 690  * @param[in]   implicit    Is the tag optional?
 691  * @param[in]   style       The mapping style.
 692  * @param[in]   start_mark  The beginning of the event.
 693  * @param[in]   end_mark    The end of the event.
 694  *
 695  * @returns A new event object, or @c NULL on error.
 696  */
 697
 698 YAML_DECLARE(yaml_event_t *)
 699 yaml_mapping_start_new(yaml_char_t *anchor, yaml_char_t *tag,
 700         int implicit, yaml_mapping_style_t style,
 701         yaml_mark_t start_mark, yaml_mark_t end_mark);
 702
 703 /**
 704  * Create a new @c YAML_MAPPING_END_EVENT event.
 705  *
 706  * @param[in]   start_mark  The beginning of the event.
 707  * @param[in]   end_mark    The end of the event.
 708  *
 709  * @returns A new event object, or @c NULL on error.
 710  */
 711
 712 YAML_DECLARE(yaml_event_t *)
 713 yaml_mapping_end_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
 714
 715 /**
 716  * Destroy an event object.
 717  *
 718  * @param[in]   event   An event object.
 719  */
 720
 721 YAML_DECLARE(void)
 722 yaml_event_delete(yaml_event_t *event);
 723
 724 /** @} */
 725
 726 /**
 727  * @defgroup parser Parser Definitions
 728  * @{
 729  */
 730
 731 /**
 732  * The prototype of a read handler.
 733  *
 734  * The read handler is called when the parser needs to read more bytes from the
 735  * source.  The handler should write not more than @a size bytes to the @a
 736  * buffer.  The number of written bytes should be set to the @a length variable.
 737  *
 738  * @param[in]   data        A pointer to an application data specified by
 739  *                          @c yaml_parser_set_read_handler.
 740  * @param[out]  buffer      The buffer to write the data from the source.
 741  * @param[in]   size        The size of the buffer.
 742  * @param[out]  size_read   The actual number of bytes read from the source.
 743  *
 744  * @returns On success, the handler should return @c 1.  If the handler failed,
 745  * the returned value should be @c 0.  On EOF, the handler should set the
 746  * @a length to @c 0 and return @c 1.
 747  */
 748
 749 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
 750         size_t *size_read);
 751
 752 /**
 753  * This structure holds a string input specified by
 754  * @c yaml_parser_set_input_string.
 755  */
 756
 757 typedef struct {
 758     /** The string start pointer. */
 759     unsigned char *start;
 760
 761     /** The string end pointer. */
 762     unsigned char *end;
 763
 764     /** The string current position. */
 765     unsigned char *current;
 766 } yaml_string_input_t;
 767
 768 /**
 769  * This structure holds information about a potential simple key.
 770  */
 771
 772 typedef struct {
 773     /** Is a simple key required? */
 774     int required;
 775
 776     /** The number of the token. */
 777     size_t token_number;
 778
 779     /** The position index. */
 780     size_t index;
 781
 782     /** The position line. */
 783     size_t line;
 784
 785     /** The position column. */
 786     size_t column;
 787
 788     /** The position mark. */
 789     yaml_mark_t mark;
 790 } yaml_simple_key_t;
 791
 792 /**
 793  * The states of the parser.
 794  */
 795 typedef enum {
 796     YAML_PARSE_END_STATE,
 797     YAML_PARSE_STREAM_START_STATE,
 798     YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
 799     YAML_PARSE_DOCUMENT_START_STATE,
 800     YAML_PARSE_DOCUMENT_CONTENT_STATE,
 801     YAML_PARSE_DOCUMENT_END_STATE,
 802     YAML_PARSE_BLOCK_NODE_STATE,
 803     YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
 804     YAML_PARSE_FLOW_NODE_STATE,
 805     YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
 806     YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
 807     YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
 808     YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
 809     YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
 810     YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
 811     YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
 812     YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
 813     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
 814     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
 815     YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
 816     YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
 817     YAML_PARSE_FLOW_MAPPING_KEY_STATE,
 818     YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
 819     YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE
 820 } yaml_parser_state_t;
 821
 822 /**
 823  * The parser structure.
 824  *
 825  * All members are internal.  Manage the structure using the @c yaml_parser_
 826  * family of functions.
 827  */
 828
 829 typedef struct {
 830
 831     /**
 832      * @name Error handling
 833      * @{
 834      */
 835
 836     /** Error type. */
 837     yaml_error_type_t error;
 838
 839     /** Error description. */
 840     const char *problem;
 841
 842     /** The byte about which the problem occured. */
 843     size_t problem_offset;
 844
 845     /** The problematic value (@c -1 is none). */
 846     int problem_value;
 847
 848     /** The problem position. */
 849     yaml_mark_t problem_mark;
 850
 851     /** The error context. */
 852     const char *context;
 853
 854     /** The context position. */
 855     yaml_mark_t context_mark;
 856
 857     /**
 858      * @}
 859      */
 860
 861     /**
 862      * @name Reader stuff
 863      * @{
 864      */
 865
 866     /** Read handler. */
 867     yaml_read_handler_t *read_handler;
 868
 869     /** A pointer for passing to the read handler. */
 870     void *read_handler_data;
 871
 872     /** EOF flag */
 873     int eof;
 874
 875     /** The pointer to the beginning of the working buffer. */
 876     yaml_char_t *buffer;
 877
 878     /** The pointer to the end of the working buffer. */
 879     yaml_char_t *buffer_end;
 880
 881     /** The pointer to the current character in the working buffer. */
 882     yaml_char_t *pointer;
 883
 884     /** The number of unread characters in the working buffer. */
 885     size_t unread;
 886
 887     /** The pointer to the beginning of the raw buffer. */
 888     unsigned char *raw_buffer;
 889
 890     /** The pointer to the current character in the raw buffer. */
 891     unsigned char *raw_pointer;
 892
 893     /** The number of unread bytes in the raw buffer. */
 894     size_t raw_unread;
 895
 896     /** The input encoding. */
 897     yaml_encoding_t encoding;
 898
 899     /** The offset of the current position (in bytes). */
 900     size_t offset;
 901
 902     /** The index of the current position (in characters). */
 903     size_t index;
 904
 905     /** The line of the current position (starting from @c 0). */
 906     size_t line;
 907
 908     /** The column of the current position (starting from @c 0). */
 909     size_t column;
 910
 911     /* String input structure. */
 912     yaml_string_input_t string_input;
 913
 914     /**
 915      * @}
 916      */
 917
 918     /**
 919      * @name Scanner stuff
 920      * @{
 921      */
 922
 923     /** Have we started to scan the input stream? */
 924     int stream_start_produced;
 925
 926     /** Have we reached the end of the input stream? */
 927     int stream_end_produced;
 928
 929     /** The number of unclosed '[' and '{' indicators. */
 930     int flow_level;
 931
 932     /** The tokens queue, which contains the current produced tokens. */
 933     yaml_token_t **tokens;
 934
 935     /** The size of the tokens queue. */
 936     size_t tokens_size;
 937
 938     /** The head of the tokens queue. */
 939     size_t tokens_head;
 940
 941     /** The tail of the tokens queue. */
 942     size_t tokens_tail;
 943
 944     /** The number of tokens fetched from the tokens queue. */
 945     size_t tokens_parsed;
 946
 947     /** The stack of indentation levels. */
 948     int *indents;
 949
 950     /** The size of the indents stack. */
 951     size_t indents_size;
 952
 953     /** The number of items in the indents stack. */
 954     size_t indents_length;
 955
 956     /** The current indentation level. */
 957     int indent;
 958
 959     /** May a simple key occur at the current position? */
 960     int simple_key_allowed;
 961
 962     /** The stack of potential simple keys. */
 963     yaml_simple_key_t **simple_keys;
 964
 965     /** The size of the simple keys stack. */
 966     size_t simple_keys_size;
 967
 968     /**
 969      * @}
 970      */
 971
 972     /**
 973      * @name Parser stuff
 974      * @{
 975      */
 976
 977     /** The parser states stack. */
 978     yaml_parser_state_t *states;
 979
 980     /** The size of the parser states stack. */
 981     size_t states_size;
 982
 983     /** The number of items in the parser states stack. */
 984     size_t states_length;
 985
 986     /** The current parser state. */
 987     yaml_parser_state_t state;
 988
 989     /** The stack of marks. */
 990     yaml_mark_t *marks;
 991
 992     /** The size of the marks stack. */
 993     size_t marks_size;
 994
 995     /** The number of items in the marks stack. */
 996     size_t marks_length;
 997
 998     /** The current event. */
 999     yaml_event_t *current_event;
1000
1001     /** The YAML version directive. */
1002     yaml_version_directive_t *version_directive;
1003
1004     /** The list of TAG directives. */
1005     yaml_tag_directive_t **tag_directives;
1006
1007     /** The size of the TAG directives list. */
1008     size_t tag_directives_size;
1009
1010     /** The number of items in the TAG directives list. */
1011     size_t tag_directives_length;
1012
1013     /**
1014      * @}
1015      */
1016
1017 } yaml_parser_t;
1018
1019 /**
1020  * Create a new parser.
1021  *
1022  * This function creates a new parser object.  An application is responsible
1023  * for destroying the object using the @c yaml_parser_delete function.
1024  *
1025  * @returns A new parser object; @c NULL on error.
1026  */
1027
1028 YAML_DECLARE(yaml_parser_t *)
1029 yaml_parser_new(void);
1030
1031 /**
1032  * Destroy a parser.
1033  *
1034  * @param[in]   parser  A parser object.
1035  */
1036
1037 YAML_DECLARE(void)
1038 yaml_parser_delete(yaml_parser_t *parser);
1039
1040 /**
1041  * Set a string input.
1042  *
1043  * Note that the @a input pointer must be valid while the @a parser object
1044  * exists.  The application is responsible for destroing @a input after
1045  * destroying the @a parser.
1046  *
1047  * @param[in]   parser  A parser object.
1048  * @param[in]   input   A source data.
1049  * @param[in]   size    The length of the source data in bytes.
1050  */
1051
1052 YAML_DECLARE(void)
1053 yaml_parser_set_input_string(yaml_parser_t *parser,
1054         unsigned char *input, size_t size);
1055
1056
1057 /**
1058  * Set a file input.
1059  *
1060  * @a file should be a file object open for reading.  The application is
1061  * responsible for closing the @a file.
1062  *
1063  * @param[in]   parser  A parser object.
1064  * @param[in]   file    An open file.
1065  */
1066
1067 YAML_DECLARE(void)
1068 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
1069
1070 /**
1071  * Set a generic input handler.
1072  *
1073  * @param[in]   parser  A parser object.
1074  * @param[in]   handler A read handler.
1075  * @param[in]   data    Any application data for passing to the read handler.
1076  */
1077
1078 YAML_DECLARE(void)
1079 yaml_parser_set_input(yaml_parser_t *parser,
1080         yaml_read_handler_t *handler, void *data);
1081
1082 /**
1083  * Set the source encoding.
1084  *
1085  * @param[in]   parser      A parser object.
1086  * @param[in]   encoding    The source encoding.
1087  */
1088
1089 YAML_DECLARE(void)
1090 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1091
1092 /**
1093  * Get the next token.
1094  *
1095  * The token is removed from the internal token queue and the application is
1096  * responsible for destroing the token object.
1097  *
1098  * @param[in]   parser      A parser object.
1099  *
1100  * @returns A token object, or @c NULL on error.
1101  */
1102
1103 YAML_DECLARE(yaml_token_t *)
1104 yaml_parser_get_token(yaml_parser_t *parser);
1105
1106 /**
1107  * Peek the next token.
1108  *
1109  * The token is not removed from the internal token queue and will be returned
1110  * again on a subsequent call of @c yaml_parser_get_token or
1111  * @c yaml_parser_peek_token. The application should not destroy the token
1112  * object.
1113  *
1114  * @param[in]   parser      A parser object.
1115  *
1116  * @returns A token object, or @c NULL on error.
1117  */
1118
1119 YAML_DECLARE(yaml_token_t *)
1120 yaml_parser_peek_token(yaml_parser_t *parser);
1121
1122 /**
1123  * Get the next event.
1124  *
1125  * The application is responsible for destroing the event object.
1126  *
1127  * @param[in]   parser      A parser object.
1128  *
1129  * @returns An event object, or @c NULL on error.
1130  */
1131
1132 YAML_DECLARE(yaml_event_t *)
1133 yaml_parser_get_event(yaml_parser_t *parser);
1134
1135 /**
1136  * Peek the next event.
1137  *
1138  * The event will be returned again on a subsequent call of
1139  * @c yaml_parser_get_event or @c yaml_parser_peek_event.  The application
1140  * should not destroy the event object.
1141  *
1142  * @param[in]   parser      A parser object.
1143  *
1144  * @returns An event object, or @c NULL on error.
1145  */
1146
1147 YAML_DECLARE(yaml_event_t *)
1148 yaml_parser_peek_event(yaml_parser_t *parser);
1149
1150 /** @} */
1151
1152 /*
1153 typedef struct {
1154 } yaml_emitter_t;
1155 */
1156
1157 /**
1158  * @defgroup internal Internal Definitions
1159  * @{
1160  */
1161
1162 /**
1163  * Allocate a dynamic memory block.
1164  *
1165  * @param[in]   size    Size of a memory block, \c 0 is valid.
1166  *
1167  * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
1168  * or @c NULL if it failed.
1169  */
1170
1171 YAML_DECLARE(void *)
1172 yaml_malloc(size_t size);
1173
1174 /**
1175  * Reallocate a dynamic memory block.
1176  *
1177  * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
1178  *                      valid.
1179  * @param[in]   size    A size of a new block, \c 0 is valid.
1180  *
1181  * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
1182  * or @c NULL if it failed.
1183  */
1184
1185 YAML_DECLARE(void *)
1186 yaml_realloc(void *ptr, size_t size);
1187
1188 /**
1189  * Free a dynamic memory block.
1190  *
1191  * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
1192  *                      valid.
1193  */
1194
1195 YAML_DECLARE(void)
1196 yaml_free(void *ptr);
1197
1198 /** The initial size for various buffers. */
1199
1200 #define YAML_DEFAULT_SIZE   16
1201
1202 /** The size of the raw buffer. */
1203
1204 #define YAML_RAW_BUFFER_SIZE 16384
1205
1206 /**
1207  * The size of the buffer.
1208  *
1209  * We allocate enough space for decoding the whole raw buffer.
1210  */
1211
1212 #define YAML_BUFFER_SIZE    (YAML_RAW_BUFFER_SIZE*3)
1213
1214 /**
1215  * Ensure that the buffer contains at least @a length characters.
1216  *
1217  * @param[in]   parser  A parser object.
1218  * @param[in]   length  The number of characters in the buffer.
1219  *
1220  * @returns @c 1 on success, @c 0 on error.
1221  */
1222
1223 YAML_DECLARE(int)
1224 yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
1225
1226 /** @} */
1227
1228
1229 #ifdef __cplusplus
1230 }
1231 #endif
1232
1233 #endif /* #ifndef YAML_H */
1234