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

Revision 237, 44.0 KB checked in by xi, 8 years ago (diff)

Add const qualifier for yaml_parser_set_input_string parameter input.

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