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

Revision 178, 6.9 KB checked in by xi, 10 years ago (diff)

Doxygenify the header file.

Add basic reader fields to the parser structure.

Start implementing basic parser functions.

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
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
33const char *
34yaml_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
44void
45yaml_get_version(int *major, int *minor, int *patch);
46
47/** @} */
48
49/**
50 * @defgroup basic Basic Types
51 * @{
52 */
53
54/** The character type. */
55typedef unsigned char yaml_char_t;
56
57/** The stream encoding. */
58typedef 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
69typedef 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
82typedef 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
91typedef enum {
92    YAML_ANY_SEQUENCE_STYLE,
93    YAML_BLOCK_SEQUENCE_STYLE,
94    YAML_FLOW_SEQUENCE_STYLE
95} yaml_sequence_style_t;
96
97typedef enum {
98    YAML_ANY_MAPPING_STYLE,
99    YAML_BLOCK_MAPPING_STYLE,
100    YAML_FLOW_MAPPING_STYLE
101} yaml_mapping_style_t;
102
103typedef 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
132typedef 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
149typedef struct {
150    size_t offset;
151    size_t index;
152    size_t line;
153    size_t column;
154} yaml_mark_t;
155
156typedef 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
164typedef 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
188typedef 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 */
262typedef 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
273typedef 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
319yaml_parser_t *
320yaml_parser_new(void);
321
322/**
323 * Destroy a parser.
324 *
325 * @param[in]   parser  A parser object.
326 */
327
328void
329yaml_parser_delete(yaml_parser_t *parser);
330
331/** @} */
332
333/*
334typedef struct {
335} yaml_emitter_t;
336*/
337
338#ifdef __cplusplus
339}
340#endif
341
342#endif /* #ifndef YAML_H */
343
Note: See TracBrowser for help on using the repository browser.