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.

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 export Export Definitions
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/**
44 * @defgroup version Version Information
45 * @{
46 */
47
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
56YAML_DECLARE(const char *)
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
67YAML_DECLARE(void)
68yaml_get_version(int *major, int *minor, int *patch);
69
70/** @} */
71
72/**
73 * @defgroup basic Basic Types
74 * @{
75 */
76
77/** The character type (UTF-8 octet). */
78typedef unsigned char yaml_char_t;
79
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
96/** The stream encoding. */
97typedef enum {
98    YAML_ANY_ENCODING,
99    YAML_UTF8_ENCODING,
100    YAML_UTF16LE_ENCODING,
101    YAML_UTF16BE_ENCODING
102} yaml_encoding_t;
103
104/** Many bad things could happen with the parser and emitter. */
105typedef enum {
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
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
130/** @} */
131
132/**
133 * @defgroup styles Node Styles
134 * @{
135 */
136
137/** Scalar styles. */
138typedef enum {
139    YAML_ANY_SCALAR_STYLE,
140
141    YAML_PLAIN_SCALAR_STYLE,
142
143    YAML_SINGLE_QUOTED_SCALAR_STYLE,
144    YAML_DOUBLE_QUOTED_SCALAR_STYLE,
145
146    YAML_LITERAL_SCALAR_STYLE,
147    YAML_FOLDED_SCALAR_STYLE
148} yaml_scalar_style_t;
149
150
151/** Sequence styles. */
152typedef enum {
153    YAML_ANY_SEQUENCE_STYLE,
154
155    YAML_BLOCK_SEQUENCE_STYLE,
156    YAML_FLOW_SEQUENCE_STYLE
157} yaml_sequence_style_t;
158
159/** Mapping styles. */
160typedef enum {
161    YAML_ANY_MAPPING_STYLE,
162
163    YAML_BLOCK_MAPPING_STYLE,
164    YAML_FLOW_MAPPING_STYLE
165} yaml_mapping_style_t;
166
167/** @} */
168
169/**
170 * @defgroup tokens Tokens
171 * @{
172 */
173
174/** Token types. */
175typedef enum {
176    YAML_STREAM_START_TOKEN,
177    YAML_STREAM_END_TOKEN,
178
179    YAML_VERSION_DIRECTIVE_TOKEN,
180    YAML_TAG_DIRECTIVE_TOKEN,
181    YAML_DOCUMENT_START_TOKEN,
182    YAML_DOCUMENT_END_TOKEN,
183
184    YAML_BLOCK_SEQUENCE_START_TOKEN,
185    YAML_BLOCK_MAPPING_START_TOKEN,
186    YAML_BLOCK_END_TOKEN,
187
188    YAML_FLOW_SEQUENCE_START_TOKEN,
189    YAML_FLOW_SEQUENCE_END_TOKEN,
190    YAML_FLOW_MAPPING_START_TOKEN,
191    YAML_FLOW_MAPPING_END_TOKEN,
192
193    YAML_BLOCK_ENTRY_TOKEN,
194    YAML_FLOW_ENTRY_TOKEN,
195    YAML_KEY_TOKEN,
196    YAML_VALUE_TOKEN,
197
198    YAML_ALIAS_TOKEN,
199    YAML_ANCHOR_TOKEN,
200    YAML_TAG_TOKEN,
201    YAML_SCALAR_TOKEN
202} yaml_token_type_t;
203
204/** The token structure. */
205typedef struct {
206
207    /** The token type. */
208    yaml_token_type_t type;
209
210    /** The token data. */
211    union {
212
213        /** The stream start (for @c YAML_STREAM_START_TOKEN). */
214        struct {
215            /** The stream encoding. */
216            yaml_encoding_t encoding;
217        } stream_start;
218
219        /** The alias (for @c YAML_ALIAS_TOKEN). */
220        struct {
221            /** The alias value. */
222            yaml_char_t *value;
223        } alias;
224
225        /** The anchor (for @c YAML_ANCHOR_TOKEN). */
226        struct {
227            /** The anchor value. */
228            yaml_char_t *value;
229        } anchor;
230
231        /** The tag (for @c YAML_TAG_TOKEN). */
232        struct {
233            /** The tag handle. */
234            yaml_char_t *handle;
235
236            /** The tag suffix. */
237            yaml_char_t *suffix;
238        } tag;
239
240        /** The scalar value (for @c YAML_SCALAR_TOKEN). */
241        struct {
242
243            /** The scalar value. */
244            yaml_char_t *value;
245
246            /** The length of the scalar value. */
247            size_t length;
248
249            /** The scalar style. */
250            yaml_scalar_style_t style;
251        } scalar;
252
253        /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
254        struct {
255            /** The major version number. */
256            int major;
257
258            /** The minor version number. */
259            int minor;
260        } version_directive;
261
262        /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
263        struct {
264            /** The tag handle. */
265            yaml_char_t *handle;
266
267            /** The tag prefix. */
268            yaml_char_t *prefix;
269        } tag_directive;
270    } data;
271
272    /** The beginning of the token. */
273    yaml_mark_t start_mark;
274
275    /** The end of the token. */
276    yaml_mark_t end_mark;
277
278} yaml_token_t;
279
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
450/**
451 * @defgroup events Events
452 * @{
453 */
454
455/** Event types. */
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
473/** The event structure. */
474typedef struct {
475
476    /** The event type. */
477    yaml_event_type_t type;
478
479    /** The event data. */
480    union {
481       
482        /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
483        struct {
484            /** The document encoding. */
485            yaml_encoding_t encoding;
486        } stream_start;
487
488        /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
489        struct {
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? */
495            int implicit;
496        } document_start;
497
498        /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
499        struct {
500            /** Is the document end indicator implicit? */
501            int implicit;
502        } document_end;
503
504        /** The alias parameters (for @c YAML_ALIAS_EVENT). */
505        struct {
506            /** The anchor. */
507            yaml_char_t *anchor;
508        } alias;
509
510        /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
511        struct {
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. */
519            size_t length;
520            /** Is the tag optional for the plain style? */
521            int plain_implicit;
522            /** Is the tag optional for any non-plain style? */
523            int quoted_implicit;
524            /** The scalar style. */
525            yaml_scalar_style_t style;
526        } scalar;
527
528        /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
529        struct {
530            /** The anchor. */
531            yaml_char_t *anchor;
532            /** The tag. */
533            yaml_char_t *tag;
534            /** Is the tag optional? */
535            int implicit;
536            /** The sequence style. */
537            yaml_sequence_style_t style;
538        } sequence_start;
539
540        /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
541        struct {
542            /** The anchor. */
543            yaml_char_t *anchor;
544            /** The tag. */
545            yaml_char_t *tag;
546            /** Is the tag optional? */
547            int implicit;
548            /** The mapping style. */
549            yaml_mapping_style_t style;
550        } mapping_start;
551
552    } data;
553
554    /** The beginning of the token. */
555    yaml_mark_t start_mark;
556
557    /** The end of the token. */
558    yaml_mark_t end_mark;
559} yaml_event_t;
560
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 */
570
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);
574
575/**
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/**
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 *
738 * @param[in]   data        A pointer to an application data specified by
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.
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 */
748
749typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
750        size_t *size_read);
751
752/**
753 * This structure holds a string input specified by
754 * @c yaml_parser_set_input_string.
755 */
756
757typedef struct {
758    /** The string start pointer. */
759    unsigned char *start;
760
761    /** The string end pointer. */
762    unsigned char *end;
763
764    /** The string current position. */
765    unsigned char *current;
766} yaml_string_input_t;
767
768/**
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/**
793 * The parser structure.
794 *
795 * All members are internal.  Manage the structure using the @c yaml_parser_
796 * family of functions.
797 */
798
799typedef struct {
800
801    /**
802     * @name Error handling
803     * @{
804     */
805
806    /** Error type. */
807    yaml_error_type_t error;
808
809    /** Error description. */
810    const char *problem;
811
812    /** The byte about which the problem occured. */
813    size_t problem_offset;
814
815    /** The problematic value (@c -1 is none). */
816    int problem_value;
817
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
827    /**
828     * @}
829     */
830
831    /**
832     * @name Reader stuff
833     * @{
834     */
835
836    /** Read handler. */
837    yaml_read_handler_t *read_handler;
838
839    /** A pointer for passing to the read handler. */
840    void *read_handler_data;
841
842    /** EOF flag */
843    int eof;
844
845    /** The pointer to the beginning of the working buffer. */
846    yaml_char_t *buffer;
847
848    /** The pointer to the end of the working buffer. */
849    yaml_char_t *buffer_end;
850
851    /** The pointer to the current character in the working buffer. */
852    yaml_char_t *pointer;
853
854    /** The number of unread characters in the working buffer. */
855    size_t unread;
856
857    /** The pointer to the beginning of the raw buffer. */
858    unsigned char *raw_buffer;
859
860    /** The pointer to the current character in the raw buffer. */
861    unsigned char *raw_pointer;
862
863    /** The number of unread bytes in the raw buffer. */
864    size_t raw_unread;
865
866    /** The input encoding. */
867    yaml_encoding_t encoding;
868
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
881    /* String input structure. */
882    yaml_string_input_t string_input;
883
884    /**
885     * @}
886     */
887
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. */
903    yaml_token_t **tokens;
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. */
933    yaml_simple_key_t **simple_keys;
934
935    /** The size of the simple keys stack. */
936    size_t simple_keys_size;
937
938    /**
939     * @}
940     */
941
942} yaml_parser_t;
943
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
953YAML_DECLARE(yaml_parser_t *)
954yaml_parser_new(void);
955
956/**
957 * Destroy a parser.
958 *
959 * @param[in]   parser  A parser object.
960 */
961
962YAML_DECLARE(void)
963yaml_parser_delete(yaml_parser_t *parser);
964
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.
974 * @param[in]   size    The length of the source data in bytes.
975 */
976
977YAML_DECLARE(void)
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
992YAML_DECLARE(void)
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
1003YAML_DECLARE(void)
1004yaml_parser_set_input(yaml_parser_t *parser,
1005        yaml_read_handler_t *handler, void *data);
1006
1007/**
1008 * Set the source encoding.
1009 *
1010 * @param[in]   parser      A parser object.
1011 * @param[in]   encoding    The source encoding.
1012 */
1013
1014YAML_DECLARE(void)
1015yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1016
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
1047/** @} */
1048
1049/*
1050typedef struct {
1051} yaml_emitter_t;
1052*/
1053
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
1068YAML_DECLARE(void *)
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
1082YAML_DECLARE(void *)
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
1092YAML_DECLARE(void)
1093yaml_free(void *ptr);
1094
1095/** The initial size for various buffers. */
1096
1097#define YAML_DEFAULT_SIZE   16
1098
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
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
1120YAML_DECLARE(int)
1121yaml_parser_update_buffer(yaml_parser_t *parser, size_t length);
1122
1123/** @} */
1124
1125
1126#ifdef __cplusplus
1127}
1128#endif
1129
1130#endif /* #ifndef YAML_H */
1131
Note: See TracBrowser for help on using the repository browser.