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

Revision 178, 6.9 KB checked in by xi, 9 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.