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 parser structure.
 794  *
 795  * All members are internal.  Manage the structure using the @c yaml_parser_
 796  * family of functions.
 797  */
 798
 799 typedef struct {
 800
 801     /**
 802      * @name Error handling
 803      * @{
 804      */
 805
 806     /** Error type. */
 807     yaml_error_type_t error;
 808
 809     /** Error description. */
 810     const char *problem;
 811
 812     /** The byte about which the problem occured. */
 813     size_t problem_offset;
 814
 815     /** The problematic value (@c -1 is none). */
 816     int problem_value;
 817
 818     /** The problem position. */
 819     yaml_mark_t problem_mark;
 820
 821     /** The error context. */
 822     const char *context;
 823
 824     /** The context position. */
 825     yaml_mark_t context_mark;
 826
 827     /**
 828      * @}
 829      */
 830
 831     /**
 832      * @name Reader stuff
 833      * @{
 834      */
 835
 836     /** Read handler. */
 837     yaml_read_handler_t *read_handler;
 838
 839     /** A pointer for passing to the read handler. */
 840     void *read_handler_data;
 841
 842     /** EOF flag */
 843     int eof;
 844
 845     /** The pointer to the beginning of the working buffer. */
 846     yaml_char_t *buffer;
 847
 848     /** The pointer to the end of the working buffer. */
 849     yaml_char_t *buffer_end;
 850
 851     /** The pointer to the current character in the working buffer. */
 852     yaml_char_t *pointer;
 853
 854     /** The number of unread characters in the working buffer. */
 855     size_t unread;
 856
 857     /** The pointer to the beginning of the raw buffer. */
 858     unsigned char *raw_buffer;
 859
 860     /** The pointer to the current character in the raw buffer. */
 861     unsigned char *raw_pointer;
 862
 863     /** The number of unread bytes in the raw buffer. */
 864     size_t raw_unread;
 865
 866     /** The input encoding. */
 867     yaml_encoding_t encoding;
 868
 869     /** The offset of the current position (in bytes). */
 870     size_t offset;
 871
 872     /** The index of the current position (in characters). */
 873     size_t index;
 874
 875     /** The line of the current position (starting from @c 0). */
 876     size_t line;
 877
 878     /** The column of the current position (starting from @c 0). */
 879     size_t column;
 880
 881     /* String input structure. */
 882     yaml_string_input_t string_input;
 883
 884     /**
 885      * @}
 886      */
 887
 888     /**
 889      * @name Scanner stuff
 890      * @{
 891      */
 892
 893     /** Have we started to scan the input stream? */
 894     int stream_start_produced;
 895
 896     /** Have we reached the end of the input stream? */
 897     int stream_end_produced;
 898
 899     /** The number of unclosed '[' and '{' indicators. */
 900     int flow_level;
 901
 902     /** The tokens queue, which contains the current produced tokens. */
 903     yaml_token_t **tokens;
 904
 905     /** The size of the tokens queue. */
 906     size_t tokens_size;
 907
 908     /** The head of the tokens queue. */
 909     size_t tokens_head;
 910
 911     /** The tail of the tokens queue. */
 912     size_t tokens_tail;
 913
 914     /** The number of tokens fetched from the tokens queue. */
 915     size_t tokens_parsed;
 916
 917     /** The stack of indentation levels. */
 918     int *indents;
 919
 920     /** The size of the indents stack. */
 921     size_t indents_size;
 922
 923     /** The number of items in the indents stack. */
 924     size_t indents_length;
 925
 926     /** The current indentation level. */
 927     int indent;
 928
 929     /** May a simple key occur at the current position? */
 930     int simple_key_allowed;
 931
 932     /** The stack of potential simple keys. */
 933     yaml_simple_key_t **simple_keys;
 934
 935     /** The size of the simple keys stack. */
 936     size_t simple_keys_size;
 937
 938     /**
 939      * @}
 940      */
 941
 942 } yaml_parser_t;
 943
 944 /**
 945  * Create a new parser.
 946  *
 947  * This function creates a new parser object.  An application is responsible
 948  * for destroying the object using the @c yaml_parser_delete function.
 949  *
 950  * @returns A new parser object; @c NULL on error.
 951  */
 952
 953 YAML_DECLARE(yaml_parser_t *)
 954 yaml_parser_new(void);
 955
 956 /**
 957  * Destroy a parser.
 958  *
 959  * @param[in]   parser  A parser object.
 960  */
 961
 962 YAML_DECLARE(void)
 963 yaml_parser_delete(yaml_parser_t *parser);
 964
 965 /**
 966  * Set a string input.
 967  *
 968  * Note that the @a input pointer must be valid while the @a parser object
 969  * exists.  The application is responsible for destroing @a input after
 970  * destroying the @a parser.
 971  *
 972  * @param[in]   parser  A parser object.
 973  * @param[in]   input   A source data.
 974  * @param[in]   size    The length of the source data in bytes.
 975  */
 976
 977 YAML_DECLARE(void)
 978 yaml_parser_set_input_string(yaml_parser_t *parser,
 979         unsigned char *input, size_t size);
 980
 981
 982 /**
 983  * Set a file input.
 984  *
 985  * @a file should be a file object open for reading.  The application is
 986  * responsible for closing the @a file.
 987  *
 988  * @param[in]   parser  A parser object.
 989  * @param[in]   file    An open file.
 990  */
 991
 992 YAML_DECLARE(void)
 993 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
 994
 995 /**
 996  * Set a generic input handler.
 997  *
 998  * @param[in]   parser  A parser object.
 999  * @param[in]   handler A read handler.
1000  * @param[in]   data    Any application data for passing to the read handler.
1001  */
1002
1003 YAML_DECLARE(void)
1004 yaml_parser_set_input(yaml_parser_t *parser,
1005         yaml_read_handler_t *handler, void *data);
1006
1007 /**
1008  * Set the source encoding.
1009  *
1010  * @param[in]   parser      A parser object.
1011  * @param[in]   encoding    The source encoding.
1012  */
1013
1014 YAML_DECLARE(void)
1015 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1016
1017 /**
1018  * Get the next token.
1019  *
1020  * The token is removed from the internal token queue and the application is
1021  * responsible for destroing the token object.
1022  *
1023  * @param[in]   parser      A parser object.
1024  *
1025  * @returns A token object, or @c NULL on error.
1026  */
1027
1028 YAML_DECLARE(yaml_token_t *)
1029 yaml_parser_get_token(yaml_parser_t *parser);
1030
1031 /**
1032  * Peek the next token.
1033  *
1034  * The token is not removed from the internal token queue and will be returned
1035  * again on a subsequent call of @c yaml_parser_get_token or
1036  * @c yaml_parser_peek_token. The application should not destroy the token
1037  * object.
1038  *
1039  * @param[in]   parser      A parser object.
1040  *
1041  * @returns A token object, or @c NULL on error.
1042  */
1043
1044 YAML_DECLARE(yaml_token_t *)
1045 yaml_parser_peek_token(yaml_parser_t *parser);
1046
1047 /** @} */
1048
1049 /*
1050 typedef struct {
1051 } yaml_emitter_t;
1052 */
1053
1054 /**
1055  * @defgroup internal Internal Definitions
1056  * @{
1057  */
1058
1059 /**
1060  * Allocate a dynamic memory block.
1061  *
1062  * @param[in]   size    Size of a memory block, \c 0 is valid.
1063  *
1064  * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
1065  * or @c NULL if it failed.
1066  */
1067
1068 YAML_DECLARE(void *)
1069 yaml_malloc(size_t size);
1070
1071 /**
1072  * Reallocate a dynamic memory block.
1073  *
1074  * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
1075  *                      valid.
1076  * @param[in]   size    A size of a new block, \c 0 is valid.
1077  *
1078  * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
1079  * or @c NULL if it failed.
1080  */
1081
1082 YAML_DECLARE(void *)
1083 yaml_realloc(void *ptr, size_t size);
1084
1085 /**
1086  * Free a dynamic memory block.
1087  *
1088  * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
1089  *                      valid.
1090  */
1091
1092 YAML_DECLARE(void)
1093 yaml_free(void *ptr);
1094
1095 /** The initial size for various buffers. */
1096
1097 #define YAML_DEFAULT_SIZE   16
1098
1099 /** The size of the raw buffer. */
1100
1101 #define YAML_RAW_BUFFER_SIZE 16384
1102
1103 /**
1104  * The size of the buffer.
1105  *
1106  * We allocate enough space for decoding the whole raw buffer.
1107  */
1108
1109 #define YAML_BUFFER_SIZE    (YAML_RAW_BUFFER_SIZE*3)
1110
1111 /**
1112  * Ensure that the buffer contains at least @a length characters.
1113  *
1114  * @param[in]   parser  A parser object.
1115  * @param[in]   length  The number of characters in the buffer.
1116  *
1117  * @returns @c 1 on success, @c 0 on error.
1118  */
1119
1120 YAML_DECLARE(int)
1121 yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
1122
1123 /** @} */
1124
1125
1126 #ifdef __cplusplus
1127 }
1128 #endif
1129
1130 #endif /* #ifndef YAML_H */
1131