From b5f8ee61a7f7e9bd291dd26b0585d03eb686c941 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 5 May 2024 13:19:16 +0200 Subject: Adding upstream version 1.46.3. Signed-off-by: Daniel Baumann --- fluent-bit/lib/jansson-e23f558/doc/.gitignore | 1 - fluent-bit/lib/jansson-e23f558/doc/Makefile.am | 20 - fluent-bit/lib/jansson-e23f558/doc/README | 5 - fluent-bit/lib/jansson-e23f558/doc/apiref.rst | 2064 -------------------- fluent-bit/lib/jansson-e23f558/doc/changes.rst | 5 - fluent-bit/lib/jansson-e23f558/doc/conf.py | 217 -- fluent-bit/lib/jansson-e23f558/doc/conformance.rst | 119 -- .../lib/jansson-e23f558/doc/ext/refcounting.py | 69 - .../lib/jansson-e23f558/doc/gettingstarted.rst | 264 --- .../lib/jansson-e23f558/doc/github_commits.c | 181 -- fluent-bit/lib/jansson-e23f558/doc/index.rst | 53 - .../lib/jansson-e23f558/doc/threadsafety.rst | 82 - fluent-bit/lib/jansson-e23f558/doc/tutorial.rst | 288 --- fluent-bit/lib/jansson-e23f558/doc/upgrading.rst | 76 - 14 files changed, 3444 deletions(-) delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/.gitignore delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/Makefile.am delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/README delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/apiref.rst delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/changes.rst delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/conf.py delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/conformance.rst delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/ext/refcounting.py delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/gettingstarted.rst delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/github_commits.c delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/index.rst delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/threadsafety.rst delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/tutorial.rst delete mode 100644 fluent-bit/lib/jansson-e23f558/doc/upgrading.rst (limited to 'fluent-bit/lib/jansson-e23f558/doc') diff --git a/fluent-bit/lib/jansson-e23f558/doc/.gitignore b/fluent-bit/lib/jansson-e23f558/doc/.gitignore deleted file mode 100644 index 69fa449dd..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_build/ diff --git a/fluent-bit/lib/jansson-e23f558/doc/Makefile.am b/fluent-bit/lib/jansson-e23f558/doc/Makefile.am deleted file mode 100644 index 8186a7db8..000000000 --- a/fluent-bit/lib/jansson-e23f558/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 threadsafety.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/fluent-bit/lib/jansson-e23f558/doc/README b/fluent-bit/lib/jansson-e23f558/doc/README deleted file mode 100644 index 930b3bf0c..000000000 --- a/fluent-bit/lib/jansson-e23f558/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/fluent-bit/lib/jansson-e23f558/doc/apiref.rst b/fluent-bit/lib/jansson-e23f558/doc/apiref.rst deleted file mode 100644 index 4bfb68799..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/apiref.rst +++ /dev/null @@ -1,2064 +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 comparisons, e.g.:: - - #if JANSSON_VERSION_HEX >= 0x010300 - /* Code specific to version 1.3 and above */ - #endif - -Additionally, there are functions to determine the version of Jansson at -runtime: - -.. function:: const char *jansson_version_str() - - Return the version of the Jansson library, in the same format as - the ``JANSSON_VERSION`` preprocessor constant. - - .. versionadded:: 2.13 - -.. function:: int jansson_version_cmp(int major, int minor, int micro) - - Returns an integer less than, equal to, or greater than zero if - the runtime version of Jansson is found, respectively, to be less - than, to match, or be greater than the provided *major*, *minor*, and - *micro*. - - .. versionadded:: 2.13 - -``JANSSON_THREAD_SAFE_REFCOUNT`` - If this value is defined all read-only operations and reference counting in - Jansson are thread safe. This value is not defined for versions older than - ``2.11`` or when the compiler does not provide built-in atomic functions. - - -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 ----- - -.. c: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 - ``int``). *json* MUST NOT be *NULL*. This function is actually - implemented as a macro for speed. - -.. function:: int json_is_object(const json_t *json) - int json_is_array(const json_t *json) - int json_is_string(const json_t *json) - int json_is_integer(const json_t *json) - int json_is_real(const json_t *json) - int json_is_true(const json_t *json) - int json_is_false(const json_t *json) - int 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:: int 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:: int 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*. - -.. function:: int json_boolean_value(const json_t *json) - - Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE`` - and 0 otherwise. - - .. versionadded:: 2.7 - - -.. _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. - -.. 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. - -Scope Dereferencing -------------------- - -.. versionadded:: 2.9 - -It is possible to use the ``json_auto_t`` type to automatically -dereference a value at the end of a scope. For example:: - - void function(void) { - json_auto_t *value = NULL; - value = json_string("foo"); - /* json_decref(value) is automatically called. */ - } - -This feature is only available on GCC and Clang. So if your project -has a portability requirement for other compilers, you should avoid -this feature. - -Additionally, as always, care should be taken when passing values to -functions that steal references. - -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). All Unicode -codepoints U+0000 through U+10FFFF are allowed, but you must use -length-aware functions if you wish to embed null bytes in strings. - -.. function:: json_t *json_string(const char *value) - - .. refcounting:: new - - Returns a new JSON string, or *NULL* on error. *value* must be a - valid null terminated UTF-8 encoded Unicode string. - -.. function:: json_t *json_stringn(const char *value, size_t len) - - .. refcounting:: new - - Like :func:`json_string`, but with explicit length, so *value* may - contain null characters or not be null terminated. - - .. versionadded:: 2.7 - -.. 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:: json_t *json_stringn_nocheck(const char *value, size_t len) - - .. refcounting:: new - - Like :func:`json_string_nocheck`, but with explicit length, so - *value* may contain null characters or not be null terminated. - - .. versionadded:: 2.7 - -.. 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 returned 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:: size_t json_string_length(const json_t *string) - - Returns the length of *string* in its UTF-8 presentation, or zero - if *string* is not a JSON string. - - .. versionadded:: 2.7 - -.. function:: int json_string_set(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_setn(json_t *string, const char *value, size_t len) - - Like :func:`json_string_set`, but with explicit length, so *value* - may contain null characters or not be null terminated. - - .. versionadded:: 2.7 - -.. function:: int json_string_set_nocheck(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). - -.. function:: int json_string_setn_nocheck(json_t *string, const char *value, size_t len) - - Like :func:`json_string_set_nocheck`, but with explicit length, - so *value* may contain null characters or not be null terminated. - - .. versionadded:: 2.7 - -.. function:: json_t *json_sprintf(const char *format, ...) - json_t *json_vsprintf(const char *format, va_list ap) - - .. refcounting:: new - - Construct a JSON string from a format string and varargs, just like - :func:`printf()`. - - .. versionadded:: 2.11 - - -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()` requires - 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. - -.. 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 success 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. - -.. function:: void 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` pointer 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 more concise and readable 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. - -Even though null bytes are allowed in string values, they are not -allowed in object keys. - -.. 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:: json_t *json_object_getn(const json_t *object, const char *key, size_t key_len) - - .. refcounting:: borrow - - Like :func:`json_object_get`, but give the fixed-length *key* with length *key_len*. - See :ref:`fixed_length_keys` for details. - - .. versionadded:: 2.14 - -.. 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_setn(json_t *object, const char *key, size_t key_len, json_t *value) - - Like :func:`json_object_set`, but give the fixed-length *key* with length *key_len*. - See :ref:`fixed_length_keys` for details. - - .. versionadded:: 2.14 - -.. 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_setn_nocheck(json_t *object, const char *key, size_t key_len, json_t *value) - - Like :func:`json_object_set_nocheck`, but give the fixed-length *key* with length *key_len*. - See :ref:`fixed_length_keys` for details. - - .. versionadded:: 2.14 - -.. 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_setn_new(json_t *object, const char *key, size_t key_len, json_t *value) - - Like :func:`json_object_set_new`, but give the fixed-length *key* with length *key_len*. - See :ref:`fixed_length_keys` for details. - - .. versionadded:: 2.14 - -.. 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_setn_new_nocheck(json_t *object, const char *key, size_t key_len, json_t *value) - - Like :func:`json_object_set_new_nocheck`, but give the fixed-length *key* with length *key_len*. - See :ref:`fixed_length_keys` for details. - - .. versionadded:: 2.14 - -.. 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_deln(json_t *object, const char *key, size_t key_len) - - Like :func:`json_object_del`, but give the fixed-length *key* with length *key_len*. - See :ref:`fixed_length_keys` for details. - - .. versionadded:: 2.14 - -.. 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 - -.. function:: int json_object_update_new(json_t *object, json_t *other) - - Like :func:`json_object_update()`, but steals the reference to - *other*. This is useful when *other* is newly created and not used - after the call. - -.. function:: int json_object_update_existing_new(json_t *object, json_t *other) - - Like :func:`json_object_update_new()`, but only the values of existing - keys are updated. No new keys are created. Returns 0 on success or - -1 on error. - -.. function:: int json_object_update_missing_new(json_t *object, json_t *other) - - Like :func:`json_object_update_new()`, but only new keys are created. - The value of any existing key is not changed. Returns 0 on success - or -1 on error. - -.. function:: int json_object_update_recursive(json_t *object, json_t *other) - - Like :func:`json_object_update()`, but object values in *other* are - recursively merged with the corresponding values in *object* if they are also - objects, instead of overwriting them. Returns 0 on success or -1 on error. - -.. function:: void 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 ``const char *`` and - :type:`json_t` pointer 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 returned in the order they were inserted to the - object. - - **Note:** It's not safe to call ``json_object_del(object, key)`` or ``json_object_deln(object, key, key_len)`` - during iteration. If you need to, use - :func:`json_object_foreach_safe` instead. - - 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 more concise and - readable code. - - .. versionadded:: 2.3 - - -.. function:: void json_object_foreach_safe(object, tmp, key, value) - - Like :func:`json_object_foreach()`, but it's safe to call - ``json_object_del(object, key)`` or ``json_object_deln(object, key, key_len)`` during iteration. - You need to pass an extra ``void *`` parameter ``tmp`` that is used for temporary storage. - - .. versionadded:: 2.8 - -.. function:: void json_object_keylen_foreach(object, key, key_len, value) - - Like :c:func:`json_object_foreach`, but in *key_len* stored length of the *key*. - Example:: - - /* obj is a JSON object */ - const char *key; - json_t *value; - size_t len; - - json_object_keylen_foreach(obj, key, len, value) { - printf("got key %s with length %zu\n", key, len); - } - - **Note:** It's not safe to call ``json_object_deln(object, key, key_len)`` - during iteration. If you need to, use - :func:`json_object_keylen_foreach_safe` instead. - - .. versionadded:: 2.14 - - -.. function:: void json_object_keylen_foreach_safe(object, tmp, key, key_len, value) - - Like :func:`json_object_keylen_foreach()`, but it's safe to call - ``json_object_deln(object, key, key_len)`` during iteration. - You need to pass an extra ``void *`` parameter ``tmp`` that is used for temporary storage. - - .. versionadded:: 2.14 - -The following functions can be used to iterate through all key-value -pairs in an object. The items are returned in the order they were -inserted to the object. - -.. 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:: size_t json_object_iter_key_len(void *iter) - - Extract the associated key length from *iter*. - - .. versionadded:: 2.14 - -.. 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`. Example:: - - /* 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); - } - - .. versionadded:: 2.3 - -.. function:: void json_object_seed(size_t seed) - - Seed the hash function used in Jansson's hashtable implementation. - The seed is used to randomize the hash function so that an - attacker cannot control its output. - - If *seed* is 0, Jansson generates the seed itself by reading - random data from the operating system's entropy sources. If no - entropy sources are available, falls back to using a combination - of the current timestamp (with microsecond precision if possible) - and the process ID. - - If called at all, this function must be called before any calls to - :func:`json_object()`, either explicit or implicit. If this - function is not called by the user, the first call to - :func:`json_object()` (either explicit or implicit) seeds the hash - function. See :ref:`thread-safety` for notes on thread safety. - - If repeatable results are required, for e.g. unit tests, the hash - function can be "unrandomized" by calling :func:`json_object_seed` - with a constant value on program startup, e.g. - ``json_object_seed(1)``. - - .. versionadded:: 2.6 - - -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. - - The last byte of this array contains a numeric error code. Use - :func:`json_error_code()` to extract this code. - - .. member:: char source[] - - Source of the error. This can be (a part of) the file name or a - special identifier in angle brackets (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:: int 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. - -.. c:enum:: json_error_code - - An enumeration containing numeric error codes. The following errors are - currently defined: - - ``json_error_unknown`` - - Unknown error. This should only be returned for non-errorneous - :type:`json_error_t` structures. - - ``json_error_out_of_memory`` - - The library couldn’t allocate any heap memory. - - ``json_error_stack_overflow`` - - Nesting too deep. - - ``json_error_cannot_open_file`` - - Couldn’t open input file. - - ``json_error_invalid_argument`` - - A function argument was invalid. - - ``json_error_invalid_utf8`` - - The input string isn’t valid UTF-8. - - ``json_error_premature_end_of_input`` - - The input ended in the middle of a JSON value. - - ``json_error_end_of_input_expected`` - - There was some text after the end of a JSON value. See the - ``JSON_DISABLE_EOF_CHECK`` flag. - - ``json_error_invalid_syntax`` - - JSON syntax error. - - ``json_error_invalid_format`` - - Invalid format string for packing or unpacking. - - ``json_error_wrong_type`` - - When packing or unpacking, the actual type of a value differed from the - one specified in the format string. - - ``json_error_null_character`` - - A null character was detected in a JSON string. See the - ``JSON_ALLOW_NUL`` flag. - - ``json_error_null_value`` - - When packing or unpacking, some key or value was ``NULL``. - - ``json_error_null_byte_in_key`` - - An object key would contain a null byte. Jansson can’t represent such - keys; see :ref:`rfc-conformance`. - - ``json_error_duplicate_key`` - - Duplicate key in object. See the ``JSON_REJECT_DUPLICATES`` flag. - - ``json_error_numeric_overflow`` - - When converting a JSON number to a C numeric type, a numeric overflow - was detected. - - ``json_error_item_not_found`` - - Key in object not found. - - ``json_error_index_out_of_range`` - - Array index is out of range. - - .. versionadded:: 2.11 - -.. function:: enum json_error_code json_error_code(const json_error_t *error) - - Returns the error code embedded in ``error->text``. - - .. versionadded:: 2.11 - - -Encoding -======== - -This section 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. - - The ``JSON_MAX_INDENT`` constant defines the maximum indentation - that can be used, and its value is 31. - - .. versionchanged:: 2.7 - Added ``JSON_MAX_INDENT``. - -``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 achieved 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`` - **Deprecated since version 2.8:** Order of object keys - is always preserved. - - Prior to version 2.8: 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 - *json* value to the encoding functions. - - **Note:** Encoding any value may be useful in some scenarios, but - it's generally discouraged as it violates strict compatibility with - :rfc:`4627`. If you use this flag, don't expect interoperability - with other JSON systems. - - .. versionadded:: 2.1 - -``JSON_ESCAPE_SLASH`` - Escape the ``/`` characters in strings with ``\/``. - - .. versionadded:: 2.4 - -``JSON_REAL_PRECISION(n)`` - Output all real numbers with at most *n* digits of precision. The - valid range for *n* is between 0 and 31 (inclusive), and other - values result in an undefined behavior. - - By default, the precision is 17, to correctly and losslessly encode - all IEEE 754 double precision floating point numbers. - - .. versionadded:: 2.7 - -``JSON_EMBED`` - If this flag is used, the opening and closing characters of the top-level - array ('[', ']') or object ('{', '}') are omitted during encoding. This - flag is useful when concatenating multiple arrays or objects into a stream. - - .. versionadded:: 2.10 - -These functions output UTF-8: - -.. function:: char *json_dumps(const json_t *json, size_t flags) - - Returns the JSON representation of *json* as a string, or *NULL* on - error. *flags* is described above. The return value must be freed - by the caller using :func:`free()`. Note that if you have called - :func:`json_set_alloc_funcs()` to override :func:`free()`, you should - call your custom free function instead to free the return value. - -.. function:: size_t json_dumpb(const json_t *json, char *buffer, size_t size, size_t flags) - - Writes the JSON representation of *json* to the *buffer* of - *size* bytes. Returns the number of bytes that would be written - or 0 on error. *flags* is described above. *buffer* is not - null-terminated. - - This function never writes more than *size* bytes. If the return - value is greater than *size*, the contents of the *buffer* are - undefined. This behavior enables you to specify a NULL *buffer* - to determine the length of the encoding. For example:: - - size_t size = json_dumpb(json, NULL, 0, 0); - if (size == 0) - return -1; - - char *buf = alloca(size); - - size = json_dumpb(json, buf, size, 0); - - .. versionadded:: 2.10 - -.. function:: int json_dumpf(const json_t *json, FILE *output, size_t flags) - - Write the JSON representation of *json* 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_dumpfd(const json_t *json, int output, size_t flags) - - Write the JSON representation of *json* 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. - - It is important to note that this function can only succeed on stream - file descriptors (such as SOCK_STREAM). Using this function on a - non-stream file descriptor will result in undefined behavior. For - non-stream file descriptors, see instead :func:`json_dumpb()`. - - This function requires POSIX and fails on all non-POSIX systems. - - .. versionadded:: 2.10 - -.. function:: int json_dump_file(const json_t *json, const char *path, size_t flags) - - Write the JSON representation of *json* 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. - - *buffer* is guaranteed to be a valid UTF-8 string (i.e. multi-byte - code unit sequences are preserved). *buffer* never contains - embedded null bytes. - - 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 *json* each time. *flags* is described above. - Returns 0 on success and -1 on error. - - .. versionadded:: 2.2 - - -.. _apiref-decoding: - -Decoding -======== - -This section 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 - occurrence 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 compatibility with - :rfc:`4627`. If you use this flag, don't expect interoperability - 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 - -``JSON_ALLOW_NUL`` - Allow ``\u0000`` escape inside string values. This is a safety - measure; If you know your input can contain null bytes, use this - flag. If you don't use this flag, you don't have to worry about null - bytes inside strings unless you explicitly create themselves by - using e.g. :func:`json_stringn()` or ``s#`` format specifier for - :func:`json_pack()`. - - Object keys cannot have embedded null bytes even if this flag is - used. - - .. versionadded:: 2.6 - -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*. - -.. 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 in, 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_loadfd(int 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 descriptor was in, 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 - descriptor's position will be at the first character after the last - ``]`` or ``}`` in the JSON input. This allows calling - :func:`json_loadfd()` on the same file descriptor multiple times, - if the input consists of consecutive JSON texts, possibly separated - by whitespace. - - It is important to note that this function can only succeed on stream - file descriptors (such as SOCK_STREAM). Using this function on a - non-stream file descriptor will result in undefined behavior. For - non-stream file descriptors, see instead :func:`json_loadb()`. In - addition, please note that this function cannot be used on non-blocking - file descriptors (such as a non-blocking socket). Using this function - on non-blocking file descriptors has a high risk of data loss because - it does not support resuming. - - This function requires POSIX and fails on all non-POSIX systems. - - .. versionadded:: 2.10 - -.. 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 write at most *buflen* bytes to - *buffer*, and return the number of bytes written; a returned value - of 0 indicates that no data was produced and that the end of file - has been reached. On error, the function should return - ``(size_t)-1`` to abort the decoding process. - - In UTF-8, some code points are encoded as multi-byte sequences. The - callback function doesn't need to worry about this, as Jansson - handles it at a higher level. For example, you can safely read a - fixed number of bytes from a network connection without having to - care about code unit sequences broken apart by the chunk - boundaries. - - .. 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 \*] - Like ``s``, but if the argument is *NULL*, output a JSON null - value. - - .. versionadded:: 2.8 - -``s*`` (string) [const char \*] - Like ``s``, but if the argument is *NULL*, do not output any value. - This format can only be used inside an object or an array. If used - inside an object, the corresponding key is additionally suppressed - when the value is omitted. See below for an example. - - .. versionadded:: 2.11 - -``s#`` (string) [const char \*, int] - Convert a UTF-8 buffer of a given length to a JSON string. - - .. versionadded:: 2.5 - -``s%`` (string) [const char \*, size_t] - Like ``s#`` but the length argument is of type :type:`size_t`. - - .. versionadded:: 2.6 - -``+`` [const char \*] - Like ``s``, but concatenate to the previous string. Only valid - after ``s``, ``s#``, ``+`` or ``+#``. - - .. versionadded:: 2.5 - -``+#`` [const char \*, int] - Like ``s#``, but concatenate to the previous string. Only valid - after ``s``, ``s#``, ``+`` or ``+#``. - - .. versionadded:: 2.5 - -``+%`` (string) [const char \*, size_t] - Like ``+#`` but the length argument is of type :type:`size_t`. - - .. versionadded:: 2.6 - -``n`` (null) - Output a JSON null value. No argument is consumed. - -``b`` (boolean) [int] - Convert a C ``int`` to JSON boolean value. Zero is converted - to ``false`` and non-zero to ``true``. - -``i`` (integer) [int] - Convert a C ``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 ``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. - -``o?``, ``O?`` (any value) [json_t \*] - Like ``o`` and ``O``, respectively, but if the argument is - *NULL*, output a JSON null value. - - .. versionadded:: 2.8 - -``o*``, ``O*`` (any value) [json_t \*] - Like ``o`` and ``O``, respectively, but if the argument is - *NULL*, do not output any value. This format can only be used - inside an object or an array. If used inside an object, the - corresponding key is additionally suppressed. See below for an - example. - - .. versionadded:: 2.11 - -``[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. - -.. 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-null terminated buffer */ - char buffer[4] = {'t', 'e', 's', 't'}; - json_pack("s#", buffer, 4); - - /* Concatenate strings together to build the JSON string "foobarbaz" */ - json_pack("s++", "foo", "bar", "baz"); - - /* Create an empty object or array when optional members are missing */ - json_pack("{s:s*,s:o*,s:O*}", "foo", NULL, "bar", NULL, "baz", NULL); - json_pack("[s*,o*,O*]", NULL, NULL, NULL); - - -.. _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. - -``s%`` (string) [const char \*, size_t \*] - Convert a JSON string to a pointer to a null terminated UTF-8 - string and its length. - - .. versionadded:: 2.6 - -``n`` (null) - Expect a JSON null value. Nothing is extracted. - -``b`` (boolean) [int] - Convert a JSON boolean value to a C ``int``, so that ``true`` - is converted to 1 and ``false`` to 0. - -``i`` (integer) [int] - Convert a JSON integer to C ``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 ``double``. - -``F`` (integer or real) [double] - Convert a JSON number (integer or real) to C ``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. - Storage pointers should be initialized NULL before using unpack. - The caller is responsible for releasing all references incremented - by unpack, even when an error occurs. - -``[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 supported. - -``{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 supported. - - .. 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. - -.. 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, myint3 = 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 ``==``.) - -.. 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 unequal 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. - -Copying objects preserves the insertion order of keys. - -.. 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. - -.. function:: void json_get_alloc_funcs(json_malloc_t *malloc_fn, json_free_t *free_fn) - - Fetch the current malloc_fn and free_fn used. Either parameter - may be NULL. - - .. versionadded:: 2.8 - -**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.hboehm.info/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 + 8); - 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. - -.. _fixed_length_keys: - -Fixed-Length keys -================= - -The Jansson API allows work with fixed-length keys. This can be useful in the following cases: - -* The key is contained inside a buffer and is not null-terminated. In this case creating a new temporary buffer is not needed. -* The key contains U+0000 inside it. - -List of API for fixed-length keys: - -* :c:func:`json_object_getn` -* :c:func:`json_object_setn` -* :c:func:`json_object_setn_nocheck` -* :c:func:`json_object_setn_new` -* :c:func:`json_object_setn_new_nocheck` -* :c:func:`json_object_deln` -* :c:func:`json_object_iter_key_len` -* :c:func:`json_object_keylen_foreach` -* :c:func:`json_object_keylen_foreach_safe` - -**Examples:** - -Try to write a new function to get :c:struct:`json_t` by path separated by ``.`` - -This requires: - -* string iterator (no need to modify the input for better performance) -* API for working with fixed-size keys - -The iterator:: - - struct string { - const char *string; - size_t length; - }; - - size_t string_try_next(struct string *str, const char *delimiter) { - str->string += strspn(str->string, delimiter); - str->length = strcspn(str->string, delimiter); - return str->length; - } - - #define string_foreach(_string, _delimiter) \ - for (; string_try_next(&(_string), _delimiter); (_string).string += (_string).length) - - -The function:: - - json_t *json_object_get_by_path(json_t *object, const char *path) { - struct string str; - json_t *out = object; - - str.string = path; - - string_foreach(str, ".") { - out = json_object_getn(out, str.string, str.length); - if (out == NULL) - return NULL; - } - - return out; - } - -And usage:: - - int main(void) { - json_t *obj = json_pack("{s:{s:{s:b}}}", "a", "b", "c", 1); - - json_t *c = json_object_get_by_path(obj, "a.b.c"); - assert(json_is_true(c)); - - json_decref(obj); - } diff --git a/fluent-bit/lib/jansson-e23f558/doc/changes.rst b/fluent-bit/lib/jansson-e23f558/doc/changes.rst deleted file mode 100644 index ea5684377..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/changes.rst +++ /dev/null @@ -1,5 +0,0 @@ -****************** -Changes in Jansson -****************** - -.. include:: ../CHANGES diff --git a/fluent-bit/lib/jansson-e23f558/doc/conf.py b/fluent-bit/lib/jansson-e23f558/doc/conf.py deleted file mode 100644 index 242617170..000000000 --- a/fluent-bit/lib/jansson-e23f558/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-2020, 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.14' -# 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/fluent-bit/lib/jansson-e23f558/doc/conformance.rst b/fluent-bit/lib/jansson-e23f558/doc/conformance.rst deleted file mode 100644 index 5556a6b81..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/conformance.rst +++ /dev/null @@ -1,119 +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. - -All Unicode codepoints U+0000 through U+10FFFF are allowed in string -values. However, U+0000 is allowed in object keys only for length-aware functions. - -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. - -Depth of nested values -====================== - -To avoid stack exhaustion, Jansson currently limits the nesting depth -for arrays and objects to a certain value (default: 2048), defined as -a macro ``JSON_PARSER_MAX_DEPTH`` within ``jansson_config.h``. - -The limit is allowed to be set by the RFC; there is no recommended value -or required minimum depth to be supported. diff --git a/fluent-bit/lib/jansson-e23f558/doc/ext/refcounting.py b/fluent-bit/lib/jansson-e23f558/doc/ext/refcounting.py deleted file mode 100644 index e72c481c5..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/ext/refcounting.py +++ /dev/null @@ -1,69 +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-2016 Petri Lehtinen - :license: MIT, see LICENSE for details. -""" - -from docutils import nodes -from docutils.parsers.rst import Directive - - -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('') - - -class refcounting(nodes.emphasis): - pass - -class refcounting_directive(Directive): - has_content = False - required_arguments = 1 - optional_arguments = 0 - final_argument_whitespace = False - - def run(self): - if self.arguments[0] == 'borrow': - text = 'Return value: Borrowed reference.' - elif self.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), - man=(visit, depart)) - app.add_directive('refcounting', refcounting_directive) diff --git a/fluent-bit/lib/jansson-e23f558/doc/gettingstarted.rst b/fluent-bit/lib/jansson-e23f558/doc/gettingstarted.rst deleted file mode 100644 index 4cd19773d..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/gettingstarted.rst +++ /dev/null @@ -1,264 +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 configuration options. - -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 -fi - -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. - -.. note:: - - If you don't want to build docs or ``Sphinx`` is not installed, you should add ``"-DJANSSON_BUILD_DOCS=OFF"`` in the ``cmake`` command. - - -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 15 2017" .. - -.. note:: - - You should replace the name of the generator (``-G`` flag) matching - the Visual Studio version installed on your system. Currently, the - following versions are supported: - - - ``Visual Studio 9 2008`` - - ``Visual Studio 10 2010`` - - ``Visual Studio 11 2012`` - - ``Visual Studio 12 2013`` - - ``Visual Studio 14 2015`` - - ``Visual Studio 15 2017`` - - ``Visual Studio 16 2019`` - - Any later version should also work. - -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 .. - -Windows (MinGW) -^^^^^^^^^^^^^^^ -If you prefer using MinGW on Windows, make sure MinGW installed and ``{MinGW}/bin`` has been added to ``PATH``, then do the following commands: - -.. parsed-literal:: - - - cd jansson-|release| - - md build - cd build - cmake -G "MinGW Makefiles" .. - mingw32-make - - -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 -DJANSSON_BUILD_SHARED_LIBS=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. - - -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_: - -.. code-block:: shell - - cc -o prog prog.c `pkg-config --cflags --libs jansson` - -.. _pkg-config: http://pkg-config.freedesktop.org/ diff --git a/fluent-bit/lib/jansson-e23f558/doc/github_commits.c b/fluent-bit/lib/jansson-e23f558/doc/github_commits.c deleted file mode 100644 index 81c806393..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/github_commits.c +++ /dev/null @@ -1,181 +0,0 @@ -/* - * Copyright (c) 2009-2016 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; - struct curl_slist *headers = NULL; - 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); - - /* GitHub commits API v3 requires a User-Agent header */ - headers = curl_slist_append(headers, "User-Agent: Jansson-Tutorial"); - curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); - - 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_slist_free_all(headers); - 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); - if (headers) - curl_slist_free_all(headers); - 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)); - 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", (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/fluent-bit/lib/jansson-e23f558/doc/index.rst b/fluent-bit/lib/jansson-e23f558/doc/index.rst deleted file mode 100644 index c679f409b..000000000 --- a/fluent-bit/lib/jansson-e23f558/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 - threadsafety - apiref - changes - - -Indices and Tables -================== - -* :ref:`genindex` -* :ref:`search` diff --git a/fluent-bit/lib/jansson-e23f558/doc/threadsafety.rst b/fluent-bit/lib/jansson-e23f558/doc/threadsafety.rst deleted file mode 100644 index 0eebb29a9..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/threadsafety.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _thread-safety: - -************* -Thread safety -************* - -Jansson as a library is thread safe and has no mutable global state. -The only exceptions are the hash function seed and memory allocation -functions, see below. - -There's no locking performed inside Jansson's code. **Read-only** -access to JSON values shared by multiple threads is safe, but -**mutating** a JSON value that's shared by multiple threads is not. A -multithreaded program must perform its own locking if JSON values -shared by multiple threads are mutated. - -However, **reference count manipulation** (:func:`json_incref()`, -:func:`json_decref()`) is usually thread-safe, and can be performed on -JSON values that are shared among threads. The thread-safety of -reference counting can be checked with the -``JANSSON_THREAD_SAFE_REFCOUNT`` preprocessor constant. Thread-safe -reference count manipulation is achieved using compiler built-in -atomic functions, which are available in most modern compilers. - -If compiler support is not available (``JANSSON_THREAD_SAFE_REFCOUNT`` -is not defined), it may be very difficult to ensure thread safety of -reference counting. It's possible to have a reference to a value -that's also stored inside an array or object in another thread. -Modifying the container (adding or removing values) may trigger -concurrent access to such values, as containers manage the reference -count of their contained values. - - -Hash function seed -================== - -To prevent an attacker from intentionally causing large JSON objects -with specially crafted keys to perform very slow, the hash function -used by Jansson is randomized using a seed value. The seed is -automatically generated on the first explicit or implicit call to -:func:`json_object()`, if :func:`json_object_seed()` has not been -called beforehand. - -The seed is generated by using operating system's entropy sources if -they are available (``/dev/urandom``, ``CryptGenRandom()``). The -initialization is done in as thread safe manner as possible, by using -architecture specific lockless operations if provided by the platform -or the compiler. - -If you're using threads, it's recommended to autoseed the hashtable -explicitly before spawning any threads by calling -``json_object_seed(0)`` , especially if you're unsure whether the -initialization is thread safe on your platform. - - -Memory allocation functions -=========================== - -Memory allocation functions should be set at most once, and only on -program startup. See :ref:`apiref-custom-memory-allocation`. - - -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/fluent-bit/lib/jansson-e23f558/doc/tutorial.rst b/fluent-bit/lib/jansson-e23f558/doc/tutorial.rst deleted file mode 100644 index bb7a6c21c..000000000 --- a/fluent-bit/lib/jansson-e23f558/doc/tutorial.rst +++ /dev/null @@ -1,288 +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 scope of this tutorial, we will only cover 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, performs 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(sha), - 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: - -.. code-block:: shell - - $ ./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/fluent-bit/lib/jansson-e23f558/doc/upgrading.rst b/fluent-bit/lib/jansson-e23f558/doc/upgrading.rst deleted file mode 100644 index 94ff7de3c..000000000 --- a/fluent-bit/lib/jansson-e23f558/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 - ``int`` to the widest available signed integer type, i.e. - ``long long`` or ``long``, depending on whether - ``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. ``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 - ``unsigned int`` and ``unsigned long`` have been replaced - with ``size_t``. This includes flags, container sizes, etc. - This should not require source code changes, as both - ``unsigned int`` and ``unsigned long`` are usually - compatible with ``size_t``. -- cgit v1.2.3