Context Navigation

← Previous Change
Next Change →

yaml.h

Timestamp:

01/03/08 22:33:04 (4 years ago)

Author:

Message:

Drop doxygen support, add more API documentation, API changes.

Files:

: 1 modified

libyaml/trunk/include/yaml.h (modified) (60 diffs)

Legend:

: Unmodified
: Added
: Removed

libyaml/trunk/include/yaml.h

r265	r266
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		*/
	1	/*****************************************************************************
	2	* Public Interface for LibYAML
	3	*
	4	* Copyright (c) 2006 Kirill Simonov
	5	*
	6	* LibYAML is free software; you can use, modify and/or redistribute it under
	7	* the terms of the MIT license; see the file LICENCE for more details.
	8	*****************************************************************************/
	9
	10	/*
	11	* General guidelines.
	12	*
	13	* Naming conventions: all functions exported by LibYAML starts with the `yaml_` prefix;
	14	* types starts with `yaml_` and ends with `_t`; macros and enumerations starts
	15	* with `YAML_`.
	16	*
	17	* FIXME: Calling conventions.
	18	* FIXME: Memory allocation.
	19	* FIXME: Errors and exceptions.
	20	* FIXME: And so on, and so forth.
	21	*/
	22
10	23
11	24	#ifndef YAML_H
…	…
20	33	#include <string.h>
21	34
22		/**
23		* @defgroup export Export Definitions
24		* @{
25		*/
26
27		/** The public API declaration. */
	35	/*****************************************************************************
	36	* Export Definitions
	37	*****************************************************************************/
	38
	39	/*
	40	* Public API declarations.
	41	*
	42	* The following definitions are relevant only for the Win32 platform. If you
	43	* are building LibYAML as a static library or linking your application against
	44	* LibYAML compiled as a static library, define the macro
	45	* `YAML_DECLARE_STATIC`. If you are building LibYAML as a dynamic library
	46	* (DLL), you need to define `YAML_DECLARE_EXPORT`. You don't need to define
	47	* any macros in case you are linking your application against LibYAML compiled
	48	* as DLL.
	49	*
	50	* There is no need to define any macros if you use LibYAML on non-Win32
	51	* platform.
	52	*/
28	53
29	54	#ifdef WIN32
…	…
39	64	#endif
40	65
41		/** ~~@} */~~
42
43		/**
44		* @defgroup version Version Information
45		* @{
46		*/
47
48		/** The major version number. */
	66	/*****************************************************************************
	67	* Version Information
	68	*****************************************************************************/
	69
	70	/*
	71	* The major, minor and patch version numbers of LibYAML.
	72	*/
	73
