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

Revision 181, 10.8 KB checked in by xi, 8 years ago (diff)

Complete UTF-8 and UTF-16 decoders.

Reader is mostly done (though untested).

Line 
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
15extern "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
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. */
60typedef 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. */
68typedef 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
85typedef 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
94typedef enum {
95    YAML_ANY_SEQUENCE_STYLE,
96    YAML_BLOCK_SEQUENCE_STYLE,
97    YAML_FLOW_SEQUENCE_STYLE
98} yaml_sequence_style_t;
99
100typedef enum {
101    YAML_ANY_MAPPING_STYLE,
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,
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
135typedef 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
152typedef struct {
153    size_t offset;
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;
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
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 {
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
266typedef 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
274typedef 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
287typedef 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
375yaml_parser_t *
376yaml_parser_new(void);
377
378/**
379 * Destroy a parser.
380 *
381 * @param[in]   parser  A parser object.
382 */
383
384void
385yaml_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
399void
400yaml_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
414void
415yaml_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
425void
426yaml_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
435void
436yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
437
438/** @} */
439
440/*
441typedef 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
459void *
460yaml_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
473void *
474yaml_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
483void
484yaml_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
507int
508yaml_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
Note: See TracBrowser for help on using the repository browser.