source: libyaml/trunk/include/yaml/yaml.h @ 180

Revision 180, 10.3 KB checked in by xi, 8 years ago (diff)

Working on the decoding code.

RevLine 
[172]1/**
2 * @file yaml.h
3 * @brief Public interface for libyaml.
4 *
[178]5 * Include the header file with the code:
[172]6 * @code
7 * #include <yaml/yaml.h>
8 * @endcode
9 */
[162]10
[169]11#ifndef YAML_H
12#define YAML_H
[162]13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
[169]18#include <stdlib.h>
[179]19#include <stdio.h>
20#include <string.h>
[162]21
[178]22/**
23 * @defgroup version Version Information
24 * @{
25 */
[169]26
[178]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
35const char *
36yaml_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
46void
47yaml_get_version(int *major, int *minor, int *patch);
48
49/** @} */
50
51/**
52 * @defgroup basic Basic Types
53 * @{
54 */
55
56/** The character type. */
57typedef unsigned char yaml_char_t;
58
59/** The stream encoding. */
[162]60typedef enum {
[178]61    YAML_ANY_ENCODING,
[162]62    YAML_UTF8_ENCODING,
63    YAML_UTF16LE_ENCODING,
64    YAML_UTF16BE_ENCODING
65} yaml_encoding_t;
66
[179]67/** Many bad things could happen with the parser and emitter. */
[162]68typedef enum {
[178]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
[179]81/** @} */
82
83/*
84
[178]85typedef enum {
[169]86    YAML_ANY_SCALAR_STYLE,
[162]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
94typedef enum {
[169]95    YAML_ANY_SEQUENCE_STYLE,
[162]96    YAML_BLOCK_SEQUENCE_STYLE,
97    YAML_FLOW_SEQUENCE_STYLE
98} yaml_sequence_style_t;
99
100typedef enum {
[169]101    YAML_ANY_MAPPING_STYLE,
[162]102    YAML_BLOCK_MAPPING_STYLE,
103    YAML_FLOW_MAPPING_STYLE
104} yaml_mapping_style_t;
105
106typedef enum {
107    YAML_STREAM_START_TOKEN,
108    YAML_STREAM_END_TOKEN,
[169]109
[162]110    YAML_VERSION_DIRECTIVE_TOKEN,
111    YAML_TAG_DIRECTIVE_TOKEN,
112    YAML_DOCUMENT_START_TOKEN,
113    YAML_DOCUMENT_END_TOKEN,
[169]114
[162]115    YAML_BLOCK_SEQUENCE_START_TOKEN,
116    YAML_BLOCK_MAPPING_START_TOKEN,
117    YAML_BLOCK_END_TOKEN,
[169]118
[162]119    YAML_FLOW_SEQUENCE_START_TOKEN,
120    YAML_FLOW_SEQUENCE_END_TOKEN,
121    YAML_FLOW_MAPPING_START_TOKEN,
122    YAML_FLOW_MAPPING_END_TOKEN,
[169]123
[162]124    YAML_BLOCK_ENTRY_TOKEN,
125    YAML_FLOW_ENTRY_TOKEN,
126    YAML_KEY_TOKEN,
127    YAML_VALUE_TOKEN,
[169]128
[162]129    YAML_ALIAS_TOKEN,
130    YAML_ANCHOR_TOKEN,
131    YAML_TAG_TOKEN,
132    YAML_SCALAR_TOKEN
133} yaml_token_type_t;
134
135typedef enum {
136    YAML_STREAM_START_EVENT,
137    YAML_STREAM_END_EVENT,
[169]138
[162]139    YAML_DOCUMENT_START_EVENT,
140    YAML_DOCUMENT_END_EVENT,
[169]141
[162]142    YAML_ALIAS_EVENT,
[169]143    YAML_SCALAR_EVENT,
144
[162]145    YAML_SEQUENCE_START_EVENT,
146    YAML_SEQUENCE_END_EVENT,
[169]147
[162]148    YAML_MAPPING_START_EVENT,
[169]149    YAML_MAPPING_END_EVENT
[162]150} yaml_event_type_t;
151
152typedef struct {
[169]153    size_t offset;
[162]154    size_t index;
155    size_t line;
156    size_t column;
157} yaml_mark_t;
158
159typedef 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
167typedef struct {
168    yaml_token_type_t type;
169    union {
170        yaml_encoding_t encoding;
[169]171        char *anchor;
172        char *tag;
[162]173        struct {
[169]174            char *value;
175            size_t length;
[162]176            yaml_scalar_style_t style;
177        } scalar;
178        struct {
179            int major;
180            int minor;
181        } version;
182        struct {
[169]183          char *handle;
184          char *prefix;
[162]185        } tag_pair;
186    } data;
187    yaml_mark_t start_mark;
188    yaml_mark_t end_mark;
189} yaml_token_t;
190
191typedef 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 {
[169]203                char *handle;
204                char *prefix;
[162]205            } **tag_pairs;
206            int implicit;
207        } document_start;
208        struct {
209            int implicit;
210        } document_end;
211        struct {
[169]212            char *anchor;
[162]213        } alias;
214        struct {
[169]215            char *anchor;
216            char *tag;
217            char *value;
218            size_t length;
[162]219            int plain_implicit;
220            int quoted_implicit;
221            yaml_scalar_style_t style;
222        } scalar;
223        struct {
[169]224            char *anchor;
225            char *tag;
[162]226            int implicit;
227            yaml_sequence_style_t style;
228        } sequence_start;
229        struct {
[169]230            char *anchor;
231            char *tag;
[162]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
[178]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 *
[180]255 * @param[in]   data        A pointer to an application data specified by
[179]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.
[178]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 */
[180]265
266typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
[179]267        size_t *size_read);
[178]268
269/**
[180]270 * This structure holds a string input specified by
271 * @c yaml_parser_set_input_string.
272 */
273
274typedef struct {
275    unsigned char *start;
276    unsigned char *end;
277    unsigned char *current;
278} yaml_string_input_t;
279
280/**
[178]281 * The parser structure.
282 *
283 * All members are internal.  Manage the structure using the @c yaml_parser_
284 * family of functions.
285 */
286
[162]287typedef struct {
[178]288
289    /**
[179]290     * @name Error handling
291     * @{
292     */
293
[180]294    yaml_error_type_t error;
[179]295
296    /**
297     * @}
298     */
299
300    /**
[178]301     * @name Reader stuff
302     * @{
303     */
304
305    /** Read handler */
[179]306    yaml_read_handler_t *read_handler;
[178]307
308    /** A pointer for passing to the read handler. */
[179]309    void *read_handler_data;
[178]310
311    /** EOF flag */
312    int eof;
313
314    /** The pointer to the beginning of the working buffer. */
315    yaml_char_t *buffer;
316
[180]317    /** The pointer to the end of the working buffer. */
318    yaml_char_t *buffer_end;
[179]319
[178]320    /** The pointer to the current character in the working buffer. */
[180]321    yaml_char_t *pointer;
[178]322
[180]323    /** The number of unread characters in the working buffer. */
324    size_t unread;
[179]325
[180]326    /** The pointer to the beginning of the raw buffer. */
[178]327    unsigned char *raw_buffer;
328
[180]329    /** The pointer to the current character in the raw buffer. */
330    unsigned char *raw_pointer;
[178]331
[180]332    /** The number of unread bytes in the raw buffer. */
333    size_t raw_unread;
[179]334
[178]335    /** The input encoding. */
336    yaml_encoding_t encoding;
337
[179]338    /** The offset of the current position (in bytes). */
339    size_t offset;
340
341    /** The index of the current position (in characters). */
342    size_t index;
343
344    /** The line of the current position (starting from @c 0). */
345    size_t line;
346
347    /** The column of the current position (starting from @c 0). */
348    size_t column;
349
[180]350    /* String input structure. */
351    yaml_string_input_t string_input;
352
[178]353    /**
354     * @}
355     */
356
[162]357} yaml_parser_t;
358
[178]359/**
360 * Create a new parser.
361 *
362 * This function creates a new parser object.  An application is responsible
363 * for destroying the object using the @c yaml_parser_delete function.
364 *
365 * @returns A new parser object; @c NULL on error.
366 */
367
368yaml_parser_t *
369yaml_parser_new(void);
370
371/**
372 * Destroy a parser.
373 *
374 * @param[in]   parser  A parser object.
375 */
376
377void
378yaml_parser_delete(yaml_parser_t *parser);
379
[179]380/**
381 * Set a string input.
382 *
383 * Note that the @a input pointer must be valid while the @a parser object
384 * exists.  The application is responsible for destroing @a input after
385 * destroying the @a parser.
386 *
387 * @param[in]   parser  A parser object.
388 * @param[in]   input   A source data.
389 * @param[in]   length  The length of the source data in bytes.
390 */
391
392void
393yaml_parser_set_input_string(yaml_parser_t *parser,
394        unsigned char *input, size_t size);
395
396
397/**
398 * Set a file input.
399 *
400 * @a file should be a file object open for reading.  The application is
401 * responsible for closing the @a file.
402 *
403 * @param[in]   parser  A parser object.
404 * @param[in]   file    An open file.
405 */
406
407void
408yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
409
410/**
411 * Set a generic input handler.
412 *
413 * @param[in]   parser  A parser object.
414 * @param[in]   handler A read handler.
415 * @param[in]   data    Any application data for passing to the read handler.
416 */
417
418void
419yaml_parser_set_input(yaml_parser_t *parser,
420        yaml_read_handler_t *handler, void *data);
421
422/**
423 * Set the source encoding.
424 *
425 * @param[in]   encoding    The source encoding.
426 */
427
428void
429yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
430
[178]431/** @} */
432
433/*
[162]434typedef struct {
435} yaml_emitter_t;
[169]436*/
[162]437
[179]438/**
439 * @defgroup internal Internal Definitions
440 * @{
441 */
442
443/**
444 * Allocate a dynamic memory block.
445 *
446 * @param[in]   size    Size of a memory block, \c 0 is valid.
447 *
448 * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
449 * or @c NULL if it failed.
450 */
451
452void *
453yaml_malloc(size_t size);
454
455/**
456 * Reallocate a dynamic memory block.
457 *
458 * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
459 *                      valid.
460 * @param[in]   size    A size of a new block, \c 0 is valid.
461 *
462 * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
463 * or @c NULL if it failed.
464 */
465
466void *
467yaml_realloc(void *ptr, size_t size);
468
469/**
470 * Free a dynamic memory block.
471 *
472 * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
473 *                      valid.
474 */
475
476void
477yaml_free(void *ptr);
478
[180]479/** The size of the raw buffer. */
480
481#define YAML_RAW_BUFFER_SIZE 16384
482
483/**
484 * The size of the buffer.
485 *
486 * We allocate enough space for decoding the whole raw buffer.
487 */
488
489#define YAML_BUFFER_SIZE    (YAML_RAW_BUFFER_SIZE*3)
490
[179]491/** @} */
492
493
[162]494#ifdef __cplusplus
495}
496#endif
497
[169]498#endif /* #ifndef YAML_H */
[162]499
Note: See TracBrowser for help on using the repository browser.