49	74	#define YAML_VERSION_MAJOR 0
50
51		~~/** The minor version number. */~~
52	75	#define YAML_VERSION_MINOR 2
53
54		~~/** The patch version number. */~~
55	76	#define YAML_VERSION_PATCH 0
56	77
57		/** The version string generator macro. */
58		#define YAML_VERSION_STRING_GENERATOR(major,minor,patch) \
59		(#major "." #minor "." #patch)
60
61		/** The version string. */
62		#define YAML_VERSION_STRING \
63		YAML_VERSION_STRING_GENERATOR(YAML_VERSION_MAJOR,YAML_VERSION_MINOR,YAML_VERSION_PATCH)
64
65		/**
	78	/*
	79	* The version of LibYAML as a string.
	80	*/
	81
	82	#define YAML_VERSION_STRING "0.2.0"
	83
	84	/*
66	85	* Get the library version numbers at runtime.
67	86	*
68		* @param[out] major Major version number.
69		* @param[out] minor Minor version number.
70		* @param[out] patch Patch version number.
	87	* Arguments:
	88	*
	89	* - `major`: a pointer to store the major version number.
	90	*
	91	* - `minor`: a pointer to store the minor version number.
	92	*
	93	* - `patch`: a pointer to store the patch version number.
71	94	*/
72	95
…	…
74	97	yaml_get_version(int major, int minor, int *patch);
75	98
76		/**
	99	/*
77	100	* Get the library version as a string at runtime.
78	101	*
79		* @returns The function returns the pointer to a static string of the form
80		* @c "X.Y.Z", where @c X is the major version number, @c Y is the minor version
81		* number, and @c Z is the patch version number.
	102	* Returns: the version of LibYAML as a static string.
82	103	*/
83	104
…	…
85	106	yaml_get_version_string(void);
86	107
87		/** @} */
88
89		/**
90		* @defgroup styles Error Handling
91		* @{
92		*/
93
94		/** Many bad things could happen with the parser and the emitter. */
	108	/*****************************************************************************
	109	* Error Handling
	110	*****************************************************************************/
	111
	112	/*
	113	* The type of the error.
	114	*
	115	* The YAML parser and emitter reports any error details using the
	116	* `yaml_error_t` structure. The error type shows what subsystem generated the
	117	* error and what additional information about the error is available.
	118	*/
	119
95	120	typedef enum yaml_error_type_e {
96		/** No error is produced. */
	121	/* No error was produced. */
97	122	YAML_NO_ERROR,
98	123
99		/** Cannot allocate or reallocate a block of memory. */
	124	/* Cannot allocate or reallocate a block of memory. */
100	125	YAML_MEMORY_ERROR,
101	126
102		/** Cannot read from the input stream. */
	127	/* Cannot read from the input stream. */
103	128	YAML_READER_ERROR,
104		/** Cannot decode the input stream. */
	129	/* Cannot decode a character in the input stream. */
105	130	YAML_DECODER_ERROR,
106		/** Cannot scan a YAML token. */
	131	/* Cannot scan a YAML token. */
107	132	YAML_SCANNER_ERROR,
108		/** Cannot parse a YAML production. */
	133	/* Cannot parse a YAML event. */
109	134	YAML_PARSER_ERROR,
110		/** Cannot compose a YAML document. */
	135	/* Cannot compose a YAML document. */
111	136	YAML_COMPOSER_ERROR,
112	137
113		/** Cannot write into the output stream. */
	138	/* Cannot write into the output stream. */
114	139	YAML_WRITER_ERROR,
115		/** Cannot emit a YAML event. */
	140	/* Cannot emit a YAML event. */
116	141	YAML_EMITTER_ERROR,
117		/** Cannot serialize a YAML document. */
	142	/* Cannot serialize a YAML document. */
118	143	YAML_SERIALIZER_ERROR,
119	144
120		/** Cannot resolve an implicit tag. */
	145	/* Cannot resolve an implicit YAML node tag. */
121	146	YAML_RESOLVER_ERROR
122	147	} yaml_error_type_t;
123	148
124		/** The pointer position. */
	149	/*
	150	* Position in the input stream.
	151	*
	152	* Marks are used to indicate the position of YAML tokens, events and documents
	153	* in the input stream as well as to point to the place where a parser error has
	154	* occured.
	155	*/
	156
125	157	typedef struct yaml_mark_s {
126		/** The character number (starting from zero). */
	158	/* The number of the character in the input stream (starting from zero). */
127	159	size_t index;
128
129		/** The mark line (starting from zero). */
	160	/* The line in the input stream (starting from zero). */
130	161	size_t line;
131
132		/** The mark column (starting from zero). */
	162	/* The column in the input stream (starting from zero). */
133	163	size_t column;
134	164	} yaml_mark_t;
135	165
136		/** The error details. */
	166	/*
	167	* Error details.
	168	*
	169	* The structure gives detailed information on any problem that occured during
	170	* parsing or emitting.
	171	*/
	172
137	173	typedef struct yaml_error_s {
138	174
139		/** The error type. */
	175	/* The error type. */
140	176	yaml_error_type_t type;
141	177
142		/** The detailed error information. */
	178	/* The specific information for each error type. */
143	179	union {
144	180
145		/**
146		* A problem ~~while reading the stream (@c YAML_READER_ERROR~~ or
147		* ~~@c YAML_DECODER_ERROR~~).
	181	/*
	182	* A problem occured while reading the input stream (relevant for
	183	* `YAML_READER_ERROR` and `YAML_DECODER_ERROR`).
148	184	*/
149	185	struct {
150		/** The problem description. */
	186	/* The problem description. */
151	187	const char *problem;
152		/** The stream offset. */
	188	/* The position in the input stream, in bytes. */
153	189	size_t offset;
154		/** The problematic octet or character (@c -1 if not applicable). */
	190	/* The problematic octet or character (`-1` if not applicable). */
155	191	int value;
156	192	} reading;
157	193
158		/**
159		* A problem while loading the stream (@c YAML_SCANNER_ERROR,
160		* @c YAML_PARSER_ERROR, or @c YAML_COMPOSER_ERROR).
	194	/*
	195	* A problem occured while loading YAML data from the input stream
	196	* (relevant for `YAML_SCANNER_ERROR`, `YAML_PARSER_ERROR`, and
	197	* `YAML_COMPOSER_ERROR`).
161	198	*/
162	199	struct {
163		/** The context in which the problem occured
164		* (@c NULL if not applicable).
165		*/
	200	/* The description of the context in which the problem occured
	201	(`NULL` if not applicable). */
166	202	const char *context;
167		/~~ The context mark (if @c problem_mark is not @c NULL). ~~/
	203	/* The context mark (if `context` is not `NULL`). */
168	204	yaml_mark_t context_mark;
169		/** The problem description. */
	205	/* The problem description. */
170	206	const char *problem;
171		/** The problem mark. */
	207	/* The problem mark. */
172	208	yaml_mark_t problem_mark;
173	209	} loading;
174	210
175		/** A problem while writing into the stream (@c YAML_WRITER_ERROR). */
	211	/*
	212	* A problem occured while writing into the output stream (relevant for
	213	* `YAML_WRITER_ERROR`).
	214	*/
176	215	struct {
177		/** The problem description. */
	216	/* The problem description. */
178	217	const char *problem;
179		/** The stream offset. */
	218	/* The position in the output stream, in bytes. */
180	219	size_t offset;
181	220	} writing;
182	221
183		/** A problem while dumping into the stream (@c YAML_EMITTER_ERROR and
184		* @c YAML_SERIALIZER_ERROR).
	222	/*
	223	* A problem while dumping YAML data into the output stream (relevant
	224	* for `YAML_EMITTER_ERROR` and `YAML_SERIALIZER_ERROR`).
185	225	*/
186	226	struct {
187		/** The problem description. */
	227	/* The problem description. */
188	228	const char *problem;
189	229	} dumping;
190	230
191		/** A problem while resolving an implicit tag (@c YAML_RESOLVER_ERROR). */
	231	/*
	232	* A problem occured while resolving an implicit YAML node tag
	233	* (relevant for `YAML_RESOLVER_ERROR`).
	234	*/
192	235	struct {
193		/** The problem description. */
	236	/* The problem description. */
194	237	const char *problem;
195	238	} resolving;
…	…
199	242	} yaml_error_t;
200	243
201		/**
202		* Create an error message.
203		*
204		* @param[in] error An error object.
205		* @param[out] buffer model A token to copy.
206		*
207		* @returns @c 1 if the function succeeded, @c 0 on error. The function may
208		* fail if the buffer is not large enough to contain the whole message.
	244	/*
	245	* Generate an error message.
	246	*
	247	* Given an instance of the `yaml_error_t` structure and a buffer, the function
	248	* fills the buffer with a message describing the error. The generated message
	249	* follows the pattern: `"Error type: error details"`. If the buffer is not
	250	* large enough to hold the whole message, the function fails.
	251	*
	252	* Arguments:
	253	*
	254	* - `error`: an error object obtained using `yaml_parser_get_error()` or
	255	* `yaml_emitter_get_error()`.
	256	*
	257	* - `buffer`: a pointer to a character buffer to be filled with a generated
	258	* error message.
	259	*
	260	* - `capacity`: the size of the buffer.
	261	*
	262	* Returns: `1` if the function succeeded, `0` on error. The function may fail
	263	* if the provided buffer is not large enough to hold the whole buffer, in
	264	* which case an application may increase the size of the buffer and call the
	265	* function again. If the function fails, the content of the buffer is
	266	* undefined.
209	267	*/
210	268
…	…
212	270	yaml_error_message(yaml_error_t error, char buffer, size_t capacity);
213	271
214		/** @} */
215
216		/**
217		* @defgroup basic Basic Types
218		* @{
219		*/
220
221		/** The character type (UTF-8 octet). */
	272	/******************************************************************************
	273	* Basic Types
	274	******************************************************************************/
	275
	276	/*
	277	* The character type (UTF-8 octet).
	278	*
	279	* Usage of the string type `(yaml_char_t *)` in the LibYAML API indicates that
	280	* the string is encoded in UTF-8.
	281	*/
	282
222	283	typedef unsigned char yaml_char_t;
223	284
224		/** The version directive data. */
	285	/*
	286	* The version directive information.
	287	*
	288	* Note that LibYAML only supports YAML 1.1.
	289	*/
	290
225	291	typedef struct yaml_version_directive_s {
226		/** The major version number. */
	292	/* The major version number. */
227	293	int major;
228		/** The minor version number. */
	294	/* The minor version number. */
229	295	int minor;
230	296	} yaml_version_directive_t;
231	297
232		/** The tag directive data. */
	298	/*
	299	* The tag directive information.
	300	*/
	301
233	302	typedef struct yaml_tag_directive_s {
234		/** The tag handle. */
	303	/* The tag handle. */
235	304	yaml_char_t *handle;
236		/** The tag prefix. */
	305	/* The tag prefix. */
237	306	yaml_char_t *prefix;
238	307	} yaml_tag_directive_t;
239	308
240		/** The stream encoding. */
	309	/*
	310	* The stream encoding.
	311	*
	312	* An application may explicitly specify the encoding in the input stream or
	313	* let the parser to detect the input stream encoding from a BOM mark. If the
	314	* stream does not start with a BOM mark, UTF-8 is assumed.
	315	*
	316	* An application may specify the encoding of the output stream or let the
	317	* emitter to choose a suitable encoding, in which case, UTF-8 is used.
	318	*/
	319
241	320	typedef enum yaml_encoding_e {
242		/** Let the parser choose the encoding. */
	321	/* The default/autodetected encoding. */
243	322	YAML_ANY_ENCODING,
244		/** The default UTF-8 encoding. */
	323	/* The UTF-8 encoding. */
245	324	YAML_UTF8_ENCODING,
246		/** The UTF-16-LE encoding with BOM. */
	325	/* The UTF-16-LE encoding. */
247	326	YAML_UTF16LE_ENCODING,
248		/** The UTF-16-BE encoding with BOM. */
	327	/* The UTF-16-BE encoding. */
249	328	YAML_UTF16BE_ENCODING
250	329	} yaml_encoding_t;
251	330
252		/** Line break types. */
	331	/*
	332	* Line break types.
	333	*
	334	* An application may specify the line break type the emitter should use or
	335	* leave it to the emitter discretion. In the latter case, LN (Unix style) is
	336	* used.
	337	*/
	338
253	339	typedef enum yaml_break_e {
254		/** Let the parser choose the break type. */
	340	/* Let the parser choose the break type. */
255	341	YAML_ANY_BREAK,
256		/** Use CR for line breaks (Mac style). */
	342	/* Use CR for line breaks (Mac style). */
257	343	YAML_CR_BREAK,
258		/** Use LN for line breaks (Unix style). */
	344	/* Use LN for line breaks (Unix style). */
259	345	YAML_LN_BREAK,
260		/** Use CR LN for line breaks (DOS style). */
	346	/* Use CR LN for line breaks (DOS style). */
261	347	YAML_CRLN_BREAK
262	348	} yaml_break_t;
263	349
264		/** @} */
265
266		/**
267		* @defgroup styles Node Styles
268		* @{
269		*/
270
271		/** Scalar styles. */
	350	/******************************************************************************
	351	* Node Styles
	352	******************************************************************************/
	353
	354	/*
	355	* Scalar styles.
	356	*
	357	* There are two groups of scalar types in YAML: flow and block. Flow scalars
	358	* are divided into three styles: plain, single-quoted, and double-quoted;
	359	* block scalars are divided into two styles: literal and folded.
	360	*
	361	* The parser reports the style in which a scalar node is represented, however
	362	* it is a purely presentation details that must not be used in interpreting
	363	* the node content.
	364	*
	365	* An application may suggest a preferred node style or leave it completely
	366	* to the emitter discretion. Note that the emitter may ignore any stylistic
	367	* suggestions.
	368	*/
	369
272	370	typedef enum yaml_scalar_style_e {
273		/** Let the emitter choose the style. */
	371	/* Let the emitter choose the style. */
274	372	YAML_ANY_SCALAR_STYLE,
275	373
276		/** The plain scalar style. */
	374	/* The plain flow scalar style. */
277	375	YAML_PLAIN_SCALAR_STYLE,
278	376
279		/** The single-quoted scalar style. */
	377	/* The single-quoted flow scalar style. */
280	378	YAML_SINGLE_QUOTED_SCALAR_STYLE,
281		/** The double-quoted scalar style. */
	379	/* The double-quoted flow scalar style. */
282	380	YAML_DOUBLE_QUOTED_SCALAR_STYLE,
283	381
284		/** The literal scalar style. */
	382	/* The literal block scalar style. */
285	383	YAML_LITERAL_SCALAR_STYLE,
286		/** The folded scalar style. */
	384	/* The folded block scalar style. */
287	385	YAML_FOLDED_SCALAR_STYLE
288	386	} yaml_scalar_style_t;
289	387
290		/** Sequence styles. */
	388	/*
	389	* Sequence styles.
	390	*
	391	* YAML supports two sequence styles: flow and block.
	392	*
	393	* The parser reports the style of a sequence node, but this information should
	394	* not be used in interpreting the sequence content.
	395	*
	396	* An application may suggest a preferred sequence style or leave it completely
	397	* to the emitter discretion. Note that the emitter may ignore any stylistic
	398	* hints.
	399	*/
291	400	typedef enum yaml_sequence_style_e {
292		/** Let the emitter choose the style. */
	401	/* Let the emitter choose the style. */
293	402	YAML_ANY_SEQUENCE_STYLE,
294	403
295		/** The block sequence style. */
	404	/* The flow sequence style. */
	405	YAML_FLOW_SEQUENCE_STYLE
	406	/* The block sequence style. */
296	407	YAML_BLOCK_SEQUENCE_STYLE,
297		~~/** The flow sequence style. */~~
298		~~YAML_FLOW_SEQUENCE_STYLE~~
299	408	} yaml_sequence_style_t;
300	409
301		/** Mapping styles. */
	410	/*
	411	* Mapping styles.
	412	*
	413	* YAML supports two mapping styles: flow and block.
	414	*
	415	* The parser reports the style of a mapping node, but this information should
	416	* not be used in interpreting the mapping content.
	417	*
	418	* An application may suggest a preferred mapping style or leave it completely
	419	* to the emitter discretion. Note that the emitter may ignore any stylistic
	420	* hints.
	421	*/
	422
302	423	typedef enum yaml_mapping_style_e {
303		/** Let the emitter choose the style. */
	424	/* Let the emitter choose the style. */
304	425	YAML_ANY_MAPPING_STYLE,
305	426
306		/** The block mapping style. */
	427	/* The block mapping style. */
307	428	YAML_BLOCK_MAPPING_STYLE,
308		/** The flow mapping style. */
	429	/* The flow mapping style. */
309	430	YAML_FLOW_MAPPING_STYLE
310		~~/* YAML_FLOW_SET_MAPPING_STYLE */~~
311	431	} yaml_mapping_style_t;
312	432
313		/** @} */
314
315		/**
316		* @defgroup tokens Tokens
317		* @{
318		*/
319
320		/** Token types. */
	433	/******************************************************************************
	434	* Tokens
	435	******************************************************************************/
	436
	437	/*
	438	* Token types.
	439	*
	440	* The LibYAML scanner generates the following types of tokens:
	441	*
	442	* - STREAM-START: indicates the beginning of the stream.
	443	*
	444	* - STREAM-END: indicates the end of the stream.
	445	*
	446	* - VERSION-DIRECTIVE: describes the `%YAML` directive.
	447	*
	448	* - TAG-DIRECTIVE: describes the `%TAG` directive.
	449	*
	450	* - DOCUMENT-START: the indicator `---`.
	451	*
	452	* - DOCUMENT-END: the indicator `...`.
	453	*
	454	* - BLOCK-SEQUENCE-START: indentation increase indicating the beginning of a
	455	* block sequence node.
	456	*
	457	* - BLOCK-MAPPING-START: indentation increase indicating the beginning of a
	458	* block mapping node.
	459	*
	460	* - BLOCK-END: indentation decrease indicating the end of a block collection
	461	* node.
	462	*
	463	* - FLOW-SEQUENCE-START: the indicator `[`.
	464	*
	465	* - FLOW-SEQUENCE-END: the indicator `]`.
	466	*
	467	* - FLOW-MAPPING-START: the indicator `{`.
	468	*
	469	* - FLOW-MAPPING-END: the indicator `}`.
	470	*
	471	* - BLOCK-ENTRY: the beginning of an item of a block sequence.
	472	*
	473	* - FLOW-ENTRY: the beginning of an item of a flow sequence.
	474	*
	475	* - KEY: the beginning of a simple key, or the indicator `?`.
	476	*
	477	* - VALUE: the indicator `:`.
	478	*
	479	* - ALIAS: an alias of a node.
	480	*
	481	* - ANCHOR: a node anchor.
	482	*
	483	* - TAG: a node tag.
	484	*
	485	* - SCALAR: the content of a scalar node.
	486	*/
	487
321	488	typedef enum yaml_token_type_e {
322		/** An empty token. */
	489	/* An empty unitialized token. */
323	490	YAML_NO_TOKEN,
324	491
325		/** A STREAM-START token. */
	492	/* A STREAM-START token. */
326	493	YAML_STREAM_START_TOKEN,
327		/** A STREAM-END token. */
	494	/* A STREAM-END token. */
328	495	YAML_STREAM_END_TOKEN,
329	496
330		/** A VERSION-DIRECTIVE token. */
	497	/* A VERSION-DIRECTIVE token. */
331	498	YAML_VERSION_DIRECTIVE_TOKEN,
332		/** A TAG-DIRECTIVE token. */
	499	/* A TAG-DIRECTIVE token. */
333	500	YAML_TAG_DIRECTIVE_TOKEN,
334		/** A DOCUMENT-START token. */
	501	/* A DOCUMENT-START token. */
335	502	YAML_DOCUMENT_START_TOKEN,
336		/** A DOCUMENT-END token. */
	503	/* A DOCUMENT-END token. */
337	504	YAML_DOCUMENT_END_TOKEN,
338	505
339		/** A BLOCK-SEQUENCE-START token. */
	506	/* A BLOCK-SEQUENCE-START token. */
340	507	YAML_BLOCK_SEQUENCE_START_TOKEN,
341		/** A BLOCK-SEQUENCE-END token. */
	508	/* A BLOCK-SEQUENCE-END token. */
342	509	YAML_BLOCK_MAPPING_START_TOKEN,
343		/** A BLOCK-END token. */
	510	/* A BLOCK-END token. */
344	511	YAML_BLOCK_END_TOKEN,
345	512
346		/** A FLOW-SEQUENCE-START token. */
	513	/* A FLOW-SEQUENCE-START token. */
347	514	YAML_FLOW_SEQUENCE_START_TOKEN,
348		/** A FLOW-SEQUENCE-END token. */
	515	/* A FLOW-SEQUENCE-END token. */
349	516	YAML_FLOW_SEQUENCE_END_TOKEN,
350		/** A FLOW-MAPPING-START token. */
	517	/* A FLOW-MAPPING-START token. */
351	518	YAML_FLOW_MAPPING_START_TOKEN,
352		/** A FLOW-MAPPING-END token. */
	519	/* A FLOW-MAPPING-END token. */
353	520	YAML_FLOW_MAPPING_END_TOKEN,
354	521
355		/** A BLOCK-ENTRY token. */
	522	/* A BLOCK-ENTRY token. */
356	523	YAML_BLOCK_ENTRY_TOKEN,
357		/** A FLOW-ENTRY token. */
	524	/* A FLOW-ENTRY token. */
358	525	YAML_FLOW_ENTRY_TOKEN,
359		/** A KEY token. */
	526	/* A KEY token. */
360	527	YAML_KEY_TOKEN,
361		/** A VALUE token. */
	528	/* A VALUE token. */
362	529	YAML_VALUE_TOKEN,
363	530
364		/** An ALIAS token. */
	531	/* An ALIAS token. */
365	532	YAML_ALIAS_TOKEN,
366		/** An ANCHOR token. */
	533	/* An ANCHOR token. */
367	534	YAML_ANCHOR_TOKEN,
368		/** A TAG token. */
	535	/* A TAG token. */
369	536	YAML_TAG_TOKEN,
370		/** A SCALAR token. */
	537	/* A SCALAR token. */
371	538	YAML_SCALAR_TOKEN
372	539	} yaml_token_type_t;
373	540
374		/** The token structure. */
	541	/*
	542	* The token object.
	543	*
	544	* Typically the token API is too low-level to be used directly by
	545	* applications. A possible user of the token API is a syntax highlighting
	546	* application.
	547	*/
	548
375	549	typedef struct yaml_token_s {
376	550
377		/** The token type. */
	551	/* The token type. */
378	552	yaml_token_type_t type;
379	553
380		/** The token data. */
	554	/* The token data. */
381	555	union {
382	556
383		/** The stream start (for @c YAML_STREAM_START_TOKEN). */
	557	/* Extra data associated with a STREAM-START token. */
384	558	struct {
385		/** The stream encoding. */
	559	/* The stream encoding. */
386	560	yaml_encoding_t encoding;
387	561	} stream_start;
388	562
389		/** The version directive (for @c YAML_VERSION_DIRECTIVE_TOKEN). */
	563	/* Extra data associated with a VERSION-DIRECTIVE token. */
390	564	struct {
391		/** The major version number. */
	565	/* The major version number. */
392	566	int major;
393		/** The minor version number. */
	567	/* The minor version number. */
394	568	int minor;
395	569	} version_directive;
396	570
397		/** The tag directive (for @c YAML_TAG_DIRECTIVE_TOKEN). */
	571	/* Extra data associated with a TAG-DIRECTIVE token. */
398	572	struct {
399		/** The tag handle. */
	573	/* The tag handle. */
400	574	yaml_char_t *handle;
401		/** The tag prefix. */
	575	/* The tag prefix. */
402	576	yaml_char_t *prefix;
403	577	} tag_directive;
404	578
405		/** The alias (for @c YAML_ALIAS_TOKEN). */
	579	/* Extra data associated with an ALIAS token. */
406	580	struct {
407		/** The alias value. */
	581	/* The alias value. */
408	582	yaml_char_t *value;
409	583	} alias;
410	584
411		/** The anchor (for @c YAML_ANCHOR_TOKEN). */
	585	/* Extra data associated with an ANCHOR token. */
412	586	struct {
413		/** The anchor value. */
	587	/* The anchor value. */
414	588	yaml_char_t *value;
415	589	} anchor;
416	590
417		/** The tag (for @c YAML_TAG_TOKEN). */
	591	/* Extra data associated with a TAG token. */
418	592	struct {
419		/** The tag handle. */
	593	/* The tag handle. */
420	594	yaml_char_t *handle;
421		/** The tag suffix. */
	595	/* The tag suffix. */
422	596	yaml_char_t *suffix;
423	597	} tag;
424	598
425		/** The scalar value (for @c YAML_SCALAR_TOKEN). */
	599	/* Extra data associated with a SCALAR token. */
426	600	struct {
427		/** The scalar value. */
	601	/* The scalar value. */
428	602	yaml_char_t *value;
429		/** The length of the scalar value. */
	603	/* The length of the scalar value. */
430	604	size_t length;
431		/** The scalar style. */
	605	/* The scalar style. */
432	606	yaml_scalar_style_t style;
433	607	} scalar;
…	…
435	609	} data;
436	610
437		/** The beginning of the token. */
	611	/* The beginning of the token. */
438	612	yaml_mark_t start_mark;
439		/** The end of the token. */
	613	/* The end of the token. */
440	614	yaml_mark_t end_mark;
441	615
442	616	} yaml_token_t;
443	617
444		/**
	618	/*
445	619	* Allocate a new empty token object.
446	620	*
447		* @returns a new token object or @c NULL on error.
	621	* A token object allocated using this function must be deleted with
	622	* `yaml_token_delete()`.
	623	*
	624	* Returns: a new empty token object or `NULL` on error. The function may fail
	625	* if it cannot allocate memory for a new token object.
448	626	*/
449	627
…	…
451	629	yaml_token_new(void);
452	630
453		/**
454		* Delete and deallocate a token object.
455		*
456		* @param[in,out] token A token object.
	631	/*
	632	* Deallocate a token object and free the associated data.
	633	*
	634	* A token object must be previously allocated with `yaml_token_new()`.
	635	*
	636	* Arguments:
	637	*
	638	* - `token`: a token object to be deallocated.
457	639	*/
458	640
…	…
460	642	yaml_token_delete(yaml_token_t *token);
461	643
462		/**
	644	/*
463	645	* Duplicate a token object.
464	646	*
465		* @param[in,out] token An empty token object.
466		* @param[in] model A token to copy.
467		*
468		* @returns @c 1 if the function succeeded, @c 0 on error.
	647	* This function creates a deep copy of an existing token object. It accepts
	648	* two token objects: an empty token and a model token. The latter is supposed
	649	* to be initialized with `yaml_parser_parse_token()`. The function assigns
	650	* the type of the model to the empty token as well as duplicates and copies
	651	* the internal state associated with the model token.
	652	*
	653	* Arguments:
	654	*
	655	* - `token`: an empty token object.
	656	*
	657	* - `model`: a token to be copied.
	658	*
	659	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	660	* allocate memory for duplicating the state of the model token. In that case,
	661	* the token remains empty.
469	662	*/
470	663
…	…
472	665	yaml_token_duplicate(yaml_token_t token, const yaml_token_t model);
473	666
474		/**
475		* Free any memory allocated for a token object.
476		*
477		* @param[in,out] token A token object.
	667	/*
	668	* Clear the token state.
	669	*
	670	* This function clears the type and the internal state of a token object
	671	* freeing any associated data. After applying this function to a token, it
	672	* becomes empty. It is supposed that the token was previously initialized
	673	* using `yaml_parser_parse_token()` or `yaml_token_duplicate()`.
	674	*
	675	* Arguments:
	676	*
	677	* - `token`: a token object.
478	678	*/
479	679
480	680	YAML_DECLARE(void)
481		yaml_token_destroy(yaml_token_t *token);
482
483		/** @} */
484
485		/**
486		* @defgroup events Events
487		* @{
488		*/
489
490		/** Event types. */
	681	yaml_token_clear(yaml_token_t *token);
	682
	683	/******************************************************************************
	684	* Events
	685	******************************************************************************/
	686
	687	/*
	688	* Event types.
	689	*
	690	* The LibYAML parser generates, while the LibYAML emitter accepts, YAML events
	691	* of the following types:
	692	*
	693	* - STREAM-START: indicates the beginning of the stream.
	694	*
	695	* - STREAM-END: indicates the end of the stream.
	696	*
	697	* - DOCUMENT-START: indicates the beginning of the document.
	698	*
	699	* - DOCUMENT-END: indicates the end of the document.
	700	*
	701	* - ALIAS: an alias to an already produced node.
	702	*
	703	* - SCALAR: a scalar node.
	704	*
	705	* - SEQUENCE-START: indicates the beginning of a sequence node.
	706	*
	707	* - SEQUENCE-END: indicates the end of a sequence node.
	708	*
	709	* - MAPPING-START: indicates the beginning of a mapping node.
	710	*
	711	* - MAPPING-END: indicates the end of a mapping node.
	712	*
	713	* A valid sequence of events obeys the grammar:
	714	*
	715	* stream ::= STREAM-START document* STREAM-END
	716	* document ::= DOCUMENT-START node DOCUMENT-END
	717	* node ::= ALIAS \| SCALAR \| sequence \| mapping
	718	* sequence ::= SEQUENCE-START node* SEQUENCE-END
	719	* mapping ::= MAPPING-START (node node)* MAPPING-END
	720	*/
	721
491	722	typedef enum yaml_event_type_e {
492		/** An empty event. */
	723	/* An empty unitialized event. */
493	724	YAML_NO_EVENT,
494	725
495		/** A STREAM-START event. */
	726	/* A STREAM-START event. */
496	727	YAML_STREAM_START_EVENT,
497		/** A STREAM-END event. */
	728	/* A STREAM-END event. */
498	729	YAML_STREAM_END_EVENT,
499	730
500		/** A DOCUMENT-START event. */
	731	/* A DOCUMENT-START event. */
501	732	YAML_DOCUMENT_START_EVENT,
502		/** A DOCUMENT-END event. */
	733	/* A DOCUMENT-END event. */
503	734	YAML_DOCUMENT_END_EVENT,
504	735
505		/** An ALIAS event. */
	736	/* An ALIAS event. */
506	737	YAML_ALIAS_EVENT,
507		/** A SCALAR event. */
	738	/* A SCALAR event. */
508	739	YAML_SCALAR_EVENT,
509	740
510		/** A SEQUENCE-START event. */
	741	/* A SEQUENCE-START event. */
511	742	YAML_SEQUENCE_START_EVENT,
512		/** A SEQUENCE-END event. */
	743	/* A SEQUENCE-END event. */
513	744	YAML_SEQUENCE_END_EVENT,
514	745
515		/** A MAPPING-START event. */
	746	/* A MAPPING-START event. */
516	747	YAML_MAPPING_START_EVENT,
517		/** A MAPPING-END event. */
	748	/* A MAPPING-END event. */
518	749	YAML_MAPPING_END_EVENT
519	750	} yaml_event_type_t;
520	751
521		/** The event structure. */
	752	/*
	753	* The event object.
	754	*
	755	* The event-level API of LibYAML should be used for streaming applications.
	756	*/
	757
522	758	typedef struct yaml_event_s {
523	759
524		/** The event type. */
	760	/* The event type. */
525	761	yaml_event_type_t type;
526	762
527		/** The event data. */
	763	/* The event data. */
528	764	union {
529	765
530		/** The stream parameters (for @c YAML_STREAM_START_EVENT). */
	766	/* The stream parameters (for `YAML_STREAM_START_EVENT`). */
531	767	struct {
532		/** The document encoding. */
	768	/* The document encoding. */
533	769	yaml_encoding_t encoding;
534	770	} stream_start;
535	771
536		/** The document parameters (for @c YAML_DOCUMENT_START_EVENT). */
	772	/* The document parameters (for `YAML_DOCUMENT_START_EVENT`). */
537	773	struct {
538		/** The version directive. */
	774	/* The version directive or `NULL` if not present. */
539	775	yaml_version_directive_t *version_directive;
540	776
541		/** The list of tag directives. */
	777	/* The list of tag directives. */
542	778	struct {
543		/** The beginning of the list. */
	779	/* The beginning of the list or `NULL`. */
544	780	yaml_tag_directive_t *list;
545		/** The length of the list. */
	781	/* The length of the list. */
546	782	size_t length;
547		/** The capacity of the list. */
	783	/* The capacity of the list (used internally). */
548	784	size_t capacity;
549	785	} tag_directives;
550	786
551		/** Is the document indicator implicit? */
	787	/* Set if the document indicator is omitted. */
552	788	int is_implicit;
553	789	} document_start;
554	790
555		/** The document end parameters (for @c YAML_DOCUMENT_END_EVENT). */
	791	/* The document end parameters (for `YAML_DOCUMENT_END_EVENT`). */
556	792	struct {
557		/** Is the document end indicator implicit? */
	793	/* Set if the document end indicator is omitted. */
558	794	int is_implicit;
559	795	} document_end;
560	796
561		/** The alias parameters (for @c YAML_ALIAS_EVENT). */
	797	/* The alias parameters (for `YAML_ALIAS_EVENT`). */
562	798	struct {
563		/** The anchor. */
	799	/* The anchor. */
564	800	yaml_char_t *anchor;
565	801	} alias;
566	802
567		/** The scalar parameters (for @c YAML_SCALAR_EVENT). */
	803	/* The scalar parameters (for `YAML_SCALAR_EVENT`). */
568	804	struct {
569		/** The anchor. */
	805	/* The node anchor or `NULL`. */
570	806	yaml_char_t *anchor;
571		/** The tag. */
	807	/* The node tag or `NULL`. */
572	808	yaml_char_t *tag;
573		/** The scalar value. */
	809	/* The scalar value. */
574	810	yaml_char_t *value;
575		/** The length of the scalar value. */
	811	/* The length of the scalar value (in bytes). */
576	812	size_t length;
577		/** Is the tag optional for the plain style? */
578		int is_plain_~~implicit~~;
579		/** Is the tag optional for any non-plain style? */
580		int is_quoted_~~implicit~~;
581		/** The scalar style. */
	813	/* Set if the tag is optional for the plain style. */
	814	int is_plain_nonspecific;
	815	/* Set if the tag is optional for any non-plain style. */
	816	int is_quoted_nonspecific;
	817	/* The scalar style. */
582	818	yaml_scalar_style_t style;
583	819	} scalar;
584	820
585		/** The sequence parameters (for @c YAML_SEQUENCE_START_EVENT). */
	821	/* The sequence parameters (for `YAML_SEQUENCE_START_EVENT`). */
586	822	struct {
587		/** The anchor. */
	823	/* The node anchor or `NULL`. */
588	824	yaml_char_t *anchor;
589		/** The tag. */
	825	/* The node tag or `NULL`. */
590	826	yaml_char_t *tag;
591		/** Is the tag optional? */
592		int is_~~implicit~~;
593		/** The sequence style. */
	827	/* Set if the tag is optional. */
	828	int is_nonspecific;
	829	/* The sequence style. */
594	830	yaml_sequence_style_t style;
595	831	} sequence_start;
596	832
597		/** The mapping parameters (for @c YAML_MAPPING_START_EVENT). */
	833	/* The mapping parameters (for `YAML_MAPPING_START_EVENT`). */
598	834	struct {
599		/** The anchor. */
	835	/* The node anchor or `NULL`. */
600	836	yaml_char_t *anchor;
601		/** The tag. */
	837	/* The node tag or `NULL`. */
602	838	yaml_char_t *tag;
603		/** Is the tag optional? */
604		int is_~~implicit~~;
605		/** The mapping style. */
	839	/* Set if the tag is optional. */
	840	int is_nonspecific;
	841	/* The mapping style. */
606	842	yaml_mapping_style_t style;
607	843	} mapping_start;
…	…
609	845	} data;
610	846
611		/** The beginning of the event. */
	847	/* The beginning of the event. */
612	848	yaml_mark_t start_mark;
613		/** The end of the event. */
	849	/* The end of the event. */
614	850	yaml_mark_t end_mark;
615	851
616	852	} yaml_event_t;
617	853
618		/**
	854	/*
619	855	* Allocate a new empty event object.
620	856	*
621		* @returns a new event object or @c NULL on error.
	857	* An event object allocated using this function must be deleted with
	858	* `yaml_event_delete()`.
	859	*
	860	* Returns: a new empty event object or `NULL` on error. The function may fail
	861	* if it cannot allocate memory for a new event object.
622	862	*/
623	863
…	…
625	865	yaml_event_new(void);
626	866
627		/**
628		* Delete and deallocate an event object.
629		*
630		* @param[in,out] event An event object.
	867	/*
	868	* Deallocate an event object and free the associated data.
	869	*
	870	* An event object must be previously allocated with `yaml_event_new()`.
	871	*
	872	* Arguments:
	873	*
	874	* - `event`: an event object to be deallocated.
631	875	*/
632	876
…	…
634	878	yaml_event_delete(yaml_event_t *event);
635	879
636		/**
637		* Duplicate a event object.
638		*
639		* @param[in,out] event An empty event object.
640		* @param[in] model An event to copy.
641		*
642		* @returns @c 1 if the function succeeded, @c 0 on error.
	880	/*
	881	* Duplicate an event object.
	882	*
	883	* This function creates a deep copy of an existing event object. It accepts
	884	* two objects: an empty event and a model event. The model event is supposed
	885	* to be initialized either with `yaml_parser_parse_event()` or using one of
	886	* the functions `yaml_event_create_*()`. The function assigns the type of the
	887	* model to the empty event and copies the internal state associated with the
	888	* model event.
	889	*
	890	* Arguments:
	891	*
	892	* - `event`: an empty event object.
	893	*
	894	* - `model`: an event to be copied.
	895	*
	896	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	897	* allocate memory for duplicating the state of the model event. In that case,
	898	* the event remains empty.
643	899	*/
644	900
…	…
646	902	yaml_event_duplicate(yaml_event_t event, const yaml_event_t model);
647	903
648		/**
	904	/*
	905	* Clear the event state.
	906	*
	907	* This function clears the type and the internal state of an event object
	908	* freeing any associated data. After applying this function to an event, it
	909	* becomes empty. It is supposed that the event was previously initialized
	910	* using `yaml_parser_parse_event()` or `yaml_event_duplicate()`. Note that
	911	* the function `yaml_emitter_emit_event()` also clears the given event.
	912	*
	913	* Arguments:
	914	*
	915	* - `event`: an event object.
	916	*/
	917
	918	YAML_DECLARE(void)
	919	yaml_event_clear(yaml_event_t *event);
	920
	921	/*
649	922	* Create a STREAM-START event.
650	923	*
651		* This function never fails.
652		*
653		* @param[out] event An empty event object.
654		* @param[in] encoding The stream encoding.
655		*
656		* @returns @c 1 if the function succeeded, @c 0 on error.
	924	* This function initializes an empty event object allocated with
	925	* `yaml_event_new()`. The initialized event could be fed to
	926	* `yaml_emitter_emit_event()`.
	927	*
	928	* Arguments:
	929	*
	930	* - `event`: an empty event object.
	931	*
	932	* - `encoding`: the stream encoding.
	933	*
	934	* Returns: `1`. The function never fails.
657	935	*/
658	936
…	…
661	939	yaml_encoding_t encoding);
662	940
663		/**
	941	/*
664	942	* Create a STREAM-END event.
665	943	*
666		* This function never fails.
667		*
668		* @param[out] event An empty event object.
669		*
670		* @returns @c 1 if the function succeeded, @c 0 on error.
	944	* This function initializes an empty event object allocated with
	945	* `yaml_event_new()`. The initialized event could be fed to
	946	* `yaml_emitter_emit_event()`.
	947	*
	948	* Arguments:
	949	*
	950	* - `event`: an empty event object.
	951	*
	952	* Returns: `1`. The function never fails.
671	953	*/
672	954
…	…
674	956	yaml_event_create_stream_end(yaml_event_t *event);
675	957
676		/**
677		* Create the DOCUMENT-START event.
678		*
679		* @param[out] event An empty event object.
680		* @param[in] version_directive The %YAML directive value or
681		* @c NULL.
682		* @param[in] tag_directives_list The beginning of the %TAG
683		* directives list or @c NULL. The
684		* list ends with @c (NULL,NULL).
685		* @param[in] is_implicit Set if the document start
686		* indicator is optional. This
687		* parameter is stylistic and may be
688		* ignored by the parser.
689		*
690		* @returns @c 1 if the function succeeded, @c 0 on error.
	958	/*
	959	* Create a DOCUMENT-START event.
	960	*
	961	* This function initializes an empty event object allocated with
	962	* `yaml_event_new()`. The initialized event could be fed to
	963	* `yaml_emitter_emit_event()`.
	964	*
	965	* Arguments:
	966	*
	967	* - `event`: an empty event object.
	968	*
	969	* - `version_directive`: a structure specifying the content of the `%YAML`
	970	* directive or `NULL` if the directive could be omitted. Note that LibYAML
	971	* supports YAML 1.1 only. The function does not check if the supplied
	972	* version equals to 1.1, but the emitter will fail to emit the event if it
	973	* is not so.
	974	*
	975	* - `tag_directives_list`: a pointer to a list specifying the content of the
	976	* `%TAG` directives associated with the document or `NULL` if the document
	977	* does not contain `%TAG` directives. The content of a tag directive is a
	978	* pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings. The tag
	979	* handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_`
	980	* and `-` surrounded by `!`. The tag prefix is a prefix of any valid tag,
	981	* that is, it is a non-empty prefix of either a global tag (a valid URI) or
	982	* a local tag (an arbitrary string starting with `!`). The function does
	983	* not check if the given directive values satisfy these requirements, but
	984	* the emitter will fail to emit the event if they are not met.
	985	*
	986	* - `tag_directives_length`: the length of `tag_directives_list`; `0` if
	987	* `tag_directives_list` is `NULL`.
	988	*
	989	* - `is_implicit`: `1` if the document indicator `---` is omitted, `0`
	990	* otherwise. Note that this attribute is only a stylistic hint and could be
	991	* ignored by the emitter.
	992	*
	993	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	994	* allocate memory for duplicating the event parameters. In this case, the
	995	* event remains empty.
691	996	*/
692	997
…	…
694	999	yaml_event_create_document_start(yaml_event_t *event,
695	1000	const yaml_version_directive_t *version_directive,
696		const yaml_tag_directive_t *tag_directives,
	1001	const yaml_tag_directive_t *tag_directives_list,
	1002	size_t tag_directives_length,
697	1003	int is_implicit);
698	1004
699		/**
700		* Create the DOCUMENT-END event.
701		*
702		* @param[out] event An empty event object.
703		* @param[in] is_implicit Set if the document end indicator is optional.
704		* This parameter is stylistic and may be ignored
705		* by the parser.
706		*
707		* @returns @c 1 if the function succeeded, @c 0 on error.
	1005	/*
	1006	* Create a DOCUMENT-END event.
	1007	*
	1008	* This function initializes an empty event object allocated with
	1009	* `yaml_event_new()`. The initialized event could be fed to
	1010	* `yaml_emitter_emit_event()`.
	1011	*
	1012	* Arguments:
	1013	*
	1014	* - `event`: an empty event object.
	1015	*
	1016	* - `is_implicit`: `1` if the document end indicator `...` is omitted, `0`
	1017	* otherwise. Note that this attribute is only a stylistic hint and could be
	1018	* ignored by the emitter.
	1019	*
	1020	* Returns: `1`. The function never fails.
708	1021	*/
709	1022
…	…
711	1024	yaml_event_create_document_end(yaml_event_t *event, int is_implicit);
712	1025
713		/**
714		* Create an ALIAS event.
715		*
716		* @param[out] event An empty event object.
717		* @param[in] anchor The anchor value.
718		*
719		* @returns @c 1 if the function succeeded, @c 0 on error.
	1026	/*
	1027	* Create an ANCHOR event.
	1028	*
	1029	* This function initializes an empty event object allocated with
	1030	* `yaml_event_new()`. The initialized event could be fed to
	1031	* `yaml_emitter_emit_event()`.
	1032	*
	1033	* Arguments:
	1034	*
	1035	* - `event`: an empty event object.
	1036	*
	1037	* - `anchor`: the anchor value. The anchor should be a non-empty
	1038	* NUL-terminated string containing only alphanumerical characters, `_`, and
	1039	* `-`. The function does not check if this requirement is satisfied, but if
	1040	* it is not so, the emitter will fail to emit the generated event.
	1041	*
	1042	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1043	* allocate memory for duplicating `anchor`. In this case, the event remains
	1044	* empty.
720	1045	*/
721	1046
…	…
723	1048	yaml_event_create_alias(yaml_event_t event, const yaml_char_t anchor);
724	1049
725		/**
	1050	/*
726	1051	* Create a SCALAR event.
727	1052	*
728		* @param[out] event An empty event object.
729		* @param[in] anchor The scalar anchor or @c NULL.
730		* @param[in] tag The scalar tag or @c NULL. If
731		* latter, one of the
732		* @a is_plain_implicit and
733		* @a is_quoted_implicit flags must
734		* be set.
735		* @param[in] value The scalar value.
736		* @param[in] length The length of the scalar value.
737		* @param[in] is_plain_implicit Set if the tag may be omitted for
738		* the plain style.
739		* @param[in] is_quoted_implicit Set if the tag may be omitted for
740		* any non-plain style.
741		* @param[in] style The scalar style. This attribute
742		* may be ignored by the emitter.
743		*
744		* @returns @c 1 if the function succeeded, @c 0 on error.
	1053	* This function initializes an empty event object allocated with
	1054	* `yaml_event_new()`. The initialized event could be fed to
	1055	* `yaml_emitter_emit_event()`.
	1056	*
	1057	* Arguments:
	1058	*
	1059	* - `event`: an empty event object.
	1060	*
	1061	* - `anchor`: the anchor value or `NULL`. The anchor should be a non-empty
	1062	* NUL-terminated string containing only alphanumerical characters, `_`, and
	1063	* `-`.
	1064	*
	1065	* - `tag`: the tag value or `NULL`. The tag should be a non-empty UTF-8
	1066	* NUL-terminated string. The tag could be global (a valid URI) or local (an
	1067	* arbitrary string starting with `!`). If `NULL` is provided, at least one
	1068	* of the flags `is_plain_nonspecific` and `is_quoted_nonspecific` must be
	1069	* set. The function does not check whether these requirements are
	1070	* satisfied, but the emitter will fail to emit the event if it is not so.
	1071	*
	1072	* - `value`: the value of the scalar node. The value should be a UTF-8
	1073	* string. It could contain any valid UTF-8 character including NUL. The
	1074	* function does not check if `value` is a valid UTF-8 string, but the
	1075	* emitter will fail to emit the event if it is not so.
	1076	*
	1077	* - `length`: the length of the scalar value (in bytes) or `-1`. If `length`
	1078	* is set to `-1`, the `value` is assumed to be NUL-terminated.
	1079	*
	1080	* - `is_plain_nonspecific`: `1` if the node tag could be omitted while
	1081	* emitting the node provided that the the plain style is used for
	1082	* representing the node value; `0` otherwise. That this flag is set assumes
	1083	* that the tag could be correctly determined by the parser using the node
	1084	* position and content.
	1085	*
	1086	* - `is_quoted_nonspecific`: `1` if the node tag could be omitted while
	1087	* emitting the node provided that the node value is represented using any
	1088	* non-plain style; `0` otherwise. That this flag is set assumes that the
	1089	* tag could be correctly determined by the parser using the node position
	1090	* and content.
	1091	*
	1092	* - `style`: the node style. Note that this attribute only serves as a hint
	1093	* and may be ignored by the emitter.
	1094	*
	1095	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1096	* allocate memory for duplicating the given string buffers. In this case, the
	1097	* event remains empty.
745	1098	*/
746	1099
…	…
748	1101	yaml_event_create_scalar(yaml_event_t *event,
749	1102	const yaml_char_t anchor, const yaml_char_t tag,
750		const yaml_char_t *value, ~~size_~~t length,
751		int is_plain_~~implicit, int is_quoted_implicit~~,
	1103	const yaml_char_t *value, int length,
	1104	int is_plain_nonspecific, int is_quoted_nonspecific,
752	1105	yaml_scalar_style_t style);
753	1106
754		/**
	1107	/*
755	1108	* Create a SEQUENCE-START event.
756	1109	*
757		* @param[out] event An empty event object.
758		* @param[in] anchor The sequence anchor or @c NULL.
759		* @param[in] tag The sequence tag or @c NULL. If latter, the
760		* @a is_implicit flag must be set.
761		* @param[in] is_implicit Set if the tag may be omitted.
762		* @param[in] style The sequence style. This attribute may be
763		* ignored by the parser.
764		*
765		* @returns @c 1 if the function succeeded, @c 0 on error.
	1110	* This function initializes an empty event object allocated with
	1111	* `yaml_event_new()`. The initialized event could be fed to
	1112	* `yaml_emitter_emit_event()`.
	1113	*
	1114	* Arguments:
	1115	*
	1116	* - `event`: an empty event object.
	1117	*
	1118	* - `anchor`: the anchor value or `NULL`. The anchor should be a non-empty
	1119	* NUL-terminated string containing only alphanumerical characters, `_`, and
	1120	* `-`. The function does not check if this requirement is satisfied, but if
	1121	* it is not so, the emitter will fail to emit the generated event.
	1122	*
	1123	* - `tag`: the tag value or `NULL`. The tag should be a non-empty UTF-8
	1124	* NUL-terminated string. The tag could be global (a valid URI) or local (an
	1125	* arbitrary string starting with `!`). If `NULL` is provided, the flag
	1126	* `is_nonspecific` must be set. The function does not check whether these
	1127	* requirements are satisfied, but if it is not so, the emitter will fail to
	1128	* emit the generated event.
	1129	*
	1130	* - `is_nonspecific`: `1` if the node tag could be omitted while
	1131	* emitting the node; `0` otherwise. This flag should only be set if the
	1132	* node tag could be correctly determined by the parser using the node
	1133	* position in the document graph.
	1134	*
	1135	* - `style`: the node style. Note that this attribute only serves as a hint
	1136	* and may be ignored by the emitter.
	1137	*
	1138	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1139	* allocate memory for duplicating the given string buffers. In this case, the
	1140	* event remains empty.
766	1141	*/
767	1142
…	…
769	1144	yaml_event_create_sequence_start(yaml_event_t *event,
770	1145	const yaml_char_t anchor, const yaml_char_t tag,
771		int is_~~implicit~~, yaml_sequence_style_t style);
772
773		/**
	1146	int is_nonspecific, yaml_sequence_style_t style);
	1147
	1148	/*
774	1149	* Create a SEQUENCE-END event.
775	1150	*
776		* @param[out] event An empty event object.
777		*
778		* @returns @c 1 if the function succeeded, @c 0 on error.
	1151	* This function initializes an empty event object allocated with
	1152	* `yaml_event_new()`. The initialized event could be fed to
	1153	* `yaml_emitter_emit_event()`.
	1154	*
	1155	* Arguments:
	1156	*
	1157	* - `event`: an empty event object.
	1158	*
	1159	* Returns: `1`. This function never fails.
779	1160	*/
780	1161
…	…
782	1163	yaml_event_create_sequence_end(yaml_event_t *event);
783	1164
784		/**
	1165	/*
785	1166	* Create a MAPPING-START event.
786	1167	*
787		* @param[out] event An empty event object.
788		* @param[in] anchor The mapping anchor or @c NULL.
789		* @param[in] tag The mapping tag or @c NULL. If latter, the
790		* @a is_implicit flag must be set.
791		* @param[in] is_implicit Set if the tag may be omitted.
792		* @param[in] style The mapping style.
793		*
794		* @returns @c 1 if the function succeeded, @c 0 on error.
	1168	* This function initializes an empty event object allocated with
	1169	* `yaml_event_new()`. The initialized event could be fed to
	1170	* `yaml_emitter_emit_event()`.
	1171	*
	1172	* Arguments:
	1173	*
	1174	* - `event`: an empty event object.
	1175	*
	1176	* - `anchor`: the anchor value or `NULL`. The anchor should be a non-empty
	1177	* NUL-terminated string containing only alphanumerical characters, `_`, and
	1178	* `-`. The function does not check if this requirement is satisfied, but if
	1179	* it is not so, the emitter will fail to emit the generated event.
	1180	*
	1181	* - `tag`: the tag value or `NULL`. The tag should be a non-empty UTF-8
	1182	* NUL-terminated string. The tag could be global (a valid URI) or local (an
	1183	* arbitrary string starting with `!`). If `NULL` is provided, the flag
	1184	* `is_nonspecific` must be set. The function does not check whether these
	1185	* requirements are satisfied, but if it is not so, the emitter will fail to
	1186	* emit the generated event.
	1187	*
	1188	* - `is_nonspecific`: `1` if the node tag could be omitted while
	1189	* emitting the node; `0` otherwise. This flag should only be set if the
	1190	* node tag could be correctly determined by the parser using the node
	1191	* position in the document graph.
	1192	*
	1193	* - `style`: the node style. Note that this attribute only serves as a hint
	1194	* and may be ignored by the emitter.
	1195	*
	1196	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1197	* allocate memory for duplicating the given string buffers. In this case, the
	1198	* event remains empty.
795	1199	*/
796	1200
…	…
798	1202	yaml_event_create_mapping_start(yaml_event_t *event,
799	1203	const yaml_char_t anchor, const yaml_char_t tag,
800		int is_~~implicit~~, yaml_mapping_style_t style);
801
802		/**
	1204	int is_nonspecific, yaml_mapping_style_t style);
	1205
	1206	/*
803	1207	* Create a MAPPING-END event.
804	1208	*
805		* @param[out] event An empty event object.
806		*
807		* @returns @c 1 if the function succeeded, @c 0 on error.
	1209	* This function initializes an empty event object allocated with
	1210	* `yaml_event_new()`. The initialized event could be fed to
	1211	* `yaml_emitter_emit_event()`.
	1212	*
	1213	* Arguments:
	1214	*
	1215	* - `event`: an empty event object.
	1216	*
	1217	* Returns: `1`. This function never fails.
808	1218	*/
809	1219
…	…
811	1221	yaml_event_create_mapping_end(yaml_event_t *event);
812	1222
813		/**
814		* Free any memory allocated for an event object.
815		*
816		* @param[in,out] event An event object.
817		*/
818
819		YAML_DECLARE(void)
820		yaml_event_destroy(yaml_event_t *event);
821
822		/** @} */
823
824		/**
825		* @defgroup nodes Nodes
826		* @{
827		*/
828
829		/** The tag @c !!null with the only possible value: @c null. */
	1223	/******************************************************************************
	1224	* Documents and Nodes
	1225	******************************************************************************/
	1226
	1227	/*
	1228	* Well-known scalar tags.
	1229	*/
	1230
830	1231	#define YAML_NULL_TAG ((const yaml_char_t *) "tag:yaml.org,2002:null")
831		~~/** The tag @c !!bool with the values: @c true and @c falce. */~~
832	1232	#define YAML_BOOL_TAG ((const yaml_char_t *) "tag:yaml.org,2002:bool")
833		~~/** The tag @c !!str for string values. */~~
834	1233	#define YAML_STR_TAG ((const yaml_char_t *) "tag:yaml.org,2002:str")
835		~~/** The tag @c !!int for integer values. */~~
836	1234	#define YAML_INT_TAG ((const yaml_char_t *) "tag:yaml.org,2002:int")
837		~~/** The tag @c !!float for float values. */~~
838	1235	#define YAML_FLOAT_TAG ((const yaml_char_t *) "tag:yaml.org,2002:float")
839	1236
840		/** The tag @c !!seq is used to denote sequences. */
	1237	/*
	1238	* Basic collection tags.
	1239	*/
	1240
841	1241	#define YAML_SEQ_TAG ((const yaml_char_t *) "tag:yaml.org,2002:seq")
842		~~/** The tag @c !!map is used to denote mapping. */~~
843	1242	#define YAML_MAP_TAG ((const yaml_char_t *) "tag:yaml.org,2002:map")
844	1243
845		/** The default scalar tag is @c !!str. */
	1244	/*
	1245	* The default tags for nodes lacking an explicit tag.
	1246	*/
	1247
846	1248	#define YAML_DEFAULT_SCALAR_TAG YAML_STR_TAG
847		~~/** The default sequence tag is @c !!seq. */~~
848	1249	#define YAML_DEFAULT_SEQUENCE_TAG YAML_SEQ_TAG
849		~~/** The default mapping tag is @c !!map. */~~
850	1250	#define YAML_DEFAULT_MAPPING_TAG YAML_MAP_TAG
851	1251
852		/** Node types. */
	1252	/*
	1253	* Document types.
	1254	*
	1255	* There are no different document types in LibYAML: the document type field is
	1256	* only used to distinguish between newly allocated documents and those that
	1257	* are initialized with `yaml_parser_parse_document()` or
	1258	* `yaml_document_create()`.
	1259	*/
	1260
	1261	typedef enum yaml_document_type_e {
	1262	/* An empty uninitialized document. */
	1263	YAML_NO_DOCUMENT.
	1264
	1265	/* A YAML document. */
	1266	YAML_DOCUMENT
	1267	} yaml_document_type_t;
	1268
	1269	/*
	1270	* Node types.
	1271	*
	1272	* YAML recognizes three kinds of nodes: scalar, sequence and mapping.
	1273	*/
	1274
853	1275	typedef enum yaml_node_type_e {
854		/** An empty node. */
	1276	/* An empty node. */
855	1277	YAML_NO_NODE,
856	1278
857		/** A scalar node. */
	1279	/* A scalar node. */
858	1280	YAML_SCALAR_NODE,
859		/** A sequence node. */
	1281	/* A sequence node. */
860	1282	YAML_SEQUENCE_NODE,
861		/** A mapping node. */
	1283	/* A mapping node. */
862	1284	YAML_MAPPING_NODE
863	1285	} yaml_node_type_t;
864	1286
865		/** Arc types. */
	1287	/*
	1288	* Arc types.
	1289	*
	1290	* Arcs are used to specify the path from the root node to a given node in the
	1291	* document graph. There are three kinds of arcs: an item in a sequence node,
	1292	* a key in a mapping node, and a value in a mapping node.
	1293	*/
	1294
866	1295	typedef enum yaml_arc_type_e {
867		/** An empty arc. */
	1296	/* An empty arc. */
868	1297	YAML_NO_ARC,
869	1298
870		/** An item of a sequence. */
	1299	/* An item of a sequence. */
871	1300	YAML_SEQUENCE_ITEM_ARC,
872		/** A key of a mapping. */
	1301	/* A key of a mapping. */
873	1302	YAML_MAPPING_KEY_ARC,
874		/** A value of a mapping. */
	1303	/* A value of a mapping. */
875	1304	YAML_MAPPING_VALUE_ARC
876	1305	} yaml_arc_type_t;
877	1306
878		/** The forward definition of a document node structure. */
879		typedef struct yaml_node_s yaml_node_t;
880
881		/** An element of a sequence node. */
	1307	/*
	1308	* An element of a sequence node.
	1309	*/
	1310
882	1311	typedef int yaml_node_item_t;
883	1312
884		/** An element of a mapping node. */
	1313	/*
	1314	* An element of a mapping node.
	1315	*/
	1316
885	1317	typedef struct yaml_node_pair_s {
886		/** The key of the element. */
	1318	/* A key in a mapping. */
887	1319	int key;
888		/** The value of the element. */
	1320	/* A value in a mapping. */
889	1321	int value;
890	1322	} yaml_node_pair_t;
891	1323
892		/** An element of a path in a YAML document. */
	1324	/*
	1325	* A path element.
	1326	*
	1327	* An arc is an element of a path from the root node to some other node in a
	1328	* YAML document. An arc consists of a collection node and information on how
	1329	* it is connected to the next node in the path. If the arc type is a sequence
	1330	* item, then the collection node is a sequence and the arc refers to the index
	1331	* in this sequence. If the arc type is a mapping key, then the collection
	1332	* node is a mapping. If the arc type is a mapping value, then the collection
	1333	* node is a mapping and the arc refers to the key associated to the value.
	1334	*/
	1335
893	1336	typedef struct yaml_arc_s {
894		/** The arc type. */
	1337
	1338	/* The arc type. */
895	1339	yaml_arc_type_t type;
896		/** The collection node. */
897		int node;
898		/** A pointer in the collection node. */
899		int item;
	1340
	1341	/* The tag of the collection node. */
	1342	yaml_char_t *tag;
	1343
	1344	/* The connection information. */
	1345	union {
	1346
	1347	/* The sequence item data (for `YAML_SEQUENCE_ITEM_ARC`). */
	1348	struct {
	1349	/* The index of the item in the sequence (starting from `0`). */
	1350	int index;
	1351	} item;
	1352
	1353	/* The mapping value data (for `YAML_MAPPING_VALUE_ARC`). */
	1354	struct {
	1355	/* The key associated with the value. */
	1356	struct {
	1357	/* The key node type. */
	1358	yaml_node_type_t type;
	1359	/* The key node tag. */
	1360	yaml_char_t *tag;
	1361	/* The key node details. */
	1362	union {
	1363	/* The scalar data (for a scalar key). */
	1364	struct {
	1365	/* The scalar value. */
	1366	yaml_char_t *value;
	1367	/* The scalar length. */
	1368	size_t length;
	1369	} scalar;
	1370	} data;
	1371	} key;
	1372	} value;
	1373	} data;
900	1374	} yaml_arc_t;
901	1375
902		/** The node structure. */
	1376	/*
	1377	* The node object.
	1378	*
	1379	* A node object represents a node in a YAML document graph. Node objects are
	1380	* created using the family of functions `yaml_document_add_*()`. Links
	1381	* between nodes are created using the functions `yaml_document_append_*()`. A
	1382	* node object is destroyed when the document containing it is destroyed.
	1383	*/
	1384
903	1385	struct yaml_node_s {
904	1386
905		/** The node type. */
	1387	/* The node type. */
906	1388	yaml_node_type_t type;
907	1389
908		/** The node anchor. */
	1390	/* The node anchor or `NULL`. */
909	1391	yaml_char_t *anchor;
910		/** The node tag. */
	1392	/* The node tag. */
911	1393	yaml_char_t *tag;
912	1394
913		/** The node data. */
	1395	/* The node data. */
914	1396	union {
915	1397
916		/** The scalar parameters (for @c YAML_SCALAR_NODE). */
	1398	/* The scalar parameters (for `YAML_SCALAR_NODE`). */
917	1399	struct {
918		/** The scalar value. */
	1400	/* The scalar value. */
919	1401	yaml_char_t *value;
920		/** The length of the scalar value. */
	1402	/* The length of the scalar value. */
921	1403	size_t length;
922		/** The scalar style. */
	1404	/* The scalar style. */
923	1405	yaml_scalar_style_t style;
924	1406	} scalar;
925	1407
926		/** The sequence parameters (for @c YAML_SEQUENCE_NODE). */
	1408	/* The sequence parameters (for `YAML_SEQUENCE_NODE`). */
927	1409	struct {
928		/** The list of sequence items. */
	1410	/* The list of sequence items. */
929	1411	struct {
930		/** The beginning of the list. */
	1412	/* The pointer to the beginning of the list. */
931	1413	yaml_node_item_t *list;
932		/** The length of the list. */
	1414	/* The length of the list. */
933	1415	size_t length;
934		/** The capacity of the list. */
	1416	/* The capacity of the list (used internally). */
935	1417	size_t capacity;
936	1418	} items;
937		/** The sequence style. */
	1419	/* The sequence style. */
938	1420	yaml_sequence_style_t style;
939	1421	} sequence;
940	1422
941		/** The mapping parameters (for @c YAML_MAPPING_NODE). */
	1423	/* The mapping parameters (for `YAML_MAPPING_NODE`). */
942	1424	struct {
943		/** The list of mapping pairs (key, value). */
	1425	/* The list of mapping pairs (key, value). */
944	1426	struct {
945		/** The beginning of the list. */
	1427	/** The pointer to the beginning of the list. */
946	1428	yaml_node_pair_t *list;
947		/** The length of the list. */
	1429	/* The length of the list. */
948	1430	size_t length;
949		/** The capacity of the list. */
	1431	/* The capacity of the list (used internally). */
950	1432	size_t capacity;
951	1433	} pairs;
952		/** The mapping style. */
	1434	/* The mapping style. */
953	1435	yaml_mapping_style_t style;
954	1436	} mapping;
…	…
956	1438	} data;
957	1439
958		/** The beginning of the node. */
	1440	/* The beginning of the node. */
959	1441	yaml_mark_t start_mark;
960		/** The end of the node. */
	1442	/* The end of the node. */
961	1443	yaml_mark_t end_mark;
962	1444
963	1445	};
964	1446
965		/** The incomplete node structure. */
	1447	/*
	1448	* The incomplete node object.
	1449	*
	1450	* This structure provides the information about a node that a tag resolver
	1451	* could use to determine the specific node tag. This information includes
	1452	* the path from the root node and the node content for scalar nodes.
	1453	*/
	1454
966	1455	typedef struct yaml_incomplete_node_s {
967	1456
968		/** The node type. */
	1457	/* The node type. */
969	1458	yaml_node_type_t type;
970	1459
971		/** The path to the new node. */
	1460	/* The path to the new node. */
972	1461	struct {
973		/** The beginning of the list. */
	1462	/* The pointer to the beginning of the list. */
974	1463	yaml_arc_t *list;
	1464	/* The length of the list. */
	1465	size_t length;
	1466	/* The capacity of the list (used internally). */
	1467	size_t capacity;
	1468	} path;
	1469
	1470	/* The node data. */
	1471	union {
	1472
	1473	/* The scalar parameters (for `YAML_SCALAR_NODE`). */
	1474	struct {
	1475	/* The scalar value. */
	1476	yaml_char_t *value;
	1477	/* The length of the scalar value. */
	1478	size_t length;
	1479	/* Set if the scalar is plain. */
	1480	int is_plain;
	1481	} scalar;
	1482
	1483	} data;
	1484
	1485	/* The position of the node. */
	1486	yaml_mark_t mark;
	1487
	1488	} yaml_incomplete_node_t;
	1489
	1490	/*
	1491	* The document object.
	1492	*
	1493	* A document object represents the main structure of the YAML object model:
	1494	* the document graph consisting of nodes of three kinds: scalars, sequences,
	1495	* and mappings with the selected root node.
	1496	*
	1497	* An empty document object is allocated using the function
	1498	* `yaml_document_new()`. Then the function `yaml_parser_parse_document()`
	1499	* could be used to load a YAML document from the input stream. Alternatively,
	1500	* a document could be created with `yaml_document_create()` and its content
	1501	* could be specified using the families of functions `yaml_document_add_*()`
	1502	* and `yaml_document_append_*()`. A document with all associated nodes could
	1503	* be destroyed using the function `yaml_document_delete()`.
	1504	*/
	1505
	1506	typedef struct yaml_document_s {
	1507
	1508	/* The document type. */
	1509	yaml_document_type_t type;
	1510
	1511	/* The document nodes (for internal use only). */
	1512	struct {
	1513	/* The pointer to the beginning of the list. */
	1514	yaml_node_t *list;
	1515	/* The length of the list. */
	1516	size_t length;
	1517	/* The capacity of the list. */
	1518	size_t capacity;
	1519	} nodes;
	1520
	1521	/* The version directive or `NULL`. */
	1522	yaml_version_directive_t *version_directive;
	1523
	1524	/* The list of tag directives. */
	1525	struct {
	1526	/* The pointer to the beginning of the list or `NULL`. */
	1527	yaml_tag_directive_t *list;
975	1528	/** The length of the list. */
976	1529	size_t length;
977		/** The capacity of the list. */
978		size_t capacity;
979		} path;
980
981		/** The node data. */
982		union {
983
984		/** The scalar parameters (for @c YAML_SCALAR_NODE). */
985		struct {
986		/** The scalar value. */
987		yaml_char_t *value;
988		/** The length of the scalar value. */
989		size_t length;
990		/** Set if the scalar is plain. */
991		int is_plain;
992		} scalar;
993
994		} data;
995
996		/** The position of the node. */
997		yaml_mark_t mark;
998
999		} yaml_incomplete_node_t;
1000
1001		/** The document structure. */
1002		typedef struct yaml_document_s {
1003
1004		/** The document nodes. */
1005		struct {
1006		/** The beginning of the list. */
1007		yaml_node_t *list;
1008		/** The length of the list. */
1009		size_t length;
1010		/** The capacity of the list. */
1011		size_t capacity;
1012		} nodes;
1013
1014		/** The version directive. */
1015		yaml_version_directive_t *version_directive;
1016
1017		/** The list of tag directives. */
1018		struct {
1019		/** The beginning of the tag directive list. */
1020		yaml_tag_directive_t *list;
1021		/** The length of the tag directive list. */
1022		size_t length;
1023		/** The capacity of the tag directive list. */
	1530	/** The capacity of the list (used internally). */
1024	1531	size_t capacity;
1025	1532	} tag_directives;
1026	1533
1027		/** ~~Is the document start indicator implicit?~~ */
	1534	/** Set if the document start indicator is implicit. */
1028	1535	int is_start_implicit;
1029		/** ~~Is the document end indicator implicit?~~ */
	1536	/** Set if the document end indicator is implicit. */
1030	1537	int is_end_implicit;
1031	1538
…	…
1037	1544	} yaml_document_t;
1038	1545
1039		#if 0
1040
1041		/**
	1546	/*
1042	1547	* Allocate a new empty document object.
1043	1548	*
1044		* @returns a new document object or @c NULL on error.
	1549	* A document object allocated using this function must be deleted with
	1550	* `yaml_document_delete()`.
	1551	*
	1552	* Returns: a new empty document object or `NULL` on error. The function may
	1553	* fail if it cannot allocate memory for a new object.
1045	1554	*/
1046	1555
…	…
1048	1557	yaml_document_new(void);
1049	1558
1050		/**
1051		* Delete and deallocatge a document object.
1052		*
1053		* @param[in,out] document A document object.
	1559	/*
	1560	* Deallocate a document object and free the associated data.
	1561	*
	1562	* A document object must be previously allocated with `yaml_document_new()`.
	1563	*
	1564	* Arguments:
	1565	*
	1566	* - `document`: a document object to be deallocated.
1054	1567	*/
1055	1568
…	…
1057	1570	yaml_document_delete(yaml_document_t *document);
1058	1571
1059		/**
	1572	/*
1060	1573	* Duplicate a document object.
1061	1574	*
1062		* @param[in,out] document An empty document object.
1063		* @param[in] model A document to copy.
1064		*
1065		* @returns @c 1 if the function succeeded, @c 0 on error.
	1575	* This function creates a complete copy of an existing document and all the
	1576	* nodes it contains. The function accepts two objects: an empty document and
	1577	* a model document. The model is supposed to be initialized either with
	1578	* `yaml_parser_parse_document()` or constructed manually. The functions
	1579	* duplicate the content of the document and its nodes and assigns it to the
	1580	* empty document.
	1581	*
	1582	* Arguments:
	1583	*
	1584	* - `document`: an empty document object.
	1585	*
	1586	* - `model`: a document to be copied.
	1587	*
	1588	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1589	* allocate memory for duplicating the state of the model. In that case, the
	1590	* document remains empty.
1066	1591	*/
1067	1592
…	…
1069	1594	yaml_document_duplicate(yaml_document_t document, yaml_document_t model);
1070	1595
1071		/**
	1596	/*
	1597	* Clear the document.
	1598	*
	1599	* This function clears the type of the document and destroys all the document
	1600	* nodes. After applying this function to a document, it becomes empty. It is
	1601	* supposed that the document was previously initialized using
	1602	* `yaml_parser_parse_document()` or created manually. Note that the function
	1603	* `yaml_emitter_emit_document()` also clears the given document.
	1604	*
	1605	* Arguments:
	1606	*
	1607	* - `document`: a document object.
	1608	*/
	1609
	1610	YAML_DECLARE(void)
	1611	yaml_document_clear(yaml_document_t *document);
	1612
	1613	/*
1072	1614	* Create a YAML document.
1073	1615	*
1074		* @param[out] document An empty document object.
1075		* @param[in] version_directive The %YAML directive value or
1076		* @c NULL.
1077		* @param[in] tag_directives The list of the %TAG directives or
1078		* @c NULL. The list must end with
1079		* the pair @c (NULL,NULL).
1080		* @param[in] is_start_implicit If the document start indicator is
1081		* implicit.
1082		* @param[in] is_end_implicit If the document end indicator is
1083		* implicit.
1084		*
1085		* @returns @c 1 if the function succeeded, @c 0 on error.
	1616	* This function initializes an empty document object allocated with
	1617	* `yaml_document_new()`. Further, nodes could be added to the document using
	1618	* the functions `yaml_document_add_()` and `yaml_document_append_()`. The
	1619	* initialized document could be fed to `yaml_emitter_emit_document()`.
	1620	*
	1621	* Arguments:
	1622	*
	1623	* - `document`: an empty document object.
	1624	*
	1625	* - `version_directive`: a structure specifying the content of the `%YAML`
	1626	* directive or `NULL` if the directive could be omitted. Note that LibYAML
	1627	* supports YAML 1.1 only. The constructor does not check if the supplied
	1628	* version equals to 1.1, but the emitter will fail to emit the document if
	1629	* it is not so.
	1630	*
	1631	* - `tag_directives_list`: a pointer to a list specifying the content of the
	1632	* `%TAG` directives associated with the document or `NULL` if the document
	1633	* does not contain `%TAG` directives. The content of a tag directive is a
	1634	* pair (handle, prefix) of non-empty NUL-terminated UTF-8 strings. The tag
	1635	* handle is one of `!`, `!!` or a sequence of alphanumeric characters, `_`
	1636	* and `-` surrounded by `!`. The tag prefix is a prefix of any valid tag,
	1637	* that is, it is a non-empty prefix of either a global tag (a valid URI) or
	1638	* a local tag (an arbitrary string starting with `!`). The constructor does
	1639	* not check if the given directive values satisfy these requirements, but
	1640	* the emitter will fail to emit the document if they are not met.
	1641	*
	1642	* - `tag_directives_length`: the length of `tag_directives_list`; `0` if
	1643	* `tag_directives_list` is `NULL`.
	1644	*
	1645	* - `is_start_implicit`: `1` if the document start indicator `---` is omitted;
	1646	* `0` otherwise. Note that this attribute is only a stylistic hint and
	1647	* could be ignored by the emitter.
	1648	*
	1649	* - `is_end_implicit`: `1` if the document end indicator `...` is omitted; `0`
	1650	* otherwise. Note that this attribute is only a stylistic hint and could be
	1651	* ignored by the emitter.
	1652	*
	1653	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1654	* allocate memory for duplicating the document parameters. In this case, the
	1655	* document remains empty.
1086	1656	*/
1087	1657
1088	1658	YAML_DECLARE(int)
1089	1659	yaml_document_create(yaml_document_t *document,
1090		yaml_version_directive_t *version_directive,
1091		yaml_tag_directive_t *tag_directives,
	1660	const yaml_version_directive_t *version_directive,
	1661	const yaml_tag_directive_t *tag_directives_list,
	1662	size_t tag_directives_length,
1092	1663	int is_start_implicit, int is_end_implicit);
1093
1094		/**
1095		* Delete a YAML document and all its nodes.
1096		*
1097		* @param[in,out] document A document object.
1098		*/
1099
1100		~~YAML_DECLARE(void)~~
1101		~~yaml_document_destroy(yaml_document_t *document);~~
1102	1664
1103	1665	/**
1104	1666	* Get a node of a YAML document.
1105	1667	*
	1668	* The root node of the document has the id `0`.
	1669	*
1106	1670	* The pointer returned by this function is valid until any of the functions
1107		* modifying the documents is called.
1108		*
1109		* @param[in] document A document object.
1110		* @param[in] index The node id.
1111		*
1112		* @returns the node objct or @c NULL if @c node_id is out of range.
	1671	* modifying the document is called.
	1672	*
	1673	* Arguments:
	1674	*
	1675	* - `document`: a document object.
	1676	*
	1677	* - `node_id`: the node id. The node id starts from `0` and increases by `1`
	1678	* for each newly added node. Specifying a negative `node_id` is possible,
	1679	* which is interpeted as the number (<total number of nodes> - `node_id`).
	1680	*
	1681	* Returns: a pointer to the node object or `NULL` if `node_id` is out of
	1682	* range.
1113	1683	*/
1114	1684
1115	1685	YAML_DECLARE(yaml_node_t *)
1116		yaml_document_get_node(yaml_document_t *document, int index);
1117
1118		/**
1119		* Get the root of a YAML document node.
1120		*
1121		* The root object is the first object added to the document.
1122		*
1123		* The pointer returned by this function is valid until any of the functions
1124		* modifying the documents is called.
1125		*
1126		* An empty document produced by the parser signifies the end of a YAML
1127		* stream.
1128		*
1129		* @param[in] document A document object.
1130		*
1131		* @returns the node object or @c NULL if the document is empty.
1132		*/
1133
1134		YAML_DECLARE(yaml_node_t *)
1135		yaml_document_get_root_node(yaml_document_t *document);
1136
1137		/**
	1686	yaml_document_get_node(yaml_document_t *document, int node_id);
	1687
	1688	/*
1138	1689	* Create a SCALAR node and attach it to the document.
1139	1690	*
1140		* The @a style argument may be ignored by the emitter.
1141		*
1142		* @param[in,out] document A document object.
1143		* @param[in] anchor A preferred anchor for the node or @c NULL.
1144		* @param[in] tag The scalar tag.
1145		* @param[in] value The scalar value.
1146		* @param[in] length The length of the scalar value.
1147		* @param[in] style The scalar style.
1148		*
1149		* @returns the node id or @c 0 on error.
1150		*/
1151
1152		YAML_DECLARE(int)
1153		yaml_document_add_scalar(yaml_document_t *document,
1154		yaml_char_t anchor, yaml_char_t tag, yaml_char_t *value,
1155		size_t length, yaml_scalar_style_t style);
1156
1157		/**
	1691	* Note that the first node attached to a document becomes the root node.
	1692	* There must exist a path from the root node to any node added to the
	1693	* document, otherwise the function `yaml_emitter_emit_document()` will fail.
	1694	*
	1695	* Arguments:
	1696	*
	1697	* - `document`: a document object.
	1698	*
	1699	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	1700	*
	1701	* - `anchor`: the node anchor or `NULL`. The anchor should be a non-empty
	1702	* NUL-terminated string containing only alphanumerical characters, `_`, and
	1703	* `-`. The function does not check whether this requirement is satisfied,
	1704	* but the emitter may fail to emit the node if it is not so. This parameter
	1705	* is considered as a stylistic hint and could be ignored by the emitter.
	1706	* The emitter may automatically generate an anchor for a node that does not
	1707	* specify it or specifies a duplicate anchor.
	1708	*
	1709	* - `tag`: the node tag. The tag should be a non-empty UTF-8 NUL-terminated
	1710	* string. The tag could be global (a valid URI) or local (an arbitrary
	1711	* string starting with `!`). The function does not check whether these
	1712	* requirements are satisfied, but the emitter will fail to emit the node if
	1713	* it is not so.
	1714	*
	1715	* - `value`: the scalar value. The value should be a string containing any
	1716	* valid UTF-8 character including NUL. The function does not check if
	1717	* `value` is a valid UTF-8 string, but the emitter will fail to emit the
	1718	* node if it is not so.
	1719	*
	1720	* - `length`: the length of the scalar value (in bytes) or `-1`. If `length`
	1721	* is set to `-1`, the `value` is assumed to be NUL-terminated.
	1722	*
	1723	* - `style`: the node style. Note that this attribute only serves as a hint
	1724	* and may be ignored by the emitter.
	1725	*
	1726	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1727	* allocate memory for duplicating the given string buffers. If the function
	1728	* succeeds, the id of the added node is returned via the pointer `node_id`
	1729	* if it is not set to `NULL`.
	1730	*/
	1731
	1732	YAML_DECLARE(int)
	1733	yaml_document_add_scalar(yaml_document_t document, int node_id,
	1734	const yaml_char_t anchor, const yaml_char_t tag,
	1735	const yaml_char_t *value, int length,
	1736	yaml_scalar_style_t style);
	1737
	1738	/*
1158	1739	* Create a SEQUENCE node and attach it to the document.
1159	1740	*
1160		* The @a style argument may be ignored by the emitter.
1161		*
1162		* @param[in,out] document A document object.
1163		* @param[in] anchor A preferred anchor for the node or @c NULL.
1164		* @param[in] tag The sequence tag.
1165		* @param[in] style The sequence style.
1166		*
1167		* @returns the node id or @c 0 on error.
1168		*/
1169
1170		YAML_DECLARE(int)
1171		yaml_document_add_sequence(yaml_document_t *document,
1172		yaml_char_t anchor, yaml_char_t tag, yaml_sequence_style_t style);
1173
1174		/**
	1741	* Note that the first node attached to a document becomes the root node.
	1742	* There must exist a path from the root node to any node added to the
	1743	* document, otherwise the function `yaml_emitter_emit_document()` will fail.
	1744	*
	1745	* Arguments:
	1746	*
	1747	* - `document`: a document object.
	1748	*
	1749	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	1750	*
	1751	* - `anchor`: the node anchor or `NULL`. The anchor should be a non-empty
	1752	* NUL-terminated string containing only alphanumerical characters, `_`, and
	1753	* `-`. The function does not check whether this requirement is satisfied,
	1754	* but the emitter may fail to emit the node if it is not so. This parameter
	1755	* is considered as a stylistic hint and could be ignored by the emitter.
	1756	* The emitter may automatically generate an anchor for a node that does not
	1757	* specify it or specifies a duplicate anchor.
	1758	*
	1759	* - `tag`: the node tag. The tag should be a non-empty UTF-8 NUL-terminated
	1760	* string. The tag could be global (a valid URI) or local (an arbitrary
	1761	* string starting with `!`). The function does not check whether these
	1762	* requirements are satisfied, but the emitter will fail to emit the node if
	1763	* it is not so.
	1764	*
	1765	* - `style`: the node style. Note that this attribute only serves as a hint
	1766	* and may be ignored by the emitter.
	1767	*
	1768	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1769	* allocate memory for duplicating the given string buffers. If the function
	1770	* succeeds, the id of the added node is returned via the pointer `node_id`
	1771	* if it is not set to `NULL`.
	1772	*/
	1773
	1774	YAML_DECLARE(int)
	1775	yaml_document_add_sequence(yaml_document_t document, int node_id,
	1776	const yaml_char_t anchor, const yaml_char_t tag,
	1777	yaml_sequence_style_t style);
	1778
	1779	/*
1175	1780	* Create a MAPPING node and attach it to the document.
1176	1781	*
1177		* The @a style argument may be ignored by the emitter.
1178		*
1179		* @param[in,out] document A document object.
1180		* @param[in] anchor A preferred anchor for the node or @c NULL.
1181		* @param[in] tag The sequence tag.
1182		* @param[in] style The sequence style.
1183		*
1184		* @returns the node id or @c 0 on error.
1185		*/
1186
1187		YAML_DECLARE(int)
1188		yaml_document_add_mapping(yaml_document_t *document,
1189		yaml_char_t anchor, yaml_char_t tag, yaml_mapping_style_t style);
1190
1191		/**
	1782	* Note that the first node attached to a document becomes the root node.
	1783	* There must exist a path from the root node to any node added to the
	1784	* document, otherwise the function `yaml_emitter_emit_document()` will fail.
	1785	*
	1786	* Arguments:
	1787	*
	1788	* - `document`: a document object.
	1789	*
	1790	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	1791	*
	1792	* - `anchor`: the node anchor or `NULL`. The anchor should be a non-empty
	1793	* NUL-terminated string containing only alphanumerical characters, `_`, and
	1794	* `-`. The function does not check whether this requirement is satisfied,
	1795	* but the emitter may fail to emit the node if it is not so. This parameter
	1796	* is considered as a stylistic hint and could be ignored by the emitter.
	1797	* The emitter may automatically generate an anchor for a node that does not
	1798	* specify it or specifies a duplicate anchor.
	1799	*
	1800	* - `tag`: the node tag. The tag should be a non-empty UTF-8 NUL-terminated
	1801	* string. The tag could be global (a valid URI) or local (an arbitrary
	1802	* string starting with `!`). The function does not check whether these
	1803	* requirements are satisfied, but the emitter will fail to emit the node if
	1804	* it is not so.
	1805	*
	1806	* - `style`: the node style. Note that this attribute only serves as a hint
	1807	* and may be ignored by the emitter.
	1808	*
	1809	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	1810	* allocate memory for duplicating the given string buffers. If the function
	1811	* succeeds, the id of the added node is returned via the pointer `node_id`
	1812	* if it is not set to `NULL`.
	1813	*/
	1814
	1815	YAML_DECLARE(int)
	1816	yaml_document_add_mapping(yaml_document_t document, int node_id,
	1817	const yaml_char_t anchor, const yaml_char_t tag,
	1818	yaml_mapping_style_t style);
	1819
	1820	/*
	1821	* Get the value of a `!!null` SCALAR node.
	1822	*
	1823	* Use this function to ensure that the given node is a scalar, the node tag is
	1824	* equal to `tag:yaml.org,2002:null` and the node value is a valid null value.
	1825	* Given that the `!!null` tag admits only one valid value, the value is not
	1826	* returned.
	1827	*
	1828	* Arguments:
	1829	*
	1830	* - `document`: a document object.
	1831	*
	1832	* - `node_id`: the node id; could be negative.
	1833	*
	1834	* Returns: `1` if the node is a valid `!!null` scalar, `0` otherwise.
	1835	*/
	1836
	1837	YAML_DECLARE(int)
	1838	yaml_document_get_null_node(yaml_document_t *document, int node_id);
	1839
	1840	/*
	1841	* Get the value of a `!!bool` SCALAR node.
	1842	*
	1843	* Use this function to ensure that the given node is a scalar, the node tag is
	1844	* `tag:yaml.org,2002:bool` and the node value is a valid boolean value. The
	1845	* function returns the true value as `1` and the false value as `0`.
	1846	*
	1847	* Arguments:
	1848	*
	1849	* - `document`: a document object.
	1850	*
	1851	* - `node_id`: the node id; could be negative.
	1852	*
	1853	* - `value`: a pointer to save the node value or `NULL`.
	1854	*
	1855	* Returns: `1` if the node is a valid `!!bool` scalar, `0` otherwise. If the
	1856	* function succeeds and `value` is not `NULL`, the node value is saved to
	1857	* `value`.
	1858	*/
	1859
	1860	YAML_DECLARE(int)
	1861	yaml_document_get_bool_node(yaml_document_t *document, int node_id,
	1862	int *value);
	1863
	1864	/*
	1865	* Get the value of a `!!str` SCALAR node.
	1866	*
	1867	* Use this function to ensure that the given node is a scalar, the node tag is
	1868	* `tag:yaml.org,2002:str` and the node value is a string that does not contain
	1869	* the NUL character. In this case, the function returns the node value. The
	1870	* produced value is valid until the document object is cleared or deleted.
	1871	*
	1872	* Arguments:
	1873	*
	1874	* - `document`: a document object.
	1875	*
	1876	* - `node_id`: the node id; could be negative.
	1877	*
	1878	* - `value`: a pointer to save the node value or `NULL`.
	1879	*
	1880	* Returns: `1` if the node is a valid `!!str` scalar, `0` otherwise. If the
	1881	* function succeeds and `value` is not `NULL`, the node value is saved to
	1882	* `value`.
	1883	*/
	1884
	1885	YAML_DECLARE(int)
	1886	yaml_document_get_str_node(yaml_document_t *document, int node_id,
	1887	char **value);
	1888
	1889	/*
	1890	* Get the value of an `!!int` SCALAR node.
	1891	*
	1892	* Use this function to ensure that the given node is a scalar, the node tag is
	1893	* `tag:yaml.org,2002:int` and the node value is a valid integer. In this
	1894	* case, the function parses the node value and returns an integer number. The
	1895	* function recognizes decimal, hexdecimal and octal numbers including negative
	1896	* numbers.
	1897	*
	1898	* Arguments:
	1899	*
	1900	* - `document`: a document object.
	1901	*
	1902	* - `node_id`: the node id; could be negative.
	1903	*
	1904	* - `value`: a pointer to save the node value or `NULL`.
	1905	*
	1906	* Returns: `1` if the node is a valid `!!int` scalar, `0` otherwise. If the
	1907	* function succeeds and `value` is not `NULL`, the node value is saved to
	1908	* `value`.
	1909	*/
	1910
	1911	YAML_DECLARE(int)
	1912	yaml_document_get_int_node(yaml_document_t *document, int node_id,
	1913	int *value);
	1914
	1915	/*
	1916	* Get the value of a `!!float` SCALAR node.
	1917	*
	1918	* Use this function to ensure that the given node is a scalar, the node tag is
	1919	* `tag:yaml.org,2002:float` and the node value is a valid float value. In
	1920	* this case, the function parses the node value and returns a float number.
	1921	* The function recognizes float values in exponential and fixed notation as
	1922	* well as special values `.nan`, `.inf` and `-.inf`.
	1923	*
	1924	* Arguments:
	1925	*
	1926	* - `document`: a document object.
	1927	*
	1928	* - `node_id`: the node id; could be negative.
	1929	*
	1930	* - `value`: a pointer to save the node value or `NULL`.
	1931	*
	1932	* Returns: `1` if the node is a valid `!!float` scalar, `0` otherwise. If the
	1933	* function succeeds and `value` is not `NULL`, the node value is saved to
	1934	* `value`.
	1935	*/
	1936
	1937	YAML_DECLARE(int)
	1938	yaml_document_get_float_node(yaml_document_t *document, int node_id,
	1939	double *value);
	1940
	1941	/*
	1942	* Get the value of a `!!seq` SEQUENCE node.
	1943	*
	1944	* Use this function to ensure that the given node is a sequence and the node
	1945	* tag is `tag:yaml.org,2002:seq`. In this case, the function returns the list
	1946	* of nodes that belong to the sequence. The produced list is valid until the
	1947	* document object is modified.
	1948	*
	1949	* Arguments:
	1950	*
	1951	* - `document`: a document object.
	1952	*
	1953	* - `node_id`: the node id; could be negative.
	1954	*
	1955	* - `items`: a pointer to save the list of sequence items or `NULL`.
	1956	*
	1957	* - `length`: a pointer to save the length of the sequence or `NULL`.
	1958	* `length` must be equal to `NULL` if and only if `items` is also `NULL`.
	1959	*
	1960	* Returns: `1` if the node is a valid `!!seq` sequence, `0` otherwise. If the
	1961	* function succeeds and `items` is not `NULL`, the list of sequence items is
	1962	* saved to `items` and the sequence length is saved to `length`.
	1963	*/
	1964
	1965	YAML_DECLARE(int)
	1966	yaml_document_get_seq_node(yaml_document_t *document, int node_id,
	1967	yaml_node_item_t *items, size_t length);
	1968
	1969	/*
	1970	* Get the value of a `!!map` MAPPING node.
	1971	*
	1972	* Use this function to ensure that the given node is a mapping and the node
	1973	* tag is `tag:yaml.org,2002:map`. In this case, the function returns the list
	1974	* of node pairs (key, value) that belong to the sequence. The produced list
	1975	* is valid until the document is modified.
	1976	*
	1977	* Arguments:
	1978	*
	1979	* - `document`: a document object.
	1980	*
	1981	* - `node_id`: the node id; could be negative.
	1982	*
	1983	* - `pairs`: a pointer to save the list of mapping pairs or `NULL`.
	1984	*
	1985	* - `length`: a pointer to save the length of the mapping or `NULL`.
	1986	* `length` must be equal to `NULL` if and only if `pairs` is also `NULL`.
	1987	*
	1988	* Returns: `1` if the node is a valid `!!map` mapping, `0` otherwise. If the
	1989	* function succeeds and `pairs` is not `NULL`, the list of mapping pairs is
	1990	* saved to `pairs` and the mapping length is saved to `length`.
	1991	*/
	1992
	1993	YAML_DECLARE(int)
	1994	yaml_document_get_map_node(yaml_document_t *document, int node_id,
	1995	yaml_node_pair_t *pairs, size_t length);
	1996
	1997	/*
	1998	* Add a `!!null` SCALAR node to the document.
	1999	*
	2000	* This function is a shorthand for the call:
	2001	*
	2002	* yaml_document_add_scalar(document, node_id, NULL,
	2003	* YAML_NULL_TAG, "null", -1, YAML_ANY_SCALAR_STYLE)
	2004	*
	2005	* Arguments:
	2006	*
	2007	* - `document`: a document object.
	2008	*
	2009	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	2010	*
	2011	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2012	* allocate memory for new buffers. If the function succeeds, the id of the
	2013	* added node is returned via the pointer `node_id` if it is not set to `NULL`.
	2014	*/
	2015
	2016	YAML_DECLARE(int)
	2017	yaml_document_add_null_node(yaml_document_t document, int node_id);
	2018
	2019	/*
	2020	* Add a `!!bool` SCALAR node to the document.
	2021	*
	2022	* This function is a shorthand for the call:
	2023	*
	2024	* yaml_document_add_scalar(document, node_id, NULL,
	2025	* YAML_BOOL_TAG, (value ? "true" : "false"), -1,
	2026	* YAML_ANY_SCALAR_STYLE)
	2027	*
	2028	* Arguments:
	2029	*
	2030	* - `document`: a document object.
	2031	*
	2032	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	2033	*
	2034	* - `value`: a boolean value; any non-zero value is true, `0` is false.
	2035	*
	2036	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2037	* allocate memory for new buffers. If the function succeeds, the id of the
	2038	* added node is returned via the pointer `node_id` if it is not set to `NULL`.
	2039	*/
	2040
	2041	YAML_DECLARE(int)
	2042	yaml_document_add_bool_node(yaml_document_t document, int node_id,
	2043	int value);
	2044
	2045	/*
	2046	* Add a `!!str` SCALAR node to the document.
	2047	*
	2048	* This function is a shorthand for the call:
	2049	*
	2050	* yaml_document_add_scalar(document, node_id, NULL,
	2051	* YAML_STR_TAG, (const yaml_char_t *) value, -1,
	2052	* YAML_ANY_SCALAR_STYLE)
	2053	*
	2054	* Arguments:
	2055	*
	2056	* - `document`: a document object.
	2057	*
	2058	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	2059	*
	2060	* - `value`: a NUL-terminated UTF-8 string. The function does not check if
	2061	* `value` is a valid UTF-8 string, but if it is not so, the emitter will
	2062	* fail to emit the node.
	2063	*
	2064	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2065	* allocate memory for new buffers. If the function succeeds, the id of the
	2066	* added node is returned via the pointer `node_id` if it is not set to `NULL`.
	2067	*/
	2068
	2069	YAML_DECLARE(int)
	2070	yaml_document_add_str_node(yaml_document_t document, int node_id,
	2071	const char *value);
	2072
	2073	/*
	2074	* Add an `!!int` SCALAR node to the document.
	2075	*
	2076	* This function is a shorthand for the call:
	2077	*
	2078	* yaml_document_add_scalar(document, node_id, NULL,
	2079	* YAML_INT_TAG, <string representation of the value>, -1,
	2080	* YAML_ANY_SCALAR_STYLE)
	2081	*
	2082	* Arguments:
	2083	*
	2084	* - `document`: a document object.
	2085	*
	2086	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	2087	*
	2088	* - `value`: an integer value.
	2089	*
	2090	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2091	* allocate memory for new buffers. If the function succeeds, the id of the
	2092	* added node is returned via the pointer `node_id` if it is not set to `NULL`.
	2093	*/
	2094
	2095	YAML_DECLARE(int)
	2096	yaml_document_add_int_node(yaml_document_t document, int node_id,
	2097	int value);
	2098
	2099	/*
	2100	* Add a `!!float` SCALAR node to the document.
	2101	*
	2102	* This function is a shorthand for the call:
	2103	*
	2104	* yaml_document_add_scalar(document, node_id, NULL,
	2105	* YAML_FLOAT_TAG, <string representation of the value>, -1,
	2106	* YAML_ANY_SCALAR_STYLE)
	2107	*
	2108	* Arguments:
	2109	*
	2110	* - `document`: a document object.
	2111	*
	2112	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	2113	*
	2114	* - `value`: a float value.
	2115	*
	2116	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2117	* allocate memory for new buffers. If the function succeeds, the id of the
	2118	* added node is returned via the pointer `node_id` if it is not set to `NULL`.
	2119	*/
	2120
	2121	YAML_DECLARE(int)
	2122	yaml_document_add_float_node(yaml_document_t document, int node_id,
	2123	double value);
	2124
	2125	/*
	2126	* Add a `!!seq` SEQUENCE node to the document.
	2127	*
	2128	* This function is a shorthand for the call:
	2129	*
	2130	* yaml_document_add_sequence(document, node_id, NULL,
	2131	* YAML_SEQ_TAG, YAML_ANY_SEQUENCE_STYLE)
	2132	*
	2133	* Arguments:
	2134	*
	2135	* - `document`: a document object.
	2136	*
	2137	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	2138	*
	2139	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2140	* allocate memory for new buffers. If the function succeeds, the id of the
	2141	* added node is returned via the pointer `node_id` if it is not set to `NULL`.
	2142	*/
	2143
	2144	YAML_DECLARE(int)
	2145	yaml_document_add_seq_node(yaml_document_t document, int node_id);
	2146
	2147	/*
	2148	* Add a `!!map` MAPPING node to the document.
	2149	*
	2150	* This function is a shorthand for the call:
	2151	*
	2152	* yaml_document_add_mapping(document, node_id, NULL,
	2153	* YAML_MAP_TAG, YAML_ANY_MAPPING_STYLE)
	2154	*
	2155	* Arguments:
	2156	*
	2157	* - `document`: a document object.
	2158	*
	2159	* - `node_id`: a pointer to save the id of the generated node or `NULL`.
	2160	*
	2161	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2162	* allocate memory for new buffers. If the function succeeds, the id of the
	2163	* added node is returned via the pointer `node_id` if it is not set to `NULL`.
	2164	*/
	2165
	2166	YAML_DECLARE(int)
	2167	yaml_document_add_map_node(yaml_document_t document, int node_id);
	2168
	2169	/*
1192	2170	* Add an item to a SEQUENCE node.
1193	2171	*
1194		* @param[in,out] document A document object.
1195		* @param[in] sequence The sequence node id.
1196		* @param[in] item The item node id.
1197		*
1198		* @returns @c 1 if the function succeeded, @c 0 on error.
	2172	* The order in which items are added to a sequence coincides with the order
	2173	* they are emitted into the output stream.
	2174	*
	2175	* Arguments:
	2176	*
	2177	* - `document`: a document object.
	2178	*
	2179	* - `sequence_id`: the id of a sequence node; could be negative. It is a
	2180	* fatal error if `sequence_id` does not refer to an existing sequence node.
	2181	*
	2182	* - `item_id`: the id of an item node; could be negative. It is a fatal error
	2183	* if `item_id` does not refer to an existing node. Note that it is possible
	2184	* for `item_id` to coincide with `sequence_id`, which means that the
	2185	* sequence recursively contains itself.
	2186	*
	2187	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2188	* allocate memory for internal buffers.
1199	2189	*/
1200	2190
1201	2191	YAML_DECLARE(int)
1202	2192	yaml_document_append_sequence_item(yaml_document_t *document,
1203		int sequence~~, int item~~);
1204
1205		/**
	2193	int sequence_id, int item_id);
	2194
	2195	/*
1206	2196	* Add a pair of a key and a value to a MAPPING node.
1207	2197	*
1208		* @param[in,out] document A document object.
1209		* @param[in] mapping The mapping node id.
1210		* @param[in] key The key node id.
1211		* @param[in] value The value node id.
1212		*
1213		* @returns @c 1 if the function succeeded, @c 0 on error.
	2198	* The order in which (key, value) pairs are added to a mapping coincides with
	2199	* the order in which they are presented in the output stream. Note that the
	2200	* mapping key order is a presentation detail and should not used to convey any
	2201	* information. An ordered mapping could be represented as a sequence of
	2202	* single-paired mappings.
	2203	*
	2204	* Arguments:
	2205	*
	2206	* - `document`: a document object.
	2207	*
	2208	* - `mapping_id`: the id of a mapping node; could be negative. It is a
	2209	* fatal error if `mapping_id` does not refer to an existing mapping node.
	2210	*
	2211	* - `key_id`: the id of a key node; could be negative. It is a fatal error
	2212	* if `key_id` does not refer to an existing node.
	2213	*
	2214	* - `value_id`: the id of a value node; could be negative. It is a fatal
	2215	* error if `value_id` does not refer to an existing node.
	2216	*
	2217	* Returns: `1` on success, `0` on error. The function may fail if it cannot
	2218	* allocate memory for internal buffers.
1214	2219	*/
1215	2220
1216	2221	YAML_DECLARE(int)
1217	2222	yaml_document_append_mapping_pair(yaml_document_t *document,
1218		int mapping, int key, int value);
1219
1220		#endif
1221
1222		/**
1223		* @defgroup callbacks Callback Definitions
1224		* @{
1225		*/
1226
1227		/**
	2223	int mapping_id, int key_id, int value_id);
	2224
	2225	/******************************************************************************
	2226	* Callback Definitions
	2227	******************************************************************************/
	2228
	2229	/*
1228	2230	* The prototype of a read handler.
1229	2231	*
1230		* The read handler is called when the parser needs to read more bytes from the
1231		* source. The handler should read no more than @a size bytes and write them
1232		* to the @a buffer. The number of the read bytes should be returned using the
1233		* @a size_read variable. If the handler reaches the stream end, @a size_read
1234		* must be set to @c 0.
1235		*
1236		* @param[in,out] data A pointer to an application data specified by
1237		* @c yaml_parser_set_reader().
1238		* @param[out] buffer The buffer to write the data from the source.
1239		* @param[in] capacity The maximum number of bytes the buffer can hold.
1240		* @param[out] length The actual number of bytes read from the source.
1241		*
1242		* @returns On success, the handler should return @c 1. If the handler failed,
1243		* the returned value should be @c 0. On EOF, the handler should set the
1244		* @a size_read to @c 0 and return @c 1.
	2232	* The reader is called when the parser needs to read more bytes from the input
	2233	* stream. The reader is given a buffer to fill and should returns the number
	2234	* of bytes read. The reader should block if no data from the input stream is
	2235	* available, but it should return immediately if it could produce least one
	2236	* byte of the input stream. If the reader reaches the stream end, it should
	2237	* return immediately setting the number of bytes read to `0`.
	2238	*
	2239	* Arguments:
	2240	*
	2241	* - `data`: a pointer to an application data specified with
	2242	* `yaml_parser_set_reader()`.
	2243	*
	2244	* - `buffer`: a pointer to a buffer which should be filled with the bytes
	2245	* from the input stream.
	2246	*
	2247	* - `capacity`: the maximum capacity of the buffer.
	2248	*
	2249	* - `length`: a pointer to save the actual number of bytes read from the input
	2250	* stream; `length` equals `0` signifies that the reader reached the end of
	2251	* the stream.
	2252	*
	2253	* Return: on success, the reader should return `1`. If the reader fails for
	2254	* any reason, it should return `0`. On the end of the input stream, the
	2255	* reader should set `length` to `0` and return `1`.
1245	2256	*/
1246	2257
…	…
1248	2259	size_t *length);
1249	2260
1250		/**
	2261	/*
1251	2262	* The prototype of a write handler.
1252	2263	*
1253		* The write handler is called when the emitter needs to flush the accumulated
1254		* characters to the output. The handler should write @a size bytes of the
1255		* @a buffer to the output.
1256		*
1257		* @param[in,out] data A pointer to an application data specified by
1258		* @c yaml_emitter_set_writer().
1259		* @param[in] buffer The buffer with bytes to be written.
1260		* @param[in] length The number of bytes to be written.
1261		*
1262		* @returns On success, the handler should return @c 1. If the handler failed,
1263		* it should return @c 0.
	2264	* The writer is called when the emitter needs to flush the accumulated bytes
	2265	* into the output stream.
	2266	*
	2267	* Arguments:
	2268	*
	2269	* - `data`: a pointer to an application data specified with
	2270	* `yaml_emitter_set_writer()`.
	2271	*
	2272	* - `buffer`: a pointer to a buffer with bytes to be written to the output
	2273	* stream.
	2274	*
	2275	* - `length`: the number of bytes to be written.
	2276	*
	2277	* Returns: on success, the writer should return `1`. If the writer fails for
	2278	* any reason, it should return `0`.
1264	2279	*/
1265	2280
…	…
1268	2283
1269	2284	/**
1270		* The prototype of a tag resolver.
1271		*
1272		* The resolve handler is called when the parser encounters a new node without
1273		* an explicit tag. The handler should determine the correct tag of the node
1274		* basing on the node kind, the path to the node from the document root and,
1275		* in the case of the scalar node, the node value. The handler is also called
1276		* by the emitter to determine whether the node tag could be omitted.
1277		*
1278		* @param[in,out] data A pointer to an application data specified by
1279		* @c yaml_parser_set_writter() or
1280		* @c yaml_emitter_set_writer().
1281		* @param[in] node Information about the new node.
1282		* @param[out] tag The guessed node tag.
1283		*
1284		* @returns On success, the handler should return @c 1. If the handler failed,
1285		* it should return @c 0.
	2285	* The prototype of a nonspecific tag resolver.
	2286	*
	2287	* The resolver is called when the parser encounters a node without an explicit
	2288	* tag. The resolver should determine the correct tag of the node from the
	2289	* path to the node from the root node and, in case of the scalar node, the
	2290	* node value. The resolver is also called by the emitter to determine whether
	2291	* the node tag could be omitted.
	2292	*
	2293	* Arguments:
	2294	*
	2295	* - `data`: a pointer to an application data specified with
	2296	* `yaml_parser_set_resolver()` or `yaml_emitter_set_resolver()`.
	2297	*
	2298	* - `node`: information about the new node.
	2299	*
	2300	* - `tag`: A pointer to save the guessed node tag. The value returned by the
	2301	* resolved is immediately copied.
	2302	*
	2303	* Returns: on success, the resolver should return `1`. If the resolver fails
	2304	* for any reason, it should return `0`.
1286	2305	*/
1287	2306
…	…
1289	2308	yaml_char_t **tag);
1290	2309
1291		/** @} */
1292
1293		/**
1294		* @defgroup parser Parser Definitions
1295		* @{
1296		*/
1297
1298		/** The parser object. */
	2310	/******************************************************************************
	2311	* Parser Definitions
	2312	******************************************************************************/
	2313
	2314	/*
	2315	* An opaque definition of the parser object.
	2316	*
	2317	* A parser object is used to parse an input YAML stream producing a sequence
	2318	* of YAML tokens, events or documents.
	2319	*/
	2320
