Context Navigation

← Previous Changeset
Next Changeset →

Changeset 266

Timestamp:

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

Author:

Message:

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

Location:

libyaml/trunk

Files:

: 1 removed
: 3 modified

README (modified) (3 diffs)
doc (deleted)
include/Makefile.am (modified) (1 diff)
include/yaml.h (modified) (60 diffs)

Legend:

: Unmodified
: Added
: Removed

libyaml/trunk/README

r220	r266
1	1	LibYAML - A C library for parsing and emitting YAML.
2
3		~~The project is in an early stage of development.~~
4	2
5	3	To build and install the library, run:
…	…
14	12	# make install
15	13
16		For more information, check the LibYAML homepage:
	14	For the API reference, check the file 'include/yaml.h'. Examples on how to use
	15	LibYAML could be found in the 'tests' directory.
	16
	17	Check the LibYAML homepage for more information:
17	18	'http://pyyaml.org/wiki/LibYAML'.
18	19
…	…
26	27	under the MIT license. See the file LICENSE for more details.
27	28
28		This project is developed for Python Software Foundation as a part of
29		Google Summer of Code under the mentorship of Clark Evans.
	29	The initial version of this project was developed for Python Software
	30	Foundation under the mentorshipf of Clark Evans as a part of Google Summer of
	31	Code 2006.

libyaml/trunk/include/Makefile.am

r200	r266
1	1	INCLUDES = yaml.h
2		~~DOXYGEN_CFG = $(top_srcdir)/doc/doxygen.cfg~~
3	2
4	3	nobase_include_HEADERS = $(INCLUDES)
5	4
6		~~if DOXYGEN~~
7
8		~~html: $(INCLUDES) $(DOXYGEN_CFG)~~
9		~~PACKAGE=$(PACKAGE) VERSION=$(VERSION) top_srcdir=$(top_srcdir) top_builddir=$(top_builddir) doxygen $(DOXYGEN_CFG)~~
10
11		~~endif~~
12
13		~~distclean-local:~~
14		~~-rm -rf $(top_builddir)/doc/html~~
15
16		~~dist-hook: html~~
17		~~cp -a $(top_builddir)/doc/html $(top_distdir)/doc~~

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