ctags.rb 1.0.0 → 1.0.6

data/ext/vendor/jansson-2.5/doc/Makefile.am

@@ -0,0 +1,20 @@
+EXTRA_DIST = conf.py apiref.rst changes.rst conformance.rst		\
+	gettingstarted.rst github_commits.c index.rst portability.rst	\
+	tutorial.rst upgrading.rst ext/refcounting.py
+
+SPHINXBUILD = sphinx-build
+SPHINXOPTS = -d _build/doctrees $(SPHINXOPTS_EXTRA)
+
+html-local:
+	$(SPHINXBUILD) -b html $(SPHINXOPTS) $(srcdir) _build/html
+
+install-html-local: html
+	mkdir -p $(DESTDIR)$(htmldir)
+	cp -r _build/html $(DESTDIR)$(htmldir)
+
+uninstall-local:
+	rm -rf $(DESTDIR)$(htmldir)
+
+clean-local:
+	rm -rf _build
+	rm -f ext/refcounting.pyc

data/ext/vendor/jansson-2.5/doc/Makefile.in

@@ -0,0 +1,401 @@
+# Makefile.in generated by automake 1.11.6 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+# 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software
+# Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+VPATH = @srcdir@
+am__make_dryrun = \
+  { \
+    am__dry=no; \
+    case $$MAKEFLAGS in \
+      *\\[\ \	]*) \
+        echo 'am--echo: ; @echo "AM"  OK' | $(MAKE) -f - 2>/dev/null \
+          | grep '^AM OK$$' >/dev/null || am__dry=yes;; \
+      *) \
+        for am__flg in $$MAKEFLAGS; do \
+          case $$am__flg in \
+            *=*|--*) ;; \
+            *n*) am__dry=yes; break;; \
+          esac; \
+        done;; \
+    esac; \
+    test $$am__dry = yes; \
+  }
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkglibexecdir = $(libexecdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = doc
+DIST_COMMON = README $(srcdir)/Makefile.am $(srcdir)/Makefile.in
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+	$(ACLOCAL_M4)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/config.h
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+SOURCES =
+DIST_SOURCES =
+am__can_run_installinfo = \
+  case $$AM_UPDATE_INFO_DIR in \
+    n|no|NO) false;; \
+    *) (install-info --version) >/dev/null 2>&1;; \
+  esac
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+AMTAR = @AMTAR@
+AR = @AR@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DLLTOOL = @DLLTOOL@
+DSYMUTIL = @DSYMUTIL@
+DUMPBIN = @DUMPBIN@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+EXEEXT = @EXEEXT@
+FGREP = @FGREP@
+GREP = @GREP@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+LD = @LD@
+LDFLAGS = @LDFLAGS@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIPO = @LIPO@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+MAKEINFO = @MAKEINFO@
+MANIFEST_TOOL = @MANIFEST_TOOL@
+MKDIR_P = @MKDIR_P@
+NM = @NM@
+NMEDIT = @NMEDIT@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OTOOL = @OTOOL@
+OTOOL64 = @OTOOL64@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+RANLIB = @RANLIB@
+SED = @SED@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+STRIP = @STRIP@
+VERSION = @VERSION@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_AR = @ac_ct_AR@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+json_have_localeconv = @json_have_localeconv@
+json_have_long_long = @json_have_long_long@
+json_inline = @json_inline@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+EXTRA_DIST = conf.py apiref.rst changes.rst conformance.rst		\
+	gettingstarted.rst github_commits.c index.rst portability.rst	\
+	tutorial.rst upgrading.rst ext/refcounting.py
+
+SPHINXBUILD = sphinx-build
+SPHINXOPTS = -d _build/doctrees $(SPHINXOPTS_EXTRA)
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in:  $(srcdir)/Makefile.am  $(am__configure_deps)
+	@for dep in $?; do \
+	  case '$(am__configure_deps)' in \
+	    *$$dep*) \
+	      ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+	        && { if test -f $@; then exit 0; else break; fi; }; \
+	      exit 1;; \
+	  esac; \
+	done; \
+	echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \
+	$(am__cd) $(top_srcdir) && \
+	  $(AUTOMAKE) --foreign doc/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+	@case '$?' in \
+	  *config.status*) \
+	    cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+	  *) \
+	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+	    cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+	esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure:  $(am__configure_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4):  $(am__aclocal_m4_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+
+mostlyclean-libtool:
+	-rm -f *.lo
+
+clean-libtool:
+	-rm -rf .libs _libs
+tags: TAGS
+TAGS:
+
+ctags: CTAGS
+CTAGS:
+
+
+distdir: $(DISTFILES)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+	topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+	list='$(DISTFILES)'; \
+	  dist_files=`for file in $$list; do echo $$file; done | \
+	  sed -e "s|^$$srcdirstrip/||;t" \
+	      -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+	case $$dist_files in \
+	  */*) $(MKDIR_P) `echo "$$dist_files" | \
+			   sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+			   sort -u` ;; \
+	esac; \
+	for file in $$dist_files; do \
+	  if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+	  if test -d $$d/$$file; then \
+	    dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+	    if test -d "$(distdir)/$$file"; then \
+	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+	    fi; \
+	    if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+	      cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
+	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+	    fi; \
+	    cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
+	  else \
+	    test -f "$(distdir)/$$file" \
+	    || cp -p $$d/$$file "$(distdir)/$$file" \
+	    || exit 1; \
+	  fi; \
+	done
+check-am: all-am
+check: check-am
+all-am: Makefile
+installdirs:
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+	if test -z '$(STRIP)'; then \
+	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	      install; \
+	else \
+	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	    "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
+	fi
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+	-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+
+maintainer-clean-generic:
+	@echo "This command is intended for maintainers to use"
+	@echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic clean-libtool clean-local mostlyclean-am
+
+distclean: distclean-am
+	-rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+html-am: html-local
+
+info: info-am
+
+info-am:
+
+install-data-am:
+
+install-dvi: install-dvi-am
+
+install-dvi-am:
+
+install-exec-am:
+
+install-html: install-html-am
+
+install-html-am: install-html-local
+
+install-info: install-info-am
+
+install-info-am:
+
+install-man:
+
+install-pdf: install-pdf-am
+
+install-pdf-am:
+
+install-ps: install-ps-am
+
+install-ps-am:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+	-rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am: uninstall-local
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-generic clean-libtool \
+	clean-local distclean distclean-generic distclean-libtool \
+	distdir dvi dvi-am html html-am html-local info info-am \
+	install install-am install-data install-data-am install-dvi \
+	install-dvi-am install-exec install-exec-am install-html \
+	install-html-am install-html-local install-info \
+	install-info-am install-man install-pdf install-pdf-am \
+	install-ps install-ps-am install-strip installcheck \
+	installcheck-am installdirs maintainer-clean \
+	maintainer-clean-generic mostlyclean mostlyclean-generic \
+	mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am \
+	uninstall-local
+
+
+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
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:

data/ext/vendor/jansson-2.5/doc/README

@@ -0,0 +1,5 @@
+To build the documentation, invoke
+
+    make html
+
+Then point your browser to _build/html/index.html.

data/ext/vendor/jansson-2.5/doc/apiref.rst

@@ -0,0 +1,1487 @@
+.. _apiref:
+
+*************
+API Reference
+*************
+
+.. highlight:: c
+
+Preliminaries
+=============
+
+All declarations are in :file:`jansson.h`, so it's enough to
+
+::
+
+   #include <jansson.h>
+
+in each source file.
+
+All constants are prefixed with ``JSON_`` (except for those describing
+the library version, prefixed with ``JANSSON_``). Other identifiers
+are prefixed with ``json_``. Type names are suffixed with ``_t`` and
+``typedef``\ 'd so that the ``struct`` keyword need not be used.
+
+
+Library Version
+===============
+
+The Jansson version is of the form *A.B.C*, where *A* is the major
+version, *B* is the minor version and *C* is the micro version. If the
+micro version is zero, it's omitted from the version string, i.e. the
+version string is just *A.B*.
+
+When a new release only fixes bugs and doesn't add new features or
+functionality, the micro version is incremented. When new features are
+added in a backwards compatible way, the minor version is incremented
+and the micro version is set to zero. When there are backwards
+incompatible changes, the major version is incremented and others are
+set to zero.
+
+The following preprocessor constants specify the current version of
+the library:
+
+``JANSSON_MAJOR_VERSION``, ``JANSSON_MINOR_VERSION``, ``JANSSON_MICRO_VERSION``
+  Integers specifying the major, minor and micro versions,
+  respectively.
+
+``JANSSON_VERSION``
+  A string representation of the current version, e.g. ``"1.2.1"`` or
+  ``"1.3"``.
+
+``JANSSON_VERSION_HEX``
+  A 3-byte hexadecimal representation of the version, e.g.
+  ``0x010201`` for version 1.2.1 and ``0x010300`` for version 1.3.
+  This is useful in numeric comparisions, e.g.::
+
+      #if JANSSON_VERSION_HEX >= 0x010300
+      /* Code specific to version 1.3 and above */
+      #endif
+
+
+Value Representation
+====================
+
+The JSON specification (:rfc:`4627`) defines the following data types:
+*object*, *array*, *string*, *number*, *boolean*, and *null*. JSON
+types are used dynamically; arrays and objects can hold any other data
+type, including themselves. For this reason, Jansson's type system is
+also dynamic in nature. There's one C type to represent all JSON
+values, and this structure knows the type of the JSON value it holds.
+
+.. type:: json_t
+
+  This data structure is used throughout the library to represent all
+  JSON values. It always contains the type of the JSON value it holds
+  and the value's reference count. The rest depends on the type of the
+  value.
+
+Objects of :type:`json_t` are always used through a pointer. There
+are APIs for querying the type, manipulating the reference count, and
+for constructing and manipulating values of different types.
+
+Unless noted otherwise, all API functions return an error value if an
+error occurs. Depending on the function's signature, the error value
+is either *NULL* or -1. Invalid arguments or invalid input are
+apparent sources for errors. Memory allocation and I/O operations may
+also cause errors.
+
+
+Type
+----
+
+The type of a JSON value is queried and tested using the following
+functions:
+
+.. type:: enum json_type
+
+   The type of a JSON value. The following members are defined:
+
+   +--------------------+
+   | ``JSON_OBJECT``    |
+   +--------------------+
+   | ``JSON_ARRAY``     |
+   +--------------------+
+   | ``JSON_STRING``    |
+   +--------------------+
+   | ``JSON_INTEGER``   |
+   +--------------------+
+   | ``JSON_REAL``      |
+   +--------------------+
+   | ``JSON_TRUE``      |
+   +--------------------+
+   | ``JSON_FALSE``     |
+   +--------------------+
+   | ``JSON_NULL``      |
+   +--------------------+
+
+   These correspond to JSON object, array, string, number, boolean and
+   null. A number is represented by either a value of the type
+   ``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value
+   is represented by a value of the type ``JSON_TRUE`` and false by a
+   value of the type ``JSON_FALSE``.
+
+.. function:: int json_typeof(const json_t *json)
+
+   Return the type of the JSON value (a :type:`json_type` cast to
+   :type:`int`). *json* MUST NOT be *NULL*. This function is actually
+   implemented as a macro for speed.
+
+.. function:: json_is_object(const json_t *json)
+               json_is_array(const json_t *json)
+               json_is_string(const json_t *json)
+               json_is_integer(const json_t *json)
+               json_is_real(const json_t *json)
+               json_is_true(const json_t *json)
+               json_is_false(const json_t *json)
+               json_is_null(const json_t *json)
+
+   These functions (actually macros) return true (non-zero) for values
+   of the given type, and false (zero) for values of other types and
+   for *NULL*.
+
+.. function:: json_is_number(const json_t *json)
+
+   Returns true for values of types ``JSON_INTEGER`` and
+   ``JSON_REAL``, and false for other types and for *NULL*.
+
+.. function:: json_is_boolean(const json_t *json)
+
+   Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false
+   for values of other types and for *NULL*.
+
+
+.. _apiref-reference-count:
+
+Reference Count
+---------------
+
+The reference count is used to track whether a value is still in use
+or not. When a value is created, it's reference count is set to 1. If
+a reference to a value is kept (e.g. a value is stored somewhere for
+later use), its reference count is incremented, and when the value is
+no longer needed, the reference count is decremented. When the
+reference count drops to zero, there are no references left, and the
+value can be destroyed.
+
+The following functions are used to manipulate the reference count.
+
+.. function:: json_t *json_incref(json_t *json)
+
+   Increment the reference count of *json* if it's not *NULL*.
+   Returns *json*.
+
+.. function:: void json_decref(json_t *json)
+
+   Decrement the reference count of *json*. As soon as a call to
+   :func:`json_decref()` drops the reference count to zero, the value
+   is destroyed and it can no longer be used.
+
+Functions creating new JSON values set the reference count to 1. These
+functions are said to return a **new reference**. Other functions
+returning (existing) JSON values do not normally increase the
+reference count. These functions are said to return a **borrowed
+reference**. So, if the user will hold a reference to a value returned
+as a borrowed reference, he must call :func:`json_incref`. As soon as
+the value is no longer needed, :func:`json_decref` should be called
+to release the reference.
+
+Normally, all functions accepting a JSON value as an argument will
+manage the reference, i.e. increase and decrease the reference count
+as needed. However, some functions **steal** the reference, i.e. they
+have the same result as if the user called :func:`json_decref()` on
+the argument right after calling the function. These functions are
+suffixed with ``_new`` or have ``_new_`` somewhere in their name.
+
+For example, the following code creates a new JSON array and appends
+an integer to it::
+
+  json_t *array, *integer;
+
+  array = json_array();
+  integer = json_integer(42);
+
+  json_array_append(array, integer);
+  json_decref(integer);
+
+Note how the caller has to release the reference to the integer value
+by calling :func:`json_decref()`. By using a reference stealing
+function :func:`json_array_append_new()` instead of
+:func:`json_array_append()`, the code becomes much simpler::
+
+  json_t *array = json_array();
+  json_array_append_new(array, json_integer(42));
+
+In this case, the user doesn't have to explicitly release the
+reference to the integer value, as :func:`json_array_append_new()`
+steals the reference when appending the value to the array.
+
+In the following sections it is clearly documented whether a function
+will return a new or borrowed reference or steal a reference to its
+argument.
+
+
+Circular References
+-------------------
+
+A circular reference is created when an object or an array is,
+directly or indirectly, inserted inside itself. The direct case is
+simple::
+
+  json_t *obj = json_object();
+  json_object_set(obj, "foo", obj);
+
+Jansson will refuse to do this, and :func:`json_object_set()` (and
+all the other such functions for objects and arrays) will return with
+an error status. The indirect case is the dangerous one::
+
+  json_t *arr1 = json_array(), *arr2 = json_array();
+  json_array_append(arr1, arr2);
+  json_array_append(arr2, arr1);
+
+In this example, the array ``arr2`` is contained in the array
+``arr1``, and vice versa. Jansson cannot check for this kind of
+indirect circular references without a performance hit, so it's up to
+the user to avoid them.
+
+If a circular reference is created, the memory consumed by the values
+cannot be freed by :func:`json_decref()`. The reference counts never
+drops to zero because the values are keeping the references to each
+other. Moreover, trying to encode the values with any of the encoding
+functions will fail. The encoder detects circular references and
+returns an error status.
+
+
+True, False and Null
+====================
+
+These three values are implemented as singletons, so the returned
+pointers won't change between invocations of these functions.
+
+.. function:: json_t *json_true(void)
+
+   .. refcounting:: new
+
+   Returns the JSON true value.
+
+.. function:: json_t *json_false(void)
+
+   .. refcounting:: new
+
+   Returns the JSON false value.
+
+.. function:: json_t *json_boolean(val)
+
+   .. refcounting:: new
+
+   Returns JSON false if ``val`` is zero, and JSON true otherwise.
+   This is a macro, and equivalent to ``val ? json_true() :
+   json_false()``.
+
+   .. versionadded:: 2.4
+
+
+.. function:: json_t *json_null(void)
+
+   .. refcounting:: new
+
+   Returns the JSON null value.
+
+
+String
+======
+
+Jansson uses UTF-8 as the character encoding. All JSON strings must be
+valid UTF-8 (or ASCII, as it's a subset of UTF-8). Normal null
+terminated C strings are used, so JSON strings may not contain
+embedded null characters. All other Unicode codepoints U+0001 through
+U+10FFFF are allowed.
+
+.. function:: json_t *json_string(const char *value)
+
+   .. refcounting:: new
+
+   Returns a new JSON string, or *NULL* on error. *value* must be a
+   valid UTF-8 encoded Unicode string.
+
+.. function:: json_t *json_string_nocheck(const char *value)
+
+   .. refcounting:: new
+
+   Like :func:`json_string`, but doesn't check that *value* is valid
+   UTF-8. Use this function only if you are certain that this really
+   is the case (e.g. you have already checked it by other means).
+
+.. function:: const char *json_string_value(const json_t *string)
+
+   Returns the associated value of *string* as a null terminated UTF-8
+   encoded string, or *NULL* if *string* is not a JSON string.
+
+   The retuned value is read-only and must not be modified or freed by
+   the user. It is valid as long as *string* exists, i.e. as long as
+   its reference count has not dropped to zero.
+
+.. function:: int json_string_set(const json_t *string, const char *value)
+
+   Sets the associated value of *string* to *value*. *value* must be a
+   valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
+   error.
+
+.. function:: int json_string_set_nocheck(const json_t *string, const char *value)
+
+   Like :func:`json_string_set`, but doesn't check that *value* is
+   valid UTF-8. Use this function only if you are certain that this
+   really is the case (e.g. you have already checked it by other
+   means).
+
+
+Number
+======
+
+The JSON specification only contains one numeric type, "number". The C
+programming language has distinct types for integer and floating-point
+numbers, so for practical reasons Jansson also has distinct types for
+the two. They are called "integer" and "real", respectively. For more
+information, see :ref:`rfc-conformance`.
+
+.. type:: json_int_t
+
+   This is the C type that is used to store JSON integer values. It
+   represents the widest integer type available on your system. In
+   practice it's just a typedef of ``long long`` if your compiler
+   supports it, otherwise ``long``.
+
+   Usually, you can safely use plain ``int`` in place of
+   ``json_int_t``, and the implicit C integer conversion handles the
+   rest. Only when you know that you need the full 64-bit range, you
+   should use ``json_int_t`` explicitly.
+
+``JSON_INTEGER_IS_LONG_LONG``
+   This is a preprocessor variable that holds the value 1 if
+   :type:`json_int_t` is ``long long``, and 0 if it's ``long``. It
+   can be used as follows::
+
+       #if JSON_INTEGER_IS_LONG_LONG
+       /* Code specific for long long */
+       #else
+       /* Code specific for long */
+       #endif
+
+``JSON_INTEGER_FORMAT``
+   This is a macro that expands to a :func:`printf()` conversion
+   specifier that corresponds to :type:`json_int_t`, without the
+   leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro
+   is required because the actual type of :type:`json_int_t` can be
+   either ``long`` or ``long long``, and :func:`printf()` reuiqres
+   different length modifiers for the two.
+
+   Example::
+
+       json_int_t x = 123123123;
+       printf("x is %" JSON_INTEGER_FORMAT "\n", x);
+
+
+.. function:: json_t *json_integer(json_int_t value)
+
+   .. refcounting:: new
+
+   Returns a new JSON integer, or *NULL* on error.
+
+.. function:: json_int_t json_integer_value(const json_t *integer)
+
+   Returns the associated value of *integer*, or 0 if *json* is not a
+   JSON integer.
+
+.. function:: int json_integer_set(const json_t *integer, json_int_t value)
+
+   Sets the associated value of *integer* to *value*. Returns 0 on
+   success and -1 if *integer* is not a JSON integer.
+
+.. function:: json_t *json_real(double value)
+
+   .. refcounting:: new
+
+   Returns a new JSON real, or *NULL* on error.
+
+.. function:: double json_real_value(const json_t *real)
+
+   Returns the associated value of *real*, or 0.0 if *real* is not a
+   JSON real.
+
+.. function:: int json_real_set(const json_t *real, double value)
+
+   Sets the associated value of *real* to *value*. Returns 0 on
+   success and -1 if *real* is not a JSON real.
+
+In addition to the functions above, there's a common query function
+for integers and reals:
+
+.. function:: double json_number_value(const json_t *json)
+
+   Returns the associated value of the JSON integer or JSON real
+   *json*, cast to double regardless of the actual type. If *json* is
+   neither JSON real nor JSON integer, 0.0 is returned.
+
+
+Array
+=====
+
+A JSON array is an ordered collection of other JSON values.
+
+.. function:: json_t *json_array(void)
+
+   .. refcounting:: new
+
+   Returns a new JSON array, or *NULL* on error. Initially, the array
+   is empty.
+
+.. function:: size_t json_array_size(const json_t *array)
+
+   Returns the number of elements in *array*, or 0 if *array* is NULL
+   or not a JSON array.
+
+.. function:: json_t *json_array_get(const json_t *array, size_t index)
+
+   .. refcounting:: borrow
+
+   Returns the element in *array* at position *index*. The valid range
+   for *index* is from 0 to the return value of
+   :func:`json_array_size()` minus 1. If *array* is not a JSON array,
+   if *array* is *NULL*, or if *index* is out of range, *NULL* is
+   returned.
+
+.. function:: int json_array_set(json_t *array, size_t index, json_t *value)
+
+   Replaces the element in *array* at position *index* with *value*.
+   The valid range for *index* is from 0 to the return value of
+   :func:`json_array_size()` minus 1. Returns 0 on success and -1 on
+   error.
+
+.. function:: int json_array_set_new(json_t *array, size_t index, json_t *value)
+
+   Like :func:`json_array_set()` but steals the reference to *value*.
+   This is useful when *value* is newly created and not used after
+   the call.
+
+.. function:: int json_array_append(json_t *array, json_t *value)
+
+   Appends *value* to the end of *array*, growing the size of *array*
+   by 1. Returns 0 on success and -1 on error.
+
+.. function:: int json_array_append_new(json_t *array, json_t *value)
+
+   Like :func:`json_array_append()` but steals the reference to
+   *value*. This is useful when *value* is newly created and not used
+   after the call.
+
+.. function:: int json_array_insert(json_t *array, size_t index, json_t *value)
+
+   Inserts *value* to *array* at position *index*, shifting the
+   elements at *index* and after it one position towards the end of
+   the array. Returns 0 on success and -1 on error.
+
+.. function:: int json_array_insert_new(json_t *array, size_t index, json_t *value)
+
+   Like :func:`json_array_insert()` but steals the reference to
+   *value*. This is useful when *value* is newly created and not used
+   after the call.
+
+.. function:: int json_array_remove(json_t *array, size_t index)
+
+   Removes the element in *array* at position *index*, shifting the
+   elements after *index* one position towards the start of the array.
+   Returns 0 on success and -1 on error. The reference count of the
+   removed value is decremented.
+
+.. function:: int json_array_clear(json_t *array)
+
+   Removes all elements from *array*. Returns 0 on sucess and -1 on
+   error. The reference count of all removed values are decremented.
+
+.. function:: int json_array_extend(json_t *array, json_t *other_array)
+
+   Appends all elements in *other_array* to the end of *array*.
+   Returns 0 on success and -1 on error.
+
+The following macro can be used to iterate through all elements
+in an array.
+
+.. function:: json_array_foreach(array, index, value)
+
+   Iterate over every element of ``array``, running the block
+   of code that follows each time with the proper values set to
+   variables ``index`` and ``value``, of types :type:`size_t` and
+   :type:`json_t *` respectively. Example::
+
+       /* array is a JSON array */
+       size_t index;
+       json_t *value;
+
+       json_array_foreach(array, index, value) {
+           /* block of code that uses index and value */
+       }
+
+   The items are returned in increasing index order.
+
+   This macro expands to an ordinary ``for`` statement upon
+   preprocessing, so its performance is equivalent to that of
+   hand-written code using the array access functions.
+   The main advantage of this macro is that it abstracts
+   away the complexity, and makes for shorter, more
+   concise code.
+
+   .. versionadded:: 2.5
+
+
+Object
+======
+
+A JSON object is a dictionary of key-value pairs, where the key is a
+Unicode string and the value is any JSON value.
+
+.. function:: json_t *json_object(void)
+
+   .. refcounting:: new
+
+   Returns a new JSON object, or *NULL* on error. Initially, the
+   object is empty.
+
+.. function:: size_t json_object_size(const json_t *object)
+
+   Returns the number of elements in *object*, or 0 if *object* is not
+   a JSON object.
+
+.. function:: json_t *json_object_get(const json_t *object, const char *key)
+
+   .. refcounting:: borrow
+
+   Get a value corresponding to *key* from *object*. Returns *NULL* if
+   *key* is not found and on error.
+
+.. function:: int json_object_set(json_t *object, const char *key, json_t *value)
+
+   Set the value of *key* to *value* in *object*. *key* must be a
+   valid null terminated UTF-8 encoded Unicode string. If there
+   already is a value for *key*, it is replaced by the new value.
+   Returns 0 on success and -1 on error.
+
+.. function:: int json_object_set_nocheck(json_t *object, const char *key, json_t *value)
+
+   Like :func:`json_object_set`, but doesn't check that *key* is
+   valid UTF-8. Use this function only if you are certain that this
+   really is the case (e.g. you have already checked it by other
+   means).
+
+.. function:: int json_object_set_new(json_t *object, const char *key, json_t *value)
+
+   Like :func:`json_object_set()` but steals the reference to
+   *value*. This is useful when *value* is newly created and not used
+   after the call.
+
+.. function:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)
+
+   Like :func:`json_object_set_new`, but doesn't check that *key* is
+   valid UTF-8. Use this function only if you are certain that this
+   really is the case (e.g. you have already checked it by other
+   means).
+
+.. function:: int json_object_del(json_t *object, const char *key)
+
+   Delete *key* from *object* if it exists. Returns 0 on success, or
+   -1 if *key* was not found. The reference count of the removed value
+   is decremented.
+
+.. function:: int json_object_clear(json_t *object)
+
+   Remove all elements from *object*. Returns 0 on success and -1 if
+   *object* is not a JSON object. The reference count of all removed
+   values are decremented.
+
+.. function:: int json_object_update(json_t *object, json_t *other)
+
+   Update *object* with the key-value pairs from *other*, overwriting
+   existing keys. Returns 0 on success or -1 on error.
+
+.. function:: int json_object_update_existing(json_t *object, json_t *other)
+
+   Like :func:`json_object_update()`, but only the values of existing
+   keys are updated. No new keys are created. Returns 0 on success or
+   -1 on error.
+
+   .. versionadded:: 2.3
+
+.. function:: int json_object_update_missing(json_t *object, json_t *other)
+
+   Like :func:`json_object_update()`, but only new keys are created.
+   The value of any existing key is not changed. Returns 0 on success
+   or -1 on error.
+
+   .. versionadded:: 2.3
+
+The following macro can be used to iterate through all key-value pairs
+in an object.
+
+.. function:: json_object_foreach(object, key, value)
+
+   Iterate over every key-value pair of ``object``, running the block
+   of code that follows each time with the proper values set to
+   variables ``key`` and ``value``, of types :type:`const char *` and
+   :type:`json_t *` respectively. Example::
+
+       /* obj is a JSON object */
+       const char *key;
+       json_t *value;
+
+       json_object_foreach(obj, key, value) {
+           /* block of code that uses key and value */
+       }
+
+   The items are not returned in any particular order.
+
+   This macro expands to an ordinary ``for`` statement upon
+   preprocessing, so its performance is equivalent to that of
+   hand-written iteration code using the object iteration protocol
+   (see below). The main advantage of this macro is that it abstracts
+   away the complexity behind iteration, and makes for shorter, more
+   concise code.
+
+   .. versionadded:: 2.3
+
+
+The following functions implement an iteration protocol for objects,
+allowing to iterate through all key-value pairs in an object. The
+items are not returned in any particular order, as this would require
+sorting due to the internal hashtable implementation.
+
+.. function:: void *json_object_iter(json_t *object)
+
+   Returns an opaque iterator which can be used to iterate over all
+   key-value pairs in *object*, or *NULL* if *object* is empty.
+
+.. function:: void *json_object_iter_at(json_t *object, const char *key)
+
+   Like :func:`json_object_iter()`, but returns an iterator to the
+   key-value pair in *object* whose key is equal to *key*, or NULL if
+   *key* is not found in *object*. Iterating forward to the end of
+   *object* only yields all key-value pairs of the object if *key*
+   happens to be the first key in the underlying hash table.
+
+.. function:: void *json_object_iter_next(json_t *object, void *iter)
+
+   Returns an iterator pointing to the next key-value pair in *object*
+   after *iter*, or *NULL* if the whole object has been iterated
+   through.
+
+.. function:: const char *json_object_iter_key(void *iter)
+
+   Extract the associated key from *iter*.
+
+.. function:: json_t *json_object_iter_value(void *iter)
+
+   .. refcounting:: borrow
+
+   Extract the associated value from *iter*.
+
+.. function:: int json_object_iter_set(json_t *object, void *iter, json_t *value)
+
+   Set the value of the key-value pair in *object*, that is pointed to
+   by *iter*, to *value*.
+
+.. function:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value)
+
+   Like :func:`json_object_iter_set()`, but steals the reference to
+   *value*. This is useful when *value* is newly created and not used
+   after the call.
+
+.. function:: void *json_object_key_to_iter(const char *key)
+
+   Like :func:`json_object_iter_at()`, but much faster. Only works for
+   values returned by :func:`json_object_iter_key()`. Using other keys
+   will lead to segfaults. This function is used internally to
+   implement :func:`json_object_foreach`.
+
+   .. versionadded:: 2.3
+
+The iteration protocol can be used for example as follows::
+
+   /* obj is a JSON object */
+   const char *key;
+   json_t *value;
+
+   void *iter = json_object_iter(obj);
+   while(iter)
+   {
+       key = json_object_iter_key(iter);
+       value = json_object_iter_value(iter);
+       /* use key and value ... */
+       iter = json_object_iter_next(obj, iter);
+   }
+
+
+Error reporting
+===============
+
+Jansson uses a single struct type to pass error information to the
+user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and
+:ref:`apiref-unpack` for functions that pass error information using
+this struct.
+
+.. type:: json_error_t
+
+   .. member:: char text[]
+
+      The error message (in UTF-8), or an empty string if a message is
+      not available.
+
+   .. member:: char source[]
+
+      Source of the error. This can be (a part of) the file name or a
+      special identifier in angle brackers (e.g. ``<string>``).
+
+   .. member:: int line
+
+      The line number on which the error occurred.
+
+   .. member:: int column
+
+      The column on which the error occurred. Note that this is the
+      *character column*, not the byte column, i.e. a multibyte UTF-8
+      character counts as one column.
+
+   .. member:: size_t position
+
+      The position in bytes from the start of the input. This is
+      useful for debugging Unicode encoding problems.
+
+The normal use of :type:`json_error_t` is to allocate it on the stack,
+and pass a pointer to a function. Example::
+
+   int main() {
+       json_t *json;
+       json_error_t error;
+
+       json = json_load_file("/path/to/file.json", 0, &error);
+       if(!json) {
+           /* the error variable contains error information */
+       }
+       ...
+   }
+
+Also note that if the call succeeded (``json != NULL`` in the above
+example), the contents of ``error`` are generally left unspecified.
+The decoding functions write to the ``position`` member also on
+success. See :ref:`apiref-decoding` for more info.
+
+All functions also accept *NULL* as the :type:`json_error_t` pointer,
+in which case no error information is returned to the caller.
+
+
+Encoding
+========
+
+This sections describes the functions that can be used to encode
+values to JSON. By default, only objects and arrays can be encoded
+directly, since they are the only valid *root* values of a JSON text.
+To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see
+below).
+
+By default, the output has no newlines, and spaces are used between
+array and object elements for a readable output. This behavior can be
+altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags
+described below. A newline is never appended to the end of the encoded
+JSON data.
+
+Each function takes a *flags* parameter that controls some aspects of
+how the data is encoded. Its default value is 0. The following macros
+can be ORed together to obtain *flags*.
+
+``JSON_INDENT(n)``
+   Pretty-print the result, using newlines between array and object
+   items, and indenting with *n* spaces. The valid range for *n* is
+   between 0 and 31 (inclusive), other values result in an undefined
+   output. If ``JSON_INDENT`` is not used or *n* is 0, no newlines are
+   inserted between array and object items.
+
+``JSON_COMPACT``
+   This flag enables a compact representation, i.e. sets the separator
+   between array and object items to ``","`` and between object keys
+   and values to ``":"``. Without this flag, the corresponding
+   separators are ``", "`` and ``": "`` for more readable output.
+
+``JSON_ENSURE_ASCII``
+   If this flag is used, the output is guaranteed to consist only of
+   ASCII characters. This is achived by escaping all Unicode
+   characters outside the ASCII range.
+
+``JSON_SORT_KEYS``
+   If this flag is used, all the objects in output are sorted by key.
+   This is useful e.g. if two JSON texts are diffed or visually
+   compared.
+
+``JSON_PRESERVE_ORDER``
+   If this flag is used, object keys in the output are sorted into the
+   same order in which they were first inserted to the object. For
+   example, decoding a JSON text and then encoding with this flag
+   preserves the order of object keys.
+
+``JSON_ENCODE_ANY``
+   Specifying this flag makes it possible to encode any JSON value on
+   its own. Without it, only objects and arrays can be passed as the
+   *root* value to the encoding functions.
+
+   **Note:** Encoding any value may be useful in some scenarios, but
+   it's generally discouraged as it violates strict compatiblity with
+   :rfc:`4627`. If you use this flag, don't expect interoperatibility
+   with other JSON systems.
+
+   .. versionadded:: 2.1
+
+``JSON_ESCAPE_SLASH``
+   Escape the ``/`` characters in strings with ``\/``.
+
+   .. versionadded:: 2.4
+
+The following functions perform the actual JSON encoding. The result
+is in UTF-8.
+
+.. function:: char *json_dumps(const json_t *root, size_t flags)
+
+   Returns the JSON representation of *root* as a string, or *NULL* on
+   error. *flags* is described above. The return value must be freed
+   by the caller using :func:`free()`.
+
+.. function:: int json_dumpf(const json_t *root, FILE *output, size_t flags)
+
+   Write the JSON representation of *root* to the stream *output*.
+   *flags* is described above. Returns 0 on success and -1 on error.
+   If an error occurs, something may have already been written to
+   *output*. In this case, the output is undefined and most likely not
+   valid JSON.
+
+.. function:: int json_dump_file(const json_t *json, const char *path, size_t flags)
+
+   Write the JSON representation of *root* to the file *path*. If
+   *path* already exists, it is overwritten. *flags* is described
+   above. Returns 0 on success and -1 on error.
+
+.. type:: json_dump_callback_t
+
+   A typedef for a function that's called by
+   :func:`json_dump_callback()`::
+
+       typedef int (*json_dump_callback_t)(const char *buffer, size_t size, void *data);
+
+   *buffer* points to a buffer containing a chunk of output, *size* is
+   the length of the buffer, and *data* is the corresponding
+   :func:`json_dump_callback()` argument passed through.
+
+   On error, the function should return -1 to stop the encoding
+   process. On success, it should return 0.
+
+   .. versionadded:: 2.2
+
+.. function:: int json_dump_callback(const json_t *json, json_dump_callback_t callback, void *data, size_t flags)
+
+   Call *callback* repeatedly, passing a chunk of the JSON
+   representation of *root* each time. *flags* is described above.
+   Returns 0 on success and -1 on error.
+
+   .. versionadded:: 2.2
+
+
+.. _apiref-decoding:
+
+Decoding
+========
+
+This sections describes the functions that can be used to decode JSON
+text to the Jansson representation of JSON data. The JSON
+specification requires that a JSON text is either a serialized array
+or object, and this requirement is also enforced with the following
+functions. In other words, the top level value in the JSON text being
+decoded must be either array or object. To decode any JSON value, use
+the ``JSON_DECODE_ANY`` flag (see below).
+
+See :ref:`rfc-conformance` for a discussion on Jansson's conformance
+to the JSON specification. It explains many design decisions that
+affect especially the behavior of the decoder.
+
+Each function takes a *flags* parameter that can be used to control
+the behavior of the decoder. Its default value is 0. The following
+macros can be ORed together to obtain *flags*.
+
+``JSON_REJECT_DUPLICATES``
+   Issue a decoding error if any JSON object in the input text
+   contains duplicate keys. Without this flag, the value of the last
+   occurence of each key ends up in the result. Key equivalence is
+   checked byte-by-byte, without special Unicode comparison
+   algorithms.
+
+   .. versionadded:: 2.1
+
+``JSON_DECODE_ANY``
+   By default, the decoder expects an array or object as the input.
+   With this flag enabled, the decoder accepts any valid JSON value.
+
+   **Note:** Decoding any value may be useful in some scenarios, but
+   it's generally discouraged as it violates strict compatiblity with
+   :rfc:`4627`. If you use this flag, don't expect interoperatibility
+   with other JSON systems.
+
+   .. versionadded:: 2.3
+
+``JSON_DISABLE_EOF_CHECK``
+   By default, the decoder expects that its whole input constitutes a
+   valid JSON text, and issues an error if there's extra data after
+   the otherwise valid JSON input. With this flag enabled, the decoder
+   stops after decoding a valid JSON array or object, and thus allows
+   extra data after the JSON text.
+
+   Normally, reading will stop when the last ``]`` or ``}`` in the
+   JSON input is encountered. If both ``JSON_DISABLE_EOF_CHECK`` and
+   ``JSON_DECODE_ANY`` flags are used, the decoder may read one extra
+   UTF-8 code unit (up to 4 bytes of input). For example, decoding
+   ``4true`` correctly decodes the integer 4, but also reads the
+   ``t``. For this reason, if reading multiple consecutive values that
+   are not arrays or objects, they should be separated by at least one
+   whitespace character.
+
+   .. versionadded:: 2.1
+
+``JSON_DECODE_INT_AS_REAL``
+   JSON defines only one number type. Jansson distinguishes between
+   ints and reals. For more information see :ref:`real-vs-integer`.
+   With this flag enabled the decoder interprets all numbers as real
+   values. Integers that do not have an exact double representation
+   will silently result in a loss of precision. Integers that cause
+   a double overflow will cause an error.
+
+   .. versionadded:: 2.5
+
+Each function also takes an optional :type:`json_error_t` parameter
+that is filled with error information if decoding fails. It's also
+updated on success; the number of bytes of input read is written to
+its ``position`` field. This is especially useful when using
+``JSON_DISABLE_EOF_CHECK`` to read multiple consecutive JSON texts.
+
+.. versionadded:: 2.3
+   Number of bytes of input read is written to the ``position`` field
+   of the :type:`json_error_t` structure.
+
+If no error or position information is needed, you can pass *NULL*.
+
+The following functions perform the actual JSON decoding.
+
+.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
+
+   .. refcounting:: new
+
+   Decodes the JSON string *input* and returns the array or object it
+   contains, or *NULL* on error, in which case *error* is filled with
+   information about the error. *flags* is described above.
+
+.. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error)
+
+   .. refcounting:: new
+
+   Decodes the JSON string *buffer*, whose length is *buflen*, and
+   returns the array or object it contains, or *NULL* on error, in
+   which case *error* is filled with information about the error. This
+   is similar to :func:`json_loads()` except that the string doesn't
+   need to be null-terminated. *flags* is described above.
+
+   .. versionadded:: 2.1
+
+.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
+
+   .. refcounting:: new
+
+   Decodes the JSON text in stream *input* and returns the array or
+   object it contains, or *NULL* on error, in which case *error* is
+   filled with information about the error. *flags* is described
+   above.
+
+   This function will start reading the input from whatever position
+   the input file was, without attempting to seek first. If an error
+   occurs, the file position will be left indeterminate. On success,
+   the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK``
+   flag was used. In this case, the file position will be at the first
+   character after the last ``]`` or ``}`` in the JSON input. This
+   allows calling :func:`json_loadf()` on the same ``FILE`` object
+   multiple times, if the input consists of consecutive JSON texts,
+   possibly separated by whitespace.
+
+.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
+
+   .. refcounting:: new
+
+   Decodes the JSON text in file *path* and returns the array or
+   object it contains, or *NULL* on error, in which case *error* is
+   filled with information about the error. *flags* is described
+   above.
+
+.. type:: json_load_callback_t
+
+   A typedef for a function that's called by
+   :func:`json_load_callback()` to read a chunk of input data::
+
+       typedef size_t (*json_load_callback_t)(void *buffer, size_t buflen, void *data);
+
+   *buffer* points to a buffer of *buflen* bytes, and *data* is the
+   corresponding :func:`json_load_callback()` argument passed through.
+
+   On success, the function should return the number of bytes read; a
+   returned value of 0 indicates that no data was read and that the
+   end of file has been reached. On error, the function should return
+   ``(size_t)-1`` to abort the decoding process.
+
+   .. versionadded:: 2.4
+
+.. function:: json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error)
+
+   .. refcounting:: new
+
+   Decodes the JSON text produced by repeated calls to *callback*, and
+   returns the array or object it contains, or *NULL* on error, in
+   which case *error* is filled with information about the error.
+   *data* is passed through to *callback* on each call. *flags* is
+   described above.
+
+   .. versionadded:: 2.4
+
+
+.. _apiref-pack:
+
+Building Values
+===============
+
+This section describes functions that help to create, or *pack*,
+complex JSON values, especially nested objects and arrays. Value
+building is based on a *format string* that is used to tell the
+functions about the expected arguments.
+
+For example, the format string ``"i"`` specifies a single integer
+value, while the format string ``"[ssb]"`` or the equivalent ``"[s, s,
+b]"`` specifies an array value with two strings and a boolean as its
+items::
+
+    /* Create the JSON integer 42 */
+    json_pack("i", 42);
+
+    /* Create the JSON array ["foo", "bar", true] */
+    json_pack("[ssb]", "foo", "bar", 1);
+
+Here's the full list of format specifiers. The type in parentheses
+denotes the resulting JSON type, and the type in brackets (if any)
+denotes the C type that is expected as the corresponding argument or
+arguments.
+
+``s`` (string) [const char \*]
+    Convert a NULL terminated UTF-8 string to a JSON string.
+
+``s#`` (string) [const char \*, int]
+    Convert a UTF-8 buffer of a given length to a JSON string.
+
+``+`` [const char \*]
+    Like ``s``, but concatenate to the previous string. Only valid
+    after ``s``, ``s#``, ``+`` or ``+#``.
+
+``+#`` [const char \*, int]
+    Like ``s#``, but concatenate to the previous string. Only valid
+    after ``s``, ``s#``, ``+`` or ``+#``.
+
+``n`` (null)
+    Output a JSON null value. No argument is consumed.
+
+``b`` (boolean) [int]
+    Convert a C :type:`int` to JSON boolean value. Zero is converted
+    to ``false`` and non-zero to ``true``.
+
+``i`` (integer) [int]
+    Convert a C :type:`int` to JSON integer.
+
+``I`` (integer) [json_int_t]
+    Convert a C :type:`json_int_t` to JSON integer.
+
+``f`` (real) [double]
+    Convert a C :type:`double` to JSON real.
+
+``o`` (any value) [json_t \*]
+    Output any given JSON value as-is. If the value is added to an
+    array or object, the reference to the value passed to ``o`` is
+    stolen by the container.
+
+``O`` (any value) [json_t \*]
+    Like ``o``, but the argument's reference count is incremented.
+    This is useful if you pack into an array or object and want to
+    keep the reference for the JSON value consumed by ``O`` to
+    yourself.
+
+``[fmt]`` (array)
+    Build an array with contents from the inner format string. ``fmt``
+    may contain objects and arrays, i.e. recursive value building is
+    supported.
+
+``{fmt}`` (object)
+    Build an object with contents from the inner format string
+    ``fmt``. The first, third, etc. format specifier represent a key,
+    and must be a string (see ``s``, ``s#``, ``+`` and ``+#`` above),
+    as object keys are always strings. The second, fourth, etc. format
+    specifier represent a value. Any value may be an object or array,
+    i.e. recursive value building is supported.
+
+Whitespace, ``:`` and ``,`` are ignored.
+
+The following functions compose the value building API:
+
+.. function:: json_t *json_pack(const char *fmt, ...)
+
+   .. refcounting:: new
+
+   Build a new JSON value according to the format string *fmt*. For
+   each format specifier (except for ``{}[]n``), one or more arguments
+   are consumed and used to build the corresponding value. Returns
+   *NULL* on error.
+
+.. function:: json_t *json_pack_ex(json_error_t *error, size_t flags, const char *fmt, ...)
+              json_t *json_vpack_ex(json_error_t *error, size_t flags, const char *fmt, va_list ap)
+
+   .. refcounting:: new
+
+   Like :func:`json_pack()`, but an in the case of an error, an error
+   message is written to *error*, if it's not *NULL*. The *flags*
+   parameter is currently unused and should be set to 0.
+
+   As only the errors in format string (and out-of-memory errors) can
+   be caught by the packer, these two functions are most likely only
+   useful for debugging format strings.
+
+More examples::
+
+  /* Build an empty JSON object */
+  json_pack("{}");
+
+  /* Build the JSON object {"foo": 42, "bar": 7} */
+  json_pack("{sisi}", "foo", 42, "bar", 7);
+
+  /* Like above, ':', ',' and whitespace are ignored */
+  json_pack("{s:i, s:i}", "foo", 42, "bar", 7);
+
+  /* Build the JSON array [[1, 2], {"cool": true}] */
+  json_pack("[[i,i],{s:b}]", 1, 2, "cool", 1);
+
+  /* Build a string from a non-NUL terminated buffer */
+  char buffer[4] = {'t', 'e', 's', 't'};
+  json_pack("s#", buffer, 4);
+
+  /* Concatentate strings together to build the JSON string "foobarbaz" */
+  json_pack("s++", "foo", "bar", "baz");
+
+
+.. _apiref-unpack:
+
+Parsing and Validating Values
+=============================
+
+This section describes functions that help to validate complex values
+and extract, or *unpack*, data from them. Like :ref:`building values
+<apiref-pack>`, this is also based on format strings.
+
+While a JSON value is unpacked, the type specified in the format
+string is checked to match that of the JSON value. This is the
+validation part of the process. In addition to this, the unpacking
+functions can also check that all items of arrays and objects are
+unpacked. This check be enabled with the format specifier ``!`` or by
+using the flag ``JSON_STRICT``. See below for details.
+
+Here's the full list of format specifiers. The type in parentheses
+denotes the JSON type, and the type in brackets (if any) denotes the C
+type whose address should be passed.
+
+``s`` (string) [const char \*]
+    Convert a JSON string to a pointer to a NULL terminated UTF-8
+    string. The resulting string is extracted by using
+    :func:`json_string_value()` internally, so it exists as long as
+    there are still references to the corresponding JSON string.
+
+``n`` (null)
+    Expect a JSON null value. Nothing is extracted.
+
+``b`` (boolean) [int]
+    Convert a JSON boolean value to a C :type:`int`, so that ``true``
+    is converted to 1 and ``false`` to 0.
+
+``i`` (integer) [int]
+    Convert a JSON integer to C :type:`int`.
+
+``I`` (integer) [json_int_t]
+    Convert a JSON integer to C :type:`json_int_t`.
+
+``f`` (real) [double]
+    Convert a JSON real to C :type:`double`.
+
+``F`` (integer or real) [double]
+    Convert a JSON number (integer or real) to C :type:`double`.
+
+``o`` (any value) [json_t \*]
+    Store a JSON value with no conversion to a :type:`json_t` pointer.
+
+``O`` (any value) [json_t \*]
+    Like ``O``, but the JSON value's reference count is incremented.
+
+``[fmt]`` (array)
+    Convert each item in the JSON array according to the inner format
+    string. ``fmt`` may contain objects and arrays, i.e. recursive
+    value extraction is supporetd.
+
+``{fmt}`` (object)
+    Convert each item in the JSON object according to the inner format
+    string ``fmt``. The first, third, etc. format specifier represent
+    a key, and must be ``s``. The corresponding argument to unpack
+    functions is read as the object key. The second fourth, etc.
+    format specifier represent a value and is written to the address
+    given as the corresponding argument. **Note** that every other
+    argument is read from and every other is written to.
+
+    ``fmt`` may contain objects and arrays as values, i.e. recursive
+    value extraction is supporetd.
+
+    .. versionadded:: 2.3
+       Any ``s`` representing a key may be suffixed with a ``?`` to
+       make the key optional. If the key is not found, nothing is
+       extracted. See below for an example.
+
+``!``
+    This special format specifier is used to enable the check that
+    all object and array items are accessed, on a per-value basis. It
+    must appear inside an array or object as the last format specifier
+    before the closing bracket or brace. To enable the check globally,
+    use the ``JSON_STRICT`` unpacking flag.
+
+``*``
+    This special format specifier is the opposite of ``!``. If the
+    ``JSON_STRICT`` flag is used, ``*`` can be used to disable the
+    strict check on a per-value basis. It must appear inside an array
+    or object as the last format specifier before the closing bracket
+    or brace.
+
+Whitespace, ``:`` and ``,`` are ignored.
+
+The following functions compose the parsing and validation API:
+
+.. function:: int json_unpack(json_t *root, const char *fmt, ...)
+
+   Validate and unpack the JSON value *root* according to the format
+   string *fmt*. Returns 0 on success and -1 on failure.
+
+.. function:: int json_unpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, ...)
+              int json_vunpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, va_list ap)
+
+   Validate and unpack the JSON value *root* according to the format
+   string *fmt*. If an error occurs and *error* is not *NULL*, write
+   error information to *error*. *flags* can be used to control the
+   behaviour of the unpacker, see below for the flags. Returns 0 on
+   success and -1 on failure.
+
+.. note::
+
+   The first argument of all unpack functions is ``json_t *root``
+   instead of ``const json_t *root``, because the use of ``O`` format
+   specifier causes the reference count of ``root``, or some value
+   reachable from ``root``, to be increased. Furthermore, the ``o``
+   format specifier may be used to extract a value as-is, which allows
+   modifying the structure or contents of a value reachable from
+   ``root``.
+
+   If the ``O`` and ``o`` format specifiers are not used, it's
+   perfectly safe to cast a ``const json_t *`` variable to plain
+   ``json_t *`` when used with these functions.
+
+The following unpacking flags are available:
+
+``JSON_STRICT``
+    Enable the extra validation step checking that all object and
+    array items are unpacked. This is equivalent to appending the
+    format specifier ``!`` to the end of every array and object in the
+    format string.
+
+``JSON_VALIDATE_ONLY``
+    Don't extract any data, just validate the JSON value against the
+    given format string. Note that object keys must still be specified
+    after the format string.
+
+Examples::
+
+    /* root is the JSON integer 42 */
+    int myint;
+    json_unpack(root, "i", &myint);
+    assert(myint == 42);
+
+    /* root is the JSON object {"foo": "bar", "quux": true} */
+    const char *str;
+    int boolean;
+    json_unpack(root, "{s:s, s:b}", "foo", &str, "quux", &boolean);
+    assert(strcmp(str, "bar") == 0 && boolean == 1);
+
+    /* root is the JSON array [[1, 2], {"baz": null} */
+    json_error_t error;
+    json_unpack_ex(root, &error, JSON_VALIDATE_ONLY, "[[i,i], {s:n}]", "baz");
+    /* returns 0 for validation success, nothing is extracted */
+
+    /* root is the JSON array [1, 2, 3, 4, 5] */
+    int myint1, myint2;
+    json_unpack(root, "[ii!]", &myint1, &myint2);
+    /* returns -1 for failed validation */
+
+    /* root is an empty JSON object */
+    int myint = 0, myint2 = 0;
+    json_unpack(root, "{s?i, s?[ii]}",
+                "foo", &myint1,
+                "bar", &myint2, &myint3);
+    /* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */
+
+
+Equality
+========
+
+Testing for equality of two JSON values cannot, in general, be
+achieved using the ``==`` operator. Equality in the terms of the
+``==`` operator states that the two :type:`json_t` pointers point to
+exactly the same JSON value. However, two JSON values can be equal not
+only if they are exactly the same value, but also if they have equal
+"contents":
+
+* Two integer or real values are equal if their contained numeric
+  values are equal. An integer value is never equal to a real value,
+  though.
+
+* Two strings are equal if their contained UTF-8 strings are equal,
+  byte by byte. Unicode comparison algorithms are not implemented.
+
+* Two arrays are equal if they have the same number of elements and
+  each element in the first array is equal to the corresponding
+  element in the second array.
+
+* Two objects are equal if they have exactly the same keys and the
+  value for each key in the first object is equal to the value of the
+  corresponding key in the second object.
+
+* Two true, false or null values have no "contents", so they are equal
+  if their types are equal. (Because these values are singletons,
+  their equality can actually be tested with ``==``.)
+
+The following function can be used to test whether two JSON values are
+equal.
+
+.. function:: int json_equal(json_t *value1, json_t *value2)
+
+   Returns 1 if *value1* and *value2* are equal, as defined above.
+   Returns 0 if they are inequal or one or both of the pointers are
+   *NULL*.
+
+
+Copying
+=======
+
+Because of reference counting, passing JSON values around doesn't
+require copying them. But sometimes a fresh copy of a JSON value is
+needed. For example, if you need to modify an array, but still want to
+use the original afterwards, you should take a copy of it first.
+
+Jansson supports two kinds of copying: shallow and deep. There is a
+difference between these methods only for arrays and objects. Shallow
+copying only copies the first level value (array or object) and uses
+the same child values in the copied value. Deep copying makes a fresh
+copy of the child values, too. Moreover, all the child values are deep
+copied in a recursive fashion.
+
+.. function:: json_t *json_copy(json_t *value)
+
+   .. refcounting:: new
+
+   Returns a shallow copy of *value*, or *NULL* on error.
+
+.. function:: json_t *json_deep_copy(const json_t *value)
+
+   .. refcounting:: new
+
+   Returns a deep copy of *value*, or *NULL* on error.
+
+
+.. _apiref-custom-memory-allocation:
+
+Custom Memory Allocation
+========================
+
+By default, Jansson uses :func:`malloc()` and :func:`free()` for
+memory allocation. These functions can be overridden if custom
+behavior is needed.
+
+.. type:: json_malloc_t
+
+   A typedef for a function pointer with :func:`malloc()`'s
+   signature::
+
+       typedef void *(*json_malloc_t)(size_t);
+
+.. type:: json_free_t
+
+   A typedef for a function pointer with :func:`free()`'s
+   signature::
+
+       typedef void (*json_free_t)(void *);
+
+.. function:: void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn)
+
+   Use *malloc_fn* instead of :func:`malloc()` and *free_fn* instead
+   of :func:`free()`. This function has to be called before any other
+   Jansson's API functions to ensure that all memory operations use
+   the same functions.
+
+**Examples:**
+
+Circumvent problems with different CRT heaps on Windows by using
+application's :func:`malloc()` and :func:`free()`::
+
+    json_set_alloc_funcs(malloc, free);
+
+Use the `Boehm's conservative garbage collector`_ for memory
+operations::
+
+    json_set_alloc_funcs(GC_malloc, GC_free);
+
+.. _Boehm's conservative garbage collector: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
+
+Allow storing sensitive data (e.g. passwords or encryption keys) in
+JSON structures by zeroing all memory when freed::
+
+    static void *secure_malloc(size_t size)
+    {
+        /* Store the memory area size in the beginning of the block */
+        void *ptr = malloc(size + 8);
+        *((size_t *)ptr) = size;
+        return ptr + 8;
+    }
+
+    static void secure_free(void *ptr)
+    {
+        size_t size;
+
+        ptr -= 8;
+        size = *((size_t *)ptr);
+
+        guaranteed_memset(ptr, 0, size);
+        free(ptr);
+    }
+
+    int main()
+    {
+        json_set_alloc_funcs(secure_malloc, secure_free);
+        /* ... */
+    }
+
+For more information about the issues of storing sensitive data in
+memory, see
+http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html.
+The page also explains the :func:`guaranteed_memset()` function used
+in the example and gives a sample implementation for it.