1299	2321	typedef struct yaml_parser_s yaml_parser_t;
1300	2322
1301		/**
1302		* ~~Cre~~ate a new parser object.
1303		*
1304		* ~~This function creates a new parser object. An application is responsible~~
1305		* ~~for destroying the object using the @c yaml_parser_delete() function.~~
1306		*
1307		* ~~@returns a new parser object or @c NULL on error~~.
	2323	/*
	2324	* Allocate a new parser object.
	2325	*
	2326	* An allocated parser object should be deleted with `yaml_parser_delete()`
	2327	*
	2328	* Returns: a new parser object or `NULL` on error. The function may fail if
	2329	* it cannot allocate memory for internal buffers.
1308	2330	*/
1309	2331
…	…
1311	2333	yaml_parser_new(void);
1312	2334
1313		/**
1314		* Destroy a parser.
1315		*
1316		* @param[in,out] parser A parser object.
	2335	/*
	2336	* Deallocate a parser and free the internal parser data.
	2337	*
	2338	* A parser object must be previously allocated with `yaml_parser_new()`.
	2339	*
	2340	* Arguments:
	2341	*
	2342	* - `parser`: a parser object.
1317	2343	*/
1318	2344
…	…
1320	2346	yaml_parser_delete(yaml_parser_t *parser);
1321	2347
1322		/**
1323		* Get a parser error.
1324		*
1325		* @param[in] parser A parser object.
1326		* @param[out] error An error object.
	2348	/*
	2349	* Clear and reinitialize the internal state of the parser.
	2350	*
	2351	* This function could be used for cleaning up a parser object after an error
	2352	* condition or after the end of the input stream is reached. A cleaned parser
	2353	* object may be reused to parse another YAML stream. Note that all the parser
	2354	* parameters including the read handler must be reset.
	2355	*
	2356	* Arguments:
	2357	*
	2358	* - `parser`: a parser object.
1327	2359	*/
1328	2360
1329	2361	YAML_DECLARE(void)
1330		yaml_parser_get_error(yaml_parser_t parser, yaml_error_t error);
1331
1332		/**
1333		* Set a string input.
1334		*
1335		* Note that the @a input pointer must be valid while the @a parser object
1336		* exists. The application is responsible for destroing @a input after
1337		* destroying the @a parser.
1338		*
1339		* @param[in,out] parser A parser object.
1340		* @param[in] buffer A source data.
1341		* @param[in] length The length of the source data in bytes.
	2362	yaml_parser_clear(yaml_parser_t *parser);
	2363
	2364	/*
	2365	* Get the parser error.
	2366	*
	2367	* Use this function to get a detailed error information after failure of one
	2368	* of the following functions: `yaml_parser_parse_token()`,
	2369	* `yaml_parser_parse_event()`, `yaml_parser_parse_document()`,
	2370	* `yaml_parser_parse_single_document()`.
	2371	*
	2372	* The pointer returned by the function is only valid until the parser object
	2373	* is not modified. However the error object could be safely copied.
	2374	*
	2375	* Arguments:
	2376	*
	2377	* - `parser`: a parser object.
	2378	*
	2379	* Returns: a pointer to an error object. The returned pointer is only valid
	2380	* until the parser object is not modified or deleted. However the error
	2381	* object could be safely copied.
	2382	*/
	2383
	2384	YAML_DECLARE(yaml_error_t *)
	2385	yaml_parser_get_error(yaml_parser_t *parser);
	2386
	2387	/*
	2388	* Set the parser to read the input stream from a character buffer.
	2389	*
	2390	* Arguments:
	2391	*
	2392	* - `parser`: a parser object.
	2393	*
	2394	* - `buffer`: a pointer to character buffer containing the input stream. The
	2395	* buffer must be valid until the parser object is cleared or deleted.
	2396	*
	2397	* - `length`: the length of the buffer in bytes.
1342	2398	*/
1343	2399
…	…
1346	2402	const unsigned char *buffer, size_t length);
1347	2403
1348		/**
1349		* Set a file input.
1350		*
1351		* @a file should be a file object open for reading. The application is
1352		* responsible for closing the @a file.
1353		*
1354		* @param[in,out] parser A parser object.
1355		* @param[in] file An open file.
	2404	/*
	2405	* Set the parser to read the input stream from a file.
	2406	*
	2407	* Arguments:
	2408	*
	2409	* - `parser`: a parser object.
	2410	*
	2411	* - `file`: a pointer to an open file object. The pointer must be valid until
	2412	* the parser object is cleared or deleted.
1356	2413	*/
1357	2414
…	…
1359	2416	yaml_parser_set_file_reader(yaml_parser_t parser, FILE file);
1360	2417
1361		/**
1362		* Set a generic input handler.
1363		*
1364		* @param[in,out] parser A parser object.
1365		* @param[in] reader A read handler.
1366		* @param[in] data Any application data for passing to the read
1367		* handler.
	2418	/*
	2419	* Set an input stream reader for a parser.
	2420	*
	2421	* Arguments:
	2422	*
	2423	* - `parser`: a parser object.
	2424	*
	2425	* - `reader`: a read handler.
	2426	*
	2427	* - `data`: application data for passing to the reader.
1368	2428	*/
1369	2429
…	…
1372	2432	yaml_reader_t reader, void data);
1373	2433
1374		#if 0
1375
1376		/**
1377		* ~~Set the standard resolve handler.~~
1378		*
1379		* ~~The standard resolver recognize the following scalar kinds: !!null, !!bool,~~
1380		* ~~!!str, !!int and !!float.~~
1381		*
1382		* ~~@param[in,out] parser A~~ parser object.
	2434	/*
	2435	* Set the standard nonspecific tag resolver for a parser.
	2436	*
	2437	* The standard resolver recognizes the following scalar tags: `!!null`,
	2438	* `!!bool`, `!!str`, `!!int`, and `!!float`.
	2439	*
	2440	* Arguments:
	2441	*
	2442	* - `parser`: a parser object.
1383	2443	*/
1384	2444
…	…
1386	2446	yaml_parser_set_standard_resolver(yaml_parser_t *parser);
1387	2447
1388		/**
1389		* Set ~~the resolve handl~~er.
1390		*
1391		* ~~The standard resolver recognize the following scalar kinds: !!null, !!bool,~~
1392		* ~~!!str, !!int and !!float.~~
1393		*
1394		* ~~@param[in,out] parser A parser object.~~
1395		* ~~@param[in] resolver A~~ resolve handler.
1396		* ~~@param[in] data Any application data for passing to the resolve~~
1397		* ~~handl~~er.
	2448	/*
	2449	* Set a nonspecific tag resolver for a parser.
	2450	*
	2451	* Arguments:
	2452	*
	2453	* - `parser`: a parser object.
	2454	*
	2455	* - `resolver`: a resolve handler.
	2456	*
	2457	* - `data`: application data for passing to the resolver.
1398	2458	*/
1399	2459
…	…
1402	2462	yaml_resolver_t resolver, void data);
1403	2463
1404		#endif
1405
1406		/**
1407		* Set the source encoding.
1408		*
1409		* @param[in,out] parser A parser object.
1410		* @param[in] encoding The source encoding.
	2464	/*
	2465	* Set the input stream encoding.
	2466	*
	2467	* Typically the parser guesses the input stream encoding by the BOM mark. If
	2468	* the BOM mark is not present, the UTF-8 encoding is assumed. An application
	2469	* could override the detection mechanism by specifying the the encoding
	2470	* explicitly.
	2471	*
	2472	* Arguments:
	2473	*
	2474	* - `parser`: a parser object.
	2475	*
	2476	* - `encoding`: the input stream encoding.
1411	2477	*/
1412	2478
…	…
1414	2480	yaml_parser_set_encoding(yaml_parser_t *parser, yaml_encoding_t encoding);
1415	2481
1416		/**
1417		* Scan the input stream and produce the next token.
1418		*
1419		* Call the function subsequently to produce a sequence of tokens corresponding
1420		* to the input stream. The initial token has the type
1421		* @c YAML_STREAM_START_TOKEN while the ending token has the type
1422		* @c YAML_STREAM_END_TOKEN.
1423		*
1424		* An application is responsible for freeing any buffers associated with the
1425		* produced token object using the @c yaml_token_delete() function.
1426		*
1427		* An application must not alternate the calls of @c yaml_parser_scan() with
1428		* the calls of @c yaml_parser_parse() or @c yaml_parser_load(). Doing this
1429		* will break the parser.
1430		*
1431		* @param[in,out] parser A parser object.
1432		* @param[out] token An empty token object.
1433		*
1434		* @returns @c 1 if the function succeeded, @c 0 on error.
	2482	/*
	2483	* Parse the input stream and produce the next token.
	2484	*
	2485	* An application may call this function subsequently to produce a sequence of
	2486	* tokens corresponding to the input stream. The first token in the sequence
	2487	* is STREAM-START and the last token is STREAM-END. When the stream ends, the
	2488	* parser produces empty tokens.
	2489	*
	2490	* An application must not alternate calls of the functions
	2491	* `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
	2492	* `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
	2493	* the same parser object.
	2494	*
	2495	* Arguments:
	2496	*
	2497	* - `parser`: a parser object.
	2498	*
	2499	* - `token`: an empty token object to save the token produced by the parser.
	2500	* An application is responsible for clearing or deleting the produced token.
	2501	* If the parser fails or the stream end is reached, the object is kept
	2502	* empty.
	2503	*
	2504	* Returns: `1` on success, `0` on error. If the function succeeds and the
	2505	* stream end is not reached, the token data is saved to the given token
	2506	* object. If the function fails, the error details could be obtained with
	2507	* `yaml_parser_get_error()`. In case of error, the parser is non-functional
	2508	* until it is cleared.
1435	2509	*/
1436	2510
…	…
1438	2512	yaml_parser_parse_token(yaml_parser_t parser, yaml_token_t token);
1439	2513
1440		/**
	2514	/*
1441	2515	* Parse the input stream and produce the next parsing event.
1442	2516	*
1443		* Call the function subsequently to produce a sequence of events corresponding
1444		* to the input stream. The initial event has the type
1445		* @c YAML_STREAM_START_EVENT while the ending event has the type
1446		* @c YAML_STREAM_END_EVENT.
1447		*
1448		* An application is responsible for freeing any buffers associated with the
1449		* produced event object using the @c yaml_event_delete() function.
1450		*
1451		* An application must not alternate the calls of @c yaml_parser_parse() with
1452		* the calls of @c yaml_parser_scan() or @c yaml_parser_load(). Doing this will
1453		* break the parser.
1454		*
1455		* @param[in,out] parser A parser object.
1456		* @param[out] event An empty event object.
1457		*
1458		* @returns @c 1 if the function succeeded, @c 0 on error.
	2517	* An application may call this function subsequently to produce a sequence of
	2518	* events corresponding to the input stream. The produced events satisfy
	2519	* the grammar:
	2520	*
	2521	* stream ::= STREAM-START document* STREAM-END
	2522	* document ::= DOCUMENT-START node DOCUMENT-END
	2523	* node ::= ALIAS \| SCALAR \| sequence \| mapping
	2524	* sequence ::= SEQUENCE-START node* SEQUENCE-END
	2525	* mapping ::= MAPPING-START (node node)* MAPPING-END
	2526	*
	2527	* When the stream ends, the parser produces empty tokens.
	2528	*
	2529	* An application must not alternate calls of the functions
	2530	* `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
	2531	* `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
	2532	* the same parser object.
	2533	*
	2534	* Arguments:
	2535	*
	2536	* - `parser`: a parser object.
	2537	*
	2538	* - `event`: an empty event object to save the event produced by the parser.
	2539	* An application is responsible for clearing or deleting the produced event.
	2540	* Alternatively the produced event could be fed to the emitter. If the
	2541	* parser fails or the stream end is reached, the object is kept empty.
	2542	*
	2543	* Returns: `1` on success, `0` on error. If the function succeeds and the
	2544	* stream end is not reached, the event data is saved to the given event
	2545	* object. If the function fails, the error details could be obtained with
	2546	* `yaml_parser_get_error()`. In case of error, the parser is non-functional
	2547	* until it is cleared.
1459	2548	*/
1460	2549
…	…
1462	2551	yaml_parser_parse_event(yaml_parser_t parser, yaml_event_t event);
1463	2552
1464		#if 0
1465
1466		/**
	2553	/*
1467	2554	* Parse the input stream and produce the next YAML document.
1468	2555	*
1469		* Call this function subsequently to produce a sequence of documents
1470		* constituting the input stream.
1471		*
1472		* If the produced document has no root node, it means that the document
1473		* end has been reached.
1474		*
1475		* An application is responsible for freeing any data associated with the
1476		* produced document object using the @c yaml_document_delete() function.
1477		*
1478		* An application must not alternate the calls of @c yaml_parser_load() with
1479		* the calls of @c yaml_parser_scan() or @c yaml_parser_parse(). Doing this
1480		* will break the parser.
1481		*
1482		* @param[in,out] parser A parser object.
1483		* @param[out] document An empty document object.
1484		*
1485		* @return @c 1 if the function succeeded, @c 0 on error.
	2556	* An application may call this function subsequently to produce a sequence of
	2557	* documents constituting the input stream. When the stream ends, the parser
	2558	* produces empty documents.
	2559	*
	2560	* An application must not alternate calls of the functions
	2561	* `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
	2562	* `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
	2563	* the same parser object.
	2564	*
	2565	* Arguments:
	2566	*
	2567	* - `parser`: a parser object.
	2568	*
	2569	* - `document`: an empty document object to save the document produced by the
	2570	* parser. An application is responsible for clearing or deleting the
	2571	* produced document. Alternatively the produced document could be fed to
	2572	* the emitter. If the parser fails or the stream end is reached, the object
	2573	* is kept empty.
	2574	*
	2575	* Returns: `1` on success, `0` on error. If the function succeeds and the
	2576	* stream end is not reached, the document data is saved to the given document
	2577	* object. If the function fails, the error details could be obtained with
	2578	* `yaml_parser_get_error()`. In case of error, the parser is non-functional
	2579	* until it is cleared.
1486	2580	*/
1487	2581
…	…
1489	2583	yaml_parser_parse_document(yaml_parser_t parser, yaml_document_t document);
1490	2584
1491		#endif
1492
1493		/** @} */
1494
1495		/**
1496		* @defgroup emitter Emitter Definitions
1497		* @{
1498		*/
1499
1500		/** The emitter object. */
	2585	/*
	2586	* Parse the input stream containing a single YAML document.
	2587	*
	2588	* An application may call this function to ensure that the input stream contain
	2589	* no more that one document. If the stream is empty, the parser produces an
	2590	* empty document. If the stream contains a single document, the parser returns
	2591	* it. If the stream contains more than one document, the parser produces an
	2592	* error.
	2593	*
	2594	* An application must not alternate calls of the functions
	2595	* `yaml_parser_parse_token()`, `yaml_parser_parse_event()`,
	2596	* `yaml_parser_parse_document()` and `yaml_parser_parse_single_document()` on
	2597	* the same parser object.
	2598	*
	2599	* Arguments:
	2600	*
	2601	* - `parser`: a parser object.
	2602	*
	2603	* - `document`: an empty document object to save the document produced by the
	2604	* parser. An application is responsible for clearing or deleting the
	2605	* produced document. Alternatively the produced document could be fed to
	2606	* the emitter. If the parser fails or the stream is empty, the object is
	2607	* kept empty.
	2608	*
	2609	* Returns: `1` on success, `0` on error. If the function succeeds and the
	2610	* stream is not empty, the document data is saved to the given document
	2611	* object. If the function fails, the error details could be obtained with
	2612	* `yaml_parser_get_error()`. In case of error, the parser is non-functional
	2613	* until it is cleared.
	2614	*/
	2615
	2616	YAML_DECLARE(int)
	2617	yaml_parser_parse_single_document(yaml_parser_t *parser,
	2618	yaml_document_t *document);
	2619
	2620	/******************************************************************************
	2621	* Emitter Definitions
	2622	******************************************************************************/
	2623
	2624	/*
	2625	* An opaque definition of the emitter object.
	2626	*
	2627	* An emitter object is used to emit YAML events or documents into an output
	2628	* YAML stream.
	2629	*/
	2630
