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.

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.
[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 *
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,
[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 *
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/**
[208]581 * Free any memory allocated for an event object.
[199]582 *
583 * @param[in]   event   An event object.
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 *
[180]603 * @param[in]   data        A pointer to an application data specified by
[179]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.
[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
878 * for destroying the object using the @c yaml_parser_delete function.
879 *
[208]880 * @param[in]   parser  An empty parser object.
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 *
891 * @param[in]   parser  A parser object.
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 *
904 * @param[in]   parser  A parser object.
905 * @param[in]   input   A source data.
[183]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 *
919 * @param[in]   parser  A parser object.
920 * @param[in]   file    An open file.
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 *
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
[183]934YAML_DECLARE(void)
[179]935yaml_parser_set_input(yaml_parser_t *parser,
936        yaml_read_handler_t *handler, void *data);
937
938/**
939 * Set the source encoding.
940 *
[183]941 * @param[in]   parser      A parser object.
[179]942 * @param[in]   encoding    The source encoding.
943 */
944
[183]945YAML_DECLARE(void)
[179]946yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
947
[184]948/**
[208]949 * Scan the input stream and produce the next token.
[184]950 *
[208]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.
[184]955 *
[208]956 * An application is responsible for freeing any buffers associated with the
957 * produced token object using the @c yaml_token_delete function.
[184]958 *
[208]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.
[184]961 *
962 * @param[in]   parser      A parser object.
[208]963 * @param[in]   token       An empty token object.
[184]964 *
[208]965 * @returns @c 1 if the function succeeded, @c 0 on error.
[184]966 */
967
[208]968YAML_DECLARE(int)
969yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
[184]970
[201]971/**
[208]972 * Parse the input stream and produce the next parsing event.
[201]973 *
[208]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.
[201]978 *
[208]979 * An application is responsible for freeing any buffers associated with the
980 * produced event object using the @c yaml_event_delete function.
[201]981 *
[208]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.
[201]984 *
985 * @param[in]   parser      A parser object.
[208]986 * @param[in]   event       An empty event object.
[201]987 *
[208]988 * @returns @c 1 if the function succeeded, @c 0 on error.
[201]989 */
990
[208]991YAML_DECLARE(int)
992yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
[201]993
[178]994/** @} */
995
[211]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,
[213]1037    YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
1038    YAML_EMIT_END_STATE
[211]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
[162]1048typedef struct {
[211]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
[214]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
[211]1249    /**
1250     * @}
1251     */
1252
[162]1253} yaml_emitter_t;
1254
[211]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
[208]1266YAML_DECLARE(int)
[211]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.
[212]1346 * @param[in]   indent      The indentation increment (1 < . < 10).
[211]1347 */
1348
1349YAML_DECLARE(void)
1350yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1351
1352/**
[212]1353 * Set the preferred line width. @c -1 means unlimited.
[211]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.
[213]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.
[211]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)
[208]1397yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
[179]1398
[211]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
[162]1412#ifdef __cplusplus
1413}
1414#endif
1415
[169]1416#endif /* #ifndef YAML_H */
[162]1417
Note: See TracBrowser for help on using the repository browser.