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

Revision 179, 9.8 KB checked in by xi, 8 years ago (diff)

Implementing Reader: first tries.

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]   ext         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 */
265typedef int yaml_read_handler_t(void *ext, unsigned char *buffer, size_t size,
266        size_t *size_read);
267
268/**
269 * The parser structure.
270 *
271 * All members are internal.  Manage the structure using the @c yaml_parser_
272 * family of functions.
273 */
274
275typedef struct {
276
277    /**
278     * @name Error handling
279     * @{
280     */
281
282    error_type_t error;
283
284    /**
285     * @}
286     */
287
288    /**
289     * @name Reader stuff
290     * @{
291     */
292
293    /** Read handler */
294    yaml_read_handler_t *read_handler;
295
296    /** A pointer for passing to the read handler. */
297    void *read_handler_data;
298
299    /** EOF flag */
300    int eof;
301
302    /** The pointer to the beginning of the working buffer. */
303    yaml_char_t *buffer;
304
305    /** The size of the buffer (in bytes). */
306    size_t buffer_size;
307
308    /** The pointer to the current character in the working buffer. */
309    yaml_char_t *buffer_pointer;
310
311    /** The number of unread characters in the buffer (in characters). */
312    size_t buffer_length;
313
314    /** The remaining undecoded characters. */
315    unsigned char *raw_buffer;
316
317    /** The size of the raw buffer (in bytes). */
318    size_t raw_buffer_size;
319
320    /** Is the application responsible for freeing the raw buffer? */
321    int raw_buffer_foreign;
322
323    /** The input encoding. */
324    yaml_encoding_t encoding;
325
326    /** The offset of the current position (in bytes). */
327    size_t offset;
328
329    /** The index of the current position (in characters). */
330    size_t index;
331
332    /** The line of the current position (starting from @c 0). */
333    size_t line;
334
335    /** The column of the current position (starting from @c 0). */
336    size_t column;
337
338    /**
339     * @}
340     */
341
342} yaml_parser_t;
343
344/**
345 * Create a new parser.
346 *
347 * This function creates a new parser object.  An application is responsible
348 * for destroying the object using the @c yaml_parser_delete function.
349 *
350 * @returns A new parser object; @c NULL on error.
351 */
352
353yaml_parser_t *
354yaml_parser_new(void);
355
356/**
357 * Destroy a parser.
358 *
359 * @param[in]   parser  A parser object.
360 */
361
362void
363yaml_parser_delete(yaml_parser_t *parser);
364
365/**
366 * Set a string input.
367 *
368 * Note that the @a input pointer must be valid while the @a parser object
369 * exists.  The application is responsible for destroing @a input after
370 * destroying the @a parser.
371 *
372 * @param[in]   parser  A parser object.
373 * @param[in]   input   A source data.
374 * @param[in]   length  The length of the source data in bytes.
375 */
376
377void
378yaml_parser_set_input_string(yaml_parser_t *parser,
379        unsigned char *input, size_t size);
380
381
382/**
383 * Set a file input.
384 *
385 * @a file should be a file object open for reading.  The application is
386 * responsible for closing the @a file.
387 *
388 * @param[in]   parser  A parser object.
389 * @param[in]   file    An open file.
390 */
391
392void
393yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
394
395/**
396 * Set a generic input handler.
397 *
398 * @param[in]   parser  A parser object.
399 * @param[in]   handler A read handler.
400 * @param[in]   data    Any application data for passing to the read handler.
401 */
402
403void
404yaml_parser_set_input(yaml_parser_t *parser,
405        yaml_read_handler_t *handler, void *data);
406
407/**
408 * Set the source encoding.
409 *
410 * @param[in]   encoding    The source encoding.
411 */
412
413void
414yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
415
416/** @} */
417
418/*
419typedef struct {
420} yaml_emitter_t;
421*/
422
423/**
424 * @defgroup internal Internal Definitions
425 * @{
426 */
427
428/**
429 * Allocate a dynamic memory block.
430 *
431 * @param[in]   size    Size of a memory block, \c 0 is valid.
432 *
433 * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
434 * or @c NULL if it failed.
435 */
436
437void *
438yaml_malloc(size_t size);
439
440/**
441 * Reallocate a dynamic memory block.
442 *
443 * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
444 *                      valid.
445 * @param[in]   size    A size of a new block, \c 0 is valid.
446 *
447 * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
448 * or @c NULL if it failed.
449 */
450
451void *
452yaml_realloc(void *ptr, size_t size);
453
454/**
455 * Free a dynamic memory block.
456 *
457 * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
458 *                      valid.
459 */
460
461void
462yaml_free(void *ptr);
463
464/** @} */
465
466
467#ifdef __cplusplus
468}
469#endif
470
471#endif /* #ifndef YAML_H */
472
Note: See TracBrowser for help on using the repository browser.