Actual source code: yaml.h
1: /**
2: * @file yaml.h
3: * @brief Public interface for libyaml.
4: *
5: * Include the header file with the code:
6: * @code
7: * #include <yaml.h>
8: * @endcode
9: */
11: #ifndef YAML_H
12: #define YAML_H
14: #ifdef __cplusplus
15: extern "C" {
16: #endif
18: #include <stdlib.h>
19: #include <stdio.h>
20: #include <string.h>
22: /**
23: * @defgroup export Export Definitions
24: * @{
25: */
27: /** The public API declaration. */
29: #define YAML_DECLARE(type) static type
31: /** @} */
33: /**
34: * @defgroup basic Basic Types
35: * @{
36: */
38: /** The character type (UTF-8 octet). */
39: typedef unsigned char yaml_char_t;
41: /** The version directive data. */
42: typedef struct yaml_version_directive_s {
43: /** The major version number. */
44: int major;
45: /** The minor version number. */
46: int minor;
47: } yaml_version_directive_t;
49: /** The tag directive data. */
50: typedef struct yaml_tag_directive_s {
51: /** The tag handle. */
52: yaml_char_t *handle;
53: /** The tag prefix. */
54: yaml_char_t *prefix;
55: } yaml_tag_directive_t;
57: /** The stream encoding. */
58: typedef enum yaml_encoding_e {
59: /** Let the parser choose the encoding. */
60: YAML_ANY_ENCODING,
61: /** The default UTF-8 encoding. */
62: YAML_UTF8_ENCODING,
63: /** The UTF-16-LE encoding with BOM. */
64: YAML_UTF16LE_ENCODING,
65: /** The UTF-16-BE encoding with BOM. */
66: YAML_UTF16BE_ENCODING
67: } yaml_encoding_t;
69: /** Line break types. */
71: typedef enum yaml_break_e {
72: /** Let the parser choose the break type. */
73: YAML_ANY_BREAK,
74: /** Use CR for line breaks (Mac style). */
75: YAML_CR_BREAK,
76: /** Use LN for line breaks (Unix style). */
77: YAML_LN_BREAK,
78: /** Use CR LN for line breaks (DOS style). */
79: YAML_CRLN_BREAK
80: } yaml_break_t;
82: /** Many bad things could happen with the parser and emitter. */
83: typedef enum yaml_error_type_e {
84: /** No error is produced. */
85: YAML_NO_ERROR,
87: /** Cannot allocate or reallocate a block of memory. */
88: YAML_MEMORY_ERROR,
90: /** Cannot read or decode the input stream. */
91: YAML_READER_ERROR,
92: /** Cannot scan the input stream. */
93: YAML_SCANNER_ERROR,
94: /** Cannot parse the input stream. */
95: YAML_PARSER_ERROR,
96: /** Cannot compose a YAML document. */
97: YAML_COMPOSER_ERROR,
99: /** Cannot write to the output stream. */
100: YAML_WRITER_ERROR,
101: /** Cannot emit a YAML stream. */
102: YAML_EMITTER_ERROR
103: } yaml_error_type_t;
105: /** The pointer position. */
106: typedef struct yaml_mark_s {
107: /** The position index. */
108: size_t index;
110: /** The position line. */
111: size_t line;
113: /** The position column. */
114: size_t column;
115: } yaml_mark_t;
117: /** @} */
119: /**
120: * @defgroup styles Node Styles
121: * @{
122: */
124: /** Scalar styles. */
125: typedef enum yaml_scalar_style_e {
126: /** Let the emitter choose the style. */
127: YAML_ANY_SCALAR_STYLE,
129: /** The plain scalar style. */
130: YAML_PLAIN_SCALAR_STYLE,
132: /** The single-quoted scalar style. */
133: YAML_SINGLE_QUOTED_SCALAR_STYLE,
134: /** The double-quoted scalar style. */
135: YAML_DOUBLE_QUOTED_SCALAR_STYLE,
137: /** The literal scalar style. */
138: YAML_LITERAL_SCALAR_STYLE,
139: /** The folded scalar style. */
140: YAML_FOLDED_SCALAR_STYLE
141: } yaml_scalar_style_t;
143: /** Sequence styles. */
144: typedef enum yaml_sequence_style_e {
145: /** Let the emitter choose the style. */
146: YAML_ANY_SEQUENCE_STYLE,
148: /** The block sequence style. */
149: YAML_BLOCK_SEQUENCE_STYLE,
150: /** The flow sequence style. */
151: YAML_FLOW_SEQUENCE_STYLE
152: } yaml_sequence_style_t;
154: /** Mapping styles. */
155: typedef enum yaml_mapping_style_e {
156: /** Let the emitter choose the style. */
157: YAML_ANY_MAPPING_STYLE,
159: /** The block mapping style. */
160: YAML_BLOCK_MAPPING_STYLE,
161: /** The flow mapping style. */
162: YAML_FLOW_MAPPING_STYLE
163: /* YAML_FLOW_SET_MAPPING_STYLE */
164: } yaml_mapping_style_t;
166: /** @} */
168: /**
169: * @defgroup tokens Tokens
170: * @{
171: */
173: /** Token types. */
174: typedef enum yaml_token_type_e {
175: /** An empty token. */
176: YAML_NO_TOKEN,
178: /** A STREAM-START token. */
179: YAML_STREAM_START_TOKEN,
180: /** A STREAM-END token. */
181: YAML_STREAM_END_TOKEN,
183: /** A VERSION-DIRECTIVE token. */
184: YAML_VERSION_DIRECTIVE_TOKEN,
185: /** A TAG-DIRECTIVE token. */
186: YAML_TAG_DIRECTIVE_TOKEN,
187: /** A DOCUMENT-START token. */
188: YAML_DOCUMENT_START_TOKEN,
189: /** A DOCUMENT-END token. */
190: YAML_DOCUMENT_END_TOKEN,
192: /** A BLOCK-SEQUENCE-START token. */
193: YAML_BLOCK_SEQUENCE_START_TOKEN,
194: /** A BLOCK-MAPPING-START token. */
195: YAML_BLOCK_MAPPING_START_TOKEN,
196: /** A BLOCK-END token. */
197: YAML_BLOCK_END_TOKEN,
199: /** A FLOW-SEQUENCE-START token. */
200: YAML_FLOW_SEQUENCE_START_TOKEN,
201: /** A FLOW-SEQUENCE-END token. */
202: YAML_FLOW_SEQUENCE_END_TOKEN,
203: /** A FLOW-MAPPING-START token. */
204: YAML_FLOW_MAPPING_START_TOKEN,
205: /** A FLOW-MAPPING-END token. */
206: YAML_FLOW_MAPPING_END_TOKEN,
208: /** A BLOCK-ENTRY token. */
209: YAML_BLOCK_ENTRY_TOKEN,
210: /** A FLOW-ENTRY token. */
211: YAML_FLOW_ENTRY_TOKEN,
212: /** A KEY token. */
213: YAML_KEY_TOKEN,
214: /** A VALUE token. */
215: YAML_VALUE_TOKEN,
217: /** An ALIAS token. */
218: YAML_ALIAS_TOKEN,
219: /** An ANCHOR token. */
220: YAML_ANCHOR_TOKEN,
221: /** A TAG token. */
222: YAML_TAG_TOKEN,
223: /** A SCALAR token. */
224: YAML_SCALAR_TOKEN
225: } yaml_token_type_t;
227: /** The token structure. */
228: typedef struct yaml_token_s {
230: /** The token type. */
231: yaml_token_type_t type;
233: /** The token data. */
234: union {
236: /** The stream start (for @c YAML_STREAM_START_TOKEN). */
237: struct {
238: /** The stream encoding. */
239: yaml_encoding_t encoding;
240: } stream_start;
242: /** The alias (for @c YAML_ALIAS_TOKEN). */
243: struct {
244: /** The alias value. */
245: yaml_char_t *value;
246: } alias;
248: /** The anchor (for @c YAML_ANCHOR_TOKEN). */
249: struct {
250: /** The anchor value. */
251: yaml_char_t *value;
252: } anchor;
254: /** The tag (for @c YAML_TAG_TOKEN). */
255: struct {
256: /** The tag handle. */
257: yaml_char_t *handle;
258: /** The tag suffix. */
259: yaml_char_t *suffix;
260: } tag;
262: /** The scalar value (for @c YAML_SCALAR_TOKEN). */
263: struct {
264: /** The scalar value. */
265: yaml_char_t *value;
266: /** The length of the scalar value. */
267: size_t length;
268: /** The scalar style. */
269: yaml_scalar_style_t style;
270: } scalar;
272: /** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
273: struct {
274: /** The major version number. */
275: int major;
276: /** The minor version number. */
277: int minor;
278: } version_directive;
280: /** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
281: struct {
282: /** The tag handle. */
283: yaml_char_t *handle;
284: /** The tag prefix. */
285: yaml_char_t *prefix;
286: } tag_directive;
288: } data;
290: /** The beginning of the token. */
291: yaml_mark_t start_mark;
292: /** The end of the token. */
293: yaml_mark_t end_mark;
295: } yaml_token_t;
297: /**
298: * Free any memory allocated for a token object.
299: *
300: * @param[in,out] token A token object.
301: */
303: YAML_DECLARE(void)
304: yaml_token_delete(yaml_token_t *token);
306: /** @} */
308: /**
309: * @defgroup events Events
310: * @{
311: */
313: /** Event types. */
314: typedef enum yaml_event_type_e {
315: /** An empty event. */
316: YAML_NO_EVENT,
318: /** A STREAM-START event. */
319: YAML_STREAM_START_EVENT,
320: /** A STREAM-END event. */
321: YAML_STREAM_END_EVENT,
323: /** A DOCUMENT-START event. */
324: YAML_DOCUMENT_START_EVENT,
325: /** A DOCUMENT-END event. */
326: YAML_DOCUMENT_END_EVENT,
328: /** An ALIAS event. */
329: YAML_ALIAS_EVENT,
330: /** A SCALAR event. */
331: YAML_SCALAR_EVENT,
333: /** A SEQUENCE-START event. */
334: YAML_SEQUENCE_START_EVENT,
335: /** A SEQUENCE-END event. */
336: YAML_SEQUENCE_END_EVENT,
338: /** A MAPPING-START event. */
339: YAML_MAPPING_START_EVENT,
340: /** A MAPPING-END event. */
341: YAML_MAPPING_END_EVENT
342: } yaml_event_type_t;
344: /** The event structure. */
345: typedef struct yaml_event_s {
347: /** The event type. */
348: yaml_event_type_t type;
350: /** The event data. */
351: union {
352:
353: /** The stream parameters (for @c YAML_STREAM_START_EVENT). */
354: struct {
355: /** The document encoding. */
356: yaml_encoding_t encoding;
357: } stream_start;
359: /** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
360: struct {
361: /** The version directive. */
362: yaml_version_directive_t *version_directive;
364: /** The list of tag directives. */
365: struct {
366: /** The beginning of the tag directives list. */
367: yaml_tag_directive_t *start;
368: /** The end of the tag directives list. */
369: yaml_tag_directive_t *end;
370: } tag_directives;
372: /** Is the document indicator implicit? */
373: int implicit;
374: } document_start;
376: /** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
377: struct {
378: /** Is the document end indicator implicit? */
379: int implicit;
380: } document_end;
382: /** The alias parameters (for @c YAML_ALIAS_EVENT). */
383: struct {
384: /** The anchor. */
385: yaml_char_t *anchor;
386: } alias;
388: /** The scalar parameters (for @c YAML_SCALAR_EVENT). */
389: struct {
390: /** The anchor. */
391: yaml_char_t *anchor;
392: /** The tag. */
393: yaml_char_t *tag;
394: /** The scalar value. */
395: yaml_char_t *value;
396: /** The length of the scalar value. */
397: size_t length;
398: /** Is the tag optional for the plain style? */
399: int plain_implicit;
400: /** Is the tag optional for any non-plain style? */
401: int quoted_implicit;
402: /** The scalar style. */
403: yaml_scalar_style_t style;
404: } scalar;
406: /** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
407: struct {
408: /** The anchor. */
409: yaml_char_t *anchor;
410: /** The tag. */
411: yaml_char_t *tag;
412: /** Is the tag optional? */
413: int implicit;
414: /** The sequence style. */
415: yaml_sequence_style_t style;
416: } sequence_start;
418: /** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
419: struct {
420: /** The anchor. */
421: yaml_char_t *anchor;
422: /** The tag. */
423: yaml_char_t *tag;
424: /** Is the tag optional? */
425: int implicit;
426: /** The mapping style. */
427: yaml_mapping_style_t style;
428: } mapping_start;
430: } data;
432: /** The beginning of the event. */
433: yaml_mark_t start_mark;
434: /** The end of the event. */
435: yaml_mark_t end_mark;
437: } yaml_event_t;
439: /** @} */
441: /**
442: * @defgroup nodes Nodes
443: * @{
444: */
446: /** The tag @c !!null with the only possible value: @c null. */
447: #define YAML_NULL_TAG "tag:yaml.org,2002:null"
448: /** The tag @c !!bool with the values: @c true and @c false. */
449: #define YAML_BOOL_TAG "tag:yaml.org,2002:bool"
450: /** The tag @c !!str for string values. */
451: #define YAML_STR_TAG "tag:yaml.org,2002:str"
452: /** The tag @c !!int for integer values. */
453: #define YAML_INT_TAG "tag:yaml.org,2002:int"
454: /** The tag @c !!float for float values. */
455: #define YAML_FLOAT_TAG "tag:yaml.org,2002:float"
456: /** The tag @c !!timestamp for date and time values. */
457: #define YAML_TIMESTAMP_TAG "tag:yaml.org,2002:timestamp"
459: /** The tag @c !!seq is used to denote sequences. */
460: #define YAML_SEQ_TAG "tag:yaml.org,2002:seq"
461: /** The tag @c !!map is used to denote mapping. */
462: #define YAML_MAP_TAG "tag:yaml.org,2002:map"
464: /** The default scalar tag is @c !!str. */
465: #define YAML_DEFAULT_SCALAR_TAG YAML_STR_TAG
466: /** The default sequence tag is @c !!seq. */
467: #define YAML_DEFAULT_SEQUENCE_TAG YAML_SEQ_TAG
468: /** The default mapping tag is @c !!map. */
469: #define YAML_DEFAULT_MAPPING_TAG YAML_MAP_TAG
471: /** Node types. */
472: typedef enum yaml_node_type_e {
473: /** An empty node. */
474: YAML_NO_NODE,
476: /** A scalar node. */
477: YAML_SCALAR_NODE,
478: /** A sequence node. */
479: YAML_SEQUENCE_NODE,
480: /** A mapping node. */
481: YAML_MAPPING_NODE
482: } yaml_node_type_t;
484: /** The forward definition of a document node structure. */
485: typedef struct yaml_node_s yaml_node_t;
487: /** An element of a sequence node. */
488: typedef int yaml_node_item_t;
490: /** An element of a mapping node. */
491: typedef struct yaml_node_pair_s {
492: /** The key of the element. */
493: int key;
494: /** The value of the element. */
495: int value;
496: } yaml_node_pair_t;
498: /** The node structure. */
499: struct yaml_node_s {
501: /** The node type. */
502: yaml_node_type_t type;
504: /** The node tag. */
505: yaml_char_t *tag;
507: /** The node data. */
508: union {
509:
510: /** The scalar parameters (for @c YAML_SCALAR_NODE). */
511: struct {
512: /** The scalar value. */
513: yaml_char_t *value;
514: /** The length of the scalar value. */
515: size_t length;
516: /** The scalar style. */
517: yaml_scalar_style_t style;
518: } scalar;
520: /** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
521: struct {
522: /** The stack of sequence items. */
523: struct {
524: /** The beginning of the stack. */
525: yaml_node_item_t *start;
526: /** The end of the stack. */
527: yaml_node_item_t *end;
528: /** The top of the stack. */
529: yaml_node_item_t *top;
530: } items;
531: /** The sequence style. */
532: yaml_sequence_style_t style;
533: } sequence;
535: /** The mapping parameters (for @c YAML_MAPPING_NODE). */
536: struct {
537: /** The stack of mapping pairs (key, value). */
538: struct {
539: /** The beginning of the stack. */
540: yaml_node_pair_t *start;
541: /** The end of the stack. */
542: yaml_node_pair_t *end;
543: /** The top of the stack. */
544: yaml_node_pair_t *top;
545: } pairs;
546: /** The mapping style. */
547: yaml_mapping_style_t style;
548: } mapping;
550: } data;
552: /** The beginning of the node. */
553: yaml_mark_t start_mark;
554: /** The end of the node. */
555: yaml_mark_t end_mark;
557: };
559: /** The document structure. */
560: typedef struct yaml_document_s {
562: /** The document nodes. */
563: struct {
564: /** The beginning of the stack. */
565: yaml_node_t *start;
566: /** The end of the stack. */
567: yaml_node_t *end;
568: /** The top of the stack. */
569: yaml_node_t *top;
570: } nodes;
572: /** The version directive. */
573: yaml_version_directive_t *version_directive;
575: /** The list of tag directives. */
576: struct {
577: /** The beginning of the tag directives list. */
578: yaml_tag_directive_t *start;
579: /** The end of the tag directives list. */
580: yaml_tag_directive_t *end;
581: } tag_directives;
583: /** Is the document start indicator implicit? */
584: int start_implicit;
585: /** Is the document end indicator implicit? */
586: int end_implicit;
588: /** The beginning of the document. */
589: yaml_mark_t start_mark;
590: /** The end of the document. */
591: yaml_mark_t end_mark;
593: } yaml_document_t;
595: /**
596: * Delete a YAML document and all its nodes.
597: *
598: * @param[in,out] document A document object.
599: */
601: YAML_DECLARE(void)
602: yaml_document_delete(yaml_document_t *document);
604: /**
605: * Get a node of a YAML document.
606: *
607: * The pointer returned by this function is valid until any of the functions
608: * modifying the documents are called.
609: *
610: * @param[in] document A document object.
611: * @param[in] index The node id.
612: *
613: * @returns the node object or @c NULL if @c node_id is out of range.
614: */
616: YAML_DECLARE(yaml_node_t *)
617: yaml_document_get_node(yaml_document_t *document, int index);
619: /**
620: * Get the root of a YAML document node.
621: *
622: * The root object is the first object added to the document.
623: *
624: * The pointer returned by this function is valid until any of the functions
625: * modifying the documents are called.
626: *
627: * An empty document produced by the parser signifies the end of a YAML
628: * stream.
629: *
630: * @param[in] document A document object.
631: *
632: * @returns the node object or @c NULL if the document is empty.
633: */
635: YAML_DECLARE(yaml_node_t *)
636: yaml_document_get_root_node(yaml_document_t *document);
638: /**
639: * Create a SCALAR node and attach it to the document.
640: *
641: * The @a style argument may be ignored by the emitter.
642: *
643: * @param[in,out] document A document object.
644: * @param[in] tag The scalar tag.
645: * @param[in] value The scalar value.
646: * @param[in] length The length of the scalar value.
647: * @param[in] style The scalar style.
648: *
649: * @returns the node id or @c 0 on error.
650: */
652: /** @} */
654: /**
655: * @defgroup parser Parser Definitions
656: * @{
657: */
659: /**
660: * The prototype of a read handler.
661: *
662: * The read handler is called when the parser needs to read more bytes from the
663: * source. The handler should write not more than @a size bytes to the @a
664: * buffer. The number of written bytes should be set to the @a length variable.
665: *
666: * @param[in,out] data A pointer to an application data specified by
667: * yaml_parser_set_input().
668: * @param[out] buffer The buffer to write the data from the source.
669: * @param[in] size The size of the buffer.
670: * @param[out] size_read The actual number of bytes read from the source.
671: *
672: * @returns On success, the handler should return @c 1. If the handler failed,
673: * the returned value should be @c 0. On EOF, the handler should set the
674: * @a size_read to @c 0 and return @c 1.
675: */
677: typedef int yaml_read_handler_t(void *data, unsigned char *buffer, size_t size,
678: size_t *size_read);
680: /**
681: * This structure holds information about a potential simple key.
682: */
684: typedef struct yaml_simple_key_s {
685: /** Is a simple key possible? */
686: int possible;
688: /** Is a simple key required? */
689: int required;
691: /** The number of the token. */
692: size_t token_number;
694: /** The position mark. */
695: yaml_mark_t mark;
696: } yaml_simple_key_t;
698: /**
699: * The states of the parser.
700: */
701: typedef enum yaml_parser_state_e {
702: /** Expect STREAM-START. */
703: YAML_PARSE_STREAM_START_STATE,
704: /** Expect the beginning of an implicit document. */
705: YAML_PARSE_IMPLICIT_DOCUMENT_START_STATE,
706: /** Expect DOCUMENT-START. */
707: YAML_PARSE_DOCUMENT_START_STATE,
708: /** Expect the content of a document. */
709: YAML_PARSE_DOCUMENT_CONTENT_STATE,
710: /** Expect DOCUMENT-END. */
711: YAML_PARSE_DOCUMENT_END_STATE,
713: /** Expect a block node. */
714: YAML_PARSE_BLOCK_NODE_STATE,
715: /** Expect a block node or indentless sequence. */
716: YAML_PARSE_BLOCK_NODE_OR_INDENTLESS_SEQUENCE_STATE,
717: /** Expect a flow node. */
718: YAML_PARSE_FLOW_NODE_STATE,
719: /** Expect the first entry of a block sequence. */
720: YAML_PARSE_BLOCK_SEQUENCE_FIRST_ENTRY_STATE,
721: /** Expect an entry of a block sequence. */
722: YAML_PARSE_BLOCK_SEQUENCE_ENTRY_STATE,
724: /** Expect an entry of an indentless sequence. */
725: YAML_PARSE_INDENTLESS_SEQUENCE_ENTRY_STATE,
726: /** Expect the first key of a block mapping. */
727: YAML_PARSE_BLOCK_MAPPING_FIRST_KEY_STATE,
728: /** Expect a block mapping key. */
729: YAML_PARSE_BLOCK_MAPPING_KEY_STATE,
730: /** Expect a block mapping value. */
731: YAML_PARSE_BLOCK_MAPPING_VALUE_STATE,
732: /** Expect the first entry of a flow sequence. */
733: YAML_PARSE_FLOW_SEQUENCE_FIRST_ENTRY_STATE,
735: /** Expect an entry of a flow sequence. */
736: YAML_PARSE_FLOW_SEQUENCE_ENTRY_STATE,
737: /** Expect a key of an ordered mapping. */
738: YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_KEY_STATE,
739: /** Expect a value of an ordered mapping. */
740: YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_VALUE_STATE,
741: /** Expect the and of an ordered mapping entry. */
742: YAML_PARSE_FLOW_SEQUENCE_ENTRY_MAPPING_END_STATE,
743: /** Expect the first key of a flow mapping. */
744: YAML_PARSE_FLOW_MAPPING_FIRST_KEY_STATE,
745: /** Expect a key of a flow mapping. */
747: YAML_PARSE_FLOW_MAPPING_KEY_STATE,
748: /** Expect a value of a flow mapping. */
749: YAML_PARSE_FLOW_MAPPING_VALUE_STATE,
750: /** Expect an empty value of a flow mapping. */
751: YAML_PARSE_FLOW_MAPPING_EMPTY_VALUE_STATE,
752: /** Expect nothing. */
753: YAML_PARSE_END_STATE
754: } yaml_parser_state_t;
756: /**
757: * This structure holds aliases data.
758: */
760: typedef struct yaml_alias_data_s {
761: /** The anchor. */
762: yaml_char_t *anchor;
763: /** The node id. */
764: int index;
765: /** The anchor mark. */
766: yaml_mark_t mark;
767: } yaml_alias_data_t;
769: /**
770: * The parser structure.
771: *
772: * All members are internal. Manage the structure using the @c yaml_parser_
773: * family of functions.
774: */
776: typedef struct yaml_parser_s {
778: /**
779: * @name Error handling
780: * @{
781: */
783: /** Error type. */
784: yaml_error_type_t error;
785: /** Error description. */
786: const char *problem;
787: /** The byte about which the problem occurred. */
788: size_t problem_offset;
789: /** The problematic value (@c -1 is none). */
790: int problem_value;
791: /** The problem position. */
792: yaml_mark_t problem_mark;
793: /** The error context. */
794: const char *context;
795: /** The context position. */
796: yaml_mark_t context_mark;
798: /**
799: * @}
800: */
802: /**
803: * @name Reader stuff
804: * @{
805: */
807: /** Read handler. */
808: yaml_read_handler_t *read_handler;
810: /** A pointer for passing to the read handler. */
811: void *read_handler_data;
813: /** Standard (string or file) input data. */
814: union {
815: /** String input data. */
816: struct {
817: /** The string start pointer. */
818: const unsigned char *start;
819: /** The string end pointer. */
820: const unsigned char *end;
821: /** The string current position. */
822: const unsigned char *current;
823: } string;
825: /** File input data. */
826: FILE *file;
827: } input;
829: /** EOF flag */
830: int eof;
832: /** The working buffer. */
833: struct {
834: /** The beginning of the buffer. */
835: yaml_char_t *start;
836: /** The end of the buffer. */
837: yaml_char_t *end;
838: /** The current position of the buffer. */
839: yaml_char_t *pointer;
840: /** The last filled position of the buffer. */
841: yaml_char_t *last;
842: } buffer;
844: /* The number of unread characters in the buffer. */
845: size_t unread;
847: /** The raw buffer. */
848: struct {
849: /** The beginning of the buffer. */
850: unsigned char *start;
851: /** The end of the buffer. */
852: unsigned char *end;
853: /** The current position of the buffer. */
854: unsigned char *pointer;
855: /** The last filled position of the buffer. */
856: unsigned char *last;
857: } raw_buffer;
859: /** The input encoding. */
860: yaml_encoding_t encoding;
862: /** The offset of the current position (in bytes). */
863: size_t offset;
865: /** The mark of the current position. */
866: yaml_mark_t mark;
868: /**
869: * @}
870: */
872: /**
873: * @name Scanner stuff
874: * @{
875: */
877: /** Have we started to scan the input stream? */
878: int stream_start_produced;
880: /** Have we reached the end of the input stream? */
881: int stream_end_produced;
883: /** The number of unclosed '[' and '{' indicators. */
884: int flow_level;
886: /** The tokens queue. */
887: struct {
888: /** The beginning of the tokens queue. */
889: yaml_token_t *start;
890: /** The end of the tokens queue. */
891: yaml_token_t *end;
892: /** The head of the tokens queue. */
893: yaml_token_t *head;
894: /** The tail of the tokens queue. */
895: yaml_token_t *tail;
896: } tokens;
898: /** The number of tokens fetched from the queue. */
899: size_t tokens_parsed;
901: /** Does the tokens queue contain a token ready for dequeueing. */
902: int token_available;
904: /** The indentation levels stack. */
905: struct {
906: /** The beginning of the stack. */
907: int *start;
908: /** The end of the stack. */
909: int *end;
910: /** The top of the stack. */
911: int *top;
912: } indents;
914: /** The current indentation level. */
915: int indent;
917: /** May a simple key occur at the current position? */
918: int simple_key_allowed;
920: /** The stack of simple keys. */
921: struct {
922: /** The beginning of the stack. */
923: yaml_simple_key_t *start;
924: /** The end of the stack. */
925: yaml_simple_key_t *end;
926: /** The top of the stack. */
927: yaml_simple_key_t *top;
928: } simple_keys;
930: /**
931: * @}
932: */
934: /**
935: * @name Parser stuff
936: * @{
937: */
939: /** The parser states stack. */
940: struct {
941: /** The beginning of the stack. */
942: yaml_parser_state_t *start;
943: /** The end of the stack. */
944: yaml_parser_state_t *end;
945: /** The top of the stack. */
946: yaml_parser_state_t *top;
947: } states;
949: /** The current parser state. */
950: yaml_parser_state_t state;
952: /** The stack of marks. */
953: struct {
954: /** The beginning of the stack. */
955: yaml_mark_t *start;
956: /** The end of the stack. */
957: yaml_mark_t *end;
958: /** The top of the stack. */
959: yaml_mark_t *top;
960: } marks;
962: /** The list of TAG directives. */
963: struct {
964: /** The beginning of the list. */
965: yaml_tag_directive_t *start;
966: /** The end of the list. */
967: yaml_tag_directive_t *end;
968: /** The top of the list. */
969: yaml_tag_directive_t *top;
970: } tag_directives;
972: /**
973: * @}
974: */
976: /**
977: * @name Dumper stuff
978: * @{
979: */
981: /** The alias data. */
982: struct {
983: /** The beginning of the list. */
984: yaml_alias_data_t *start;
985: /** The end of the list. */
986: yaml_alias_data_t *end;
987: /** The top of the list. */
988: yaml_alias_data_t *top;
989: } aliases;
991: /** The currently parsed document. */
992: yaml_document_t *document;
994: /**
995: * @}
996: */
998: } yaml_parser_t;
1000: /**
1001: * Initialize a parser.
1002: *
1003: * This function creates a new parser object. An application is responsible
1004: * for destroying the object using the yaml_parser_delete() function.
1005: *
1006: * @param[out] parser An empty parser object.
1007: *
1008: * @returns @c 1 if the function succeeded, @c 0 on error.
1009: */
1011: YAML_DECLARE(int)
1012: yaml_parser_initialize(yaml_parser_t *parser);
1014: /**
1015: * Destroy a parser.
1016: *
1017: * @param[in,out] parser A parser object.
1018: */
1020: YAML_DECLARE(void)
1021: yaml_parser_delete(yaml_parser_t *parser);
1023: /**
1024: * Set a string input.
1025: *
1026: * Note that the @a input pointer must be valid while the @a parser object
1027: * exists. The application is responsible for destroying @a input after
1028: * destroying the @a parser.
1029: *
1030: * @param[in,out] parser A parser object.
1031: * @param[in] input A source data.
1032: * @param[in] size The length of the source data in bytes.
1033: */
1035: YAML_DECLARE(void)
1036: yaml_parser_set_input_string(yaml_parser_t *parser,
1037: const unsigned char *input, size_t size);
1039: /**
1040: * Set a file input.
1041: *
1042: * @a file should be a file object open for reading. The application is
1043: * responsible for closing the @a file.
1044: *
1045: * @param[in,out] parser A parser object.
1046: * @param[in] file An open file.
1047: */
1049: YAML_DECLARE(void)
1050: yaml_parser_set_input_file(yaml_parser_t *parser, FILE *file);
1052: /**
1053: * Set a generic input handler.
1054: *
1055: * @param[in,out] parser A parser object.
1056: * @param[in] handler A read handler.
1057: * @param[in] data Any application data for passing to the read
1058: * handler.
1059: */
1061: YAML_DECLARE(void)
1062: yaml_parser_set_input(yaml_parser_t *parser,
1063: yaml_read_handler_t *handler, void *data);
1065: /**
1066: * Set the source encoding.
1067: *
1068: * @param[in,out] parser A parser object.
1069: * @param[in] encoding The source encoding.
1070: */
1072: YAML_DECLARE(void)
1073: yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1075: /**
1076: * Scan the input stream and produce the next token.
1077: *
1078: * Call the function subsequently to produce a sequence of tokens corresponding
1079: * to the input stream. The initial token has the type
1080: * @c YAML_STREAM_START_TOKEN while the ending token has the type
1081: * @c YAML_STREAM_END_TOKEN.
1082: *
1083: * An application is responsible for freeing any buffers associated with the
1084: * produced token object using the @c yaml_token_delete function.
1085: *
1086: * An application must not alternate the calls of yaml_parser_scan() with the
1087: * calls of yaml_parser_parse() or yaml_parser_load(). Doing this will break
1088: * the parser.
1089: *
1090: * @param[in,out] parser A parser object.
1091: * @param[out] token An empty token object.
1092: *
1093: * @returns @c 1 if the function succeeded, @c 0 on error.
1094: */
1096: YAML_DECLARE(int)
1097: yaml_parser_scan(yaml_parser_t *parser, yaml_token_t *token);
1099: /**
1100: * Parse the input stream and produce the next parsing event.
1101: *
1102: * Call the function subsequently to produce a sequence of events corresponding
1103: * to the input stream. The initial event has the type
1104: * @c YAML_STREAM_START_EVENT while the ending event has the type
1105: * @c YAML_STREAM_END_EVENT.
1106: *
1107: * An application is responsible for freeing any buffers associated with the
1108: * produced event object using the yaml_event_delete() function.
1109: *
1110: * An application must not alternate the calls of yaml_parser_parse() with the
1111: * calls of yaml_parser_scan() or yaml_parser_load(). Doing this will break the
1112: * parser.
1113: *
1114: * @param[in,out] parser A parser object.
1115: * @param[out] event An empty event object.
1116: *
1117: * @returns @c 1 if the function succeeded, @c 0 on error.
1118: */
1120: YAML_DECLARE(int)
1121: yaml_parser_parse(yaml_parser_t *parser, yaml_event_t *event);
1123: /**
1124: * Parse the input stream and produce the next YAML document.
1125: *
1126: * Call this function subsequently to produce a sequence of documents
1127: * constituting the input stream.
1128: *
1129: * If the produced document has no root node, it means that the document
1130: * end has been reached.
1131: *
1132: * An application is responsible for freeing any data associated with the
1133: * produced document object using the yaml_document_delete() function.
1134: *
1135: * An application must not alternate the calls of yaml_parser_load() with the
1136: * calls of yaml_parser_scan() or yaml_parser_parse(). Doing this will break
1137: * the parser.
1138: *
1139: * @param[in,out] parser A parser object.
1140: * @param[out] document An empty document object.
1141: *
1142: * @returns @c 1 if the function succeeded, @c 0 on error.
1143: */
1145: YAML_DECLARE(int)
1146: yaml_parser_load(yaml_parser_t *parser, yaml_document_t *document);
1148: /** @} */
1150: #ifdef __cplusplus
1151: }
1152: #endif
1154: #endif /* #ifndef YAML_H */