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

Revision 208, 20.0 KB checked in by xi, 8 years ago (diff)

Refactor internal and external API.

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/** Sequence styles. */
151typedef enum {
152    YAML_ANY_SEQUENCE_STYLE,
153
154    YAML_BLOCK_SEQUENCE_STYLE,
155    YAML_FLOW_SEQUENCE_STYLE
156} yaml_sequence_style_t;
157
158/** Mapping styles. */
159typedef enum {
160    YAML_ANY_MAPPING_STYLE,
161
162    YAML_BLOCK_MAPPING_STYLE,
163    YAML_FLOW_MAPPING_STYLE,
164    YAML_FLOW_SET_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_NO_TOKEN,
177
178    YAML_STREAM_START_TOKEN,
179    YAML_STREAM_END_TOKEN,
180
181    YAML_VERSION_DIRECTIVE_TOKEN,
182    YAML_TAG_DIRECTIVE_TOKEN,
183    YAML_DOCUMENT_START_TOKEN,
184    YAML_DOCUMENT_END_TOKEN,
185
186    YAML_BLOCK_SEQUENCE_START_TOKEN,
187    YAML_BLOCK_MAPPING_START_TOKEN,
188    YAML_BLOCK_END_TOKEN,
189
190    YAML_FLOW_SEQUENCE_START_TOKEN,
191    YAML_FLOW_SEQUENCE_END_TOKEN,
192    YAML_FLOW_MAPPING_START_TOKEN,
193    YAML_FLOW_MAPPING_END_TOKEN,
194
195    YAML_BLOCK_ENTRY_TOKEN,
196    YAML_FLOW_ENTRY_TOKEN,
197    YAML_KEY_TOKEN,
198    YAML_VALUE_TOKEN,
199
200    YAML_ALIAS_TOKEN,
201    YAML_ANCHOR_TOKEN,
202    YAML_TAG_TOKEN,
203    YAML_SCALAR_TOKEN
204} yaml_token_type_t;
205
206/** The token structure. */
207typedef struct {
208
209    /** The token type. */
210    yaml_token_type_t type;
211
212    /** The token data. */
213    union {
214
215        /** The stream start (for @c YAML_STREAM_START_TOKEN). */
216        struct {
217            /** The stream encoding. */
218            yaml_encoding_t encoding;
219        } stream_start;
220
221        /** The alias (for @c YAML_ALIAS_TOKEN). */
222        struct {
223            /** The alias value. */
224            yaml_char_t *value;
225        } alias;
226
227        /** The anchor (for @c YAML_ANCHOR_TOKEN). */
228        struct {
229            /** The anchor value. */
230            yaml_char_t *value;
231        } anchor;
232
233        /** The tag (for @c YAML_TAG_TOKEN). */
234        struct {
235            /** The tag handle. */
236            yaml_char_t *handle;
237            /** The tag suffix. */
238            yaml_char_t *suffix;
239        } tag;
240
241        /** The scalar value (for @c YAML_SCALAR_TOKEN). */
242        struct {
243            /** The scalar value. */
244            yaml_char_t *value;
245            /** The length of the scalar value. */
246            size_t length;
247            /** The scalar style. */
248            yaml_scalar_style_t style;
249        } scalar;
250
251        /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
252        struct {
253            /** The major version number. */
254            int major;
255            /** The minor version number. */
256            int minor;
257        } version_directive;
258
259        /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
260        struct {
261            /** The tag handle. */
262            yaml_char_t *handle;
263            /** The tag prefix. */
264            yaml_char_t *prefix;
265        } tag_directive;
266
267    } data;
268
269    /** The beginning of the token. */
270    yaml_mark_t start_mark;
271    /** The end of the token. */
272    yaml_mark_t end_mark;
273
274} yaml_token_t;
275
276/**
277 * Free any memory allocated for a token object.
278 *
279 * @param[in]   token   A token object.
280 */
281
282YAML_DECLARE(void)
283yaml_token_delete(yaml_token_t *token);
284
285/** @} */
286
287/**
288 * @defgroup events Events
289 * @{
290 */
291
292/** Event types. */
293typedef enum {
294    YAML_NO_EVENT,
295
296    YAML_STREAM_START_EVENT,
297    YAML_STREAM_END_EVENT,
298
299    YAML_DOCUMENT_START_EVENT,
300    YAML_DOCUMENT_END_EVENT,
301
302    YAML_ALIAS_EVENT,
303    YAML_SCALAR_EVENT,
304
305    YAML_SEQUENCE_START_EVENT,
306    YAML_SEQUENCE_END_EVENT,
307
308    YAML_MAPPING_START_EVENT,
309    YAML_MAPPING_END_EVENT
310} yaml_event_type_t;
311
312/** The event structure. */
313typedef struct {
314
315    /** The event type. */
316    yaml_event_type_t type;
317
318    /** The event data. */
319    union {
320       
321        /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
322        struct {
323            /** The document encoding. */
324            yaml_encoding_t encoding;
325        } stream_start;
326
327        /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
328        struct {
329            /** The version directive. */
330            yaml_version_directive_t *version_directive;
331
332            /** The list of tag directives. */
333            struct {
334                /** The beginning of the tag directives list. */
335                yaml_tag_directive_t *start;
336                /** The end of the tag directives list. */
337                yaml_tag_directive_t *end;
338            } tag_directives;
339
340            /** Is the document indicator implicit? */
341            int implicit;
342        } document_start;
343
344        /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
345        struct {
346            /** Is the document end indicator implicit? */
347            int implicit;
348        } document_end;
349
350        /** The alias parameters (for @c YAML_ALIAS_EVENT). */
351        struct {
352            /** The anchor. */
353            yaml_char_t *anchor;
354        } alias;
355
356        /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
357        struct {
358            /** The anchor. */
359            yaml_char_t *anchor;
360            /** The tag. */
361            yaml_char_t *tag;
362            /** The scalar value. */
363            yaml_char_t *value;
364            /** The length of the scalar value. */
365            size_t length;
366            /** Is the tag optional for the plain style? */
367            int plain_implicit;
368            /** Is the tag optional for any non-plain style? */
369            int quoted_implicit;
370            /** The scalar style. */
371            yaml_scalar_style_t style;
372        } scalar;
373
374        /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
375        struct {
376            /** The anchor. */
377            yaml_char_t *anchor;
378            /** The tag. */
379            yaml_char_t *tag;
380            /** Is the tag optional? */
381            int implicit;
382            /** The sequence style. */
383            yaml_sequence_style_t style;
384        } sequence_start;
385
386        /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
387        struct {
388            /** The anchor. */
389            yaml_char_t *anchor;
390            /** The tag. */
391            yaml_char_t *tag;
392            /** Is the tag optional? */
393            int implicit;
394            /** The mapping style. */
395            yaml_mapping_style_t style;
396        } mapping_start;
397
398    } data;
399
400    /** The beginning of the token. */
401    yaml_mark_t start_mark;
402    /** The end of the token. */
403    yaml_mark_t end_mark;
404
405} yaml_event_t;
406
407/**
408 * Free any memory allocated for an event object.
409 *
410 * @param[in]   event   An event object.
411 */
412
413YAML_DECLARE(void)
414yaml_event_delete(yaml_event_t *event);
415
416/** @} */
417
418/**
419 * @defgroup parser Parser Definitions
420 * @{
421 */
422
423/**
424 * The prototype of a read handler.
425 *
426 * The read handler is called when the parser needs to read more bytes from the
427 * source.  The handler should write not more than @a size bytes to the @a
428 * buffer.  The number of written bytes should be set to the @a length variable.
429 *
430 * @param[in]   data        A pointer to an application data specified by
431 *                          @c yaml_parser_set_read_handler.
432 * @param[out]  buffer      The buffer to write the data from the source.
433 * @param[in]   size        The size of the buffer.
434 * @param[out]  size_read   The actual number of bytes read from the source.
435 *
436 * @returns On success, the handler should return @c 1.  If the handler failed,
437 * the returned value should be @c 0.  On EOF, the handler should set the
438 * @a length to @c 0 and return @c 1.
439 */
440
441typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
442        size_t *size_read);
443
444/**
445 * This structure holds information about a potential simple key.
446 */
447
448typedef struct {
449    /** Is a simple key possible? */
450    int possible;
451
452    /** Is a simple key required? */
453    int required;
454
455    /** The number of the token. */
456    size_t token_number;
457
458    /** The position mark. */
459    yaml_mark_t mark;
460} yaml_simple_key_t;
461
462/**
463 * The states of the parser.
464 */
465typedef enum {
466    YAML_PARSE_STREAM_START_STATE,
467    YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
468    YAML_PARSE_DOCUMENT_START_STATE,
469    YAML_PARSE_DOCUMENT_CONTENT_STATE,
470    YAML_PARSE_DOCUMENT_END_STATE,
471    YAML_PARSE_BLOCK_NODE_STATE,
472    YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
473    YAML_PARSE_FLOW_NODE_STATE,
474    YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
475    YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
476    YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
477    YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
478    YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
479    YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
480    YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
481    YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
482    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
483    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
484    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
485    YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
486    YAML_PARSE_FLOW_MAPPING_KEY_STATE,
487    YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
488    YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
489    YAML_PARSE_END_STATE
490} yaml_parser_state_t;
491
492/**
493 * The parser structure.
494 *
495 * All members are internal.  Manage the structure using the @c yaml_parser_
496 * family of functions.
497 */
498
499typedef struct {
500
501    /**
502     * @name Error handling
503     * @{
504     */
505
506    /** Error type. */
507    yaml_error_type_t error;
508    /** Error description. */
509    const char *problem;
510    /** The byte about which the problem occured. */
511    size_t problem_offset;
512    /** The problematic value (@c -1 is none). */
513    int problem_value;
514    /** The problem position. */
515    yaml_mark_t problem_mark;
516    /** The error context. */
517    const char *context;
518    /** The context position. */
519    yaml_mark_t context_mark;
520
521    /**
522     * @}
523     */
524
525    /**
526     * @name Reader stuff
527     * @{
528     */
529
530    /** Read handler. */
531    yaml_read_handler_t *read_handler;
532
533    /** A pointer for passing to the read handler. */
534    void *read_handler_data;
535
536    /** Standard (string or file) input data. */
537    union {
538        /** String input data. */
539        struct {
540            /** The string start pointer. */
541            unsigned char *start;
542            /** The string end pointer. */
543            unsigned char *end;
544            /** The string current position. */
545            unsigned char *current;
546        } string;
547
548        /** File input data. */
549        FILE *file;
550    } input;
551
552    /** EOF flag */
553    int eof;
554
555    /** The working buffer. */
556    struct {
557        /* The beginning of the buffer. */
558        yaml_char_t *start;
559        /* The end of the buffer. */
560        yaml_char_t *end;
561        /* The current position of the buffer. */
562        yaml_char_t *pointer;
563        /* The last filled position of the buffer. */
564        yaml_char_t *last;
565    } buffer;
566
567    /* The number of unread characters in the buffer. */
568    size_t unread;
569
570    /** The raw buffer. */
571    struct {
572        /** The beginning of the buffer. */
573        unsigned char *start;
574        /** The end of the buffer. */
575        unsigned char *end;
576        /** The current position of the buffer. */
577        unsigned char *pointer;
578        /** The last filled position of the buffer. */
579        unsigned char *last;
580    } raw_buffer;
581
582    /** The input encoding. */
583    yaml_encoding_t encoding;
584
585    /** The offset of the current position (in bytes). */
586    size_t offset;
587
588    /** The mark of the current position. */
589    yaml_mark_t mark;
590
591    /**
592     * @}
593     */
594
595    /**
596     * @name Scanner stuff
597     * @{
598     */
599
600    /** Have we started to scan the input stream? */
601    int stream_start_produced;
602
603    /** Have we reached the end of the input stream? */
604    int stream_end_produced;
605
606    /** The number of unclosed '[' and '{' indicators. */
607    int flow_level;
608
609    /** The tokens queue. */
610    struct {
611        /** The beginning of the tokens queue. */
612        yaml_token_t *start;
613        /** The end of the tokens queue. */
614        yaml_token_t *end;
615        /** The head of the tokens queue. */
616        yaml_token_t *head;
617        /** The tail of the tokens queue. */
618        yaml_token_t *tail;
619    } tokens;
620
621    /** The number of tokens fetched from the queue. */
622    size_t tokens_parsed;
623
624    /* Does the tokens queue contain a token ready for dequeueing. */
625    int token_available;
626
627    /** The indentation levels stack. */
628    struct {
629        /** The beginning of the stack. */
630        int *start;
631        /** The end of the stack. */
632        int *end;
633        /** The top of the stack. */
634        int *top;
635    } indents;
636
637    /** The current indentation level. */
638    int indent;
639
640    /** May a simple key occur at the current position? */
641    int simple_key_allowed;
642
643    /** The stack of simple keys. */
644    struct {
645        /** The beginning of the stack. */
646        yaml_simple_key_t *start;
647        /** The end of the stack. */
648        yaml_simple_key_t *end;
649        /** The top of the stack. */
650        yaml_simple_key_t *top;
651    } simple_keys;
652
653    /**
654     * @}
655     */
656
657    /**
658     * @name Parser stuff
659     * @{
660     */
661
662    /** The parser states stack. */
663    struct {
664        /** The beginning of the stack. */
665        yaml_parser_state_t *start;
666        /** The end of the stack. */
667        yaml_parser_state_t *end;
668        /** The top of the stack. */
669        yaml_parser_state_t *top;
670    } states;
671
672    /** The current parser state. */
673    yaml_parser_state_t state;
674
675    /** The stack of marks. */
676    struct {
677        /** The beginning of the stack. */
678        yaml_mark_t *start;
679        /** The end of the stack. */
680        yaml_mark_t *end;
681        /** The top of the stack. */
682        yaml_mark_t *top;
683    } marks;
684
685    /** The list of TAG directives. */
686    struct {
687        /** The beginning of the list. */
688        yaml_tag_directive_t *start;
689        /** The end of the list. */
690        yaml_tag_directive_t *end;
691        /** The top of the list. */
692        yaml_tag_directive_t *top;
693    } tag_directives;
694
695    /**
696     * @}
697     */
698
699} yaml_parser_t;
700
701/**
702 * Initialize a parser.
703 *
704 * This function creates a new parser object.  An application is responsible
705 * for destroying the object using the @c yaml_parser_delete function.
706 *
707 * @param[in]   parser  An empty parser object.
708 *
709 * @returns #c 1 if the function succeeded, @c 0 on error.
710 */
711
712YAML_DECLARE(int)
713yaml_parser_initialize(yaml_parser_t *parser);
714
715/**
716 * Destroy a parser.
717 *
718 * @param[in]   parser  A parser object.
719 */
720
721YAML_DECLARE(void)
722yaml_parser_delete(yaml_parser_t *parser);
723
724/**
725 * Set a string input.
726 *
727 * Note that the @a input pointer must be valid while the @a parser object
728 * exists.  The application is responsible for destroing @a input after
729 * destroying the @a parser.
730 *
731 * @param[in]   parser  A parser object.
732 * @param[in]   input   A source data.
733 * @param[in]   size    The length of the source data in bytes.
734 */
735
736YAML_DECLARE(void)
737yaml_parser_set_input_string(yaml_parser_t *parser,
738        unsigned char *input, size_t size);
739
740
741/**
742 * Set a file input.
743 *
744 * @a file should be a file object open for reading.  The application is
745 * responsible for closing the @a file.
746 *
747 * @param[in]   parser  A parser object.
748 * @param[in]   file    An open file.
749 */
750
751YAML_DECLARE(void)
752yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
753
754/**
755 * Set a generic input handler.
756 *
757 * @param[in]   parser  A parser object.
758 * @param[in]   handler A read handler.
759 * @param[in]   data    Any application data for passing to the read handler.
760 */
761
762YAML_DECLARE(void)
763yaml_parser_set_input(yaml_parser_t *parser,
764        yaml_read_handler_t *handler, void *data);
765
766/**
767 * Set the source encoding.
768 *
769 * @param[in]   parser      A parser object.
770 * @param[in]   encoding    The source encoding.
771 */
772
773YAML_DECLARE(void)
774yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
775
776/**
777 * Scan the input stream and produce the next token.
778 *
779 * Call the function subsequently to produce a sequence of tokens corresponding
780 * to the input stream.  The initial token has the type
781 * @c YAML_STREAM_START_TOKEN while the ending token has the type
782 * @c YAML_STREAM_END_TOKEN.
783 *
784 * An application is responsible for freeing any buffers associated with the
785 * produced token object using the @c yaml_token_delete function.
786 *
787 * An application must not alternate the calls of @c yaml_parser_scan with the
788 * calls of @c yaml_parser_parse. Doing this will break the parser.
789 *
790 * @param[in]   parser      A parser object.
791 * @param[in]   token       An empty token object.
792 *
793 * @returns @c 1 if the function succeeded, @c 0 on error.
794 */
795
796YAML_DECLARE(int)
797yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
798
799/**
800 * Parse the input stream and produce the next parsing event.
801 *
802 * Call the function subsequently to produce a sequence of events corresponding
803 * to the input stream.  The initial event has the type
804 * @c YAML_STREAM_START_EVENT while the ending event has the type
805 * @c YAML_STREAM_END_EVENT.
806 *
807 * An application is responsible for freeing any buffers associated with the
808 * produced event object using the @c yaml_event_delete function.
809 *
810 * An application must not alternate the calls of @c yaml_parser_scan with the
811 * calls of @c yaml_parser_parse. Doing this will break the parser.
812 *
813 * @param[in]   parser      A parser object.
814 * @param[in]   event       An empty event object.
815 *
816 * @returns @c 1 if the function succeeded, @c 0 on error.
817 */
818
819YAML_DECLARE(int)
820yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
821
822/** @} */
823
824/*
825typedef struct {
826} yaml_emitter_t;
827
828YAML_DECLARE(int)
829yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
830
831YAML_DECLARE(int)
832yaml_emitter_emit_stream_start(yaml_emitter_t *emitter,
833        yaml_encoding_t encoding);
834
835*/
836
837#ifdef __cplusplus
838}
839#endif
840
841#endif /* #ifndef YAML_H */
842
Note: See TracBrowser for help on using the repository browser.