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

Revision 182, 10.8 KB checked in by xi, 9 years ago (diff)

Complete buffering and encoding 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
[181]294    /** Error type. */
[180]295    yaml_error_type_t error;
[179]296
[181]297    /** Error description. */
298    const char *problem;
299
300    /** The byte about which the problem occured. */
301    size_t problem_offset;
302
[182]303    /** The problematic value (@c -1 is none). */
304    int problem_value;
305
[179]306    /**
307     * @}
308     */
309
310    /**
[178]311     * @name Reader stuff
312     * @{
313     */
314
[181]315    /** Read handler. */
[179]316    yaml_read_handler_t *read_handler;
[178]317
318    /** A pointer for passing to the read handler. */
[179]319    void *read_handler_data;
[178]320
321    /** EOF flag */
322    int eof;
323
324    /** The pointer to the beginning of the working buffer. */
325    yaml_char_t *buffer;
326
[180]327    /** The pointer to the end of the working buffer. */
328    yaml_char_t *buffer_end;
[179]329
[178]330    /** The pointer to the current character in the working buffer. */
[180]331    yaml_char_t *pointer;
[178]332
[180]333    /** The number of unread characters in the working buffer. */
334    size_t unread;
[179]335
[180]336    /** The pointer to the beginning of the raw buffer. */
[178]337    unsigned char *raw_buffer;
338
[180]339    /** The pointer to the current character in the raw buffer. */
340    unsigned char *raw_pointer;
[178]341
[180]342    /** The number of unread bytes in the raw buffer. */
343    size_t raw_unread;
[179]344
[178]345    /** The input encoding. */
346    yaml_encoding_t encoding;
347
[179]348    /** The offset of the current position (in bytes). */
349    size_t offset;
350
351    /** The index of the current position (in characters). */
352    size_t index;
353
354    /** The line of the current position (starting from @c 0). */
355    size_t line;
356
357    /** The column of the current position (starting from @c 0). */
358    size_t column;
359
[180]360    /* String input structure. */
361    yaml_string_input_t string_input;
362
[178]363    /**
364     * @}
365     */
366
[162]367} yaml_parser_t;
368
[178]369/**
370 * Create a new parser.
371 *
372 * This function creates a new parser object.  An application is responsible
373 * for destroying the object using the @c yaml_parser_delete function.
374 *
375 * @returns A new parser object; @c NULL on error.
376 */
377
378yaml_parser_t *
379yaml_parser_new(void);
380
381/**
382 * Destroy a parser.
383 *
384 * @param[in]   parser  A parser object.
385 */
386
387void
388yaml_parser_delete(yaml_parser_t *parser);
389
[179]390/**
391 * Set a string input.
392 *
393 * Note that the @a input pointer must be valid while the @a parser object
394 * exists.  The application is responsible for destroing @a input after
395 * destroying the @a parser.
396 *
397 * @param[in]   parser  A parser object.
398 * @param[in]   input   A source data.
399 * @param[in]   length  The length of the source data in bytes.
400 */
401
402void
403yaml_parser_set_input_string(yaml_parser_t *parser,
404        unsigned char *input, size_t size);
405
406
407/**
408 * Set a file input.
409 *
410 * @a file should be a file object open for reading.  The application is
411 * responsible for closing the @a file.
412 *
413 * @param[in]   parser  A parser object.
414 * @param[in]   file    An open file.
415 */
416
417void
418yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
419
420/**
421 * Set a generic input handler.
422 *
423 * @param[in]   parser  A parser object.
424 * @param[in]   handler A read handler.
425 * @param[in]   data    Any application data for passing to the read handler.
426 */
427
428void
429yaml_parser_set_input(yaml_parser_t *parser,
430        yaml_read_handler_t *handler, void *data);
431
432/**
433 * Set the source encoding.
434 *
435 * @param[in]   encoding    The source encoding.
436 */
437
438void
439yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
440
[178]441/** @} */
442
443/*
[162]444typedef struct {
445} yaml_emitter_t;
[169]446*/
[162]447
[179]448/**
449 * @defgroup internal Internal Definitions
450 * @{
451 */
452
453/**
454 * Allocate a dynamic memory block.
455 *
456 * @param[in]   size    Size of a memory block, \c 0 is valid.
457 *
458 * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
459 * or @c NULL if it failed.
460 */
461
462void *
463yaml_malloc(size_t size);
464
465/**
466 * Reallocate a dynamic memory block.
467 *
468 * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
469 *                      valid.
470 * @param[in]   size    A size of a new block, \c 0 is valid.
471 *
472 * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
473 * or @c NULL if it failed.
474 */
475
476void *
477yaml_realloc(void *ptr, size_t size);
478
479/**
480 * Free a dynamic memory block.
481 *
482 * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
483 *                      valid.
484 */
485
486void
487yaml_free(void *ptr);
488
[180]489/** The size of the raw buffer. */
490
491#define YAML_RAW_BUFFER_SIZE 16384
492
493/**
494 * The size of the buffer.
495 *
496 * We allocate enough space for decoding the whole raw buffer.
497 */
498
499#define YAML_BUFFER_SIZE    (YAML_RAW_BUFFER_SIZE*3)
500
[181]501/**
502 * Ensure that the buffer contains at least @a length characters.
503 *
504 * @param[in]   parser  A parser object.
505 * @param[in]   length  The number of characters in the buffer.
506 *
507 * @returns @c 1 on success, @c 0 on error.
508 */
509
510int
511yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
512
[179]513/** @} */
514
515
[162]516#ifdef __cplusplus
517}
518#endif
519
[169]520#endif /* #ifndef YAML_H */
[162]521
Note: See TracBrowser for help on using the repository browser.