include/yaml/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 stream encoding. */
  81 typedef enum {
  82     YAML_ANY_ENCODING,
  83     YAML_UTF8_ENCODING,
  84     YAML_UTF16LE_ENCODING,
  85     YAML_UTF16BE_ENCODING
  86 } yaml_encoding_t;
  87
  88 /** Many bad things could happen with the parser and emitter. */
  89 typedef enum {
  90     YAML_NO_ERROR,
  91
  92     YAML_MEMORY_ERROR,
  93
  94     YAML_READER_ERROR,
  95     YAML_SCANNER_ERROR,
  96     YAML_PARSER_ERROR,
  97
  98     YAML_WRITER_ERROR,
  99     YAML_EMITTER_ERROR
 100 } yaml_error_type_t;
 101
 102 /** The pointer position. */
 103 typedef struct {
 104     /** The position index. */
 105     size_t index;
 106
 107     /** The position line. */
 108     size_t line;
 109
 110     /** The position column. */
 111     size_t column;
 112 } yaml_mark_t;
 113
 114 /** @} */
 115
 116 /**
 117  * @defgroup styles Node Styles
 118  * @{
 119  */
 120
 121 /** Scalar styles. */
 122 typedef enum {
 123     YAML_ANY_SCALAR_STYLE,
 124
 125     YAML_PLAIN_SCALAR_STYLE,
 126
 127     YAML_SINGLE_QUOTED_SCALAR_STYLE,
 128     YAML_DOUBLE_QUOTED_SCALAR_STYLE,
 129
 130     YAML_LITERAL_SCALAR_STYLE,
 131     YAML_FOLDED_SCALAR_STYLE
 132 } yaml_scalar_style_t;
 133
 134
 135 /** Sequence styles. */
 136 typedef enum {
 137     YAML_ANY_SEQUENCE_STYLE,
 138
 139     YAML_BLOCK_SEQUENCE_STYLE,
 140     YAML_FLOW_SEQUENCE_STYLE
 141 } yaml_sequence_style_t;
 142
 143 /** Mapping styles. */
 144 typedef enum {
 145     YAML_ANY_MAPPING_STYLE,
 146
 147     YAML_BLOCK_MAPPING_STYLE,
 148     YAML_FLOW_MAPPING_STYLE
 149 } yaml_mapping_style_t;
 150
 151 /** @} */
 152
 153 /**
 154  * @defgroup tokens Tokens
 155  * @{
 156  */
 157
 158 /** Token types. */
 159 typedef enum {
 160     YAML_STREAM_START_TOKEN,
 161     YAML_STREAM_END_TOKEN,
 162
 163     YAML_VERSION_DIRECTIVE_TOKEN,
 164     YAML_TAG_DIRECTIVE_TOKEN,
 165     YAML_DOCUMENT_START_TOKEN,
 166     YAML_DOCUMENT_END_TOKEN,
 167
 168     YAML_BLOCK_SEQUENCE_START_TOKEN,
 169     YAML_BLOCK_MAPPING_START_TOKEN,
 170     YAML_BLOCK_END_TOKEN,
 171
 172     YAML_FLOW_SEQUENCE_START_TOKEN,
 173     YAML_FLOW_SEQUENCE_END_TOKEN,
 174     YAML_FLOW_MAPPING_START_TOKEN,
 175     YAML_FLOW_MAPPING_END_TOKEN,
 176
 177     YAML_BLOCK_ENTRY_TOKEN,
 178     YAML_FLOW_ENTRY_TOKEN,
 179     YAML_KEY_TOKEN,
 180     YAML_VALUE_TOKEN,
 181
 182     YAML_ALIAS_TOKEN,
 183     YAML_ANCHOR_TOKEN,
 184     YAML_TAG_TOKEN,
 185     YAML_SCALAR_TOKEN
 186 } yaml_token_type_t;
 187
 188 /** The token structure. */
 189 typedef struct {
 190
 191     /** The token type. */
 192     yaml_token_type_t type;
 193
 194     /** The token data. */
 195     union {
 196
 197         /** The stream encoding (for @c YAML_STREAM_START_TOKEN). */
 198         yaml_encoding_t encoding;
 199
 200         /** The anchor (for @c YAML_ALIAS_TOKEN and @c YAML_ANCHOR_TOKEN). */
 201         yaml_char_t *anchor;
 202
 203         /** The tag (for @c YAML_TAG_TOKEN). */
 204         struct {
 205             /** The tag handle. */
 206             yaml_char_t *handle;
 207
 208             /** The tag suffix. */
 209             yaml_char_t *suffix;
 210         } tag;
 211
 212         /** The scalar value (for @c YAML_SCALAR_TOKEN). */
 213         struct {
 214
 215             /** The scalar value. */
 216             yaml_char_t *value;
 217
 218             /** The length of the scalar value. */
 219             size_t length;
 220
 221             /** The scalar style. */
 222             yaml_scalar_style_t style;
 223         } scalar;
 224
 225         /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
 226         struct {
 227             /** The major version number. */
 228             int major;
 229
 230             /** The minor version number. */
 231             int minor;
 232         } version_directive;
 233
 234         /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
 235         struct {
 236             /** The tag handle. */
 237             yaml_char_t *handle;
 238
 239             /** The tag prefix. */
 240             yaml_char_t *prefix;
 241         } tag_directive;
 242     } data;
 243
 244     /** The beginning of the token. */
 245     yaml_mark_t start_mark;
 246
 247     /** The end of the token. */
 248     yaml_mark_t end_mark;
 249
 250 } yaml_token_t;
 251
 252 /**
 253  * Create a new token without assigning any data.
 254  *
 255  * This function can be used for constructing indicator tokens:
 256  * @c YAML_DOCUMENT_START, @c YAML_DOCUMENT_END,
 257  * @c YAML_BLOCK_SEQUENCE_START_TOKEN, @c YAML_BLOCK_MAPPING_START_TOKEN,
 258  * @c YAML_BLOCK_END_TOKEN,
 259  * @c YAML_FLOW_SEQUENCE_START_TOKEN, @c YAML_FLOW_SEQUENCE_END_TOKEN,
 260  * @c YAML_FLOW_MAPPING_START_TOKEN, @c YAML_FLOW_MAPPING_END_TOKEN,
 261  * @c YAML_BLOCK_ENTRY_TOKEN, @c YAML_FLOW_ENTRY_TOKEN,
 262  * @c YAML_KEY_TOKEN, @c YAML_VALUE_TOKEN.
 263  *
 264  * @param[in]   type        The token type.
 265  * @param[in]   start_mark  The beginning of the token.
 266  * @param[in]   end_mark    The end of the token.
 267  *
 268  * @returns A new token object, or @c NULL on error.
 269  */
 270
 271 YAML_DECLARE(yaml_token_t *)
 272 yaml_token_new(yaml_token_type_t type,
 273         yaml_mark_t start_mark, yaml_mark_t end_mark);
 274
 275 /**
 276  * Create a new @c YAML_STREAM_START_TOKEN token with the specified encoding.
 277  *
 278  * @param[in]   encoding    The stream encoding.
 279  * @param[in]   start_mark  The beginning of the token.
 280  * @param[in]   end_mark    The end of the token.
 281  *
 282  * @returns A new token object, or @c NULL on error.
 283  */
 284
 285 YAML_DECLARE(yaml_token_t *)
 286 yaml_stream_start_token_new(yaml_encoding_t encoding,
 287         yaml_mark_t start_mark, yaml_mark_t end_mark);
 288
 289 /**
 290  * Create a new @c YAML_STREAM_END_TOKEN token.
 291  *
 292  * @param[in]   start_mark  The beginning of the token.
 293  * @param[in]   end_mark    The end of the token.
 294  *
 295  * @returns A new token object, or @c NULL on error.
 296  */
 297
 298 YAML_DECLARE(yaml_token_t *)
 299 yaml_stream_end_token_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
 300
 301 /**
 302  * Create a new @c YAML_VERSION_DIRECTIVE_TOKEN token with the specified
 303  * version numbers.
 304  *
 305  * @param[in]   major       The major version number.
 306  * @param[in]   minor       The minor version number.
 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_version_directive_token_new(int major, int minor,
 315         yaml_mark_t start_mark, yaml_mark_t end_mark);
 316
 317 /**
 318  * Create a new @c YAML_TAG_DIRECTIVE_TOKEN token with the specified tag
 319  * handle and prefix.
 320  *
 321  * Note that the @a handle and the @a prefix pointers will be freed by
 322  * the token descructor.
 323  *
 324  * @param[in]   handle      The tag handle.
 325  * @param[in]   prefix      The tag prefix.
 326  * @param[in]   start_mark  The beginning of the token.
 327  * @param[in]   end_mark    The end of the token.
 328  *
 329  * @returns A new token object, or @c NULL on error.
 330  */
 331
 332 YAML_DECLARE(yaml_token_t *)
 333 yaml_tag_directive_token_new(yaml_char_t *handle, yaml_char_t *prefix,
 334         yaml_mark_t start_mark, yaml_mark_t end_mark);
 335
 336 /**
 337  * Create a new @c YAML_ALIAS_TOKEN token with the specified anchor.
 338  *
 339  * Note that the @a anchor pointer will be freed by the token descructor.
 340  *
 341  * @param[in]   anchor      The anchor.
 342  * @param[in]   start_mark  The beginning of the token.
 343  * @param[in]   end_mark    The end of the token.
 344  *
 345  * @returns A new token object, or @c NULL on error.
 346  */
 347
 348 YAML_DECLARE(yaml_token_t *)
 349 yaml_alias_token_new(yaml_char_t *anchor,
 350         yaml_mark_t start_mark, yaml_mark_t end_mark);
 351
 352 /**
 353  * Create a new @c YAML_ANCHOR_TOKEN token with the specified anchor.
 354  *
 355  * Note that the @a anchor pointer will be freed by the token descructor.
 356  *
 357  * @param[in]   anchor      The anchor.
 358  * @param[in]   start_mark  The beginning of the token.
 359  * @param[in]   end_mark    The end of the token.
 360  *
 361  * @returns A new token object, or @c NULL on error.
 362  */
 363
 364 YAML_DECLARE(yaml_token_t *)
 365 yaml_anchor_token_new(yaml_char_t *anchor,
 366         yaml_mark_t start_mark, yaml_mark_t end_mark);
 367
 368 /**
 369  * Create a new @c YAML_TAG_TOKEN token with the specified tag handle and
 370  * suffix.
 371  *
 372  * Note that the @a handle and the @a suffix pointers will be freed by
 373  * the token descructor.
 374  *
 375  * @param[in]   handle      The tag handle.
 376  * @param[in]   suffix      The tag suffix.
 377  * @param[in]   start_mark  The beginning of the token.
 378  * @param[in]   end_mark    The end of the token.
 379  *
 380  * @returns A new token object, or @c NULL on error.
 381  */
 382
 383 YAML_DECLARE(yaml_token_t *)
 384 yaml_tag_token_new(yaml_char_t *handle, yaml_char_t *suffix,
 385         yaml_mark_t start_mark, yaml_mark_t end_mark);
 386
 387 /**
 388  * Create a new @c YAML_SCALAR_TOKEN token with the specified scalar value,
 389  * length, and style.
 390  *
 391  * Note that the scalar value may contain the @c NUL character, therefore
 392  * the value length is also required.  The scalar value always ends with
 393  * @c NUL.
 394  *
 395  * Note that the @a value pointer will be freed by the token descructor.
 396  *
 397  * @param[in]   value       The scalar value.
 398  * @param[in]   length      The value length.
 399  * @param[in]   style       The scalar style.
 400  * @param[in]   start_mark  The beginning of the token.
 401  * @param[in]   end_mark    The end of the token.
 402  *
 403  * @returns A new token object, or @c NULL on error.
 404  */
 405
 406 YAML_DECLARE(yaml_token_t *)
 407 yaml_scalar_token_new(yaml_char_t *value, size_t length,
 408         yaml_scalar_style_t style,
 409         yaml_mark_t start_mark, yaml_mark_t end_mark);
 410
 411 /**
 412  * Destroy a token object.
 413  *
 414  * @param[in]   token   A token object.
 415  */
 416
 417 YAML_DECLARE(void)
 418 yaml_token_delete(yaml_token_t *token);
 419
 420 /** @} */
 421
 422 /*
 423
 424 typedef enum {
 425     YAML_STREAM_START_EVENT,
 426     YAML_STREAM_END_EVENT,
 427
 428     YAML_DOCUMENT_START_EVENT,
 429     YAML_DOCUMENT_END_EVENT,
 430
 431     YAML_ALIAS_EVENT,
 432     YAML_SCALAR_EVENT,
 433
 434     YAML_SEQUENCE_START_EVENT,
 435     YAML_SEQUENCE_END_EVENT,
 436
 437     YAML_MAPPING_START_EVENT,
 438     YAML_MAPPING_END_EVENT
 439 } yaml_event_type_t;
 440
 441 typedef struct {
 442     yaml_event_type_t type;
 443     union {
 444         struct {
 445             yaml_encoding_t encoding;
 446         } stream_start;
 447         struct {
 448             struct {
 449                 int major;
 450                 int minor;
 451             } version;
 452             struct {
 453                 char *handle;
 454                 char *prefix;
 455             } **tag_pairs;
 456             int implicit;
 457         } document_start;
 458         struct {
 459             int implicit;
 460         } document_end;
 461         struct {
 462             char *anchor;
 463         } alias;
 464         struct {
 465             char *anchor;
 466             char *tag;
 467             char *value;
 468             size_t length;
 469             int plain_implicit;
 470             int quoted_implicit;
 471             yaml_scalar_style_t style;
 472         } scalar;
 473         struct {
 474             char *anchor;
 475             char *tag;
 476             int implicit;
 477             yaml_sequence_style_t style;
 478         } sequence_start;
 479         struct {
 480             char *anchor;
 481             char *tag;
 482             int implicit;
 483             yaml_mapping_style_t style;
 484         } mapping_start;
 485     } data;
 486     yaml_mark_t start_mark;
 487     yaml_mark_t end_mark;
 488 } yaml_event_t;
 489
 490 */
 491
 492
 493 /**
 494  * @defgroup parser Parser Definitions
 495  * @{
 496  */
 497
 498 /**
 499  * The prototype of a read handler.
 500  *
 501  * The read handler is called when the parser needs to read more bytes from the
 502  * source.  The handler should write not more than @a size bytes to the @a
 503  * buffer.  The number of written bytes should be set to the @a length variable.
 504  *
 505  * @param[in]   data        A pointer to an application data specified by
 506  *                          @c yaml_parser_set_read_handler.
 507  * @param[out]  buffer      The buffer to write the data from the source.
 508  * @param[in]   size        The size of the buffer.
 509  * @param[out]  size_read   The actual number of bytes read from the source.
 510  *
 511  * @returns On success, the handler should return @c 1.  If the handler failed,
 512  * the returned value should be @c 0.  On EOF, the handler should set the
 513  * @a length to @c 0 and return @c 1.
 514  */
 515
 516 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
 517         size_t *size_read);
 518
 519 /**
 520  * This structure holds a string input specified by
 521  * @c yaml_parser_set_input_string.
 522  */
 523
 524 typedef struct {
 525     /** The string start pointer. */
 526     unsigned char *start;
 527
 528     /** The string end pointer. */
 529     unsigned char *end;
 530
 531     /** The string current position. */
 532     unsigned char *current;
 533 } yaml_string_input_t;
 534
 535 /**
 536  * This structure holds information about a potential simple key.
 537  */
 538
 539 typedef struct {
 540     /** Is a simple key possible? */
 541     int possible;
 542
 543     /** Is a simple key required? */
 544     int required;
 545
 546     /** The number of the token. */
 547     size_t token_number;
 548
 549     /** The position index. */
 550     size_t index;
 551
 552     /** The position line. */
 553     size_t line;
 554
 555     /** The position column. */
 556     size_t column;
 557
 558     /** The position mark. */
 559     yaml_mark_t mark;
 560 } yaml_simple_key_t;
 561
 562 /**
 563  * The parser structure.
 564  *
 565  * All members are internal.  Manage the structure using the @c yaml_parser_
 566  * family of functions.
 567  */
 568
 569 typedef struct {
 570
 571     /**
 572      * @name Error handling
 573      * @{
 574      */
 575
 576     /** Error type. */
 577     yaml_error_type_t error;
 578
 579     /** Error description. */
 580     const char *problem;
 581
 582     /** The byte about which the problem occured. */
 583     size_t problem_offset;
 584
 585     /** The problematic value (@c -1 is none). */
 586     int problem_value;
 587
 588     /**
 589      * @}
 590      */
 591
 592     /**
 593      * @name Reader stuff
 594      * @{
 595      */
 596
 597     /** Read handler. */
 598     yaml_read_handler_t *read_handler;
 599
 600     /** A pointer for passing to the read handler. */
 601     void *read_handler_data;
 602
 603     /** EOF flag */
 604     int eof;
 605
 606     /** The pointer to the beginning of the working buffer. */
 607     yaml_char_t *buffer;
 608
 609     /** The pointer to the end of the working buffer. */
 610     yaml_char_t *buffer_end;
 611
 612     /** The pointer to the current character in the working buffer. */
 613     yaml_char_t *pointer;
 614
 615     /** The number of unread characters in the working buffer. */
 616     size_t unread;
 617
 618     /** The pointer to the beginning of the raw buffer. */
 619     unsigned char *raw_buffer;
 620
 621     /** The pointer to the current character in the raw buffer. */
 622     unsigned char *raw_pointer;
 623
 624     /** The number of unread bytes in the raw buffer. */
 625     size_t raw_unread;
 626
 627     /** The input encoding. */
 628     yaml_encoding_t encoding;
 629
 630     /** The offset of the current position (in bytes). */
 631     size_t offset;
 632
 633     /** The index of the current position (in characters). */
 634     size_t index;
 635
 636     /** The line of the current position (starting from @c 0). */
 637     size_t line;
 638
 639     /** The column of the current position (starting from @c 0). */
 640     size_t column;
 641
 642     /* String input structure. */
 643     yaml_string_input_t string_input;
 644
 645     /**
 646      * @}
 647      */
 648
 649     /**
 650      * @name Scanner stuff
 651      * @{
 652      */
 653
 654     /** Have we started to scan the input stream? */
 655     int stream_start_produced;
 656
 657     /** Have we reached the end of the input stream? */
 658     int stream_end_produced;
 659
 660     /** The number of unclosed '[' and '{' indicators. */
 661     int flow_level;
 662
 663     /** The tokens queue, which contains the current produced tokens. */
 664     yaml_token_t *tokens;
 665
 666     /** The size of the tokens queue. */
 667     size_t tokens_size;
 668
 669     /** The head of the tokens queue. */
 670     size_t tokens_head;
 671
 672     /** The tail of the tokens queue. */
 673     size_t tokens_tail;
 674
 675     /** The number of tokens fetched from the tokens queue. */
 676     size_t tokens_parsed;
 677
 678     /** The stack of indentation levels. */
 679     int *indents;
 680
 681     /** The size of the indents stack. */
 682     size_t indents_size;
 683
 684     /** The number of items in the indents stack. */
 685     size_t indents_length;
 686
 687     /** The current indentation level. */
 688     int indent;
 689
 690     /** May a simple key occur at the current position? */
 691     int simple_key_allowed;
 692
 693     /** The stack of potential simple keys. */
 694     yaml_simple_key_t *simple_keys;
 695
 696     /** The size of the simple keys stack. */
 697     size_t simple_keys_size;
 698
 699     /**
 700      * @}
 701      */
 702
 703 } yaml_parser_t;
 704
 705 /**
 706  * Create a new parser.
 707  *
 708  * This function creates a new parser object.  An application is responsible
 709  * for destroying the object using the @c yaml_parser_delete function.
 710  *
 711  * @returns A new parser object; @c NULL on error.
 712  */
 713
 714 YAML_DECLARE(yaml_parser_t *)
 715 yaml_parser_new(void);
 716
 717 /**
 718  * Destroy a parser.
 719  *
 720  * @param[in]   parser  A parser object.
 721  */
 722
 723 YAML_DECLARE(void)
 724 yaml_parser_delete(yaml_parser_t *parser);
 725
 726 /**
 727  * Set a string input.
 728  *
 729  * Note that the @a input pointer must be valid while the @a parser object
 730  * exists.  The application is responsible for destroing @a input after
 731  * destroying the @a parser.
 732  *
 733  * @param[in]   parser  A parser object.
 734  * @param[in]   input   A source data.
 735  * @param[in]   size    The length of the source data in bytes.
 736  */
 737
 738 YAML_DECLARE(void)
 739 yaml_parser_set_input_string(yaml_parser_t *parser,
 740         unsigned char *input, size_t size);
 741
 742
 743 /**
 744  * Set a file input.
 745  *
 746  * @a file should be a file object open for reading.  The application is
 747  * responsible for closing the @a file.
 748  *
 749  * @param[in]   parser  A parser object.
 750  * @param[in]   file    An open file.
 751  */
 752
 753 YAML_DECLARE(void)
 754 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
 755
 756 /**
 757  * Set a generic input handler.
 758  *
 759  * @param[in]   parser  A parser object.
 760  * @param[in]   handler A read handler.
 761  * @param[in]   data    Any application data for passing to the read handler.
 762  */
 763
 764 YAML_DECLARE(void)
 765 yaml_parser_set_input(yaml_parser_t *parser,
 766         yaml_read_handler_t *handler, void *data);
 767
 768 /**
 769  * Set the source encoding.
 770  *
 771  * @param[in]   parser      A parser object.
 772  * @param[in]   encoding    The source encoding.
 773  */
 774
 775 YAML_DECLARE(void)
 776 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
 777
 778 /**
 779  * Get the next token.
 780  *
 781  * The token is removed from the internal token queue and the application is
 782  * responsible for destroing the token object.
 783  *
 784  * @param[in]   parser      A parser object.
 785  *
 786  * @returns A token object, or @c NULL on error.
 787  */
 788
 789 YAML_DECLARE(yaml_token_t *)
 790 yaml_parser_get_token(yaml_parser_t *parser);
 791
 792 /**
 793  * Peek the next token.
 794  *
 795  * The token is not removed from the internal token queue and will be returned
 796  * again on a subsequent call of @c yaml_parser_get_token or
 797  * @c yaml_parser_peek_token. The application should not destroy the token
 798  * object.
 799  *
 800  * @param[in]   parser      A parser object.
 801  *
 802  * @returns A token object, or @c NULL on error.
 803  */
 804
 805 YAML_DECLARE(yaml_token_t *)
 806 yaml_parser_peek_token(yaml_parser_t *parser);
 807
 808 /** @} */
 809
 810 /*
 811 typedef struct {
 812 } yaml_emitter_t;
 813 */
 814
 815 /**
 816  * @defgroup internal Internal Definitions
 817  * @{
 818  */
 819
 820 /**
 821  * Allocate a dynamic memory block.
 822  *
 823  * @param[in]   size    Size of a memory block, \c 0 is valid.
 824  *
 825  * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
 826  * or @c NULL if it failed.
 827  */
 828
 829 YAML_DECLARE(void *)
 830 yaml_malloc(size_t size);
 831
 832 /**
 833  * Reallocate a dynamic memory block.
 834  *
 835  * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
 836  *                      valid.
 837  * @param[in]   size    A size of a new block, \c 0 is valid.
 838  *
 839  * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
 840  * or @c NULL if it failed.
 841  */
 842
 843 YAML_DECLARE(void *)
 844 yaml_realloc(void *ptr, size_t size);
 845
 846 /**
 847  * Free a dynamic memory block.
 848  *
 849  * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
 850  *                      valid.
 851  */
 852
 853 YAML_DECLARE(void)
 854 yaml_free(void *ptr);
 855
 856 /** The size of the raw buffer. */
 857
 858 #define YAML_RAW_BUFFER_SIZE 16384
 859
 860 /**
 861  * The size of the buffer.
 862  *
 863  * We allocate enough space for decoding the whole raw buffer.
 864  */
 865
 866 #define YAML_BUFFER_SIZE    (YAML_RAW_BUFFER_SIZE*3)
 867
 868 /**
 869  * Ensure that the buffer contains at least @a length characters.
 870  *
 871  * @param[in]   parser  A parser object.
 872  * @param[in]   length  The number of characters in the buffer.
 873  *
 874  * @returns @c 1 on success, @c 0 on error.
 875  */
 876
 877 YAML_DECLARE(int)
 878 yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
 879
 880 /** @} */
 881
 882
 883 #ifdef __cplusplus
 884 }
 885 #endif
 886
 887 #endif /* #ifndef YAML_H */
 888