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

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

Prepare the initial release.

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
[220]7 * #include <yaml.h>
[172]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 *
[220]288 * @param[in,out]   token   A token object.
[183]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 *
[220]419 * @param[out]  event       An empty event object.
[219]420 * @param[in]   encoding    The stream encoding.
[213]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 *
[220]432 * @param[out]  event       An empty event object.
[213]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 *
[220]446 * @param[out]  event                   An empty event object.
[213]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 *
[220]468 * @param[out]  event       An empty event object.
[213]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 *
[220]480 * @param[out]  event       An empty event object.
[213]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 *
[220]497 * @param[out]  event           An empty event object.
[213]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,
[219]512        yaml_char_t *value, int length,
[213]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 *
[220]523 * @param[out]  event       An empty event object.
[213]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 *
[220]540 * @param[out]  event       An empty event object.
[213]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 *
[220]555 * @param[out]  event       An empty event object.
[213]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 *
[220]572 * @param[out]  event       An empty event object.
[213]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/**
[208]581 * Free any memory allocated for an event object.
[199]582 *
[220]583 * @param[out]  event   An event object.
[199]584 */
585
586YAML_DECLARE(void)
587yaml_event_delete(yaml_event_t *event);
588
589/** @} */
590
591/**
[178]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 *
[220]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.
[178]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
[211]611 * @a size_read to @c 0 and return @c 1.
[178]612 */
[180]613
614typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
[179]615        size_t *size_read);
[178]616
617/**
[184]618 * This structure holds information about a potential simple key.
619 */
620
621typedef struct {
[208]622    /** Is a simple key possible? */
623    int possible;
624
[184]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/**
[201]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,
[208]661    YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
662    YAML_PARSE_END_STATE
[201]663} yaml_parser_state_t;
664
665/**
[178]666 * The parser structure.
667 *
668 * All members are internal.  Manage the structure using the @c yaml_parser_
669 * family of functions.
670 */
671
[162]672typedef struct {
[178]673
674    /**
[179]675     * @name Error handling
676     * @{
677     */
678
[181]679    /** Error type. */
[180]680    yaml_error_type_t error;
[181]681    /** Error description. */
682    const char *problem;
683    /** The byte about which the problem occured. */
684    size_t problem_offset;
[182]685    /** The problematic value (@c -1 is none). */
686    int problem_value;
[185]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
[179]694    /**
695     * @}
696     */
697
698    /**
[178]699     * @name Reader stuff
700     * @{
701     */
702
[181]703    /** Read handler. */
[179]704    yaml_read_handler_t *read_handler;
[178]705
706    /** A pointer for passing to the read handler. */
[179]707    void *read_handler_data;
[178]708
[208]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
[178]725    /** EOF flag */
726    int eof;
727
[208]728    /** The working buffer. */
729    struct {
[211]730        /** The beginning of the buffer. */
[208]731        yaml_char_t *start;
[211]732        /** The end of the buffer. */
[208]733        yaml_char_t *end;
[211]734        /** The current position of the buffer. */
[208]735        yaml_char_t *pointer;
[211]736        /** The last filled position of the buffer. */
[208]737        yaml_char_t *last;
738    } buffer;
[178]739
[208]740    /* The number of unread characters in the buffer. */
[180]741    size_t unread;
[179]742
[208]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;
[178]754
755    /** The input encoding. */
756    yaml_encoding_t encoding;
757
[179]758    /** The offset of the current position (in bytes). */
759    size_t offset;
760
[208]761    /** The mark of the current position. */
762    yaml_mark_t mark;
[179]763
[178]764    /**
765     * @}
766     */
767
[184]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
[208]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;
[184]793
[208]794    /** The number of tokens fetched from the queue. */
[184]795    size_t tokens_parsed;
796
[208]797    /* Does the tokens queue contain a token ready for dequeueing. */
798    int token_available;
[184]799
[208]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;
[184]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
[208]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;
[184]825
826    /**
827     * @}
828     */
829
[201]830    /**
831     * @name Parser stuff
832     * @{
833     */
834
835    /** The parser states stack. */
[208]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;
[201]844
845    /** The current parser state. */
846    yaml_parser_state_t state;
847
848    /** The stack of marks. */
[208]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;
[201]857
858    /** The list of TAG directives. */
[208]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;
[201]867
868    /**
869     * @}
870     */
871
[162]872} yaml_parser_t;
873
[178]874/**
[208]875 * Initialize a parser.
[178]876 *
877 * This function creates a new parser object.  An application is responsible
[220]878 * for destroying the object using the yaml_parser_delete() function.
[178]879 *
[220]880 * @param[out]  parser  An empty parser object.
[208]881 *
[211]882 * @returns @c 1 if the function succeeded, @c 0 on error.
[178]883 */
884
[208]885YAML_DECLARE(int)
886yaml_parser_initialize(yaml_parser_t *parser);
[178]887
888/**
889 * Destroy a parser.
890 *
[220]891 * @param[in,out]   parser  A parser object.
[178]892 */
893
[183]894YAML_DECLARE(void)
[178]895yaml_parser_delete(yaml_parser_t *parser);
896
[179]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 *
[220]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.
[179]907 */
908
[183]909YAML_DECLARE(void)
[179]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 *
[220]919 * @param[in,out]   parser  A parser object.
920 * @param[in]       file    An open file.
[179]921 */
922
[183]923YAML_DECLARE(void)
[179]924yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
925
926/**
927 * Set a generic input handler.
928 *
[220]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.
[179]933 */
934
[183]935YAML_DECLARE(void)
[179]936yaml_parser_set_input(yaml_parser_t *parser,
937        yaml_read_handler_t *handler, void *data);
938
939/**
940 * Set the source encoding.
941 *
[220]942 * @param[in,out]   parser      A parser object.
943 * @param[in]       encoding    The source encoding.
[179]944 */
945
[183]946YAML_DECLARE(void)
[179]947yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
948
[184]949/**
[208]950 * Scan the input stream and produce the next token.
[184]951 *
[208]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.
[184]956 *
[208]957 * An application is responsible for freeing any buffers associated with the
958 * produced token object using the @c yaml_token_delete function.
[184]959 *
[220]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.
[184]962 *
[220]963 * @param[in,out]   parser      A parser object.
964 * @param[out]      token       An empty token object.
[184]965 *
[208]966 * @returns @c 1 if the function succeeded, @c 0 on error.
[184]967 */
968
[208]969YAML_DECLARE(int)
970yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
[184]971
[201]972/**
[208]973 * Parse the input stream and produce the next parsing event.
[201]974 *
[208]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.
[201]979 *
[208]980 * An application is responsible for freeing any buffers associated with the
[220]981 * produced event object using the yaml_event_delete() function.
[201]982 *
[220]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.
[201]985 *
[220]986 * @param[in,out]   parser      A parser object.
987 * @param[out]      event       An empty event object.
[201]988 *
[208]989 * @returns @c 1 if the function succeeded, @c 0 on error.
[201]990 */
991
[208]992YAML_DECLARE(int)
993yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
[201]994
[178]995/** @} */
996
[211]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 *
[220]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.
[211]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,
[213]1038    YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
1039    YAML_EMIT_END_STATE
[211]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
[162]1049typedef struct {
[211]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
[214]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
[211]1250    /**
1251     * @}
1252     */
1253
[162]1254} yaml_emitter_t;
1255
[211]1256/**
1257 * Initialize an emitter.
1258 *
1259 * This function creates a new emitter object.  An application is responsible
[220]1260 * for destroying the object using the yaml_emitter_delete() function.
[211]1261 *
[220]1262 * @param[out]      emitter     An empty parser object.
[211]1263 *
1264 * @returns @c 1 if the function succeeded, @c 0 on error.
1265 */
1266
[208]1267YAML_DECLARE(int)
[211]1268yaml_emitter_initialize(yaml_emitter_t *emitter);
1269
1270/**
1271 * Destroy an emitter.
1272 *
[220]1273 * @param[in,out]   emitter     An emitter object.
[211]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 *
[220]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.
[211]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 *
[220]1304 * @param[in,out]   emitter     An emitter object.
1305 * @param[in]       file        An open file.
[211]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 *
[220]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.
[211]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 *
[220]1327 * @param[in,out]   emitter     An emitter object.
1328 * @param[in]       encoding    The output encoding.
[211]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 *
[220]1338 * @param[in,out]   emitter     An emitter object.
1339 * @param[in]       canonical   If the output is canonical.
[211]1340 */
1341
1342YAML_DECLARE(void)
1343yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1344
1345/**
1346 * Set the intendation increment.
1347 *
[220]1348 * @param[in,out]   emitter     An emitter object.
1349 * @param[in]       indent      The indentation increment (1 < . < 10).
[211]1350 */
1351
1352YAML_DECLARE(void)
1353yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1354
1355/**
[212]1356 * Set the preferred line width. @c -1 means unlimited.
[211]1357 *
[220]1358 * @param[in,out]   emitter     An emitter object.
1359 * @param[in]       width       The preferred line width.
[211]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 *
[220]1368 * @param[in,out]   emitter     An emitter object.
1369 * @param[in]       unicode     If unescaped Unicode characters are allowed.
[211]1370 */
1371
1372YAML_DECLARE(void)
1373yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1374
1375/**
1376 * Set the preferred line break.
1377 *
[220]1378 * @param[in,out]   emitter     An emitter object.
1379 * @param[in]       line_break  The preferred line break.
[211]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 *
[220]1388 * The event object may be generated using the yaml_parser_parse() function.
[213]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.
[211]1392 *
[220]1393 * @param[in,out]   emitter     An emitter object.
1394 * @param[in,out]   event       An event object.
[211]1395 *
1396 * @returns @c 1 if the function succeeded, @c 0 on error.
1397 */
1398
1399YAML_DECLARE(int)
[208]1400yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
[179]1401
[211]1402/**
1403 * Flush the accumulated characters to the output.
1404 *
[220]1405 * @param[in,out]   emitter     An emitter object.
[211]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
[162]1415#ifdef __cplusplus
1416}
1417#endif
1418
[169]1419#endif /* #ifndef YAML_H */
[162]1420
Note: See TracBrowser for help on using the repository browser.