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

Revision 220, 35.9 KB checked in by xi, 8 years ago (diff)

Prepare the initial release.

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.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/** Line break types. */
105
106typedef enum {
107    YAML_ANY_BREAK,
108    YAML_CR_BREAK,
109    YAML_LN_BREAK,
110    YAML_CRLN_BREAK
111} yaml_break_t;
112
113/** Many bad things could happen with the parser and emitter. */
114typedef enum {
115    YAML_NO_ERROR,
116
117    YAML_MEMORY_ERROR,
118
119    YAML_READER_ERROR,
120    YAML_SCANNER_ERROR,
121    YAML_PARSER_ERROR,
122
123    YAML_WRITER_ERROR,
124    YAML_EMITTER_ERROR
125} yaml_error_type_t;
126
127/** The pointer position. */
128typedef struct {
129    /** The position index. */
130    size_t index;
131
132    /** The position line. */
133    size_t line;
134
135    /** The position column. */
136    size_t column;
137} yaml_mark_t;
138
139/** @} */
140
141/**
142 * @defgroup styles Node Styles
143 * @{
144 */
145
146/** Scalar styles. */
147typedef enum {
148    YAML_ANY_SCALAR_STYLE,
149
150    YAML_PLAIN_SCALAR_STYLE,
151
152    YAML_SINGLE_QUOTED_SCALAR_STYLE,
153    YAML_DOUBLE_QUOTED_SCALAR_STYLE,
154
155    YAML_LITERAL_SCALAR_STYLE,
156    YAML_FOLDED_SCALAR_STYLE
157} yaml_scalar_style_t;
158
159/** Sequence styles. */
160typedef enum {
161    YAML_ANY_SEQUENCE_STYLE,
162
163    YAML_BLOCK_SEQUENCE_STYLE,
164    YAML_FLOW_SEQUENCE_STYLE
165} yaml_sequence_style_t;
166
167/** Mapping styles. */
168typedef enum {
169    YAML_ANY_MAPPING_STYLE,
170
171    YAML_BLOCK_MAPPING_STYLE,
172    YAML_FLOW_MAPPING_STYLE
173/*    YAML_FLOW_SET_MAPPING_STYLE   */
174} yaml_mapping_style_t;
175
176/** @} */
177
178/**
179 * @defgroup tokens Tokens
180 * @{
181 */
182
183/** Token types. */
184typedef enum {
185    YAML_NO_TOKEN,
186
187    YAML_STREAM_START_TOKEN,
188    YAML_STREAM_END_TOKEN,
189
190    YAML_VERSION_DIRECTIVE_TOKEN,
191    YAML_TAG_DIRECTIVE_TOKEN,
192    YAML_DOCUMENT_START_TOKEN,
193    YAML_DOCUMENT_END_TOKEN,
194
195    YAML_BLOCK_SEQUENCE_START_TOKEN,
196    YAML_BLOCK_MAPPING_START_TOKEN,
197    YAML_BLOCK_END_TOKEN,
198
199    YAML_FLOW_SEQUENCE_START_TOKEN,
200    YAML_FLOW_SEQUENCE_END_TOKEN,
201    YAML_FLOW_MAPPING_START_TOKEN,
202    YAML_FLOW_MAPPING_END_TOKEN,
203
204    YAML_BLOCK_ENTRY_TOKEN,
205    YAML_FLOW_ENTRY_TOKEN,
206    YAML_KEY_TOKEN,
207    YAML_VALUE_TOKEN,
208
209    YAML_ALIAS_TOKEN,
210    YAML_ANCHOR_TOKEN,
211    YAML_TAG_TOKEN,
212    YAML_SCALAR_TOKEN
213} yaml_token_type_t;
214
215/** The token structure. */
216typedef struct {
217
218    /** The token type. */
219    yaml_token_type_t type;
220
221    /** The token data. */
222    union {
223
224        /** The stream start (for @c YAML_STREAM_START_TOKEN). */
225        struct {
226            /** The stream encoding. */
227            yaml_encoding_t encoding;
228        } stream_start;
229
230        /** The alias (for @c YAML_ALIAS_TOKEN). */
231        struct {
232            /** The alias value. */
233            yaml_char_t *value;
234        } alias;
235
236        /** The anchor (for @c YAML_ANCHOR_TOKEN). */
237        struct {
238            /** The anchor value. */
239            yaml_char_t *value;
240        } anchor;
241
242        /** The tag (for @c YAML_TAG_TOKEN). */
243        struct {
244            /** The tag handle. */
245            yaml_char_t *handle;
246            /** The tag suffix. */
247            yaml_char_t *suffix;
248        } tag;
249
250        /** The scalar value (for @c YAML_SCALAR_TOKEN). */
251        struct {
252            /** The scalar value. */
253            yaml_char_t *value;
254            /** The length of the scalar value. */
255            size_t length;
256            /** The scalar style. */
257            yaml_scalar_style_t style;
258        } scalar;
259
260        /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
261        struct {
262            /** The major version number. */
263            int major;
264            /** The minor version number. */
265            int minor;
266        } version_directive;
267
268        /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
269        struct {
270            /** The tag handle. */
271            yaml_char_t *handle;
272            /** The tag prefix. */
273            yaml_char_t *prefix;
274        } tag_directive;
275
276    } data;
277
278    /** The beginning of the token. */
279    yaml_mark_t start_mark;
280    /** The end of the token. */
281    yaml_mark_t end_mark;
282
283} yaml_token_t;
284
285/**
286 * Free any memory allocated for a token object.
287 *
288 * @param[in,out]   token   A token object.
289 */
290
291YAML_DECLARE(void)
292yaml_token_delete(yaml_token_t *token);
293
294/** @} */
295
296/**
297 * @defgroup events Events
298 * @{
299 */
300
301/** Event types. */
302typedef enum {
303    YAML_NO_EVENT,
304
305    YAML_STREAM_START_EVENT,
306    YAML_STREAM_END_EVENT,
307
308    YAML_DOCUMENT_START_EVENT,
309    YAML_DOCUMENT_END_EVENT,
310
311    YAML_ALIAS_EVENT,
312    YAML_SCALAR_EVENT,
313
314    YAML_SEQUENCE_START_EVENT,
315    YAML_SEQUENCE_END_EVENT,
316
317    YAML_MAPPING_START_EVENT,
318    YAML_MAPPING_END_EVENT
319} yaml_event_type_t;
320
321/** The event structure. */
322typedef struct {
323
324    /** The event type. */
325    yaml_event_type_t type;
326
327    /** The event data. */
328    union {
329       
330        /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
331        struct {
332            /** The document encoding. */
333            yaml_encoding_t encoding;
334        } stream_start;
335
336        /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
337        struct {
338            /** The version directive. */
339            yaml_version_directive_t *version_directive;
340
341            /** The list of tag directives. */
342            struct {
343                /** The beginning of the tag directives list. */
344                yaml_tag_directive_t *start;
345                /** The end of the tag directives list. */
346                yaml_tag_directive_t *end;
347            } tag_directives;
348
349            /** Is the document indicator implicit? */
350            int implicit;
351        } document_start;
352
353        /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
354        struct {
355            /** Is the document end indicator implicit? */
356            int implicit;
357        } document_end;
358
359        /** The alias parameters (for @c YAML_ALIAS_EVENT). */
360        struct {
361            /** The anchor. */
362            yaml_char_t *anchor;
363        } alias;
364
365        /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
366        struct {
367            /** The anchor. */
368            yaml_char_t *anchor;
369            /** The tag. */
370            yaml_char_t *tag;
371            /** The scalar value. */
372            yaml_char_t *value;
373            /** The length of the scalar value. */
374            size_t length;
375            /** Is the tag optional for the plain style? */
376            int plain_implicit;
377            /** Is the tag optional for any non-plain style? */
378            int quoted_implicit;
379            /** The scalar style. */
380            yaml_scalar_style_t style;
381        } scalar;
382
383        /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
384        struct {
385            /** The anchor. */
386            yaml_char_t *anchor;
387            /** The tag. */
388            yaml_char_t *tag;
389            /** Is the tag optional? */
390            int implicit;
391            /** The sequence style. */
392            yaml_sequence_style_t style;
393        } sequence_start;
394
395        /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
396        struct {
397            /** The anchor. */
398            yaml_char_t *anchor;
399            /** The tag. */
400            yaml_char_t *tag;
401            /** Is the tag optional? */
402            int implicit;
403            /** The mapping style. */
404            yaml_mapping_style_t style;
405        } mapping_start;
406
407    } data;
408
409    /** The beginning of the token. */
410    yaml_mark_t start_mark;
411    /** The end of the token. */
412    yaml_mark_t end_mark;
413
414} yaml_event_t;
415
416/**
417 * Create the STREAM-START event.
418 *
419 * @param[out]  event       An empty event object.
420 * @param[in]   encoding    The stream encoding.
421 *
422 * @returns @c 1 if the function succeeded, @c 0 on error.
423 */
424
425YAML_DECLARE(int)
426yaml_stream_start_event_initialize(yaml_event_t *event,
427        yaml_encoding_t encoding);
428
429/**
430 * Create the STREAM-END event.
431 *
432 * @param[out]  event       An empty event object.
433 *
434 * @returns @c 1 if the function succeeded, @c 0 on error.
435 */
436
437YAML_DECLARE(int)
438yaml_stream_end_event_initialize(yaml_event_t *event);
439
440/**
441 * Create the DOCUMENT-START event.
442 *
443 * The @a implicit argument is considered as a stylistic parameter and may be
444 * ignored by the emitter.
445 *
446 * @param[out]  event                   An empty event object.
447 * @param[in]   version_directive       The %YAML directive value or @c NULL.
448 * @param[in]   tag_directives_start    The beginning of the %TAG directives list.
449 * @param[in]   tag_directives_end      The end of the %TAG directives list.
450 * @param[in]   implicit                If the document start indicator is implicit.
451 *
452 * @returns @c 1 if the function succeeded, @c 0 on error.
453 */
454
455YAML_DECLARE(int)
456yaml_document_start_event_initialize(yaml_event_t *event,
457        yaml_version_directive_t *version_directive,
458        yaml_tag_directive_t *tag_directives_start,
459        yaml_tag_directive_t *tag_directives_end,
460        int implicit);
461
462/**
463 * Create the DOCUMENT-END event.
464 *
465 * The @a implicit argument is considered as a stylistic parameter and may be
466 * ignored by the emitter.
467 *
468 * @param[out]  event       An empty event object.
469 * @param[in]   implicit    If the document end indicator is implicit.
470 *
471 * @returns @c 1 if the function succeeded, @c 0 on error.
472 */
473
474YAML_DECLARE(int)
475yaml_document_end_event_initialize(yaml_event_t *event, int implicit);
476
477/**
478 * Create an ALIAS event.
479 *
480 * @param[out]  event       An empty event object.
481 * @param[in]   anchor      The anchor value.
482 *
483 * @returns @c 1 if the function succeeded, @c 0 on error.
484 */
485
486YAML_DECLARE(int)
487yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor);
488
489/**
490 * Create a SCALAR event.
491 *
492 * The @a style argument may be ignored by the emitter.
493 *
494 * Either the @a tag attribute or one of the @a plain_implicit and
495 * @a quoted_implicit flags must be set.
496 *
497 * @param[out]  event           An empty event object.
498 * @param[in]   anchor          The scalar anchor or @c NULL.
499 * @param[in]   tag             The scalar tag or @c NULL.
500 * @param[in]   value           The scalar value.
501 * @param[in]   length          The length of the scalar value.
502 * @param[in]   plain_implicit  If the tag may be omitted for the plain style.
503 * @param[in]   quoted_implicit If the tag may be omitted for any non-plain style.
504 * @param[in]   style           The scalar style.
505 *
506 * @returns @c 1 if the function succeeded, @c 0 on error.
507 */
508
509YAML_DECLARE(int)
510yaml_scalar_event_initialize(yaml_event_t *event,
511        yaml_char_t *anchor, yaml_char_t *tag,
512        yaml_char_t *value, int length,
513        int plain_implicit, int quoted_implicit,
514        yaml_scalar_style_t style);
515
516/**
517 * Create a SEQUENCE-START event.
518 *
519 * The @a style argument may be ignored by the emitter.
520 *
521 * Either the @a tag attribute or the @a implicit flag must be set.
522 *
523 * @param[out]  event       An empty event object.
524 * @param[in]   anchor      The sequence anchor or @c NULL.
525 * @param[in]   tag         The sequence tag or @c NULL.
526 * @param[in]   implicit    If the tag may be omitted.
527 * @param[in]   style       The sequence style.
528 *
529 * @returns @c 1 if the function succeeded, @c 0 on error.
530 */
531
532YAML_DECLARE(int)
533yaml_sequence_start_event_initialize(yaml_event_t *event,
534        yaml_char_t *anchor, yaml_char_t *tag, int implicit,
535        yaml_sequence_style_t style);
536
537/**
538 * Create a SEQUENCE-END event.
539 *
540 * @param[out]  event       An empty event object.
541 *
542 * @returns @c 1 if the function succeeded, @c 0 on error.
543 */
544
545YAML_DECLARE(int)
546yaml_sequence_end_event_initialize(yaml_event_t *event);
547
548/**
549 * Create a MAPPING-START event.
550 *
551 * The @a style argument may be ignored by the emitter.
552 *
553 * Either the @a tag attribute or the @a implicit flag must be set.
554 *
555 * @param[out]  event       An empty event object.
556 * @param[in]   anchor      The mapping anchor or @c NULL.
557 * @param[in]   tag         The mapping tag or @c NULL.
558 * @param[in]   implicit    If the tag may be omitted.
559 * @param[in]   style       The mapping style.
560 *
561 * @returns @c 1 if the function succeeded, @c 0 on error.
562 */
563
564YAML_DECLARE(int)
565yaml_mapping_start_event_initialize(yaml_event_t *event,
566        yaml_char_t *anchor, yaml_char_t *tag, int implicit,
567        yaml_mapping_style_t style);
568
569/**
570 * Create a MAPPING-END event.
571 *
572 * @param[out]  event       An empty event object.
573 *
574 * @returns @c 1 if the function succeeded, @c 0 on error.
575 */
576
577YAML_DECLARE(int)
578yaml_mapping_end_event_initialize(yaml_event_t *event);
579
580/**
581 * Free any memory allocated for an event object.
582 *
583 * @param[out]  event   An event object.
584 */
585
586YAML_DECLARE(void)
587yaml_event_delete(yaml_event_t *event);
588
589/** @} */
590
591/**
592 * @defgroup parser Parser Definitions
593 * @{
594 */
595
596/**
597 * The prototype of a read handler.
598 *
599 * The read handler is called when the parser needs to read more bytes from the
600 * source.  The handler should write not more than @a size bytes to the @a
601 * buffer.  The number of written bytes should be set to the @a length variable.
602 *
603 * @param[in,out]   data        A pointer to an application data specified by
604 *                              yaml_parser_set_input().
605 * @param[out]      buffer      The buffer to write the data from the source.
606 * @param[in]       size        The size of the buffer.
607 * @param[out]      size_read   The actual number of bytes read from the source.
608 *
609 * @returns On success, the handler should return @c 1.  If the handler failed,
610 * the returned value should be @c 0.  On EOF, the handler should set the
611 * @a size_read to @c 0 and return @c 1.
612 */
613
614typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
615        size_t *size_read);
616
617/**
618 * This structure holds information about a potential simple key.
619 */
620
621typedef struct {
622    /** Is a simple key possible? */
623    int possible;
624
625    /** Is a simple key required? */
626    int required;
627
628    /** The number of the token. */
629    size_t token_number;
630
631    /** The position mark. */
632    yaml_mark_t mark;
633} yaml_simple_key_t;
634
635/**
636 * The states of the parser.
637 */
638typedef enum {
639    YAML_PARSE_STREAM_START_STATE,
640    YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
641    YAML_PARSE_DOCUMENT_START_STATE,
642    YAML_PARSE_DOCUMENT_CONTENT_STATE,
643    YAML_PARSE_DOCUMENT_END_STATE,
644    YAML_PARSE_BLOCK_NODE_STATE,
645    YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
646    YAML_PARSE_FLOW_NODE_STATE,
647    YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
648    YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
649    YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
650    YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
651    YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
652    YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
653    YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
654    YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
655    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
656    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
657    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
658    YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
659    YAML_PARSE_FLOW_MAPPING_KEY_STATE,
660    YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
661    YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
662    YAML_PARSE_END_STATE
663} yaml_parser_state_t;
664
665/**
666 * The parser structure.
667 *
668 * All members are internal.  Manage the structure using the @c yaml_parser_
669 * family of functions.
670 */
671
672typedef struct {
673
674    /**
675     * @name Error handling
676     * @{
677     */
678
679    /** Error type. */
680    yaml_error_type_t error;
681    /** Error description. */
682    const char *problem;
683    /** The byte about which the problem occured. */
684    size_t problem_offset;
685    /** The problematic value (@c -1 is none). */
686    int problem_value;
687    /** The problem position. */
688    yaml_mark_t problem_mark;
689    /** The error context. */
690    const char *context;
691    /** The context position. */
692    yaml_mark_t context_mark;
693
694    /**
695     * @}
696     */
697
698    /**
699     * @name Reader stuff
700     * @{
701     */
702
703    /** Read handler. */
704    yaml_read_handler_t *read_handler;
705
706    /** A pointer for passing to the read handler. */
707    void *read_handler_data;
708
709    /** Standard (string or file) input data. */
710    union {
711        /** String input data. */
712        struct {
713            /** The string start pointer. */
714            unsigned char *start;
715            /** The string end pointer. */
716            unsigned char *end;
717            /** The string current position. */
718            unsigned char *current;
719        } string;
720
721        /** File input data. */
722        FILE *file;
723    } input;
724
725    /** EOF flag */
726    int eof;
727
728    /** The working buffer. */
729    struct {
730        /** The beginning of the buffer. */
731        yaml_char_t *start;
732        /** The end of the buffer. */
733        yaml_char_t *end;
734        /** The current position of the buffer. */
735        yaml_char_t *pointer;
736        /** The last filled position of the buffer. */
737        yaml_char_t *last;
738    } buffer;
739
740    /* The number of unread characters in the buffer. */
741    size_t unread;
742
743    /** The raw buffer. */
744    struct {
745        /** The beginning of the buffer. */
746        unsigned char *start;
747        /** The end of the buffer. */
748        unsigned char *end;
749        /** The current position of the buffer. */
750        unsigned char *pointer;
751        /** The last filled position of the buffer. */
752        unsigned char *last;
753    } raw_buffer;
754
755    /** The input encoding. */
756    yaml_encoding_t encoding;
757
758    /** The offset of the current position (in bytes). */
759    size_t offset;
760
761    /** The mark of the current position. */
762    yaml_mark_t mark;
763
764    /**
765     * @}
766     */
767
768    /**
769     * @name Scanner stuff
770     * @{
771     */
772
773    /** Have we started to scan the input stream? */
774    int stream_start_produced;
775
776    /** Have we reached the end of the input stream? */
777    int stream_end_produced;
778
779    /** The number of unclosed '[' and '{' indicators. */
780    int flow_level;
781
782    /** The tokens queue. */
783    struct {
784        /** The beginning of the tokens queue. */
785        yaml_token_t *start;
786        /** The end of the tokens queue. */
787        yaml_token_t *end;
788        /** The head of the tokens queue. */
789        yaml_token_t *head;
790        /** The tail of the tokens queue. */
791        yaml_token_t *tail;
792    } tokens;
793
794    /** The number of tokens fetched from the queue. */
795    size_t tokens_parsed;
796
797    /* Does the tokens queue contain a token ready for dequeueing. */
798    int token_available;
799
800    /** The indentation levels stack. */
801    struct {
802        /** The beginning of the stack. */
803        int *start;
804        /** The end of the stack. */
805        int *end;
806        /** The top of the stack. */
807        int *top;
808    } indents;
809
810    /** The current indentation level. */
811    int indent;
812
813    /** May a simple key occur at the current position? */
814    int simple_key_allowed;
815
816    /** The stack of simple keys. */
817    struct {
818        /** The beginning of the stack. */
819        yaml_simple_key_t *start;
820        /** The end of the stack. */
821        yaml_simple_key_t *end;
822        /** The top of the stack. */
823        yaml_simple_key_t *top;
824    } simple_keys;
825
826    /**
827     * @}
828     */
829
830    /**
831     * @name Parser stuff
832     * @{
833     */
834
835    /** The parser states stack. */
836    struct {
837        /** The beginning of the stack. */
838        yaml_parser_state_t *start;
839        /** The end of the stack. */
840        yaml_parser_state_t *end;
841        /** The top of the stack. */
842        yaml_parser_state_t *top;
843    } states;
844
845    /** The current parser state. */
846    yaml_parser_state_t state;
847
848    /** The stack of marks. */
849    struct {
850        /** The beginning of the stack. */
851        yaml_mark_t *start;
852        /** The end of the stack. */
853        yaml_mark_t *end;
854        /** The top of the stack. */
855        yaml_mark_t *top;
856    } marks;
857
858    /** The list of TAG directives. */
859    struct {
860        /** The beginning of the list. */
861        yaml_tag_directive_t *start;
862        /** The end of the list. */
863        yaml_tag_directive_t *end;
864        /** The top of the list. */
865        yaml_tag_directive_t *top;
866    } tag_directives;
867
868    /**
869     * @}
870     */
871
872} yaml_parser_t;
873
874/**
875 * Initialize a parser.
876 *
877 * This function creates a new parser object.  An application is responsible
878 * for destroying the object using the yaml_parser_delete() function.
879 *
880 * @param[out]  parser  An empty parser object.
881 *
882 * @returns @c 1 if the function succeeded, @c 0 on error.
883 */
884
885YAML_DECLARE(int)
886yaml_parser_initialize(yaml_parser_t *parser);
887
888/**
889 * Destroy a parser.
890 *
891 * @param[in,out]   parser  A parser object.
892 */
893
894YAML_DECLARE(void)
895yaml_parser_delete(yaml_parser_t *parser);
896
897/**
898 * Set a string input.
899 *
900 * Note that the @a input pointer must be valid while the @a parser object
901 * exists.  The application is responsible for destroing @a input after
902 * destroying the @a parser.
903 *
904 * @param[in,out]   parser  A parser object.
905 * @param[in]       input   A source data.
906 * @param[in]       size    The length of the source data in bytes.
907 */
908
909YAML_DECLARE(void)
910yaml_parser_set_input_string(yaml_parser_t *parser,
911        unsigned char *input, size_t size);
912
913/**
914 * Set a file input.
915 *
916 * @a file should be a file object open for reading.  The application is
917 * responsible for closing the @a file.
918 *
919 * @param[in,out]   parser  A parser object.
920 * @param[in]       file    An open file.
921 */
922
923YAML_DECLARE(void)
924yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
925
926/**
927 * Set a generic input handler.
928 *
929 * @param[in,out]   parser  A parser object.
930 * @param[in]       handler A read handler.
931 * @param[in]       data    Any application data for passing to the read
932 *                          handler.
933 */
934
935YAML_DECLARE(void)
936yaml_parser_set_input(yaml_parser_t *parser,
937        yaml_read_handler_t *handler, void *data);
938
939/**
940 * Set the source encoding.
941 *
942 * @param[in,out]   parser      A parser object.
943 * @param[in]       encoding    The source encoding.
944 */
945
946YAML_DECLARE(void)
947yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
948
949/**
950 * Scan the input stream and produce the next token.
951 *
952 * Call the function subsequently to produce a sequence of tokens corresponding
953 * to the input stream.  The initial token has the type
954 * @c YAML_STREAM_START_TOKEN while the ending token has the type
955 * @c YAML_STREAM_END_TOKEN.
956 *
957 * An application is responsible for freeing any buffers associated with the
958 * produced token object using the @c yaml_token_delete function.
959 *
960 * An application must not alternate the calls of yaml_parser_scan() with the
961 * calls of yaml_parser_parse(). Doing this will break the parser.
962 *
963 * @param[in,out]   parser      A parser object.
964 * @param[out]      token       An empty token object.
965 *
966 * @returns @c 1 if the function succeeded, @c 0 on error.
967 */
968
969YAML_DECLARE(int)
970yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
971
972/**
973 * Parse the input stream and produce the next parsing event.
974 *
975 * Call the function subsequently to produce a sequence of events corresponding
976 * to the input stream.  The initial event has the type
977 * @c YAML_STREAM_START_EVENT while the ending event has the type
978 * @c YAML_STREAM_END_EVENT.
979 *
980 * An application is responsible for freeing any buffers associated with the
981 * produced event object using the yaml_event_delete() function.
982 *
983 * An application must not alternate the calls of yaml_parser_scan() with the
984 * calls of yaml_parser_parse(). Doing this will break the parser.
985 *
986 * @param[in,out]   parser      A parser object.
987 * @param[out]      event       An empty event object.
988 *
989 * @returns @c 1 if the function succeeded, @c 0 on error.
990 */
991
992YAML_DECLARE(int)
993yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
994
995/** @} */
996
997/**
998 * @defgroup emitter Emitter Definitions
999 * @{
1000 */
1001
1002/**
1003 * The prototype of a write handler.
1004 *
1005 * The write handler is called when the emitter needs to flush the accumulated
1006 * characters to the output.  The handler should write @a size bytes of the
1007 * @a buffer to the output.
1008 *
1009 * @param[in,out]   data        A pointer to an application data specified by
1010 *                              yaml_emitter_set_output().
1011 * @param[in]       buffer      The buffer with bytes to be written.
1012 * @param[in]       size        The size of the buffer.
1013 *
1014 * @returns On success, the handler should return @c 1.  If the handler failed,
1015 * the returned value should be @c 0.
1016 */
1017
1018typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size);
1019
1020/** The emitter states. */
1021typedef enum {
1022    YAML_EMIT_STREAM_START_STATE,
1023    YAML_EMIT_FIRST_DOCUMENT_START_STATE,
1024    YAML_EMIT_DOCUMENT_START_STATE,
1025    YAML_EMIT_DOCUMENT_CONTENT_STATE,
1026    YAML_EMIT_DOCUMENT_END_STATE,
1027    YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
1028    YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
1029    YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
1030    YAML_EMIT_FLOW_MAPPING_KEY_STATE,
1031    YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
1032    YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
1033    YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
1034    YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
1035    YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
1036    YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
1037    YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
1038    YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
1039    YAML_EMIT_END_STATE
1040} yaml_emitter_state_t;
1041
1042/**
1043 * The emitter structure.
1044 *
1045 * All members are internal.  Manage the structure using the @c yaml_emitter_
1046 * family of functions.
1047 */
1048
1049typedef struct {
1050
1051    /**
1052     * @name Error handling
1053     * @{
1054     */
1055
1056    /** Error type. */
1057    yaml_error_type_t error;
1058    /** Error description. */
1059    const char *problem;
1060
1061    /**
1062     * @}
1063     */
1064
1065    /**
1066     * @name Writer stuff
1067     * @{
1068     */
1069
1070    /** Write handler. */
1071    yaml_write_handler_t *write_handler;
1072
1073    /** A pointer for passing to the white handler. */
1074    void *write_handler_data;
1075
1076    /** Standard (string or file) output data. */
1077    union {
1078        /** String output data. */
1079        struct {
1080            /** The buffer pointer. */
1081            unsigned char *buffer;
1082            /** The buffer size. */
1083            size_t size;
1084            /** The number of written bytes. */
1085            size_t *size_written;
1086        } string;
1087
1088        /** File output data. */
1089        FILE *file;
1090    } output;
1091
1092    /** The working buffer. */
1093    struct {
1094        /** The beginning of the buffer. */
1095        yaml_char_t *start;
1096        /** The end of the buffer. */
1097        yaml_char_t *end;
1098        /** The current position of the buffer. */
1099        yaml_char_t *pointer;
1100        /** The last filled position of the buffer. */
1101        yaml_char_t *last;
1102    } buffer;
1103
1104    /** The raw buffer. */
1105    struct {
1106        /** The beginning of the buffer. */
1107        unsigned char *start;
1108        /** The end of the buffer. */
1109        unsigned char *end;
1110        /** The current position of the buffer. */
1111        unsigned char *pointer;
1112        /** The last filled position of the buffer. */
1113        unsigned char *last;
1114    } raw_buffer;
1115
1116    /** The stream encoding. */
1117    yaml_encoding_t encoding;
1118
1119    /**
1120     * @}
1121     */
1122
1123    /**
1124     * @name Emitter stuff
1125     * @{
1126     */
1127
1128    /** If the output is in the canonical style? */
1129    int canonical;
1130    /** The number of indentation spaces. */
1131    int best_indent;
1132    /** The preferred width of the output lines. */
1133    int best_width;
1134    /** Allow unescaped non-ASCII characters? */
1135    int unicode;
1136    /** The preferred line break. */
1137    yaml_break_t line_break;
1138
1139    /** The stack of states. */
1140    struct {
1141        /** The beginning of the stack. */
1142        yaml_emitter_state_t *start;
1143        /** The end of the stack. */
1144        yaml_emitter_state_t *end;
1145        /** The top of the stack. */
1146        yaml_emitter_state_t *top;
1147    } states;
1148
1149    /** The current emitter state. */
1150    yaml_emitter_state_t state;
1151
1152    /** The event queue. */
1153    struct {
1154        /** The beginning of the event queue. */
1155        yaml_event_t *start;
1156        /** The end of the event queue. */
1157        yaml_event_t *end;
1158        /** The head of the event queue. */
1159        yaml_event_t *head;
1160        /** The tail of the event queue. */
1161        yaml_event_t *tail;
1162    } events;
1163
1164    /** The stack of indentation levels. */
1165    struct {
1166        /** The beginning of the stack. */
1167        int *start;
1168        /** The end of the stack. */
1169        int *end;
1170        /** The top of the stack. */
1171        int *top;
1172    } indents;
1173
1174    /** The list of tag directives. */
1175    struct {
1176        /** The beginning of the list. */
1177        yaml_tag_directive_t *start;
1178        /** The end of the list. */
1179        yaml_tag_directive_t *end;
1180        /** The top of the list. */
1181        yaml_tag_directive_t *top;
1182    } tag_directives;
1183
1184    /** The current indentation level. */
1185    int indent;
1186
1187    /** The current flow level. */
1188    int flow_level;
1189
1190    /** Is it the document root context? */
1191    int root_context;
1192    /** Is it a sequence context? */
1193    int sequence_context;
1194    /** Is it a mapping context? */
1195    int mapping_context;
1196    /** Is it a simple mapping key context? */
1197    int simple_key_context;
1198
1199    /** The current line. */
1200    int line;
1201    /** The current column. */
1202    int column;
1203    /** If the last character was a whitespace? */
1204    int whitespace;
1205    /** If the last character was an indentation character (' ', '-', '?', ':')? */
1206    int indention;
1207
1208    /** Anchor analysis. */
1209    struct {
1210        /** The anchor value. */
1211        yaml_char_t *anchor;
1212        /** The anchor length. */
1213        size_t anchor_length;
1214        /** Is it an alias? */
1215        int alias;
1216    } anchor_data;
1217
1218    /** Tag analysis. */
1219    struct {
1220        /** The tag handle. */
1221        yaml_char_t *handle;
1222        /** The tag handle length. */
1223        size_t handle_length;
1224        /** The tag suffix. */
1225        yaml_char_t *suffix;
1226        /** The tag suffix length. */
1227        size_t suffix_length;
1228    } tag_data;
1229
1230    /** Scalar analysis. */
1231    struct {
1232        /** The scalar value. */
1233        yaml_char_t *value;
1234        /** The scalar length. */
1235        size_t length;
1236        /** Does the scalar contain line breaks? */
1237        int multiline;
1238        /** Can the scalar be expessed in the flow plain style? */
1239        int flow_plain_allowed;
1240        /** Can the scalar be expressed in the block plain style? */
1241        int block_plain_allowed;
1242        /** Can the scalar be expressed in the single quoted style? */
1243        int single_quoted_allowed;
1244        /** Can the scalar be expressed in the literal or folded styles? */
1245        int block_allowed;
1246        /** The output style. */
1247        yaml_scalar_style_t style;
1248    } scalar_data;
1249
1250    /**
1251     * @}
1252     */
1253
1254} yaml_emitter_t;
1255
1256/**
1257 * Initialize an emitter.
1258 *
1259 * This function creates a new emitter object.  An application is responsible
1260 * for destroying the object using the yaml_emitter_delete() function.
1261 *
1262 * @param[out]      emitter     An empty parser object.
1263 *
1264 * @returns @c 1 if the function succeeded, @c 0 on error.
1265 */
1266
1267YAML_DECLARE(int)
1268yaml_emitter_initialize(yaml_emitter_t *emitter);
1269
1270/**
1271 * Destroy an emitter.
1272 *
1273 * @param[in,out]   emitter     An emitter object.
1274 */
1275
1276YAML_DECLARE(void)
1277yaml_emitter_delete(yaml_emitter_t *emitter);
1278
1279/**
1280 * Set a string output.
1281 *
1282 * The emitter will write the output characters to the @a output buffer of the
1283 * size @a size.  The emitter will set @a size_written to the number of written
1284 * bytes.  If the buffer is smaller than required, the emitter produces the
1285 * YAML_WRITE_ERROR error.
1286 *
1287 * @param[in,out]   emitter         An emitter object.
1288 * @param[in]       output          An output buffer.
1289 * @param[in]       size            The buffer size.
1290 * @param[in]       size_written    The pointer to save the number of written
1291 *                                  bytes.
1292 */
1293
1294YAML_DECLARE(void)
1295yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1296        unsigned char *output, size_t size, size_t *size_written);
1297
1298/**
1299 * Set a file output.
1300 *
1301 * @a file should be a file object open for writing.  The application is
1302 * responsible for closing the @a file.
1303 *
1304 * @param[in,out]   emitter     An emitter object.
1305 * @param[in]       file        An open file.
1306 */
1307
1308YAML_DECLARE(void)
1309yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1310
1311/**
1312 * Set a generic output handler.
1313 *
1314 * @param[in,out]   emitter     An emitter object.
1315 * @param[in]       handler     A write handler.
1316 * @param[in]       data        Any application data for passing to the write
1317 *                              handler.
1318 */
1319
1320YAML_DECLARE(void)
1321yaml_emitter_set_output(yaml_emitter_t *emitter,
1322        yaml_write_handler_t *handler, void *data);
1323
1324/**
1325 * Set the output encoding.
1326 *
1327 * @param[in,out]   emitter     An emitter object.
1328 * @param[in]       encoding    The output encoding.
1329 */
1330
1331YAML_DECLARE(void)
1332yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1333
1334/**
1335 * Set if the output should be in the "canonical" format as in the YAML
1336 * specification.
1337 *
1338 * @param[in,out]   emitter     An emitter object.
1339 * @param[in]       canonical   If the output is canonical.
1340 */
1341
1342YAML_DECLARE(void)
1343yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1344
1345/**
1346 * Set the intendation increment.
1347 *
1348 * @param[in,out]   emitter     An emitter object.
1349 * @param[in]       indent      The indentation increment (1 < . < 10).
1350 */
1351
1352YAML_DECLARE(void)
1353yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1354
1355/**
1356 * Set the preferred line width. @c -1 means unlimited.
1357 *
1358 * @param[in,out]   emitter     An emitter object.
1359 * @param[in]       width       The preferred line width.
1360 */
1361
1362YAML_DECLARE(void)
1363yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1364
1365/**
1366 * Set if unescaped non-ASCII characters are allowed.
1367 *
1368 * @param[in,out]   emitter     An emitter object.
1369 * @param[in]       unicode     If unescaped Unicode characters are allowed.
1370 */
1371
1372YAML_DECLARE(void)
1373yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1374
1375/**
1376 * Set the preferred line break.
1377 *
1378 * @param[in,out]   emitter     An emitter object.
1379 * @param[in]       line_break  The preferred line break.
1380 */
1381
1382YAML_DECLARE(void)
1383yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1384
1385/**
1386 * Emit an event.
1387 *
1388 * The event object may be generated using the yaml_parser_parse() function.
1389 * The emitter takes the responsibility for the event object and destroys its
1390 * content after it is emitted. The event object is destroyed even if the
1391 * function fails.
1392 *
1393 * @param[in,out]   emitter     An emitter object.
1394 * @param[in,out]   event       An event object.
1395 *
1396 * @returns @c 1 if the function succeeded, @c 0 on error.
1397 */
1398
1399YAML_DECLARE(int)
1400yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
1401
1402/**
1403 * Flush the accumulated characters to the output.
1404 *
1405 * @param[in,out]   emitter     An emitter object.
1406 *
1407 * @returns @c 1 if the function succeeded, @c 0 on error.
1408 */
1409
1410YAML_DECLARE(int)
1411yaml_emitter_flush(yaml_emitter_t *emitter);
1412
1413/** @} */
1414
1415#ifdef __cplusplus
1416}
1417#endif
1418
1419#endif /* #ifndef YAML_H */
1420
Note: See TracBrowser for help on using the repository browser.