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 version Version Information
  24  * @{
  25  */
  26
  27 /**
  28  * Get the library version as a string.
  29  *
  30  * @returns The function returns the pointer to a static string of the form
  31  * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version
  32  * number, and @c Z is the patch version number.
  33  */
  34
  35 const char *
  36 yaml_get_version_string(void);
  37
  38 /**
  39  * Get the library version numbers.
  40  *
  41  * @param[out]  major   Major version number.
  42  * @param[out]  minor   Minor version number.
  43  * @param[out]  patch   Patch version number.
  44  */
  45
  46 void
  47 yaml_get_version(int *major, int *minor, int *patch);
  48
  49 /** @} */
  50
  51 /**
  52  * @defgroup basic Basic Types
  53  * @{
  54  */
  55
  56 /** The character type. */
  57 typedef unsigned char yaml_char_t;
  58
  59 /** The stream encoding. */
  60 typedef enum {
  61     YAML_ANY_ENCODING,
  62     YAML_UTF8_ENCODING,
  63     YAML_UTF16LE_ENCODING,
  64     YAML_UTF16BE_ENCODING
  65 } yaml_encoding_t;
  66
  67 /** Many bad things could happen with the parser and emitter. */
  68 typedef enum {
  69     YAML_NO_ERROR,
  70
  71     YAML_MEMORY_ERROR,
  72
  73     YAML_READER_ERROR,
  74     YAML_SCANNER_ERROR,
  75     YAML_PARSER_ERROR,
  76
  77     YAML_WRITER_ERROR,
  78     YAML_EMITTER_ERROR
  79 } yaml_error_type_t;
  80
  81 /** @} */
  82
  83 /*
  84
  85 typedef enum {
  86     YAML_ANY_SCALAR_STYLE,
  87     YAML_PLAIN_SCALAR_STYLE,
  88     YAML_SINGLE_QUOTED_SCALAR_STYLE,
  89     YAML_DOUBLE_QUOTED_SCALAR_STYLE,
  90     YAML_LITERAL_SCALAR_STYLE,
  91     YAML_FOLDED_SCALAR_STYLE
  92 } yaml_scalar_style_t;
  93
  94 typedef enum {
  95     YAML_ANY_SEQUENCE_STYLE,
  96     YAML_BLOCK_SEQUENCE_STYLE,
  97     YAML_FLOW_SEQUENCE_STYLE
  98 } yaml_sequence_style_t;
  99
 100 typedef enum {
 101     YAML_ANY_MAPPING_STYLE,
 102     YAML_BLOCK_MAPPING_STYLE,
 103     YAML_FLOW_MAPPING_STYLE
 104 } yaml_mapping_style_t;
 105
 106 typedef enum {
 107     YAML_STREAM_START_TOKEN,
 108     YAML_STREAM_END_TOKEN,
 109
 110     YAML_VERSION_DIRECTIVE_TOKEN,
 111     YAML_TAG_DIRECTIVE_TOKEN,
 112     YAML_DOCUMENT_START_TOKEN,
 113     YAML_DOCUMENT_END_TOKEN,
 114
 115     YAML_BLOCK_SEQUENCE_START_TOKEN,
 116     YAML_BLOCK_MAPPING_START_TOKEN,
 117     YAML_BLOCK_END_TOKEN,
 118
 119     YAML_FLOW_SEQUENCE_START_TOKEN,
 120     YAML_FLOW_SEQUENCE_END_TOKEN,
 121     YAML_FLOW_MAPPING_START_TOKEN,
 122     YAML_FLOW_MAPPING_END_TOKEN,
 123
 124     YAML_BLOCK_ENTRY_TOKEN,
 125     YAML_FLOW_ENTRY_TOKEN,
 126     YAML_KEY_TOKEN,
 127     YAML_VALUE_TOKEN,
 128
 129     YAML_ALIAS_TOKEN,
 130     YAML_ANCHOR_TOKEN,
 131     YAML_TAG_TOKEN,
 132     YAML_SCALAR_TOKEN
 133 } yaml_token_type_t;
 134
 135 typedef enum {
 136     YAML_STREAM_START_EVENT,
 137     YAML_STREAM_END_EVENT,
 138
 139     YAML_DOCUMENT_START_EVENT,
 140     YAML_DOCUMENT_END_EVENT,
 141
 142     YAML_ALIAS_EVENT,
 143     YAML_SCALAR_EVENT,
 144
 145     YAML_SEQUENCE_START_EVENT,
 146     YAML_SEQUENCE_END_EVENT,
 147
 148     YAML_MAPPING_START_EVENT,
 149     YAML_MAPPING_END_EVENT
 150 } yaml_event_type_t;
 151
 152 typedef struct {
 153     size_t offset;
 154     size_t index;
 155     size_t line;
 156     size_t column;
 157 } yaml_mark_t;
 158
 159 typedef struct {
 160     yaml_error_type_t type;
 161     char *context;
 162     yaml_mark_t context_mark;
 163     char *problem;
 164     yaml_mark_t problem_mark;
 165 } yaml_error_t;
 166
 167 typedef struct {
 168     yaml_token_type_t type;
 169     union {
 170         yaml_encoding_t encoding;
 171         char *anchor;
 172         char *tag;
 173         struct {
 174             char *value;
 175             size_t length;
 176             yaml_scalar_style_t style;
 177         } scalar;
 178         struct {
 179             int major;
 180             int minor;
 181         } version;
 182         struct {
 183           char *handle;
 184           char *prefix;
 185         } tag_pair;
 186     } data;
 187     yaml_mark_t start_mark;
 188     yaml_mark_t end_mark;
 189 } yaml_token_t;
 190
 191 typedef struct {
 192     yaml_event_type_t type;
 193     union {
 194         struct {
 195             yaml_encoding_t encoding;
 196         } stream_start;
 197         struct {
 198             struct {
 199                 int major;
 200                 int minor;
 201             } version;
 202             struct {
 203                 char *handle;
 204                 char *prefix;
 205             } **tag_pairs;
 206             int implicit;
 207         } document_start;
 208         struct {
 209             int implicit;
 210         } document_end;
 211         struct {
 212             char *anchor;
 213         } alias;
 214         struct {
 215             char *anchor;
 216             char *tag;
 217             char *value;
 218             size_t length;
 219             int plain_implicit;
 220             int quoted_implicit;
 221             yaml_scalar_style_t style;
 222         } scalar;
 223         struct {
 224             char *anchor;
 225             char *tag;
 226             int implicit;
 227             yaml_sequence_style_t style;
 228         } sequence_start;
 229         struct {
 230             char *anchor;
 231             char *tag;
 232             int implicit;
 233             yaml_mapping_style_t style;
 234         } mapping_start;
 235     } data;
 236     yaml_mark_t start_mark;
 237     yaml_mark_t end_mark;
 238 } yaml_event_t;
 239
 240 */
 241
 242
 243 /**
 244  * @defgroup parser Parser Definitions
 245  * @{
 246  */
 247
 248 /**
 249  * The prototype of a read handler.
 250  *
 251  * The read handler is called when the parser needs to read more bytes from the
 252  * source.  The handler should write not more than @a size bytes to the @a
 253  * buffer.  The number of written bytes should be set to the @a length variable.
 254  *
 255  * @param[in]   data        A pointer to an application data specified by
 256  *                          @c yaml_parser_set_read_handler.
 257  * @param[out]  buffer      The buffer to write the data from the source.
 258  * @param[in]   size        The size of the buffer.
 259  * @param[out]  size_read   The actual number of bytes read from the source.
 260  *
 261  * @returns On success, the handler should return @c 1.  If the handler failed,
 262  * the returned value should be @c 0.  On EOF, the handler should set the
 263  * @a length to @c 0 and return @c 1.
 264  */
 265
 266 typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
 267         size_t *size_read);
 268
 269 /**
 270  * This structure holds a string input specified by
 271  * @c yaml_parser_set_input_string.
 272  */
 273
 274 typedef struct {
 275     unsigned char *start;
 276     unsigned char *end;
 277     unsigned char *current;
 278 } yaml_string_input_t;
 279
 280 /**
 281  * The parser structure.
 282  *
 283  * All members are internal.  Manage the structure using the @c yaml_parser_
 284  * family of functions.
 285  */
 286
 287 typedef struct {
 288
 289     /**
 290      * @name Error handling
 291      * @{
 292      */
 293
 294     /** Error type. */
 295     yaml_error_type_t error;
 296
 297     /** Error description. */
 298     const char *problem;
 299
 300     /** The byte about which the problem occured. */
 301     size_t problem_offset;
 302
 303     /**
 304      * @}
 305      */
 306
 307     /**
 308      * @name Reader stuff
 309      * @{
 310      */
 311
 312     /** Read handler. */
 313     yaml_read_handler_t *read_handler;
 314
 315     /** A pointer for passing to the read handler. */
 316     void *read_handler_data;
 317
 318     /** EOF flag */
 319     int eof;
 320
 321     /** The pointer to the beginning of the working buffer. */
 322     yaml_char_t *buffer;
 323
 324     /** The pointer to the end of the working buffer. */
 325     yaml_char_t *buffer_end;
 326
 327     /** The pointer to the current character in the working buffer. */
 328     yaml_char_t *pointer;
 329
 330     /** The number of unread characters in the working buffer. */
 331     size_t unread;
 332
 333     /** The pointer to the beginning of the raw buffer. */
 334     unsigned char *raw_buffer;
 335
 336     /** The pointer to the current character in the raw buffer. */
 337     unsigned char *raw_pointer;
 338
 339     /** The number of unread bytes in the raw buffer. */
 340     size_t raw_unread;
 341
 342     /** The input encoding. */
 343     yaml_encoding_t encoding;
 344
 345     /** The offset of the current position (in bytes). */
 346     size_t offset;
 347
 348     /** The index of the current position (in characters). */
 349     size_t index;
 350
 351     /** The line of the current position (starting from @c 0). */
 352     size_t line;
 353
 354     /** The column of the current position (starting from @c 0). */
 355     size_t column;
 356
 357     /* String input structure. */
 358     yaml_string_input_t string_input;
 359
 360     /**
 361      * @}
 362      */
 363
 364 } yaml_parser_t;
 365
 366 /**
 367  * Create a new parser.
 368  *
 369  * This function creates a new parser object.  An application is responsible
 370  * for destroying the object using the @c yaml_parser_delete function.
 371  *
 372  * @returns A new parser object; @c NULL on error.
 373  */
 374
 375 yaml_parser_t *
 376 yaml_parser_new(void);
 377
 378 /**
 379  * Destroy a parser.
 380  *
 381  * @param[in]   parser  A parser object.
 382  */
 383
 384 void
 385 yaml_parser_delete(yaml_parser_t *parser);
 386
 387 /**
 388  * Set a string input.
 389  *
 390  * Note that the @a input pointer must be valid while the @a parser object
 391  * exists.  The application is responsible for destroing @a input after
 392  * destroying the @a parser.
 393  *
 394  * @param[in]   parser  A parser object.
 395  * @param[in]   input   A source data.
 396  * @param[in]   length  The length of the source data in bytes.
 397  */
 398
 399 void
 400 yaml_parser_set_input_string(yaml_parser_t *parser,
 401         unsigned char *input, size_t size);
 402
 403
 404 /**
 405  * Set a file input.
 406  *
 407  * @a file should be a file object open for reading.  The application is
 408  * responsible for closing the @a file.
 409  *
 410  * @param[in]   parser  A parser object.
 411  * @param[in]   file    An open file.
 412  */
 413
 414 void
 415 yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
 416
 417 /**
 418  * Set a generic input handler.
 419  *
 420  * @param[in]   parser  A parser object.
 421  * @param[in]   handler A read handler.
 422  * @param[in]   data    Any application data for passing to the read handler.
 423  */
 424
 425 void
 426 yaml_parser_set_input(yaml_parser_t *parser,
 427         yaml_read_handler_t *handler, void *data);
 428
 429 /**
 430  * Set the source encoding.
 431  *
 432  * @param[in]   encoding    The source encoding.
 433  */
 434
 435 void
 436 yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
 437
 438 /** @} */
 439
 440 /*
 441 typedef struct {
 442 } yaml_emitter_t;
 443 */
 444
 445 /**
 446  * @defgroup internal Internal Definitions
 447  * @{
 448  */
 449
 450 /**
 451  * Allocate a dynamic memory block.
 452  *
 453  * @param[in]   size    Size of a memory block, \c 0 is valid.
 454  *
 455  * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
 456  * or @c NULL if it failed.
 457  */
 458
 459 void *
 460 yaml_malloc(size_t size);
 461
 462 /**
 463  * Reallocate a dynamic memory block.
 464  *
 465  * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
 466  *                      valid.
 467  * @param[in]   size    A size of a new block, \c 0 is valid.
 468  *
 469  * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
 470  * or @c NULL if it failed.
 471  */
 472
 473 void *
 474 yaml_realloc(void *ptr, size_t size);
 475
 476 /**
 477  * Free a dynamic memory block.
 478  *
 479  * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
 480  *                      valid.
 481  */
 482
 483 void
 484 yaml_free(void *ptr);
 485
 486 /** The size of the raw buffer. */
 487
 488 #define YAML_RAW_BUFFER_SIZE 16384
 489
 490 /**
 491  * The size of the buffer.
 492  *
 493  * We allocate enough space for decoding the whole raw buffer.
 494  */
 495
 496 #define YAML_BUFFER_SIZE    (YAML_RAW_BUFFER_SIZE*3)
 497
 498 /**
 499  * Ensure that the buffer contains at least @a length characters.
 500  *
 501  * @param[in]   parser  A parser object.
 502  * @param[in]   length  The number of characters in the buffer.
 503  *
 504  * @returns @c 1 on success, @c 0 on error.
 505  */
 506
 507 int
 508 yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
 509
 510 /** @} */
 511
 512
 513 #ifdef __cplusplus
 514 }
 515 #endif
 516
 517 #endif /* #ifndef YAML_H */
 518