Commit eb410d4b authored by Alessandro Ghedini's avatar Alessandro Ghedini

Imported Upstream version 2.0

parent da6c6196
......@@ -24,4 +24,4 @@ missing
stamp-h1
*.pyc
*.pc
/src/jansson.h
/src/jansson_config.h
Version 2.0
===========
Released 2011-02-28
This release is backwards incompatible with the 1.x release series.
See the chapter "Upgrading from older versions" in documentation for
details.
* Backwards incompatible changes:
- Unify unsigned integer usage in the API: All occurences of
unsigned int and unsigned long have been replaced with size_t.
- Change JSON integer's underlying type to the widest signed integer
type available, i.e. long long if it's supported, otherwise long.
Add a typedef json_int_t that defines the type.
- Change the maximum indentation depth to 31 spaces in encoder. This
frees up bits from the flags parameter of encoding functions
`json_dumpf()`, `json_dumps()` and `json_dump_file()`.
- For future needs, add a flags parameter to all decoding functions
`json_loadf()`, `json_loads()` and `json_load_file()`.
* New features
- `json_pack()`, `json_pack_ex()`, `json_vpack_ex()`: Create JSON
values based on a format string.
- `json_unpack()`, `json_unpack_ex()`, `json_vunpack_ex()`: Simple
value extraction and validation functionality based on a format
string.
- Add column, position and source fields to the ``json_error_t``
struct.
- Enhance error reporting in the decoder.
- ``JANSSON_VERSION`` et al.: Preprocessor constants that define the
library version.
- `json_set_alloc_funcs()`: Set custom memory allocation functions.
* Fix many portability issues, especially on Windows.
* Configuration
- Add file ``jansson_config.h`` that contains site specific
configuration. It's created automatically by the configure script,
or can be created by hand if the configure script cannot be used.
The file ``jansson_config.h.win32`` can be used without
modifications on Windows systems.
- Add a section to documentation describing how to build Jansson on
Windows.
- Documentation now requires Sphinx 1.0 or newer.
Version 1.3
===========
Released 2010-06-13
* New functions:
- `json_object_iter_set()`, `json_object_iter_set_new()`: Change
object contents while iterating over it.
- `json_object_iter_at()`: Return an iterator that points to a
specific object item.
* New encoding flags:
- ``JSON_PRESERVE_ORDER``: Preserve the insertion order of object
......
Copyright (c) 2009, 2010 Petri Lehtinen <petri@digip.org>
Copyright (c) 2009-2011 Petri Lehtinen <petri@digip.org>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
......
EXTRA_DIST = CHANGES LICENSE README.rst
SUBDIRS = doc src test
check-local: html
check-doc:
$(MAKE) SPHINXOPTS_EXTRA=-W html
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = jansson.pc
......@@ -24,7 +24,13 @@ Compilation and Installation
If you obtained a source tarball, just use the standard autotools
commands::
$ ./configure && make && make install
$ ./configure
$ make
$ make install
To run the test suite, invoke::
$ make check
If the source has been checked out from a Git repository, the
./configure script has to be generated fist. The easiest way is to use
......@@ -32,28 +38,22 @@ autoreconf::
$ autoreconf -i
To run the test suite, invoke::
$ make check
Documentation
-------------
Documentation is in the ``doc/`` subdirectory. It's written in
reStructuredText_ with Sphinx_ annotations, so reading it in plain may
be inconvenient. For this reason, prebuilt HTML documentation is
available at http://www.digip.org/jansson/doc/.
Prebuilt HTML documentation is available at
http://www.digip.org/jansson/doc/.
To generate HTML documentation yourself, invoke::
The documentation source is in the ``doc/`` subdirectory. To generate
HTML documentation, invoke::
make html
$ make html
and point your browser to ``doc/_build/html/index.html``. Sphinx_ is
required to generate the documentation.
Then, point your browser to ``doc/_build/html/index.html``. Sphinx_
1.0 or newer is required to generate the documentation.
.. _Jansson: http://www.digip.org/jansson/
.. _`MIT license`: http://www.opensource.org/licenses/mit-license.php
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org/
AC_PREREQ([2.60])
AC_INIT([jansson], [1.3], [petri@digip.org])
AC_INIT([jansson], [2.0], [petri@digip.org])
AM_INIT_AUTOMAKE([1.10 foreign])
......@@ -8,8 +8,8 @@ AC_CONFIG_HEADERS([config.h])
# Checks for programs.
AC_PROG_CC
AC_PROG_CXX
AC_PROG_LIBTOOL
AM_CONDITIONAL([GCC], [test x$GCC = xyes])
# Checks for libraries.
......@@ -18,6 +18,13 @@ AC_PROG_LIBTOOL
# Checks for typedefs, structures, and compiler characteristics.
AC_TYPE_INT32_T
AC_TYPE_LONG_LONG_INT
case $ac_cv_type_long_long_int in
yes) json_have_long_long=1;;
*) json_have_long_long=0;;
esac
AC_SUBST([json_have_long_long])
AC_C_INLINE
case $ac_cv_c_inline in
yes) json_inline=inline;;
......@@ -33,7 +40,7 @@ AC_CONFIG_FILES([
Makefile
doc/Makefile
src/Makefile
src/jansson.h
src/jansson_config.h
test/Makefile
test/bin/Makefile
test/suites/Makefile
......
......@@ -3,7 +3,7 @@ EXTRA_DIST = conf.py apiref.rst changes.rst conformance.rst \
ext/refcounting.py
SPHINXBUILD = sphinx-build
SPHINXOPTS = -d _build/doctrees -W
SPHINXOPTS = -d _build/doctrees $(SPHINXOPTS_EXTRA)
html-local:
$(SPHINXBUILD) -b html $(SPHINXOPTS) $(srcdir) _build/html
......
This diff is collapsed.
# -*- coding: utf-8 -*-
#
# Jansson documentation build configuration file, created by
# sphinx-quickstart on Thu Jul 30 11:35:32 2009.
# sphinx-quickstart on Sun Sep 5 21:47:20 2010.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# The contents of this file are pickled, so don't put values in the namespace
# that aren't pickleable (module imports are okay, they're removed automatically).
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
......@@ -15,44 +12,45 @@
# serve to show the default.
import sys, os
sys.path.insert(0, os.path.abspath('ext'))
# If your extensions (or modules documented by autodoc) are in another directory,
# 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.append(os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('ext'))
# -- General configuration -----------------------------------------------------
# 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_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8'
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Jansson'
copyright = u'2009, 2010 Petri Lehtinen'
copyright = u'2009-2011, 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 = '1.3'
version = '2.0'
# The full version, including alpha/beta/rc tags.
release = '1.3'
release = '2.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -64,15 +62,13 @@ release = '1.3'
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of documents that shouldn't be included in the build.
#unused_docs = []
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = ['_build']
# 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 = 'cfunc'
default_role = 'c:func'
primary_domain = 'c'
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
......@@ -88,14 +84,23 @@ default_role = 'cfunc'
# 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'
# Options for HTML output
# -----------------------
# 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 = {}
# The style sheet to use for HTML and HTML Help pages. A file of that name
# must exist either in Sphinx' static/ path, or in one of the custom paths
# given in html_static_path.
html_style = 'default.css'
# 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
# "<project> v<release> documentation".
......@@ -116,7 +121,7 @@ html_style = 'default.css'
# 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 = []
#html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
......@@ -134,7 +139,7 @@ html_static_path = []
#html_additional_pages = {}
# If false, no module index is generated.
#html_use_modindex = True
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
......@@ -142,23 +147,28 @@ html_static_path = []
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, the reST sources are included in the HTML build as _sources/<name>.
#html_copy_source = True
# 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 <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''
# 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
# ------------------------
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
......@@ -167,10 +177,10 @@ htmlhelp_basename = 'Janssondoc'
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'Jansson.tex', ur'Jansson Documentation',
ur'Petri Lehtinen', 'manual'),
('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
......@@ -181,6 +191,12 @@ latex_documents = [
# 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 = ''
......@@ -188,4 +204,14 @@ latex_documents = [
#latex_appendices = []
# If false, no module index is generated.
#latex_use_modindex = True
#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)
]
.. _rfc-conformance:
***************
RFC Conformance
***************
......@@ -36,7 +38,9 @@ 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 ``int`` type.
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
......@@ -54,19 +58,19 @@ 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
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`` type will result in an overflow error (a JSON decoding
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 ``int`` type will result in an overflow error (a
JSON decoding error). Thus, depending on platform, JSON numbers like
1000000000000000 may result in parsing error.
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
......@@ -94,9 +98,9 @@ Types
-----
No support is provided in Jansson for any C numeric types other than
``int`` and ``double``. This excludes things such as unsigned types,
``long``, ``long long``, ``long double``, etc. Obviously, shorter
types like ``short`` 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.
``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.
......@@ -19,7 +19,7 @@
<description of the json_object function>
:copyright: Copyright (c) 2009, 2010 Petri Lehtinen <petri@digip.org>
:copyright: Copyright (c) 2009-2011 Petri Lehtinen <petri@digip.org>
:license: MIT, see LICENSE for details.
"""
......
......@@ -10,6 +10,9 @@ Compiling and Installing Jansson
The Jansson source is available at
http://www.digip.org/jansson/releases/.
Unix-like systems
-----------------
Unpack the source tarball and change to the source directory:
.. parsed-literal::
......@@ -37,7 +40,7 @@ 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, Autotools needs to be
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``::
......@@ -51,18 +54,30 @@ used as described above.
.. _libtool: http://www.gnu.org/software/libtool/
Installing Prebuilt Binary Packages
-----------------------------------
Other Systems
-------------
On Windows and other 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``. This file has some platform-specific
parameters that are normally filled in by the ``./configure``
script:
- On Windows, rename ``jansson_config.h.win32`` to ``jansson_config.h``.
Binary ``.deb`` packages for Ubuntu are available in `this PPA`_ at
Launchpad_. Follow the instructions in the PPA ("Technical details
about this PPA" link) to take the PPA into use. Then install the -dev
package::
- On other systems, edit ``jansson_config.h.in``, replacing all
``@variable@`` placeholders, and rename the file to
``jansson_config.h``.
sudo apt-get install libjansson-dev
2. Make ``jansson.h`` and ``jansson_config.h`` available to the
compiler, so that they can be found when compiling programs that
use Jansson.
.. _this PPA: http://launchpad.net/~petri/+archive/ppa
.. _Launchpad: http://launchpad.net/
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
......@@ -77,14 +92,14 @@ documentation, invoke::
make html
and point your browser to ``doc/_build/html/index.html``. Sphinx_ is
required to generate the documentation.
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
Compiling Programs that Use Jansson
===================================
Jansson involves one C header file, :file:`jansson.h`, so it's enough
......
/*
* Copyright (c) 2009, 2010 Petri Lehtinen <petri@digip.org>
* Copyright (c) 2009-2011 Petri Lehtinen <petri@digip.org>
*
* Jansson is free software; you can redistribute it and/or modify
* it under the terms of the MIT license. See LICENSE for details.
......@@ -96,7 +96,7 @@ static char *request(const char *url)
int main(int argc, char *argv[])
{
unsigned int i;
size_t i;
char *text;
char url[URL_SIZE];
......@@ -117,7 +117,7 @@ int main(int argc, char *argv[])
if(!text)
return 1;
root = json_loads(text, &error);
root = json_loads(text, 0, &error);
free(text);
if(!root)
......
......@@ -33,6 +33,7 @@ Contents
:maxdepth: 2
gettingstarted
upgrading
tutorial
conformance
apiref
......
......@@ -118,7 +118,7 @@ first newline in the commit message::
The main function follows. In the beginning, we first declare a bunch
of variables and check the command line parameters::
unsigned int i;
size_t i;
char *text;
char url[URL_SIZE];
......@@ -149,10 +149,10 @@ 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 :cfunc:`json_loads()` to decode the JSON text we got
Next we'll call :func:`json_loads()` to decode the JSON text we got
as a response::
root = json_loads(text, &error);
root = json_loads(text, 0, &error);
free(text);
if(!root)
......@@ -162,8 +162,8 @@ as a response::
}
We don't need the JSON text anymore, so we can free the ``text``
variable right after decoding it. If :cfunc:`json_loads()` fails, it
returns *NULL* and sets error information to the :ctype:`json_error_t`
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.
......@@ -182,8 +182,8 @@ First, we'll extract the ``commits`` array from the JSON response::
This is the array that contains objects describing latest commits in
the repository. We check that the returned value really is an array.
If the key ``commits`` doesn't exist, :cfunc:`json_object_get()`
returns *NULL*, but :cfunc:`json_is_array()` handles this case, too.
If the key ``commits`` doesn't exist, :func:`json_object_get()`
returns *NULL*, but :func:`json_is_array()` handles this case, too.
Then we proceed to loop over all the commits in the array::
......@@ -200,9 +200,9 @@ Then we proceed to loop over all the commits in the array::
}
...
The function :cfunc:`json_array_size()` returns the size of a JSON
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 ``commits`` array using :cfunc:`json_array_get()`.
i'th element of the ``commits`` array using :func:`json_array_get()`.
We also check that the resulting value is a JSON object.
Next we'll extract the commit ID and commit message, and check that
......@@ -225,7 +225,7 @@ they both are JSON strings::
And finally, we'll print the first 8 characters of the commit ID and