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

Revision 200, 27.8 KB checked in by xi, 8 years ago (diff)

Move yaml/yaml.h to yaml.h and merge version.c to api.c.

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/**
[184]23 * @defgroup export Export Definitions
[183]24 * @{
25 */
26
27/** The public API declaration. */
28
29#ifdef WIN32
30#   if defined(YAML_DECLARE_STATIC)
31#       define  YAML_DECLARE(type)  type
32#   elif defined(YAML_DECLARE_EXPORT)
33#       define  YAML_DECLARE(type)  __declspec(dllexport) type
34#   else
35#       define  YAML_DECLARE(type)  __declspec(dllimport) type
36#   endif
37#else
38#   define  YAML_DECLARE(type)  type
39#endif
40
41/** @} */
42
43/**
[178]44 * @defgroup version Version Information
45 * @{
46 */
[169]47
[178]48/**
49 * Get the library version as a string.
50 *
51 * @returns The function returns the pointer to a static string of the form
52 * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version
53 * number, and @c Z is the patch version number.
54 */
55
[183]56YAML_DECLARE(const char *)
[178]57yaml_get_version_string(void);
58
59/**
60 * Get the library version numbers.
61 *
62 * @param[out]  major   Major version number.
63 * @param[out]  minor   Minor version number.
64 * @param[out]  patch   Patch version number.
65 */
66
[183]67YAML_DECLARE(void)
[178]68yaml_get_version(int *major, int *minor, int *patch);
69
70/** @} */
71
72/**
73 * @defgroup basic Basic Types
74 * @{
75 */
76
[183]77/** The character type (UTF-8 octet). */
[178]78typedef unsigned char yaml_char_t;
79
[199]80/** The version directive data. */
81typedef struct {
82    /** The major version number. */
83    int major;
84    /** The minor version number. */
85    int minor;
86} yaml_version_directive_t;
87
88/** The tag directive data. */
89typedef struct {
90    /** The tag handle. */
91    yaml_char_t *handle;
92    /** The tag prefix. */
93    yaml_char_t *prefix;
94} yaml_tag_directive_t;
95
[178]96/** The stream encoding. */
[162]97typedef enum {
[178]98    YAML_ANY_ENCODING,
[162]99    YAML_UTF8_ENCODING,
100    YAML_UTF16LE_ENCODING,
101    YAML_UTF16BE_ENCODING
102} yaml_encoding_t;
103
[179]104/** Many bad things could happen with the parser and emitter. */
[162]105typedef enum {
[178]106    YAML_NO_ERROR,
107
108    YAML_MEMORY_ERROR,
109
110    YAML_READER_ERROR,
111    YAML_SCANNER_ERROR,
112    YAML_PARSER_ERROR,
113
114    YAML_WRITER_ERROR,
115    YAML_EMITTER_ERROR
116} yaml_error_type_t;
117
[183]118/** The pointer position. */
119typedef struct {
120    /** The position index. */
121    size_t index;
122
123    /** The position line. */
124    size_t line;
125
126    /** The position column. */
127    size_t column;
128} yaml_mark_t;
129
[179]130/** @} */
131
[183]132/**
[184]133 * @defgroup styles Node Styles
[183]134 * @{
135 */
[179]136
[183]137/** Scalar styles. */
[178]138typedef enum {
[169]139    YAML_ANY_SCALAR_STYLE,
[183]140
[162]141    YAML_PLAIN_SCALAR_STYLE,
[183]142
[162]143    YAML_SINGLE_QUOTED_SCALAR_STYLE,
144    YAML_DOUBLE_QUOTED_SCALAR_STYLE,
[183]145
[162]146    YAML_LITERAL_SCALAR_STYLE,
147    YAML_FOLDED_SCALAR_STYLE
148} yaml_scalar_style_t;
149
[183]150
151/** Sequence styles. */
[162]152typedef enum {
[169]153    YAML_ANY_SEQUENCE_STYLE,
[183]154
[162]155    YAML_BLOCK_SEQUENCE_STYLE,
156    YAML_FLOW_SEQUENCE_STYLE
157} yaml_sequence_style_t;
158
[183]159/** Mapping styles. */
[162]160typedef enum {
[169]161    YAML_ANY_MAPPING_STYLE,
[183]162
[162]163    YAML_BLOCK_MAPPING_STYLE,
164    YAML_FLOW_MAPPING_STYLE
165} yaml_mapping_style_t;
166
[183]167/** @} */
168
169/**
[184]170 * @defgroup tokens Tokens
[183]171 * @{
172 */
173
174/** Token types. */
[162]175typedef enum {
176    YAML_STREAM_START_TOKEN,
177    YAML_STREAM_END_TOKEN,
[169]178
[162]179    YAML_VERSION_DIRECTIVE_TOKEN,
180    YAML_TAG_DIRECTIVE_TOKEN,
181    YAML_DOCUMENT_START_TOKEN,
182    YAML_DOCUMENT_END_TOKEN,
[169]183
[162]184    YAML_BLOCK_SEQUENCE_START_TOKEN,
185    YAML_BLOCK_MAPPING_START_TOKEN,
186    YAML_BLOCK_END_TOKEN,
[169]187
[162]188    YAML_FLOW_SEQUENCE_START_TOKEN,
189    YAML_FLOW_SEQUENCE_END_TOKEN,
190    YAML_FLOW_MAPPING_START_TOKEN,
191    YAML_FLOW_MAPPING_END_TOKEN,
[169]192
[162]193    YAML_BLOCK_ENTRY_TOKEN,
194    YAML_FLOW_ENTRY_TOKEN,
195    YAML_KEY_TOKEN,
196    YAML_VALUE_TOKEN,
[169]197
[162]198    YAML_ALIAS_TOKEN,
199    YAML_ANCHOR_TOKEN,
200    YAML_TAG_TOKEN,
201    YAML_SCALAR_TOKEN
202} yaml_token_type_t;
203
[183]204/** The token structure. */
205typedef struct {
[169]206
[183]207    /** The token type. */
208    yaml_token_type_t type;
[169]209
[183]210    /** The token data. */
211    union {
[169]212
[199]213        /** The stream start (for @c YAML_STREAM_START_TOKEN). */
214        struct {
215            /** The stream encoding. */
216            yaml_encoding_t encoding;
217        } stream_start;
[169]218
[199]219        /** The alias (for @c YAML_ALIAS_TOKEN). */
220        struct {
221            /** The alias value. */
222            yaml_char_t *value;
223        } alias;
[162]224
[199]225        /** The anchor (for @c YAML_ANCHOR_TOKEN). */
226        struct {
227            /** The anchor value. */
228            yaml_char_t *value;
229        } anchor;
230
[183]231        /** The tag (for @c YAML_TAG_TOKEN). */
232        struct {
233            /** The tag handle. */
234            yaml_char_t *handle;
[162]235
[183]236            /** The tag suffix. */
237            yaml_char_t *suffix;
238        } tag;
[162]239
[183]240        /** The scalar value (for @c YAML_SCALAR_TOKEN). */
[162]241        struct {
[183]242
243            /** The scalar value. */
244            yaml_char_t *value;
245
246            /** The length of the scalar value. */
[169]247            size_t length;
[183]248
249            /** The scalar style. */
[162]250            yaml_scalar_style_t style;
251        } scalar;
[183]252
253        /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
[162]254        struct {
[183]255            /** The major version number. */
[162]256            int major;
[183]257
258            /** The minor version number. */
[162]259            int minor;
[183]260        } version_directive;
261
262        /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
[162]263        struct {
[183]264            /** The tag handle. */
265            yaml_char_t *handle;
266
267            /** The tag prefix. */
268            yaml_char_t *prefix;
269        } tag_directive;
[162]270    } data;
[183]271
272    /** The beginning of the token. */
[162]273    yaml_mark_t start_mark;
[183]274
275    /** The end of the token. */
[162]276    yaml_mark_t end_mark;
[183]277
[162]278} yaml_token_t;
279
[183]280/**
281 * Create a new token without assigning any data.
282 *
283 * This function can be used for constructing indicator tokens:
284 * @c YAML_DOCUMENT_START, @c YAML_DOCUMENT_END,
285 * @c YAML_BLOCK_SEQUENCE_START_TOKEN, @c YAML_BLOCK_MAPPING_START_TOKEN,
286 * @c YAML_BLOCK_END_TOKEN,
287 * @c YAML_FLOW_SEQUENCE_START_TOKEN, @c YAML_FLOW_SEQUENCE_END_TOKEN,
288 * @c YAML_FLOW_MAPPING_START_TOKEN, @c YAML_FLOW_MAPPING_END_TOKEN,
289 * @c YAML_BLOCK_ENTRY_TOKEN, @c YAML_FLOW_ENTRY_TOKEN,
290 * @c YAML_KEY_TOKEN, @c YAML_VALUE_TOKEN.
291 *
292 * @param[in]   type        The token type.
293 * @param[in]   start_mark  The beginning of the token.
294 * @param[in]   end_mark    The end of the token.
295 *
296 * @returns A new token object, or @c NULL on error.
297 */
298
299YAML_DECLARE(yaml_token_t *)
300yaml_token_new(yaml_token_type_t type,
301        yaml_mark_t start_mark, yaml_mark_t end_mark);
302
303/**
304 * Create a new @c YAML_STREAM_START_TOKEN token with the specified encoding.
305 *
306 * @param[in]   encoding    The stream encoding.
307 * @param[in]   start_mark  The beginning of the token.
308 * @param[in]   end_mark    The end of the token.
309 *
310 * @returns A new token object, or @c NULL on error.
311 */
312
313YAML_DECLARE(yaml_token_t *)
314yaml_stream_start_token_new(yaml_encoding_t encoding,
315        yaml_mark_t start_mark, yaml_mark_t end_mark);
316
317/**
318 * Create a new @c YAML_STREAM_END_TOKEN token.
319 *
320 * @param[in]   start_mark  The beginning of the token.
321 * @param[in]   end_mark    The end of the token.
322 *
323 * @returns A new token object, or @c NULL on error.
324 */
325
326YAML_DECLARE(yaml_token_t *)
327yaml_stream_end_token_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
328
329/**
330 * Create a new @c YAML_VERSION_DIRECTIVE_TOKEN token with the specified
331 * version numbers.
332 *
333 * @param[in]   major       The major version number.
334 * @param[in]   minor       The minor version number.
335 * @param[in]   start_mark  The beginning of the token.
336 * @param[in]   end_mark    The end of the token.
337 *
338 * @returns A new token object, or @c NULL on error.
339 */
340
341YAML_DECLARE(yaml_token_t *)
342yaml_version_directive_token_new(int major, int minor,
343        yaml_mark_t start_mark, yaml_mark_t end_mark);
344
345/**
346 * Create a new @c YAML_TAG_DIRECTIVE_TOKEN token with the specified tag
347 * handle and prefix.
348 *
349 * Note that the @a handle and the @a prefix pointers will be freed by
350 * the token descructor.
351 *
352 * @param[in]   handle      The tag handle.
353 * @param[in]   prefix      The tag prefix.
354 * @param[in]   start_mark  The beginning of the token.
355 * @param[in]   end_mark    The end of the token.
356 *
357 * @returns A new token object, or @c NULL on error.
358 */
359
360YAML_DECLARE(yaml_token_t *)
361yaml_tag_directive_token_new(yaml_char_t *handle, yaml_char_t *prefix,
362        yaml_mark_t start_mark, yaml_mark_t end_mark);
363
364/**
365 * Create a new @c YAML_ALIAS_TOKEN token with the specified anchor.
366 *
367 * Note that the @a anchor pointer will be freed by the token descructor.
368 *
369 * @param[in]   anchor      The anchor.
370 * @param[in]   start_mark  The beginning of the token.
371 * @param[in]   end_mark    The end of the token.
372 *
373 * @returns A new token object, or @c NULL on error.
374 */
375
376YAML_DECLARE(yaml_token_t *)
377yaml_alias_token_new(yaml_char_t *anchor,
378        yaml_mark_t start_mark, yaml_mark_t end_mark);
379
380/**
381 * Create a new @c YAML_ANCHOR_TOKEN token with the specified anchor.
382 *
383 * Note that the @a anchor pointer will be freed by the token descructor.
384 *
385 * @param[in]   anchor      The anchor.
386 * @param[in]   start_mark  The beginning of the token.
387 * @param[in]   end_mark    The end of the token.
388 *
389 * @returns A new token object, or @c NULL on error.
390 */
391
392YAML_DECLARE(yaml_token_t *)
393yaml_anchor_token_new(yaml_char_t *anchor,
394        yaml_mark_t start_mark, yaml_mark_t end_mark);
395
396/**
397 * Create a new @c YAML_TAG_TOKEN token with the specified tag handle and
398 * suffix.
399 *
400 * Note that the @a handle and the @a suffix pointers will be freed by
401 * the token descructor.
402 *
403 * @param[in]   handle      The tag handle.
404 * @param[in]   suffix      The tag suffix.
405 * @param[in]   start_mark  The beginning of the token.
406 * @param[in]   end_mark    The end of the token.
407 *
408 * @returns A new token object, or @c NULL on error.
409 */
410
411YAML_DECLARE(yaml_token_t *)
412yaml_tag_token_new(yaml_char_t *handle, yaml_char_t *suffix,
413        yaml_mark_t start_mark, yaml_mark_t end_mark);
414
415/**
416 * Create a new @c YAML_SCALAR_TOKEN token with the specified scalar value,
417 * length, and style.
418 *
419 * Note that the scalar value may contain the @c NUL character, therefore
420 * the value length is also required.  The scalar value always ends with
421 * @c NUL.
422 *
423 * Note that the @a value pointer will be freed by the token descructor.
424 *
425 * @param[in]   value       The scalar value.
426 * @param[in]   length      The value length.
427 * @param[in]   style       The scalar style.
428 * @param[in]   start_mark  The beginning of the token.
429 * @param[in]   end_mark    The end of the token.
430 *
431 * @returns A new token object, or @c NULL on error.
432 */
433
434YAML_DECLARE(yaml_token_t *)
435yaml_scalar_token_new(yaml_char_t *value, size_t length,
436        yaml_scalar_style_t style,
437        yaml_mark_t start_mark, yaml_mark_t end_mark);
438
439/**
440 * Destroy a token object.
441 *
442 * @param[in]   token   A token object.
443 */
444
445YAML_DECLARE(void)
446yaml_token_delete(yaml_token_t *token);
447
448/** @} */
449
[199]450/**
451 * @defgroup events Events
452 * @{
453 */
[183]454
[199]455/** Event types. */
[183]456typedef enum {
457    YAML_STREAM_START_EVENT,
458    YAML_STREAM_END_EVENT,
459
460    YAML_DOCUMENT_START_EVENT,
461    YAML_DOCUMENT_END_EVENT,
462
463    YAML_ALIAS_EVENT,
464    YAML_SCALAR_EVENT,
465
466    YAML_SEQUENCE_START_EVENT,
467    YAML_SEQUENCE_END_EVENT,
468
469    YAML_MAPPING_START_EVENT,
470    YAML_MAPPING_END_EVENT
471} yaml_event_type_t;
472
[199]473/** The event structure. */
[162]474typedef struct {
[199]475
476    /** The event type. */
[162]477    yaml_event_type_t type;
[199]478
479    /** The event data. */
[162]480    union {
[199]481       
482        /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
[162]483        struct {
[199]484            /** The document encoding. */
[162]485            yaml_encoding_t encoding;
486        } stream_start;
[199]487
488        /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
[162]489        struct {
[199]490            /** The version directive. */
491            yaml_version_directive_t *version_directive;
492            /** The list of tag directives. */
493            yaml_tag_directive_t **tag_directives;
494            /** Is the document indicator implicit? */
[162]495            int implicit;
496        } document_start;
[199]497
498        /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
[162]499        struct {
[199]500            /** Is the document end indicator implicit? */
[162]501            int implicit;
502        } document_end;
[199]503
504        /** The alias parameters (for @c YAML_ALIAS_EVENT). */
[162]505        struct {
[199]506            /** The anchor. */
507            yaml_char_t *anchor;
[162]508        } alias;
[199]509
510        /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
[162]511        struct {
[199]512            /** The anchor. */
513            yaml_char_t *anchor;
514            /** The tag. */
515            yaml_char_t *tag;
516            /** The scalar value. */
517            yaml_char_t *value;
518            /** The length of the scalar value. */
[169]519            size_t length;
[199]520            /** Is the tag optional for the plain style? */
[162]521            int plain_implicit;
[199]522            /** Is the tag optional for any non-plain style? */
[162]523            int quoted_implicit;
[199]524            /** The scalar style. */
[162]525            yaml_scalar_style_t style;
526        } scalar;
[199]527
528        /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
[162]529        struct {
[199]530            /** The anchor. */
531            yaml_char_t *anchor;
532            /** The tag. */
533            yaml_char_t *tag;
534            /** Is the tag optional? */
[162]535            int implicit;
[199]536            /** The sequence style. */
[162]537            yaml_sequence_style_t style;
538        } sequence_start;
[199]539
540        /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
[162]541        struct {
[199]542            /** The anchor. */
543            yaml_char_t *anchor;
544            /** The tag. */
545            yaml_char_t *tag;
546            /** Is the tag optional? */
[162]547            int implicit;
[199]548            /** The mapping style. */
[162]549            yaml_mapping_style_t style;
550        } mapping_start;
[199]551
[162]552    } data;
[199]553
554    /** The beginning of the token. */
[162]555    yaml_mark_t start_mark;
[199]556
557    /** The end of the token. */
[162]558    yaml_mark_t end_mark;
559} yaml_event_t;
560
[199]561/**
562 * Create a new @c YAML_STREAM_START_EVENT event.
563 *
564 * @param[in]   encoding    The stream encoding.
565 * @param[in]   start_mark  The beginning of the event.
566 * @param[in]   end_mark    The end of the event.
567 *
568 * @returns A new event object, or @c NULL on error.
569 */
[178]570
[199]571YAML_DECLARE(yaml_event_t *)
572yaml_stream_start_event_new(yaml_encoding_t encoding,
573        yaml_mark_t start_mark, yaml_mark_t end_mark);
[178]574
575/**
[199]576 * Create a new @c YAML_STREAM_END_TOKEN event.
577 *
578 * @param[in]   start_mark  The beginning of the event.
579 * @param[in]   end_mark    The end of the event.
580 *
581 * @returns A new event object, or @c NULL on error.
582 */
583
584YAML_DECLARE(yaml_event_t *)
585yaml_stream_end_event_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
586
587/**
588 * Create a new @c YAML_DOCUMENT_START_EVENT event.
589 *
590 * @param[in]   version_directive   The version directive or @c NULL.
591 * @param[in]   tag_directives      A list of tag directives or @c NULL.
592 * @param[in]   implicit            Is the document indicator present?
593 * @param[in]   start_mark          The beginning of the event.
594 * @param[in]   end_mark            The end of the event.
595 *
596 * @returns A new event object, or @c NULL on error.
597 */
598
599YAML_DECLARE(yaml_event_t *)
600yaml_document_start_event_new(yaml_version_directive_t *version_directive,
601        yaml_tag_directive_t **tag_directives, int implicit,
602        yaml_mark_t start_mark, yaml_mark_t end_mark);
603
604/**
605 * Create a new @c YAML_DOCUMENT_END_EVENT event.
606 *
607 * @param[in]   implicit    Is the document end indicator present?
608 * @param[in]   start_mark  The beginning of the event.
609 * @param[in]   end_mark    The end of the event.
610 *
611 * @returns A new event object, or @c NULL on error.
612 */
613
614YAML_DECLARE(yaml_event_t *)
615yaml_document_end_event_new(int implicit,
616        yaml_mark_t start_mark, yaml_mark_t end_mark);
617
618/**
619 * Create a new @c YAML_ALIAS_EVENT event.
620 *
621 * @param[in]   anchor      The anchor value.
622 * @param[in]   start_mark  The beginning of the event.
623 * @param[in]   end_mark    The end of the event.
624 *
625 * @returns A new event object, or @c NULL on error.
626 */
627
628YAML_DECLARE(yaml_event_t *)
629yaml_alias_event_new(yaml_char_t *anchor,
630        yaml_mark_t start_mark, yaml_mark_t end_mark);
631
632/**
633 * Create a new @c YAML_SCALAR_EVENT event.
634 *
635 * @param[in]   anchor          The anchor value or @c NULL.
636 * @param[in]   tag             The tag value or @c NULL.
637 * @param[in]   value           The scalar value.
638 * @param[in]   length          The length of the scalar value.
639 * @param[in]   plain_implicit  Is the tag optional for the plain style?
640 * @param[in]   quoted_implicit Is the tag optional for any non-plain style?
641 * @param[in]   style           The scalar style.
642 * @param[in]   start_mark      The beginning of the event.
643 * @param[in]   end_mark        The end of the event.
644 *
645 * @returns A new event object, or @c NULL on error.
646 */
647
648YAML_DECLARE(yaml_event_t *)
649yaml_scalar_event_new(yaml_char_t *anchor, yaml_char_t *tag,
650        yaml_char_t *value, size_t length,
651        int plain_implicit, int quoted_implicit,
652        yaml_scalar_style_t style,
653        yaml_mark_t start_mark, yaml_mark_t end_mark);
654
655/**
656 * Create a new @c YAML_SEQUENCE_START_EVENT event.
657 *
658 * @param[in]   anchor      The anchor value or @c NULL.
659 * @param[in]   tag         The tag value or @c NULL.
660 * @param[in]   implicit    Is the tag optional?
661 * @param[in]   style       The sequence style.
662 * @param[in]   start_mark  The beginning of the event.
663 * @param[in]   end_mark    The end of the event.
664 *
665 * @returns A new event object, or @c NULL on error.
666 */
667
668YAML_DECLARE(yaml_event_t *)
669yaml_sequence_start_new(yaml_char_t *anchor, yaml_char_t *tag,
670        int implicit, yaml_sequence_style_t style,
671        yaml_mark_t start_mark, yaml_mark_t end_mark);
672
673/**
674 * Create a new @c YAML_SEQUENCE_END_EVENT event.
675 *
676 * @param[in]   start_mark  The beginning of the event.
677 * @param[in]   end_mark    The end of the event.
678 *
679 * @returns A new event object, or @c NULL on error.
680 */
681
682YAML_DECLARE(yaml_event_t *)
683yaml_sequence_end_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
684
685/**
686 * Create a new @c YAML_MAPPING_START_EVENT event.
687 *
688 * @param[in]   anchor      The anchor value or @c NULL.
689 * @param[in]   tag         The tag value or @c NULL.
690 * @param[in]   implicit    Is the tag optional?
691 * @param[in]   style       The mapping style.
692 * @param[in]   start_mark  The beginning of the event.
693 * @param[in]   end_mark    The end of the event.
694 *
695 * @returns A new event object, or @c NULL on error.
696 */
697
698YAML_DECLARE(yaml_event_t *)
699yaml_mapping_start_new(yaml_char_t *anchor, yaml_char_t *tag,
700        int implicit, yaml_mapping_style_t style,
701        yaml_mark_t start_mark, yaml_mark_t end_mark);
702
703/**
704 * Create a new @c YAML_MAPPING_END_EVENT event.
705 *
706 * @param[in]   start_mark  The beginning of the event.
707 * @param[in]   end_mark    The end of the event.
708 *
709 * @returns A new event object, or @c NULL on error.
710 */
711
712YAML_DECLARE(yaml_event_t *)
713yaml_mapping_end_new(yaml_mark_t start_mark, yaml_mark_t end_mark);
714
715/**
716 * Destroy an event object.
717 *
718 * @param[in]   event   An event object.
719 */
720
721YAML_DECLARE(void)
722yaml_event_delete(yaml_event_t *event);
723
724/** @} */
725
726/**
[178]727 * @defgroup parser Parser Definitions
728 * @{
729 */
730
731/**
732 * The prototype of a read handler.
733 *
734 * The read handler is called when the parser needs to read more bytes from the
735 * source.  The handler should write not more than @a size bytes to the @a
736 * buffer.  The number of written bytes should be set to the @a length variable.
737 *
[180]738 * @param[in]   data        A pointer to an application data specified by
[179]739 *                          @c yaml_parser_set_read_handler.
740 * @param[out]  buffer      The buffer to write the data from the source.
741 * @param[in]   size        The size of the buffer.
742 * @param[out]  size_read   The actual number of bytes read from the source.
[178]743 *
744 * @returns On success, the handler should return @c 1.  If the handler failed,
745 * the returned value should be @c 0.  On EOF, the handler should set the
746 * @a length to @c 0 and return @c 1.
747 */
[180]748
749typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
[179]750        size_t *size_read);
[178]751
752/**
[180]753 * This structure holds a string input specified by
754 * @c yaml_parser_set_input_string.
755 */
756
757typedef struct {
[183]758    /** The string start pointer. */
[180]759    unsigned char *start;
[183]760
761    /** The string end pointer. */
[180]762    unsigned char *end;
[183]763
764    /** The string current position. */
[180]765    unsigned char *current;
766} yaml_string_input_t;
767
768/**
[184]769 * This structure holds information about a potential simple key.
770 */
771
772typedef struct {
773    /** Is a simple key required? */
774    int required;
775
776    /** The number of the token. */
777    size_t token_number;
778
779    /** The position index. */
780    size_t index;
781
782    /** The position line. */
783    size_t line;
784
785    /** The position column. */
786    size_t column;
787
788    /** The position mark. */
789    yaml_mark_t mark;
790} yaml_simple_key_t;
791
792/**
[178]793 * The parser structure.
794 *
795 * All members are internal.  Manage the structure using the @c yaml_parser_
796 * family of functions.
797 */
798
[162]799typedef struct {
[178]800
801    /**
[179]802     * @name Error handling
803     * @{
804     */
805
[181]806    /** Error type. */
[180]807    yaml_error_type_t error;
[179]808
[181]809    /** Error description. */
810    const char *problem;
811
812    /** The byte about which the problem occured. */
813    size_t problem_offset;
814
[182]815    /** The problematic value (@c -1 is none). */
816    int problem_value;
817
[185]818    /** The problem position. */
819    yaml_mark_t problem_mark;
820
821    /** The error context. */
822    const char *context;
823
824    /** The context position. */
825    yaml_mark_t context_mark;
826
[179]827    /**
828     * @}
829     */
830
831    /**
[178]832     * @name Reader stuff
833     * @{
834     */
835
[181]836    /** Read handler. */
[179]837    yaml_read_handler_t *read_handler;
[178]838
839    /** A pointer for passing to the read handler. */
[179]840    void *read_handler_data;
[178]841
842    /** EOF flag */
843    int eof;
844
845    /** The pointer to the beginning of the working buffer. */
846    yaml_char_t *buffer;
847
[180]848    /** The pointer to the end of the working buffer. */
849    yaml_char_t *buffer_end;
[179]850
[178]851    /** The pointer to the current character in the working buffer. */
[180]852    yaml_char_t *pointer;
[178]853
[180]854    /** The number of unread characters in the working buffer. */
855    size_t unread;
[179]856
[180]857    /** The pointer to the beginning of the raw buffer. */
[178]858    unsigned char *raw_buffer;
859
[180]860    /** The pointer to the current character in the raw buffer. */
861    unsigned char *raw_pointer;
[178]862
[180]863    /** The number of unread bytes in the raw buffer. */
864    size_t raw_unread;
[179]865
[178]866    /** The input encoding. */
867    yaml_encoding_t encoding;
868
[179]869    /** The offset of the current position (in bytes). */
870    size_t offset;
871
872    /** The index of the current position (in characters). */
873    size_t index;
874
875    /** The line of the current position (starting from @c 0). */
876    size_t line;
877
878    /** The column of the current position (starting from @c 0). */
879    size_t column;
880
[180]881    /* String input structure. */
882    yaml_string_input_t string_input;
883
[178]884    /**
885     * @}
886     */
887
[184]888    /**
889     * @name Scanner stuff
890     * @{
891     */
892
893    /** Have we started to scan the input stream? */
894    int stream_start_produced;
895
896    /** Have we reached the end of the input stream? */
897    int stream_end_produced;
898
899    /** The number of unclosed '[' and '{' indicators. */
900    int flow_level;
901
902    /** The tokens queue, which contains the current produced tokens. */
[185]903    yaml_token_t **tokens;
[184]904
905    /** The size of the tokens queue. */
906    size_t tokens_size;
907
908    /** The head of the tokens queue. */
909    size_t tokens_head;
910
911    /** The tail of the tokens queue. */
912    size_t tokens_tail;
913
914    /** The number of tokens fetched from the tokens queue. */
915    size_t tokens_parsed;
916
917    /** The stack of indentation levels. */
918    int *indents;
919
920    /** The size of the indents stack. */
921    size_t indents_size;
922
923    /** The number of items in the indents stack. */
924    size_t indents_length;
925
926    /** The current indentation level. */
927    int indent;
928
929    /** May a simple key occur at the current position? */
930    int simple_key_allowed;
931
932    /** The stack of potential simple keys. */
[185]933    yaml_simple_key_t **simple_keys;
[184]934
935    /** The size of the simple keys stack. */
936    size_t simple_keys_size;
937
938    /**
939     * @}
940     */
941
[162]942} yaml_parser_t;
943
[178]944/**
945 * Create a new parser.
946 *
947 * This function creates a new parser object.  An application is responsible
948 * for destroying the object using the @c yaml_parser_delete function.
949 *
950 * @returns A new parser object; @c NULL on error.
951 */
952
[183]953YAML_DECLARE(yaml_parser_t *)
[178]954yaml_parser_new(void);
955
956/**
957 * Destroy a parser.
958 *
959 * @param[in]   parser  A parser object.
960 */
961
[183]962YAML_DECLARE(void)
[178]963yaml_parser_delete(yaml_parser_t *parser);
964
[179]965/**
966 * Set a string input.
967 *
968 * Note that the @a input pointer must be valid while the @a parser object
969 * exists.  The application is responsible for destroing @a input after
970 * destroying the @a parser.
971 *
972 * @param[in]   parser  A parser object.
973 * @param[in]   input   A source data.
[183]974 * @param[in]   size    The length of the source data in bytes.
[179]975 */
976
[183]977YAML_DECLARE(void)
[179]978yaml_parser_set_input_string(yaml_parser_t *parser,
979        unsigned char *input, size_t size);
980
981
982/**
983 * Set a file input.
984 *
985 * @a file should be a file object open for reading.  The application is
986 * responsible for closing the @a file.
987 *
988 * @param[in]   parser  A parser object.
989 * @param[in]   file    An open file.
990 */
991
[183]992YAML_DECLARE(void)
[179]993yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
994
995/**
996 * Set a generic input handler.
997 *
998 * @param[in]   parser  A parser object.
999 * @param[in]   handler A read handler.
1000 * @param[in]   data    Any application data for passing to the read handler.
1001 */
1002
[183]1003YAML_DECLARE(void)
[179]1004yaml_parser_set_input(yaml_parser_t *parser,
1005        yaml_read_handler_t *handler, void *data);
1006
1007/**
1008 * Set the source encoding.
1009 *
[183]1010 * @param[in]   parser      A parser object.
[179]1011 * @param[in]   encoding    The source encoding.
1012 */
1013
[183]1014YAML_DECLARE(void)
[179]1015yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1016
[184]1017/**
1018 * Get the next token.
1019 *
1020 * The token is removed from the internal token queue and the application is
1021 * responsible for destroing the token object.
1022 *
1023 * @param[in]   parser      A parser object.
1024 *
1025 * @returns A token object, or @c NULL on error.
1026 */
1027
1028YAML_DECLARE(yaml_token_t *)
1029yaml_parser_get_token(yaml_parser_t *parser);
1030
1031/**
1032 * Peek the next token.
1033 *
1034 * The token is not removed from the internal token queue and will be returned
1035 * again on a subsequent call of @c yaml_parser_get_token or
1036 * @c yaml_parser_peek_token. The application should not destroy the token
1037 * object.
1038 *
1039 * @param[in]   parser      A parser object.
1040 *
1041 * @returns A token object, or @c NULL on error.
1042 */
1043
1044YAML_DECLARE(yaml_token_t *)
1045yaml_parser_peek_token(yaml_parser_t *parser);
1046
[178]1047/** @} */
1048
1049/*
[162]1050typedef struct {
1051} yaml_emitter_t;
[169]1052*/
[162]1053
[179]1054/**
1055 * @defgroup internal Internal Definitions
1056 * @{
1057 */
1058
1059/**
1060 * Allocate a dynamic memory block.
1061 *
1062 * @param[in]   size    Size of a memory block, \c 0 is valid.
1063 *
1064 * @returns @c yaml_malloc returns a pointer to a newly allocated memory block,
1065 * or @c NULL if it failed.
1066 */
1067
[183]1068YAML_DECLARE(void *)
[179]1069yaml_malloc(size_t size);
1070
1071/**
1072 * Reallocate a dynamic memory block.
1073 *
1074 * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
1075 *                      valid.
1076 * @param[in]   size    A size of a new block, \c 0 is valid.
1077 *
1078 * @returns @c yaml_realloc returns a pointer to a reallocated memory block,
1079 * or @c NULL if it failed.
1080 */
1081
[183]1082YAML_DECLARE(void *)
[179]1083yaml_realloc(void *ptr, size_t size);
1084
1085/**
1086 * Free a dynamic memory block.
1087 *
1088 * @param[in]   ptr     A pointer to an existing memory block, \c NULL is
1089 *                      valid.
1090 */
1091
[183]1092YAML_DECLARE(void)
[179]1093yaml_free(void *ptr);
1094
[185]1095/** The initial size for various buffers. */
1096
1097#define YAML_DEFAULT_SIZE   16
1098
[180]1099/** The size of the raw buffer. */
1100
1101#define YAML_RAW_BUFFER_SIZE 16384
1102
1103/**
1104 * The size of the buffer.
1105 *
1106 * We allocate enough space for decoding the whole raw buffer.
1107 */
1108
1109#define YAML_BUFFER_SIZE    (YAML_RAW_BUFFER_SIZE*3)
1110
[181]1111/**
1112 * Ensure that the buffer contains at least @a length characters.
1113 *
1114 * @param[in]   parser  A parser object.
1115 * @param[in]   length  The number of characters in the buffer.
1116 *
1117 * @returns @c 1 on success, @c 0 on error.
1118 */
1119
[183]1120YAML_DECLARE(int)
[181]1121yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
1122
[179]1123/** @} */
1124
1125
[162]1126#ifdef __cplusplus
1127}
1128#endif
1129
[169]1130#endif /* #ifndef YAML_H */
[162]1131
Note: See TracBrowser for help on using the repository browser.