source: libyaml/tags/0.1.4/include/yaml.h @ 385

Revision 385, 53.0 KB checked in by xi, 4 years ago (diff)

Merged _WIN32 fix from the stable branch.

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
[385]29#ifdef _WIN32
[183]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 *
[238]62 * @param[out]      major   Major version number.
63 * @param[out]      minor   Minor version number.
64 * @param[out]      patch   Patch version number.
[178]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. */
[238]81typedef struct yaml_version_directive_s {
[199]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. */
[238]89typedef struct yaml_tag_directive_s {
[199]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. */
[238]97typedef enum yaml_encoding_e {
[243]98    /** Let the parser choose the encoding. */
[178]99    YAML_ANY_ENCODING,
[243]100    /** The default UTF-8 encoding. */
[162]101    YAML_UTF8_ENCODING,
[243]102    /** The UTF-16-LE encoding with BOM. */
[162]103    YAML_UTF16LE_ENCODING,
[243]104    /** The UTF-16-BE encoding with BOM. */
[162]105    YAML_UTF16BE_ENCODING
106} yaml_encoding_t;
107
[211]108/** Line break types. */
109
[238]110typedef enum yaml_break_e {
[243]111    /** Let the parser choose the break type. */
[211]112    YAML_ANY_BREAK,
[243]113    /** Use CR for line breaks (Mac style). */
[211]114    YAML_CR_BREAK,
[243]115    /** Use LN for line breaks (Unix style). */
[211]116    YAML_LN_BREAK,
[243]117    /** Use CR LN for line breaks (DOS style). */
[211]118    YAML_CRLN_BREAK
119} yaml_break_t;
120
[179]121/** Many bad things could happen with the parser and emitter. */
[238]122typedef enum yaml_error_type_e {
[243]123    /** No error is produced. */
[178]124    YAML_NO_ERROR,
125
[243]126    /** Cannot allocate or reallocate a block of memory. */
[178]127    YAML_MEMORY_ERROR,
128
[243]129    /** Cannot read or decode the input stream. */
[178]130    YAML_READER_ERROR,
[243]131    /** Cannot scan the input stream. */
[178]132    YAML_SCANNER_ERROR,
[243]133    /** Cannot parse the input stream. */
[178]134    YAML_PARSER_ERROR,
[243]135    /** Cannot compose a YAML document. */
[238]136    YAML_COMPOSER_ERROR,
[178]137
[243]138    /** Cannot write to the output stream. */
[178]139    YAML_WRITER_ERROR,
[243]140    /** Cannot emit a YAML stream. */
[178]141    YAML_EMITTER_ERROR
142} yaml_error_type_t;
143
[183]144/** The pointer position. */
[238]145typedef struct yaml_mark_s {
[183]146    /** The position index. */
147    size_t index;
148
149    /** The position line. */
150    size_t line;
151
152    /** The position column. */
153    size_t column;
154} yaml_mark_t;
155
[179]156/** @} */
157
[183]158/**
[184]159 * @defgroup styles Node Styles
[183]160 * @{
161 */
[179]162
[183]163/** Scalar styles. */
[238]164typedef enum yaml_scalar_style_e {
[243]165    /** Let the emitter choose the style. */
[169]166    YAML_ANY_SCALAR_STYLE,
[183]167
[243]168    /** The plain scalar style. */
[162]169    YAML_PLAIN_SCALAR_STYLE,
[183]170
[243]171    /** The single-quoted scalar style. */
[162]172    YAML_SINGLE_QUOTED_SCALAR_STYLE,
[243]173    /** The double-quoted scalar style. */
[162]174    YAML_DOUBLE_QUOTED_SCALAR_STYLE,
[183]175
[243]176    /** The literal scalar style. */
[162]177    YAML_LITERAL_SCALAR_STYLE,
[243]178    /** The folded scalar style. */
[162]179    YAML_FOLDED_SCALAR_STYLE
180} yaml_scalar_style_t;
181
[183]182/** Sequence styles. */
[238]183typedef enum yaml_sequence_style_e {
[243]184    /** Let the emitter choose the style. */
[169]185    YAML_ANY_SEQUENCE_STYLE,
[183]186
[243]187    /** The block sequence style. */
[162]188    YAML_BLOCK_SEQUENCE_STYLE,
[243]189    /** The flow sequence style. */
[162]190    YAML_FLOW_SEQUENCE_STYLE
191} yaml_sequence_style_t;
192
[183]193/** Mapping styles. */
[238]194typedef enum yaml_mapping_style_e {
[243]195    /** Let the emitter choose the style. */
[169]196    YAML_ANY_MAPPING_STYLE,
[183]197
[243]198    /** The block mapping style. */
[162]199    YAML_BLOCK_MAPPING_STYLE,
[243]200    /** The flow mapping style. */
[213]201    YAML_FLOW_MAPPING_STYLE
202/*    YAML_FLOW_SET_MAPPING_STYLE   */
[162]203} yaml_mapping_style_t;
204
[183]205/** @} */
206
207/**
[184]208 * @defgroup tokens Tokens
[183]209 * @{
210 */
211
212/** Token types. */
[238]213typedef enum yaml_token_type_e {
[243]214    /** An empty token. */
[208]215    YAML_NO_TOKEN,
216
[243]217    /** A STREAM-START token. */
[162]218    YAML_STREAM_START_TOKEN,
[243]219    /** A STREAM-END token. */
[162]220    YAML_STREAM_END_TOKEN,
[169]221
[243]222    /** A VERSION-DIRECTIVE token. */
[162]223    YAML_VERSION_DIRECTIVE_TOKEN,
[243]224    /** A TAG-DIRECTIVE token. */
[162]225    YAML_TAG_DIRECTIVE_TOKEN,
[243]226    /** A DOCUMENT-START token. */
[162]227    YAML_DOCUMENT_START_TOKEN,
[243]228    /** A DOCUMENT-END token. */
[162]229    YAML_DOCUMENT_END_TOKEN,
[169]230
[243]231    /** A BLOCK-SEQUENCE-START token. */
[162]232    YAML_BLOCK_SEQUENCE_START_TOKEN,
[243]233    /** A BLOCK-SEQUENCE-END token. */
[162]234    YAML_BLOCK_MAPPING_START_TOKEN,
[243]235    /** A BLOCK-END token. */
[162]236    YAML_BLOCK_END_TOKEN,
[169]237
[243]238    /** A FLOW-SEQUENCE-START token. */
[162]239    YAML_FLOW_SEQUENCE_START_TOKEN,
[243]240    /** A FLOW-SEQUENCE-END token. */
[162]241    YAML_FLOW_SEQUENCE_END_TOKEN,
[243]242    /** A FLOW-MAPPING-START token. */
[162]243    YAML_FLOW_MAPPING_START_TOKEN,
[243]244    /** A FLOW-MAPPING-END token. */
[162]245    YAML_FLOW_MAPPING_END_TOKEN,
[169]246
[243]247    /** A BLOCK-ENTRY token. */
[162]248    YAML_BLOCK_ENTRY_TOKEN,
[243]249    /** A FLOW-ENTRY token. */
[162]250    YAML_FLOW_ENTRY_TOKEN,
[243]251    /** A KEY token. */
[162]252    YAML_KEY_TOKEN,
[243]253    /** A VALUE token. */
[162]254    YAML_VALUE_TOKEN,
[169]255
[243]256    /** An ALIAS token. */
[162]257    YAML_ALIAS_TOKEN,
[243]258    /** An ANCHOR token. */
[162]259    YAML_ANCHOR_TOKEN,
[243]260    /** A TAG token. */
[162]261    YAML_TAG_TOKEN,
[243]262    /** A SCALAR token. */
[162]263    YAML_SCALAR_TOKEN
264} yaml_token_type_t;
265
[183]266/** The token structure. */
[238]267typedef struct yaml_token_s {
[169]268
[183]269    /** The token type. */
270    yaml_token_type_t type;
[169]271
[183]272    /** The token data. */
273    union {
[169]274
[199]275        /** The stream start (for @c YAML_STREAM_START_TOKEN). */
276        struct {
277            /** The stream encoding. */
278            yaml_encoding_t encoding;
279        } stream_start;
[169]280
[199]281        /** The alias (for @c YAML_ALIAS_TOKEN). */
282        struct {
283            /** The alias value. */
284            yaml_char_t *value;
285        } alias;
[162]286
[199]287        /** The anchor (for @c YAML_ANCHOR_TOKEN). */
288        struct {
289            /** The anchor value. */
290            yaml_char_t *value;
291        } anchor;
292
[183]293        /** The tag (for @c YAML_TAG_TOKEN). */
294        struct {
295            /** The tag handle. */
296            yaml_char_t *handle;
297            /** The tag suffix. */
298            yaml_char_t *suffix;
299        } tag;
[162]300
[183]301        /** The scalar value (for @c YAML_SCALAR_TOKEN). */
[162]302        struct {
[183]303            /** The scalar value. */
304            yaml_char_t *value;
305            /** The length of the scalar value. */
[169]306            size_t length;
[183]307            /** The scalar style. */
[162]308            yaml_scalar_style_t style;
309        } scalar;
[183]310
311        /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
[162]312        struct {
[183]313            /** The major version number. */
[162]314            int major;
[183]315            /** The minor version number. */
[162]316            int minor;
[183]317        } version_directive;
318
319        /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
[162]320        struct {
[183]321            /** The tag handle. */
322            yaml_char_t *handle;
323            /** The tag prefix. */
324            yaml_char_t *prefix;
325        } tag_directive;
[208]326
[162]327    } data;
[183]328
329    /** The beginning of the token. */
[162]330    yaml_mark_t start_mark;
[183]331    /** The end of the token. */
[162]332    yaml_mark_t end_mark;
[183]333
[162]334} yaml_token_t;
335
[183]336/**
[208]337 * Free any memory allocated for a token object.
[183]338 *
[220]339 * @param[in,out]   token   A token object.
[183]340 */
341
342YAML_DECLARE(void)
343yaml_token_delete(yaml_token_t *token);
344
345/** @} */
346
[199]347/**
348 * @defgroup events Events
349 * @{
350 */
[183]351
[199]352/** Event types. */
[238]353typedef enum yaml_event_type_e {
[243]354    /** An empty event. */
[208]355    YAML_NO_EVENT,
356
[243]357    /** A STREAM-START event. */
[183]358    YAML_STREAM_START_EVENT,
[243]359    /** A STREAM-END event. */
[183]360    YAML_STREAM_END_EVENT,
361
[243]362    /** A DOCUMENT-START event. */
[183]363    YAML_DOCUMENT_START_EVENT,
[243]364    /** A DOCUMENT-END event. */
[183]365    YAML_DOCUMENT_END_EVENT,
366
[243]367    /** An ALIAS event. */
[183]368    YAML_ALIAS_EVENT,
[243]369    /** A SCALAR event. */
[183]370    YAML_SCALAR_EVENT,
371
[243]372    /** A SEQUENCE-START event. */
[183]373    YAML_SEQUENCE_START_EVENT,
[243]374    /** A SEQUENCE-END event. */
[183]375    YAML_SEQUENCE_END_EVENT,
376
[243]377    /** A MAPPING-START event. */
[183]378    YAML_MAPPING_START_EVENT,
[243]379    /** A MAPPING-END event. */
[183]380    YAML_MAPPING_END_EVENT
381} yaml_event_type_t;
382
[199]383/** The event structure. */
[238]384typedef struct yaml_event_s {
[199]385
386    /** The event type. */
[162]387    yaml_event_type_t type;
[199]388
389    /** The event data. */
[162]390    union {
[199]391       
392        /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
[162]393        struct {
[199]394            /** The document encoding. */
[162]395            yaml_encoding_t encoding;
396        } stream_start;
[199]397
398        /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
[162]399        struct {
[199]400            /** The version directive. */
401            yaml_version_directive_t *version_directive;
[208]402
[199]403            /** The list of tag directives. */
[208]404            struct {
405                /** The beginning of the tag directives list. */
406                yaml_tag_directive_t *start;
407                /** The end of the tag directives list. */
408                yaml_tag_directive_t *end;
409            } tag_directives;
410
[199]411            /** Is the document indicator implicit? */
[162]412            int implicit;
413        } document_start;
[199]414
415        /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
[162]416        struct {
[199]417            /** Is the document end indicator implicit? */
[162]418            int implicit;
419        } document_end;
[199]420
421        /** The alias parameters (for @c YAML_ALIAS_EVENT). */
[162]422        struct {
[199]423            /** The anchor. */
424            yaml_char_t *anchor;
[162]425        } alias;
[199]426
427        /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
[162]428        struct {
[199]429            /** The anchor. */
430            yaml_char_t *anchor;
431            /** The tag. */
432            yaml_char_t *tag;
433            /** The scalar value. */
434            yaml_char_t *value;
435            /** The length of the scalar value. */
[169]436            size_t length;
[199]437            /** Is the tag optional for the plain style? */
[162]438            int plain_implicit;
[199]439            /** Is the tag optional for any non-plain style? */
[162]440            int quoted_implicit;
[199]441            /** The scalar style. */
[162]442            yaml_scalar_style_t style;
443        } scalar;
[199]444
445        /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
[162]446        struct {
[199]447            /** The anchor. */
448            yaml_char_t *anchor;
449            /** The tag. */
450            yaml_char_t *tag;
451            /** Is the tag optional? */
[162]452            int implicit;
[199]453            /** The sequence style. */
[162]454            yaml_sequence_style_t style;
455        } sequence_start;
[199]456
457        /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
[162]458        struct {
[199]459            /** The anchor. */
460            yaml_char_t *anchor;
461            /** The tag. */
462            yaml_char_t *tag;
463            /** Is the tag optional? */
[162]464            int implicit;
[199]465            /** The mapping style. */
[162]466            yaml_mapping_style_t style;
467        } mapping_start;
[199]468
[162]469    } data;
[199]470
[237]471    /** The beginning of the event. */
[162]472    yaml_mark_t start_mark;
[237]473    /** The end of the event. */
[162]474    yaml_mark_t end_mark;
[208]475
[162]476} yaml_event_t;
477
[199]478/**
[213]479 * Create the STREAM-START event.
480 *
[238]481 * @param[out]      event       An empty event object.
482 * @param[in]       encoding    The stream encoding.
[213]483 *
484 * @returns @c 1 if the function succeeded, @c 0 on error.
485 */
486
487YAML_DECLARE(int)
488yaml_stream_start_event_initialize(yaml_event_t *event,
489        yaml_encoding_t encoding);
490
491/**
492 * Create the STREAM-END event.
493 *
[238]494 * @param[out]      event       An empty event object.
[213]495 *
496 * @returns @c 1 if the function succeeded, @c 0 on error.
497 */
498
499YAML_DECLARE(int)
500yaml_stream_end_event_initialize(yaml_event_t *event);
501
502/**
503 * Create the DOCUMENT-START event.
504 *
505 * The @a implicit argument is considered as a stylistic parameter and may be
506 * ignored by the emitter.
507 *
[238]508 * @param[out]      event                   An empty event object.
509 * @param[in]       version_directive       The %YAML directive value or
510 *                                          @c NULL.
511 * @param[in]       tag_directives_start    The beginning of the %TAG
512 *                                          directives list.
513 * @param[in]       tag_directives_end      The end of the %TAG directives
514 *                                          list.
515 * @param[in]       implicit                If the document start indicator is
516 *                                          implicit.
[213]517 *
518 * @returns @c 1 if the function succeeded, @c 0 on error.
519 */
520
521YAML_DECLARE(int)
522yaml_document_start_event_initialize(yaml_event_t *event,
523        yaml_version_directive_t *version_directive,
524        yaml_tag_directive_t *tag_directives_start,
525        yaml_tag_directive_t *tag_directives_end,
526        int implicit);
527
528/**
529 * Create the DOCUMENT-END event.
530 *
531 * The @a implicit argument is considered as a stylistic parameter and may be
532 * ignored by the emitter.
533 *
[238]534 * @param[out]      event       An empty event object.
535 * @param[in]       implicit    If the document end indicator is implicit.
[213]536 *
537 * @returns @c 1 if the function succeeded, @c 0 on error.
538 */
539
540YAML_DECLARE(int)
541yaml_document_end_event_initialize(yaml_event_t *event, int implicit);
542
543/**
544 * Create an ALIAS event.
545 *
[238]546 * @param[out]      event       An empty event object.
547 * @param[in]       anchor      The anchor value.
[213]548 *
549 * @returns @c 1 if the function succeeded, @c 0 on error.
550 */
551
552YAML_DECLARE(int)
553yaml_alias_event_initialize(yaml_event_t *event, yaml_char_t *anchor);
554
555/**
556 * Create a SCALAR event.
557 *
558 * The @a style argument may be ignored by the emitter.
559 *
560 * Either the @a tag attribute or one of the @a plain_implicit and
561 * @a quoted_implicit flags must be set.
562 *
[238]563 * @param[out]      event           An empty event object.
564 * @param[in]       anchor          The scalar anchor or @c NULL.
565 * @param[in]       tag             The scalar tag or @c NULL.
566 * @param[in]       value           The scalar value.
567 * @param[in]       length          The length of the scalar value.
568 * @param[in]       plain_implicit  If the tag may be omitted for the plain
569 *                                  style.
570 * @param[in]       quoted_implicit If the tag may be omitted for any
571 *                                  non-plain style.
572 * @param[in]       style           The scalar style.
[213]573 *
574 * @returns @c 1 if the function succeeded, @c 0 on error.
575 */
576
577YAML_DECLARE(int)
578yaml_scalar_event_initialize(yaml_event_t *event,
579        yaml_char_t *anchor, yaml_char_t *tag,
[219]580        yaml_char_t *value, int length,
[213]581        int plain_implicit, int quoted_implicit,
582        yaml_scalar_style_t style);
583
584/**
585 * Create a SEQUENCE-START event.
586 *
587 * The @a style argument may be ignored by the emitter.
588 *
589 * Either the @a tag attribute or the @a implicit flag must be set.
590 *
[238]591 * @param[out]      event       An empty event object.
592 * @param[in]       anchor      The sequence anchor or @c NULL.
593 * @param[in]       tag         The sequence tag or @c NULL.
594 * @param[in]       implicit    If the tag may be omitted.
595 * @param[in]       style       The sequence style.
[213]596 *
597 * @returns @c 1 if the function succeeded, @c 0 on error.
598 */
599
600YAML_DECLARE(int)
601yaml_sequence_start_event_initialize(yaml_event_t *event,
602        yaml_char_t *anchor, yaml_char_t *tag, int implicit,
603        yaml_sequence_style_t style);
604
605/**
606 * Create a SEQUENCE-END event.
607 *
[238]608 * @param[out]      event       An empty event object.
[213]609 *
610 * @returns @c 1 if the function succeeded, @c 0 on error.
611 */
612
613YAML_DECLARE(int)
614yaml_sequence_end_event_initialize(yaml_event_t *event);
615
616/**
617 * Create a MAPPING-START event.
618 *
619 * The @a style argument may be ignored by the emitter.
620 *
621 * Either the @a tag attribute or the @a implicit flag must be set.
622 *
[238]623 * @param[out]      event       An empty event object.
624 * @param[in]       anchor      The mapping anchor or @c NULL.
625 * @param[in]       tag         The mapping tag or @c NULL.
626 * @param[in]       implicit    If the tag may be omitted.
627 * @param[in]       style       The mapping style.
[213]628 *
629 * @returns @c 1 if the function succeeded, @c 0 on error.
630 */
631
632YAML_DECLARE(int)
633yaml_mapping_start_event_initialize(yaml_event_t *event,
634        yaml_char_t *anchor, yaml_char_t *tag, int implicit,
635        yaml_mapping_style_t style);
636
637/**
638 * Create a MAPPING-END event.
639 *
[238]640 * @param[out]      event       An empty event object.
[213]641 *
642 * @returns @c 1 if the function succeeded, @c 0 on error.
643 */
644
645YAML_DECLARE(int)
646yaml_mapping_end_event_initialize(yaml_event_t *event);
647
648/**
[208]649 * Free any memory allocated for an event object.
[199]650 *
[238]651 * @param[in,out]   event   An event object.
[199]652 */
653
654YAML_DECLARE(void)
655yaml_event_delete(yaml_event_t *event);
656
[243]657/** @} */
658
[237]659/**
660 * @defgroup nodes Nodes
661 * @{
662 */
663
[243]664/** The tag @c !!null with the only possible value: @c null. */
[237]665#define YAML_NULL_TAG       "tag:yaml.org,2002:null"
[243]666/** The tag @c !!bool with the values: @c true and @c falce. */
[237]667#define YAML_BOOL_TAG       "tag:yaml.org,2002:bool"
[243]668/** The tag @c !!str for string values. */
[237]669#define YAML_STR_TAG        "tag:yaml.org,2002:str"
[243]670/** The tag @c !!int for integer values. */
[237]671#define YAML_INT_TAG        "tag:yaml.org,2002:int"
[243]672/** The tag @c !!float for float values. */
[237]673#define YAML_FLOAT_TAG      "tag:yaml.org,2002:float"
[243]674/** The tag @c !!timestamp for date and time values. */
[237]675#define YAML_TIMESTAMP_TAG  "tag:yaml.org,2002:timestamp"
676
[243]677/** The tag @c !!seq is used to denote sequences. */
[237]678#define YAML_SEQ_TAG        "tag:yaml.org,2002:seq"
[243]679/** The tag @c !!map is used to denote mapping. */
[237]680#define YAML_MAP_TAG        "tag:yaml.org,2002:map"
681
[243]682/** The default scalar tag is @c !!str. */
[237]683#define YAML_DEFAULT_SCALAR_TAG     YAML_STR_TAG
[243]684/** The default sequence tag is @c !!seq. */
[237]685#define YAML_DEFAULT_SEQUENCE_TAG   YAML_SEQ_TAG
[243]686/** The default mapping tag is @c !!map. */
[238]687#define YAML_DEFAULT_MAPPING_TAG    YAML_MAP_TAG
[237]688
689/** Node types. */
[238]690typedef enum yaml_node_type_e {
[243]691    /** An empty node. */
[237]692    YAML_NO_NODE,
693
[243]694    /** A scalar node. */
[237]695    YAML_SCALAR_NODE,
[243]696    /** A sequence node. */
[237]697    YAML_SEQUENCE_NODE,
[243]698    /** A mapping node. */
[237]699    YAML_MAPPING_NODE
700} yaml_node_type_t;
701
[238]702/** The forward definition of a document node structure. */
703typedef struct yaml_node_s yaml_node_t;
[237]704
[238]705/** An element of a sequence node. */
706typedef int yaml_node_item_t;
[237]707
[238]708/** An element of a mapping node. */
709typedef struct yaml_node_pair_s {
710    /** The key of the element. */
711    int key;
712    /** The value of the element. */
713    int value;
[237]714} yaml_node_pair_t;
715
716/** The node structure. */
[238]717struct yaml_node_s {
[237]718
719    /** The node type. */
720    yaml_node_type_t type;
721
[238]722    /** The node tag. */
723    yaml_char_t *tag;
[237]724
725    /** The node data. */
726    union {
727       
728        /** The scalar parameters (for @c YAML_SCALAR_NODE). */
729        struct {
730            /** The scalar value. */
731            yaml_char_t *value;
732            /** The length of the scalar value. */
733            size_t length;
734            /** The scalar style. */
735            yaml_scalar_style_t style;
736        } scalar;
737
738        /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
739        struct {
740            /** The stack of sequence items. */
741            struct {
742                /** The beginning of the stack. */
[238]743                yaml_node_item_t *start;
[237]744                /** The end of the stack. */
[238]745                yaml_node_item_t *end;
[237]746                /** The top of the stack. */
[238]747                yaml_node_item_t *top;
[237]748            } items;
749            /** The sequence style. */
750            yaml_sequence_style_t style;
751        } sequence;
752
753        /** The mapping parameters (for @c YAML_MAPPING_NODE). */
754        struct {
[238]755            /** The stack of mapping pairs (key, value). */
[237]756            struct {
757                /** The beginning of the stack. */
[238]758                yaml_node_pair_t *start;
[237]759                /** The end of the stack. */
[238]760                yaml_node_pair_t *end;
[237]761                /** The top of the stack. */
[238]762                yaml_node_pair_t *top;
[237]763            } pairs;
764            /** The mapping style. */
765            yaml_mapping_style_t style;
766        } mapping;
767
768    } data;
769
770    /** The beginning of the node. */
771    yaml_mark_t start_mark;
772    /** The end of the node. */
773    yaml_mark_t end_mark;
774
[238]775};
[237]776
[238]777/** The document structure. */
778typedef struct yaml_document_s {
[237]779
[238]780    /** The document nodes. */
781    struct {
782        /** The beginning of the stack. */
783        yaml_node_t *start;
784        /** The end of the stack. */
785        yaml_node_t *end;
786        /** The top of the stack. */
787        yaml_node_t *top;
788    } nodes;
[237]789
[238]790    /** The version directive. */
791    yaml_version_directive_t *version_directive;
792
793    /** The list of tag directives. */
794    struct {
795        /** The beginning of the tag directives list. */
796        yaml_tag_directive_t *start;
797        /** The end of the tag directives list. */
798        yaml_tag_directive_t *end;
799    } tag_directives;
800
801    /** Is the document start indicator implicit? */
802    int start_implicit;
803    /** Is the document end indicator implicit? */
804    int end_implicit;
805
806    /** The beginning of the document. */
807    yaml_mark_t start_mark;
808    /** The end of the document. */
809    yaml_mark_t end_mark;
810
811} yaml_document_t;
812
[237]813/**
[238]814 * Create a YAML document.
[237]815 *
[238]816 * @param[out]      document                An empty document object.
817 * @param[in]       version_directive       The %YAML directive value or
818 *                                          @c NULL.
819 * @param[in]       tag_directives_start    The beginning of the %TAG
820 *                                          directives list.
821 * @param[in]       tag_directives_end      The end of the %TAG directives
822 *                                          list.
823 * @param[in]       start_implicit          If the document start indicator is
824 *                                          implicit.
825 * @param[in]       end_implicit            If the document end indicator is
826 *                                          implicit.
[237]827 *
828 * @returns @c 1 if the function succeeded, @c 0 on error.
829 */
830
831YAML_DECLARE(int)
[238]832yaml_document_initialize(yaml_document_t *document,
833        yaml_version_directive_t *version_directive,
834        yaml_tag_directive_t *tag_directives_start,
835        yaml_tag_directive_t *tag_directives_end,
836        int start_implicit, int end_implicit);
[237]837
838/**
[238]839 * Delete a YAML document and all its nodes.
[237]840 *
[238]841 * @param[in,out]   document        A document object.
[237]842 */
843
[238]844YAML_DECLARE(void)
845yaml_document_delete(yaml_document_t *document);
[237]846
847/**
[238]848 * Get a node of a YAML document.
[237]849 *
[238]850 * The pointer returned by this function is valid until any of the functions
851 * modifying the documents are called.
[237]852 *
[238]853 * @param[in]       document        A document object.
[243]854 * @param[in]       index           The node id.
[238]855 *
856 * @returns the node objct or @c NULL if @c node_id is out of range.
[237]857 */
858
[238]859YAML_DECLARE(yaml_node_t *)
[243]860yaml_document_get_node(yaml_document_t *document, int index);
[237]861
862/**
[238]863 * Get the root of a YAML document node.
[237]864 *
[238]865 * The root object is the first object added to the document.
[237]866 *
[238]867 * The pointer returned by this function is valid until any of the functions
868 * modifying the documents are called.
[237]869 *
[238]870 * An empty document produced by the parser signifies the end of a YAML
871 * stream.
872 *
873 * @param[in]       document        A document object.
874 *
875 * @returns the node object or @c NULL if the document is empty.
[237]876 */
877
[238]878YAML_DECLARE(yaml_node_t *)
879yaml_document_get_root_node(yaml_document_t *document);
[237]880
881/**
[238]882 * Create a SCALAR node and attach it to the document.
[237]883 *
884 * The @a style argument may be ignored by the emitter.
885 *
[238]886 * @param[in,out]   document        A document object.
887 * @param[in]       tag             The scalar tag.
888 * @param[in]       value           The scalar value.
889 * @param[in]       length          The length of the scalar value.
890 * @param[in]       style           The scalar style.
[237]891 *
[238]892 * @returns the node id or @c 0 on error.
[237]893 */
894
895YAML_DECLARE(int)
[238]896yaml_document_add_scalar(yaml_document_t *document,
897        yaml_char_t *tag, yaml_char_t *value, int length,
898        yaml_scalar_style_t style);
[237]899
900/**
[238]901 * Create a SEQUENCE node and attach it to the document.
[237]902 *
[238]903 * The @a style argument may be ignored by the emitter.
[237]904 *
[238]905 * @param[in,out]   document    A document object.
906 * @param[in]       tag         The sequence tag.
907 * @param[in]       style       The sequence style.
908 *
909 * @returns the node id or @c 0 on error.
[237]910 */
911
912YAML_DECLARE(int)
[238]913yaml_document_add_sequence(yaml_document_t *document,
914        yaml_char_t *tag, yaml_sequence_style_t style);
[237]915
916/**
[238]917 * Create a MAPPING node and attach it to the document.
[237]918 *
[238]919 * The @a style argument may be ignored by the emitter.
[237]920 *
[238]921 * @param[in,out]   document    A document object.
922 * @param[in]       tag         The sequence tag.
923 * @param[in]       style       The sequence style.
924 *
925 * @returns the node id or @c 0 on error.
[237]926 */
927
928YAML_DECLARE(int)
[238]929yaml_document_add_mapping(yaml_document_t *document,
930        yaml_char_t *tag, yaml_mapping_style_t style);
[237]931
932/**
[238]933 * Add an item to a SEQUENCE node.
[237]934 *
[238]935 * @param[in,out]   document    A document object.
936 * @param[in]       sequence    The sequence node id.
937 * @param[in]       item        The item node id.
938*
[237]939 * @returns @c 1 if the function succeeded, @c 0 on error.
940 */
941
942YAML_DECLARE(int)
[238]943yaml_document_append_sequence_item(yaml_document_t *document,
944        int sequence, int item);
[237]945
946/**
[238]947 * Add a pair of a key and a value to a MAPPING node.
[237]948 *
[238]949 * @param[in,out]   document    A document object.
950 * @param[in]       mapping     The mapping node id.
951 * @param[in]       key         The key node id.
952 * @param[in]       value       The value node id.
953*
954 * @returns @c 1 if the function succeeded, @c 0 on error.
[237]955 */
956
[238]957YAML_DECLARE(int)
958yaml_document_append_mapping_pair(yaml_document_t *document,
959        int mapping, int key, int value);
[237]960
[199]961/** @} */
962
963/**
[178]964 * @defgroup parser Parser Definitions
965 * @{
966 */
967
968/**
969 * The prototype of a read handler.
970 *
971 * The read handler is called when the parser needs to read more bytes from the
972 * source.  The handler should write not more than @a size bytes to the @a
973 * buffer.  The number of written bytes should be set to the @a length variable.
974 *
[220]975 * @param[in,out]   data        A pointer to an application data specified by
976 *                              yaml_parser_set_input().
977 * @param[out]      buffer      The buffer to write the data from the source.
978 * @param[in]       size        The size of the buffer.
979 * @param[out]      size_read   The actual number of bytes read from the source.
[178]980 *
981 * @returns On success, the handler should return @c 1.  If the handler failed,
982 * the returned value should be @c 0.  On EOF, the handler should set the
[211]983 * @a size_read to @c 0 and return @c 1.
[178]984 */
[180]985
986typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
[179]987        size_t *size_read);
[178]988
989/**
[184]990 * This structure holds information about a potential simple key.
991 */
992
[238]993typedef struct yaml_simple_key_s {
[208]994    /** Is a simple key possible? */
995    int possible;
996
[184]997    /** Is a simple key required? */
998    int required;
999
1000    /** The number of the token. */
1001    size_t token_number;
1002
1003    /** The position mark. */
1004    yaml_mark_t mark;
1005} yaml_simple_key_t;
1006
1007/**
[201]1008 * The states of the parser.
1009 */
[238]1010typedef enum yaml_parser_state_e {
[243]1011    /** Expect STREAM-START. */
[201]1012    YAML_PARSE_STREAM_START_STATE,
[243]1013    /** Expect the beginning of an implicit document. */
[201]1014    YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
[243]1015    /** Expect DOCUMENT-START. */
[201]1016    YAML_PARSE_DOCUMENT_START_STATE,
[243]1017    /** Expect the content of a document. */
[201]1018    YAML_PARSE_DOCUMENT_CONTENT_STATE,
[243]1019    /** Expect DOCUMENT-END. */
[201]1020    YAML_PARSE_DOCUMENT_END_STATE,
[243]1021    /** Expect a block node. */
[201]1022    YAML_PARSE_BLOCK_NODE_STATE,
[243]1023    /** Expect a block node or indentless sequence. */
[201]1024    YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
[243]1025    /** Expect a flow node. */
[201]1026    YAML_PARSE_FLOW_NODE_STATE,
[243]1027    /** Expect the first entry of a block sequence. */
[201]1028    YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
[243]1029    /** Expect an entry of a block sequence. */
[201]1030    YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
[243]1031    /** Expect an entry of an indentless sequence. */
[201]1032    YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
[243]1033    /** Expect the first key of a block mapping. */
[201]1034    YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
[243]1035    /** Expect a block mapping key. */
[201]1036    YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
[243]1037    /** Expect a block mapping value. */
[201]1038    YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
[243]1039    /** Expect the first entry of a flow sequence. */
[201]1040    YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
[243]1041    /** Expect an entry of a flow sequence. */
[201]1042    YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
[243]1043    /** Expect a key of an ordered mapping. */
[201]1044    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
[243]1045    /** Expect a value of an ordered mapping. */
[201]1046    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
[243]1047    /** Expect the and of an ordered mapping entry. */
[201]1048    YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
[243]1049    /** Expect the first key of a flow mapping. */
[201]1050    YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
[243]1051    /** Expect a key of a flow mapping. */
[201]1052    YAML_PARSE_FLOW_MAPPING_KEY_STATE,
[243]1053    /** Expect a value of a flow mapping. */
[201]1054    YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
[243]1055    /** Expect an empty value of a flow mapping. */
[208]1056    YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
[243]1057    /** Expect nothing. */
[208]1058    YAML_PARSE_END_STATE
[201]1059} yaml_parser_state_t;
1060
1061/**
[238]1062 * This structure holds aliases data.
1063 */
1064
1065typedef struct yaml_alias_data_s {
1066    /** The anchor. */
1067    yaml_char_t *anchor;
1068    /** The node id. */
1069    int index;
1070    /** The anchor mark. */
1071    yaml_mark_t mark;
1072} yaml_alias_data_t;
1073
1074/**
[178]1075 * The parser structure.
1076 *
1077 * All members are internal.  Manage the structure using the @c yaml_parser_
1078 * family of functions.
1079 */
1080
[238]1081typedef struct yaml_parser_s {
[178]1082
1083    /**
[179]1084     * @name Error handling
1085     * @{
1086     */
1087
[181]1088    /** Error type. */
[180]1089    yaml_error_type_t error;
[181]1090    /** Error description. */
1091    const char *problem;
1092    /** The byte about which the problem occured. */
1093    size_t problem_offset;
[182]1094    /** The problematic value (@c -1 is none). */
1095    int problem_value;
[185]1096    /** The problem position. */
1097    yaml_mark_t problem_mark;
1098    /** The error context. */
1099    const char *context;
1100    /** The context position. */
1101    yaml_mark_t context_mark;
1102
[179]1103    /**
1104     * @}
1105     */
1106
1107    /**
[178]1108     * @name Reader stuff
1109     * @{
1110     */
1111
[181]1112    /** Read handler. */
[179]1113    yaml_read_handler_t *read_handler;
[178]1114
1115    /** A pointer for passing to the read handler. */
[179]1116    void *read_handler_data;
[178]1117
[208]1118    /** Standard (string or file) input data. */
1119    union {
1120        /** String input data. */
1121        struct {
1122            /** The string start pointer. */
[237]1123            const unsigned char *start;
[208]1124            /** The string end pointer. */
[237]1125            const unsigned char *end;
[208]1126            /** The string current position. */
[237]1127            const unsigned char *current;
[208]1128        } string;
1129
1130        /** File input data. */
1131        FILE *file;
1132    } input;
1133
[178]1134    /** EOF flag */
1135    int eof;
1136
[208]1137    /** The working buffer. */
1138    struct {
[211]1139        /** The beginning of the buffer. */
[208]1140        yaml_char_t *start;
[211]1141        /** The end of the buffer. */
[208]1142        yaml_char_t *end;
[211]1143        /** The current position of the buffer. */
[208]1144        yaml_char_t *pointer;
[211]1145        /** The last filled position of the buffer. */
[208]1146        yaml_char_t *last;
1147    } buffer;
[178]1148
[208]1149    /* The number of unread characters in the buffer. */
[180]1150    size_t unread;
[179]1151
[208]1152    /** The raw buffer. */
1153    struct {
1154        /** The beginning of the buffer. */
1155        unsigned char *start;
1156        /** The end of the buffer. */
1157        unsigned char *end;
1158        /** The current position of the buffer. */
1159        unsigned char *pointer;
1160        /** The last filled position of the buffer. */
1161        unsigned char *last;
1162    } raw_buffer;
[178]1163
1164    /** The input encoding. */
1165    yaml_encoding_t encoding;
1166
[179]1167    /** The offset of the current position (in bytes). */
1168    size_t offset;
1169
[208]1170    /** The mark of the current position. */
1171    yaml_mark_t mark;
[179]1172
[178]1173    /**
1174     * @}
1175     */
1176
[184]1177    /**
1178     * @name Scanner stuff
1179     * @{
1180     */
1181
1182    /** Have we started to scan the input stream? */
1183    int stream_start_produced;
1184
1185    /** Have we reached the end of the input stream? */
1186    int stream_end_produced;
1187
1188    /** The number of unclosed '[' and '{' indicators. */
1189    int flow_level;
1190
[208]1191    /** The tokens queue. */
1192    struct {
1193        /** The beginning of the tokens queue. */
1194        yaml_token_t *start;
1195        /** The end of the tokens queue. */
1196        yaml_token_t *end;
1197        /** The head of the tokens queue. */
1198        yaml_token_t *head;
1199        /** The tail of the tokens queue. */
1200        yaml_token_t *tail;
1201    } tokens;
[184]1202
[208]1203    /** The number of tokens fetched from the queue. */
[184]1204    size_t tokens_parsed;
1205
[208]1206    /* Does the tokens queue contain a token ready for dequeueing. */
1207    int token_available;
[184]1208
[208]1209    /** The indentation levels stack. */
1210    struct {
1211        /** The beginning of the stack. */
1212        int *start;
1213        /** The end of the stack. */
1214        int *end;
1215        /** The top of the stack. */
1216        int *top;
1217    } indents;
[184]1218
1219    /** The current indentation level. */
1220    int indent;
1221
1222    /** May a simple key occur at the current position? */
1223    int simple_key_allowed;
1224
[208]1225    /** The stack of simple keys. */
1226    struct {
1227        /** The beginning of the stack. */
1228        yaml_simple_key_t *start;
1229        /** The end of the stack. */
1230        yaml_simple_key_t *end;
1231        /** The top of the stack. */
1232        yaml_simple_key_t *top;
1233    } simple_keys;
[184]1234
1235    /**
1236     * @}
1237     */
1238
[201]1239    /**
1240     * @name Parser stuff
1241     * @{
1242     */
1243
1244    /** The parser states stack. */
[208]1245    struct {
1246        /** The beginning of the stack. */
1247        yaml_parser_state_t *start;
1248        /** The end of the stack. */
1249        yaml_parser_state_t *end;
1250        /** The top of the stack. */
1251        yaml_parser_state_t *top;
1252    } states;
[201]1253
1254    /** The current parser state. */
1255    yaml_parser_state_t state;
1256
1257    /** The stack of marks. */
[208]1258    struct {
1259        /** The beginning of the stack. */
1260        yaml_mark_t *start;
1261        /** The end of the stack. */
1262        yaml_mark_t *end;
1263        /** The top of the stack. */
1264        yaml_mark_t *top;
1265    } marks;
[201]1266
1267    /** The list of TAG directives. */
[208]1268    struct {
1269        /** The beginning of the list. */
1270        yaml_tag_directive_t *start;
1271        /** The end of the list. */
1272        yaml_tag_directive_t *end;
1273        /** The top of the list. */
1274        yaml_tag_directive_t *top;
1275    } tag_directives;
[201]1276
1277    /**
1278     * @}
1279     */
1280
[238]1281    /**
1282     * @name Dumper stuff
1283     * @{
1284     */
1285
1286    /** The alias data. */
1287    struct {
1288        /** The beginning of the list. */
1289        yaml_alias_data_t *start;
1290        /** The end of the list. */
1291        yaml_alias_data_t *end;
1292        /** The top of the list. */
1293        yaml_alias_data_t *top;
1294    } aliases;
1295
1296    /** The currently parsed document. */
1297    yaml_document_t *document;
1298
1299    /**
1300     * @}
1301     */
1302
[162]1303} yaml_parser_t;
1304
[178]1305/**
[208]1306 * Initialize a parser.
[178]1307 *
1308 * This function creates a new parser object.  An application is responsible
[220]1309 * for destroying the object using the yaml_parser_delete() function.
[178]1310 *
[238]1311 * @param[out]      parser  An empty parser object.
[208]1312 *
[211]1313 * @returns @c 1 if the function succeeded, @c 0 on error.
[178]1314 */
1315
[208]1316YAML_DECLARE(int)
1317yaml_parser_initialize(yaml_parser_t *parser);
[178]1318
1319/**
1320 * Destroy a parser.
1321 *
[220]1322 * @param[in,out]   parser  A parser object.
[178]1323 */
1324
[183]1325YAML_DECLARE(void)
[178]1326yaml_parser_delete(yaml_parser_t *parser);
1327
[179]1328/**
1329 * Set a string input.
1330 *
1331 * Note that the @a input pointer must be valid while the @a parser object
1332 * exists.  The application is responsible for destroing @a input after
1333 * destroying the @a parser.
1334 *
[220]1335 * @param[in,out]   parser  A parser object.
1336 * @param[in]       input   A source data.
1337 * @param[in]       size    The length of the source data in bytes.
[179]1338 */
1339
[183]1340YAML_DECLARE(void)
[179]1341yaml_parser_set_input_string(yaml_parser_t *parser,
[237]1342        const unsigned char *input, size_t size);
[179]1343
1344/**
1345 * Set a file input.
1346 *
1347 * @a file should be a file object open for reading.  The application is
1348 * responsible for closing the @a file.
1349 *
[220]1350 * @param[in,out]   parser  A parser object.
1351 * @param[in]       file    An open file.
[179]1352 */
1353
[183]1354YAML_DECLARE(void)
[179]1355yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
1356
1357/**
1358 * Set a generic input handler.
1359 *
[220]1360 * @param[in,out]   parser  A parser object.
1361 * @param[in]       handler A read handler.
1362 * @param[in]       data    Any application data for passing to the read
1363 *                          handler.
[179]1364 */
1365
[183]1366YAML_DECLARE(void)
[179]1367yaml_parser_set_input(yaml_parser_t *parser,
1368        yaml_read_handler_t *handler, void *data);
1369
1370/**
1371 * Set the source encoding.
1372 *
[220]1373 * @param[in,out]   parser      A parser object.
1374 * @param[in]       encoding    The source encoding.
[179]1375 */
1376
[183]1377YAML_DECLARE(void)
[179]1378yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1379
[184]1380/**
[208]1381 * Scan the input stream and produce the next token.
[184]1382 *
[208]1383 * Call the function subsequently to produce a sequence of tokens corresponding
1384 * to the input stream.  The initial token has the type
1385 * @c YAML_STREAM_START_TOKEN while the ending token has the type
1386 * @c YAML_STREAM_END_TOKEN.
[184]1387 *
[208]1388 * An application is responsible for freeing any buffers associated with the
1389 * produced token object using the @c yaml_token_delete function.
[184]1390 *
[220]1391 * An application must not alternate the calls of yaml_parser_scan() with the
[238]1392 * calls of yaml_parser_parse() or yaml_parser_load(). Doing this will break
1393 * the parser.
[184]1394 *
[220]1395 * @param[in,out]   parser      A parser object.
1396 * @param[out]      token       An empty token object.
[184]1397 *
[208]1398 * @returns @c 1 if the function succeeded, @c 0 on error.
[184]1399 */
1400
[208]1401YAML_DECLARE(int)
1402yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
[184]1403
[201]1404/**
[208]1405 * Parse the input stream and produce the next parsing event.
[201]1406 *
[208]1407 * Call the function subsequently to produce a sequence of events corresponding
1408 * to the input stream.  The initial event has the type
1409 * @c YAML_STREAM_START_EVENT while the ending event has the type
1410 * @c YAML_STREAM_END_EVENT.
[201]1411 *
[208]1412 * An application is responsible for freeing any buffers associated with the
[220]1413 * produced event object using the yaml_event_delete() function.
[201]1414 *
[238]1415 * An application must not alternate the calls of yaml_parser_parse() with the
1416 * calls of yaml_parser_scan() or yaml_parser_load(). Doing this will break the
1417 * parser.
[201]1418 *
[220]1419 * @param[in,out]   parser      A parser object.
1420 * @param[out]      event       An empty event object.
[201]1421 *
[208]1422 * @returns @c 1 if the function succeeded, @c 0 on error.
[201]1423 */
1424
[208]1425YAML_DECLARE(int)
1426yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
[201]1427
[238]1428/**
1429 * Parse the input stream and produce the next YAML document.
1430 *
1431 * Call this function subsequently to produce a sequence of documents
1432 * constituting the input stream.
1433 *
1434 * If the produced document has no root node, it means that the document
1435 * end has been reached.
1436 *
1437 * An application is responsible for freeing any data associated with the
1438 * produced document object using the yaml_document_delete() function.
1439 *
1440 * An application must not alternate the calls of yaml_parser_load() with the
1441 * calls of yaml_parser_scan() or yaml_parser_parse(). Doing this will break
1442 * the parser.
1443 *
1444 * @param[in,out]   parser      A parser object.
1445 * @param[out]      document    An empty document object.
1446 *
1447 * @return @c 1 if the function succeeded, @c 0 on error.
1448 */
1449
1450YAML_DECLARE(int)
1451yaml_parser_load(yaml_parser_t *parser, yaml_document_t *document);
1452
[178]1453/** @} */
1454
[211]1455/**
1456 * @defgroup emitter Emitter Definitions
1457 * @{
1458 */
1459
1460/**
1461 * The prototype of a write handler.
1462 *
1463 * The write handler is called when the emitter needs to flush the accumulated
1464 * characters to the output.  The handler should write @a size bytes of the
1465 * @a buffer to the output.
1466 *
[220]1467 * @param[in,out]   data        A pointer to an application data specified by
1468 *                              yaml_emitter_set_output().
1469 * @param[in]       buffer      The buffer with bytes to be written.
1470 * @param[in]       size        The size of the buffer.
[211]1471 *
1472 * @returns On success, the handler should return @c 1.  If the handler failed,
1473 * the returned value should be @c 0.
1474 */
1475
1476typedef int yaml_write_handler_t(void *data, unsigned char *buffer, size_t size);
1477
1478/** The emitter states. */
[238]1479typedef enum yaml_emitter_state_e {
[243]1480    /** Expect STREAM-START. */
[211]1481    YAML_EMIT_STREAM_START_STATE,
[243]1482    /** Expect the first DOCUMENT-START or STREAM-END. */
[211]1483    YAML_EMIT_FIRST_DOCUMENT_START_STATE,
[243]1484    /** Expect DOCUMENT-START or STREAM-END. */
[211]1485    YAML_EMIT_DOCUMENT_START_STATE,
[243]1486    /** Expect the content of a document. */
[211]1487    YAML_EMIT_DOCUMENT_CONTENT_STATE,
[243]1488    /** Expect DOCUMENT-END. */
[211]1489    YAML_EMIT_DOCUMENT_END_STATE,
[243]1490    /** Expect the first item of a flow sequence. */
[211]1491    YAML_EMIT_FLOW_SEQUENCE_FIRST_ITEM_STATE,
[243]1492    /** Expect an item of a flow sequence. */
[211]1493    YAML_EMIT_FLOW_SEQUENCE_ITEM_STATE,
[243]1494    /** Expect the first key of a flow mapping. */
[211]1495    YAML_EMIT_FLOW_MAPPING_FIRST_KEY_STATE,
[243]1496    /** Expect a key of a flow mapping. */
[211]1497    YAML_EMIT_FLOW_MAPPING_KEY_STATE,
[243]1498    /** Expect a value for a simple key of a flow mapping. */
[211]1499    YAML_EMIT_FLOW_MAPPING_SIMPLE_VALUE_STATE,
[243]1500    /** Expect a value of a flow mapping. */
[211]1501    YAML_EMIT_FLOW_MAPPING_VALUE_STATE,
[243]1502    /** Expect the first item of a block sequence. */
[211]1503    YAML_EMIT_BLOCK_SEQUENCE_FIRST_ITEM_STATE,
[243]1504    /** Expect an item of a block sequence. */
[211]1505    YAML_EMIT_BLOCK_SEQUENCE_ITEM_STATE,
[243]1506    /** Expect the first key of a block mapping. */
[211]1507    YAML_EMIT_BLOCK_MAPPING_FIRST_KEY_STATE,
[243]1508    /** Expect the key of a block mapping. */
[211]1509    YAML_EMIT_BLOCK_MAPPING_KEY_STATE,
[243]1510    /** Expect a value for a simple key of a block mapping. */
[211]1511    YAML_EMIT_BLOCK_MAPPING_SIMPLE_VALUE_STATE,
[243]1512    /** Expect a value of a block mapping. */
[213]1513    YAML_EMIT_BLOCK_MAPPING_VALUE_STATE,
[243]1514    /** Expect nothing. */
[213]1515    YAML_EMIT_END_STATE
[211]1516} yaml_emitter_state_t;
1517
1518/**
1519 * The emitter structure.
1520 *
1521 * All members are internal.  Manage the structure using the @c yaml_emitter_
1522 * family of functions.
1523 */
1524
[238]1525typedef struct yaml_emitter_s {
[211]1526
1527    /**
1528     * @name Error handling
1529     * @{
1530     */
1531
1532    /** Error type. */
1533    yaml_error_type_t error;
1534    /** Error description. */
1535    const char *problem;
1536
1537    /**
1538     * @}
1539     */
1540
1541    /**
1542     * @name Writer stuff
1543     * @{
1544     */
1545
1546    /** Write handler. */
1547    yaml_write_handler_t *write_handler;
1548
1549    /** A pointer for passing to the white handler. */
1550    void *write_handler_data;
1551
1552    /** Standard (string or file) output data. */
1553    union {
1554        /** String output data. */
1555        struct {
1556            /** The buffer pointer. */
1557            unsigned char *buffer;
1558            /** The buffer size. */
1559            size_t size;
1560            /** The number of written bytes. */
1561            size_t *size_written;
1562        } string;
1563
1564        /** File output data. */
1565        FILE *file;
1566    } output;
1567
1568    /** The working buffer. */
1569    struct {
1570        /** The beginning of the buffer. */
1571        yaml_char_t *start;
1572        /** The end of the buffer. */
1573        yaml_char_t *end;
1574        /** The current position of the buffer. */
1575        yaml_char_t *pointer;
1576        /** The last filled position of the buffer. */
1577        yaml_char_t *last;
1578    } buffer;
1579
1580    /** The raw buffer. */
1581    struct {
1582        /** The beginning of the buffer. */
1583        unsigned char *start;
1584        /** The end of the buffer. */
1585        unsigned char *end;
1586        /** The current position of the buffer. */
1587        unsigned char *pointer;
1588        /** The last filled position of the buffer. */
1589        unsigned char *last;
1590    } raw_buffer;
1591
1592    /** The stream encoding. */
1593    yaml_encoding_t encoding;
1594
1595    /**
1596     * @}
1597     */
1598
1599    /**
1600     * @name Emitter stuff
1601     * @{
1602     */
1603
1604    /** If the output is in the canonical style? */
1605    int canonical;
1606    /** The number of indentation spaces. */
1607    int best_indent;
1608    /** The preferred width of the output lines. */
1609    int best_width;
1610    /** Allow unescaped non-ASCII characters? */
1611    int unicode;
1612    /** The preferred line break. */
1613    yaml_break_t line_break;
1614
1615    /** The stack of states. */
1616    struct {
1617        /** The beginning of the stack. */
1618        yaml_emitter_state_t *start;
1619        /** The end of the stack. */
1620        yaml_emitter_state_t *end;
1621        /** The top of the stack. */
1622        yaml_emitter_state_t *top;
1623    } states;
1624
1625    /** The current emitter state. */
1626    yaml_emitter_state_t state;
1627
1628    /** The event queue. */
1629    struct {
1630        /** The beginning of the event queue. */
1631        yaml_event_t *start;
1632        /** The end of the event queue. */
1633        yaml_event_t *end;
1634        /** The head of the event queue. */
1635        yaml_event_t *head;
1636        /** The tail of the event queue. */
1637        yaml_event_t *tail;
1638    } events;
1639
1640    /** The stack of indentation levels. */
1641    struct {
1642        /** The beginning of the stack. */
1643        int *start;
1644        /** The end of the stack. */
1645        int *end;
1646        /** The top of the stack. */
1647        int *top;
1648    } indents;
1649
1650    /** The list of tag directives. */
1651    struct {
1652        /** The beginning of the list. */
1653        yaml_tag_directive_t *start;
1654        /** The end of the list. */
1655        yaml_tag_directive_t *end;
1656        /** The top of the list. */
1657        yaml_tag_directive_t *top;
1658    } tag_directives;
1659
1660    /** The current indentation level. */
1661    int indent;
1662
1663    /** The current flow level. */
1664    int flow_level;
1665
1666    /** Is it the document root context? */
1667    int root_context;
1668    /** Is it a sequence context? */
1669    int sequence_context;
1670    /** Is it a mapping context? */
1671    int mapping_context;
1672    /** Is it a simple mapping key context? */
1673    int simple_key_context;
1674
1675    /** The current line. */
1676    int line;
1677    /** The current column. */
1678    int column;
1679    /** If the last character was a whitespace? */
1680    int whitespace;
1681    /** If the last character was an indentation character (' ', '-', '?', ':')? */
1682    int indention;
[315]1683    /** If an explicit document end is required? */
1684    int open_ended;
[211]1685
[214]1686    /** Anchor analysis. */
1687    struct {
1688        /** The anchor value. */
1689        yaml_char_t *anchor;
1690        /** The anchor length. */
1691        size_t anchor_length;
1692        /** Is it an alias? */
1693        int alias;
1694    } anchor_data;
1695
1696    /** Tag analysis. */
1697    struct {
1698        /** The tag handle. */
1699        yaml_char_t *handle;
1700        /** The tag handle length. */
1701        size_t handle_length;
1702        /** The tag suffix. */
1703        yaml_char_t *suffix;
1704        /** The tag suffix length. */
1705        size_t suffix_length;
1706    } tag_data;
1707
1708    /** Scalar analysis. */
1709    struct {
1710        /** The scalar value. */
1711        yaml_char_t *value;
1712        /** The scalar length. */
1713        size_t length;
1714        /** Does the scalar contain line breaks? */
1715        int multiline;
1716        /** Can the scalar be expessed in the flow plain style? */
1717        int flow_plain_allowed;
1718        /** Can the scalar be expressed in the block plain style? */
1719        int block_plain_allowed;
1720        /** Can the scalar be expressed in the single quoted style? */
1721        int single_quoted_allowed;
1722        /** Can the scalar be expressed in the literal or folded styles? */
1723        int block_allowed;
1724        /** The output style. */
1725        yaml_scalar_style_t style;
1726    } scalar_data;
1727
[211]1728    /**
1729     * @}
1730     */
1731
[238]1732    /**
1733     * @name Dumper stuff
1734     * @{
1735     */
1736
1737    /** If the stream was already opened? */
1738    int opened;
1739    /** If the stream was already closed? */
1740    int closed;
1741
1742    /** The information associated with the document nodes. */
1743    struct {
1744        /** The number of references. */
1745        int references;
1746        /** The anchor id. */
1747        int anchor;
1748        /** If the node has been emitted? */
1749        int serialized;
1750    } *anchors;
1751
1752    /** The last assigned anchor id. */
1753    int last_anchor_id;
1754
1755    /** The currently emitted document. */
1756    yaml_document_t *document;
1757
1758    /**
1759     * @}
1760     */
1761
[162]1762} yaml_emitter_t;
1763
[211]1764/**
1765 * Initialize an emitter.
1766 *
1767 * This function creates a new emitter object.  An application is responsible
[220]1768 * for destroying the object using the yaml_emitter_delete() function.
[211]1769 *
[220]1770 * @param[out]      emitter     An empty parser object.
[211]1771 *
1772 * @returns @c 1 if the function succeeded, @c 0 on error.
1773 */
1774
[208]1775YAML_DECLARE(int)
[211]1776yaml_emitter_initialize(yaml_emitter_t *emitter);
1777
1778/**
1779 * Destroy an emitter.
1780 *
[220]1781 * @param[in,out]   emitter     An emitter object.
[211]1782 */
1783
1784YAML_DECLARE(void)
1785yaml_emitter_delete(yaml_emitter_t *emitter);
1786
1787/**
1788 * Set a string output.
1789 *
1790 * The emitter will write the output characters to the @a output buffer of the
1791 * size @a size.  The emitter will set @a size_written to the number of written
1792 * bytes.  If the buffer is smaller than required, the emitter produces the
1793 * YAML_WRITE_ERROR error.
1794 *
[220]1795 * @param[in,out]   emitter         An emitter object.
1796 * @param[in]       output          An output buffer.
1797 * @param[in]       size            The buffer size.
1798 * @param[in]       size_written    The pointer to save the number of written
1799 *                                  bytes.
[211]1800 */
1801
1802YAML_DECLARE(void)
1803yaml_emitter_set_output_string(yaml_emitter_t *emitter,
1804        unsigned char *output, size_t size, size_t *size_written);
1805
1806/**
1807 * Set a file output.
1808 *
1809 * @a file should be a file object open for writing.  The application is
1810 * responsible for closing the @a file.
1811 *
[220]1812 * @param[in,out]   emitter     An emitter object.
1813 * @param[in]       file        An open file.
[211]1814 */
1815
1816YAML_DECLARE(void)
1817yaml_emitter_set_output_file(yaml_emitter_t *emitter, FILE *file);
1818
1819/**
1820 * Set a generic output handler.
1821 *
[220]1822 * @param[in,out]   emitter     An emitter object.
1823 * @param[in]       handler     A write handler.
1824 * @param[in]       data        Any application data for passing to the write
1825 *                              handler.
[211]1826 */
1827
1828YAML_DECLARE(void)
1829yaml_emitter_set_output(yaml_emitter_t *emitter,
1830        yaml_write_handler_t *handler, void *data);
1831
1832/**
1833 * Set the output encoding.
1834 *
[220]1835 * @param[in,out]   emitter     An emitter object.
1836 * @param[in]       encoding    The output encoding.
[211]1837 */
1838
1839YAML_DECLARE(void)
1840yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1841
1842/**
1843 * Set if the output should be in the "canonical" format as in the YAML
1844 * specification.
1845 *
[220]1846 * @param[in,out]   emitter     An emitter object.
1847 * @param[in]       canonical   If the output is canonical.
[211]1848 */
1849
1850YAML_DECLARE(void)
1851yaml_emitter_set_canonical(yaml_emitter_t *emitter, int canonical);
1852
1853/**
1854 * Set the intendation increment.
1855 *
[220]1856 * @param[in,out]   emitter     An emitter object.
1857 * @param[in]       indent      The indentation increment (1 < . < 10).
[211]1858 */
1859
1860YAML_DECLARE(void)
1861yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1862
1863/**
[212]1864 * Set the preferred line width. @c -1 means unlimited.
[211]1865 *
[220]1866 * @param[in,out]   emitter     An emitter object.
1867 * @param[in]       width       The preferred line width.
[211]1868 */
1869
1870YAML_DECLARE(void)
1871yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1872
1873/**
1874 * Set if unescaped non-ASCII characters are allowed.
1875 *
[220]1876 * @param[in,out]   emitter     An emitter object.
1877 * @param[in]       unicode     If unescaped Unicode characters are allowed.
[211]1878 */
1879
1880YAML_DECLARE(void)
1881yaml_emitter_set_unicode(yaml_emitter_t *emitter, int unicode);
1882
1883/**
1884 * Set the preferred line break.
1885 *
[220]1886 * @param[in,out]   emitter     An emitter object.
1887 * @param[in]       line_break  The preferred line break.
[211]1888 */
1889
1890YAML_DECLARE(void)
1891yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1892
1893/**
1894 * Emit an event.
1895 *
[220]1896 * The event object may be generated using the yaml_parser_parse() function.
[213]1897 * The emitter takes the responsibility for the event object and destroys its
1898 * content after it is emitted. The event object is destroyed even if the
1899 * function fails.
[211]1900 *
[220]1901 * @param[in,out]   emitter     An emitter object.
1902 * @param[in,out]   event       An event object.
[211]1903 *
1904 * @returns @c 1 if the function succeeded, @c 0 on error.
1905 */
1906
1907YAML_DECLARE(int)
[208]1908yaml_emitter_emit(yaml_emitter_t *emitter, yaml_event_t *event);
[179]1909
[243]1910/**
[238]1911 * Start a YAML stream.
1912 *
1913 * This function should be used before yaml_emitter_dump() is called.
1914 *
1915 * @param[in,out]   emitter     An emitter object.
1916 *
1917 * @returns @c 1 if the function succeeded, @c 0 on error.
1918 */
1919
1920YAML_DECLARE(int)
1921yaml_emitter_open(yaml_emitter_t *emitter);
1922
[243]1923/**
[238]1924 * Finish a YAML stream.
1925 *
1926 * This function should be used after yaml_emitter_dump() is called.
1927 *
1928 * @param[in,out]   emitter     An emitter object.
1929 *
1930 * @returns @c 1 if the function succeeded, @c 0 on error.
1931 */
1932
1933YAML_DECLARE(int)
1934yaml_emitter_close(yaml_emitter_t *emitter);
1935
[243]1936/**
[238]1937 * Emit a YAML document.
1938 *
1939 * The documen object may be generated using the yaml_parser_load() function
1940 * or the yaml_document_initialize() function.  The emitter takes the
1941 * responsibility for the document object and destoys its content after
1942 * it is emitted. The document object is destroyedeven if the function fails.
1943 *
1944 * @param[in,out]   emitter     An emitter object.
1945 * @param[in,out]   document    A document object.
1946 *
1947 * @returns @c 1 if the function succeeded, @c 0 on error.
1948 */
1949
1950YAML_DECLARE(int)
1951yaml_emitter_dump(yaml_emitter_t *emitter, yaml_document_t *document);
1952
[211]1953/**
1954 * Flush the accumulated characters to the output.
1955 *
[220]1956 * @param[in,out]   emitter     An emitter object.
[211]1957 *
1958 * @returns @c 1 if the function succeeded, @c 0 on error.
1959 */
1960
1961YAML_DECLARE(int)
1962yaml_emitter_flush(yaml_emitter_t *emitter);
1963
1964/** @} */
1965
[162]1966#ifdef __cplusplus
1967}
1968#endif
1969
[169]1970#endif /* #ifndef YAML_H */
[162]1971
Note: See TracBrowser for help on using the repository browser.