1501	2631	typedef struct yaml_emitter_s yaml_emitter_t;
1502	2632
1503		/**
1504		* ~~Cre~~ate a new emitter object.
1505		*
1506		* ~~This function creates a new emitter object. An application is responsible~~
1507		* ~~for destroying the object using the @c yaml_emitter_delete() function.~~
1508		*
1509		* ~~@returns a new emitter object or @c NULL on error~~.
	2633	/*
	2634	* Allocate a new emitter object.
	2635	*
	2636	* An allocated emitter object should be deleted with `yaml_emitter_delete()`.
	2637	*
	2638	* Returns: a new emitter or `NULL` on error. The function mail fail if it
	2639	* cannot allocate memory for internal buffers.
1510	2640	*/
1511	2641
…	…
1513	2643	yaml_emitter_new(void);
1514	2644
1515		/**
1516		* Destroy an emitter.
1517		*
1518		* @param[in,out] emitter An emitter object.
	2645	/*
	2646	* Deallocate an emitter and free the internal emitter data.
	2647	*
	2648	* An emitter object must be previously allocated with `yaml_emitter_new()`.
	2649	*
	2650	* Arguments:
	2651	*
	2652	* - `emitter`: an emitter object.
1519	2653	*/
1520	2654
…	…
1522	2656	yaml_emitter_delete(yaml_emitter_t *emitter);
1523	2657
1524		/**
1525		* Get an emitter error.
1526		*
1527		* @param[in] emitter An emitter object.
1528		* @param[out] error An error object.
	2658	/*
	2659	* Clear and reinitialize the internal state of the emitter.
	2660	*
	2661	* This function could be used for cleaning up an emitter object after an error
	2662	* condition or after a complete YAML stream was produced. A cleaned emitter
	2663	* object may be reused to produce another YAML stream. Note that all the
	2664	* emitter parameters including the write handler must be reset.
	2665	*
	2666	* Arguments:
	2667	*
	2668	* - `emitter`: an emitter object.
1529	2669	*/
1530	2670
1531	2671	YAML_DECLARE(void)
1532		yaml_emitter_get_error(yaml_emitter_t emitter, yaml_error_t error);
1533
1534		/**
1535		* Set a string output.
1536		*
1537		* The emitter will write the output characters to the @a output buffer of the
1538		* size @a size. The emitter will set @a size_written to the number of written
1539		* bytes. If the buffer is smaller than required, the emitter produces the
1540		* @c YAML_WRITE_ERROR error.
1541		*
1542		* @param[in,out] emitter An emitter object.
1543		* @param[in] buffer An output buffer.
1544		* @param[in] capacity The buffer size.
1545		* @param[in] length The pointer to save the number of written
1546		* bytes.
	2672	yaml_emitter_clear(yaml_emitter_t *emitter);
	2673
	2674	/*
	2675	* Get the emitter error.
	2676	*
	2677	* Use this function to get a detailed error information after failure of one
	2678	* of the following functions: `yaml_emitter_emit_event()`,
	2679	* `yaml_emitter_open()`, `yaml_emitter_close()`,
	2680	* `yaml_emitter_emit_document()`, `yaml_emitter_emit_single_document()`.
	2681	*
	2682	* The pointer returned by the function is only valid until the emitter object
	2683	* is not modified. However the error object could be safely copied.
	2684	*
	2685	* Arguments:
	2686	*
	2687	* - `emitter`: an emitter object.
	2688	*
	2689	* Returns: a pointer to an error object. The returned pointer is only valid
	2690	* until the emitter object is not modified or deleted. However the error
	2691	* object could be safely copied.
	2692	*/
	2693
	2694	YAML_DECLARE(yaml_error_t *)
	2695	yaml_emitter_get_error(yaml_emitter_t *emitter);
	2696
	2697	/*
	2698	* Set the emitter to dump the generated YAML stream into a string buffer.
	2699	*
	2700	* Arguments:
	2701	*
	2702	* - `emitter`: an emitter object.
	2703	*
	2704	* - `buffer`: a pointer to a buffer to store the generated YAML stream. The
	2705	* pointer must be valid until the emitter object is cleared or deleted.
	2706	*
	2707	* - `capacity`: the size of the buffer. The emitter will fail if the buffer
	2708	* is smaller than required to hold the whole stream.
	2709	*
	2710	* - `length`: a pointer to save the length of the produced stream (in bytes).
1547	2711	*/
1548	2712
…	…
1551	2715	unsigned char buffer, size_t capacity, size_t length);
1552	2716
1553		/**
1554		* Set a file output.
1555		*
1556		* @a file should be a file object open for writing. The application is
1557		* responsible for closing the @a file.
1558		*
1559		* @param[in,out] emitter An emitter object.
1560		* @param[in] file An open file.
	2717	/*
	2718	* Set the emitter to dump the generated YAML stream into a file.
	2719	*
	2720	* Arguments:
	2721	*
	2722	* - `emitter`: an emitter object.
	2723	*
	2724	* - `file`: a pointer to a file open for writing. The pointer must be valid
	2725	* until the emitter object is cleared or deleted.
1561	2726	*/
1562	2727
…	…
1564	2729	yaml_emitter_set_file_writer(yaml_emitter_t emitter, FILE file);
1565	2730
1566		/**
1567		* Set a generic output handler.
1568		*
1569		* @param[in,out] emitter An emitter object.
1570		* @param[in] writer A write handler.
1571		* @param[in] data Any application data for passing to the write
1572		* handler.
	2731	/*
	2732	* Set the output stream writer for an emitter.
	2733	*
	2734	* Arguments:
	2735	*
	2736	* - `emitter`: an emitter object.
	2737	*
	2738	* - `writer`: a write handler.
	2739	*
	2740	* - `data`: application data for passing to the writer.
1573	2741	*/
1574	2742
…	…
1577	2745	yaml_writer_t writer, void data);
1578	2746
1579		#if 0
1580
1581		/**
1582		* ~~Set the standard resolve handler.~~
1583		*
1584		* ~~The standard resolver recognize the following scalar kinds: !!null, !!bool,~~
1585		* ~~!!str, !!int and !!float.~~
1586		*
1587		* ~~@param[in,out] emitter A~~n emitter object.
	2747	/*
	2748	* Set the standard nonspecific tag resolver for an emitter.
	2749	*
	2750	* The standard resolver recognizes the following scalar tags: `!!null`,
	2751	* `!!bool`, `!!str`, `!!int`, and `!!float`.
	2752	*
	2753	* Arguments:
	2754	*
	2755	* - `emitter`: an emitter object.
1588	2756	*/
1589	2757
…	…
1591	2759	yaml_emitter_set_standard_resolver(yaml_emitter_t *emitter);
1592	2760
1593		/**
1594		* Set ~~the resolve handl~~er.
1595		*
1596		* ~~The standard resolver recognize the following scalar kinds: !!null, !!bool,~~
1597		* ~~!!str, !!int and !!float.~~
1598		*
1599		* ~~@param[in,out] emitter An emitter object.~~
1600		* ~~@param[in] resolver A~~ resolve handler.
1601		* ~~@param[in] data Any application data for passing to the resolve~~
1602		* ~~handl~~er.
	2761	/*
	2762	* Set a nonspecific tag resolver for an emitter.
	2763	*
	2764	* Arguments:
	2765	*
	2766	* - `emitter`: an emitter object.
	2767	*
	2768	* - `resolver`: a resolve handler.
	2769	*
	2770	* - `data`: application data for passing to the resolver.
1603	2771	*/
1604	2772
…	…
1607	2775	yaml_resolver_t resolver, void data);
1608	2776
1609		#endif
1610
1611		/**
1612		* Set the output encoding.
1613		*
1614		* @param[in,out] emitter An emitter object.
1615		* @param[in] encoding The output encoding.
	2777	/*
	2778	* Set the output stream encoding.
	2779	*
	2780	* The emitter uses the UTF-8 encoding for the output stream unless another
	2781	* encoding is specified explicitly. The encoding could be specified using
	2782	* this function or via the `encoding` parameter of the STREAM-START event.
	2783	*
	2784	* Arguments:
	2785	*
	2786	* - `emitter`: an emitter object.
	2787	*
	2788	* - `encoding`: the output stream encoding.
1616	2789	*/
1617	2790
…	…
1619	2792	yaml_emitter_set_encoding(yaml_emitter_t *emitter, yaml_encoding_t encoding);
1620	2793
1621		/**
1622		* Set if the output should be in the "canonical" format as in the YAML
1623		* specification.
1624		*
1625		* @param[in,out] emitter An emitter object.
1626		* @param[in] is_canonical If the output is canonical.
	2794	/*
	2795	* Specify if the emitter should use the "canonical" output format.
	2796	*
	2797	* The "canonical" format uses the flow style for collections and the
	2798	* double-quoted style for scalars. Node tags are always dumped explicitly.
	2799	*
	2800	* Arguments:
	2801	*
	2802	* - `emitter`: an emitter object.
	2803	*
	2804	* - `is_canonical`: `1` to set the "canonical" format, `0` otherwise.
1627	2805	*/
1628	2806
…	…
1630	2808	yaml_emitter_set_canonical(yaml_emitter_t *emitter, int is_canonical);
1631	2809
1632		/**
	2810	/*
1633	2811	* Set the intendation increment.
1634	2812	*
1635		* @param[in,out] emitter An emitter object.
1636		* @param[in] indent The indentation increment (1 < . < 10).
	2813	* The default intendation increment is `2`.
	2814	*
	2815	* Arguments:
	2816	*
	2817	* - `emitter`: an emitter object.
	2818	*
	2819	* - `indent`: the indentation increment; a number between `2` and `9`.
1637	2820	*/
1638	2821
…	…
1640	2823	yaml_emitter_set_indent(yaml_emitter_t *emitter, int indent);
1641	2824
1642		/**
1643		* Set the preferred line width. @c -1 means unlimited.
1644		*
1645		* @param[in,out] emitter An emitter object.
1646		* @param[in] width The preferred line width.
	2825	/*
	2826	* Set the preferred line width.
	2827	*
	2828	* The default preferred line width is `80`. The given line width is only a
	2829	* stylistic hint and could be violated by the emitter. When the line width is
	2830	* exceeded, the emitter seeks for a way to move to the next line.
	2831	*
	2832	* Arguments:
	2833	*
	2834	* - `emitter`: an emitter object.
	2835	*
	2836	* - `width`: the preferred line width; `-1` means unlimited.
1647	2837	*/
1648	2838
…	…
1650	2840	yaml_emitter_set_width(yaml_emitter_t *emitter, int width);
1651	2841
1652		/**
1653		* Set if unescaped non-ASCII characters are allowed.
1654		*
1655		* @param[in,out] emitter An emitter object.
1656		* @param[in] is_unicode If unescaped Unicode characters are allowed.
	2842	/*
	2843	* Specify if non-ASCII characters could be emitted unescaped.
	2844	*
	2845	* By default, the emitter always escapes non-ASCII characters using the `\u`
	2846	* or `\U` format.
	2847	*
	2848	* Arguments:
	2849	*
	2850	* - `emitter`: an emitter object.
	2851	*
	2852	* - `is_unicode`: `1` if unescaped non-ASCII characters are allowed; `0`
	2853	* otherwise.
1657	2854	*/
1658	2855
…	…
1660	2857	yaml_emitter_set_unicode(yaml_emitter_t *emitter, int is_unicode);
1661	2858
1662		/**
	2859	/*
1663	2860	* Set the preferred line break.
1664	2861	*
1665		* @param[in,out] emitter An emitter object.
1666		* @param[in] line_break The preferred line break.
	2862	* By default, the emitter uses the LN character for line breaks.
	2863	*
	2864	* Arguments:
	2865	*
	2866	* - `emitter`: an emitter object.
	2867	*
	2868	* - `line_break`: the preferred line break.
1667	2869	*/
1668	2870
…	…
1670	2872	yaml_emitter_set_break(yaml_emitter_t *emitter, yaml_break_t line_break);
1671	2873
1672		/**
1673		* Emit an event.
1674		*
1675		* The event object may be generated using the yaml_parser_parse() function.
1676		* The emitter takes the responsibility for the event object and destroys its
1677		* content after it is emitted. The event object is destroyed even if the
1678		* function fails.
1679		*
1680		* @param[in,out] emitter An emitter object.
1681		* @param[in,out] event An event object.
1682		*
1683		* @returns @c 1 if the function succeeded, @c 0 on error.
	2874	/*
	2875	* Emit an event to the output YAML stream.
	2876	*
	2877	* An application needs to call this function subsequently to produce a whole
	2878	* YAML stream. The event sequence must satisfy the following grammar:
	2879	*
	2880	* stream ::= STREAM-START document* STREAM-END
	2881	* document ::= DOCUMENT-START node DOCUMENT-END
	2882	* node ::= ALIAS \| SCALAR \| sequence \| mapping
	2883	* sequence ::= SEQUENCE-START node* SEQUENCE-END
	2884	* mapping ::= MAPPING-START (node node)* MAPPING-END
	2885	*
	2886	* An application must not alternate the calls of the functions
	2887	* `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
	2888	* `yaml_emitter_emit_single_document()` on the same emitter object.
	2889	*
	2890	* Arguments:
	2891	*
	2892	* - `emitter`: an emitter object.
	2893	*
	2894	* - `event`: an event to emit. The event must be previously initialized using
	2895	* either one of the functions `yaml_event_create_*()` or with
	2896	* `yaml_parser_parse_event()`. The emitter takes the responsibility for the
	2897	* event data and clears the event, so that it becomes empty. The event is
	2898	* cleared even if the function fails.
	2899	*
	2900	* Returns: `1` on success, `0` on error. Note that the emitter may not
	2901	* immediately dump the given event, so that the function could indicate
	2902	* success on an errorneous event. In this case, some of the next calls of the
	2903	* function will generate an error. If the function fails, the error details
	2904	* could be obtained with `yaml_emitter_get_error()`. In case of error, the
	2905	* emitter is non-functional until it is cleared.
1684	2906	*/
1685	2907
…	…
1687	2909	yaml_emitter_emit_event(yaml_emitter_t emitter, yaml_event_t event);
1688	2910
1689		#if 0
1690
1691		/**
	2911	/*
1692	2912	* Start a YAML stream.
1693	2913	*
1694		* This function should be used before the first @c yaml_emitter_dump() is
1695		* called.
1696		*
1697		* @param[in,out] emitter An emitter object.
1698		*
1699		* @returns @c 1 if the function succeeded, @c 0 on error.
1700		*/
1701
1702		YAML_DECLARE(int)
1703		yaml_emitter_open(yaml_emitter_t *emitter);
1704
1705		/**
	2914	* This function should be used in conjunction with
	2915	* `yaml_emitter_emit_document()` and `yaml_emitter_end()`. This function must
	2916	* be called once before any documents are emitted.
	2917	*
	2918	* Arguments:
	2919	*
	2920	* - `emitter`: an emitter object.
	2921	*
	2922	* Returns: `1` on success, `0` on error. If the function fails, the error
	2923	* details could be obtained with `yaml_emitter_get_error()`. In case of
	2924	* error, the emitter is non-functional until it is cleared.
	2925	*/
	2926
	2927	YAML_DECLARE(int)
	2928	yaml_emitter_start(yaml_emitter_t *emitter);
	2929
	2930	/*
1706	2931	* Finish a YAML stream.
1707	2932	*
1708		* This function should be used after the last @c yaml_emitter_dump() is
1709		* called.
1710		*
1711		* @param[in,out] emitter An emitter object.
1712		*
1713		* @returns @c 1 if the function succeeded, @c 0 on error.
1714		*/
1715
1716		YAML_DECLARE(int)
1717		yaml_emitter_close(yaml_emitter_t *emitter);
1718
1719		/**
	2933	* This function should be used in conjunction with `yaml_emitter_start()` and
	2934	* `yaml_emitter_emit_document()`. This function must be called once after all
	2935	* documents are emitted.
	2936	*
	2937	* Arguments:
	2938	*
	2939	* - `emitter`: an emitter object.
	2940	*
	2941	* Returns: `1` on success, `0` on error. If the function fails, the error
	2942	* details could be obtained with `yaml_emitter_get_error()`. In case of
	2943	* error, the emitter is non-functional until it is cleared.
	2944	*/
	2945
	2946	YAML_DECLARE(int)
	2947	yaml_emitter_end(yaml_emitter_t *emitter);
	2948
	2949	/*
1720	2950	* Emit a YAML document.
1721	2951	*
1722		* The document object may be generated using the @c yaml_parser_load()
1723		* function or the @c yaml_document_initialize() function. The emitter takes
1724		* the responsibility for the document object and destoys its content after
1725		* it is emitted. The document object is destroyed even if the function fails.
1726		*
1727		* @param[in,out] emitter An emitter object.
1728		* @param[in,out] document A document object.
1729		*
1730		* @returns @c 1 if the function succeeded, @c 0 on error.
	2952	* Before emitting any documents, the function `yaml_emitter_start()` must be
	2953	* called. After all documents are emitted, the function `yaml_emitter_end()`
	2954	* must be called.
	2955	*
	2956	* An application must not alternate the calls of the functions
	2957	* `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
	2958	* `yaml_emitter_emit_single_document()` on the same emitter object.
	2959	*
	2960	* Arguments:
	2961	*
	2962	* - `emitter`: an emitter object.
	2963	*
	2964	* - `document`: a document to emit. The document must have a root node with
	2965	* all the other nodes reachable from it. The document may be prepared using
	2966	* the functions `yaml_document_create()`, `yaml_document_add_*()` and
	2967	* `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`.
	2968	* The emitter takes the responsibility for the document content and clears
	2969	* the document, so that it becomes empty. The document is cleared even if
	2970	* the function fails.
	2971	*
	2972	* Returns: `1` on success, `0` on error. If the function fails, the error
	2973	* details could be obtained with `yaml_emitter_get_error()`. In case of
	2974	* error, the emitter is non-functional until it is cleared.
1731	2975	*/
1732	2976
…	…
1734	2978	yaml_emitter_emit_document(yaml_emitter_t emitter, yaml_document_t document);
1735	2979
1736		#endif
1737
1738		/**
1739		* Flush the accumulated characters to the output stream.
1740		*
1741		* @param[in,out] emitter An emitter object.
1742		*
1743		* @returns @c 1 if the function succeeded, @c 0 on error.
	2980	/*
	2981	* Emit a YAML stream consisting of a single document.
	2982	*
	2983	* This function is a shorthand of the calls:
	2984	*
	2985	* yaml_emitter_start(emitter)
	2986	* yaml_emitter_emit_document(emitter, document)
	2987	* yaml_emitter_end(emitter)
	2988	*
	2989	* An application must not alternate the calls of the functions
	2990	* `yaml_emitter_emit_event()`, `yaml_emitter_emit_document()` and
	2991	* `yaml_emitter_emit_single_document()` on the same emitter object.
	2992	*
	2993	* Arguments:
	2994	*
	2995	* - `emitter`: an emitter object.
	2996	*
	2997	* - `document`: a document to emit. The document must have a root node with
	2998	* all the other nodes reachable from it. The document may be prepared using
	2999	* the functions `yaml_document_create()`, `yaml_document_add_*()` and
	3000	* `yaml_document_append_*()` or obtained via `yaml_parser_parse_document()`.
	3001	* The emitter takes the responsibility for the document content and clears
	3002	* the document, so that it becomes empty. The document is cleared even if
	3003	* the function fails.
	3004	*
	3005	* Returns: `1` on success, `0` on error. If the function fails, the error
	3006	* details could be obtained with `yaml_emitter_get_error()`. In case of
	3007	* error, the emitter is non-functional until it is cleared.
	3008	*/
	3009
	3010	YAML_DECLARE(int)
	3011	yaml_emitter_emit_single_document(yaml_emitter_t *emitter,
	3012	yaml_document_t *document);
	3013
	3014	/*
	3015	* Flush the accumulated characters.
	3016	*
	3017	* This function flushes the accumulated characters from the internal emitter
	3018	* buffer to the output stream. Note that the buffer is flushed automatically
	3019	* when a complete document has emitted or a stream has ended.
	3020	*
	3021	* Arguments:
	3022	*
	3023	* - `emitter`: an emitter object.
	3024	*
	3025	* Returns: `1` on success, `0` on error. If the function fails, the error
	3026	* details could be obtained with `yaml_emitter_get_error()`. In case of
	3027	* error, the emitter is non-functional until it is cleared.
1744	3028	*/
1745	3029
…	…
1747	3031	yaml_emitter_flush(yaml_emitter_t *emitter);
1748	3032
1749		~~/** @} */~~
1750	3033
1751	3034	#ifdef __cplusplus

Context Navigation

Changeset 266 for libyaml/trunk/include/yaml.h

Legend:

libyaml/trunk/include/yaml.h

Download in other formats: