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

Revision 213, 34.3 KB checked in by xi, 8 years ago (diff)

Implement Emitter state machine.

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