Fossil SCM

fossil-scm / extsrc / cson_amalgamation.h

Source Blame History 2871 lines

b62f651…	stephan	1	#ifdef FOSSIL_ENABLE_JSON
b62f651…	stephan	2	#ifndef CSON_FOSSIL_MODE
b62f651…	stephan	3	#define CSON_FOSSIL_MODE
b62f651…	stephan	4	#endif
b62f651…	stephan	5	/* auto-generated! Do not edit! */
b62f651…	stephan	6	/* begin file include/wh/cson/cson.h */
b62f651…	stephan	7	#if !defined(WANDERINGHORSE_NET_CSON_H_INCLUDED)
b62f651…	stephan	8	#define WANDERINGHORSE_NET_CSON_H_INCLUDED 1
b62f651…	stephan	9
b62f651…	stephan	10	/#include <stdint.h> C99: fixed-size int types. /
b62f651…	stephan	11	#include <stdio.h> /* FILE decl */
b62f651…	stephan	12
40a14c1…	stephan	13	#include <stdarg.h>
40a14c1…	stephan	14
b62f651…	stephan	15	/** @page page_cson cson JSON API
b62f651…	stephan	16
b62f651…	stephan	17	cson (pronounced "season") is an object-oriented C API for generating
b62f651…	stephan	18	and consuming JSON (http://www.json.org) data.
b62f651…	stephan	19
b62f651…	stephan	20	Its main claim to fame is that it can parse JSON from, and output it
b62f651…	stephan	21	to, damned near anywhere. The i/o routines use a callback function to
b62f651…	stephan	22	fetch/emit JSON data, allowing clients to easily plug in their own
b62f651…	stephan	23	implementations. Implementations are provided for string- and
b62f651…	stephan	24	FILE-based i/o.
b62f651…	stephan	25
40a14c1…	stephan	26	Project home page: https://fossil.wanderinghorse.net/r/cson
b62f651…	stephan	27
40a14c1…	stephan	28	Author: Stephan Beal (https://www.wanderinghorse.net/home/stephan/)
b62f651…	stephan	29
b62f651…	stephan	30	License: Dual Public Domain/MIT
b62f651…	stephan	31
b62f651…	stephan	32	The full license text is at the bottom of the main header file
b62f651…	stephan	33	(cson.h).
b62f651…	stephan	34
b62f651…	stephan	35	Examples of how to use the library are scattered throughout
b62f651…	stephan	36	the API documentation, in the test.c file in the source repo,
b62f651…	stephan	37	and in the wiki on the project's home page.
b62f651…	stephan	38	*/
b62f651…	stephan	39
b62f651…	stephan	40	#if defined(__cplusplus)
b62f651…	stephan	41	extern "C" {
b62f651…	stephan	42	#endif
b62f651…	stephan	43
b62f651…	stephan	44	#if defined(_WIN32) \|\| defined(_WIN64)
b62f651…	stephan	45	# define CSON_ENABLE_UNIX 0
b62f651…	stephan	46	#else
b62f651…	stephan	47	# define CSON_ENABLE_UNIX 1
b62f651…	stephan	48	#endif
b62f651…	stephan	49
b62f651…	stephan	50
b62f651…	stephan	51	/** @typedef some_long_int_type cson_int_t
b62f651…	stephan	52
b62f651…	stephan	53	Typedef for JSON-like integer types. This is (long long) where feasible,
b62f651…	stephan	54	otherwise (long).
b62f651…	stephan	55	*/
b62f651…	stephan	56	#ifdef _WIN32
b62f651…	stephan	57	typedef __int64 cson_int_t;
b62f651…	stephan	58	#define CSON_INT_T_SFMT "I64d"
b62f651…	stephan	59	#define CSON_INT_T_PFMT "I64d"
b62f651…	stephan	60	#elif (__STDC_VERSION__ >= 199901L) \|\| (HAVE_LONG_LONG == 1)
b62f651…	stephan	61	typedef long long cson_int_t;
b62f651…	stephan	62	#define CSON_INT_T_SFMT "lld"
b62f651…	stephan	63	#define CSON_INT_T_PFMT "lld"
b62f651…	stephan	64	#else
b62f651…	stephan	65	typedef long cson_int_t;
b62f651…	stephan	66	#define CSON_INT_T_SFMT "ld"
b62f651…	stephan	67	#define CSON_INT_T_PFMT "ld"
b62f651…	stephan	68	#endif
b62f651…	stephan	69
b62f651…	stephan	70	/** @typedef double_or_long_double cson_double_t
b62f651…	stephan	71
b62f651…	stephan	72	This is the type of double value used by the library.
b62f651…	stephan	73	It is only lightly tested with long double, and when using
b62f651…	stephan	74	long double the memory requirements for such values goes
b62f651…	stephan	75	up.
b62f651…	stephan	76
b62f651…	stephan	77	Note that by default cson uses C-API defaults for numeric
b62f651…	stephan	78	precision. To use a custom precision throughout the library, one
b62f651…	stephan	79	needs to define the macros CSON_DOUBLE_T_SFMT and/or
b62f651…	stephan	80	CSON_DOUBLE_T_PFMT macros to include their desired precision, and
b62f651…	stephan	81	must build BOTH cson AND the client using these same values. For
b62f651…	stephan	82	example:
b62f651…	stephan	83
b62f651…	stephan	84	@code
b62f651…	stephan	85	#define CSON_DOUBLE_T_PFMT ".8Lf" // for Modified Julian Day values
b62f651…	stephan	86	#define HAVE_LONG_DOUBLE
b62f651…	stephan	87	@endcode
b62f651…	stephan	88
b62f651…	stephan	89	(Only CSON_DOUBLE_T_PFTM should be needed for most
b62f651…	stephan	90	purposes.)
b62f651…	stephan	91	*/
b62f651…	stephan	92
b62f651…	stephan	93	#if defined(HAVE_LONG_DOUBLE)
b62f651…	stephan	94	typedef long double cson_double_t;
b62f651…	stephan	95	# ifndef CSON_DOUBLE_T_SFMT
b62f651…	stephan	96	# define CSON_DOUBLE_T_SFMT "Lf"
b62f651…	stephan	97	# endif
b62f651…	stephan	98	# ifndef CSON_DOUBLE_T_PFMT
b62f651…	stephan	99	# define CSON_DOUBLE_T_PFMT "Lf"
b62f651…	stephan	100	# endif
b62f651…	stephan	101	#else
b62f651…	stephan	102	typedef double cson_double_t;
b62f651…	stephan	103	# ifndef CSON_DOUBLE_T_SFMT
b62f651…	stephan	104	# define CSON_DOUBLE_T_SFMT "f"
b62f651…	stephan	105	# endif
b62f651…	stephan	106	# ifndef CSON_DOUBLE_T_PFMT
b62f651…	stephan	107	# define CSON_DOUBLE_T_PFMT "f"
b62f651…	stephan	108	# endif
b62f651…	stephan	109	#endif
b62f651…	stephan	110
b62f651…	stephan	111	/** @def CSON_VOID_PTR_IS_BIG
b62f651…	stephan	112
b62f651…	stephan	113	ONLY define this to a true value if you know that
b62f651…	stephan	114
b62f651…	stephan	115	(sizeof(cson_int_t) <= sizeof(void*))
b62f651…	stephan	116
b62f651…	stephan	117	If that is the case, cson does not need to dynamically
b62f651…	stephan	118	allocate integers. However, enabling this may cause
b62f651…	stephan	119	compilation warnings in 32-bit builds even though the code
b62f651…	stephan	120	being warned about cannot ever be called. To get around such
b62f651…	stephan	121	warnings, when building on a 64-bit environment you can define
b62f651…	stephan	122	this to 1 to get "big" integer support. HOWEVER, all clients must
b62f651…	stephan	123	also use the same value for this macro. If i knew a halfway reliable
b62f651…	stephan	124	way to determine this automatically at preprocessor-time, i would
b62f651…	stephan	125	automate this. We might be able to do halfway reliably by looking
b62f651…	stephan	126	for a large INT_MAX value?
b62f651…	stephan	127	*/
b62f651…	stephan	128	#if !defined(CSON_VOID_PTR_IS_BIG)
b62f651…	stephan	129
b62f651…	stephan	130	/* Largely taken from http://predef.sourceforge.net/prearch.html
b62f651…	stephan	131
b62f651…	stephan	132	See also: http://poshlib.hookatooka.com/poshlib/trac.cgi/browser/posh.h
b62f651…	stephan	133	*/
b62f651…	stephan	134	# if defined(_WIN64) \|\| defined(__LP64__)/gcc/ \
b62f651…	stephan	135	\|\| defined(_M_X64) \|\| defined(__amd64__) \|\| defined(__amd64) \
b62f651…	stephan	136	\|\| defined(__x86_64__) \|\| defined(__x86_64) \
b62f651…	stephan	137	\|\| defined(__ia64__) \|\| defined(__ia64) \|\| defined(_IA64) \|\| defined(__IA64__) \
b62f651…	stephan	138	\|\| defined(_M_IA64) \
b62f651…	stephan	139	\|\| defined(__sparc_v9__) \|\| defined(__sparcv9) \|\| defined(_ADDR64) \
b62f651…	stephan	140	\|\| defined(__64BIT__)
b62f651…	stephan	141	# define CSON_VOID_PTR_IS_BIG 1
b62f651…	stephan	142	# else
b62f651…	stephan	143	# define CSON_VOID_PTR_IS_BIG 0
b62f651…	stephan	144	# endif
b62f651…	stephan	145	#endif
b62f651…	stephan	146
b62f651…	stephan	147	/** @def CSON_INT_T_SFMT
b62f651…	stephan	148
b62f651…	stephan	149	scanf()-compatible format token for cson_int_t.
b62f651…	stephan	150	*/
b62f651…	stephan	151
b62f651…	stephan	152	/** @def CSON_INT_T_PFMT
b62f651…	stephan	153
b62f651…	stephan	154	printf()-compatible format token for cson_int_t.
b62f651…	stephan	155	*/
b62f651…	stephan	156
b62f651…	stephan	157
b62f651…	stephan	158	/** @def CSON_DOUBLE_T_SFMT
b62f651…	stephan	159
b62f651…	stephan	160	scanf()-compatible format token for cson_double_t.
b62f651…	stephan	161	*/
b62f651…	stephan	162
b62f651…	stephan	163	/** @def CSON_DOUBLE_T_PFMT
b62f651…	stephan	164
b62f651…	stephan	165	printf()-compatible format token for cson_double_t.
b62f651…	stephan	166	*/
b62f651…	stephan	167
b62f651…	stephan	168	/**
b62f651…	stephan	169	Type IDs corresponding to JavaScript/JSON types.
b62f651…	stephan	170
b62f651…	stephan	171	These are only in the public API to allow O(1) client-side
b62f651…	stephan	172	dispatching based on cson_value types.
b62f651…	stephan	173	*/
b62f651…	stephan	174	enum cson_type_id {
b62f651…	stephan	175	/**
b62f651…	stephan	176	The special "undefined" value constant.
b62f651…	stephan	177
b62f651…	stephan	178	Its value must be 0 for internal reasons.
b62f651…	stephan	179	*/
b62f651…	stephan	180	CSON_TYPE_UNDEF = 0,
b62f651…	stephan	181	/**
b62f651…	stephan	182	The special "null" value constant.
b62f651…	stephan	183	*/
b62f651…	stephan	184	CSON_TYPE_NULL = 1,
b62f651…	stephan	185	/**
b62f651…	stephan	186	The bool value type.
b62f651…	stephan	187	*/
b62f651…	stephan	188	CSON_TYPE_BOOL = 2,
b62f651…	stephan	189	/**
b62f651…	stephan	190	The integer value type, represented in this library
b62f651…	stephan	191	by cson_int_t.
b62f651…	stephan	192	*/
b62f651…	stephan	193	CSON_TYPE_INTEGER = 3,
b62f651…	stephan	194	/**
b62f651…	stephan	195	The double value type, represented in this library
b62f651…	stephan	196	by cson_double_t.
b62f651…	stephan	197	*/
b62f651…	stephan	198	CSON_TYPE_DOUBLE = 4,
b62f651…	stephan	199	/** The immutable string type. This library stores strings
b62f651…	stephan	200	as immutable UTF8.
b62f651…	stephan	201	*/
b62f651…	stephan	202	CSON_TYPE_STRING = 5,
b62f651…	stephan	203	/** The "Array" type. */
b62f651…	stephan	204	CSON_TYPE_ARRAY = 6,
b62f651…	stephan	205	/** The "Object" type. */
b62f651…	stephan	206	CSON_TYPE_OBJECT = 7
b62f651…	stephan	207	};
b62f651…	stephan	208	/**
b62f651…	stephan	209	Convenience typedef.
b62f651…	stephan	210	*/
b62f651…	stephan	211	typedef enum cson_type_id cson_type_id;
b62f651…	stephan	212
b62f651…	stephan	213
b62f651…	stephan	214	/**
b62f651…	stephan	215	Convenience typedef.
b62f651…	stephan	216	*/
b62f651…	stephan	217	typedef struct cson_value cson_value;
b62f651…	stephan	218
b62f651…	stephan	219	/** @struct cson_value
b62f651…	stephan	220
b62f651…	stephan	221	The core value type of this API. It is opaque to clients, and
b62f651…	stephan	222	only the cson public API should be used for setting or
b62f651…	stephan	223	inspecting their values.
b62f651…	stephan	224
b62f651…	stephan	225	This class is opaque because stack-based usage can easily cause
b62f651…	stephan	226	leaks if one does not intimately understand the underlying
b62f651…	stephan	227	internal memory management (which sometimes changes).
b62f651…	stephan	228
b62f651…	stephan	229	It is (as of 20110323) legal to insert a given value instance into
b62f651…	stephan	230	multiple containers (they will share ownership using reference
b62f651…	stephan	231	counting) as long as those insertions do not cause cycles. However,
b62f651…	stephan	232	be very aware that such value re-use uses a reference to the
b62f651…	stephan	233	original copy, meaning that if its value is changed once, it is
b62f651…	stephan	234	changed everywhere. Also beware that multi-threaded write
b62f651…	stephan	235	operations on such references leads to undefined behaviour.
b62f651…	stephan	236
b62f651…	stephan	237	PLEASE read the ACHTUNGEN below...
b62f651…	stephan	238
b62f651…	stephan	239	ACHTUNG #1:
b62f651…	stephan	240
b62f651…	stephan	241	cson_values MUST NOT form cycles (e.g. via object or array
b62f651…	stephan	242	entries).
b62f651…	stephan	243
b62f651…	stephan	244	Not abiding th Holy Law Of No Cycles will lead to double-frees and
b62f651…	stephan	245	the like (i.e. undefined behaviour, likely crashes due to infinite
b62f651…	stephan	246	recursion or stepping on invalid (freed) pointers).
b62f651…	stephan	247
b62f651…	stephan	248	ACHTUNG #2:
b62f651…	stephan	249
b62f651…	stephan	250	ALL cson_values returned as non-const cson_value pointers from any
b62f651…	stephan	251	public functions in the cson API are to be treated as if they are
b62f651…	stephan	252	heap-allocated, and MUST be freed by client by doing ONE of:
b62f651…	stephan	253
b62f651…	stephan	254	- Passing it to cson_value_free().
b62f651…	stephan	255
b62f651…	stephan	256	- Adding it to an Object or Array, in which case the object/array
b62f651…	stephan	257	takes over ownership. As of 20110323, a value may be inserted into
b62f651…	stephan	258	a single container multiple times, or into multiple containers,
b62f651…	stephan	259	in which case they all share ownership (via reference counting)
b62f651…	stephan	260	of the original value (meaning any changes to it are visible in
b62f651…	stephan	261	all references to it).
b62f651…	stephan	262
b62f651…	stephan	263	Each call to cson_value_new_xxx() MUST eventually be followed up
b62f651…	stephan	264	by one of those options.
b62f651…	stephan	265
b62f651…	stephan	266	Some cson_value_new_XXX() implementations do not actually allocate
b62f651…	stephan	267	memory, but this is an internal implementation detail. Client code
b62f651…	stephan	268	MUST NOT rely on this behaviour and MUST treat each object
b62f651…	stephan	269	returned by such a function as if it was a freshly-allocated copy
b62f651…	stephan	270	(even if their pointer addresses are the same).
b62f651…	stephan	271
b62f651…	stephan	272	ACHTUNG #3:
b62f651…	stephan	273
b62f651…	stephan	274	Note that ACHTUNG #2 tells us that we must always free (or transfer
b62f651…	stephan	275	ownership of) all pointers returned bycson_value_new_xxx(), but
b62f651…	stephan	276	that two calls to (e.g.) cson_value_new_bool(1) will (or might)
b62f651…	stephan	277	return the same address. The client must not rely on the
b62f651…	stephan	278	"non-allocation" policy of such special cases, and must pass each
b62f651…	stephan	279	returned value to cson_value_free(), even if two of them have the
b62f651…	stephan	280	same address. Some special values (e.g. null, true, false, integer
b62f651…	stephan	281	0, double 0.0, and empty strings) use shared copies and in other
b62f651…	stephan	282	places reference counting is used internally to figure out when it
b62f651…	stephan	283	is safe to destroy an object.
b62f651…	stephan	284
b62f651…	stephan	285
b62f651…	stephan	286	@see cson_value_new_array()
b62f651…	stephan	287	@see cson_value_new_object()
b62f651…	stephan	288	@see cson_value_new_string()
b62f651…	stephan	289	@see cson_value_new_integer()
b62f651…	stephan	290	@see cson_value_new_double()
b62f651…	stephan	291	@see cson_value_new_bool()
b62f651…	stephan	292	@see cson_value_true()
b62f651…	stephan	293	@see cson_value_false()
b62f651…	stephan	294	@see cson_value_null()
b62f651…	stephan	295	@see cson_value_free()
b62f651…	stephan	296	@see cson_value_type_id()
b62f651…	stephan	297	*/
b62f651…	stephan	298
b62f651…	stephan	299	/** @var cson_rc
b62f651…	stephan	300
40a14c1…	stephan	301	Deprecated: clients are encouraged to use the CSON_RC_xxx values
40a14c1…	stephan	302	which correspond to cson_rc.xxx, as those are more efficient. Some
40a14c1…	stephan	303	docs and code may still refer to cson_rc, though.
40a14c1…	stephan	304
b62f651…	stephan	305	This object defines the error codes used by cson.
b62f651…	stephan	306
b62f651…	stephan	307	Library routines which return int values almost always return a
b62f651…	stephan	308	value from this structure. None of the members in this struct have
b62f651…	stephan	309	published values except for the OK member, which has the value 0.
b62f651…	stephan	310	All other values might be incidentally defined where clients
b62f651…	stephan	311	can see them, but the numbers might change from release to
b62f651…	stephan	312	release, so clients should only use the symbolic names.
b62f651…	stephan	313
b62f651…	stephan	314	Client code is expected to access these values via the shared
b62f651…	stephan	315	cson_rc object, and use them as demonstrated here:
b62f651…	stephan	316
b62f651…	stephan	317	@code
b62f651…	stephan	318	int rc = cson_some_func(...);
b62f651…	stephan	319	if( 0 == rc ) {...success...}
b62f651…	stephan	320	else if( cson_rc.ArgError == rc ) { ... some argument was wrong ... }
b62f651…	stephan	321	else if( cson_rc.AllocError == rc ) { ... allocation error ... }
b62f651…	stephan	322	...
b62f651…	stephan	323	@endcode
40a14c1…	stephan	324
40a14c1…	stephan	325	Or with the preferred/newer method:
40a14c1…	stephan	326
40a14c1…	stephan	327	@code
40a14c1…	stephan	328	int rc = cson_some_func(...);
40a14c1…	stephan	329	switch(rc){
40a14c1…	stephan	330	case 0: ...success...;
40a14c1…	stephan	331	case CSON_RC_ArgError: ... some argument was wrong ...
40a14c1…	stephan	332	case CSON_RC_AllocError: ... allocation error ...
40a14c1…	stephan	333	...
40a14c1…	stephan	334	}
40a14c1…	stephan	335	@endcode
b62f651…	stephan	336
b62f651…	stephan	337	The entries named Parse_XXX are generally only returned by
b62f651…	stephan	338	cson_parse() and friends.
40a14c1…	stephan	339
40a14c1…	stephan	340	@deprecated
b62f651…	stephan	341	*/
40a14c1…	stephan	342
40a14c1…	stephan	343	/**
40a14c1…	stephan	344	The CSON_RC_xxx values are intended to replace the older
40a14c1…	stephan	345	cson_rc.xxx values.
40a14c1…	stephan	346	*/
40a14c1…	stephan	347	enum cson_rc_values {
40a14c1…	stephan	348	/** The generic success value. Guaranteed to be 0. */
40a14c1…	stephan	349	CSON_RC_OK = 0,
40a14c1…	stephan	350	/** Signifies an error in one or more arguments (e.g. NULL where it is not allowed). */
40a14c1…	stephan	351	CSON_RC_ArgError,
40a14c1…	stephan	352	/** Signifies that some argument is not in a valid range. */
40a14c1…	stephan	353	CSON_RC_RangeError,
40a14c1…	stephan	354	/** Signifies that some argument is not of the correct logical cson type. */
40a14c1…	stephan	355	CSON_RC_TypeError,
40a14c1…	stephan	356	/** Signifies an input/ouput error. */
40a14c1…	stephan	357	CSON_RC_IOError,
40a14c1…	stephan	358	/** Signifies an out-of-memory error. */
40a14c1…	stephan	359	CSON_RC_AllocError,
40a14c1…	stephan	360	/** Signifies that the called code is "NYI" (Not Yet Implemented). */
40a14c1…	stephan	361	CSON_RC_NYIError,
40a14c1…	stephan	362	/** Signifies that an internal error was triggered. If it happens, please report this as a bug! */
40a14c1…	stephan	363	CSON_RC_InternalError,
40a14c1…	stephan	364	/** Signifies that the called operation is not supported in the
40a14c1…	stephan	365	current environment. e.g. missing support from 3rd-party or
40a14c1…	stephan	366	platform-specific code.
40a14c1…	stephan	367	*/
40a14c1…	stephan	368	CSON_RC_UnsupportedError,
40a14c1…	stephan	369	/**
40a14c1…	stephan	370	Signifies that the request resource could not be found.
40a14c1…	stephan	371	*/
40a14c1…	stephan	372	CSON_RC_NotFoundError,
40a14c1…	stephan	373	/**
40a14c1…	stephan	374	Signifies an unknown error, possibly because an underlying
40a14c1…	stephan	375	3rd-party API produced an error and we have no other reasonable
40a14c1…	stephan	376	error code to convert it to.
40a14c1…	stephan	377	*/
40a14c1…	stephan	378	CSON_RC_UnknownError,
40a14c1…	stephan	379	/**
40a14c1…	stephan	380	Signifies that the parser found an unexpected character.
40a14c1…	stephan	381	*/
40a14c1…	stephan	382	CSON_RC_Parse_INVALID_CHAR,
40a14c1…	stephan	383	/**
40a14c1…	stephan	384	Signifies that the parser found an invalid keyword (possibly
40a14c1…	stephan	385	an unquoted string).
40a14c1…	stephan	386	*/
40a14c1…	stephan	387	CSON_RC_Parse_INVALID_KEYWORD,
40a14c1…	stephan	388	/**
40a14c1…	stephan	389	Signifies that the parser found an invalid escape sequence.
40a14c1…	stephan	390	*/
40a14c1…	stephan	391	CSON_RC_Parse_INVALID_ESCAPE_SEQUENCE,
40a14c1…	stephan	392	/**
40a14c1…	stephan	393	Signifies that the parser found an invalid Unicode character
40a14c1…	stephan	394	sequence.
40a14c1…	stephan	395	*/
40a14c1…	stephan	396	CSON_RC_Parse_INVALID_UNICODE_SEQUENCE,
40a14c1…	stephan	397	/**
40a14c1…	stephan	398	Signifies that the parser found an invalid numeric token.
40a14c1…	stephan	399	*/
40a14c1…	stephan	400	CSON_RC_Parse_INVALID_NUMBER,
40a14c1…	stephan	401	/**
40a14c1…	stephan	402	Signifies that the parser reached its maximum defined
40a14c1…	stephan	403	parsing depth before finishing the input.
40a14c1…	stephan	404	*/
40a14c1…	stephan	405	CSON_RC_Parse_NESTING_DEPTH_REACHED,
40a14c1…	stephan	406	/**
40a14c1…	stephan	407	Signifies that the parser found an unclosed object or array.
40a14c1…	stephan	408	*/
40a14c1…	stephan	409	CSON_RC_Parse_UNBALANCED_COLLECTION,
40a14c1…	stephan	410	/**
40a14c1…	stephan	411	Signifies that the parser found an key in an unexpected place.
40a14c1…	stephan	412	*/
40a14c1…	stephan	413	CSON_RC_Parse_EXPECTED_KEY,
40a14c1…	stephan	414	/**
40a14c1…	stephan	415	Signifies that the parser expected to find a colon but
40a14c1…	stephan	416	found none (e.g. between keys and values in an object).
40a14c1…	stephan	417	*/
40a14c1…	stephan	418	CSON_RC_Parse_EXPECTED_COLON
40a14c1…	stephan	419	};
b62f651…	stephan	420
b62f651…	stephan	421	/** @struct cson_rc_
b62f651…	stephan	422	See \ref cson_rc for details.
b62f651…	stephan	423	*/
b62f651…	stephan	424	static const struct cson_rc_
b62f651…	stephan	425	{
b62f651…	stephan	426	/** The generic success value. Guaranteed to be 0. */
b62f651…	stephan	427	const int OK;
b62f651…	stephan	428	/** Signifies an error in one or more arguments (e.g. NULL where it is not allowed). */
b62f651…	stephan	429	const int ArgError;
b62f651…	stephan	430	/** Signifies that some argument is not in a valid range. */
b62f651…	stephan	431	const int RangeError;
b62f651…	stephan	432	/** Signifies that some argument is not of the correct logical cson type. */
b62f651…	stephan	433	const int TypeError;
b62f651…	stephan	434	/** Signifies an input/ouput error. */
b62f651…	stephan	435	const int IOError;
b62f651…	stephan	436	/** Signifies an out-of-memory error. */
b62f651…	stephan	437	const int AllocError;
b62f651…	stephan	438	/** Signifies that the called code is "NYI" (Not Yet Implemented). */
b62f651…	stephan	439	const int NYIError;
b62f651…	stephan	440	/** Signifies that an internal error was triggered. If it happens, please report this as a bug! */
b62f651…	stephan	441	const int InternalError;
b62f651…	stephan	442	/** Signifies that the called operation is not supported in the
b62f651…	stephan	443	current environment. e.g. missing support from 3rd-party or
b62f651…	stephan	444	platform-specific code.
b62f651…	stephan	445	*/
b62f651…	stephan	446	const int UnsupportedError;
b62f651…	stephan	447	/**
b62f651…	stephan	448	Signifies that the request resource could not be found.
b62f651…	stephan	449	*/
b62f651…	stephan	450	const int NotFoundError;
b62f651…	stephan	451	/**
b62f651…	stephan	452	Signifies an unknown error, possibly because an underlying
b62f651…	stephan	453	3rd-party API produced an error and we have no other reasonable
b62f651…	stephan	454	error code to convert it to.
b62f651…	stephan	455	*/
b62f651…	stephan	456	const int UnknownError;
b62f651…	stephan	457	/**
b62f651…	stephan	458	Signifies that the parser found an unexpected character.
b62f651…	stephan	459	*/
b62f651…	stephan	460	const int Parse_INVALID_CHAR;
b62f651…	stephan	461	/**
b62f651…	stephan	462	Signifies that the parser found an invalid keyword (possibly
b62f651…	stephan	463	an unquoted string).
b62f651…	stephan	464	*/
b62f651…	stephan	465	const int Parse_INVALID_KEYWORD;
b62f651…	stephan	466	/**
b62f651…	stephan	467	Signifies that the parser found an invalid escape sequence.
b62f651…	stephan	468	*/
b62f651…	stephan	469	const int Parse_INVALID_ESCAPE_SEQUENCE;
b62f651…	stephan	470	/**
b62f651…	stephan	471	Signifies that the parser found an invalid Unicode character
b62f651…	stephan	472	sequence.
b62f651…	stephan	473	*/
b62f651…	stephan	474	const int Parse_INVALID_UNICODE_SEQUENCE;
b62f651…	stephan	475	/**
b62f651…	stephan	476	Signifies that the parser found an invalid numeric token.
b62f651…	stephan	477	*/
b62f651…	stephan	478	const int Parse_INVALID_NUMBER;
b62f651…	stephan	479	/**
b62f651…	stephan	480	Signifies that the parser reached its maximum defined
b62f651…	stephan	481	parsing depth before finishing the input.
b62f651…	stephan	482	*/
b62f651…	stephan	483	const int Parse_NESTING_DEPTH_REACHED;
b62f651…	stephan	484	/**
b62f651…	stephan	485	Signifies that the parser found an unclosed object or array.
b62f651…	stephan	486	*/
b62f651…	stephan	487	const int Parse_UNBALANCED_COLLECTION;
b62f651…	stephan	488	/**
b62f651…	stephan	489	Signifies that the parser found an key in an unexpected place.
b62f651…	stephan	490	*/
b62f651…	stephan	491	const int Parse_EXPECTED_KEY;
b62f651…	stephan	492	/**
b62f651…	stephan	493	Signifies that the parser expected to find a colon but
b62f651…	stephan	494	found none (e.g. between keys and values in an object).
b62f651…	stephan	495	*/
b62f651…	stephan	496	const int Parse_EXPECTED_COLON;
b62f651…	stephan	497	} cson_rc = {
40a14c1…	stephan	498	CSON_RC_OK,
40a14c1…	stephan	499	CSON_RC_ArgError,
40a14c1…	stephan	500	CSON_RC_RangeError,
40a14c1…	stephan	501	CSON_RC_TypeError,
40a14c1…	stephan	502	CSON_RC_IOError,
40a14c1…	stephan	503	CSON_RC_AllocError,
40a14c1…	stephan	504	CSON_RC_NYIError,
40a14c1…	stephan	505	CSON_RC_InternalError,
40a14c1…	stephan	506	CSON_RC_UnsupportedError,
40a14c1…	stephan	507	CSON_RC_NotFoundError,
40a14c1…	stephan	508	CSON_RC_UnknownError,
40a14c1…	stephan	509	CSON_RC_Parse_INVALID_CHAR,
40a14c1…	stephan	510	CSON_RC_Parse_INVALID_KEYWORD,
40a14c1…	stephan	511	CSON_RC_Parse_INVALID_ESCAPE_SEQUENCE,
40a14c1…	stephan	512	CSON_RC_Parse_INVALID_UNICODE_SEQUENCE,
40a14c1…	stephan	513	CSON_RC_Parse_INVALID_NUMBER,
40a14c1…	stephan	514	CSON_RC_Parse_NESTING_DEPTH_REACHED,
40a14c1…	stephan	515	CSON_RC_Parse_UNBALANCED_COLLECTION,
40a14c1…	stephan	516	CSON_RC_Parse_EXPECTED_KEY,
40a14c1…	stephan	517	CSON_RC_Parse_EXPECTED_COLON
b62f651…	stephan	518	};
b62f651…	stephan	519
b62f651…	stephan	520	/**
b62f651…	stephan	521	Returns the string form of the cson_rc code corresponding to rc, or
b62f651…	stephan	522	some unspecified, non-NULL string if it is an unknown code.
b62f651…	stephan	523
b62f651…	stephan	524	The returned bytes are static and do not changing during the
b62f651…	stephan	525	lifetime of the application.
b62f651…	stephan	526	*/
b62f651…	stephan	527	char const * cson_rc_string(int rc);
b62f651…	stephan	528
b62f651…	stephan	529	/** @struct cson_parse_opt
b62f651…	stephan	530	Client-configurable options for the cson_parse() family of
b62f651…	stephan	531	functions.
b62f651…	stephan	532	*/
b62f651…	stephan	533	struct cson_parse_opt
b62f651…	stephan	534	{
b62f651…	stephan	535	/**
b62f651…	stephan	536	Maximum object/array depth to traverse.
b62f651…	stephan	537	*/
b62f651…	stephan	538	unsigned short maxDepth;
b62f651…	stephan	539	/**
b62f651…	stephan	540	Whether or not to allow C-style comments. Do not rely on this
b62f651…	stephan	541	option being available. If the underlying parser is replaced,
b62f651…	stephan	542	this option might no longer be supported.
b62f651…	stephan	543	*/
b62f651…	stephan	544	char allowComments;
b62f651…	stephan	545	};
b62f651…	stephan	546	typedef struct cson_parse_opt cson_parse_opt;
b62f651…	stephan	547
b62f651…	stephan	548	/**
b62f651…	stephan	549	Empty-initialized cson_parse_opt object.
b62f651…	stephan	550	*/
b62f651…	stephan	551	#define cson_parse_opt_empty_m { 25/maxDepth/, 0/allowComments/}
b62f651…	stephan	552
b62f651…	stephan	553
b62f651…	stephan	554	/**
b62f651…	stephan	555	A class for holding JSON parser information. It is primarily
b62f651…	stephan	556	intended for finding the position of a parse error.
b62f651…	stephan	557	*/
b62f651…	stephan	558	struct cson_parse_info
b62f651…	stephan	559	{
b62f651…	stephan	560	/**
b62f651…	stephan	561	1-based line number.
b62f651…	stephan	562	*/
b62f651…	stephan	563	unsigned int line;
b62f651…	stephan	564	/**
b62f651…	stephan	565	0-based column number.
b62f651…	stephan	566	*/
b62f651…	stephan	567	unsigned int col;
b62f651…	stephan	568
b62f651…	stephan	569	/**
b62f651…	stephan	570	Length, in bytes.
b62f651…	stephan	571	*/
b62f651…	stephan	572	unsigned int length;
b62f651…	stephan	573
b62f651…	stephan	574	/**
b62f651…	stephan	575	Error code of the parse run (0 for no error).
b62f651…	stephan	576	*/
b62f651…	stephan	577	int errorCode;
b62f651…	stephan	578
b62f651…	stephan	579	/**
b62f651…	stephan	580	The total number of object keys successfully processed by the
b62f651…	stephan	581	parser.
b62f651…	stephan	582	*/
b62f651…	stephan	583	unsigned int totalKeyCount;
b62f651…	stephan	584
b62f651…	stephan	585	/**
b62f651…	stephan	586	The total number of object/array values successfully processed
b62f651…	stephan	587	by the parser, including the root node.
b62f651…	stephan	588	*/
b62f651…	stephan	589	unsigned int totalValueCount;
b62f651…	stephan	590	};
b62f651…	stephan	591	typedef struct cson_parse_info cson_parse_info;
b62f651…	stephan	592
b62f651…	stephan	593	/**
b62f651…	stephan	594	Empty-initialized cson_parse_info object.
b62f651…	stephan	595	*/
b62f651…	stephan	596	#define cson_parse_info_empty_m {1/line/,\
b62f651…	stephan	597	0/col/, \
b62f651…	stephan	598	0/length/, \
b62f651…	stephan	599	0/errorCode/, \
b62f651…	stephan	600	0/totalKeyCount/, \
b62f651…	stephan	601	0/totalValueCount/ \
b62f651…	stephan	602	}
b62f651…	stephan	603	/**
b62f651…	stephan	604	Empty-initialized cson_parse_info object.
b62f651…	stephan	605	*/
b62f651…	stephan	606	extern const cson_parse_info cson_parse_info_empty;
b62f651…	stephan	607
b62f651…	stephan	608	/**
b62f651…	stephan	609	Empty-initialized cson_parse_opt object.
b62f651…	stephan	610	*/
b62f651…	stephan	611	extern const cson_parse_opt cson_parse_opt_empty;
b62f651…	stephan	612
b62f651…	stephan	613	/**
b62f651…	stephan	614	Client-configurable options for the cson_output() family of
b62f651…	stephan	615	functions.
b62f651…	stephan	616	*/
b62f651…	stephan	617	struct cson_output_opt
b62f651…	stephan	618	{
b62f651…	stephan	619	/**
b62f651…	stephan	620	Specifies how to indent (or not) output. The values
b62f651…	stephan	621	are:
b62f651…	stephan	622
b62f651…	stephan	623	(0) == no extra indentation.
b62f651…	stephan	624
b62f651…	stephan	625	(1) == 1 TAB character for each level.
b62f651…	stephan	626
b62f651…	stephan	627	(>1) == that number of SPACES for each level.
b62f651…	stephan	628	*/
b62f651…	stephan	629	unsigned char indentation;
b62f651…	stephan	630
b62f651…	stephan	631	/**
b62f651…	stephan	632	Maximum object/array depth to traverse. Traversing deeply can
b62f651…	stephan	633	be indicative of cycles in the object/array tree, and this
b62f651…	stephan	634	value is used to figure out when to abort the traversal.
b62f651…	stephan	635	*/
b62f651…	stephan	636	unsigned short maxDepth;
b62f651…	stephan	637
b62f651…	stephan	638	/**
b62f651…	stephan	639	If true, a newline will be added to generated output,
b62f651…	stephan	640	else not.
b62f651…	stephan	641	*/
b62f651…	stephan	642	char addNewline;
b62f651…	stephan	643
b62f651…	stephan	644	/**
b62f651…	stephan	645	If true, a space will be added after the colon operator
b62f651…	stephan	646	in objects' key/value pairs.
b62f651…	stephan	647	*/
b62f651…	stephan	648	char addSpaceAfterColon;
b62f651…	stephan	649
b62f651…	stephan	650	/**
b62f651…	stephan	651	If set to 1 then objects/arrays containing only a single value
b62f651…	stephan	652	will not indent an extra level for that value (but will indent
b62f651…	stephan	653	on subsequent levels if that value contains multiple values).
b62f651…	stephan	654	*/
b62f651…	stephan	655	char indentSingleMemberValues;
b62f651…	stephan	656
b62f651…	stephan	657	/**
b62f651…	stephan	658	The JSON format allows, but does not require, JSON generators
b62f651…	stephan	659	to backslash-escape forward slashes. This option enables/disables
b62f651…	stephan	660	that feature. According to JSON's inventor, Douglas Crockford:
b62f651…	stephan	661
b62f651…	stephan	662	<quote>
b62f651…	stephan	663	It is allowed, not required. It is allowed so that JSON can be
b62f651…	stephan	664	safely embedded in HTML, which can freak out when seeing
b62f651…	stephan	665	strings containing "</". JSON tolerates "<\/" for this reason.
b62f651…	stephan	666	</quote>
b62f651…	stephan	667
b62f651…	stephan	668	(from an email on 2011-04-08)
b62f651…	stephan	669
b62f651…	stephan	670	The default value is 0 (because it's just damned ugly).
b62f651…	stephan	671	*/
b62f651…	stephan	672	char escapeForwardSlashes;
b62f651…	stephan	673	};
b62f651…	stephan	674	typedef struct cson_output_opt cson_output_opt;
b62f651…	stephan	675
b62f651…	stephan	676	/**
b62f651…	stephan	677	Empty-initialized cson_output_opt object.
b62f651…	stephan	678	*/
b62f651…	stephan	679	#define cson_output_opt_empty_m { 0/indentation/,\
b62f651…	stephan	680	25/maxDepth/, \
b62f651…	stephan	681	0/addNewline/, \
b62f651…	stephan	682	0/addSpaceAfterColon/, \
b62f651…	stephan	683	0/indentSingleMemberValues/, \
b62f651…	stephan	684	0/escapeForwardSlashes/ \
b62f651…	stephan	685	}
b62f651…	stephan	686
b62f651…	stephan	687	/**
b62f651…	stephan	688	Empty-initialized cson_output_opt object.
b62f651…	stephan	689	*/
b62f651…	stephan	690	extern const cson_output_opt cson_output_opt_empty;
b62f651…	stephan	691
b62f651…	stephan	692	/**
b62f651…	stephan	693	Typedef for functions which act as an input source for
b62f651…	stephan	694	the cson JSON parser.
b62f651…	stephan	695
b62f651…	stephan	696	The arguments are:
b62f651…	stephan	697
b62f651…	stephan	698	- state: implementation-specific state needed by the function.
b62f651…	stephan	699
b62f651…	stephan	700	- n: when called, *n will be the number of bytes the function
b62f651…	stephan	701	should read and copy to dest. The function MUST NOT copy more than
b62f651…	stephan	702	n bytes to dest. Before returning, n must be set to the number of
b62f651…	stephan	703	bytes actually copied to dest. If that number is smaller than the
b62f651…	stephan	704	original *n value, the input is assumed to be completed (thus this
b62f651…	stephan	705	is not useful with non-blocking readers).
b62f651…	stephan	706
b62f651…	stephan	707	- dest: the destination memory to copy the data do.
b62f651…	stephan	708
b62f651…	stephan	709	Must return 0 on success, non-0 on error (preferably a value from
b62f651…	stephan	710	cson_rc).
b62f651…	stephan	711
b62f651…	stephan	712	The parser allows this routine to return a partial character from a
b62f651…	stephan	713	UTF multi-byte character. The input routine does not need to
b62f651…	stephan	714	concern itself with character boundaries.
b62f651…	stephan	715	*/
b62f651…	stephan	716	typedef int (cson_data_source_f)( void state, void * dest, unsigned int * n );
b62f651…	stephan	717
b62f651…	stephan	718	/**
b62f651…	stephan	719	Typedef for functions which act as an output destination for
b62f651…	stephan	720	generated JSON.
b62f651…	stephan	721
b62f651…	stephan	722	The arguments are:
b62f651…	stephan	723
b62f651…	stephan	724	- state: implementation-specific state needed by the function.
b62f651…	stephan	725
b62f651…	stephan	726	- n: the length, in bytes, of src.
b62f651…	stephan	727
b62f651…	stephan	728	- src: the source bytes which the output function should consume.
b62f651…	stephan	729	The src pointer will be invalidated shortly after this function
b62f651…	stephan	730	returns, so the implementation must copy or ignore the data, but not
b62f651…	stephan	731	hold a copy of the src pointer.
b62f651…	stephan	732
b62f651…	stephan	733	Must return 0 on success, non-0 on error (preferably a value from
b62f651…	stephan	734	cson_rc).
b62f651…	stephan	735
b62f651…	stephan	736	These functions are called relatively often during the JSON-output
b62f651…	stephan	737	process, and should try to be fast.
b62f651…	stephan	738	*/
b62f651…	stephan	739	typedef int (cson_data_dest_f)( void state, void const * src, unsigned int n );
b62f651…	stephan	740
b62f651…	stephan	741	/**
b62f651…	stephan	742	Reads JSON-formatted string data (in ASCII, UTF8, or UTF16), using the
b62f651…	stephan	743	src function to fetch all input. This function fetches each input character
b62f651…	stephan	744	from the source function, which is calls like src(srcState, buffer, bufferSize),
b62f651…	stephan	745	and processes them. If anything is not JSON-kosher then this function
b62f651…	stephan	746	fails and returns one of the non-0 cson_rc codes.
b62f651…	stephan	747
b62f651…	stephan	748	This function is only intended to read root nodes of a JSON tree, either
b62f651…	stephan	749	a single object or a single array, containing any number of child elements.
b62f651…	stephan	750
b62f651…	stephan	751	On success, *tgt is assigned the value of the root node of the
b62f651…	stephan	752	JSON input, and the caller takes over ownership of that memory.
b62f651…	stephan	753	On error, *tgt is not modified and the caller need not do any
b62f651…	stephan	754	special cleanup, except possibly for the input source.
b62f651…	stephan	755
b62f651…	stephan	756
b62f651…	stephan	757	The opt argument may point to an initialized cson_parse_opt object
b62f651…	stephan	758	which contains any settings the caller wants. If it is NULL then
b62f651…	stephan	759	default settings (the values defined in cson_parse_opt_empty) are
b62f651…	stephan	760	used.
b62f651…	stephan	761
b62f651…	stephan	762	The info argument may be NULL. If it is not NULL then the parser
b62f651…	stephan	763	populates it with information which is useful in error
b62f651…	stephan	764	reporting. Namely, it contains the line/column of parse errors.
b62f651…	stephan	765
b62f651…	stephan	766	The srcState argument is ignored by this function but is passed on to src,
b62f651…	stephan	767	so any output-destination-specific state can be stored there and accessed
b62f651…	stephan	768	via the src callback.
b62f651…	stephan	769
b62f651…	stephan	770	Non-parse error conditions include:
b62f651…	stephan	771
40a14c1…	stephan	772	- (!tgt) or !src: CSON_RC_ArgError
40a14c1…	stephan	773	- CSON_RC_AllocError can happen at any time during the input phase
b62f651…	stephan	774
b62f651…	stephan	775	Here's a complete example of using a custom input source:
b62f651…	stephan	776
b62f651…	stephan	777	@code
b62f651…	stephan	778	// Internal type to hold state for a JSON input string.
b62f651…	stephan	779	typedef struct
b62f651…	stephan	780	{
b62f651…	stephan	781	char const * str; // start of input string
b62f651…	stephan	782	char const * pos; // current internal cursor position
b62f651…	stephan	783	char const * end; // logical EOF (one-past-the-end)
b62f651…	stephan	784	} StringSource;
b62f651…	stephan	785
b62f651…	stephan	786	// cson_data_source_f() impl which uses StringSource.
b62f651…	stephan	787	static int cson_data_source_StringSource( void * state, void * dest,
b62f651…	stephan	788	unsigned int * n )
b62f651…	stephan	789	{
b62f651…	stephan	790	StringSource * ss = (StringSource*) state;
b62f651…	stephan	791	unsigned int i;
b62f651…	stephan	792	unsigned char * tgt = (unsigned char *)dest;
40a14c1…	stephan	793	if( ! ss \|\| ! n \|\| !dest ) return CSON_RC_ArgError;
40a14c1…	stephan	794	else if( !*n ) return CSON_RC_RangeError;
b62f651…	stephan	795	for( i = 0;
b62f651…	stephan	796	(i < *n) && (ss->pos < ss->end);
b62f651…	stephan	797	++i, ++ss->pos, ++tgt )
b62f651…	stephan	798	{
b62f651…	stephan	799	tgt = ss->pos;
b62f651…	stephan	800	}
b62f651…	stephan	801	*n = i;
b62f651…	stephan	802	return 0;
b62f651…	stephan	803	}
b62f651…	stephan	804
b62f651…	stephan	805	...
b62f651…	stephan	806	// Now use StringSource together with cson_parse()
b62f651…	stephan	807	StringSource ss;
b62f651…	stephan	808	cson_value * root = NULL;
b62f651…	stephan	809	char const * json = "{\"k1\":123}";
b62f651…	stephan	810	ss.str = ss.pos = json;
b62f651…	stephan	811	ss.end = json + strlen(json);
b62f651…	stephan	812	int rc = cson_parse( &root, cson_data_source_StringSource, &ss, NULL, NULL );
b62f651…	stephan	813	@endcode
b62f651…	stephan	814
b62f651…	stephan	815	It is recommended that clients wrap such utility code into
b62f651…	stephan	816	type-safe wrapper functions which also initialize the internal
b62f651…	stephan	817	state object and check the user-provided parameters for legality
b62f651…	stephan	818	before passing them on to cson_parse(). For examples of this, see
b62f651…	stephan	819	cson_parse_FILE() or cson_parse_string().
b62f651…	stephan	820
b62f651…	stephan	821	TODOs:
b62f651…	stephan	822
b62f651…	stephan	823	- Buffer the input in larger chunks. We currently read
b62f651…	stephan	824	byte-by-byte, but i'm too tired to write/test the looping code for
b62f651…	stephan	825	the buffering.
b62f651…	stephan	826
b62f651…	stephan	827	@see cson_parse_FILE()
b62f651…	stephan	828	@see cson_parse_string()
b62f651…	stephan	829	*/
b62f651…	stephan	830	int cson_parse( cson_value ** tgt, cson_data_source_f src, void * srcState,
b62f651…	stephan	831	cson_parse_opt const * opt, cson_parse_info * info );
b62f651…	stephan	832	/**
b62f651…	stephan	833	A cson_data_source_f() implementation which requires the state argument
b62f651…	stephan	834	to be a readable (FILE*) handle.
b62f651…	stephan	835	*/
b62f651…	stephan	836	int cson_data_source_FILE( void * state, void * dest, unsigned int * n );
b62f651…	stephan	837
b62f651…	stephan	838	/**
b62f651…	stephan	839	Equivalent to cson_parse( tgt, cson_data_source_FILE, src, opt ).
b62f651…	stephan	840
b62f651…	stephan	841	@see cson_parse_filename()
b62f651…	stephan	842	*/
b62f651…	stephan	843	int cson_parse_FILE( cson_value ** tgt, FILE * src,
b62f651…	stephan	844	cson_parse_opt const * opt, cson_parse_info * info );
b62f651…	stephan	845
b62f651…	stephan	846	/**
b62f651…	stephan	847	Convenience wrapper around cson_parse_FILE() which opens the given filename.
b62f651…	stephan	848
40a14c1…	stephan	849	Returns CSON_RC_IOError if the file cannot be opened.
b62f651…	stephan	850
b62f651…	stephan	851	@see cson_parse_FILE()
b62f651…	stephan	852	*/
b62f651…	stephan	853	int cson_parse_filename( cson_value ** tgt, char const * src,
b62f651…	stephan	854	cson_parse_opt const * opt, cson_parse_info * info );
b62f651…	stephan	855
b62f651…	stephan	856	/**
b62f651…	stephan	857	Uses an internal helper class to pass src through cson_parse().
b62f651…	stephan	858	See that function for the return value and argument semantics.
b62f651…	stephan	859
b62f651…	stephan	860	src must be a string containing JSON code, at least len bytes long,
b62f651…	stephan	861	and the parser will attempt to parse exactly len bytes from src.
b62f651…	stephan	862
b62f651…	stephan	863	If len is less than 2 (the minimum length of a legal top-node JSON
40a14c1…	stephan	864	object) then CSON_RC_RangeError is returned.
b62f651…	stephan	865	*/
b62f651…	stephan	866	int cson_parse_string( cson_value ** tgt, char const * src, unsigned int len,
b62f651…	stephan	867	cson_parse_opt const * opt, cson_parse_info * info );
b62f651…	stephan	868
b62f651…	stephan	869
b62f651…	stephan	870
b62f651…	stephan	871	/**
b62f651…	stephan	872	Outputs the given value as a JSON-formatted string, sending all
b62f651…	stephan	873	output to the given callback function. It is intended for top-level
b62f651…	stephan	874	objects or arrays, but can be used with any cson_value.
b62f651…	stephan	875
b62f651…	stephan	876	If opt is NULL then default options (the values defined in
b62f651…	stephan	877	cson_output_opt_empty) are used.
b62f651…	stephan	878
b62f651…	stephan	879	If opt->maxDepth is exceeded while traversing the value tree,
40a14c1…	stephan	880	CSON_RC_RangeError is returned.
b62f651…	stephan	881
b62f651…	stephan	882	The destState parameter is ignored by this function and is passed
b62f651…	stephan	883	on to the dest function.
b62f651…	stephan	884
b62f651…	stephan	885	Returns 0 on success. On error, any amount of output might have been
b62f651…	stephan	886	generated before the error was triggered.
b62f651…	stephan	887
b62f651…	stephan	888	Example:
b62f651…	stephan	889
b62f651…	stephan	890	@code
b62f651…	stephan	891	int rc = cson_output( myValue, cson_data_dest_FILE, stdout, NULL );
b62f651…	stephan	892	// basically equivalent to: cson_output_FILE( myValue, stdout, NULL );
b62f651…	stephan	893	// but note that cson_output_FILE() actually uses different defaults
b62f651…	stephan	894	// for the output options.
b62f651…	stephan	895	@endcode
b62f651…	stephan	896	*/
b62f651…	stephan	897	int cson_output( cson_value const * src, cson_data_dest_f dest, void * destState, cson_output_opt const * opt );
b62f651…	stephan	898
b62f651…	stephan	899
b62f651…	stephan	900	/**
b62f651…	stephan	901	A cson_data_dest_f() implementation which requires the state argument
b62f651…	stephan	902	to be a writable (FILE*) handle.
b62f651…	stephan	903	*/
b62f651…	stephan	904	int cson_data_dest_FILE( void * state, void const * src, unsigned int n );
b62f651…	stephan	905
b62f651…	stephan	906	/**
b62f651…	stephan	907	Almost equivalent to cson_output( src, cson_data_dest_FILE, dest, opt ),
b62f651…	stephan	908	with one minor difference: if opt is NULL then the default options
b62f651…	stephan	909	always include the addNewline option, since that is normally desired
b62f651…	stephan	910	for FILE output.
b62f651…	stephan	911
b62f651…	stephan	912	@see cson_output_filename()
b62f651…	stephan	913	*/
b62f651…	stephan	914	int cson_output_FILE( cson_value const * src, FILE * dest, cson_output_opt const * opt );
b62f651…	stephan	915	/**
b62f651…	stephan	916	Convenience wrapper around cson_output_FILE() which writes to the given filename, destroying
40a14c1…	stephan	917	any existing contents. Returns CSON_RC_IOError if the file cannot be opened.
b62f651…	stephan	918
b62f651…	stephan	919	@see cson_output_FILE()
b62f651…	stephan	920	*/
b62f651…	stephan	921	int cson_output_filename( cson_value const * src, char const * dest, cson_output_opt const * fmt );
b62f651…	stephan	922
b62f651…	stephan	923	/**
b62f651…	stephan	924	Returns the virtual type of v, or CSON_TYPE_UNDEF if !v.
b62f651…	stephan	925	*/
b62f651…	stephan	926	cson_type_id cson_value_type_id( cson_value const * v );
b62f651…	stephan	927
b62f651…	stephan	928
b62f651…	stephan	929	/** Returns true if v is null, v->api is NULL, or v holds the special undefined value. */
b62f651…	stephan	930	char cson_value_is_undef( cson_value const * v );
b62f651…	stephan	931	/** Returns true if v contains a null value. */
b62f651…	stephan	932	char cson_value_is_null( cson_value const * v );
b62f651…	stephan	933	/** Returns true if v contains a bool value. */
b62f651…	stephan	934	char cson_value_is_bool( cson_value const * v );
b62f651…	stephan	935	/** Returns true if v contains an integer value. */
b62f651…	stephan	936	char cson_value_is_integer( cson_value const * v );
b62f651…	stephan	937	/** Returns true if v contains a double value. */
b62f651…	stephan	938	char cson_value_is_double( cson_value const * v );
b62f651…	stephan	939	/** Returns true if v contains a number (double, integer) value. */
b62f651…	stephan	940	char cson_value_is_number( cson_value const * v );
b62f651…	stephan	941	/** Returns true if v contains a string value. */
b62f651…	stephan	942	char cson_value_is_string( cson_value const * v );
b62f651…	stephan	943	/** Returns true if v contains an array value. */
b62f651…	stephan	944	char cson_value_is_array( cson_value const * v );
b62f651…	stephan	945	/** Returns true if v contains an object value. */
b62f651…	stephan	946	char cson_value_is_object( cson_value const * v );
b62f651…	stephan	947
b62f651…	stephan	948	/** @struct cson_object
b62f651…	stephan	949
b62f651…	stephan	950	cson_object is an opaque handle to an Object value.
b62f651…	stephan	951
b62f651…	stephan	952	They are used like:
b62f651…	stephan	953
b62f651…	stephan	954	@code
b62f651…	stephan	955	cson_object * obj = cson_value_get_object(myValue);
b62f651…	stephan	956	...
b62f651…	stephan	957	@endcode
b62f651…	stephan	958
b62f651…	stephan	959	They can be created like:
b62f651…	stephan	960
b62f651…	stephan	961	@code
b62f651…	stephan	962	cson_value * objV = cson_value_new_object();
b62f651…	stephan	963	cson_object * obj = cson_value_get_object(objV);
b62f651…	stephan	964	// obj is owned by objV and objV must eventually be freed
b62f651…	stephan	965	// using cson_value_free() or added to a container
b62f651…	stephan	966	// object/array (which transfers ownership to that container).
b62f651…	stephan	967	@endcode
b62f651…	stephan	968
b62f651…	stephan	969	@see cson_value_new_object()
b62f651…	stephan	970	@see cson_value_get_object()
b62f651…	stephan	971	@see cson_value_free()
b62f651…	stephan	972	*/
b62f651…	stephan	973
b62f651…	stephan	974	typedef struct cson_object cson_object;
b62f651…	stephan	975
b62f651…	stephan	976	/** @struct cson_array
b62f651…	stephan	977
b62f651…	stephan	978	cson_array is an opaque handle to an Array value.
b62f651…	stephan	979
b62f651…	stephan	980	They are used like:
b62f651…	stephan	981
b62f651…	stephan	982	@code
b62f651…	stephan	983	cson_array * obj = cson_value_get_array(myValue);
b62f651…	stephan	984	...
b62f651…	stephan	985	@endcode
b62f651…	stephan	986
b62f651…	stephan	987	They can be created like:
b62f651…	stephan	988
b62f651…	stephan	989	@code
b62f651…	stephan	990	cson_value * arV = cson_value_new_array();
b62f651…	stephan	991	cson_array * ar = cson_value_get_array(arV);
b62f651…	stephan	992	// ar is owned by arV and arV must eventually be freed
b62f651…	stephan	993	// using cson_value_free() or added to a container
b62f651…	stephan	994	// object/array (which transfers ownership to that container).
b62f651…	stephan	995	@endcode
b62f651…	stephan	996
b62f651…	stephan	997	@see cson_value_new_array()
b62f651…	stephan	998	@see cson_value_get_array()
b62f651…	stephan	999	@see cson_value_free()
b62f651…	stephan	1000
b62f651…	stephan	1001	*/
b62f651…	stephan	1002	typedef struct cson_array cson_array;
b62f651…	stephan	1003
b62f651…	stephan	1004	/** @struct cson_string
b62f651…	stephan	1005
b62f651…	stephan	1006	cson-internal string type, opaque to client code. Strings in cson
b62f651…	stephan	1007	are immutable and allocated only by library internals, never
b62f651…	stephan	1008	directly by client code.
b62f651…	stephan	1009
b62f651…	stephan	1010	The actual string bytes are to be allocated together in the same
b62f651…	stephan	1011	memory chunk as the cson_string object, which saves us 1 malloc()
b62f651…	stephan	1012	and 1 pointer member in this type (because we no longer have a
b62f651…	stephan	1013	direct pointer to the memory).
b62f651…	stephan	1014
b62f651…	stephan	1015	Potential TODOs:
b62f651…	stephan	1016
b62f651…	stephan	1017	@see cson_string_cstr()
b62f651…	stephan	1018	*/
b62f651…	stephan	1019	typedef struct cson_string cson_string;
b62f651…	stephan	1020
b62f651…	stephan	1021	/**
b62f651…	stephan	1022	Converts the given value to a boolean, using JavaScript semantics depending
b62f651…	stephan	1023	on the concrete type of val:
b62f651…	stephan	1024
b62f651…	stephan	1025	undef or null: false
b62f651…	stephan	1026
b62f651…	stephan	1027	boolean: same
b62f651…	stephan	1028
b62f651…	stephan	1029	integer, double: 0 or 0.0 == false, else true
b62f651…	stephan	1030
b62f651…	stephan	1031	object, array: true
b62f651…	stephan	1032
b62f651…	stephan	1033	string: length-0 string is false, else true.
b62f651…	stephan	1034
b62f651…	stephan	1035	Returns 0 on success and assigns *v (if v is not NULL) to either 0 or 1.
b62f651…	stephan	1036	On error (val is NULL) then v is not modified.
b62f651…	stephan	1037	*/
b62f651…	stephan	1038	int cson_value_fetch_bool( cson_value const * val, char * v );
b62f651…	stephan	1039
b62f651…	stephan	1040	/**
b62f651…	stephan	1041	Similar to cson_value_fetch_bool(), but fetches an integer value.
b62f651…	stephan	1042
b62f651…	stephan	1043	The conversion, if any, depends on the concrete type of val:
b62f651…	stephan	1044
b62f651…	stephan	1045	NULL, null, undefined: *v is set to 0 and 0 is returned.
b62f651…	stephan	1046
b62f651…	stephan	1047	string, object, array: *v is set to 0 and
40a14c1…	stephan	1048	CSON_RC_TypeError is returned. The error may normally be safely
b62f651…	stephan	1049	ignored, but it is provided for those wanted to know whether a direct
b62f651…	stephan	1050	conversion was possible.
b62f651…	stephan	1051
b62f651…	stephan	1052	integer: *v is set to the int value and 0 is returned.
b62f651…	stephan	1053
b62f651…	stephan	1054	double: *v is set to the value truncated to int and 0 is returned.
b62f651…	stephan	1055	*/
b62f651…	stephan	1056	int cson_value_fetch_integer( cson_value const * val, cson_int_t * v );
b62f651…	stephan	1057
b62f651…	stephan	1058	/**
b62f651…	stephan	1059	The same conversions and return values as
b62f651…	stephan	1060	cson_value_fetch_integer(), except that the roles of int/double are
b62f651…	stephan	1061	swapped.
b62f651…	stephan	1062	*/
b62f651…	stephan	1063	int cson_value_fetch_double( cson_value const * val, cson_double_t * v );
b62f651…	stephan	1064
b62f651…	stephan	1065	/**
b62f651…	stephan	1066	If cson_value_is_string(val) then this function assigns *str to the
b62f651…	stephan	1067	contents of the string. str may be NULL, in which case this function
b62f651…	stephan	1068	functions like cson_value_is_string() but returns 0 on success.
b62f651…	stephan	1069
b62f651…	stephan	1070	Returns 0 if val is-a string, else non-0, in which case *str is not
b62f651…	stephan	1071	modified.
b62f651…	stephan	1072
b62f651…	stephan	1073	The bytes are owned by the given value and may be invalidated in any of
b62f651…	stephan	1074	the following ways:
b62f651…	stephan	1075
b62f651…	stephan	1076	- The value is cleaned up or freed.
b62f651…	stephan	1077
b62f651…	stephan	1078	- An array or object containing the value peforms a re-allocation
b62f651…	stephan	1079	(it shrinks or grows).
b62f651…	stephan	1080
b62f651…	stephan	1081	And thus the bytes should be consumed before any further operations
b62f651…	stephan	1082	on val or any container which holds it.
b62f651…	stephan	1083
b62f651…	stephan	1084	Note that this routine does not convert non-String values to their
b62f651…	stephan	1085	string representations. (Adding that ability would add more
b62f651…	stephan	1086	overhead to every cson_value instance.)
b62f651…	stephan	1087	*/
b62f651…	stephan	1088	int cson_value_fetch_string( cson_value const * val, cson_string ** str );
b62f651…	stephan	1089
b62f651…	stephan	1090	/**
b62f651…	stephan	1091	If cson_value_is_object(val) then this function assigns *obj to the underlying
b62f651…	stephan	1092	object value and returns 0, otherwise non-0 is returned and *obj is not modified.
b62f651…	stephan	1093
b62f651…	stephan	1094	obj may be NULL, in which case this function works like cson_value_is_object()
b62f651…	stephan	1095	but with inverse return value semantics (0==success) (and it's a few
b62f651…	stephan	1096	CPU cycles slower).
b62f651…	stephan	1097
b62f651…	stephan	1098	The *obj pointer is owned by val, and will be invalidated when val
b62f651…	stephan	1099	is cleaned up.
b62f651…	stephan	1100
b62f651…	stephan	1101	Achtung: for best results, ALWAYS pass a pointer to NULL as the
b62f651…	stephan	1102	second argument, e.g.:
b62f651…	stephan	1103
b62f651…	stephan	1104	@code
b62f651…	stephan	1105	cson_object * obj = NULL;
b62f651…	stephan	1106	int rc = cson_value_fetch_object( val, &obj );
b62f651…	stephan	1107
b62f651…	stephan	1108	// Or, more simply:
b62f651…	stephan	1109	obj = cson_value_get_object( val );
b62f651…	stephan	1110	@endcode
b62f651…	stephan	1111
b62f651…	stephan	1112	@see cson_value_get_object()
b62f651…	stephan	1113	*/
b62f651…	stephan	1114	int cson_value_fetch_object( cson_value const * val, cson_object ** obj );
b62f651…	stephan	1115
b62f651…	stephan	1116	/**
b62f651…	stephan	1117	Identical to cson_value_fetch_object(), but works on array values.
b62f651…	stephan	1118
b62f651…	stephan	1119	@see cson_value_get_array()
b62f651…	stephan	1120	*/
b62f651…	stephan	1121	int cson_value_fetch_array( cson_value const * val, cson_array ** tgt );
b62f651…	stephan	1122
b62f651…	stephan	1123	/**
b62f651…	stephan	1124	Simplified form of cson_value_fetch_bool(). Returns 0 if val
b62f651…	stephan	1125	is NULL.
b62f651…	stephan	1126	*/
b62f651…	stephan	1127	char cson_value_get_bool( cson_value const * val );
b62f651…	stephan	1128
b62f651…	stephan	1129	/**
b62f651…	stephan	1130	Simplified form of cson_value_fetch_integer(). Returns 0 if val
b62f651…	stephan	1131	is NULL.
b62f651…	stephan	1132	*/
b62f651…	stephan	1133	cson_int_t cson_value_get_integer( cson_value const * val );
b62f651…	stephan	1134
b62f651…	stephan	1135	/**
b62f651…	stephan	1136	Simplified form of cson_value_fetch_double(). Returns 0.0 if val
b62f651…	stephan	1137	is NULL.
b62f651…	stephan	1138	*/
b62f651…	stephan	1139	cson_double_t cson_value_get_double( cson_value const * val );
b62f651…	stephan	1140
b62f651…	stephan	1141	/**
b62f651…	stephan	1142	Simplified form of cson_value_fetch_string(). Returns NULL if val
b62f651…	stephan	1143	is-not-a string value.
b62f651…	stephan	1144	*/
b62f651…	stephan	1145	cson_string * cson_value_get_string( cson_value const * val );
b62f651…	stephan	1146
b62f651…	stephan	1147	/**
b62f651…	stephan	1148	Returns a pointer to the NULL-terminated string bytes of str.
b62f651…	stephan	1149	The bytes are owned by string and will be invalided when it
b62f651…	stephan	1150	is cleaned up.
b62f651…	stephan	1151
b62f651…	stephan	1152	If str is NULL then NULL is returned. If the string has a length
b62f651…	stephan	1153	of 0 then "" is returned.
b62f651…	stephan	1154
b62f651…	stephan	1155	@see cson_string_length_bytes()
b62f651…	stephan	1156	@see cson_value_get_string()
b62f651…	stephan	1157	*/
b62f651…	stephan	1158	char const * cson_string_cstr( cson_string const * str );
b62f651…	stephan	1159
b62f651…	stephan	1160	/**
b62f651…	stephan	1161	Convenience function which returns the string bytes of
b62f651…	stephan	1162	the given value if it is-a string, otherwise it returns
b62f651…	stephan	1163	NULL. Note that this does no conversion of non-string types
b62f651…	stephan	1164	to strings.
b62f651…	stephan	1165
b62f651…	stephan	1166	Equivalent to cson_string_cstr(cson_value_get_string(val)).
b62f651…	stephan	1167	*/
b62f651…	stephan	1168	char const * cson_value_get_cstr( cson_value const * val );
b62f651…	stephan	1169
b62f651…	stephan	1170	/**
b62f651…	stephan	1171	Equivalent to cson_string_cmp_cstr_n(lhs, cson_string_cstr(rhs), cson_string_length_bytes(rhs)).
b62f651…	stephan	1172	*/
b62f651…	stephan	1173	int cson_string_cmp( cson_string const * lhs, cson_string const * rhs );
b62f651…	stephan	1174
b62f651…	stephan	1175	/**
b62f651…	stephan	1176	Compares lhs to rhs using memcmp()/strcmp() semantics. Generically
b62f651…	stephan	1177	speaking it returns a negative number if lhs is less-than rhs, 0 if
b62f651…	stephan	1178	they are equivalent, or a positive number if lhs is greater-than
b62f651…	stephan	1179	rhs. It has the following rules for equivalence:
b62f651…	stephan	1180
b62f651…	stephan	1181	- The maximum number of bytes compared is the lesser of rhsLen and
b62f651…	stephan	1182	the length of lhs. If the strings do not match, but compare equal
b62f651…	stephan	1183	up to the just-described comparison length, the shorter string is
b62f651…	stephan	1184	considered to be less-than the longer one.
b62f651…	stephan	1185
b62f651…	stephan	1186	- If lhs and rhs are both NULL, or both have a length of 0 then they will
b62f651…	stephan	1187	compare equal.
b62f651…	stephan	1188
b62f651…	stephan	1189	- If lhs is null/length-0 but rhs is not then lhs is considered to be less-than
b62f651…	stephan	1190	rhs.
b62f651…	stephan	1191
b62f651…	stephan	1192	- If rhs is null/length-0 but lhs is not then rhs is considered to be less-than
b62f651…	stephan	1193	rhs.
b62f651…	stephan	1194
b62f651…	stephan	1195	- i have no clue if the results are exactly correct for UTF strings.
b62f651…	stephan	1196
b62f651…	stephan	1197	*/
b62f651…	stephan	1198	int cson_string_cmp_cstr_n( cson_string const * lhs, char const * rhs, unsigned int rhsLen );
b62f651…	stephan	1199
b62f651…	stephan	1200	/**
b62f651…	stephan	1201	Equivalent to cson_string_cmp_cstr_n( lhs, rhs, (rhs&&*rhs)?strlen(rhs):0 ).
b62f651…	stephan	1202	*/
b62f651…	stephan	1203	int cson_string_cmp_cstr( cson_string const * lhs, char const * rhs );
b62f651…	stephan	1204
b62f651…	stephan	1205	/**
b62f651…	stephan	1206	Returns the length, in bytes, of str, or 0 if str is NULL. This is
b62f651…	stephan	1207	an O(1) operation.
b62f651…	stephan	1208
b62f651…	stephan	1209	TODO: add cson_string_length_chars() (is O(N) unless we add another
b62f651…	stephan	1210	member to store the char length).
b62f651…	stephan	1211
b62f651…	stephan	1212	@see cson_string_cstr()
b62f651…	stephan	1213	*/
b62f651…	stephan	1214	unsigned int cson_string_length_bytes( cson_string const * str );
b62f651…	stephan	1215
b62f651…	stephan	1216	/**
b62f651…	stephan	1217	Returns the number of UTF8 characters in str. This value will
b62f651…	stephan	1218	be at most as long as cson_string_length_bytes() for the
b62f651…	stephan	1219	same string, and less if it has multi-byte characters.
b62f651…	stephan	1220
b62f651…	stephan	1221	Returns 0 if str is NULL.
b62f651…	stephan	1222	*/
b62f651…	stephan	1223	unsigned int cson_string_length_utf8( cson_string const * str );
b62f651…	stephan	1224
b62f651…	stephan	1225	/**
b62f651…	stephan	1226	Like cson_value_get_string(), but returns a copy of the underying
b62f651…	stephan	1227	string bytes, which the caller owns and must eventually free
b62f651…	stephan	1228	using free().
b62f651…	stephan	1229	*/
b62f651…	stephan	1230	char * cson_value_get_string_copy( cson_value const * val );
b62f651…	stephan	1231
b62f651…	stephan	1232	/**
b62f651…	stephan	1233	Simplified form of cson_value_fetch_object(). Returns NULL if val
b62f651…	stephan	1234	is-not-a object value.
b62f651…	stephan	1235	*/
b62f651…	stephan	1236	cson_object * cson_value_get_object( cson_value const * val );
b62f651…	stephan	1237
b62f651…	stephan	1238	/**
b62f651…	stephan	1239	Simplified form of cson_value_fetch_array(). Returns NULL if val
b62f651…	stephan	1240	is-not-a array value.
b62f651…	stephan	1241	*/
b62f651…	stephan	1242	cson_array * cson_value_get_array( cson_value const * val );
b62f651…	stephan	1243
b62f651…	stephan	1244	/**
b62f651…	stephan	1245	Const-correct form of cson_value_get_array().
b62f651…	stephan	1246	*/
b62f651…	stephan	1247	cson_array const * cson_value_get_array_c( cson_value const * val );
b62f651…	stephan	1248
b62f651…	stephan	1249	/**
b62f651…	stephan	1250	If ar is-a array and is at least (pos+1) entries long then *v (if v is not NULL)
b62f651…	stephan	1251	is assigned to the value at that position (which may be NULL).
b62f651…	stephan	1252
b62f651…	stephan	1253	Ownership of the *v return value is unchanged by this call. (The
b62f651…	stephan	1254	containing array may share ownership of the value with other
b62f651…	stephan	1255	containers.)
b62f651…	stephan	1256
b62f651…	stephan	1257	If pos is out of range, non-0 is returned and *v is not modified.
b62f651…	stephan	1258
b62f651…	stephan	1259	If v is NULL then this function returns 0 if pos is in bounds, but does not
b62f651…	stephan	1260	otherwise return a value to the caller.
b62f651…	stephan	1261	*/
b62f651…	stephan	1262	int cson_array_value_fetch( cson_array const * ar, unsigned int pos, cson_value ** v );
b62f651…	stephan	1263
b62f651…	stephan	1264	/**
b62f651…	stephan	1265	Simplified form of cson_array_value_fetch() which returns NULL if
b62f651…	stephan	1266	ar is NULL, pos is out of bounds or if ar has no element at that
b62f651…	stephan	1267	position.
b62f651…	stephan	1268	*/
b62f651…	stephan	1269	cson_value * cson_array_get( cson_array const * ar, unsigned int pos );
b62f651…	stephan	1270
b62f651…	stephan	1271	/**
b62f651…	stephan	1272	Ensures that ar has allocated space for at least the given
b62f651…	stephan	1273	number of entries. This never shrinks the array and never
b62f651…	stephan	1274	changes its logical size, but may pre-allocate space in the
b62f651…	stephan	1275	array for storing new (as-yet-unassigned) values.
b62f651…	stephan	1276
b62f651…	stephan	1277	Returns 0 on success, or non-zero on error:
b62f651…	stephan	1278
40a14c1…	stephan	1279	- If ar is NULL: CSON_RC_ArgError
b62f651…	stephan	1280
40a14c1…	stephan	1281	- If allocation fails: CSON_RC_AllocError
b62f651…	stephan	1282	*/
b62f651…	stephan	1283	int cson_array_reserve( cson_array * ar, unsigned int size );
b62f651…	stephan	1284
b62f651…	stephan	1285	/**
b62f651…	stephan	1286	If ar is not NULL, sets *v (if v is not NULL) to the length of the array
40a14c1…	stephan	1287	and returns 0. Returns CSON_RC_ArgError if ar is NULL.
b62f651…	stephan	1288	*/
b62f651…	stephan	1289	int cson_array_length_fetch( cson_array const * ar, unsigned int * v );
b62f651…	stephan	1290
b62f651…	stephan	1291	/**
b62f651…	stephan	1292	Simplified form of cson_array_length_fetch() which returns 0 if ar
b62f651…	stephan	1293	is NULL.
b62f651…	stephan	1294	*/
b62f651…	stephan	1295	unsigned int cson_array_length_get( cson_array const * ar );
b62f651…	stephan	1296
b62f651…	stephan	1297	/**
b62f651…	stephan	1298	Sets the given index of the given array to the given value.
b62f651…	stephan	1299
b62f651…	stephan	1300	If ar already has an item at that index then it is cleaned up and
b62f651…	stephan	1301	freed before inserting the new item.
b62f651…	stephan	1302
b62f651…	stephan	1303	ar is expanded, if needed, to be able to hold at least (ndx+1)
b62f651…	stephan	1304	items, and any new entries created by that expansion are empty
b62f651…	stephan	1305	(NULL values).
b62f651…	stephan	1306
b62f651…	stephan	1307	On success, 0 is returned and ownership of v is transfered to ar.
b62f651…	stephan	1308
b62f651…	stephan	1309	On error ownership of v is NOT modified, and the caller may still
b62f651…	stephan	1310	need to clean it up. For example, the following code will introduce
b62f651…	stephan	1311	a leak if this function fails:
b62f651…	stephan	1312
b62f651…	stephan	1313	@code
b62f651…	stephan	1314	cson_array_append( myArray, cson_value_new_integer(42) );
b62f651…	stephan	1315	@endcode
b62f651…	stephan	1316
b62f651…	stephan	1317	Because the value created by cson_value_new_integer() has no owner
b62f651…	stephan	1318	and is not cleaned up. The "more correct" way to do this is:
b62f651…	stephan	1319
b62f651…	stephan	1320	@code
b62f651…	stephan	1321	cson_value * v = cson_value_new_integer(42);
b62f651…	stephan	1322	int rc = cson_array_append( myArray, v );
b62f651…	stephan	1323	if( 0 != rc ) {
b62f651…	stephan	1324	cson_value_free( v );
b62f651…	stephan	1325	... handle error ...
b62f651…	stephan	1326	}
b62f651…	stephan	1327	@endcode
b62f651…	stephan	1328
b62f651…	stephan	1329	*/
b62f651…	stephan	1330	int cson_array_set( cson_array * ar, unsigned int ndx, cson_value * v );
b62f651…	stephan	1331
b62f651…	stephan	1332	/**
b62f651…	stephan	1333	Appends the given value to the given array, transfering ownership of
b62f651…	stephan	1334	v to ar. On error, ownership of v is not modified. Ownership of ar
b62f651…	stephan	1335	is never changed by this function.
b62f651…	stephan	1336
b62f651…	stephan	1337	This is functionally equivalent to
b62f651…	stephan	1338	cson_array_set(ar,cson_array_length_get(ar),v), but this
b62f651…	stephan	1339	implementation has slightly different array-preallocation policy
b62f651…	stephan	1340	(it grows more eagerly).
b62f651…	stephan	1341
b62f651…	stephan	1342	Returns 0 on success, non-zero on error. Error cases include:
b62f651…	stephan	1343
40a14c1…	stephan	1344	- ar or v are NULL: CSON_RC_ArgError
b62f651…	stephan	1345
40a14c1…	stephan	1346	- Array cannot be expanded to hold enough elements: CSON_RC_AllocError.
b62f651…	stephan	1347
b62f651…	stephan	1348	- Appending would cause a numeric overlow in the array's size:
40a14c1…	stephan	1349	CSON_RC_RangeError. (However, you'll get an AllocError long before
b62f651…	stephan	1350	that happens!)
b62f651…	stephan	1351
b62f651…	stephan	1352	On error ownership of v is NOT modified, and the caller may still
b62f651…	stephan	1353	need to clean it up. See cson_array_set() for the details.
b62f651…	stephan	1354
b62f651…	stephan	1355	*/
b62f651…	stephan	1356	int cson_array_append( cson_array * ar, cson_value * v );
b62f651…	stephan	1357
b62f651…	stephan	1358
b62f651…	stephan	1359	/**
b62f651…	stephan	1360	Creates a new cson_value from the given boolean value.
b62f651…	stephan	1361
b62f651…	stephan	1362	Ownership of the new value is passed to the caller, who must
b62f651…	stephan	1363	eventually either free the value using cson_value_free() or
b62f651…	stephan	1364	inserting it into a container (array or object), which transfers
b62f651…	stephan	1365	ownership to the container. See the cson_value class documentation
b62f651…	stephan	1366	for more details.
b62f651…	stephan	1367
b62f651…	stephan	1368	Semantically speaking this function Returns NULL on allocation
b62f651…	stephan	1369	error, but the implementation never actually allocates for this
b62f651…	stephan	1370	case. Nonetheless, it must be treated as if it were an allocated
b62f651…	stephan	1371	value.
b62f651…	stephan	1372	*/
b62f651…	stephan	1373	cson_value * cson_value_new_bool( char v );
b62f651…	stephan	1374
b62f651…	stephan	1375
b62f651…	stephan	1376	/**
b62f651…	stephan	1377	Alias for cson_value_new_bool(v).
b62f651…	stephan	1378	*/
b62f651…	stephan	1379	cson_value * cson_new_bool(char v);
b62f651…	stephan	1380
b62f651…	stephan	1381	/**
b62f651…	stephan	1382	Returns the special JSON "null" value. When outputing JSON,
b62f651…	stephan	1383	its string representation is "null" (without the quotes).
b62f651…	stephan	1384
b62f651…	stephan	1385	See cson_value_new_bool() for notes regarding the returned
b62f651…	stephan	1386	value's memory.
b62f651…	stephan	1387	*/
b62f651…	stephan	1388	cson_value * cson_value_null( void );
b62f651…	stephan	1389
b62f651…	stephan	1390	/**
b62f651…	stephan	1391	Equivalent to cson_value_new_bool(1).
b62f651…	stephan	1392	*/
b62f651…	stephan	1393	cson_value * cson_value_true( void );
b62f651…	stephan	1394
b62f651…	stephan	1395	/**
b62f651…	stephan	1396	Equivalent to cson_value_new_bool(0).
b62f651…	stephan	1397	*/
b62f651…	stephan	1398	cson_value * cson_value_false( void );
b62f651…	stephan	1399
b62f651…	stephan	1400	/**
b62f651…	stephan	1401	Semantically the same as cson_value_new_bool(), but for integers.
b62f651…	stephan	1402	*/
b62f651…	stephan	1403	cson_value * cson_value_new_integer( cson_int_t v );
b62f651…	stephan	1404
b62f651…	stephan	1405	/**
b62f651…	stephan	1406	Alias for cson_value_new_integer(v).
b62f651…	stephan	1407	*/
b62f651…	stephan	1408	cson_value * cson_new_int(cson_int_t v);
b62f651…	stephan	1409
b62f651…	stephan	1410	/**
b62f651…	stephan	1411	Semantically the same as cson_value_new_bool(), but for doubles.
b62f651…	stephan	1412	*/
b62f651…	stephan	1413	cson_value * cson_value_new_double( cson_double_t v );
b62f651…	stephan	1414
b62f651…	stephan	1415	/**
b62f651…	stephan	1416	Alias for cson_value_new_double(v).
b62f651…	stephan	1417	*/
b62f651…	stephan	1418	cson_value * cson_new_double(cson_double_t v);
b62f651…	stephan	1419
b62f651…	stephan	1420	/**
b62f651…	stephan	1421	Semantically the same as cson_value_new_bool(), but for strings.
b62f651…	stephan	1422	This creates a JSON value which copies the first n bytes of str.
b62f651…	stephan	1423	The string will automatically be NUL-terminated.
b62f651…	stephan	1424
b62f651…	stephan	1425	Note that if str is NULL or n is 0, this function still
b62f651…	stephan	1426	returns non-NULL value representing that empty string.
b62f651…	stephan	1427
b62f651…	stephan	1428	Returns NULL on allocation error.
b62f651…	stephan	1429
b62f651…	stephan	1430	See cson_value_new_bool() for important information about the
b62f651…	stephan	1431	returned memory.
b62f651…	stephan	1432	*/
b62f651…	stephan	1433	cson_value * cson_value_new_string( char const * str, unsigned int n );
b62f651…	stephan	1434
b62f651…	stephan	1435	/**
b62f651…	stephan	1436	Allocates a new "object" value and transfers ownership of it to the
b62f651…	stephan	1437	caller. It must eventually be destroyed, by the caller or its
b62f651…	stephan	1438	owning container, by passing it to cson_value_free().
b62f651…	stephan	1439
b62f651…	stephan	1440	Returns NULL on allocation error.
b62f651…	stephan	1441
b62f651…	stephan	1442	Post-conditions: cson_value_is_object(value) will return true.
b62f651…	stephan	1443
b62f651…	stephan	1444	@see cson_value_new_array()
b62f651…	stephan	1445	@see cson_value_free()
b62f651…	stephan	1446	*/
b62f651…	stephan	1447	cson_value * cson_value_new_object( void );
b62f651…	stephan	1448
b62f651…	stephan	1449	/**
b62f651…	stephan	1450	This works like cson_value_new_object() but returns an Object
b62f651…	stephan	1451	handle directly.
b62f651…	stephan	1452
b62f651…	stephan	1453	The value handle for the returned object can be fetched with
b62f651…	stephan	1454	cson_object_value(theObject).
b62f651…	stephan	1455
b62f651…	stephan	1456	Ownership is transfered to the caller, who must eventually free it
b62f651…	stephan	1457	by passing the Value handle (NOT the Object handle) to
b62f651…	stephan	1458	cson_value_free() or passing ownership to a parent container.
b62f651…	stephan	1459
b62f651…	stephan	1460	Returns NULL on error (out of memory).
b62f651…	stephan	1461	*/
b62f651…	stephan	1462	cson_object * cson_new_object( void );
b62f651…	stephan	1463
b62f651…	stephan	1464	/**
b62f651…	stephan	1465	Identical to cson_new_object() except that it creates
b62f651…	stephan	1466	an Array.
b62f651…	stephan	1467	*/
b62f651…	stephan	1468	cson_array * cson_new_array( void );
b62f651…	stephan	1469
b62f651…	stephan	1470	/**
b62f651…	stephan	1471	Identical to cson_new_object() except that it creates
b62f651…	stephan	1472	a String.
b62f651…	stephan	1473	*/
b62f651…	stephan	1474	cson_string * cson_new_string(char const * val, unsigned int len);
b62f651…	stephan	1475
b62f651…	stephan	1476	/**
b62f651…	stephan	1477	Equivalent to cson_value_free(cson_object_value(x)).
b62f651…	stephan	1478	*/
b62f651…	stephan	1479	void cson_free_object(cson_object *x);
b62f651…	stephan	1480
b62f651…	stephan	1481	/**
b62f651…	stephan	1482	Equivalent to cson_value_free(cson_array_value(x)).
b62f651…	stephan	1483	*/
b62f651…	stephan	1484	void cson_free_array(cson_array *x);
b62f651…	stephan	1485
b62f651…	stephan	1486	/**
b62f651…	stephan	1487	Equivalent to cson_value_free(cson_string_value(x)).
b62f651…	stephan	1488	*/
b62f651…	stephan	1489	void cson_free_string(cson_string *x);
b62f651…	stephan	1490
b62f651…	stephan	1491
b62f651…	stephan	1492	/**
b62f651…	stephan	1493	Allocates a new "array" value and transfers ownership of it to the
b62f651…	stephan	1494	caller. It must eventually be destroyed, by the caller or its
b62f651…	stephan	1495	owning container, by passing it to cson_value_free().
b62f651…	stephan	1496
b62f651…	stephan	1497	Returns NULL on allocation error.
b62f651…	stephan	1498
b62f651…	stephan	1499	Post-conditions: cson_value_is_array(value) will return true.
b62f651…	stephan	1500
b62f651…	stephan	1501	@see cson_value_new_object()
b62f651…	stephan	1502	@see cson_value_free()
b62f651…	stephan	1503	*/
b62f651…	stephan	1504	cson_value * cson_value_new_array( void );
b62f651…	stephan	1505
b62f651…	stephan	1506	/**
b62f651…	stephan	1507	Frees any resources owned by v, then frees v. If v is a container
b62f651…	stephan	1508	type (object or array) its children are also freed (recursively).
b62f651…	stephan	1509
b62f651…	stephan	1510	If v is NULL, this is a no-op.
b62f651…	stephan	1511
b62f651…	stephan	1512	This function decrements a reference count and only destroys the
b62f651…	stephan	1513	value if its reference count drops to 0. Reference counts are
b62f651…	stephan	1514	increased by either inserting the value into a container or via
b62f651…	stephan	1515	cson_value_add_reference(). Even if this function does not
b62f651…	stephan	1516	immediately destroy the value, the value must be considered, from
b62f651…	stephan	1517	the perspective of that client code, to have been
b62f651…	stephan	1518	destroyed/invalidated by this call.
b62f651…	stephan	1519
b62f651…	stephan	1520
b62f651…	stephan	1521	@see cson_value_new_object()
b62f651…	stephan	1522	@see cson_value_new_array()
b62f651…	stephan	1523	@see cson_value_add_reference()
b62f651…	stephan	1524	*/
b62f651…	stephan	1525	void cson_value_free(cson_value * v);
b62f651…	stephan	1526
b62f651…	stephan	1527	/**
b62f651…	stephan	1528	Alias for cson_value_free().
b62f651…	stephan	1529	*/
b62f651…	stephan	1530	void cson_free_value(cson_value * v);
b62f651…	stephan	1531
b62f651…	stephan	1532
b62f651…	stephan	1533	/**
b62f651…	stephan	1534	Functionally similar to cson_array_set(), but uses a string key
b62f651…	stephan	1535	as an index. Like arrays, if a value already exists for the given key,
b62f651…	stephan	1536	it is destroyed by this function before inserting the new value.
b62f651…	stephan	1537
b62f651…	stephan	1538	If v is NULL then this call is equivalent to
b62f651…	stephan	1539	cson_object_unset(obj,key). Note that (v==NULL) is treated
b62f651…	stephan	1540	differently from v having the special null value. In the latter
b62f651…	stephan	1541	case, the key is set to the special null value.
b62f651…	stephan	1542
b62f651…	stephan	1543	The key may be encoded as ASCII or UTF8. Results are undefined
b62f651…	stephan	1544	with other encodings, and the errors won't show up here, but may
b62f651…	stephan	1545	show up later, e.g. during output.
b62f651…	stephan	1546
b62f651…	stephan	1547	Returns 0 on success, non-0 on error. It has the following error
b62f651…	stephan	1548	cases:
b62f651…	stephan	1549
40a14c1…	stephan	1550	- CSON_RC_ArgError: obj or key are NULL or strlen(key) is 0.
b62f651…	stephan	1551
40a14c1…	stephan	1552	- CSON_RC_AllocError: an out-of-memory error
b62f651…	stephan	1553
b62f651…	stephan	1554	On error ownership of v is NOT modified, and the caller may still
b62f651…	stephan	1555	need to clean it up. For example, the following code will introduce
b62f651…	stephan	1556	a leak if this function fails:
b62f651…	stephan	1557
b62f651…	stephan	1558	@code
b62f651…	stephan	1559	cson_object_set( myObj, "foo", cson_value_new_integer(42) );
b62f651…	stephan	1560	@endcode
b62f651…	stephan	1561
b62f651…	stephan	1562	Because the value created by cson_value_new_integer() has no owner
b62f651…	stephan	1563	and is not cleaned up. The "more correct" way to do this is:
b62f651…	stephan	1564
b62f651…	stephan	1565	@code
b62f651…	stephan	1566	cson_value * v = cson_value_new_integer(42);
b62f651…	stephan	1567	int rc = cson_object_set( myObj, "foo", v );
b62f651…	stephan	1568	if( 0 != rc ) {
b62f651…	stephan	1569	cson_value_free( v );
b62f651…	stephan	1570	... handle error ...
b62f651…	stephan	1571	}
b62f651…	stephan	1572	@endcode
b62f651…	stephan	1573
b62f651…	stephan	1574	Potential TODOs:
b62f651…	stephan	1575
b62f651…	stephan	1576	- Add an overload which takes a cson_value key instead. To get
b62f651…	stephan	1577	any value out of that we first need to be able to convert arbitrary
b62f651…	stephan	1578	value types to strings. We could simply to-JSON them and use those
b62f651…	stephan	1579	as keys.
b62f651…	stephan	1580	*/
b62f651…	stephan	1581	int cson_object_set( cson_object * obj, char const * key, cson_value * v );
b62f651…	stephan	1582
b62f651…	stephan	1583	/**
b62f651…	stephan	1584	Functionaly equivalent to cson_object_set(), but takes a
b62f651…	stephan	1585	cson_string() as its KEY type. The string will be reference-counted
b62f651…	stephan	1586	like any other values, and the key may legally be used within this
b62f651…	stephan	1587	same container (as a value) or others (as a key or value) at the
b62f651…	stephan	1588	same time.
b62f651…	stephan	1589
b62f651…	stephan	1590	Returns 0 on success. On error, ownership (i.e. refcounts) of key
b62f651…	stephan	1591	and value are not modified. On success key and value will get
b62f651…	stephan	1592	increased refcounts unless they are replacing themselves (which is
b62f651…	stephan	1593	a harmless no-op).
b62f651…	stephan	1594	*/
b62f651…	stephan	1595	int cson_object_set_s( cson_object * obj, cson_string * key, cson_value * v );
b62f651…	stephan	1596
b62f651…	stephan	1597	/**
b62f651…	stephan	1598	Removes a property from an object.
b62f651…	stephan	1599
b62f651…	stephan	1600	If obj contains the given key, it is removed and 0 is returned. If
40a14c1…	stephan	1601	it is not found, CSON_RC_NotFoundError is returned (which can
b62f651…	stephan	1602	normally be ignored by client code).
b62f651…	stephan	1603
40a14c1…	stephan	1604	CSON_RC_ArgError is returned if obj or key are NULL or key has
b62f651…	stephan	1605	a length of 0.
b62f651…	stephan	1606
b62f651…	stephan	1607	Returns 0 if the given key is found and removed.
b62f651…	stephan	1608
b62f651…	stephan	1609	This is functionally equivalent calling
b62f651…	stephan	1610	cson_object_set(obj,key,NULL).
b62f651…	stephan	1611	*/
b62f651…	stephan	1612	int cson_object_unset( cson_object * obj, char const * key );
b62f651…	stephan	1613
b62f651…	stephan	1614	/**
b62f651…	stephan	1615	Searches the given object for a property with the given key. If found,
b62f651…	stephan	1616	it is returned. If no match is found, or any arguments are NULL, NULL is
b62f651…	stephan	1617	returned. The returned object is owned by obj, and may be invalidated
b62f651…	stephan	1618	by ANY operations which change obj's property list (i.e. add or remove
b62f651…	stephan	1619	properties).
b62f651…	stephan	1620
b62f651…	stephan	1621	FIXME: allocate the key/value pairs like we do for cson_array,
b62f651…	stephan	1622	to get improve the lifetimes of fetched values.
b62f651…	stephan	1623
b62f651…	stephan	1624	@see cson_object_fetch_sub()
b62f651…	stephan	1625	@see cson_object_get_sub()
b62f651…	stephan	1626	*/
b62f651…	stephan	1627	cson_value * cson_object_get( cson_object const * obj, char const * key );
b62f651…	stephan	1628
b62f651…	stephan	1629	/**
b62f651…	stephan	1630	Equivalent to cson_object_get() but takes a cson_string argument
b62f651…	stephan	1631	instead of a C-style string.
b62f651…	stephan	1632	*/
b62f651…	stephan	1633	cson_value * cson_object_get_s( cson_object const * obj, cson_string const *key );
b62f651…	stephan	1634
b62f651…	stephan	1635	/**
b62f651…	stephan	1636	Similar to cson_object_get(), but removes the value from the parent
b62f651…	stephan	1637	object's ownership. If no item is found then NULL is returned, else
b62f651…	stephan	1638	the object (now owned by the caller or possibly shared with other
b62f651…	stephan	1639	containers) is returned.
b62f651…	stephan	1640
b62f651…	stephan	1641	Returns NULL if either obj or key are NULL or key has a length
b62f651…	stephan	1642	of 0.
b62f651…	stephan	1643
b62f651…	stephan	1644	This function reduces the returned value's reference count but has
b62f651…	stephan	1645	the specific property that it does not treat refcounts 0 and 1
b62f651…	stephan	1646	identically, meaning that the returned object may have a refcount
b62f651…	stephan	1647	of 0. This behaviour works around a corner-case where we want to
b62f651…	stephan	1648	extract a child element from its parent and then destroy the parent
b62f651…	stephan	1649	(which leaves us in an undesireable (normally) reference count
b62f651…	stephan	1650	state).
b62f651…	stephan	1651	*/
b62f651…	stephan	1652	cson_value * cson_object_take( cson_object * obj, char const * key );
b62f651…	stephan	1653
b62f651…	stephan	1654	/**
b62f651…	stephan	1655	Fetches a property from a child (or [great-]*grand-child) object.
b62f651…	stephan	1656
b62f651…	stephan	1657	obj is the object to search.
b62f651…	stephan	1658
b62f651…	stephan	1659	path is a delimited string, where the delimiter is the given
b62f651…	stephan	1660	separator character.
b62f651…	stephan	1661
b62f651…	stephan	1662	This function searches for the given path, starting at the given object
b62f651…	stephan	1663	and traversing its properties as the path specifies. If a given part of the
40a14c1…	stephan	1664	path is not found, then this function fails with CSON_RC_NotFoundError.
b62f651…	stephan	1665
b62f651…	stephan	1666	If it finds the given path, it returns the value by assiging *tgt
b62f651…	stephan	1667	to it. If tgt is NULL then this function has no side-effects but
b62f651…	stephan	1668	will return 0 if the given path is found within the object, so it can be used
b62f651…	stephan	1669	to test for existence without fetching it.
b62f651…	stephan	1670
40a14c1…	stephan	1671	Returns 0 if it finds an entry, CSON_RC_NotFoundError if it finds
b62f651…	stephan	1672	no item, and any other non-zero error code on a "real" error. Errors include:
b62f651…	stephan	1673
40a14c1…	stephan	1674	- obj or path are NULL: CSON_RC_ArgError
b62f651…	stephan	1675
b62f651…	stephan	1676	- separator is 0, or path is an empty string or contains only
40a14c1…	stephan	1677	separator characters: CSON_RC_RangeError
b62f651…	stephan	1678
b62f651…	stephan	1679	- There is an upper limit on how long a single path component may
40a14c1…	stephan	1680	be (some "reasonable" internal size), and CSON_RC_RangeError is
b62f651…	stephan	1681	returned if that length is violated.
b62f651…	stephan	1682
b62f651…	stephan	1683
b62f651…	stephan	1684	Limitations:
b62f651…	stephan	1685
b62f651…	stephan	1686	- It has no way to fetch data from arrays this way. i could
b62f651…	stephan	1687	imagine, e.g., a path of "subobj.subArray.0" for
b62f651…	stephan	1688	subobj.subArray[0], or "0.3.1" for [0][3][1]. But i'm too
b62f651…	stephan	1689	lazy/tired to add this.
b62f651…	stephan	1690
b62f651…	stephan	1691	Example usage:
b62f651…	stephan	1692
b62f651…	stephan	1693
b62f651…	stephan	1694	Assume we have a JSON structure which abstractly looks like:
b62f651…	stephan	1695
b62f651…	stephan	1696	@code
b62f651…	stephan	1697	{"subobj":{"subsubobj":{"myValue":[1,2,3]}}}
b62f651…	stephan	1698	@endcode
b62f651…	stephan	1699
b62f651…	stephan	1700	Out goal is to get the value of myValue. We can do that with:
b62f651…	stephan	1701
b62f651…	stephan	1702	@code
b62f651…	stephan	1703	cson_value * v = NULL;
b62f651…	stephan	1704	int rc = cson_object_fetch_sub( object, &v, "subobj.subsubobj.myValue", '.' );
b62f651…	stephan	1705	@endcode
b62f651…	stephan	1706
b62f651…	stephan	1707	Note that because keys in JSON may legally contain a '.', the
b62f651…	stephan	1708	separator must be specified by the caller. e.g. the path
b62f651…	stephan	1709	"subobj/subsubobj/myValue" with separator='/' is equivalent the
b62f651…	stephan	1710	path "subobj.subsubobj.myValue" with separator='.'. The value of 0
b62f651…	stephan	1711	is not legal as a separator character because we cannot
b62f651…	stephan	1712	distinguish that use from the real end-of-string without requiring
b62f651…	stephan	1713	the caller to also pass in the length of the string.
b62f651…	stephan	1714
b62f651…	stephan	1715	Multiple successive separators in the list are collapsed into a
b62f651…	stephan	1716	single separator for parsing purposes. e.g. the path "a...b...c"
b62f651…	stephan	1717	(separator='.') is equivalent to "a.b.c".
b62f651…	stephan	1718
b62f651…	stephan	1719	@see cson_object_get_sub()
b62f651…	stephan	1720	@see cson_object_get_sub2()
b62f651…	stephan	1721	*/
b62f651…	stephan	1722	int cson_object_fetch_sub( cson_object const * obj, cson_value ** tgt, char const * path, char separator );
b62f651…	stephan	1723
b62f651…	stephan	1724	/**
b62f651…	stephan	1725	Similar to cson_object_fetch_sub(), but derives the path separator
b62f651…	stephan	1726	character from the first byte of the path argument. e.g. the
b62f651…	stephan	1727	following arg equivalent:
b62f651…	stephan	1728
b62f651…	stephan	1729	@code
b62f651…	stephan	1730	cson_object_fetch_sub( obj, &tgt, "foo.bar.baz", '.' );
b62f651…	stephan	1731	cson_object_fetch_sub2( obj, &tgt, ".foo.bar.baz" );
b62f651…	stephan	1732	@endcode
b62f651…	stephan	1733	*/
b62f651…	stephan	1734	int cson_object_fetch_sub2( cson_object const * obj, cson_value ** tgt, char const * path );
b62f651…	stephan	1735
b62f651…	stephan	1736	/**
b62f651…	stephan	1737	Convenience form of cson_object_fetch_sub() which returns NULL if the given
b62f651…	stephan	1738	item is not found.
b62f651…	stephan	1739	*/
b62f651…	stephan	1740	cson_value * cson_object_get_sub( cson_object const * obj, char const * path, char sep );
b62f651…	stephan	1741
b62f651…	stephan	1742	/**
b62f651…	stephan	1743	Convenience form of cson_object_fetch_sub2() which returns NULL if the given
b62f651…	stephan	1744	item is not found.
b62f651…	stephan	1745	*/
b62f651…	stephan	1746	cson_value * cson_object_get_sub2( cson_object const * obj, char const * path );
b62f651…	stephan	1747
b62f651…	stephan	1748	/** @enum CSON_MERGE_FLAGS
b62f651…	stephan	1749
b62f651…	stephan	1750	Flags for cson_object_merge().
b62f651…	stephan	1751	*/
b62f651…	stephan	1752	enum CSON_MERGE_FLAGS {
b62f651…	stephan	1753	CSON_MERGE_DEFAULT = 0,
b62f651…	stephan	1754	CSON_MERGE_REPLACE = 0x01,
b62f651…	stephan	1755	CSON_MERGE_NO_RECURSE = 0x02
b62f651…	stephan	1756	};
b62f651…	stephan	1757
b62f651…	stephan	1758	/**
b62f651…	stephan	1759	"Merges" the src object's properties into dest. Each property in
b62f651…	stephan	1760	src is copied (using reference counting, not cloning) into dest. If
b62f651…	stephan	1761	dest already has the given property then behaviour depends on the
b62f651…	stephan	1762	flags argument:
b62f651…	stephan	1763
b62f651…	stephan	1764	If flag has the CSON_MERGE_REPLACE bit set then this function will
b62f651…	stephan	1765	by default replace non-object properties with the src property. If
b62f651…	stephan	1766	src and dest both have the property AND it is an Object then this
b62f651…	stephan	1767	function operates recursively on those objects. If
b62f651…	stephan	1768	CSON_MERGE_NO_RECURSE is set then objects are not recursed in this
b62f651…	stephan	1769	manner, and will be completely replaced if CSON_MERGE_REPLACE is
b62f651…	stephan	1770	set.
b62f651…	stephan	1771
b62f651…	stephan	1772	Array properties in dest are NOT recursed for merging - they are
b62f651…	stephan	1773	either replaced or left as-is, depending on whether flags contains
b62f651…	stephan	1774	he CSON_MERGE_REPLACE bit.
b62f651…	stephan	1775
b62f651…	stephan	1776	Returns 0 on success. The error conditions are:
b62f651…	stephan	1777
40a14c1…	stephan	1778	- dest or src are NULL or (dest==src) returns CSON_RC_ArgError.
b62f651…	stephan	1779
b62f651…	stephan	1780	- dest or src contain cyclic references - this will likely cause a
b62f651…	stephan	1781	crash due to endless recursion.
b62f651…	stephan	1782
b62f651…	stephan	1783	Potential TODOs:
b62f651…	stephan	1784
b62f651…	stephan	1785	- Add a flag to copy clones, not the original values.
b62f651…	stephan	1786	*/
b62f651…	stephan	1787	int cson_object_merge( cson_object * dest, cson_object const * src, int flags );
b62f651…	stephan	1788
b62f651…	stephan	1789
b62f651…	stephan	1790	/**
b62f651…	stephan	1791	An iterator type for traversing object properties.
b62f651…	stephan	1792
b62f651…	stephan	1793	Its values must be considered private, not to be touched by client
b62f651…	stephan	1794	code.
b62f651…	stephan	1795
b62f651…	stephan	1796	@see cson_object_iter_init()
b62f651…	stephan	1797	@see cson_object_iter_next()
b62f651…	stephan	1798	*/
b62f651…	stephan	1799	struct cson_object_iterator
b62f651…	stephan	1800	{
b62f651…	stephan	1801
b62f651…	stephan	1802	/** @internal
b62f651…	stephan	1803	The underlying object.
b62f651…	stephan	1804	*/
b62f651…	stephan	1805	cson_object const * obj;
b62f651…	stephan	1806	/** @internal
b62f651…	stephan	1807	Current position in the property list.
b62f651…	stephan	1808	*/
b62f651…	stephan	1809	unsigned int pos;
b62f651…	stephan	1810	};
b62f651…	stephan	1811	typedef struct cson_object_iterator cson_object_iterator;
b62f651…	stephan	1812
b62f651…	stephan	1813	/**
b62f651…	stephan	1814	Empty-initialized cson_object_iterator object.
b62f651…	stephan	1815	*/
b62f651…	stephan	1816	#define cson_object_iterator_empty_m {NULL/obj/,0/pos/}
b62f651…	stephan	1817
b62f651…	stephan	1818	/**
b62f651…	stephan	1819	Empty-initialized cson_object_iterator object.
b62f651…	stephan	1820	*/
b62f651…	stephan	1821	extern const cson_object_iterator cson_object_iterator_empty;
b62f651…	stephan	1822
b62f651…	stephan	1823	/**
b62f651…	stephan	1824	Initializes the given iterator to point at the start of obj's
40a14c1…	stephan	1825	properties. Returns 0 on success or CSON_RC_ArgError if !obj
b62f651…	stephan	1826	or !iter.
b62f651…	stephan	1827
b62f651…	stephan	1828	obj must outlive iter, or results are undefined. Results are also
b62f651…	stephan	1829	undefined if obj is modified while the iterator is active.
b62f651…	stephan	1830
b62f651…	stephan	1831	@see cson_object_iter_next()
b62f651…	stephan	1832	*/
b62f651…	stephan	1833	int cson_object_iter_init( cson_object const * obj, cson_object_iterator * iter );
b62f651…	stephan	1834
b62f651…	stephan	1835	/** @struct cson_kvp
b62f651…	stephan	1836
b62f651…	stephan	1837	This class represents a key/value pair and is used for storing
b62f651…	stephan	1838	object properties. It is opaque to client code, and the public
b62f651…	stephan	1839	API only uses this type for purposes of iterating over cson_object
b62f651…	stephan	1840	properties using the cson_object_iterator interfaces.
b62f651…	stephan	1841	*/
b62f651…	stephan	1842
b62f651…	stephan	1843	typedef struct cson_kvp cson_kvp;
b62f651…	stephan	1844
b62f651…	stephan	1845	/**
b62f651…	stephan	1846	Returns the next property from the given iterator's object, or NULL
b62f651…	stephan	1847	if the end of the property list as been reached.
b62f651…	stephan	1848
b62f651…	stephan	1849	Note that the order of object properties is undefined by the API,
b62f651…	stephan	1850	and may change from version to version.
b62f651…	stephan	1851
b62f651…	stephan	1852	The returned memory belongs to the underlying object and may be
b62f651…	stephan	1853	invalidated by any changes to that object.
b62f651…	stephan	1854
b62f651…	stephan	1855	Example usage:
b62f651…	stephan	1856
b62f651…	stephan	1857	@code
b62f651…	stephan	1858	cson_object_iterator it;
b62f651…	stephan	1859	cson_object_iter_init( myObject, &it ); // only fails if either arg is 0
b62f651…	stephan	1860	cson_kvp * kvp;
b62f651…	stephan	1861	cson_string const * key;
b62f651…	stephan	1862	cson_value const * val;
b62f651…	stephan	1863	while( (kvp = cson_object_iter_next(&it) ) )
b62f651…	stephan	1864	{
b62f651…	stephan	1865	key = cson_kvp_key(kvp);
b62f651…	stephan	1866	val = cson_kvp_value(kvp);
b62f651…	stephan	1867	...
b62f651…	stephan	1868	}
b62f651…	stephan	1869	@endcode
b62f651…	stephan	1870
b62f651…	stephan	1871	There is no need to clean up an iterator, as it holds no dynamic resources.
b62f651…	stephan	1872
b62f651…	stephan	1873	@see cson_kvp_key()
b62f651…	stephan	1874	@see cson_kvp_value()
b62f651…	stephan	1875	*/
b62f651…	stephan	1876	cson_kvp * cson_object_iter_next( cson_object_iterator * iter );
b62f651…	stephan	1877
b62f651…	stephan	1878
b62f651…	stephan	1879	/**
b62f651…	stephan	1880	Returns the key associated with the given key/value pair,
b62f651…	stephan	1881	or NULL if !kvp. The memory is owned by the object which contains
b62f651…	stephan	1882	the key/value pair, and may be invalidated by any modifications
b62f651…	stephan	1883	to that object.
b62f651…	stephan	1884	*/
b62f651…	stephan	1885	cson_string * cson_kvp_key( cson_kvp const * kvp );
b62f651…	stephan	1886
b62f651…	stephan	1887	/**
b62f651…	stephan	1888	Returns the value associated with the given key/value pair,
b62f651…	stephan	1889	or NULL if !kvp. The memory is owned by the object which contains
b62f651…	stephan	1890	the key/value pair, and may be invalidated by any modifications
b62f651…	stephan	1891	to that object.
b62f651…	stephan	1892	*/
b62f651…	stephan	1893	cson_value * cson_kvp_value( cson_kvp const * kvp );
b62f651…	stephan	1894
b62f651…	stephan	1895	/** @typedef some unsigned int type cson_size_t
b62f651…	stephan	1896
b62f651…	stephan	1897	*/
b62f651…	stephan	1898	typedef unsigned int cson_size_t;
b62f651…	stephan	1899
b62f651…	stephan	1900	/**
b62f651…	stephan	1901	A generic buffer class.
b62f651…	stephan	1902
b62f651…	stephan	1903	They can be used like this:
b62f651…	stephan	1904
b62f651…	stephan	1905	@code
b62f651…	stephan	1906	cson_buffer b = cson_buffer_empty;
b62f651…	stephan	1907	int rc = cson_buffer_reserve( &buf, 100 );
b62f651…	stephan	1908	if( 0 != rc ) { ... allocation error ... }
b62f651…	stephan	1909	... use buf.mem ...
b62f651…	stephan	1910	... then free it up ...
b62f651…	stephan	1911	cson_buffer_reserve( &buf, 0 );
b62f651…	stephan	1912	@endcode
b62f651…	stephan	1913
b62f651…	stephan	1914	To take over ownership of a buffer's memory:
b62f651…	stephan	1915
b62f651…	stephan	1916	@code
b62f651…	stephan	1917	void * mem = b.mem;
b62f651…	stephan	1918	// mem is b.capacity bytes long, but only b.used
b62f651…	stephan	1919	// bytes of it has been "used" by the API.
b62f651…	stephan	1920	b = cson_buffer_empty;
b62f651…	stephan	1921	@endcode
b62f651…	stephan	1922
b62f651…	stephan	1923	The memory now belongs to the caller and must eventually be
b62f651…	stephan	1924	free()d.
b62f651…	stephan	1925	*/
b62f651…	stephan	1926	struct cson_buffer
b62f651…	stephan	1927	{
b62f651…	stephan	1928	/**
b62f651…	stephan	1929	The number of bytes allocated for this object.
b62f651…	stephan	1930	Use cson_buffer_reserve() to change its value.
b62f651…	stephan	1931	*/
b62f651…	stephan	1932	cson_size_t capacity;
b62f651…	stephan	1933	/**
b62f651…	stephan	1934	The number of bytes "used" by this object. It is not needed for
b62f651…	stephan	1935	all use cases, and management of this value (if needed) is up
b62f651…	stephan	1936	to the client. The cson_buffer public API does not use this
b62f651…	stephan	1937	member. The intention is that this can be used to track the
b62f651…	stephan	1938	length of strings which are allocated via cson_buffer, since
b62f651…	stephan	1939	they need an explicit length and/or null terminator.
b62f651…	stephan	1940	*/
b62f651…	stephan	1941	cson_size_t used;
b62f651…	stephan	1942
b62f651…	stephan	1943	/**
b62f651…	stephan	1944	This is a debugging/metric-counting value
b62f651…	stephan	1945	intended to help certain malloc()-conscious
b62f651…	stephan	1946	clients tweak their memory reservation sizes.
b62f651…	stephan	1947	Each time cson_buffer_reserve() expands the
b62f651…	stephan	1948	buffer, it increments this value by 1.
b62f651…	stephan	1949	*/
b62f651…	stephan	1950	cson_size_t timesExpanded;
b62f651…	stephan	1951
b62f651…	stephan	1952	/**
b62f651…	stephan	1953	The memory allocated for and owned by this buffer.
b62f651…	stephan	1954	Use cson_buffer_reserve() to change its size or
b62f651…	stephan	1955	free it. To take over ownership, do:
b62f651…	stephan	1956
b62f651…	stephan	1957	@code
b62f651…	stephan	1958	void * myptr = buf.mem;
b62f651…	stephan	1959	buf = cson_buffer_empty;
b62f651…	stephan	1960	@endcode
b62f651…	stephan	1961
b62f651…	stephan	1962	(You might also need to store buf.used and buf.capacity,
b62f651…	stephan	1963	depending on what you want to do with the memory.)
b62f651…	stephan	1964
b62f651…	stephan	1965	When doing so, the memory must eventually be passed to free()
b62f651…	stephan	1966	to deallocate it.
b62f651…	stephan	1967	*/
b62f651…	stephan	1968	unsigned char * mem;
b62f651…	stephan	1969	};
b62f651…	stephan	1970	/** Convenience typedef. */
b62f651…	stephan	1971	typedef struct cson_buffer cson_buffer;
b62f651…	stephan	1972
b62f651…	stephan	1973	/** An empty-initialized cson_buffer object. */
b62f651…	stephan	1974	#define cson_buffer_empty_m {0/capacity/,0/used/,0/timesExpanded/,NULL/mem/}
b62f651…	stephan	1975	/** An empty-initialized cson_buffer object. */
b62f651…	stephan	1976	extern const cson_buffer cson_buffer_empty;
b62f651…	stephan	1977
b62f651…	stephan	1978	/**
b62f651…	stephan	1979	Uses cson_output() to append all JSON output to the given buffer
b62f651…	stephan	1980	object. The semantics for the (v, opt) parameters, and the return
b62f651…	stephan	1981	value, are as documented for cson_output(). buf must be a non-NULL
b62f651…	stephan	1982	pointer to a properly initialized buffer (see example below).
b62f651…	stephan	1983
b62f651…	stephan	1984	Ownership of buf is not changed by calling this.
b62f651…	stephan	1985
b62f651…	stephan	1986	On success 0 is returned and the contents of buf.mem are guaranteed
b62f651…	stephan	1987	to be NULL-terminated. On error the buffer might contain partial
b62f651…	stephan	1988	contents, and it should not be used except to free its contents.
b62f651…	stephan	1989
b62f651…	stephan	1990	On error non-zero is returned. Errors include:
b62f651…	stephan	1991
40a14c1…	stephan	1992	- Invalid arguments: CSON_RC_ArgError
b62f651…	stephan	1993
40a14c1…	stephan	1994	- Buffer cannot be expanded (runs out of memory): CSON_RC_AllocError
b62f651…	stephan	1995
b62f651…	stephan	1996	Example usage:
b62f651…	stephan	1997
b62f651…	stephan	1998	@code
b62f651…	stephan	1999	cson_buffer buf = cson_buffer_empty;
b62f651…	stephan	2000	// optional: cson_buffer_reserve(&buf, 1024 * 10);
b62f651…	stephan	2001	int rc = cson_output_buffer( myValue, &buf, NULL );
b62f651…	stephan	2002	if( 0 != rc ) {
b62f651…	stephan	2003	... error! ...
b62f651…	stephan	2004	}
b62f651…	stephan	2005	else {
b62f651…	stephan	2006	... use buffer ...
b62f651…	stephan	2007	puts((char const*)buf.mem);
b62f651…	stephan	2008	}
b62f651…	stephan	2009	// In both cases, we eventually need to clean up the buffer:
b62f651…	stephan	2010	cson_buffer_reserve( &buf, 0 );
b62f651…	stephan	2011	// Or take over ownership of its memory:
b62f651…	stephan	2012	{
b62f651…	stephan	2013	char * mem = (char *)buf.mem;
b62f651…	stephan	2014	buf = cson_buffer_empty;
b62f651…	stephan	2015	...
b62f651…	stephan	2016	free(mem);
b62f651…	stephan	2017	}
b62f651…	stephan	2018	@endcode
b62f651…	stephan	2019
b62f651…	stephan	2020	@see cson_output()
b62f651…	stephan	2021
b62f651…	stephan	2022	*/
b62f651…	stephan	2023	int cson_output_buffer( cson_value const * v, cson_buffer * buf,
b62f651…	stephan	2024	cson_output_opt const * opt );
b62f651…	stephan	2025
b62f651…	stephan	2026	/**
b62f651…	stephan	2027	This works identically to cson_parse_string(), but takes a
b62f651…	stephan	2028	cson_buffer object as its input. buf->used bytes of buf->mem are
b62f651…	stephan	2029	assumed to be valid JSON input, but it need not be NUL-terminated
b62f651…	stephan	2030	(we only read up to buf->used bytes). The value of buf->used is
b62f651…	stephan	2031	assumed to be the "string length" of buf->mem, i.e. not including
b62f651…	stephan	2032	the NUL terminator.
b62f651…	stephan	2033
b62f651…	stephan	2034	Returns 0 on success, non-0 on error.
b62f651…	stephan	2035
b62f651…	stephan	2036	See cson_parse() for the semantics of the tgt, opt, and err
b62f651…	stephan	2037	parameters.
b62f651…	stephan	2038	*/
b62f651…	stephan	2039	int cson_parse_buffer( cson_value ** tgt, cson_buffer const * buf,
b62f651…	stephan	2040	cson_parse_opt const * opt, cson_parse_info * err );
b62f651…	stephan	2041
b62f651…	stephan	2042
b62f651…	stephan	2043	/**
b62f651…	stephan	2044	Reserves the given amount of memory for the given buffer object.
b62f651…	stephan	2045
b62f651…	stephan	2046	If n is 0 then buf->mem is freed and its state is set to
b62f651…	stephan	2047	NULL/0 values.
b62f651…	stephan	2048
b62f651…	stephan	2049	If buf->capacity is less than or equal to n then 0 is returned and
b62f651…	stephan	2050	buf is not modified.
b62f651…	stephan	2051
b62f651…	stephan	2052	If n is larger than buf->capacity then buf->mem is (re)allocated
b62f651…	stephan	2053	and buf->capacity contains the new length. Newly-allocated bytes
b62f651…	stephan	2054	are filled with zeroes.
b62f651…	stephan	2055
b62f651…	stephan	2056	On success 0 is returned. On error non-0 is returned and buf is not
b62f651…	stephan	2057	modified.
b62f651…	stephan	2058
b62f651…	stephan	2059	buf->mem is owned by buf and must eventually be freed by passing an
b62f651…	stephan	2060	n value of 0 to this function.
b62f651…	stephan	2061
b62f651…	stephan	2062	buf->used is never modified by this function unless n is 0, in which case
b62f651…	stephan	2063	it is reset.
b62f651…	stephan	2064	*/
b62f651…	stephan	2065	int cson_buffer_reserve( cson_buffer * buf, cson_size_t n );
b62f651…	stephan	2066
b62f651…	stephan	2067	/**
b62f651…	stephan	2068	Fills all bytes of the given buffer with the given character.
b62f651…	stephan	2069	Returns the number of bytes set (buf->capacity), or 0 if
b62f651…	stephan	2070	!buf or buf has no memory allocated to it.
b62f651…	stephan	2071	*/
b62f651…	stephan	2072	cson_size_t cson_buffer_fill( cson_buffer * buf, char c );
b62f651…	stephan	2073
b62f651…	stephan	2074	/**
b62f651…	stephan	2075	Uses a cson_data_source_f() function to buffer input into a
b62f651…	stephan	2076	cson_buffer.
b62f651…	stephan	2077
b62f651…	stephan	2078	dest must be a non-NULL, initialized (though possibly empty)
b62f651…	stephan	2079	cson_buffer object. Its contents, if any, will be overwritten by
b62f651…	stephan	2080	this function, and any memory it holds might be re-used.
b62f651…	stephan	2081
b62f651…	stephan	2082	The src function is called, and passed the state parameter, to
b62f651…	stephan	2083	fetch the input. If it returns non-0, this function returns that
b62f651…	stephan	2084	error code. src() is called, possibly repeatedly, until it reports
b62f651…	stephan	2085	that there is no more data.
b62f651…	stephan	2086
b62f651…	stephan	2087	Whether or not this function succeeds, dest still owns any memory
b62f651…	stephan	2088	pointed to by dest->mem, and the client must eventually free it by
b62f651…	stephan	2089	calling cson_buffer_reserve(dest,0).
b62f651…	stephan	2090
b62f651…	stephan	2091	dest->mem might (and possibly will) be (re)allocated by this
b62f651…	stephan	2092	function, so any pointers to it held from before this call might be
b62f651…	stephan	2093	invalidated by this call.
b62f651…	stephan	2094
b62f651…	stephan	2095	On error non-0 is returned and dest has almost certainly been
b62f651…	stephan	2096	modified but its state must be considered incomplete.
b62f651…	stephan	2097
b62f651…	stephan	2098	Errors include:
b62f651…	stephan	2099
40a14c1…	stephan	2100	- dest or src are NULL (CSON_RC_ArgError)
b62f651…	stephan	2101
40a14c1…	stephan	2102	- Allocation error (CSON_RC_AllocError)
b62f651…	stephan	2103
b62f651…	stephan	2104	- src() returns an error code
b62f651…	stephan	2105
b62f651…	stephan	2106	Whether or not the state parameter may be NULL depends on
b62f651…	stephan	2107	the src implementation requirements.
b62f651…	stephan	2108
b62f651…	stephan	2109	On success dest will contain the contents read from the input
b62f651…	stephan	2110	source. dest->used will be the length of the read-in data, and
b62f651…	stephan	2111	dest->mem will point to the memory. dest->mem is automatically
b62f651…	stephan	2112	NUL-terminated if this function succeeds, but dest->used does not
b62f651…	stephan	2113	count that terminator. On error the state of dest->mem must be
b62f651…	stephan	2114	considered incomplete, and is not guaranteed to be NUL-terminated.
b62f651…	stephan	2115
b62f651…	stephan	2116	Example usage:
b62f651…	stephan	2117
b62f651…	stephan	2118	@code
b62f651…	stephan	2119	cson_buffer buf = cson_buffer_empty;
b62f651…	stephan	2120	int rc = cson_buffer_fill_from( &buf,
b62f651…	stephan	2121	cson_data_source_FILE,
b62f651…	stephan	2122	stdin );
b62f651…	stephan	2123	if( rc )
b62f651…	stephan	2124	{
b62f651…	stephan	2125	fprintf(stderr,"Error %d (%s) while filling buffer.\n",
b62f651…	stephan	2126	rc, cson_rc_string(rc));
b62f651…	stephan	2127	cson_buffer_reserve( &buf, 0 );
b62f651…	stephan	2128	return ...;
b62f651…	stephan	2129	}
b62f651…	stephan	2130	... use the buf->mem ...
b62f651…	stephan	2131	... clean up the buffer ...
b62f651…	stephan	2132	cson_buffer_reserve( &buf, 0 );
b62f651…	stephan	2133	@endcode
b62f651…	stephan	2134
b62f651…	stephan	2135	To take over ownership of the buffer's memory, do:
b62f651…	stephan	2136
b62f651…	stephan	2137	@code
b62f651…	stephan	2138	void * mem = buf.mem;
b62f651…	stephan	2139	buf = cson_buffer_empty;
b62f651…	stephan	2140	@endcode
b62f651…	stephan	2141
b62f651…	stephan	2142	In which case the memory must eventually be passed to free() to
b62f651…	stephan	2143	free it.
b62f651…	stephan	2144	*/
b62f651…	stephan	2145	int cson_buffer_fill_from( cson_buffer * dest, cson_data_source_f src, void * state );
b62f651…	stephan	2146
b62f651…	stephan	2147
b62f651…	stephan	2148	/**
b62f651…	stephan	2149	Increments the reference count for the given value. This is a
b62f651…	stephan	2150	low-level operation and should not normally be used by client code
b62f651…	stephan	2151	without understanding exactly what side-effects it introduces.
b62f651…	stephan	2152	Mis-use can lead to premature destruction or cause a value instance
b62f651…	stephan	2153	to never be properly destructed (i.e. a memory leak).
b62f651…	stephan	2154
b62f651…	stephan	2155	This function is probably only useful for the following cases:
b62f651…	stephan	2156
b62f651…	stephan	2157	- You want to hold a reference to a value which is itself contained
b62f651…	stephan	2158	in one or more containers, and you need to be sure that your
b62f651…	stephan	2159	reference outlives the container(s) and/or that you can free your
b62f651…	stephan	2160	copy of the reference without invaliding any references to the same
b62f651…	stephan	2161	value held in containers.
b62f651…	stephan	2162
b62f651…	stephan	2163	- You want to implement "value sharing" behaviour without using an
b62f651…	stephan	2164	object or array to contain the shared value. This can be used to
b62f651…	stephan	2165	ensure the lifetime of the shared value instance. Each sharing
b62f651…	stephan	2166	point adds a reference and simply passed the value to
b62f651…	stephan	2167	cson_value_free() when they're done. The object will be kept alive
b62f651…	stephan	2168	for other sharing points which added a reference.
b62f651…	stephan	2169
b62f651…	stephan	2170	Normally any such value handles would be invalidated when the
b62f651…	stephan	2171	parent container(s) is/are cleaned up, but this function can be
b62f651…	stephan	2172	used to effectively delay the cleanup.
b62f651…	stephan	2173
b62f651…	stephan	2174	This function, at its lowest level, increments the value's
b62f651…	stephan	2175	reference count by 1.
b62f651…	stephan	2176
b62f651…	stephan	2177	To decrement the reference count, pass the value to
b62f651…	stephan	2178	cson_value_free(), after which the value must be considered, from
b62f651…	stephan	2179	the perspective of that client code, to be destroyed (though it
b62f651…	stephan	2180	will not be if there are still other live references to
b62f651…	stephan	2181	it). cson_value_free() will not _actually_ destroy the value until
b62f651…	stephan	2182	its reference count drops to 0.
b62f651…	stephan	2183
b62f651…	stephan	2184	Returns 0 on success. The only error conditions are if v is NULL
40a14c1…	stephan	2185	(CSON_RC_ArgError) or if the reference increment would overflow
40a14c1…	stephan	2186	(CSON_RC_RangeError). In theory a client would get allocation
b62f651…	stephan	2187	errors long before the reference count could overflow (assuming
b62f651…	stephan	2188	those reference counts come from container insertions, as opposed
b62f651…	stephan	2189	to via this function).
b62f651…	stephan	2190
b62f651…	stephan	2191	Insider notes which clients really need to know:
b62f651…	stephan	2192
b62f651…	stephan	2193	For shared/constant value instances, such as those returned by
b62f651…	stephan	2194	cson_value_true() and cson_value_null(), this function has no side
b62f651…	stephan	2195	effects - it does not actually modify the reference count because
b62f651…	stephan	2196	(A) those instances are shared across all client code and (B) those
b62f651…	stephan	2197	objects are static and never get cleaned up. However, that is an
b62f651…	stephan	2198	implementation detail which client code should not rely on. In
b62f651…	stephan	2199	other words, if you call cson_value_add_reference() 3 times using
b62f651…	stephan	2200	the value returned by cson_value_true() (which is incidentally a
b62f651…	stephan	2201	shared cson_value instance), you must eventually call
b62f651…	stephan	2202	cson_value_free() 3 times to (semantically) remove those
b62f651…	stephan	2203	references. However, internally the reference count for that
b62f651…	stephan	2204	specific cson_value instance will not be modified and those
b62f651…	stephan	2205	objects will never be freed (they're stack-allocated).
b62f651…	stephan	2206
b62f651…	stephan	2207	It might be interesting to note that newly-created objects
b62f651…	stephan	2208	have a reference count of 0 instead of 1. This is partly because
b62f651…	stephan	2209	if the initial reference is counted then it makes ownership
b62f651…	stephan	2210	problematic when inserting values into containers. e.g. consider the
b62f651…	stephan	2211	following code:
b62f651…	stephan	2212
b62f651…	stephan	2213	@code
b62f651…	stephan	2214	// ACHTUNG: this code is hypothetical and does not reflect
b62f651…	stephan	2215	// what actually happens!
b62f651…	stephan	2216	cson_value * v =
b62f651…	stephan	2217	cson_value_new_integer( 42 ); // v's refcount = 1
b62f651…	stephan	2218	cson_array_append( myArray, v ); // v's refcount = 2
b62f651…	stephan	2219	@endcode
b62f651…	stephan	2220
b62f651…	stephan	2221	If that were the case, the client would be forced to free his own
b62f651…	stephan	2222	reference after inserting it into the container (which is a bit
b62f651…	stephan	2223	counter-intuitive as well as intrusive). It would look a bit like
b62f651…	stephan	2224	the following and would have to be done after every create/insert
b62f651…	stephan	2225	operation:
b62f651…	stephan	2226
b62f651…	stephan	2227	@code
b62f651…	stephan	2228	// ACHTUNG: this code is hypothetical and does not reflect
b62f651…	stephan	2229	// what actually happens!
b62f651…	stephan	2230	cson_array_append( myArray, v ); // v's refcount = 2
b62f651…	stephan	2231	cson_value_free( v ); // v's refcount = 1
b62f651…	stephan	2232	@endcode
b62f651…	stephan	2233
b62f651…	stephan	2234	(As i said: it's counter-intuitive and intrusive.)
b62f651…	stephan	2235
b62f651…	stephan	2236	Instead, values start with a refcount of 0 and it is only increased
b62f651…	stephan	2237	when the value is added to an object/array container or when this
b62f651…	stephan	2238	function is used to manually increment it. cson_value_free() treats
b62f651…	stephan	2239	a refcount of 0 or 1 equivalently, destroying the value
b62f651…	stephan	2240	instance. The only semantic difference between 0 and 1, for
b62f651…	stephan	2241	purposes of cleaning up, is that a value with a non-0 refcount has
b62f651…	stephan	2242	been had its refcount adjusted, whereas a 0 refcount indicates a
b62f651…	stephan	2243	fresh, "unowned" reference.
b62f651…	stephan	2244	*/
b62f651…	stephan	2245	int cson_value_add_reference( cson_value * v );
b62f651…	stephan	2246
b62f651…	stephan	2247	#if 0
b62f651…	stephan	2248	/**
b62f651…	stephan	2249	DO NOT use this unless you know EXACTLY what you're doing.
b62f651…	stephan	2250	It is only in the public API to work around a couple corner
b62f651…	stephan	2251	cases involving extracting child elements and discarding
b62f651…	stephan	2252	their parents.
b62f651…	stephan	2253
b62f651…	stephan	2254	This function sets v's reference count to the given value.
b62f651…	stephan	2255	It does not clean up the object if rc is 0.
b62f651…	stephan	2256
b62f651…	stephan	2257	Returns 0 on success, non-0 on error.
b62f651…	stephan	2258	*/
b62f651…	stephan	2259	int cson_value_refcount_set( cson_value * v, unsigned short rc );
b62f651…	stephan	2260	#endif
b62f651…	stephan	2261
b62f651…	stephan	2262	/**
b62f651…	stephan	2263	Deeply copies a JSON value, be it an object/array or a "plain"
b62f651…	stephan	2264	value (e.g. number/string/boolean). If cv is not NULL then this
b62f651…	stephan	2265	function makes a deep clone of it and returns that clone. Ownership
b62f651…	stephan	2266	of the clone is identical t transfered to the caller, who must
b62f651…	stephan	2267	eventually free the value using cson_value_free() or add it to a
b62f651…	stephan	2268	container object/array to transfer ownership to the container. The
b62f651…	stephan	2269	returned object will be of the same logical type as orig.
b62f651…	stephan	2270
b62f651…	stephan	2271	ACHTUNG: if orig contains any cyclic references at any depth level
b62f651…	stephan	2272	this function will endlessly recurse. (Having _any_ cyclic
b62f651…	stephan	2273	references violates this library's requirements.)
b62f651…	stephan	2274
b62f651…	stephan	2275	Returns NULL if orig is NULL or if cloning fails. Assuming that
b62f651…	stephan	2276	orig is in a valid state, the only "likely" error case is that an
b62f651…	stephan	2277	allocation fails while constructing the clone. In other words, if
b62f651…	stephan	2278	cloning fails due to something other than an allocation error then
b62f651…	stephan	2279	either orig is in an invalid state or there is a bug.
b62f651…	stephan	2280
b62f651…	stephan	2281	When this function clones Objects or Arrays it shares any immutable
b62f651…	stephan	2282	values (including object keys) between the parent and the
b62f651…	stephan	2283	clone. Mutable values (Objects and Arrays) are copied, however.
b62f651…	stephan	2284	For example, if we clone:
b62f651…	stephan	2285
b62f651…	stephan	2286	@code
b62f651…	stephan	2287	{ a: 1, b: 2, c:["hi"] }
b62f651…	stephan	2288	@endcode
b62f651…	stephan	2289
b62f651…	stephan	2290	The cloned object and the array "c" would be a new Object/Array
b62f651…	stephan	2291	instances but the object keys (a,b,b) and the values of (a,b), as
b62f651…	stephan	2292	well as the string value within the "c" array, would be shared
b62f651…	stephan	2293	between the original and the clone. The "c" array itself would be
b62f651…	stephan	2294	deeply cloned, such that future changes to the clone are not
b62f651…	stephan	2295	visible to the parent, and vice versa, but immutable values within
b62f651…	stephan	2296	the array are shared (in this case the string "hi"). The
b62f651…	stephan	2297	justification for this heuristic is that immutable values can never
b62f651…	stephan	2298	be changed, so there is no harm in sharing them across
b62f651…	stephan	2299	clones. Additionally, such types can never contribute to cycles in
b62f651…	stephan	2300	a JSON tree, so they are safe to share this way. Objects and
b62f651…	stephan	2301	Arrays, on the other hand, can be modified later and can contribute
b62f651…	stephan	2302	to cycles, and thus the clone needs to be an independent instance.
b62f651…	stephan	2303	Note, however, that if this function directly passed a
b62f651…	stephan	2304	non-Object/Array, that value is deeply cloned. The sharing
b62f651…	stephan	2305	behaviour only applies when traversing Objects/Arrays.
b62f651…	stephan	2306	*/
b62f651…	stephan	2307	cson_value * cson_value_clone( cson_value const * orig );
b62f651…	stephan	2308
b62f651…	stephan	2309	/**
b62f651…	stephan	2310	Returns the value handle associated with s. The handle itself owns
b62f651…	stephan	2311	s, and ownership of the handle is not changed by calling this
b62f651…	stephan	2312	function. If the returned handle is part of a container, calling
b62f651…	stephan	2313	cson_value_free() on the returned handle invoked undefined
b62f651…	stephan	2314	behaviour (quite possibly downstream when the container tries to
b62f651…	stephan	2315	use it).
b62f651…	stephan	2316
b62f651…	stephan	2317	This function only returns NULL if s is NULL. The length of the
b62f651…	stephan	2318	returned string is cson_string_length_bytes().
b62f651…	stephan	2319	*/
b62f651…	stephan	2320	cson_value * cson_string_value(cson_string const * s);
b62f651…	stephan	2321	/**
b62f651…	stephan	2322	The Object form of cson_string_value(). See that function
b62f651…	stephan	2323	for full details.
b62f651…	stephan	2324	*/
b62f651…	stephan	2325	cson_value * cson_object_value(cson_object const * s);
b62f651…	stephan	2326
b62f651…	stephan	2327	/**
b62f651…	stephan	2328	The Array form of cson_string_value(). See that function
b62f651…	stephan	2329	for full details.
b62f651…	stephan	2330	*/
b62f651…	stephan	2331	cson_value * cson_array_value(cson_array const * s);
b62f651…	stephan	2332
b62f651…	stephan	2333
b62f651…	stephan	2334	/**
b62f651…	stephan	2335	Calculates the approximate in-memory-allocated size of v,
b62f651…	stephan	2336	recursively if it is a container type, with the following caveats
b62f651…	stephan	2337	and limitations:
b62f651…	stephan	2338
40a14c1…	stephan	2339	If a given value is reference counted and encountered multiple
b62f651…	stephan	2340	times within a traversed container, each reference is counted at
b62f651…	stephan	2341	full cost. We have no way of knowing if a given reference has been
b62f651…	stephan	2342	visited already and whether it should or should not be counted, so
b62f651…	stephan	2343	we pessimistically count them even though the _might_ not really
b62f651…	stephan	2344	count for the given object tree (it depends on where the other open
b62f651…	stephan	2345	references live).
b62f651…	stephan	2346
b62f651…	stephan	2347	This function returns 0 if any of the following are true:
b62f651…	stephan	2348
b62f651…	stephan	2349	- v is NULL
b62f651…	stephan	2350
b62f651…	stephan	2351	- v is one of the special singleton values (null, bools, empty
b62f651…	stephan	2352	string, int 0, double 0.0)
b62f651…	stephan	2353
b62f651…	stephan	2354	All other values require an allocation, and this will return their
b62f651…	stephan	2355	total memory cost, including the cson-specific internals and the
b62f651…	stephan	2356	native value(s).
b62f651…	stephan	2357
b62f651…	stephan	2358	Note that because arrays and objects might have more internal slots
b62f651…	stephan	2359	allocated than used, the alloced size of a container does not
b62f651…	stephan	2360	necessarily increase when a new item is inserted into it. An interesting
b62f651…	stephan	2361	side-effect of this is that when cson_clone()ing an array or object, the
b62f651…	stephan	2362	size of the clone can actually be less than the original.
b62f651…	stephan	2363	*/
b62f651…	stephan	2364	unsigned int cson_value_msize(cson_value const * v);
b62f651…	stephan	2365
b62f651…	stephan	2366	/**
b62f651…	stephan	2367	Parses command-line-style arguments into a JSON object.
b62f651…	stephan	2368
b62f651…	stephan	2369	It expects arguments to be in any of these forms, and any number
b62f651…	stephan	2370	of leading dashes are treated identically:
b62f651…	stephan	2371
b62f651…	stephan	2372	--key : Treats key as a boolean with a true value.
b62f651…	stephan	2373
b62f651…	stephan	2374	--key=VAL : Treats VAL as either a double, integer, or string.
b62f651…	stephan	2375
b62f651…	stephan	2376	--key= : Treats key as a JSON null (not literal NULL) value.
b62f651…	stephan	2377
b62f651…	stephan	2378	Arguments not starting with a dash are skipped.
b62f651…	stephan	2379
b62f651…	stephan	2380	Each key/value pair is inserted into an object. If a given key
b62f651…	stephan	2381	appears more than once then only the final entry is actually
b62f651…	stephan	2382	stored.
b62f651…	stephan	2383
b62f651…	stephan	2384	argc and argv are expected to be values from main() (or similar,
b62f651…	stephan	2385	possibly adjusted to remove argv[0]).
b62f651…	stephan	2386
b62f651…	stephan	2387	tgt must be either a pointer to NULL or a pointer to a
b62f651…	stephan	2388	client-provided Object. If (NULL==*tgt) then this function
b62f651…	stephan	2389	allocates a new object and on success it stores the new object in
b62f651…	stephan	2390	tgt (it is owned by the caller). If (NULL!=tgt) then it is
b62f651…	stephan	2391	assumed to be a properly allocated object. DO NOT pass a pointer to
b62f651…	stephan	2392	an unitialized pointer, as that will fool this function into
b62f651…	stephan	2393	thinking it is a valid object and Undefined Behaviour will ensue.
b62f651…	stephan	2394
b62f651…	stephan	2395	If count is not NULL then the number of arugments parsed by this
b62f651…	stephan	2396	function are assigned to it. On error, count will be the number of
b62f651…	stephan	2397	options successfully parsed before the error was encountered.
b62f651…	stephan	2398
b62f651…	stephan	2399	On success:
b62f651…	stephan	2400
b62f651…	stephan	2401	- 0 is returned.
b62f651…	stephan	2402
b62f651…	stephan	2403	- If (tgt==NULL) then tgt is assigned to a newly-allocated
b62f651…	stephan	2404	object, owned by the caller. Note that even if no arguments are
b62f651…	stephan	2405	parsed, the object is still created.
b62f651…	stephan	2406
b62f651…	stephan	2407	On error:
b62f651…	stephan	2408
b62f651…	stephan	2409	- non-0 is returned
b62f651…	stephan	2410
b62f651…	stephan	2411	- If (*tgt==NULL) then it is not modified.
b62f651…	stephan	2412
b62f651…	stephan	2413	- If (*tgt!=NULL) (i.e., the caller provides his own object) then
b62f651…	stephan	2414	it might contain partial results.
b62f651…	stephan	2415	*/
b62f651…	stephan	2416	int cson_parse_argv_flags( int argc, char const * const * argv,
b62f651…	stephan	2417	cson_object ** tgt, unsigned int * count );
b62f651…	stephan	2418
40a14c1…	stephan	2419	/**
40a14c1…	stephan	2420	Return values for the cson_pack() and cson_unpack() interfaces.
40a14c1…	stephan	2421	*/
40a14c1…	stephan	2422	enum cson_pack_retval {
40a14c1…	stephan	2423	/** Signals an out-of-memory error. */
40a14c1…	stephan	2424	CSON_PACK_ALLOC_ERROR = -1,
40a14c1…	stephan	2425	/** Signals a syntax error in the format string. */
40a14c1…	stephan	2426	CSON_PACK_ARG_ERROR = -2,
40a14c1…	stephan	2427	/**
40a14c1…	stephan	2428	Signals an that an internal error has occurred.
40a14c1…	stephan	2429	This indicates a bug in this library.
40a14c1…	stephan	2430	*/
40a14c1…	stephan	2431	CSON_PACK_INTERNAL_ERROR = -3,
40a14c1…	stephan	2432	/**
40a14c1…	stephan	2433	Signals that the JSON document does not validate agains the format
40a14c1…	stephan	2434	string passed to cson_unpack().
40a14c1…	stephan	2435	*/
40a14c1…	stephan	2436	CSON_PACK_VALIDATION_ERROR = -4
40a14c1…	stephan	2437	};
40a14c1…	stephan	2438
40a14c1…	stephan	2439	/**
40a14c1…	stephan	2440	Construct arbitrarily complex JSON documents from native C types.
40a14c1…	stephan	2441
40a14c1…	stephan	2442	Create a new object or array and add or merge the passed values and
40a14c1…	stephan	2443	properties to it according to the supplied format string.
40a14c1…	stephan	2444
40a14c1…	stephan	2445	fmt is a format string, it must at least contain an array or object
40a14c1…	stephan	2446	specifier as its root value. Format specifiers start with a percent sign '\%'
40a14c1…	stephan	2447	followed by one or more modifiers and a type character. Object properties
40a14c1…	stephan	2448	are specified as key-value pairs where the key is specified as a string and
40a14c1…	stephan	2449	passed as an argument of const char *. Any space, tab, carriage return, line
40a14c1…	stephan	2450	feed, colon and comma characters between format specifiers are ignored.
40a14c1…	stephan	2451
40a14c1…	stephan	2452	\| Type \| Description \|
40a14c1…	stephan	2453	\| :--: \| :---------- \|
40a14c1…	stephan	2454	\| s \| creates either a property name or a string value, in case of the former the corresponding argument is a pointer to const char which is a sequence of bytes specifying the name of the property that is to be created, in case of the latter the corresponding argument is a pointer to const char \|
40a14c1…	stephan	2455	\| d \| creates an integer value, the corresponding argument is an int \|
40a14c1…	stephan	2456	\| i \| ^ \|
40a14c1…	stephan	2457	\| f \| creates a floating point value, the corresponding argument is a double \|
40a14c1…	stephan	2458	\| b \| creates a boolean value, the corresponding argument is an int \|
40a14c1…	stephan	2459	\| N \| creates a null value \|
40a14c1…	stephan	2460	\| [...] \| creates an array, the corresponding argument is a pointer to a cson_array \|
40a14c1…	stephan	2461	\| {...} \| creates an array, the corresponding argument is a pointer to a cson_object \|
40a14c1…	stephan	2462
40a14c1…	stephan	2463	\| Modifier \| Description \|
40a14c1…	stephan	2464	\| :------: \| :---------- \|
40a14c1…	stephan	2465	\| l \| specifies that the following d or i specifier applies to an argument which is a pointer to long \|
40a14c1…	stephan	2466	\| ll \| specifies that the following d or i specifier applies to an argument which is a pointer to cson_int_t \|
40a14c1…	stephan	2467
40a14c1…	stephan	2468	\| Short Form \| Expands to
40a14c1…	stephan	2469	\| :--------: \| :--------- \|
40a14c1…	stephan	2470	\| {...} \| %*{...} \|
40a14c1…	stephan	2471	\| [...] \| %*[...] \|
40a14c1…	stephan	2472	\| \%D \| \%lld \|
40a14c1…	stephan	2473
40a14c1…	stephan	2474
40a14c1…	stephan	2475	Returns 0 on success. The error conditions are:
40a14c1…	stephan	2476
40a14c1…	stephan	2477	- CSON_PACK_ARG_ERROR: fmt contains a syntax error
40a14c1…	stephan	2478
40a14c1…	stephan	2479	- CSON_PACK_ALLOC_ERROR: a memory allocation failed
40a14c1…	stephan	2480
40a14c1…	stephan	2481	- CSON_PACK_INTERNAL_ERROR: an internal error has occurred, this is a bug in
40a14c1…	stephan	2482	cson
40a14c1…	stephan	2483
40a14c1…	stephan	2484	Example:
40a14c1…	stephan	2485	@code
40a14c1…	stephan	2486	cson_value * root_value;
40a14c1…	stephan	2487	cson_array * arr;
40a14c1…	stephan	2488	...
40a14c1…	stephan	2489	rc = cson_pack( root_value, "{%s: %d, %s: %[]}", "foo", 42, "bar", arr );
40a14c1…	stephan	2490	if( 0 != rc ) {
40a14c1…	stephan	2491	... error ...
40a14c1…	stephan	2492	}
40a14c1…	stephan	2493	@endcode
40a14c1…	stephan	2494	*/
40a14c1…	stephan	2495	int cson_pack( cson_value *root_valuep, const char fmt, ... );
40a14c1…	stephan	2496
40a14c1…	stephan	2497	/**
40a14c1…	stephan	2498	Same as cson_pack() except that it takes a va_list instead of a variable
40a14c1…	stephan	2499	number of arguments.
40a14c1…	stephan	2500	*/
40a14c1…	stephan	2501	int cson_vpack( cson_value *root_valuep, const char fmt, va_list args );
40a14c1…	stephan	2502
40a14c1…	stephan	2503	/**
40a14c1…	stephan	2504	Iterate over the given object or array and convert an arbitrary number of
40a14c1…	stephan	2505	JSON values into their native C types or validates them according to the
40a14c1…	stephan	2506	given format string fmt.
40a14c1…	stephan	2507
40a14c1…	stephan	2508	fmt is a format string, it must at least contain an array or object
40a14c1…	stephan	2509	specifier as its root value. Format specifiers start with a percent sign '\%'
40a14c1…	stephan	2510	followed by one or more modifiers and a type character. Object properties
40a14c1…	stephan	2511	are specified as key-value pairs where the key is specified as a string and
40a14c1…	stephan	2512	passed as an argument of const char *. Any space, tab, carriage return, line
40a14c1…	stephan	2513	feed, colon and comma characters between format specifiers are ignored.
40a14c1…	stephan	2514
40a14c1…	stephan	2515	\| Type \| Description \|
40a14c1…	stephan	2516	\| :--: \| :---------- \|
40a14c1…	stephan	2517	\| s \| matches a either a property name or a string value, in case of the former the corresponding argument is a pointer to const char which is a sequence of bytes specifying the name of the property that is to be matched, in case of the latter the corresponding argument is a pointer to a pointer to const char unless the 'm' modifier is specified where the the corresponding argument is a pointer to a pointer to char \|
40a14c1…	stephan	2518	\| d \| matches an integer value and must be used in with the "ll" modifier, the corresponding argument is a pointer to cson_int_t \|
40a14c1…	stephan	2519	\| i \| ^ \|
40a14c1…	stephan	2520	\| f \| matches a floating point value, the corresponding argument is a pointer to double \|
40a14c1…	stephan	2521	\| b \| matches a boolean value, the corresponding argument is a pointer to int \|
40a14c1…	stephan	2522	\| N \| matches a null value \|
40a14c1…	stephan	2523	\| [...] \| matches an array, the corresponding argument is a pointer to a pointer to a cson_array \|
40a14c1…	stephan	2524	\| {...} \| matches an array, the corresponding argument is a pointer to a pointer to a cson_object \|
40a14c1…	stephan	2525
40a14c1…	stephan	2526	\| Modifier \| Description \|
40a14c1…	stephan	2527	\| :------: \| :---------- \|
40a14c1…	stephan	2528	\| ? \| specifies that the property reffered to by the given property name is optional \|
40a14c1…	stephan	2529	\| * \| suppresses assignment, only check for the presence and type of the specified value \|
40a14c1…	stephan	2530	\| m \| allocates a memory buffer for the extracted string \|
40a14c1…	stephan	2531	\| ll \| specifies that the following d or i specifier applies to an argument which is a pointer to cson_int_t \|
40a14c1…	stephan	2532
40a14c1…	stephan	2533	\| Short Form \| Expands to
40a14c1…	stephan	2534	\| :--------: \| :--------- \|
40a14c1…	stephan	2535	\| {...} \| %*{...} \|
40a14c1…	stephan	2536	\| [...] \| %*[...] \|
40a14c1…	stephan	2537	\| \%D \| \%lld \|
40a14c1…	stephan	2538
40a14c1…	stephan	2539	Returns 0 on success. The error conditions are:
40a14c1…	stephan	2540
40a14c1…	stephan	2541	- CSON_PACK_ARG_ERROR: fmt contains a syntax error
40a14c1…	stephan	2542
40a14c1…	stephan	2543	- CSON_PACK_ALLOC_ERROR: a memory allocation failed
40a14c1…	stephan	2544
40a14c1…	stephan	2545	- CSON_PACK_VALIDATION_ERROR: validation failed, the JSON document structure
40a14c1…	stephan	2546	differs from that described by the format string
40a14c1…	stephan	2547
40a14c1…	stephan	2548	- CSON_PACK_INTERNAL_ERROR: an internal error has occurred, this
40a14c1…	stephan	2549	indicates a bug in this library.
40a14c1…	stephan	2550
40a14c1…	stephan	2551	Example:
40a14c1…	stephan	2552	@code
40a14c1…	stephan	2553	cson_value * root_value;
40a14c1…	stephan	2554	cson_int_t x = 0;
40a14c1…	stephan	2555	cson_array * arr = NULL;
40a14c1…	stephan	2556	const char *str = NULL;
40a14c1…	stephan	2557	...
40a14c1…	stephan	2558	rc = cson_unpack( root_value, "{%s: %d, %s: %[], %?s: %s}", "foo", &x, "bar", &arr, "baz", &str );
40a14c1…	stephan	2559	if( rc < 3 && rc >= 0 ) {
40a14c1…	stephan	2560	... optional property is missing ...
40a14c1…	stephan	2561	} else if ( CSON_PACK_ALLOC_ERROR == rc ) {
40a14c1…	stephan	2562	... out of memory error ...
40a14c1…	stephan	2563	} else if ( CSON_PACK_VALIDATION_ERROR == rc ) {
40a14c1…	stephan	2564	... unexpected JSON document structure ...
40a14c1…	stephan	2565	} else if ( rc ) {
40a14c1…	stephan	2566	... internal error ...
40a14c1…	stephan	2567	}
40a14c1…	stephan	2568	@endcode
40a14c1…	stephan	2569
40a14c1…	stephan	2570	*/
40a14c1…	stephan	2571	int cson_unpack( cson_value root_value, const char fmt, ... );
40a14c1…	stephan	2572
40a14c1…	stephan	2573	/**
40a14c1…	stephan	2574	Same as cson_unpack() except that it takes a va_list instead of a variable
40a14c1…	stephan	2575	number of arguments.
40a14c1…	stephan	2576	*/
40a14c1…	stephan	2577	int cson_vunpack( cson_value root_value, const char fmt, va_list args );
b62f651…	stephan	2578
b62f651…	stephan	2579	/* LICENSE
b62f651…	stephan	2580
b62f651…	stephan	2581	This software's source code, including accompanying documentation and
b62f651…	stephan	2582	demonstration applications, are licensed under the following
b62f651…	stephan	2583	conditions...
b62f651…	stephan	2584
b62f651…	stephan	2585	Certain files are imported from external projects and have their own
b62f651…	stephan	2586	licensing terms. Namely, the JSON_parser.* files. See their files for
b62f651…	stephan	2587	their official licenses, but the summary is "do what you want [with
b62f651…	stephan	2588	them] but leave the license text and copyright in place."
b62f651…	stephan	2589
b62f651…	stephan	2590	The author (Stephan G. Beal [http://wanderinghorse.net/home/stephan/])
b62f651…	stephan	2591	explicitly disclaims copyright in all jurisdictions which recognize
b62f651…	stephan	2592	such a disclaimer. In such jurisdictions, this software is released
b62f651…	stephan	2593	into the Public Domain.
b62f651…	stephan	2594
b62f651…	stephan	2595	In jurisdictions which do not recognize Public Domain property
b62f651…	stephan	2596	(e.g. Germany as of 2011), this software is Copyright (c) 2011 by
b62f651…	stephan	2597	Stephan G. Beal, and is released under the terms of the MIT License
b62f651…	stephan	2598	(see below).
b62f651…	stephan	2599
b62f651…	stephan	2600	In jurisdictions which recognize Public Domain property, the user of
b62f651…	stephan	2601	this software may choose to accept it either as 1) Public Domain, 2)
b62f651…	stephan	2602	under the conditions of the MIT License (see below), or 3) under the
b62f651…	stephan	2603	terms of dual Public Domain/MIT License conditions described here, as
b62f651…	stephan	2604	they choose.
b62f651…	stephan	2605
b62f651…	stephan	2606	The MIT License is about as close to Public Domain as a license can
b62f651…	stephan	2607	get, and is described in clear, concise terms at:
b62f651…	stephan	2608
b62f651…	stephan	2609	http://en.wikipedia.org/wiki/MIT_License
b62f651…	stephan	2610
b62f651…	stephan	2611	The full text of the MIT License follows:
b62f651…	stephan	2612
b62f651…	stephan	2613	--
b62f651…	stephan	2614	Copyright (c) 2011 Stephan G. Beal (http://wanderinghorse.net/home/stephan/)
b62f651…	stephan	2615
b62f651…	stephan	2616	Permission is hereby granted, free of charge, to any person
b62f651…	stephan	2617	obtaining a copy of this software and associated documentation
b62f651…	stephan	2618	files (the "Software"), to deal in the Software without
b62f651…	stephan	2619	restriction, including without limitation the rights to use,
b62f651…	stephan	2620	copy, modify, merge, publish, distribute, sublicense, and/or sell
b62f651…	stephan	2621	copies of the Software, and to permit persons to whom the
b62f651…	stephan	2622	Software is furnished to do so, subject to the following
b62f651…	stephan	2623	conditions:
b62f651…	stephan	2624
b62f651…	stephan	2625	The above copyright notice and this permission notice shall be
b62f651…	stephan	2626	included in all copies or substantial portions of the Software.
b62f651…	stephan	2627
b62f651…	stephan	2628	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
b62f651…	stephan	2629	EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
b62f651…	stephan	2630	OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
b62f651…	stephan	2631	NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
b62f651…	stephan	2632	HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
b62f651…	stephan	2633	WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
b62f651…	stephan	2634	FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
b62f651…	stephan	2635	OTHER DEALINGS IN THE SOFTWARE.
b62f651…	stephan	2636
b62f651…	stephan	2637	--END OF MIT LICENSE--
b62f651…	stephan	2638
b62f651…	stephan	2639	For purposes of the above license, the term "Software" includes
b62f651…	stephan	2640	documentation and demonstration source code which accompanies
b62f651…	stephan	2641	this software. ("Accompanies" = is contained in the Software's
b62f651…	stephan	2642	primary public source code repository.)
b62f651…	stephan	2643
b62f651…	stephan	2644	*/
b62f651…	stephan	2645
b62f651…	stephan	2646	#if defined(__cplusplus)
b62f651…	stephan	2647	} /extern "C"/
b62f651…	stephan	2648	#endif
b62f651…	stephan	2649
b62f651…	stephan	2650	#endif /* WANDERINGHORSE_NET_CSON_H_INCLUDED */
b62f651…	stephan	2651	/* end file include/wh/cson/cson.h */
b62f651…	stephan	2652	/* begin file include/wh/cson/cson_sqlite3.h */
b62f651…	stephan	2653	/** @file cson_sqlite3.h
b62f651…	stephan	2654
b62f651…	stephan	2655	This file contains cson's public sqlite3-to-JSON API declarations
b62f651…	stephan	2656	and API documentation. If CSON_ENABLE_SQLITE3 is not defined,
b62f651…	stephan	2657	or is defined to 0, then including this file will have no side-effects
b62f651…	stephan	2658	other than defining CSON_ENABLE_SQLITE3 (if it was not defined) to 0
b62f651…	stephan	2659	and defining a few include guard macros. i.e. if CSON_ENABLE_SQLITE3
b62f651…	stephan	2660	is not set to a true value then the API is not visible.
b62f651…	stephan	2661
b62f651…	stephan	2662	This API requires that <sqlite3.h> be in the INCLUDES path and that
b62f651…	stephan	2663	the client eventually link to (or directly embed) the sqlite3 library.
b62f651…	stephan	2664	*/
b62f651…	stephan	2665	#if !defined(WANDERINGHORSE_NET_CSON_SQLITE3_H_INCLUDED)
b62f651…	stephan	2666	#define WANDERINGHORSE_NET_CSON_SQLITE3_H_INCLUDED 1
b62f651…	stephan	2667	#if !defined(CSON_ENABLE_SQLITE3)
b62f651…	stephan	2668	# if defined(DOXYGEN)
b62f651…	stephan	2669	#define CSON_ENABLE_SQLITE3 1
b62f651…	stephan	2670	# else
b62f651…	stephan	2671	#define CSON_ENABLE_SQLITE3 1
b62f651…	stephan	2672	# endif
b62f651…	stephan	2673	#endif
b62f651…	stephan	2674
b62f651…	stephan	2675	#if CSON_ENABLE_SQLITE3 /* we do this here for the sake of the amalgamation build */
1bb9c77…	stephan	2676	#include "sqlite3.h"
b62f651…	stephan	2677
b62f651…	stephan	2678	#if defined(__cplusplus)
b62f651…	stephan	2679	extern "C" {
b62f651…	stephan	2680	#endif
b62f651…	stephan	2681
b62f651…	stephan	2682	/**
b62f651…	stephan	2683	Converts a single value from a single 0-based column index to its JSON
b62f651…	stephan	2684	equivalent.
b62f651…	stephan	2685
b62f651…	stephan	2686	On success it returns a new JSON value, which will have a different concrete
b62f651…	stephan	2687	type depending on the field type reported by sqlite3_column_type(st,col):
b62f651…	stephan	2688
b62f651…	stephan	2689	Integer, double, null, or string (TEXT and BLOB data, though not
b62f651…	stephan	2690	all blob data is legal for a JSON string).
b62f651…	stephan	2691
b62f651…	stephan	2692	st must be a sqlite3_step()'d row and col must be a 0-based column
b62f651…	stephan	2693	index within that result row.
b62f651…	stephan	2694	*/
b62f651…	stephan	2695	cson_value * cson_sqlite3_column_to_value( sqlite3_stmt * st, int col );
b62f651…	stephan	2696
b62f651…	stephan	2697	/**
b62f651…	stephan	2698	Creates a JSON Array object containing the names of all columns
b62f651…	stephan	2699	of the given prepared statement handle.
b62f651…	stephan	2700
b62f651…	stephan	2701	Returns a new array value on success, which the caller owns. Its elements
b62f651…	stephan	2702	are in the same order as in the underlying query.
b62f651…	stephan	2703
b62f651…	stephan	2704	On error NULL is returned.
b62f651…	stephan	2705
b62f651…	stephan	2706	st is not traversed or freed by this function - only the column
b62f651…	stephan	2707	count and names are read.
b62f651…	stephan	2708	*/
b62f651…	stephan	2709	cson_value * cson_sqlite3_column_names( sqlite3_stmt * st );
b62f651…	stephan	2710
b62f651…	stephan	2711	/**
b62f651…	stephan	2712	Creates a JSON Object containing key/value pairs corresponding
b62f651…	stephan	2713	to the result columns in the current row of the given statement
b62f651…	stephan	2714	handle. st must be a sqlite3_step()'d row result.
b62f651…	stephan	2715
b62f651…	stephan	2716	On success a new Object is returned which is owned by the
b62f651…	stephan	2717	caller. On error NULL is returned.
b62f651…	stephan	2718
b62f651…	stephan	2719	cson_sqlite3_column_to_value() is used to convert each column to a
b62f651…	stephan	2720	JSON value, and the column names are taken from
b62f651…	stephan	2721	sqlite3_column_name().
b62f651…	stephan	2722	*/
b62f651…	stephan	2723	cson_value * cson_sqlite3_row_to_object( sqlite3_stmt * st );
b62f651…	stephan	2724	/**
b62f651…	stephan	2725	Functionally almost identical to cson_sqlite3_row_to_object(), the
b62f651…	stephan	2726	only difference being how the result objects gets its column names.
b62f651…	stephan	2727	st must be a freshly-step()'d handle holding a result row.
b62f651…	stephan	2728	colNames must be an Array with at least the same number of columns
b62f651…	stephan	2729	as st. If it has fewer, NULL is returned and this function has
b62f651…	stephan	2730	no side-effects.
b62f651…	stephan	2731
b62f651…	stephan	2732	For each column in the result set, the colNames entry at the same
b62f651…	stephan	2733	index is used for the column key. If a given entry is-not-a String
b62f651…	stephan	2734	then conversion will fail and NULL will be returned.
b62f651…	stephan	2735
b62f651…	stephan	2736	The one reason to prefer this over cson_sqlite3_row_to_object() is
b62f651…	stephan	2737	that this one can share the keys across multiple rows (or even
b62f651…	stephan	2738	other JSON containers), whereas the former makes fresh copies of
b62f651…	stephan	2739	the column names for each row.
b62f651…	stephan	2740
b62f651…	stephan	2741	*/
b62f651…	stephan	2742	cson_value * cson_sqlite3_row_to_object2( sqlite3_stmt * st,
b62f651…	stephan	2743	cson_array * colNames );
b62f651…	stephan	2744
b62f651…	stephan	2745	/**
b62f651…	stephan	2746	Similar to cson_sqlite3_row_to_object(), but creates an Array
b62f651…	stephan	2747	value which contains the JSON-form values of the given result
b62f651…	stephan	2748	set row.
b62f651…	stephan	2749	*/
b62f651…	stephan	2750	cson_value * cson_sqlite3_row_to_array( sqlite3_stmt * st );
b62f651…	stephan	2751	/**
b62f651…	stephan	2752	Converts the results of an sqlite3 SELECT statement to JSON,
b62f651…	stephan	2753	in the form of a cson_value object tree.
b62f651…	stephan	2754
b62f651…	stephan	2755	st must be a prepared, but not yet traversed, SELECT query.
b62f651…	stephan	2756	tgt must be a pointer to NULL (see the example below). If
b62f651…	stephan	2757	either of those arguments are NULL, cson_rc.ArgError is returned.
b62f651…	stephan	2758
b62f651…	stephan	2759	This walks the query results and returns a JSON object which
b62f651…	stephan	2760	has a different structure depending on the value of the 'fat'
b62f651…	stephan	2761	argument.
b62f651…	stephan	2762
b62f651…	stephan	2763
b62f651…	stephan	2764	If 'fat' is 0 then the structure is:
b62f651…	stephan	2765
b62f651…	stephan	2766	@code
b62f651…	stephan	2767	{
b62f651…	stephan	2768	"columns":["colName1",..."colNameN"],
b62f651…	stephan	2769	"rows":[
b62f651…	stephan	2770	[colVal0, ... colValN],
b62f651…	stephan	2771	[colVal0, ... colValN],
b62f651…	stephan	2772	...
b62f651…	stephan	2773	]
b62f651…	stephan	2774	}
b62f651…	stephan	2775	@endcode
b62f651…	stephan	2776
b62f651…	stephan	2777	In the "non-fat" format the order of the columns and row values is
b62f651…	stephan	2778	guaranteed to be the same as that of the underlying query.
b62f651…	stephan	2779
b62f651…	stephan	2780	If 'fat' is not 0 then the structure is:
b62f651…	stephan	2781
b62f651…	stephan	2782	@code
b62f651…	stephan	2783	{
b62f651…	stephan	2784	"columns":["colName1",..."colNameN"],
b62f651…	stephan	2785	"rows":[
b62f651…	stephan	2786	{"colName1":value1,..."colNameN":valueN},
b62f651…	stephan	2787	{"colName1":value1,..."colNameN":valueN},
b62f651…	stephan	2788	...
b62f651…	stephan	2789	]
b62f651…	stephan	2790	}
b62f651…	stephan	2791	@endcode
b62f651…	stephan	2792
b62f651…	stephan	2793	In the "fat" format, the order of the "columns" entries is guaranteed
b62f651…	stephan	2794	to be the same as the underlying query fields, but the order
b62f651…	stephan	2795	of the keys in the "rows" might be different and might in fact
b62f651…	stephan	2796	change when passed through different JSON implementations,
b62f651…	stephan	2797	depending on how they implement object key/value pairs.
b62f651…	stephan	2798
b62f651…	stephan	2799	On success it returns 0 and assigns *tgt to a newly-allocated
b62f651…	stephan	2800	JSON object tree (using the above structure), which the caller owns.
b62f651…	stephan	2801	If the query returns no rows, the "rows" value will be an empty
b62f651…	stephan	2802	array, as opposed to null.
b62f651…	stephan	2803
b62f651…	stephan	2804	On error non-0 is returned and *tgt is not modified.
b62f651…	stephan	2805
b62f651…	stephan	2806	The error code cson_rc.IOError is used to indicate a db-level
b62f651…	stephan	2807	error, and cson_rc.TypeError is returned if sqlite3_column_count(st)
b62f651…	stephan	2808	returns 0 or less (indicating an invalid or non-SELECT statement).
b62f651…	stephan	2809
b62f651…	stephan	2810	The JSON data types are determined by the column type as reported
b62f651…	stephan	2811	by sqlite3_column_type():
b62f651…	stephan	2812
b62f651…	stephan	2813	SQLITE_INTEGER: integer
b62f651…	stephan	2814
b62f651…	stephan	2815	SQLITE_FLOAT: double
b62f651…	stephan	2816
b62f651…	stephan	2817	SQLITE_TEXT or SQLITE_BLOB: string, and this will only work if
b62f651…	stephan	2818	the data is UTF8 compatible.
b62f651…	stephan	2819
b62f651…	stephan	2820	If the db returns a literal or SQL NULL for a value it is converted
b62f651…	stephan	2821	to a JSON null. If it somehow finds a column type it cannot handle,
b62f651…	stephan	2822	the value is also converted to a NULL in the output.
b62f651…	stephan	2823
b62f651…	stephan	2824	Example
b62f651…	stephan	2825
b62f651…	stephan	2826	@code
b62f651…	stephan	2827	cson_value * json = NULL;
b62f651…	stephan	2828	int rc = cson_sqlite3_stmt_to_json( myStatement, &json, 1 );
b62f651…	stephan	2829	if( 0 != rc ) { ... error ... }
b62f651…	stephan	2830	else {
b62f651…	stephan	2831	cson_output_FILE( json, stdout, NULL );
b62f651…	stephan	2832	cson_value_free( json );
b62f651…	stephan	2833	}
b62f651…	stephan	2834	@endcode
b62f651…	stephan	2835	*/
b62f651…	stephan	2836	int cson_sqlite3_stmt_to_json( sqlite3_stmt * st, cson_value ** tgt, char fat );
b62f651…	stephan	2837
b62f651…	stephan	2838	/**
b62f651…	stephan	2839	A convenience wrapper around cson_sqlite3_stmt_to_json(), which
b62f651…	stephan	2840	takes SQL instead of a sqlite3_stmt object. It has the same
b62f651…	stephan	2841	return value and argument semantics as that function.
b62f651…	stephan	2842	*/
b62f651…	stephan	2843	int cson_sqlite3_sql_to_json( sqlite3 * db, cson_value ** tgt, char const * sql, char fat );
b62f651…	stephan	2844
b62f651…	stephan	2845	/**
b62f651…	stephan	2846	Binds a JSON value to a 1-based parameter index in a prepared SQL
b62f651…	stephan	2847	statement. v must be NULL or one of one of the types (null, string,
b62f651…	stephan	2848	integer, double, boolean, array). Booleans are bound as integer 0
b62f651…	stephan	2849	or 1. NULL or null are bound as SQL NULL. Integers are bound as
b62f651…	stephan	2850	64-bit ints. Strings are bound using sqlite3_bind_text() (as
b62f651…	stephan	2851	opposed to text16), but we could/should arguably bind them as
b62f651…	stephan	2852	blobs.
b62f651…	stephan	2853
b62f651…	stephan	2854	If v is an Array then ndx is is used as a starting position
b62f651…	stephan	2855	(1-based) and each item in the array is bound to the next parameter
b62f651…	stephan	2856	position (starting and ndx, though the array uses 0-based offsets).
b62f651…	stephan	2857
b62f651…	stephan	2858	TODO: add Object support for named parameters.
b62f651…	stephan	2859
b62f651…	stephan	2860	Returns 0 on success, non-0 on error.
b62f651…	stephan	2861	*/
b62f651…	stephan	2862	int cson_sqlite3_bind_value( sqlite3_stmt * st, int ndx, cson_value const * v );
b62f651…	stephan	2863
b62f651…	stephan	2864	#if defined(__cplusplus)
b62f651…	stephan	2865	} /extern "C"/
b62f651…	stephan	2866	#endif
b62f651…	stephan	2867
b62f651…	stephan	2868	#endif /* CSON_ENABLE_SQLITE3 */
b62f651…	stephan	2869	#endif /* WANDERINGHORSE_NET_CSON_SQLITE3_H_INCLUDED */
b62f651…	stephan	2870	/* end file include/wh/cson/cson_sqlite3.h */
b62f651…	stephan	2871	#endif /* FOSSIL_ENABLE_JSON */

Fossil SCM

Keyboard Shortcuts