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
  20 /**
  21  * @defgroup version Version Information
  22  * @{
  23  */
  24
  25 /**
  26  * Get the library version as a string.
  27  *
  28  * @returns The function returns the pointer to a static string of the form
  29  * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version
  30  * number, and @c Z is the patch version number.
  31  */
  32
  33 const char *
  34 yaml_get_version_string(void);
  35
  36 /**
  37  * Get the library version numbers.
  38  *
  39  * @param[out]  major   Major version number.
  40  * @param[out]  minor   Minor version number.
  41  * @param[out]  patch   Patch version number.
  42  */
  43
  44 void
  45 yaml_get_version(int *major, int *minor, int *patch);
  46
  47 /** @} */
  48
  49 /**
  50  * @defgroup basic Basic Types
  51  * @{
  52  */
  53
  54 /** The character type. */
  55 typedef unsigned char yaml_char_t;
  56
  57 /** The stream encoding. */
  58 typedef enum {
  59     YAML_ANY_ENCODING,
  60     YAML_UTF8_ENCODING,
  61     YAML_UTF16LE_ENCODING,
  62     YAML_UTF16BE_ENCODING
  63 } yaml_encoding_t;
  64
  65 /** @} */
  66
  67 /*
  68
  69 typedef enum {
  70     YAML_NO_ERROR,
  71
  72     YAML_MEMORY_ERROR,
  73
  74     YAML_READER_ERROR,
  75     YAML_SCANNER_ERROR,
  76     YAML_PARSER_ERROR,
  77
  78     YAML_WRITER_ERROR,
  79     YAML_EMITTER_ERROR
  80 } yaml_error_type_t;
  81
  82 typedef enum {
  83     YAML_ANY_SCALAR_STYLE,
  84     YAML_PLAIN_SCALAR_STYLE,
  85     YAML_SINGLE_QUOTED_SCALAR_STYLE,
  86     YAML_DOUBLE_QUOTED_SCALAR_STYLE,
  87     YAML_LITERAL_SCALAR_STYLE,
  88     YAML_FOLDED_SCALAR_STYLE
  89 } yaml_scalar_style_t;
  90
  91 typedef enum {
  92     YAML_ANY_SEQUENCE_STYLE,
  93     YAML_BLOCK_SEQUENCE_STYLE,
  94     YAML_FLOW_SEQUENCE_STYLE
  95 } yaml_sequence_style_t;
  96
  97 typedef enum {
  98     YAML_ANY_MAPPING_STYLE,
  99     YAML_BLOCK_MAPPING_STYLE,
 100     YAML_FLOW_MAPPING_STYLE
 101 } yaml_mapping_style_t;
 102
 103 typedef enum {
 104     YAML_STREAM_START_TOKEN,
 105     YAML_STREAM_END_TOKEN,
 106
 107     YAML_VERSION_DIRECTIVE_TOKEN,
 108     YAML_TAG_DIRECTIVE_TOKEN,
 109     YAML_DOCUMENT_START_TOKEN,
 110     YAML_DOCUMENT_END_TOKEN,
 111
 112     YAML_BLOCK_SEQUENCE_START_TOKEN,
 113     YAML_BLOCK_MAPPING_START_TOKEN,
 114     YAML_BLOCK_END_TOKEN,
 115
 116     YAML_FLOW_SEQUENCE_START_TOKEN,
 117     YAML_FLOW_SEQUENCE_END_TOKEN,
 118     YAML_FLOW_MAPPING_START_TOKEN,
 119     YAML_FLOW_MAPPING_END_TOKEN,
 120
 121     YAML_BLOCK_ENTRY_TOKEN,
 122     YAML_FLOW_ENTRY_TOKEN,
 123     YAML_KEY_TOKEN,
 124     YAML_VALUE_TOKEN,
 125
 126     YAML_ALIAS_TOKEN,
 127     YAML_ANCHOR_TOKEN,
 128     YAML_TAG_TOKEN,
 129     YAML_SCALAR_TOKEN
 130 } yaml_token_type_t;
 131
 132 typedef enum {
 133     YAML_STREAM_START_EVENT,
 134     YAML_STREAM_END_EVENT,
 135
 136     YAML_DOCUMENT_START_EVENT,
 137     YAML_DOCUMENT_END_EVENT,
 138
 139     YAML_ALIAS_EVENT,
 140     YAML_SCALAR_EVENT,
 141
 142     YAML_SEQUENCE_START_EVENT,
 143     YAML_SEQUENCE_END_EVENT,
 144
 145     YAML_MAPPING_START_EVENT,
 146     YAML_MAPPING_END_EVENT
 147 } yaml_event_type_t;
 148
 149 typedef struct {
 150     size_t offset;
 151     size_t index;
 152     size_t line;
 153     size_t column;
 154 } yaml_mark_t;
 155
 156 typedef struct {
 157     yaml_error_type_t type;
 158     char *context;
 159     yaml_mark_t context_mark;
 160     char *problem;
 161     yaml_mark_t problem_mark;
 162 } yaml_error_t;
 163
 164 typedef struct {
 165     yaml_token_type_t type;
 166     union {
 167         yaml_encoding_t encoding;
 168         char *anchor;
 169         char *tag;
 170         struct {
 171             char *value;
 172             size_t length;
 173             yaml_scalar_style_t style;
 174         } scalar;
 175         struct {
 176             int major;
 177             int minor;
 178         } version;
 179         struct {
 180           char *handle;
 181           char *prefix;
 182         } tag_pair;
 183     } data;
 184     yaml_mark_t start_mark;
 185     yaml_mark_t end_mark;
 186 } yaml_token_t;
 187
 188 typedef struct {
 189     yaml_event_type_t type;
 190     union {
 191         struct {
 192             yaml_encoding_t encoding;
 193         } stream_start;
 194         struct {
 195             struct {
 196                 int major;
 197                 int minor;
 198             } version;
 199             struct {
 200                 char *handle;
 201                 char *prefix;
 202             } **tag_pairs;
 203             int implicit;
 204         } document_start;
 205         struct {
 206             int implicit;
 207         } document_end;
 208         struct {
 209             char *anchor;
 210         } alias;
 211         struct {
 212             char *anchor;
 213             char *tag;
 214             char *value;
 215             size_t length;
 216             int plain_implicit;
 217             int quoted_implicit;
 218             yaml_scalar_style_t style;
 219         } scalar;
 220         struct {
 221             char *anchor;
 222             char *tag;
 223             int implicit;
 224             yaml_sequence_style_t style;
 225         } sequence_start;
 226         struct {
 227             char *anchor;
 228             char *tag;
 229             int implicit;
 230             yaml_mapping_style_t style;
 231         } mapping_start;
 232     } data;
 233     yaml_mark_t start_mark;
 234     yaml_mark_t end_mark;
 235 } yaml_event_t;
 236
 237 */
 238
 239
 240 /**
 241  * @defgroup parser Parser Definitions
 242  * @{
 243  */
 244
 245 /**
 246  * The prototype of a read handler.
 247  *
 248  * The read handler is called when the parser needs to read more bytes from the
 249  * source.  The handler should write not more than @a size bytes to the @a
 250  * buffer.  The number of written bytes should be set to the @a length variable.
 251  *
 252  * @param[in]   ext     A pointer to an application data specified by
 253  *                      @c yaml_parser_set_read_handler.
 254  * @param[out]  buffer  The buffer to write the data from the source.
 255  * @param[in]   size    The size of the buffer.
 256  * @param[out]  length  The actual number of bytes read from the source.
 257  *
 258  * @returns On success, the handler should return @c 1.  If the handler failed,
 259  * the returned value should be @c 0.  On EOF, the handler should set the
 260  * @a length to @c 0 and return @c 1.
 261  */
 262 typedef int yaml_read_handler_t(void *ext, yaml_char_t *buffer, size_t size,
 263         size_t *length);
 264
 265
 266 /**
 267  * The parser structure.
 268  *
 269  * All members are internal.  Manage the structure using the @c yaml_parser_
 270  * family of functions.
 271  */
 272
 273 typedef struct {
 274
 275     /**
 276      * @name Reader stuff
 277      * @{
 278      */
 279
 280     /** Read handler */
 281     yaml_read_handler_t *reader;
 282
 283     /** A pointer for passing to the read handler. */
 284     void *reader_ext;
 285
 286     /** EOF flag */
 287     int eof;
 288
 289     /** The pointer to the beginning of the working buffer. */
 290     yaml_char_t *buffer;
 291
 292     /** The pointer to the current character in the working buffer. */
 293     yaml_char_t *pointer;
 294
 295     /** The remaining undecoded characters. */
 296     unsigned char *raw_buffer;
 297
 298     /** The size of the raw buffer. */
 299     size_t raw_buffer_size;
 300
 301     /** The input encoding. */
 302     yaml_encoding_t encoding;
 303
 304     /**
 305      * @}
 306      */
 307
 308 } yaml_parser_t;
 309
 310 /**
 311  * Create a new parser.
 312  *
 313  * This function creates a new parser object.  An application is responsible
 314  * for destroying the object using the @c yaml_parser_delete function.
 315  *
 316  * @returns A new parser object; @c NULL on error.
 317  */
 318
 319 yaml_parser_t *
 320 yaml_parser_new(void);
 321
 322 /**
 323  * Destroy a parser.
 324  *
 325  * @param[in]   parser  A parser object.
 326  */
 327
 328 void
 329 yaml_parser_delete(yaml_parser_t *parser);
 330
 331 /** @} */
 332
 333 /*
 334 typedef struct {
 335 } yaml_emitter_t;
 336 */
 337
 338 #ifdef __cplusplus
 339 }
 340 #endif
 341
 342 #endif /* #ifndef YAML_H */
 343