include/yaml.h

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