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

Revision 219, 35.6 KB checked in by xi, 8 years ago (diff)

Add two examples and prepare the build system for distribution.

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/** 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]   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[in]   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[in]   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[in]   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[in]   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[in]   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[in]   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[in]   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[in]   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[in]   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[in]   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[in]   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]   data        A pointer to an application data specified by
604 *                          @c yaml_parser_set_read_handler.
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 @c yaml_parser_delete function.
879 *
880 * @param[in]   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]   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]   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]   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]   parser  A parser object.
930 * @param[in]   handler A read handler.
931 * @param[in]   data    Any application data for passing to the read handler.
932 */
933
934YAML_DECLARE(void)
935yaml_parser_set_input(yaml_parser_t *parser,
936        yaml_read_handler_t *handler, void *data);
937
938/**
939 * Set the source encoding.
940 *
941 * @param[in]   parser      A parser object.
942 * @param[in]   encoding    The source encoding.
943 */
944
945YAML_DECLARE(void)
946yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
947
948/**
949 * Scan the input stream and produce the next token.
950 *
951 * Call the function subsequently to produce a sequence of tokens corresponding
952 * to the input stream.  The initial token has the type
953 * @c YAML_STREAM_START_TOKEN while the ending token has the type
954 * @c YAML_STREAM_END_TOKEN.
955 *
956 * An application is responsible for freeing any buffers associated with the
957 * produced token object using the @c yaml_token_delete function.
958 *
959 * An application must not alternate the calls of @c yaml_parser_scan with the
960 * calls of @c yaml_parser_parse. Doing this will break the parser.
961 *
962 * @param[in]   parser      A parser object.
963 * @param[in]   token       An empty token object.
964 *
965 * @returns @c 1 if the function succeeded, @c 0 on error.
966 */
967
968YAML_DECLARE(int)
969yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
970
971/**
972 * Parse the input stream and produce the next parsing event.
973 *
974 * Call the function subsequently to produce a sequence of events corresponding
975 * to the input stream.  The initial event has the type
976 * @c YAML_STREAM_START_EVENT while the ending event has the type
977 * @c YAML_STREAM_END_EVENT.
978 *
979 * An application is responsible for freeing any buffers associated with the
980 * produced event object using the @c yaml_event_delete function.
981 *
982 * An application must not alternate the calls of @c yaml_parser_scan with the
983 * calls of @c yaml_parser_parse. Doing this will break the parser.
984 *
985 * @param[in]   parser      A parser object.
986 * @param[in]   event       An empty event object.
987 *
988 * @returns @c 1 if the function succeeded, @c 0 on error.
989 */
990
991YAML_DECLARE(int)
992yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
993
994/** @} */
995
996/**
997 * @defgroup emitter Emitter Definitions
998 * @{
999 */
1000
1001/**
1002 * The prototype of a write handler.
1003 *
1004 * The write handler is called when the emitter needs to flush the accumulated
1005 * characters to the output.  The handler should write @a size bytes of the
1006 * @a buffer to the output.
1007 *
1008 * @param[in]   data        A pointer to an application data specified by
1009 *                          @c yaml_emitter_set_write_handler.
1010 * @param[out]  buffer      The buffer with bytes to be written.
1011 * @param[in]   size        The size of the buffer.
1012 *
1013 * @returns On success, the handler should return @c 1.  If the handler failed,
1014 * the returned value should be @c 0.
1015 */
1016
1017typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size);
1018
1019/** The emitter states. */
1020typedef enum {
1021    YAML_EMIT_STREAM_START_STATE,
1022    YAML_EMIT_FIRST_DOCUMENT_START_STATE,
1023    YAML_EMIT_DOCUMENT_START_STATE,
1024    YAML_EMIT_DOCUMENT_CONTENT_STATE,
1025    YAML_EMIT_DOCUMENT_END_STATE,
1026    YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
1027    YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
1028    YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
1029    YAML_EMIT_FLOW_MAPPING_KEY_STATE,
1030    YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
1031    YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
1032    YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
1033    YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
1034    YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
1035    YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
1036    YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
1037    YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
1038    YAML_EMIT_END_STATE
1039} yaml_emitter_state_t;
1040
1041/**
1042 * The emitter structure.
1043 *
1044 * All members are internal.  Manage the structure using the @c yaml_emitter_
1045 * family of functions.
1046 */
1047
1048typedef struct {
1049
1050    /**
1051     * @name Error handling
1052     * @{
1053     */
1054
1055    /** Error type. */
1056    yaml_error_type_t error;
1057    /** Error description. */
1058    const char *problem;
1059
1060    /**
1061     * @}
1062     */
1063
1064    /**
1065     * @name Writer stuff
1066     * @{
1067     */
1068
1069    /** Write handler. */
1070    yaml_write_handler_t *write_handler;
1071
1072    /** A pointer for passing to the white handler. */
1073    void *write_handler_data;
1074
1075    /** Standard (string or file) output data. */
1076    union {
1077        /** String output data. */
1078        struct {
1079            /** The buffer pointer. */
1080            unsigned char *buffer;
1081            /** The buffer size. */
1082            size_t size;
1083            /** The number of written bytes. */
1084            size_t *size_written;
1085        } string;
1086
1087        /** File output data. */
1088        FILE *file;
1089    } output;
1090
1091    /** The working buffer. */
1092    struct {
1093        /** The beginning of the buffer. */
1094        yaml_char_t *start;
1095        /** The end of the buffer. */
1096        yaml_char_t *end;
1097        /** The current position of the buffer. */
1098        yaml_char_t *pointer;
1099        /** The last filled position of the buffer. */
1100        yaml_char_t *last;
1101    } buffer;
1102
1103    /** The raw buffer. */
1104    struct {
1105        /** The beginning of the buffer. */
1106        unsigned char *start;
1107        /** The end of the buffer. */
1108        unsigned char *end;
1109        /** The current position of the buffer. */
1110        unsigned char *pointer;
1111        /** The last filled position of the buffer. */
1112        unsigned char *last;
1113    } raw_buffer;
1114
1115    /** The stream encoding. */
1116    yaml_encoding_t encoding;
1117
1118    /**
1119     * @}
1120     */
1121
1122    /**
1123     * @name Emitter stuff
1124     * @{
1125     */
1126
1127    /** If the output is in the canonical style? */
1128    int canonical;
1129    /** The number of indentation spaces. */
1130    int best_indent;
1131    /** The preferred width of the output lines. */
1132    int best_width;
1133    /** Allow unescaped non-ASCII characters? */
1134    int unicode;
1135    /** The preferred line break. */
1136    yaml_break_t line_break;
1137
1138    /** The stack of states. */
1139    struct {
1140        /** The beginning of the stack. */
1141        yaml_emitter_state_t *start;
1142        /** The end of the stack. */
1143        yaml_emitter_state_t *end;
1144        /** The top of the stack. */
1145        yaml_emitter_state_t *top;
1146    } states;
1147
1148    /** The current emitter state. */
1149    yaml_emitter_state_t state;
1150
1151    /** The event queue. */
1152    struct {
1153        /** The beginning of the event queue. */
1154        yaml_event_t *start;
1155        /** The end of the event queue. */
1156        yaml_event_t *end;
1157        /** The head of the event queue. */
1158        yaml_event_t *head;
1159        /** The tail of the event queue. */
1160        yaml_event_t *tail;
1161    } events;
1162
1163    /** The stack of indentation levels. */
1164    struct {
1165        /** The beginning of the stack. */
1166        int *start;
1167        /** The end of the stack. */
1168        int *end;
1169        /** The top of the stack. */
1170        int *top;
1171    } indents;
1172
1173    /** The list of tag directives. */
1174    struct {
1175        /** The beginning of the list. */
1176        yaml_tag_directive_t *start;
1177        /** The end of the list. */
1178        yaml_tag_directive_t *end;
1179        /** The top of the list. */
1180        yaml_tag_directive_t *top;
1181    } tag_directives;
1182
1183    /** The current indentation level. */
1184    int indent;
1185
1186    /** The current flow level. */
1187    int flow_level;
1188
1189    /** Is it the document root context? */
1190    int root_context;
1191    /** Is it a sequence context? */
1192    int sequence_context;
1193    /** Is it a mapping context? */
1194    int mapping_context;
1195    /** Is it a simple mapping key context? */
1196    int simple_key_context;
1197
1198    /** The current line. */
1199    int line;
1200    /** The current column. */
1201    int column;
1202    /** If the last character was a whitespace? */
1203    int whitespace;
1204    /** If the last character was an indentation character (' ', '-', '?', ':')? */
1205    int indention;
1206
1207    /** Anchor analysis. */
1208    struct {
1209        /** The anchor value. */
1210        yaml_char_t *anchor;
1211        /** The anchor length. */
1212        size_t anchor_length;
1213        /** Is it an alias? */
1214        int alias;
1215    } anchor_data;
1216
1217    /** Tag analysis. */
1218    struct {
1219        /** The tag handle. */
1220        yaml_char_t *handle;
1221        /** The tag handle length. */
1222        size_t handle_length;
1223        /** The tag suffix. */
1224        yaml_char_t *suffix;
1225        /** The tag suffix length. */
1226        size_t suffix_length;
1227    } tag_data;
1228
1229    /** Scalar analysis. */
1230    struct {
1231        /** The scalar value. */
1232        yaml_char_t *value;
1233        /** The scalar length. */
1234        size_t length;
1235        /** Does the scalar contain line breaks? */
1236        int multiline;
1237        /** Can the scalar be expessed in the flow plain style? */
1238        int flow_plain_allowed;
1239        /** Can the scalar be expressed in the block plain style? */
1240        int block_plain_allowed;
1241        /** Can the scalar be expressed in the single quoted style? */
1242        int single_quoted_allowed;
1243        /** Can the scalar be expressed in the literal or folded styles? */
1244        int block_allowed;
1245        /** The output style. */
1246        yaml_scalar_style_t style;
1247    } scalar_data;
1248
1249    /**
1250     * @}
1251     */
1252
1253} yaml_emitter_t;
1254
1255/**
1256 * Initialize an emitter.
1257 *
1258 * This function creates a new emitter object.  An application is responsible
1259 * for destroying the object using the @c yaml_emitter_delete function.
1260 *
1261 * @param[in]   emitter An empty parser object.
1262 *
1263 * @returns @c 1 if the function succeeded, @c 0 on error.
1264 */
1265
1266YAML_DECLARE(int)
1267yaml_emitter_initialize(yaml_emitter_t *emitter);
1268
1269/**
1270 * Destroy an emitter.
1271 *
1272 * @param[in]   emitter An emitter object.
1273 */
1274
1275YAML_DECLARE(void)
1276yaml_emitter_delete(yaml_emitter_t *emitter);
1277
1278/**
1279 * Set a string output.
1280 *
1281 * The emitter will write the output characters to the @a output buffer of the
1282 * size @a size.  The emitter will set @a size_written to the number of written
1283 * bytes.  If the buffer is smaller than required, the emitter produces the
1284 * YAML_WRITE_ERROR error.
1285 *
1286 * @param[in]   emitter         An emitter object.
1287 * @param[in]   output          An output buffer.
1288 * @param[in]   size            The buffer size.
1289 * @param[in]   size_written    The pointer to save the number of written bytes.
1290 */
1291
1292YAML_DECLARE(void)
1293yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1294        unsigned char *output, size_t size, size_t *size_written);
1295
1296/**
1297 * Set a file output.
1298 *
1299 * @a file should be a file object open for writing.  The application is
1300 * responsible for closing the @a file.
1301 *
1302 * @param[in]   emitter An emitter object.
1303 * @param[in]   file    An open file.
1304 */
1305
1306YAML_DECLARE(void)
1307yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1308
1309/**
1310 * Set a generic output handler.
1311 *
1312 * @param[in]   emitter An emitter object.
1313 * @param[in]   handler A write handler.
1314 * @param[in]   data    Any application data for passing to the write handler.
1315 */
1316
1317YAML_DECLARE(void)
1318yaml_emitter_set_output(yaml_emitter_t *emitter,
1319        yaml_write_handler_t *handler, void *data);
1320
1321/**
1322 * Set the output encoding.
1323 *
1324 * @param[in]   emitter     An emitter object.
1325 * @param[in]   encoding    The output encoding.
1326 */
1327
1328YAML_DECLARE(void)
1329yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1330
1331/**
1332 * Set if the output should be in the "canonical" format as in the YAML
1333 * specification.
1334 *
1335 * @param[in]   emitter     An emitter object.
1336 * @param[in]   canonical   If the output is canonical.
1337 */
1338
1339YAML_DECLARE(void)
1340yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1341
1342/**
1343 * Set the intendation increment.
1344 *
1345 * @param[in]   emitter     An emitter object.
1346 * @param[in]   indent      The indentation increment (1 < . < 10).
1347 */
1348
1349YAML_DECLARE(void)
1350yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1351
1352/**
1353 * Set the preferred line width. @c -1 means unlimited.
1354 *
1355 * @param[in]   emitter     An emitter object.
1356 * @param[in]   width       The preferred line width.
1357 */
1358
1359YAML_DECLARE(void)
1360yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1361
1362/**
1363 * Set if unescaped non-ASCII characters are allowed.
1364 *
1365 * @param[in]   emitter     An emitter object.
1366 * @param[in]   unicode     If unescaped Unicode characters are allowed.
1367 */
1368
1369YAML_DECLARE(void)
1370yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1371
1372/**
1373 * Set the preferred line break.
1374 *
1375 * @param[in]   emitter     An emitter object.
1376 * @param[in]   line_break  The preferred line break.
1377 */
1378
1379YAML_DECLARE(void)
1380yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1381
1382/**
1383 * Emit an event.
1384 *
1385 * The event object may be generated using the @c yaml_parser_parse function.
1386 * The emitter takes the responsibility for the event object and destroys its
1387 * content after it is emitted. The event object is destroyed even if the
1388 * function fails.
1389 *
1390 * @param[in]   emitter     An emitter object.
1391 * @param[in]   event       An event object.
1392 *
1393 * @returns @c 1 if the function succeeded, @c 0 on error.
1394 */
1395
1396YAML_DECLARE(int)
1397yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
1398
1399/**
1400 * Flush the accumulated characters to the output.
1401 *
1402 * @param[in]   emitter     An emitter object.
1403 *
1404 * @returns @c 1 if the function succeeded, @c 0 on error.
1405 */
1406
1407YAML_DECLARE(int)
1408yaml_emitter_flush(yaml_emitter_t *emitter);
1409
1410/** @} */
1411
1412#ifdef __cplusplus
1413}
1414#endif
1415
1416#endif /* #ifndef YAML_H */
1417
Note: See TracBrowser for help on using the repository browser.