codekingpro/portable-devtools
114k
1/**2 * @file yaml.h3 * @brief Public interface for libyaml.4 * 5 * Include the header file with the code:6 * @code7 * #include <yaml.h>8 * @endcode9 */10 11#ifndef YAML_H12#define YAML_H13 14#ifdef __cplusplus15extern "C" {16#endif17 18#include <stdlib.h>19#include <stdio.h>20#include <string.h>21 22/**23 * @defgroup export Export Definitions24 * @{25 */26 27/** The public API declaration. */28 29#if defined(__MINGW32__)30# define YAML_DECLARE(type) type31#elif defined(_WIN32)32# if defined(YAML_DECLARE_STATIC)33# define YAML_DECLARE(type) type34# elif defined(YAML_DECLARE_EXPORT)35# define YAML_DECLARE(type) __declspec(dllexport) type36# else37# define YAML_DECLARE(type) __declspec(dllimport) type38# endif39#else40# define YAML_DECLARE(type) type41#endif42 43/** @} */44 45/**46 * @defgroup version Version Information47 * @{48 */49 50/**51 * Get the library version as a string.52 *53 * @returns The function returns the pointer to a static string of the form54 * @c "X.Y.Z", where @c X is the major version number, @c Y is a minor version55 * number, and @c Z is the patch version number.56 */57 58YAML_DECLARE(const char *)59yaml_get_version_string(void);60 61/**62 * Get the library version numbers.63 *64 * @param[out] major Major version number.65 * @param[out] minor Minor version number.66 * @param[out] patch Patch version number.67 */68 69YAML_DECLARE(void)70yaml_get_version(int *major, int *minor, int *patch);71 72/** @} */73 74/**75 * @defgroup basic Basic Types76 * @{77 */78 79/** The character type (UTF-8 octet). */80typedef unsigned char yaml_char_t;81 82/** The version directive data. */83typedef struct yaml_version_directive_s {84 /** The major version number. */85 int major;86 /** The minor version number. */87 int minor;88} yaml_version_directive_t;89 90/** The tag directive data. */91typedef struct yaml_tag_directive_s {92 /** The tag handle. */93 yaml_char_t *handle;94 /** The tag prefix. */95 yaml_char_t *prefix;96} yaml_tag_directive_t;97 98/** The stream encoding. */99typedef enum yaml_encoding_e {100 /** Let the parser choose the encoding. */101 YAML_ANY_ENCODING,102 /** The default UTF-8 encoding. */103 YAML_UTF8_ENCODING,104 /** The UTF-16-LE encoding with BOM. */105 YAML_UTF16LE_ENCODING,106 /** The UTF-16-BE encoding with BOM. */107 YAML_UTF16BE_ENCODING108} yaml_encoding_t;109 110/** Line break types. */111 112typedef enum yaml_break_e {113 /** Let the parser choose the break type. */114 YAML_ANY_BREAK,115 /** Use CR for line breaks (Mac style). */116 YAML_CR_BREAK,117 /** Use LN for line breaks (Unix style). */118 YAML_LN_BREAK,119 /** Use CR LN for line breaks (DOS style). */120 YAML_CRLN_BREAK121} yaml_break_t;122 123/** Many bad things could happen with the parser and emitter. */124typedef enum yaml_error_type_e {125 /** No error is produced. */126 YAML_NO_ERROR,127 128 /** Cannot allocate or reallocate a block of memory. */129 YAML_MEMORY_ERROR,130 131 /** Cannot read or decode the input stream. */132 YAML_READER_ERROR,133 /** Cannot scan the input stream. */134 YAML_SCANNER_ERROR,135 /** Cannot parse the input stream. */136 YAML_PARSER_ERROR,137 /** Cannot compose a YAML document. */138 YAML_COMPOSER_ERROR,139 140 /** Cannot write to the output stream. */141 YAML_WRITER_ERROR,142 /** Cannot emit a YAML stream. */143 YAML_EMITTER_ERROR144} yaml_error_type_t;145 146/** The pointer position. */147typedef struct yaml_mark_s {148 /** The position index. */149 size_t index;150 151 /** The position line. */152 size_t line;153 154 /** The position column. */155 size_t column;156} yaml_mark_t;157 158/** @} */159 160/**161 * @defgroup styles Node Styles162 * @{163 */164 165/** Scalar styles. */166typedef enum yaml_scalar_style_e {167 /** Let the emitter choose the style. */168 YAML_ANY_SCALAR_STYLE,169 170 /** The plain scalar style. */171 YAML_PLAIN_SCALAR_STYLE,172 173 /** The single-quoted scalar style. */174 YAML_SINGLE_QUOTED_SCALAR_STYLE,175 /** The double-quoted scalar style. */176 YAML_DOUBLE_QUOTED_SCALAR_STYLE,177 178 /** The literal scalar style. */179 YAML_LITERAL_SCALAR_STYLE,180 /** The folded scalar style. */181 YAML_FOLDED_SCALAR_STYLE182} yaml_scalar_style_t;183 184/** Sequence styles. */185typedef enum yaml_sequence_style_e {186 /** Let the emitter choose the style. */187 YAML_ANY_SEQUENCE_STYLE,188 189 /** The block sequence style. */190 YAML_BLOCK_SEQUENCE_STYLE,191 /** The flow sequence style. */192 YAML_FLOW_SEQUENCE_STYLE193} yaml_sequence_style_t;194 195/** Mapping styles. */196typedef enum yaml_mapping_style_e {197 /** Let the emitter choose the style. */198 YAML_ANY_MAPPING_STYLE,199 200 /** The block mapping style. */201 YAML_BLOCK_MAPPING_STYLE,202 /** The flow mapping style. */203 YAML_FLOW_MAPPING_STYLE204/* YAML_FLOW_SET_MAPPING_STYLE */205} yaml_mapping_style_t;206 207/** @} */208 209/**210 * @defgroup tokens Tokens211 * @{212 */213 214/** Token types. */215typedef enum yaml_token_type_e {216 /** An empty token. */217 YAML_NO_TOKEN,218 219 /** A STREAM-START token. */220 YAML_STREAM_START_TOKEN,221 /** A STREAM-END token. */222 YAML_STREAM_END_TOKEN,223 224 /** A VERSION-DIRECTIVE token. */225 YAML_VERSION_DIRECTIVE_TOKEN,226 /** A TAG-DIRECTIVE token. */227 YAML_TAG_DIRECTIVE_TOKEN,228 /** A DOCUMENT-START token. */229 YAML_DOCUMENT_START_TOKEN,230 /** A DOCUMENT-END token. */231 YAML_DOCUMENT_END_TOKEN,232 233 /** A BLOCK-SEQUENCE-START token. */234 YAML_BLOCK_SEQUENCE_START_TOKEN,235 /** A BLOCK-MAPPING-START token. */236 YAML_BLOCK_MAPPING_START_TOKEN,237 /** A BLOCK-END token. */238 YAML_BLOCK_END_TOKEN,239 240 /** A FLOW-SEQUENCE-START token. */241 YAML_FLOW_SEQUENCE_START_TOKEN,242 /** A FLOW-SEQUENCE-END token. */243 YAML_FLOW_SEQUENCE_END_TOKEN,244 /** A FLOW-MAPPING-START token. */245 YAML_FLOW_MAPPING_START_TOKEN,246 /** A FLOW-MAPPING-END token. */247 YAML_FLOW_MAPPING_END_TOKEN,248 249 /** A BLOCK-ENTRY token. */250 YAML_BLOCK_ENTRY_TOKEN,251 /** A FLOW-ENTRY token. */252 YAML_FLOW_ENTRY_TOKEN,253 /** A KEY token. */254 YAML_KEY_TOKEN,255 /** A VALUE token. */256 YAML_VALUE_TOKEN,257 258 /** An ALIAS token. */259 YAML_ALIAS_TOKEN,260 /** An ANCHOR token. */261 YAML_ANCHOR_TOKEN,262 /** A TAG token. */263 YAML_TAG_TOKEN,264 /** A SCALAR token. */265 YAML_SCALAR_TOKEN266} yaml_token_type_t;267 268/** The token structure. */269typedef struct yaml_token_s {270 271 /** The token type. */272 yaml_token_type_t type;273 274 /** The token data. */275 union {276 277 /** The stream start (for @c YAML_STREAM_START_TOKEN). */278 struct {279 /** The stream encoding. */280 yaml_encoding_t encoding;281 } stream_start;282 283 /** The alias (for @c YAML_ALIAS_TOKEN). */284 struct {285 /** The alias value. */286 yaml_char_t *value;287 } alias;288 289 /** The anchor (for @c YAML_ANCHOR_TOKEN). */290 struct {291 /** The anchor value. */292 yaml_char_t *value;293 } anchor;294 295 /** The tag (for @c YAML_TAG_TOKEN). */296 struct {297 /** The tag handle. */298 yaml_char_t *handle;299 /** The tag suffix. */300 yaml_char_t *suffix;301 } tag;302 303 /** The scalar value (for @c YAML_SCALAR_TOKEN). */304 struct {305 /** The scalar value. */306 yaml_char_t *value;307 /** The length of the scalar value. */308 size_t length;309 /** The scalar style. */310 yaml_scalar_style_t style;311 } scalar;312 313 /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */314 struct {315 /** The major version number. */316 int major;317 /** The minor version number. */318 int minor;319 } version_directive;320 321 /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */322 struct {323 /** The tag handle. */324 yaml_char_t *handle;325 /** The tag prefix. */326 yaml_char_t *prefix;327 } tag_directive;328 329 } data;330 331 /** The beginning of the token. */332 yaml_mark_t start_mark;333 /** The end of the token. */334 yaml_mark_t end_mark;335 336} yaml_token_t;337 338/**339 * Free any memory allocated for a token object.340 *341 * @param[in,out] token A token object.342 */343 344YAML_DECLARE(void)345yaml_token_delete(yaml_token_t *token);346 347/** @} */348 349/**350 * @defgroup events Events351 * @{352 */353 354/** Event types. */355typedef enum yaml_event_type_e {356 /** An empty event. */357 YAML_NO_EVENT,358 359 /** A STREAM-START event. */360 YAML_STREAM_START_EVENT,361 /** A STREAM-END event. */362 YAML_STREAM_END_EVENT,363 364 /** A DOCUMENT-START event. */365 YAML_DOCUMENT_START_EVENT,366 /** A DOCUMENT-END event. */367 YAML_DOCUMENT_END_EVENT,368 369 /** An ALIAS event. */370 YAML_ALIAS_EVENT,371 /** A SCALAR event. */372 YAML_SCALAR_EVENT,373 374 /** A SEQUENCE-START event. */375 YAML_SEQUENCE_START_EVENT,376 /** A SEQUENCE-END event. */377 YAML_SEQUENCE_END_EVENT,378 379 /** A MAPPING-START event. */380 YAML_MAPPING_START_EVENT,381 /** A MAPPING-END event. */382 YAML_MAPPING_END_EVENT383} yaml_event_type_t;384 385/** The event structure. */386typedef struct yaml_event_s {387 388 /** The event type. */389 yaml_event_type_t type;390 391 /** The event data. */392 union {393 394 /** The stream parameters (for @c YAML_STREAM_START_EVENT). */395 struct {396 /** The document encoding. */397 yaml_encoding_t encoding;398 } stream_start;399 400 /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */401 struct {402 /** The version directive. */403 yaml_version_directive_t *version_directive;404 405 /** The list of tag directives. */406 struct {407 /** The beginning of the tag directives list. */408 yaml_tag_directive_t *start;409 /** The end of the tag directives list. */410 yaml_tag_directive_t *end;411 } tag_directives;412 413 /** Is the document indicator implicit? */414 int implicit;415 } document_start;416 417 /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */418 struct {419 /** Is the document end indicator implicit? */420 int implicit;421 } document_end;422 423 /** The alias parameters (for @c YAML_ALIAS_EVENT). */424 struct {425 /** The anchor. */426 yaml_char_t *anchor;427 } alias;428 429 /** The scalar parameters (for @c YAML_SCALAR_EVENT). */430 struct {431 /** The anchor. */432 yaml_char_t *anchor;433 /** The tag. */434 yaml_char_t *tag;435 /** The scalar value. */436 yaml_char_t *value;437 /** The length of the scalar value. */438 size_t length;439 /** Is the tag optional for the plain style? */440 int plain_implicit;441 /** Is the tag optional for any non-plain style? */442 int quoted_implicit;443 /** The scalar style. */444 yaml_scalar_style_t style;445 } scalar;446 447 /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */448 struct {449 /** The anchor. */450 yaml_char_t *anchor;451 /** The tag. */452 yaml_char_t *tag;453 /** Is the tag optional? */454 int implicit;455 /** The sequence style. */456 yaml_sequence_style_t style;457 } sequence_start;458 459 /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */460 struct {461 /** The anchor. */462 yaml_char_t *anchor;463 /** The tag. */464 yaml_char_t *tag;465 /** Is the tag optional? */466 int implicit;467 /** The mapping style. */468 yaml_mapping_style_t style;469 } mapping_start;470 471 } data;472 473 /** The beginning of the event. */474 yaml_mark_t start_mark;475 /** The end of the event. */476 yaml_mark_t end_mark;477 478} yaml_event_t;479 480/**481 * Create the STREAM-START event.482 *483 * @param[out] event An empty event object.484 * @param[in] encoding The stream encoding.485 *486 * @returns @c 1 if the function succeeded, @c 0 on error.487 */488 489YAML_DECLARE(int)490yaml_stream_start_event_initialize(yaml_event_t *event,491 yaml_encoding_t encoding);492 493/**494 * Create the STREAM-END event.495 *496 * @param[out] event An empty event object.497 *498 * @returns @c 1 if the function succeeded, @c 0 on error.499 */500 501YAML_DECLARE(int)502yaml_stream_end_event_initialize(yaml_event_t *event);503 504/**505 * Create the DOCUMENT-START event.506 *507 * The @a implicit argument is considered as a stylistic parameter and may be508 * ignored by the emitter.509 *510 * @param[out] event An empty event object.511 * @param[in] version_directive The %YAML directive value or512 * @c NULL.513 * @param[in] tag_directives_start The beginning of the %TAG514 * directives list.515 * @param[in] tag_directives_end The end of the %TAG directives516 * list.517 * @param[in] implicit If the document start indicator is518 * implicit.519 *520 * @returns @c 1 if the function succeeded, @c 0 on error.521 */522 523YAML_DECLARE(int)524yaml_document_start_event_initialize(yaml_event_t *event,525 yaml_version_directive_t *version_directive,526 yaml_tag_directive_t *tag_directives_start,527 yaml_tag_directive_t *tag_directives_end,528 int implicit);529 530/**531 * Create the DOCUMENT-END event.532 *533 * The @a implicit argument is considered as a stylistic parameter and may be534 * ignored by the emitter.535 *536 * @param[out] event An empty event object.537 * @param[in] implicit If the document end indicator is implicit.538 *539 * @returns @c 1 if the function succeeded, @c 0 on error.540 */541 542YAML_DECLARE(int)543yaml_document_end_event_initialize(yaml_event_t *event, int implicit);544 545/**546 * Create an ALIAS event.547 *548 * @param[out] event An empty event object.549 * @param[in] anchor The anchor value.550 *551 * @returns @c 1 if the function succeeded, @c 0 on error.552 */553 554YAML_DECLARE(int)555yaml_alias_event_initialize(yaml_event_t *event, const yaml_char_t *anchor);556 557/**558 * Create a SCALAR event.559 *560 * The @a style argument may be ignored by the emitter.561 *562 * Either the @a tag attribute or one of the @a plain_implicit and563 * @a quoted_implicit flags must be set.564 *565 * @param[out] event An empty event object.566 * @param[in] anchor The scalar anchor or @c NULL.567 * @param[in] tag The scalar tag or @c NULL.568 * @param[in] value The scalar value.569 * @param[in] length The length of the scalar value.570 * @param[in] plain_implicit If the tag may be omitted for the plain571 * style.572 * @param[in] quoted_implicit If the tag may be omitted for any573 * non-plain style.574 * @param[in] style The scalar style.575 *576 * @returns @c 1 if the function succeeded, @c 0 on error.577 */578 579YAML_DECLARE(int)580yaml_scalar_event_initialize(yaml_event_t *event,581 const yaml_char_t *anchor, const yaml_char_t *tag,582 const yaml_char_t *value, int length,583 int plain_implicit, int quoted_implicit,584 yaml_scalar_style_t style);585 586/**587 * Create a SEQUENCE-START event.588 *589 * The @a style argument may be ignored by the emitter.590 *591 * Either the @a tag attribute or the @a implicit flag must be set.592 *593 * @param[out] event An empty event object.594 * @param[in] anchor The sequence anchor or @c NULL.595 * @param[in] tag The sequence tag or @c NULL.596 * @param[in] implicit If the tag may be omitted.597 * @param[in] style The sequence style.598 *599 * @returns @c 1 if the function succeeded, @c 0 on error.600 */601 602YAML_DECLARE(int)603yaml_sequence_start_event_initialize(yaml_event_t *event,604 const yaml_char_t *anchor, const yaml_char_t *tag, int implicit,605 yaml_sequence_style_t style);606 607/**608 * Create a SEQUENCE-END event.609 *610 * @param[out] event An empty event object.611 *612 * @returns @c 1 if the function succeeded, @c 0 on error.613 */614 615YAML_DECLARE(int)616yaml_sequence_end_event_initialize(yaml_event_t *event);617 618/**619 * Create a MAPPING-START event.620 *621 * The @a style argument may be ignored by the emitter.622 *623 * Either the @a tag attribute or the @a implicit flag must be set.624 *625 * @param[out] event An empty event object.626 * @param[in] anchor The mapping anchor or @c NULL.627 * @param[in] tag The mapping tag or @c NULL.628 * @param[in] implicit If the tag may be omitted.629 * @param[in] style The mapping style.630 *631 * @returns @c 1 if the function succeeded, @c 0 on error.632 */633 634YAML_DECLARE(int)635yaml_mapping_start_event_initialize(yaml_event_t *event,636 const yaml_char_t *anchor, const yaml_char_t *tag, int implicit,637 yaml_mapping_style_t style);638 639/**640 * Create a MAPPING-END event.641 *642 * @param[out] event An empty event object.643 *644 * @returns @c 1 if the function succeeded, @c 0 on error.645 */646 647YAML_DECLARE(int)648yaml_mapping_end_event_initialize(yaml_event_t *event);649 650/**651 * Free any memory allocated for an event object.652 *653 * @param[in,out] event An event object.654 */655 656YAML_DECLARE(void)657yaml_event_delete(yaml_event_t *event);658 659/** @} */660 661/**662 * @defgroup nodes Nodes663 * @{664 */665 666/** The tag @c !!null with the only possible value: @c null. */667#define YAML_NULL_TAG "tag:yaml.org,2002:null"668/** The tag @c !!bool with the values: @c true and @c false. */669#define YAML_BOOL_TAG "tag:yaml.org,2002:bool"670/** The tag @c !!str for string values. */671#define YAML_STR_TAG "tag:yaml.org,2002:str"672/** The tag @c !!int for integer values. */673#define YAML_INT_TAG "tag:yaml.org,2002:int"674/** The tag @c !!float for float values. */675#define YAML_FLOAT_TAG "tag:yaml.org,2002:float"676/** The tag @c !!timestamp for date and time values. */677#define YAML_TIMESTAMP_TAG "tag:yaml.org,2002:timestamp"678 679/** The tag @c !!seq is used to denote sequences. */680#define YAML_SEQ_TAG "tag:yaml.org,2002:seq"681/** The tag @c !!map is used to denote mapping. */682#define YAML_MAP_TAG "tag:yaml.org,2002:map"683 684/** The default scalar tag is @c !!str. */685#define YAML_DEFAULT_SCALAR_TAG YAML_STR_TAG686/** The default sequence tag is @c !!seq. */687#define YAML_DEFAULT_SEQUENCE_TAG YAML_SEQ_TAG688/** The default mapping tag is @c !!map. */689#define YAML_DEFAULT_MAPPING_TAG YAML_MAP_TAG690 691/** Node types. */692typedef enum yaml_node_type_e {693 /** An empty node. */694 YAML_NO_NODE,695 696 /** A scalar node. */697 YAML_SCALAR_NODE,698 /** A sequence node. */699 YAML_SEQUENCE_NODE,700 /** A mapping node. */701 YAML_MAPPING_NODE702} yaml_node_type_t;703 704/** The forward definition of a document node structure. */705typedef struct yaml_node_s yaml_node_t;706 707/** An element of a sequence node. */708typedef int yaml_node_item_t;709 710/** An element of a mapping node. */711typedef struct yaml_node_pair_s {712 /** The key of the element. */713 int key;714 /** The value of the element. */715 int value;716} yaml_node_pair_t;717 718/** The node structure. */719struct yaml_node_s {720 721 /** The node type. */722 yaml_node_type_t type;723 724 /** The node tag. */725 yaml_char_t *tag;726 727 /** The node data. */728 union {729 730 /** The scalar parameters (for @c YAML_SCALAR_NODE). */731 struct {732 /** The scalar value. */733 yaml_char_t *value;734 /** The length of the scalar value. */735 size_t length;736 /** The scalar style. */737 yaml_scalar_style_t style;738 } scalar;739 740 /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */741 struct {742 /** The stack of sequence items. */743 struct {744 /** The beginning of the stack. */745 yaml_node_item_t *start;746 /** The end of the stack. */747 yaml_node_item_t *end;748 /** The top of the stack. */749 yaml_node_item_t *top;750 } items;751 /** The sequence style. */752 yaml_sequence_style_t style;753 } sequence;754 755 /** The mapping parameters (for @c YAML_MAPPING_NODE). */756 struct {757 /** The stack of mapping pairs (key, value). */758 struct {759 /** The beginning of the stack. */760 yaml_node_pair_t *start;761 /** The end of the stack. */762 yaml_node_pair_t *end;763 /** The top of the stack. */764 yaml_node_pair_t *top;765 } pairs;766 /** The mapping style. */767 yaml_mapping_style_t style;768 } mapping;769 770 } data;771 772 /** The beginning of the node. */773 yaml_mark_t start_mark;774 /** The end of the node. */775 yaml_mark_t end_mark;776 777};778 779/** The document structure. */780typedef struct yaml_document_s {781 782 /** The document nodes. */783 struct {784 /** The beginning of the stack. */785 yaml_node_t *start;786 /** The end of the stack. */787 yaml_node_t *end;788 /** The top of the stack. */789 yaml_node_t *top;790 } nodes;791 792 /** The version directive. */793 yaml_version_directive_t *version_directive;794 795 /** The list of tag directives. */796 struct {797 /** The beginning of the tag directives list. */798 yaml_tag_directive_t *start;799 /** The end of the tag directives list. */800 yaml_tag_directive_t *end;801 } tag_directives;802 803 /** Is the document start indicator implicit? */804 int start_implicit;805 /** Is the document end indicator implicit? */806 int end_implicit;807 808 /** The beginning of the document. */809 yaml_mark_t start_mark;810 /** The end of the document. */811 yaml_mark_t end_mark;812 813} yaml_document_t;814 815/**816 * Create a YAML document.817 *818 * @param[out] document An empty document object.819 * @param[in] version_directive The %YAML directive value or820 * @c NULL.821 * @param[in] tag_directives_start The beginning of the %TAG822 * directives list.823 * @param[in] tag_directives_end The end of the %TAG directives824 * list.825 * @param[in] start_implicit If the document start indicator is826 * implicit.827 * @param[in] end_implicit If the document end indicator is828 * implicit.829 *830 * @returns @c 1 if the function succeeded, @c 0 on error.831 */832 833YAML_DECLARE(int)834yaml_document_initialize(yaml_document_t *document,835 yaml_version_directive_t *version_directive,836 yaml_tag_directive_t *tag_directives_start,837 yaml_tag_directive_t *tag_directives_end,838 int start_implicit, int end_implicit);839 840/**841 * Delete a YAML document and all its nodes.842 *843 * @param[in,out] document A document object.844 */845 846YAML_DECLARE(void)847yaml_document_delete(yaml_document_t *document);848 849/**850 * Get a node of a YAML document.851 *852 * The pointer returned by this function is valid until any of the functions853 * modifying the documents are called.854 *855 * @param[in] document A document object.856 * @param[in] index The node id.857 *858 * @returns the node objct or @c NULL if @c node_id is out of range.859 */860 861YAML_DECLARE(yaml_node_t *)862yaml_document_get_node(yaml_document_t *document, int index);863 864/**865 * Get the root of a YAML document node.866 *867 * The root object is the first object added to the document.868 *869 * The pointer returned by this function is valid until any of the functions870 * modifying the documents are called.871 *872 * An empty document produced by the parser signifies the end of a YAML873 * stream.874 *875 * @param[in] document A document object.876 *877 * @returns the node object or @c NULL if the document is empty.878 */879 880YAML_DECLARE(yaml_node_t *)881yaml_document_get_root_node(yaml_document_t *document);882 883/**884 * Create a SCALAR node and attach it to the document.885 *886 * The @a style argument may be ignored by the emitter.887 *888 * @param[in,out] document A document object.889 * @param[in] tag The scalar tag.890 * @param[in] value The scalar value.891 * @param[in] length The length of the scalar value.892 * @param[in] style The scalar style.893 *894 * @returns the node id or @c 0 on error.895 */896 897YAML_DECLARE(int)898yaml_document_add_scalar(yaml_document_t *document,899 const yaml_char_t *tag, const yaml_char_t *value, int length,900 yaml_scalar_style_t style);901 902/**903 * Create a SEQUENCE node and attach it to the document.904 *905 * The @a style argument may be ignored by the emitter.906 *907 * @param[in,out] document A document object.908 * @param[in] tag The sequence tag.909 * @param[in] style The sequence style.910 *911 * @returns the node id or @c 0 on error.912 */913 914YAML_DECLARE(int)915yaml_document_add_sequence(yaml_document_t *document,916 const yaml_char_t *tag, yaml_sequence_style_t style);917 918/**919 * Create a MAPPING node and attach it to the document.920 *921 * The @a style argument may be ignored by the emitter.922 *923 * @param[in,out] document A document object.924 * @param[in] tag The sequence tag.925 * @param[in] style The sequence style.926 *927 * @returns the node id or @c 0 on error.928 */929 930YAML_DECLARE(int)931yaml_document_add_mapping(yaml_document_t *document,932 const yaml_char_t *tag, yaml_mapping_style_t style);933 934/**935 * Add an item to a SEQUENCE node.936 *937 * @param[in,out] document A document object.938 * @param[in] sequence The sequence node id.939 * @param[in] item The item node id.940 *941 * @returns @c 1 if the function succeeded, @c 0 on error.942 */943 944YAML_DECLARE(int)945yaml_document_append_sequence_item(yaml_document_t *document,946 int sequence, int item);947 948/**949 * Add a pair of a key and a value to a MAPPING node.950 *951 * @param[in,out] document A document object.952 * @param[in] mapping The mapping node id.953 * @param[in] key The key node id.954 * @param[in] value The value node id.955 *956 * @returns @c 1 if the function succeeded, @c 0 on error.957 */958 959YAML_DECLARE(int)960yaml_document_append_mapping_pair(yaml_document_t *document,961 int mapping, int key, int value);962 963/** @} */964 965/**966 * @defgroup parser Parser Definitions967 * @{968 */969 970/**971 * The prototype of a read handler.972 *973 * The read handler is called when the parser needs to read more bytes from the974 * source. The handler should write not more than @a size bytes to the @a975 * buffer. The number of written bytes should be set to the @a length variable.976 *977 * @param[in,out] data A pointer to an application data specified by978 * yaml_parser_set_input().979 * @param[out] buffer The buffer to write the data from the source.980 * @param[in] size The size of the buffer.981 * @param[out] size_read The actual number of bytes read from the source.982 *983 * @returns On success, the handler should return @c 1. If the handler failed,984 * the returned value should be @c 0. On EOF, the handler should set the985 * @a size_read to @c 0 and return @c 1.986 */987 988typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,989 size_t *size_read);990 991/**992 * This structure holds information about a potential simple key.993 */994 995typedef struct yaml_simple_key_s {996 /** Is a simple key possible? */997 int possible;998 999 /** Is a simple key required? */1000 int required;1001 1002 /** The number of the token. */1003 size_t token_number;1004 1005 /** The position mark. */1006 yaml_mark_t mark;1007} yaml_simple_key_t;1008 1009/**1010 * The states of the parser.1011 */1012typedef enum yaml_parser_state_e {1013 /** Expect STREAM-START. */1014 YAML_PARSE_STREAM_START_STATE,1015 /** Expect the beginning of an implicit document. */1016 YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,1017 /** Expect DOCUMENT-START. */1018 YAML_PARSE_DOCUMENT_START_STATE,1019 /** Expect the content of a document. */1020 YAML_PARSE_DOCUMENT_CONTENT_STATE,1021 /** Expect DOCUMENT-END. */1022 YAML_PARSE_DOCUMENT_END_STATE,1023 1024 /** Expect a block node. */1025 YAML_PARSE_BLOCK_NODE_STATE,1026 /** Expect a block node or indentless sequence. */1027 YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,1028 /** Expect a flow node. */1029 YAML_PARSE_FLOW_NODE_STATE,1030 /** Expect the first entry of a block sequence. */1031 YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,1032 /** Expect an entry of a block sequence. */1033 YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,1034 1035 /** Expect an entry of an indentless sequence. */1036 YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,1037 /** Expect the first key of a block mapping. */1038 YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,1039 /** Expect a block mapping key. */1040 YAML_PARSE_BLOCK_MAPPING_KEY_STATE,1041 /** Expect a block mapping value. */1042 YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,1043 /** Expect the first entry of a flow sequence. */1044 YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,1045 1046 /** Expect an entry of a flow sequence. */1047 YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,1048 /** Expect a key of an ordered mapping. */1049 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,1050 /** Expect a value of an ordered mapping. */1051 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,1052 /** Expect the and of an ordered mapping entry. */1053 YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,1054 /** Expect the first key of a flow mapping. */1055 YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,1056 /** Expect a key of a flow mapping. */1057 1058 YAML_PARSE_FLOW_MAPPING_KEY_STATE,1059 /** Expect a value of a flow mapping. */1060 YAML_PARSE_FLOW_MAPPING_VALUE_STATE,1061 /** Expect an empty value of a flow mapping. */1062 YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,1063 /** Expect nothing. */1064 YAML_PARSE_END_STATE1065} yaml_parser_state_t;1066 1067/**1068 * This structure holds aliases data.1069 */1070 1071typedef struct yaml_alias_data_s {1072 /** The anchor. */1073 yaml_char_t *anchor;1074 /** The node id. */1075 int index;1076 /** The anchor mark. */1077 yaml_mark_t mark;1078} yaml_alias_data_t;1079 1080/**1081 * The parser structure.1082 *1083 * All members are internal. Manage the structure using the @c yaml_parser_1084 * family of functions.1085 */1086 1087typedef struct yaml_parser_s {1088 1089 /**1090 * @name Error handling1091 * @{1092 */1093 1094 /** Error type. */1095 yaml_error_type_t error;1096 /** Error description. */1097 const char *problem;1098 /** The byte about which the problem occured. */1099 size_t problem_offset;1100 /** The problematic value (@c -1 is none). */1101 int problem_value;1102 /** The problem position. */1103 yaml_mark_t problem_mark;1104 /** The error context. */1105 const char *context;1106 /** The context position. */1107 yaml_mark_t context_mark;1108 1109 /**1110 * @}1111 */1112 1113 /**1114 * @name Reader stuff1115 * @{1116 */1117 1118 /** Read handler. */1119 yaml_read_handler_t *read_handler;1120 1121 /** A pointer for passing to the read handler. */1122 void *read_handler_data;1123 1124 /** Standard (string or file) input data. */1125 union {1126 /** String input data. */1127 struct {1128 /** The string start pointer. */1129 const unsigned char *start;1130 /** The string end pointer. */1131 const unsigned char *end;1132 /** The string current position. */1133 const unsigned char *current;1134 } string;1135 1136 /** File input data. */1137 FILE *file;1138 } input;1139 1140 /** EOF flag */1141 int eof;1142 1143 /** The working buffer. */1144 struct {1145 /** The beginning of the buffer. */1146 yaml_char_t *start;1147 /** The end of the buffer. */1148 yaml_char_t *end;1149 /** The current position of the buffer. */1150 yaml_char_t *pointer;1151 /** The last filled position of the buffer. */1152 yaml_char_t *last;1153 } buffer;1154 1155 /* The number of unread characters in the buffer. */1156 size_t unread;1157 1158 /** The raw buffer. */1159 struct {1160 /** The beginning of the buffer. */1161 unsigned char *start;1162 /** The end of the buffer. */1163 unsigned char *end;1164 /** The current position of the buffer. */1165 unsigned char *pointer;1166 /** The last filled position of the buffer. */1167 unsigned char *last;1168 } raw_buffer;1169 1170 /** The input encoding. */1171 yaml_encoding_t encoding;1172 1173 /** The offset of the current position (in bytes). */1174 size_t offset;1175 1176 /** The mark of the current position. */1177 yaml_mark_t mark;1178 1179 /**1180 * @}1181 */1182 1183 /**1184 * @name Scanner stuff1185 * @{1186 */1187 1188 /** Have we started to scan the input stream? */1189 int stream_start_produced;1190 1191 /** Have we reached the end of the input stream? */1192 int stream_end_produced;1193 1194 /** The number of unclosed '[' and '{' indicators. */1195 int flow_level;1196 1197 /** The tokens queue. */1198 struct {1199 /** The beginning of the tokens queue. */1200 yaml_token_t *start;