diff --git a/compat/jansson-2.5/Makefile.am b/compat/jansson-2.5/Makefile.am index aaa944a9..a6efeb0a 100644 --- a/compat/jansson-2.5/Makefile.am +++ b/compat/jansson-2.5/Makefile.am @@ -1,6 +1,6 @@ ACLOCAL_AMFLAGS = -I m4 -EXTRA_DIST = CHANGES LICENSE README.rst win32 +EXTRA_DIST = CHANGES LICENSE README.rst SUBDIRS = src # "make distcheck" builds the dvi target, so use it to check that the diff --git a/compat/jansson-2.5/doc/Makefile.am b/compat/jansson-2.5/doc/Makefile.am deleted file mode 100644 index 5069623f..00000000 --- a/compat/jansson-2.5/doc/Makefile.am +++ /dev/null @@ -1,20 +0,0 @@ -EXTRA_DIST = conf.py apiref.rst changes.rst conformance.rst \ - gettingstarted.rst github_commits.c index.rst portability.rst \ - tutorial.rst upgrading.rst ext/refcounting.py - -SPHINXBUILD = sphinx-build -SPHINXOPTS = -d _build/doctrees $(SPHINXOPTS_EXTRA) - -html-local: - $(SPHINXBUILD) -b html $(SPHINXOPTS) $(srcdir) _build/html - -install-html-local: html - mkdir -p $(DESTDIR)$(htmldir) - cp -r _build/html $(DESTDIR)$(htmldir) - -uninstall-local: - rm -rf $(DESTDIR)$(htmldir) - -clean-local: - rm -rf _build - rm -f ext/refcounting.pyc diff --git a/compat/jansson-2.5/doc/README b/compat/jansson-2.5/doc/README deleted file mode 100644 index 930b3bf0..00000000 --- a/compat/jansson-2.5/doc/README +++ /dev/null @@ -1,5 +0,0 @@ -To build the documentation, invoke - - make html - -Then point your browser to _build/html/index.html. diff --git a/compat/jansson-2.5/doc/apiref.rst b/compat/jansson-2.5/doc/apiref.rst deleted file mode 100644 index cfab058e..00000000 --- a/compat/jansson-2.5/doc/apiref.rst +++ /dev/null @@ -1,1487 +0,0 @@ -.. _apiref: - -************* -API Reference -************* - -.. highlight:: c - -Preliminaries -============= - -All declarations are in :file:`jansson.h`, so it's enough to - -:: - - #include - -in each source file. - -All constants are prefixed with ``JSON_`` (except for those describing -the library version, prefixed with ``JANSSON_``). Other identifiers -are prefixed with ``json_``. Type names are suffixed with ``_t`` and -``typedef``\ 'd so that the ``struct`` keyword need not be used. - - -Library Version -=============== - -The Jansson version is of the form *A.B.C*, where *A* is the major -version, *B* is the minor version and *C* is the micro version. If the -micro version is zero, it's omitted from the version string, i.e. the -version string is just *A.B*. - -When a new release only fixes bugs and doesn't add new features or -functionality, the micro version is incremented. When new features are -added in a backwards compatible way, the minor version is incremented -and the micro version is set to zero. When there are backwards -incompatible changes, the major version is incremented and others are -set to zero. - -The following preprocessor constants specify the current version of -the library: - -``JANSSON_MAJOR_VERSION``, ``JANSSON_MINOR_VERSION``, ``JANSSON_MICRO_VERSION`` - Integers specifying the major, minor and micro versions, - respectively. - -``JANSSON_VERSION`` - A string representation of the current version, e.g. ``"1.2.1"`` or - ``"1.3"``. - -``JANSSON_VERSION_HEX`` - A 3-byte hexadecimal representation of the version, e.g. - ``0x010201`` for version 1.2.1 and ``0x010300`` for version 1.3. - This is useful in numeric comparisions, e.g.:: - - #if JANSSON_VERSION_HEX >= 0x010300 - /* Code specific to version 1.3 and above */ - #endif - - -Value Representation -==================== - -The JSON specification (:rfc:`4627`) defines the following data types: -*object*, *array*, *string*, *number*, *boolean*, and *null*. JSON -types are used dynamically; arrays and objects can hold any other data -type, including themselves. For this reason, Jansson's type system is -also dynamic in nature. There's one C type to represent all JSON -values, and this structure knows the type of the JSON value it holds. - -.. type:: json_t - - This data structure is used throughout the library to represent all - JSON values. It always contains the type of the JSON value it holds - and the value's reference count. The rest depends on the type of the - value. - -Objects of :type:`json_t` are always used through a pointer. There -are APIs for querying the type, manipulating the reference count, and -for constructing and manipulating values of different types. - -Unless noted otherwise, all API functions return an error value if an -error occurs. Depending on the function's signature, the error value -is either *NULL* or -1. Invalid arguments or invalid input are -apparent sources for errors. Memory allocation and I/O operations may -also cause errors. - - -Type ----- - -The type of a JSON value is queried and tested using the following -functions: - -.. type:: enum json_type - - The type of a JSON value. The following members are defined: - - +--------------------+ - | ``JSON_OBJECT`` | - +--------------------+ - | ``JSON_ARRAY`` | - +--------------------+ - | ``JSON_STRING`` | - +--------------------+ - | ``JSON_INTEGER`` | - +--------------------+ - | ``JSON_REAL`` | - +--------------------+ - | ``JSON_TRUE`` | - +--------------------+ - | ``JSON_FALSE`` | - +--------------------+ - | ``JSON_NULL`` | - +--------------------+ - - These correspond to JSON object, array, string, number, boolean and - null. A number is represented by either a value of the type - ``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value - is represented by a value of the type ``JSON_TRUE`` and false by a - value of the type ``JSON_FALSE``. - -.. function:: int json_typeof(const json_t *json) - - Return the type of the JSON value (a :type:`json_type` cast to - :type:`int`). *json* MUST NOT be *NULL*. This function is actually - implemented as a macro for speed. - -.. function:: json_is_object(const json_t *json) - json_is_array(const json_t *json) - json_is_string(const json_t *json) - json_is_integer(const json_t *json) - json_is_real(const json_t *json) - json_is_true(const json_t *json) - json_is_false(const json_t *json) - json_is_null(const json_t *json) - - These functions (actually macros) return true (non-zero) for values - of the given type, and false (zero) for values of other types and - for *NULL*. - -.. function:: json_is_number(const json_t *json) - - Returns true for values of types ``JSON_INTEGER`` and - ``JSON_REAL``, and false for other types and for *NULL*. - -.. function:: json_is_boolean(const json_t *json) - - Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false - for values of other types and for *NULL*. - - -.. _apiref-reference-count: - -Reference Count ---------------- - -The reference count is used to track whether a value is still in use -or not. When a value is created, it's reference count is set to 1. If -a reference to a value is kept (e.g. a value is stored somewhere for -later use), its reference count is incremented, and when the value is -no longer needed, the reference count is decremented. When the -reference count drops to zero, there are no references left, and the -value can be destroyed. - -The following functions are used to manipulate the reference count. - -.. function:: json_t *json_incref(json_t *json) - - Increment the reference count of *json* if it's not *NULL*. - Returns *json*. - -.. function:: void json_decref(json_t *json) - - Decrement the reference count of *json*. As soon as a call to - :func:`json_decref()` drops the reference count to zero, the value - is destroyed and it can no longer be used. - -Functions creating new JSON values set the reference count to 1. These -functions are said to return a **new reference**. Other functions -returning (existing) JSON values do not normally increase the -reference count. These functions are said to return a **borrowed -reference**. So, if the user will hold a reference to a value returned -as a borrowed reference, he must call :func:`json_incref`. As soon as -the value is no longer needed, :func:`json_decref` should be called -to release the reference. - -Normally, all functions accepting a JSON value as an argument will -manage the reference, i.e. increase and decrease the reference count -as needed. However, some functions **steal** the reference, i.e. they -have the same result as if the user called :func:`json_decref()` on -the argument right after calling the function. These functions are -suffixed with ``_new`` or have ``_new_`` somewhere in their name. - -For example, the following code creates a new JSON array and appends -an integer to it:: - - json_t *array, *integer; - - array = json_array(); - integer = json_integer(42); - - json_array_append(array, integer); - json_decref(integer); - -Note how the caller has to release the reference to the integer value -by calling :func:`json_decref()`. By using a reference stealing -function :func:`json_array_append_new()` instead of -:func:`json_array_append()`, the code becomes much simpler:: - - json_t *array = json_array(); - json_array_append_new(array, json_integer(42)); - -In this case, the user doesn't have to explicitly release the -reference to the integer value, as :func:`json_array_append_new()` -steals the reference when appending the value to the array. - -In the following sections it is clearly documented whether a function -will return a new or borrowed reference or steal a reference to its -argument. - - -Circular References -------------------- - -A circular reference is created when an object or an array is, -directly or indirectly, inserted inside itself. The direct case is -simple:: - - json_t *obj = json_object(); - json_object_set(obj, "foo", obj); - -Jansson will refuse to do this, and :func:`json_object_set()` (and -all the other such functions for objects and arrays) will return with -an error status. The indirect case is the dangerous one:: - - json_t *arr1 = json_array(), *arr2 = json_array(); - json_array_append(arr1, arr2); - json_array_append(arr2, arr1); - -In this example, the array ``arr2`` is contained in the array -``arr1``, and vice versa. Jansson cannot check for this kind of -indirect circular references without a performance hit, so it's up to -the user to avoid them. - -If a circular reference is created, the memory consumed by the values -cannot be freed by :func:`json_decref()`. The reference counts never -drops to zero because the values are keeping the references to each -other. Moreover, trying to encode the values with any of the encoding -functions will fail. The encoder detects circular references and -returns an error status. - - -True, False and Null -==================== - -These three values are implemented as singletons, so the returned -pointers won't change between invocations of these functions. - -.. function:: json_t *json_true(void) - - .. refcounting:: new - - Returns the JSON true value. - -.. function:: json_t *json_false(void) - - .. refcounting:: new - - Returns the JSON false value. - -.. function:: json_t *json_boolean(val) - - .. refcounting:: new - - Returns JSON false if ``val`` is zero, and JSON true otherwise. - This is a macro, and equivalent to ``val ? json_true() : - json_false()``. - - .. versionadded:: 2.4 - - -.. function:: json_t *json_null(void) - - .. refcounting:: new - - Returns the JSON null value. - - -String -====== - -Jansson uses UTF-8 as the character encoding. All JSON strings must be -valid UTF-8 (or ASCII, as it's a subset of UTF-8). Normal null -terminated C strings are used, so JSON strings may not contain -embedded null characters. All other Unicode codepoints U+0001 through -U+10FFFF are allowed. - -.. function:: json_t *json_string(const char *value) - - .. refcounting:: new - - Returns a new JSON string, or *NULL* on error. *value* must be a - valid UTF-8 encoded Unicode string. - -.. function:: json_t *json_string_nocheck(const char *value) - - .. refcounting:: new - - Like :func:`json_string`, but doesn't check that *value* is valid - UTF-8. Use this function only if you are certain that this really - is the case (e.g. you have already checked it by other means). - -.. function:: const char *json_string_value(const json_t *string) - - Returns the associated value of *string* as a null terminated UTF-8 - encoded string, or *NULL* if *string* is not a JSON string. - - The retuned value is read-only and must not be modified or freed by - the user. It is valid as long as *string* exists, i.e. as long as - its reference count has not dropped to zero. - -.. function:: int json_string_set(const json_t *string, const char *value) - - Sets the associated value of *string* to *value*. *value* must be a - valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on - error. - -.. function:: int json_string_set_nocheck(const json_t *string, const char *value) - - Like :func:`json_string_set`, but doesn't check that *value* is - valid UTF-8. Use this function only if you are certain that this - really is the case (e.g. you have already checked it by other - means). - - -Number -====== - -The JSON specification only contains one numeric type, "number". The C -programming language has distinct types for integer and floating-point -numbers, so for practical reasons Jansson also has distinct types for -the two. They are called "integer" and "real", respectively. For more -information, see :ref:`rfc-conformance`. - -.. type:: json_int_t - - This is the C type that is used to store JSON integer values. It - represents the widest integer type available on your system. In - practice it's just a typedef of ``long long`` if your compiler - supports it, otherwise ``long``. - - Usually, you can safely use plain ``int`` in place of - ``json_int_t``, and the implicit C integer conversion handles the - rest. Only when you know that you need the full 64-bit range, you - should use ``json_int_t`` explicitly. - -``JSON_INTEGER_IS_LONG_LONG`` - This is a preprocessor variable that holds the value 1 if - :type:`json_int_t` is ``long long``, and 0 if it's ``long``. It - can be used as follows:: - - #if JSON_INTEGER_IS_LONG_LONG - /* Code specific for long long */ - #else - /* Code specific for long */ - #endif - -``JSON_INTEGER_FORMAT`` - This is a macro that expands to a :func:`printf()` conversion - specifier that corresponds to :type:`json_int_t`, without the - leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro - is required because the actual type of :type:`json_int_t` can be - either ``long`` or ``long long``, and :func:`printf()` reuiqres - different length modifiers for the two. - - Example:: - - json_int_t x = 123123123; - printf("x is %" JSON_INTEGER_FORMAT "\n", x); - - -.. function:: json_t *json_integer(json_int_t value) - - .. refcounting:: new - - Returns a new JSON integer, or *NULL* on error. - -.. function:: json_int_t json_integer_value(const json_t *integer) - - Returns the associated value of *integer*, or 0 if *json* is not a - JSON integer. - -.. function:: int json_integer_set(const json_t *integer, json_int_t value) - - Sets the associated value of *integer* to *value*. Returns 0 on - success and -1 if *integer* is not a JSON integer. - -.. function:: json_t *json_real(double value) - - .. refcounting:: new - - Returns a new JSON real, or *NULL* on error. - -.. function:: double json_real_value(const json_t *real) - - Returns the associated value of *real*, or 0.0 if *real* is not a - JSON real. - -.. function:: int json_real_set(const json_t *real, double value) - - Sets the associated value of *real* to *value*. Returns 0 on - success and -1 if *real* is not a JSON real. - -In addition to the functions above, there's a common query function -for integers and reals: - -.. function:: double json_number_value(const json_t *json) - - Returns the associated value of the JSON integer or JSON real - *json*, cast to double regardless of the actual type. If *json* is - neither JSON real nor JSON integer, 0.0 is returned. - - -Array -===== - -A JSON array is an ordered collection of other JSON values. - -.. function:: json_t *json_array(void) - - .. refcounting:: new - - Returns a new JSON array, or *NULL* on error. Initially, the array - is empty. - -.. function:: size_t json_array_size(const json_t *array) - - Returns the number of elements in *array*, or 0 if *array* is NULL - or not a JSON array. - -.. function:: json_t *json_array_get(const json_t *array, size_t index) - - .. refcounting:: borrow - - Returns the element in *array* at position *index*. The valid range - for *index* is from 0 to the return value of - :func:`json_array_size()` minus 1. If *array* is not a JSON array, - if *array* is *NULL*, or if *index* is out of range, *NULL* is - returned. - -.. function:: int json_array_set(json_t *array, size_t index, json_t *value) - - Replaces the element in *array* at position *index* with *value*. - The valid range for *index* is from 0 to the return value of - :func:`json_array_size()` minus 1. Returns 0 on success and -1 on - error. - -.. function:: int json_array_set_new(json_t *array, size_t index, json_t *value) - - Like :func:`json_array_set()` but steals the reference to *value*. - This is useful when *value* is newly created and not used after - the call. - -.. function:: int json_array_append(json_t *array, json_t *value) - - Appends *value* to the end of *array*, growing the size of *array* - by 1. Returns 0 on success and -1 on error. - -.. function:: int json_array_append_new(json_t *array, json_t *value) - - Like :func:`json_array_append()` but steals the reference to - *value*. This is useful when *value* is newly created and not used - after the call. - -.. function:: int json_array_insert(json_t *array, size_t index, json_t *value) - - Inserts *value* to *array* at position *index*, shifting the - elements at *index* and after it one position towards the end of - the array. Returns 0 on success and -1 on error. - -.. function:: int json_array_insert_new(json_t *array, size_t index, json_t *value) - - Like :func:`json_array_insert()` but steals the reference to - *value*. This is useful when *value* is newly created and not used - after the call. - -.. function:: int json_array_remove(json_t *array, size_t index) - - Removes the element in *array* at position *index*, shifting the - elements after *index* one position towards the start of the array. - Returns 0 on success and -1 on error. The reference count of the - removed value is decremented. - -.. function:: int json_array_clear(json_t *array) - - Removes all elements from *array*. Returns 0 on sucess and -1 on - error. The reference count of all removed values are decremented. - -.. function:: int json_array_extend(json_t *array, json_t *other_array) - - Appends all elements in *other_array* to the end of *array*. - Returns 0 on success and -1 on error. - -The following macro can be used to iterate through all elements -in an array. - -.. function:: json_array_foreach(array, index, value) - - Iterate over every element of ``array``, running the block - of code that follows each time with the proper values set to - variables ``index`` and ``value``, of types :type:`size_t` and - :type:`json_t *` respectively. Example:: - - /* array is a JSON array */ - size_t index; - json_t *value; - - json_array_foreach(array, index, value) { - /* block of code that uses index and value */ - } - - The items are returned in increasing index order. - - This macro expands to an ordinary ``for`` statement upon - preprocessing, so its performance is equivalent to that of - hand-written code using the array access functions. - The main advantage of this macro is that it abstracts - away the complexity, and makes for shorter, more - concise code. - - .. versionadded:: 2.5 - - -Object -====== - -A JSON object is a dictionary of key-value pairs, where the key is a -Unicode string and the value is any JSON value. - -.. function:: json_t *json_object(void) - - .. refcounting:: new - - Returns a new JSON object, or *NULL* on error. Initially, the - object is empty. - -.. function:: size_t json_object_size(const json_t *object) - - Returns the number of elements in *object*, or 0 if *object* is not - a JSON object. - -.. function:: json_t *json_object_get(const json_t *object, const char *key) - - .. refcounting:: borrow - - Get a value corresponding to *key* from *object*. Returns *NULL* if - *key* is not found and on error. - -.. function:: int json_object_set(json_t *object, const char *key, json_t *value) - - Set the value of *key* to *value* in *object*. *key* must be a - valid null terminated UTF-8 encoded Unicode string. If there - already is a value for *key*, it is replaced by the new value. - Returns 0 on success and -1 on error. - -.. function:: int json_object_set_nocheck(json_t *object, const char *key, json_t *value) - - Like :func:`json_object_set`, but doesn't check that *key* is - valid UTF-8. Use this function only if you are certain that this - really is the case (e.g. you have already checked it by other - means). - -.. function:: int json_object_set_new(json_t *object, const char *key, json_t *value) - - Like :func:`json_object_set()` but steals the reference to - *value*. This is useful when *value* is newly created and not used - after the call. - -.. function:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value) - - Like :func:`json_object_set_new`, but doesn't check that *key* is - valid UTF-8. Use this function only if you are certain that this - really is the case (e.g. you have already checked it by other - means). - -.. function:: int json_object_del(json_t *object, const char *key) - - Delete *key* from *object* if it exists. Returns 0 on success, or - -1 if *key* was not found. The reference count of the removed value - is decremented. - -.. function:: int json_object_clear(json_t *object) - - Remove all elements from *object*. Returns 0 on success and -1 if - *object* is not a JSON object. The reference count of all removed - values are decremented. - -.. function:: int json_object_update(json_t *object, json_t *other) - - Update *object* with the key-value pairs from *other*, overwriting - existing keys. Returns 0 on success or -1 on error. - -.. function:: int json_object_update_existing(json_t *object, json_t *other) - - Like :func:`json_object_update()`, but only the values of existing - keys are updated. No new keys are created. Returns 0 on success or - -1 on error. - - .. versionadded:: 2.3 - -.. function:: int json_object_update_missing(json_t *object, json_t *other) - - Like :func:`json_object_update()`, but only new keys are created. - The value of any existing key is not changed. Returns 0 on success - or -1 on error. - - .. versionadded:: 2.3 - -The following macro can be used to iterate through all key-value pairs -in an object. - -.. function:: json_object_foreach(object, key, value) - - Iterate over every key-value pair of ``object``, running the block - of code that follows each time with the proper values set to - variables ``key`` and ``value``, of types :type:`const char *` and - :type:`json_t *` respectively. Example:: - - /* obj is a JSON object */ - const char *key; - json_t *value; - - json_object_foreach(obj, key, value) { - /* block of code that uses key and value */ - } - - The items are not returned in any particular order. - - This macro expands to an ordinary ``for`` statement upon - preprocessing, so its performance is equivalent to that of - hand-written iteration code using the object iteration protocol - (see below). The main advantage of this macro is that it abstracts - away the complexity behind iteration, and makes for shorter, more - concise code. - - .. versionadded:: 2.3 - - -The following functions implement an iteration protocol for objects, -allowing to iterate through all key-value pairs in an object. The -items are not returned in any particular order, as this would require -sorting due to the internal hashtable implementation. - -.. function:: void *json_object_iter(json_t *object) - - Returns an opaque iterator which can be used to iterate over all - key-value pairs in *object*, or *NULL* if *object* is empty. - -.. function:: void *json_object_iter_at(json_t *object, const char *key) - - Like :func:`json_object_iter()`, but returns an iterator to the - key-value pair in *object* whose key is equal to *key*, or NULL if - *key* is not found in *object*. Iterating forward to the end of - *object* only yields all key-value pairs of the object if *key* - happens to be the first key in the underlying hash table. - -.. function:: void *json_object_iter_next(json_t *object, void *iter) - - Returns an iterator pointing to the next key-value pair in *object* - after *iter*, or *NULL* if the whole object has been iterated - through. - -.. function:: const char *json_object_iter_key(void *iter) - - Extract the associated key from *iter*. - -.. function:: json_t *json_object_iter_value(void *iter) - - .. refcounting:: borrow - - Extract the associated value from *iter*. - -.. function:: int json_object_iter_set(json_t *object, void *iter, json_t *value) - - Set the value of the key-value pair in *object*, that is pointed to - by *iter*, to *value*. - -.. function:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value) - - Like :func:`json_object_iter_set()`, but steals the reference to - *value*. This is useful when *value* is newly created and not used - after the call. - -.. function:: void *json_object_key_to_iter(const char *key) - - Like :func:`json_object_iter_at()`, but much faster. Only works for - values returned by :func:`json_object_iter_key()`. Using other keys - will lead to segfaults. This function is used internally to - implement :func:`json_object_foreach`. - - .. versionadded:: 2.3 - -The iteration protocol can be used for example as follows:: - - /* obj is a JSON object */ - const char *key; - json_t *value; - - void *iter = json_object_iter(obj); - while(iter) - { - key = json_object_iter_key(iter); - value = json_object_iter_value(iter); - /* use key and value ... */ - iter = json_object_iter_next(obj, iter); - } - - -Error reporting -=============== - -Jansson uses a single struct type to pass error information to the -user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and -:ref:`apiref-unpack` for functions that pass error information using -this struct. - -.. type:: json_error_t - - .. member:: char text[] - - The error message (in UTF-8), or an empty string if a message is - not available. - - .. member:: char source[] - - Source of the error. This can be (a part of) the file name or a - special identifier in angle brackers (e.g. ````). - - .. member:: int line - - The line number on which the error occurred. - - .. member:: int column - - The column on which the error occurred. Note that this is the - *character column*, not the byte column, i.e. a multibyte UTF-8 - character counts as one column. - - .. member:: size_t position - - The position in bytes from the start of the input. This is - useful for debugging Unicode encoding problems. - -The normal use of :type:`json_error_t` is to allocate it on the stack, -and pass a pointer to a function. Example:: - - int main() { - json_t *json; - json_error_t error; - - json = json_load_file("/path/to/file.json", 0, &error); - if(!json) { - /* the error variable contains error information */ - } - ... - } - -Also note that if the call succeeded (``json != NULL`` in the above -example), the contents of ``error`` are generally left unspecified. -The decoding functions write to the ``position`` member also on -success. See :ref:`apiref-decoding` for more info. - -All functions also accept *NULL* as the :type:`json_error_t` pointer, -in which case no error information is returned to the caller. - - -Encoding -======== - -This sections describes the functions that can be used to encode -values to JSON. By default, only objects and arrays can be encoded -directly, since they are the only valid *root* values of a JSON text. -To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see -below). - -By default, the output has no newlines, and spaces are used between -array and object elements for a readable output. This behavior can be -altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags -described below. A newline is never appended to the end of the encoded -JSON data. - -Each function takes a *flags* parameter that controls some aspects of -how the data is encoded. Its default value is 0. The following macros -can be ORed together to obtain *flags*. - -``JSON_INDENT(n)`` - Pretty-print the result, using newlines between array and object - items, and indenting with *n* spaces. The valid range for *n* is - between 0 and 31 (inclusive), other values result in an undefined - output. If ``JSON_INDENT`` is not used or *n* is 0, no newlines are - inserted between array and object items. - -``JSON_COMPACT`` - This flag enables a compact representation, i.e. sets the separator - between array and object items to ``","`` and between object keys - and values to ``":"``. Without this flag, the corresponding - separators are ``", "`` and ``": "`` for more readable output. - -``JSON_ENSURE_ASCII`` - If this flag is used, the output is guaranteed to consist only of - ASCII characters. This is achived by escaping all Unicode - characters outside the ASCII range. - -``JSON_SORT_KEYS`` - If this flag is used, all the objects in output are sorted by key. - This is useful e.g. if two JSON texts are diffed or visually - compared. - -``JSON_PRESERVE_ORDER`` - If this flag is used, object keys in the output are sorted into the - same order in which they were first inserted to the object. For - example, decoding a JSON text and then encoding with this flag - preserves the order of object keys. - -``JSON_ENCODE_ANY`` - Specifying this flag makes it possible to encode any JSON value on - its own. Without it, only objects and arrays can be passed as the - *root* value to the encoding functions. - - **Note:** Encoding any value may be useful in some scenarios, but - it's generally discouraged as it violates strict compatiblity with - :rfc:`4627`. If you use this flag, don't expect interoperatibility - with other JSON systems. - - .. versionadded:: 2.1 - -``JSON_ESCAPE_SLASH`` - Escape the ``/`` characters in strings with ``\/``. - - .. versionadded:: 2.4 - -The following functions perform the actual JSON encoding. The result -is in UTF-8. - -.. function:: char *json_dumps(const json_t *root, size_t flags) - - Returns the JSON representation of *root* as a string, or *NULL* on - error. *flags* is described above. The return value must be freed - by the caller using :func:`free()`. - -.. function:: int json_dumpf(const json_t *root, FILE *output, size_t flags) - - Write the JSON representation of *root* to the stream *output*. - *flags* is described above. Returns 0 on success and -1 on error. - If an error occurs, something may have already been written to - *output*. In this case, the output is undefined and most likely not - valid JSON. - -.. function:: int json_dump_file(const json_t *json, const char *path, size_t flags) - - Write the JSON representation of *root* to the file *path*. If - *path* already exists, it is overwritten. *flags* is described - above. Returns 0 on success and -1 on error. - -.. type:: json_dump_callback_t - - A typedef for a function that's called by - :func:`json_dump_callback()`:: - - typedef int (*json_dump_callback_t)(const char *buffer, size_t size, void *data); - - *buffer* points to a buffer containing a chunk of output, *size* is - the length of the buffer, and *data* is the corresponding - :func:`json_dump_callback()` argument passed through. - - On error, the function should return -1 to stop the encoding - process. On success, it should return 0. - - .. versionadded:: 2.2 - -.. function:: int json_dump_callback(const json_t *json, json_dump_callback_t callback, void *data, size_t flags) - - Call *callback* repeatedly, passing a chunk of the JSON - representation of *root* each time. *flags* is described above. - Returns 0 on success and -1 on error. - - .. versionadded:: 2.2 - - -.. _apiref-decoding: - -Decoding -======== - -This sections describes the functions that can be used to decode JSON -text to the Jansson representation of JSON data. The JSON -specification requires that a JSON text is either a serialized array -or object, and this requirement is also enforced with the following -functions. In other words, the top level value in the JSON text being -decoded must be either array or object. To decode any JSON value, use -the ``JSON_DECODE_ANY`` flag (see below). - -See :ref:`rfc-conformance` for a discussion on Jansson's conformance -to the JSON specification. It explains many design decisions that -affect especially the behavior of the decoder. - -Each function takes a *flags* parameter that can be used to control -the behavior of the decoder. Its default value is 0. The following -macros can be ORed together to obtain *flags*. - -``JSON_REJECT_DUPLICATES`` - Issue a decoding error if any JSON object in the input text - contains duplicate keys. Without this flag, the value of the last - occurence of each key ends up in the result. Key equivalence is - checked byte-by-byte, without special Unicode comparison - algorithms. - - .. versionadded:: 2.1 - -``JSON_DECODE_ANY`` - By default, the decoder expects an array or object as the input. - With this flag enabled, the decoder accepts any valid JSON value. - - **Note:** Decoding any value may be useful in some scenarios, but - it's generally discouraged as it violates strict compatiblity with - :rfc:`4627`. If you use this flag, don't expect interoperatibility - with other JSON systems. - - .. versionadded:: 2.3 - -``JSON_DISABLE_EOF_CHECK`` - By default, the decoder expects that its whole input constitutes a - valid JSON text, and issues an error if there's extra data after - the otherwise valid JSON input. With this flag enabled, the decoder - stops after decoding a valid JSON array or object, and thus allows - extra data after the JSON text. - - Normally, reading will stop when the last ``]`` or ``}`` in the - JSON input is encountered. If both ``JSON_DISABLE_EOF_CHECK`` and - ``JSON_DECODE_ANY`` flags are used, the decoder may read one extra - UTF-8 code unit (up to 4 bytes of input). For example, decoding - ``4true`` correctly decodes the integer 4, but also reads the - ``t``. For this reason, if reading multiple consecutive values that - are not arrays or objects, they should be separated by at least one - whitespace character. - - .. versionadded:: 2.1 - -``JSON_DECODE_INT_AS_REAL`` - JSON defines only one number type. Jansson distinguishes between - ints and reals. For more information see :ref:`real-vs-integer`. - With this flag enabled the decoder interprets all numbers as real - values. Integers that do not have an exact double representation - will silently result in a loss of precision. Integers that cause - a double overflow will cause an error. - - .. versionadded:: 2.5 - -Each function also takes an optional :type:`json_error_t` parameter -that is filled with error information if decoding fails. It's also -updated on success; the number of bytes of input read is written to -its ``position`` field. This is especially useful when using -``JSON_DISABLE_EOF_CHECK`` to read multiple consecutive JSON texts. - -.. versionadded:: 2.3 - Number of bytes of input read is written to the ``position`` field - of the :type:`json_error_t` structure. - -If no error or position information is needed, you can pass *NULL*. - -The following functions perform the actual JSON decoding. - -.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error) - - .. refcounting:: new - - Decodes the JSON string *input* and returns the array or object it - contains, or *NULL* on error, in which case *error* is filled with - information about the error. *flags* is described above. - -.. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error) - - .. refcounting:: new - - Decodes the JSON string *buffer*, whose length is *buflen*, and - returns the array or object it contains, or *NULL* on error, in - which case *error* is filled with information about the error. This - is similar to :func:`json_loads()` except that the string doesn't - need to be null-terminated. *flags* is described above. - - .. versionadded:: 2.1 - -.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error) - - .. refcounting:: new - - Decodes the JSON text in stream *input* and returns the array or - object it contains, or *NULL* on error, in which case *error* is - filled with information about the error. *flags* is described - above. - - This function will start reading the input from whatever position - the input file was, without attempting to seek first. If an error - occurs, the file position will be left indeterminate. On success, - the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK`` - flag was used. In this case, the file position will be at the first - character after the last ``]`` or ``}`` in the JSON input. This - allows calling :func:`json_loadf()` on the same ``FILE`` object - multiple times, if the input consists of consecutive JSON texts, - possibly separated by whitespace. - -.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error) - - .. refcounting:: new - - Decodes the JSON text in file *path* and returns the array or - object it contains, or *NULL* on error, in which case *error* is - filled with information about the error. *flags* is described - above. - -.. type:: json_load_callback_t - - A typedef for a function that's called by - :func:`json_load_callback()` to read a chunk of input data:: - - typedef size_t (*json_load_callback_t)(void *buffer, size_t buflen, void *data); - - *buffer* points to a buffer of *buflen* bytes, and *data* is the - corresponding :func:`json_load_callback()` argument passed through. - - On success, the function should return the number of bytes read; a - returned value of 0 indicates that no data was read and that the - end of file has been reached. On error, the function should return - ``(size_t)-1`` to abort the decoding process. - - .. versionadded:: 2.4 - -.. function:: json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error) - - .. refcounting:: new - - Decodes the JSON text produced by repeated calls to *callback*, and - returns the array or object it contains, or *NULL* on error, in - which case *error* is filled with information about the error. - *data* is passed through to *callback* on each call. *flags* is - described above. - - .. versionadded:: 2.4 - - -.. _apiref-pack: - -Building Values -=============== - -This section describes functions that help to create, or *pack*, -complex JSON values, especially nested objects and arrays. Value -building is based on a *format string* that is used to tell the -functions about the expected arguments. - -For example, the format string ``"i"`` specifies a single integer -value, while the format string ``"[ssb]"`` or the equivalent ``"[s, s, -b]"`` specifies an array value with two strings and a boolean as its -items:: - - /* Create the JSON integer 42 */ - json_pack("i", 42); - - /* Create the JSON array ["foo", "bar", true] */ - json_pack("[ssb]", "foo", "bar", 1); - -Here's the full list of format specifiers. The type in parentheses -denotes the resulting JSON type, and the type in brackets (if any) -denotes the C type that is expected as the corresponding argument or -arguments. - -``s`` (string) [const char \*] - Convert a NULL terminated UTF-8 string to a JSON string. - -``s#`` (string) [const char \*, int] - Convert a UTF-8 buffer of a given length to a JSON string. - -``+`` [const char \*] - Like ``s``, but concatenate to the previous string. Only valid - after ``s``, ``s#``, ``+`` or ``+#``. - -``+#`` [const char \*, int] - Like ``s#``, but concatenate to the previous string. Only valid - after ``s``, ``s#``, ``+`` or ``+#``. - -``n`` (null) - Output a JSON null value. No argument is consumed. - -``b`` (boolean) [int] - Convert a C :type:`int` to JSON boolean value. Zero is converted - to ``false`` and non-zero to ``true``. - -``i`` (integer) [int] - Convert a C :type:`int` to JSON integer. - -``I`` (integer) [json_int_t] - Convert a C :type:`json_int_t` to JSON integer. - -``f`` (real) [double] - Convert a C :type:`double` to JSON real. - -``o`` (any value) [json_t \*] - Output any given JSON value as-is. If the value is added to an - array or object, the reference to the value passed to ``o`` is - stolen by the container. - -``O`` (any value) [json_t \*] - Like ``o``, but the argument's reference count is incremented. - This is useful if you pack into an array or object and want to - keep the reference for the JSON value consumed by ``O`` to - yourself. - -``[fmt]`` (array) - Build an array with contents from the inner format string. ``fmt`` - may contain objects and arrays, i.e. recursive value building is - supported. - -``{fmt}`` (object) - Build an object with contents from the inner format string - ``fmt``. The first, third, etc. format specifier represent a key, - and must be a string (see ``s``, ``s#``, ``+`` and ``+#`` above), - as object keys are always strings. The second, fourth, etc. format - specifier represent a value. Any value may be an object or array, - i.e. recursive value building is supported. - -Whitespace, ``:`` and ``,`` are ignored. - -The following functions compose the value building API: - -.. function:: json_t *json_pack(const char *fmt, ...) - - .. refcounting:: new - - Build a new JSON value according to the format string *fmt*. For - each format specifier (except for ``{}[]n``), one or more arguments - are consumed and used to build the corresponding value. Returns - *NULL* on error. - -.. function:: json_t *json_pack_ex(json_error_t *error, size_t flags, const char *fmt, ...) - json_t *json_vpack_ex(json_error_t *error, size_t flags, const char *fmt, va_list ap) - - .. refcounting:: new - - Like :func:`json_pack()`, but an in the case of an error, an error - message is written to *error*, if it's not *NULL*. The *flags* - parameter is currently unused and should be set to 0. - - As only the errors in format string (and out-of-memory errors) can - be caught by the packer, these two functions are most likely only - useful for debugging format strings. - -More examples:: - - /* Build an empty JSON object */ - json_pack("{}"); - - /* Build the JSON object {"foo": 42, "bar": 7} */ - json_pack("{sisi}", "foo", 42, "bar", 7); - - /* Like above, ':', ',' and whitespace are ignored */ - json_pack("{s:i, s:i}", "foo", 42, "bar", 7); - - /* Build the JSON array [[1, 2], {"cool": true}] */ - json_pack("[[i,i],{s:b}]", 1, 2, "cool", 1); - - /* Build a string from a non-NUL terminated buffer */ - char buffer[4] = {'t', 'e', 's', 't'}; - json_pack("s#", buffer, 4); - - /* Concatentate strings together to build the JSON string "foobarbaz" */ - json_pack("s++", "foo", "bar", "baz"); - - -.. _apiref-unpack: - -Parsing and Validating Values -============================= - -This section describes functions that help to validate complex values -and extract, or *unpack*, data from them. Like :ref:`building values -`, this is also based on format strings. - -While a JSON value is unpacked, the type specified in the format -string is checked to match that of the JSON value. This is the -validation part of the process. In addition to this, the unpacking -functions can also check that all items of arrays and objects are -unpacked. This check be enabled with the format specifier ``!`` or by -using the flag ``JSON_STRICT``. See below for details. - -Here's the full list of format specifiers. The type in parentheses -denotes the JSON type, and the type in brackets (if any) denotes the C -type whose address should be passed. - -``s`` (string) [const char \*] - Convert a JSON string to a pointer to a NULL terminated UTF-8 - string. The resulting string is extracted by using - :func:`json_string_value()` internally, so it exists as long as - there are still references to the corresponding JSON string. - -``n`` (null) - Expect a JSON null value. Nothing is extracted. - -``b`` (boolean) [int] - Convert a JSON boolean value to a C :type:`int`, so that ``true`` - is converted to 1 and ``false`` to 0. - -``i`` (integer) [int] - Convert a JSON integer to C :type:`int`. - -``I`` (integer) [json_int_t] - Convert a JSON integer to C :type:`json_int_t`. - -``f`` (real) [double] - Convert a JSON real to C :type:`double`. - -``F`` (integer or real) [double] - Convert a JSON number (integer or real) to C :type:`double`. - -``o`` (any value) [json_t \*] - Store a JSON value with no conversion to a :type:`json_t` pointer. - -``O`` (any value) [json_t \*] - Like ``O``, but the JSON value's reference count is incremented. - -``[fmt]`` (array) - Convert each item in the JSON array according to the inner format - string. ``fmt`` may contain objects and arrays, i.e. recursive - value extraction is supporetd. - -``{fmt}`` (object) - Convert each item in the JSON object according to the inner format - string ``fmt``. The first, third, etc. format specifier represent - a key, and must be ``s``. The corresponding argument to unpack - functions is read as the object key. The second fourth, etc. - format specifier represent a value and is written to the address - given as the corresponding argument. **Note** that every other - argument is read from and every other is written to. - - ``fmt`` may contain objects and arrays as values, i.e. recursive - value extraction is supporetd. - - .. versionadded:: 2.3 - Any ``s`` representing a key may be suffixed with a ``?`` to - make the key optional. If the key is not found, nothing is - extracted. See below for an example. - -``!`` - This special format specifier is used to enable the check that - all object and array items are accessed, on a per-value basis. It - must appear inside an array or object as the last format specifier - before the closing bracket or brace. To enable the check globally, - use the ``JSON_STRICT`` unpacking flag. - -``*`` - This special format specifier is the opposite of ``!``. If the - ``JSON_STRICT`` flag is used, ``*`` can be used to disable the - strict check on a per-value basis. It must appear inside an array - or object as the last format specifier before the closing bracket - or brace. - -Whitespace, ``:`` and ``,`` are ignored. - -The following functions compose the parsing and validation API: - -.. function:: int json_unpack(json_t *root, const char *fmt, ...) - - Validate and unpack the JSON value *root* according to the format - string *fmt*. Returns 0 on success and -1 on failure. - -.. function:: int json_unpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, ...) - int json_vunpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, va_list ap) - - Validate and unpack the JSON value *root* according to the format - string *fmt*. If an error occurs and *error* is not *NULL*, write - error information to *error*. *flags* can be used to control the - behaviour of the unpacker, see below for the flags. Returns 0 on - success and -1 on failure. - -.. note:: - - The first argument of all unpack functions is ``json_t *root`` - instead of ``const json_t *root``, because the use of ``O`` format - specifier causes the reference count of ``root``, or some value - reachable from ``root``, to be increased. Furthermore, the ``o`` - format specifier may be used to extract a value as-is, which allows - modifying the structure or contents of a value reachable from - ``root``. - - If the ``O`` and ``o`` format specifiers are not used, it's - perfectly safe to cast a ``const json_t *`` variable to plain - ``json_t *`` when used with these functions. - -The following unpacking flags are available: - -``JSON_STRICT`` - Enable the extra validation step checking that all object and - array items are unpacked. This is equivalent to appending the - format specifier ``!`` to the end of every array and object in the - format string. - -``JSON_VALIDATE_ONLY`` - Don't extract any data, just validate the JSON value against the - given format string. Note that object keys must still be specified - after the format string. - -Examples:: - - /* root is the JSON integer 42 */ - int myint; - json_unpack(root, "i", &myint); - assert(myint == 42); - - /* root is the JSON object {"foo": "bar", "quux": true} */ - const char *str; - int boolean; - json_unpack(root, "{s:s, s:b}", "foo", &str, "quux", &boolean); - assert(strcmp(str, "bar") == 0 && boolean == 1); - - /* root is the JSON array [[1, 2], {"baz": null} */ - json_error_t error; - json_unpack_ex(root, &error, JSON_VALIDATE_ONLY, "[[i,i], {s:n}]", "baz"); - /* returns 0 for validation success, nothing is extracted */ - - /* root is the JSON array [1, 2, 3, 4, 5] */ - int myint1, myint2; - json_unpack(root, "[ii!]", &myint1, &myint2); - /* returns -1 for failed validation */ - - /* root is an empty JSON object */ - int myint = 0, myint2 = 0; - json_unpack(root, "{s?i, s?[ii]}", - "foo", &myint1, - "bar", &myint2, &myint3); - /* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */ - - -Equality -======== - -Testing for equality of two JSON values cannot, in general, be -achieved using the ``==`` operator. Equality in the terms of the -``==`` operator states that the two :type:`json_t` pointers point to -exactly the same JSON value. However, two JSON values can be equal not -only if they are exactly the same value, but also if they have equal -"contents": - -* Two integer or real values are equal if their contained numeric - values are equal. An integer value is never equal to a real value, - though. - -* Two strings are equal if their contained UTF-8 strings are equal, - byte by byte. Unicode comparison algorithms are not implemented. - -* Two arrays are equal if they have the same number of elements and - each element in the first array is equal to the corresponding - element in the second array. - -* Two objects are equal if they have exactly the same keys and the - value for each key in the first object is equal to the value of the - corresponding key in the second object. - -* Two true, false or null values have no "contents", so they are equal - if their types are equal. (Because these values are singletons, - their equality can actually be tested with ``==``.) - -The following function can be used to test whether two JSON values are -equal. - -.. function:: int json_equal(json_t *value1, json_t *value2) - - Returns 1 if *value1* and *value2* are equal, as defined above. - Returns 0 if they are inequal or one or both of the pointers are - *NULL*. - - -Copying -======= - -Because of reference counting, passing JSON values around doesn't -require copying them. But sometimes a fresh copy of a JSON value is -needed. For example, if you need to modify an array, but still want to -use the original afterwards, you should take a copy of it first. - -Jansson supports two kinds of copying: shallow and deep. There is a -difference between these methods only for arrays and objects. Shallow -copying only copies the first level value (array or object) and uses -the same child values in the copied value. Deep copying makes a fresh -copy of the child values, too. Moreover, all the child values are deep -copied in a recursive fashion. - -.. function:: json_t *json_copy(json_t *value) - - .. refcounting:: new - - Returns a shallow copy of *value*, or *NULL* on error. - -.. function:: json_t *json_deep_copy(const json_t *value) - - .. refcounting:: new - - Returns a deep copy of *value*, or *NULL* on error. - - -.. _apiref-custom-memory-allocation: - -Custom Memory Allocation -======================== - -By default, Jansson uses :func:`malloc()` and :func:`free()` for -memory allocation. These functions can be overridden if custom -behavior is needed. - -.. type:: json_malloc_t - - A typedef for a function pointer with :func:`malloc()`'s - signature:: - - typedef void *(*json_malloc_t)(size_t); - -.. type:: json_free_t - - A typedef for a function pointer with :func:`free()`'s - signature:: - - typedef void (*json_free_t)(void *); - -.. function:: void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn) - - Use *malloc_fn* instead of :func:`malloc()` and *free_fn* instead - of :func:`free()`. This function has to be called before any other - Jansson's API functions to ensure that all memory operations use - the same functions. - -**Examples:** - -Circumvent problems with different CRT heaps on Windows by using -application's :func:`malloc()` and :func:`free()`:: - - json_set_alloc_funcs(malloc, free); - -Use the `Boehm's conservative garbage collector`_ for memory -operations:: - - json_set_alloc_funcs(GC_malloc, GC_free); - -.. _Boehm's conservative garbage collector: http://www.hpl.hp.com/personal/Hans_Boehm/gc/ - -Allow storing sensitive data (e.g. passwords or encryption keys) in -JSON structures by zeroing all memory when freed:: - - static void *secure_malloc(size_t size) - { - /* Store the memory area size in the beginning of the block */ - void *ptr = malloc(size + 8); - *((size_t *)ptr) = size; - return ptr + 8; - } - - static void secure_free(void *ptr) - { - size_t size; - - ptr -= 8; - size = *((size_t *)ptr); - - guaranteed_memset(ptr, 0, size); - free(ptr); - } - - int main() - { - json_set_alloc_funcs(secure_malloc, secure_free); - /* ... */ - } - -For more information about the issues of storing sensitive data in -memory, see -http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html. -The page also explains the :func:`guaranteed_memset()` function used -in the example and gives a sample implementation for it. diff --git a/compat/jansson-2.5/doc/changes.rst b/compat/jansson-2.5/doc/changes.rst deleted file mode 100644 index ea568437..00000000 --- a/compat/jansson-2.5/doc/changes.rst +++ /dev/null @@ -1,5 +0,0 @@ -****************** -Changes in Jansson -****************** - -.. include:: ../CHANGES diff --git a/compat/jansson-2.5/doc/conf.py b/compat/jansson-2.5/doc/conf.py deleted file mode 100644 index ddf58333..00000000 --- a/compat/jansson-2.5/doc/conf.py +++ /dev/null @@ -1,217 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Jansson documentation build configuration file, created by -# sphinx-quickstart on Sun Sep 5 21:47:20 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('ext')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['refcounting'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Jansson' -copyright = u'2009-2013, Petri Lehtinen' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '2.5' -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -default_role = 'c:func' -primary_domain = 'c' - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -#html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'Janssondoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'Jansson.tex', u'Jansson Documentation', - u'Petri Lehtinen', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'jansson', u'Jansson Documentation', - [u'Petri Lehtinen'], 1) -] diff --git a/compat/jansson-2.5/doc/conformance.rst b/compat/jansson-2.5/doc/conformance.rst deleted file mode 100644 index 19f603d6..00000000 --- a/compat/jansson-2.5/doc/conformance.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _rfc-conformance: - -*************** -RFC Conformance -*************** - -JSON is specified in :rfc:`4627`, *"The application/json Media Type -for JavaScript Object Notation (JSON)"*. - -Character Encoding -================== - -Jansson only supports UTF-8 encoded JSON texts. It does not support or -auto-detect any of the other encodings mentioned in the RFC, namely -UTF-16LE, UTF-16BE, UTF-32LE or UTF-32BE. Pure ASCII is supported, as -it's a subset of UTF-8. - -Strings -======= - -JSON strings are mapped to C-style null-terminated character arrays, -and UTF-8 encoding is used internally. Strings may not contain -embedded null characters, not even escaped ones. - -For example, trying to decode the following JSON text leads to a parse -error:: - - ["this string contains the null character: \u0000"] - -All other Unicode codepoints U+0001 through U+10FFFF are allowed. - -Unicode normalization or any other transformation is never performed -on any strings (string values or object keys). When checking for -equivalence of strings or object keys, the comparison is performed -byte by byte between the original UTF-8 representations of the -strings. - -Numbers -======= - -.. _real-vs-integer: - -Real vs. Integer ----------------- - -JSON makes no distinction between real and integer numbers; Jansson -does. Real numbers are mapped to the ``double`` type and integers to -the ``json_int_t`` type, which is a typedef of ``long long`` or -``long``, depending on whether ``long long`` is supported by your -compiler or not. - -A JSON number is considered to be a real number if its lexical -representation includes one of ``e``, ``E``, or ``.``; regardless if -its actual numeric value is a true integer (e.g., all of ``1E6``, -``3.0``, ``400E-2``, and ``3.14E3`` are mathematical integers, but -will be treated as real values). With the ``JSON_DECODE_INT_AS_REAL`` -decoder flag set all numbers are interpreted as real. - -All other JSON numbers are considered integers. - -When encoding to JSON, real values are always represented -with a fractional part; e.g., the ``double`` value 3.0 will be -represented in JSON as ``3.0``, not ``3``. - -Overflow, Underflow & Precision -------------------------------- - -Real numbers whose absolute values are too small to be represented in -a C ``double`` will be silently estimated with 0.0. Thus, depending on -platform, JSON numbers very close to zero such as 1E-999 may result in -0.0. - -Real numbers whose absolute values are too large to be represented in -a C ``double`` will result in an overflow error (a JSON decoding -error). Thus, depending on platform, JSON numbers like 1E+999 or --1E+999 may result in a parsing error. - -Likewise, integer numbers whose absolute values are too large to be -represented in the ``json_int_t`` type (see above) will result in an -overflow error (a JSON decoding error). Thus, depending on platform, -JSON numbers like 1000000000000000 may result in parsing error. - -Parsing JSON real numbers may result in a loss of precision. As long -as overflow does not occur (i.e. a total loss of precision), the -rounded approximate value is silently used. Thus the JSON number -1.000000000000000005 may, depending on platform, result in the -``double`` value 1.0. - -Signed zeros ------------- - -JSON makes no statement about what a number means; however Javascript -(ECMAscript) does state that +0.0 and -0.0 must be treated as being -distinct values, i.e. -0.0 |not-equal| 0.0. Jansson relies on the -underlying floating point library in the C environment in which it is -compiled. Therefore it is platform-dependent whether 0.0 and -0.0 will -be distinct values. Most platforms that use the IEEE 754 -floating-point standard will support signed zeros. - -Note that this only applies to floating-point; neither JSON, C, or -IEEE support the concept of signed integer zeros. - -.. |not-equal| unicode:: U+2260 - -Types ------ - -No support is provided in Jansson for any C numeric types other than -``json_int_t`` and ``double``. This excludes things such as unsigned -types, ``long double``, etc. Obviously, shorter types like ``short``, -``int``, ``long`` (if ``json_int_t`` is ``long long``) and ``float`` -are implicitly handled via the ordinary C type coercion rules (subject -to overflow semantics). Also, no support or hooks are provided for any -supplemental "bignum" type add-on packages. diff --git a/compat/jansson-2.5/doc/ext/refcounting.py b/compat/jansson-2.5/doc/ext/refcounting.py deleted file mode 100644 index 4af30846..00000000 --- a/compat/jansson-2.5/doc/ext/refcounting.py +++ /dev/null @@ -1,59 +0,0 @@ -""" - refcounting - ~~~~~~~~~~~ - - Reference count annotations for C API functions. Has the same - result as the sphinx.ext.refcounting extension but works for all - functions regardless of the signature, and the reference counting - information is written inline with the documentation instead of a - separate file. - - Adds a new directive "refcounting". The directive has no content - and one required positional parameter:: "new" or "borrow". - - Example: - - .. cfunction:: json_t *json_object(void) - - .. refcounting:: new - - - - :copyright: Copyright (c) 2009-2013 Petri Lehtinen - :license: MIT, see LICENSE for details. -""" - -from docutils import nodes - -class refcounting(nodes.emphasis): pass - -def visit(self, node): - self.visit_emphasis(node) - -def depart(self, node): - self.depart_emphasis(node) - -def html_visit(self, node): - self.body.append(self.starttag(node, 'em', '', CLASS='refcount')) - -def html_depart(self, node): - self.body.append('') - - -def refcounting_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - if arguments[0] == 'borrow': - text = 'Return value: Borrowed reference.' - elif arguments[0] == 'new': - text = 'Return value: New reference.' - else: - raise Error('Valid arguments: new, borrow') - - return [refcounting(text, text)] - -def setup(app): - app.add_node(refcounting, - html=(html_visit, html_depart), - latex=(visit, depart), - text=(visit, depart)) - app.add_directive('refcounting', refcounting_directive, 0, (1, 0, 0)) diff --git a/compat/jansson-2.5/doc/gettingstarted.rst b/compat/jansson-2.5/doc/gettingstarted.rst deleted file mode 100644 index 4e59e519..00000000 --- a/compat/jansson-2.5/doc/gettingstarted.rst +++ /dev/null @@ -1,237 +0,0 @@ -*************** -Getting Started -*************** - -.. highlight:: c - -Compiling and Installing Jansson -================================ - -The Jansson source is available at -http://www.digip.org/jansson/releases/. - -Unix-like systems (including MinGW) ------------------------------------ - -Unpack the source tarball and change to the source directory: - -.. parsed-literal:: - - bunzip2 -c jansson-|release|.tar.bz2 | tar xf - - cd jansson-|release| - -The source uses GNU Autotools (autoconf_, automake_, libtool_), so -compiling and installing is extremely simple:: - - ./configure - make - make check - make install - -To change the destination directory (``/usr/local`` by default), use -the ``--prefix=DIR`` argument to ``./configure``. See ``./configure ---help`` for the list of all possible installation options. (There are -no options to customize the resulting Jansson binary.) - -The command ``make check`` runs the test suite distributed with -Jansson. This step is not strictly necessary, but it may find possible -problems that Jansson has on your platform. If any problems are found, -please report them. - -If you obtained the source from a Git repository (or any other source -control system), there's no ``./configure`` script as it's not kept in -version control. To create the script, the build system needs to be -bootstrapped. There are many ways to do this, but the easiest one is -to use ``autoreconf``:: - - autoreconf -vi - -This command creates the ``./configure`` script, which can then be -used as described above. - -.. _autoconf: http://www.gnu.org/software/autoconf/ -.. _automake: http://www.gnu.org/software/automake/ -.. _libtool: http://www.gnu.org/software/libtool/ - - -.. _build-cmake: - -CMake (various platforms, including Windows) --------------------------------------------- - -Jansson can be built using CMake_. Create a build directory for an -out-of-tree build, change to that directory, and run ``cmake`` (or ``ccmake``, -``cmake-gui``, or similar) to configure the project. - -See the examples below for more detailed information. - -.. note:: In the below examples ``..`` is used as an argument for ``cmake``. - This is simply the path to the jansson project root directory. - In the example it is assumed you've created a sub-directory ``build`` - and are using that. You could use any path you want. - -.. _build-cmake-unix: - -Unix (Make files) -^^^^^^^^^^^^^^^^^ -Generating make files on unix: - -.. parsed-literal:: - - bunzip2 -c jansson-|release|.tar.bz2 | tar xf - - cd jansson-|release| - - mkdir build - cd build - cmake .. # or `ccmake ..` for a GUI. - -Then to build:: - - make - make check - make install - -Windows (Visual Studio) -^^^^^^^^^^^^^^^^^^^^^^^ -Creating Visual Studio project files from the command line: - -.. parsed-literal:: - - - cd jansson-|release| - - md build - cd build - cmake -G "Visual Studio 10" .. - -You will now have a *Visual Studio Solution* in your build directory. -To run the unit tests build the ``RUN_TESTS`` project. - -If you prefer a GUI the ``cmake`` line in the above example can -be replaced with:: - - cmake-gui .. - -For command line help (including a list of available generators) -for CMake_ simply run:: - - cmake - -To list available CMake_ settings (and what they are currently set to) -for the project, run:: - - cmake -LH .. - -Mac OSX (Xcode) -^^^^^^^^^^^^^^^ -If you prefer using Xcode instead of make files on OSX, -do the following. (Use the same steps as -for :ref:`Unix `):: - - ... - cmake -G "Xcode" .. - -Additional CMake settings -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Shared library -"""""""""""""" -By default the CMake_ project will generate build files for building the -static library. To build the shared version use:: - - ... - cmake -DBUILD_SHARED=1 .. - -Changing install directory (same as autoconf --prefix) -"""""""""""""""""""""""""""""""""""""""""""""""""""""" -Just as with the autoconf_ project you can change the destination directory -for ``make install``. The equivalent for autoconfs ``./configure --prefix`` -in CMake_ is:: - - ... - cmake -DCMAKE_INSTALL_PREFIX:PATH=/some/other/path .. - make install - -.. _CMake: http://www.cmake.org - -Android -------- - -Jansson can be built for Android platforms. Android.mk is in the -source root directory. The configuration header file is located in the -``android`` directory in the source distribution. - - -Windows -------- - -**This method is deprecated**. Using :ref:`CMake ` is now -preferred. - -Jansson can be built with Visual Studio 2010 (and probably newer -versions, too). The solution and project files are in the -``win32/vs2010/`` directory in the source distribution. - - -Other Systems -------------- - -On non Unix-like systems, you may be unable to run the ``./configure`` -script. In this case, follow these steps. All the files mentioned can -be found in the ``src/`` directory. - -1. Create ``jansson_config.h`` (which has some platform-specific - parameters that are normally filled in by the ``./configure`` - script). Edit ``jansson_config.h.in``, replacing all ``@variable@`` - placeholders, and rename the file to ``jansson_config.h``. - -2. Make ``jansson.h`` and ``jansson_config.h`` available to the - compiler, so that they can be found when compiling programs that - use Jansson. - -3. Compile all the ``.c`` files (in the ``src/`` directory) into a - library file. Make the library available to the compiler, as in - step 2. - - -Building the Documentation --------------------------- - -(This subsection describes how to build the HTML documentation you are -currently reading, so it can be safely skipped.) - -Documentation is in the ``doc/`` subdirectory. It's written in -reStructuredText_ with Sphinx_ annotations. To generate the HTML -documentation, invoke:: - - make html - -and point your browser to ``doc/_build/html/index.html``. Sphinx_ 1.0 -or newer is required to generate the documentation. - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Sphinx: http://sphinx.pocoo.org/ - - -Compiling Programs that Use Jansson -=================================== - -Jansson involves one C header file, :file:`jansson.h`, so it's enough -to put the line - -:: - - #include - -in the beginning of every source file that uses Jansson. - -There's also just one library to link with, ``libjansson``. Compile and -link the program as follows:: - - cc -o prog prog.c -ljansson - -Starting from version 1.2, there's also support for pkg-config_:: - - cc -o prog prog.c `pkg-config --cflags --libs jansson` - -.. _pkg-config: http://pkg-config.freedesktop.org/ diff --git a/compat/jansson-2.5/doc/github_commits.c b/compat/jansson-2.5/doc/github_commits.c deleted file mode 100644 index 2b39250d..00000000 --- a/compat/jansson-2.5/doc/github_commits.c +++ /dev/null @@ -1,192 +0,0 @@ -/* - * Copyright (c) 2009-2013 Petri Lehtinen - * - * Jansson is free software; you can redistribute it and/or modify - * it under the terms of the MIT license. See LICENSE for details. - */ - -#include -#include - -#include -#include - -#define BUFFER_SIZE (256 * 1024) /* 256 KB */ - -#define URL_FORMAT "https://api.github.com/repos/%s/%s/commits" -#define URL_SIZE 256 - -/* Return the offset of the first newline in text or the length of - text if there's no newline */ -static int newline_offset(const char *text) -{ - const char *newline = strchr(text, '\n'); - if(!newline) - return strlen(text); - else - return (int)(newline - text); -} - -struct write_result -{ - char *data; - int pos; -}; - -static size_t write_response(void *ptr, size_t size, size_t nmemb, void *stream) -{ - struct write_result *result = (struct write_result *)stream; - - if(result->pos + size * nmemb >= BUFFER_SIZE - 1) - { - fprintf(stderr, "error: too small buffer\n"); - return 0; - } - - memcpy(result->data + result->pos, ptr, size * nmemb); - result->pos += size * nmemb; - - return size * nmemb; -} - -static char *request(const char *url) -{ - CURL *curl = NULL; - CURLcode status; - char *data = NULL; - long code; - - curl_global_init(CURL_GLOBAL_ALL); - curl = curl_easy_init(); - if(!curl) - goto error; - - data = malloc(BUFFER_SIZE); - if(!data) - goto error; - - struct write_result write_result = { - .data = data, - .pos = 0 - }; - - curl_easy_setopt(curl, CURLOPT_URL, url); - curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_response); - curl_easy_setopt(curl, CURLOPT_WRITEDATA, &write_result); - - status = curl_easy_perform(curl); - if(status != 0) - { - fprintf(stderr, "error: unable to request data from %s:\n", url); - fprintf(stderr, "%s\n", curl_easy_strerror(status)); - goto error; - } - - curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &code); - if(code != 200) - { - fprintf(stderr, "error: server responded with code %ld\n", code); - goto error; - } - - curl_easy_cleanup(curl); - curl_global_cleanup(); - - /* zero-terminate the result */ - data[write_result.pos] = '\0'; - - return data; - -error: - if(data) - free(data); - if(curl) - curl_easy_cleanup(curl); - curl_global_cleanup(); - return NULL; -} - -int main(int argc, char *argv[]) -{ - size_t i; - char *text; - char url[URL_SIZE]; - - json_t *root; - json_error_t error; - - if(argc != 3) - { - fprintf(stderr, "usage: %s USER REPOSITORY\n\n", argv[0]); - fprintf(stderr, "List commits at USER's REPOSITORY.\n\n"); - return 2; - } - - snprintf(url, URL_SIZE, URL_FORMAT, argv[1], argv[2]); - - text = request(url); - if(!text) - return 1; - - root = json_loads(text, 0, &error); - free(text); - - if(!root) - { - fprintf(stderr, "error: on line %d: %s\n", error.line, error.text); - return 1; - } - - if(!json_is_array(root)) - { - fprintf(stderr, "error: root is not an array\n"); - json_decref(root); - return 1; - } - - for(i = 0; i < json_array_size(root); i++) - { - json_t *data, *sha, *commit, *message; - const char *message_text; - - data = json_array_get(root, i); - if(!json_is_object(data)) - { - fprintf(stderr, "error: commit data %d is not an object\n", (int)(i + 1)); - json_decref(root); - return 1; - } - - sha = json_object_get(data, "sha"); - if(!json_is_string(sha)) - { - fprintf(stderr, "error: commit %d: sha is not a string\n", (int)(i + 1)); - return 1; - } - - commit = json_object_get(data, "commit"); - if(!json_is_object(commit)) - { - fprintf(stderr, "error: commit %d: commit is not an object\n", (int)(i + 1)); - json_decref(root); - return 1; - } - - message = json_object_get(commit, "message"); - if(!json_is_string(message)) - { - fprintf(stderr, "error: commit %d: message is not a string\n", (int)(i + 1)); - json_decref(root); - return 1; - } - - message_text = json_string_value(message); - printf("%.8s %.*s\n", - json_string_value(sha), - newline_offset(message_text), - message_text); - } - - json_decref(root); - return 0; -} diff --git a/compat/jansson-2.5/doc/index.rst b/compat/jansson-2.5/doc/index.rst deleted file mode 100644 index 1f3f8ef7..00000000 --- a/compat/jansson-2.5/doc/index.rst +++ /dev/null @@ -1,53 +0,0 @@ -Jansson Documentation -===================== - -This is the documentation for Jansson_ |release|, last updated |today|. - -Introduction ------------- - -Jansson_ is a C library for encoding, decoding and manipulating JSON -data. Its main features and design principles are: - -- Simple and intuitive API and data model - -- Comprehensive documentation - -- No dependencies on other libraries - -- Full Unicode support (UTF-8) - -- Extensive test suite - -Jansson is licensed under the `MIT license`_; see LICENSE in the -source distribution for details. - -Jansson is used in production and its API is stable. It works on -numerous platforms, including numerous Unix like systems and Windows. -It's suitable for use on any system, including desktop, server, and -small embedded systems. - - -.. _`MIT license`: http://www.opensource.org/licenses/mit-license.php -.. _Jansson: http://www.digip.org/jansson/ - -Contents --------- - -.. toctree:: - :maxdepth: 2 - - gettingstarted - upgrading - tutorial - conformance - portability - apiref - changes - - -Indices and Tables -================== - -* :ref:`genindex` -* :ref:`search` diff --git a/compat/jansson-2.5/doc/portability.rst b/compat/jansson-2.5/doc/portability.rst deleted file mode 100644 index dc6c5eb5..00000000 --- a/compat/jansson-2.5/doc/portability.rst +++ /dev/null @@ -1,52 +0,0 @@ -*********** -Portability -*********** - -Thread safety -------------- - -Jansson is thread safe and has no mutable global state. The only -exception are the memory allocation functions, that should be set at -most once, and only on program startup. See -:ref:`apiref-custom-memory-allocation`. - -There's no locking performed inside Jansson's code, so a multithreaded -program must perform its own locking if JSON values are shared by -multiple threads. Jansson's reference counting semantics may make this -a bit harder than it seems, as it's possible to have a reference to a -value that's also stored inside a list or object. Modifying the -container (adding or removing values) may trigger concurrent access to -such values, as containers manage the reference count of their -contained values. Bugs involving concurrent incrementing or -decrementing of deference counts may be hard to track. - -The encoding functions (:func:`json_dumps()` and friends) track -reference loops by modifying the internal state of objects and arrays. -For this reason, encoding functions must not be run on the same JSON -values in two separate threads at the same time. As already noted -above, be especially careful if two arrays or objects share their -contained values with another array or object. - -If you want to make sure that two JSON value hierarchies do not -contain shared values, use :func:`json_deep_copy()` to make copies. - -Locale ------- - -Jansson works fine under any locale. - -However, if the host program is multithreaded and uses ``setlocale()`` -to switch the locale in one thread while Jansson is currently encoding -or decoding JSON data in another thread, the result may be wrong or -the program may even crash. - -Jansson uses locale specific functions for certain string conversions -in the encoder and decoder, and then converts the locale specific -values to/from the JSON representation. This fails if the locale -changes between the string conversion and the locale-to-JSON -conversion. This can only happen in multithreaded programs that use -``setlocale()``, because ``setlocale()`` switches the locale for all -running threads, not only the thread that calls ``setlocale()``. - -If your program uses ``setlocale()`` as described above, consider -using the thread-safe ``uselocale()`` instead. diff --git a/compat/jansson-2.5/doc/tutorial.rst b/compat/jansson-2.5/doc/tutorial.rst deleted file mode 100644 index c2df081c..00000000 --- a/compat/jansson-2.5/doc/tutorial.rst +++ /dev/null @@ -1,286 +0,0 @@ -.. _tutorial: - -******** -Tutorial -******** - -.. highlight:: c - -In this tutorial, we create a program that fetches the latest commits -of a repository in GitHub_ over the web. `GitHub API`_ uses JSON, so -the result can be parsed using Jansson. - -To stick to the the scope of this tutorial, we will only cover the the -parts of the program related to handling JSON data. For the best user -experience, the full source code is available: -:download:`github_commits.c`. To compile it (on Unix-like systems with -gcc), use the following command:: - - gcc -o github_commits github_commits.c -ljansson -lcurl - -libcurl_ is used to communicate over the web, so it is required to -compile the program. - -The command line syntax is:: - - github_commits USER REPOSITORY - -``USER`` is a GitHub user ID and ``REPOSITORY`` is the repository -name. Please note that the GitHub API is rate limited, so if you run -the program too many times within a short period of time, the sever -starts to respond with an error. - -.. _GitHub: https://github.com/ -.. _GitHub API: http://developer.github.com/ -.. _libcurl: http://curl.haxx.se/ - - -.. _tutorial-github-commits-api: - -The GitHub Repo Commits API -=========================== - -The `GitHub Repo Commits API`_ is used by sending HTTP requests to -URLs like ``https://api.github.com/repos/USER/REPOSITORY/commits``, -where ``USER`` and ``REPOSITORY`` are the GitHub user ID and the name -of the repository whose commits are to be listed, respectively. - -GitHub responds with a JSON array of the following form: - -.. code-block:: none - - [ - { - "sha": "", - "commit": { - "message": "", - - }, - - }, - { - "sha": "", - "commit": { - "message": "", - - }, - - }, - - ] - -In our program, the HTTP request is sent using the following -function:: - - static char *request(const char *url); - -It takes the URL as a parameter, preforms a HTTP GET request, and -returns a newly allocated string that contains the response body. If -the request fails, an error message is printed to stderr and the -return value is *NULL*. For full details, refer to :download:`the code -`, as the actual implementation is not important -here. - -.. _GitHub Repo Commits API: http://developer.github.com/v3/repos/commits/ - -.. _tutorial-the-program: - -The Program -=========== - -First the includes:: - - #include - #include - -Like all the programs using Jansson, we need to include -:file:`jansson.h`. - -The following definitions are used to build the GitHub API request -URL:: - - #define URL_FORMAT "https://api.github.com/repos/%s/%s/commits" - #define URL_SIZE 256 - -The following function is used when formatting the result to find the -first newline in the commit message:: - - /* Return the offset of the first newline in text or the length of - text if there's no newline */ - static int newline_offset(const char *text) - { - const char *newline = strchr(text, '\n'); - if(!newline) - return strlen(text); - else - return (int)(newline - text); - } - -The main function follows. In the beginning, we first declare a bunch -of variables and check the command line parameters:: - - int main(int argc, char *argv[]) - { - size_t i; - char *text; - char url[URL_SIZE]; - - json_t *root; - json_error_t error; - - if(argc != 3) - { - fprintf(stderr, "usage: %s USER REPOSITORY\n\n", argv[0]); - fprintf(stderr, "List commits at USER's REPOSITORY.\n\n"); - return 2; - } - -Then we build the request URL using the user and repository names -given as command line parameters:: - - snprintf(url, URL_SIZE, URL_FORMAT, argv[1], argv[2]); - -This uses the ``URL_SIZE`` and ``URL_FORMAT`` constants defined above. -Now we're ready to actually request the JSON data over the web:: - - text = request(url); - if(!text) - return 1; - -If an error occurs, our function ``request`` prints the error and -returns *NULL*, so it's enough to just return 1 from the main -function. - -Next we'll call :func:`json_loads()` to decode the JSON text we got -as a response:: - - root = json_loads(text, 0, &error); - free(text); - - if(!root) - { - fprintf(stderr, "error: on line %d: %s\n", error.line, error.text); - return 1; - } - -We don't need the JSON text anymore, so we can free the ``text`` -variable right after decoding it. If :func:`json_loads()` fails, it -returns *NULL* and sets error information to the :type:`json_error_t` -structure given as the second parameter. In this case, our program -prints the error information out and returns 1 from the main function. - -Now we're ready to extract the data out of the decoded JSON response. -The structure of the response JSON was explained in section -:ref:`tutorial-github-commits-api`. - -We check that the returned value really is an array:: - - if(!json_is_array(root)) - { - fprintf(stderr, "error: root is not an array\n"); - json_decref(root); - return 1; - } - -Then we proceed to loop over all the commits in the array:: - - for(i = 0; i < json_array_size(root); i++) - { - json_t *data, *sha, *commit, *message; - const char *message_text; - - data = json_array_get(root, i); - if(!json_is_object(data)) - { - fprintf(stderr, "error: commit data %d is not an object\n", i + 1); - json_decref(root); - return 1; - } - ... - -The function :func:`json_array_size()` returns the size of a JSON -array. First, we again declare some variables and then extract the -i'th element of the ``root`` array using :func:`json_array_get()`. -We also check that the resulting value is a JSON object. - -Next we'll extract the commit ID (a hexadecimal SHA-1 sum), -intermediate commit info object, and the commit message from that -object. We also do proper type checks:: - - sha = json_object_get(data, "sha"); - if(!json_is_string(sha)) - { - fprintf(stderr, "error: commit %d: sha is not a string\n", i + 1); - json_decref(root); - return 1; - } - - commit = json_object_get(data, "commit"); - if(!json_is_object(commit)) - { - fprintf(stderr, "error: commit %d: commit is not an object\n", i + 1); - json_decref(root); - return 1; - } - - message = json_object_get(commit, "message"); - if(!json_is_string(message)) - { - fprintf(stderr, "error: commit %d: message is not a string\n", i + 1); - json_decref(root); - return 1; - } - ... - -And finally, we'll print the first 8 characters of the commit ID and -the first line of the commit message. A C-style string is extracted -from a JSON string using :func:`json_string_value()`:: - - message_text = json_string_value(message); - printf("%.8s %.*s\n", - json_string_value(id), - newline_offset(message_text), - message_text); - } - -After sending the HTTP request, we decoded the JSON text using -:func:`json_loads()`, remember? It returns a *new reference* to the -JSON value it decodes. When we're finished with the value, we'll need -to decrease the reference count using :func:`json_decref()`. This way -Jansson can release the resources:: - - json_decref(root); - return 0; - -For a detailed explanation of reference counting in Jansson, see -:ref:`apiref-reference-count` in :ref:`apiref`. - -The program's ready, let's test it and view the latest commits in -Jansson's repository:: - - $ ./github_commits akheron jansson - 1581f26a Merge branch '2.3' - aabfd493 load: Change buffer_pos to be a size_t - bd72efbd load: Avoid unexpected behaviour in macro expansion - e8fd3e30 Document and tweak json_load_callback() - 873eddaf Merge pull request #60 from rogerz/contrib - bd2c0c73 Ignore the binary test_load_callback - 17a51a4b Merge branch '2.3' - 09c39adc Add json_load_callback to the list of exported symbols - cbb80baf Merge pull request #57 from rogerz/contrib - 040bd7b0 Add json_load_callback() - 2637faa4 Make test stripping locale independent - <...> - - -Conclusion -========== - -In this tutorial, we implemented a program that fetches the latest -commits of a GitHub repository using the GitHub Repo Commits API. -Jansson was used to decode the JSON response and to extract the commit -data. - -This tutorial only covered a small part of Jansson. For example, we -did not create or manipulate JSON values at all. Proceed to -:ref:`apiref` to explore all features of Jansson. diff --git a/compat/jansson-2.5/doc/upgrading.rst b/compat/jansson-2.5/doc/upgrading.rst deleted file mode 100644 index 9b490461..00000000 --- a/compat/jansson-2.5/doc/upgrading.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. highlight:: c - -****************** -Upgrading from 1.x -****************** - -This chapter lists the backwards incompatible changes introduced in -Jansson 2.0, and the steps that are needed for upgrading your code. - -**The incompatibilities are not dramatic.** The biggest change is that -all decoding functions now require and extra parameter. Most programs -can be modified to work with 2.0 by adding a ``0`` as the second -parameter to all calls of :func:`json_loads()`, :func:`json_loadf()` -and :func:`json_load_file()`. - - -Compatibility -============= - -Jansson 2.0 is backwards incompatible with the Jansson 1.x releases. -It is ABI incompatible, i.e. all programs dynamically linking to the -Jansson library need to be recompiled. It's also API incompatible, -i.e. the source code of programs using Jansson 1.x may need -modifications to make them compile against Jansson 2.0. - -All the 2.x releases are guaranteed to be backwards compatible for -both ABI and API, so no recompilation or source changes are needed -when upgrading from 2.x to 2.y. - - -List of Incompatible Changes -============================ - -**Decoding flags** - For future needs, a ``flags`` parameter was added as the second - parameter to all decoding functions, i.e. :func:`json_loads()`, - :func:`json_loadf()` and :func:`json_load_file()`. All calls to - these functions need to be changed by adding a ``0`` as the second - argument. For example:: - - /* old code */ - json_loads(input, &error); - - /* new code */ - json_loads(input, 0, &error); - - -**Underlying type of JSON integers** - The underlying C type of JSON integers has been changed from - :type:`int` to the widest available signed integer type, i.e. - :type:`long long` or :type:`long`, depending on whether - :type:`long long` is supported on your system or not. This makes - the whole 64-bit integer range available on most modern systems. - - ``jansson.h`` has a typedef :type:`json_int_t` to the underlying - integer type. :type:`int` should still be used in most cases when - dealing with smallish JSON integers, as the compiler handles - implicit type coercion. Only when the full 64-bit range is needed, - :type:`json_int_t` should be explicitly used. - - -**Maximum encoder indentation depth** - The maximum argument of the ``JSON_INDENT()`` macro has been - changed from 255 to 31, to free up bits from the ``flags`` - parameter of :func:`json_dumps()`, :func:`json_dumpf()` and - :func:`json_dump_file()`. If your code uses a bigger indentation - than 31, it needs to be changed. - - -**Unsigned integers in API functions** - Version 2.0 unifies unsigned integer usage in the API. All uses of - :type:`unsigned int` and :type:`unsigned long` have been replaced - with :type:`size_t`. This includes flags, container sizes, etc. - This should not require source code changes, as both - :type:`unsigned int` and :type:`unsigned long` are usually - compatible with :type:`size_t`. diff --git a/compat/jansson-2.5/win32/jansson_config.h b/compat/jansson-2.5/win32/jansson_config.h deleted file mode 100644 index ab1da5dd..00000000 --- a/compat/jansson-2.5/win32/jansson_config.h +++ /dev/null @@ -1,39 +0,0 @@ -/* - * Copyright (c) 2010-2013 Petri Lehtinen - * - * Jansson is free software; you can redistribute it and/or modify - * it under the terms of the MIT license. See LICENSE for details. - * - * - * This file specifies a part of the site-specific configuration for - * Jansson, namely those things that affect the public API in - * jansson.h. - * - * The configure script copies this file to jansson_config.h and - * replaces @var@ substitutions by values that fit your system. If you - * cannot run the configure script, you can do the value substitution - * by hand. - */ - -#ifndef JANSSON_CONFIG_H -#define JANSSON_CONFIG_H - -/* If your compiler supports the inline keyword in C, JSON_INLINE is - defined to `inline', otherwise empty. In C++, the inline is always - supported. */ -#ifdef __cplusplus -#define JSON_INLINE inline -#else -#define JSON_INLINE __inline -#endif - -/* If your compiler supports the `long long` type and the strtoll() - library function, JSON_INTEGER_IS_LONG_LONG is defined to 1, - otherwise to 0. */ -#define JSON_INTEGER_IS_LONG_LONG 1 - -/* If locale.h and localeconv() are available, define to 1, - otherwise to 0. */ -#define JSON_HAVE_LOCALECONV 1 - -#endif diff --git a/compat/jansson-2.5/win32/vs2010/jansson.sln b/compat/jansson-2.5/win32/vs2010/jansson.sln deleted file mode 100644 index 58f911ba..00000000 --- a/compat/jansson-2.5/win32/vs2010/jansson.sln +++ /dev/null @@ -1,20 +0,0 @@ - -Microsoft Visual Studio Solution File, Format Version 11.00 -# Visual C++ Express 2010 -Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "jansson", "jansson.vcxproj", "{76226D20-1972-4789-A595-EDACC7A76DC3}" -EndProject -Global - GlobalSection(SolutionConfigurationPlatforms) = preSolution - Debug|Win32 = Debug|Win32 - Release|Win32 = Release|Win32 - EndGlobalSection - GlobalSection(ProjectConfigurationPlatforms) = postSolution - {76226D20-1972-4789-A595-EDACC7A76DC3}.Debug|Win32.ActiveCfg = Debug|Win32 - {76226D20-1972-4789-A595-EDACC7A76DC3}.Debug|Win32.Build.0 = Debug|Win32 - {76226D20-1972-4789-A595-EDACC7A76DC3}.Release|Win32.ActiveCfg = Release|Win32 - {76226D20-1972-4789-A595-EDACC7A76DC3}.Release|Win32.Build.0 = Release|Win32 - EndGlobalSection - GlobalSection(SolutionProperties) = preSolution - HideSolutionNode = FALSE - EndGlobalSection -EndGlobal diff --git a/compat/jansson-2.5/win32/vs2010/jansson.vcxproj b/compat/jansson-2.5/win32/vs2010/jansson.vcxproj deleted file mode 100644 index d5b2a879..00000000 --- a/compat/jansson-2.5/win32/vs2010/jansson.vcxproj +++ /dev/null @@ -1,108 +0,0 @@ - - - - - Debug - Win32 - - - Release - Win32 - - - - - - - - - - - - - - - - - - - - - - - - {76226D20-1972-4789-A595-EDACC7A76DC3} - Win32Proj - jansson_dll - jansson - - - - DynamicLibrary - true - Unicode - - - DynamicLibrary - false - true - Unicode - - - - - - - - - - - - - true - Output\$(Configuration)\ - Build\$(Configuration)\ - - - false - Output\$(Configuration)\ - Build\$(Configuration)\ - - - - NotUsing - Level3 - Disabled - WIN32;_DEBUG;_WINDOWS;_USRDLL;JANSSON_DLL_EXPORTS;%(PreprocessorDefinitions) - .. - 4996 - - - Windows - true - ../../src/jansson.def - - - - - Level3 - NotUsing - MaxSpeed - true - true - WIN32;NDEBUG;_WINDOWS;_USRDLL;JANSSON_DLL_EXPORTS;%(PreprocessorDefinitions) - .. - 4996 - - - Windows - true - true - true - ../../src/jansson.def - - - - - - \ No newline at end of file diff --git a/compat/jansson-2.5/win32/vs2010/jansson.vcxproj.filters b/compat/jansson-2.5/win32/vs2010/jansson.vcxproj.filters deleted file mode 100644 index f8eee304..00000000 --- a/compat/jansson-2.5/win32/vs2010/jansson.vcxproj.filters +++ /dev/null @@ -1,69 +0,0 @@ - - - - - {4FC737F1-C7A5-4376-A066-2A32D752A2FF} - cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx - - - {93995380-89BD-4b04-88EB-625FBE52EBFB} - h;hpp;hxx;hm;inl;inc;xsd - - - {67DA6AB6-F800-4c08-8B7A-83BB121AAD01} - rc;ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe;resx;tiff;tif;png;wav;mfcribbon-ms - - - - - Source Files - - - Source Files - - - Source Files - - - Source Files - - - Source Files - - - Source Files - - - Source Files - - - Source Files - - - Source Files - - - Source Files - - - - - Header Files - - - Header Files - - - Header Files - - - Header Files - - - Header Files - - - Header Files - - - \ No newline at end of file diff --git a/compat/jansson-2.5/win32/vs2010/jansson.vcxproj.user b/compat/jansson-2.5/win32/vs2010/jansson.vcxproj.user deleted file mode 100644 index ace9a86a..00000000 --- a/compat/jansson-2.5/win32/vs2010/jansson.vcxproj.user +++ /dev/null @@ -1,3 +0,0 @@ - - - \ No newline at end of file