mirror of
https://github.com/akheron/jansson.git
synced 2025-04-05 05:25:04 +00:00
Enhance documentation
- Add more information to the documentation front page - Document how to build the documentation - Clarify the tutorial a bit and remove some quirks - Bring README.rst up-to-date - Small enhancements here and there
This commit is contained in:
Petri Lehtinen
parent
a83cd30c31
commit
cd96049d10
5 changed files with 92 additions and 52 deletions
|
|
@ -6,14 +6,14 @@ data. Its main features and design principles are:
|
|||
|
||||
- Simple and intuitive API and data model
|
||||
|
||||
- Good documentation
|
||||
- Comprehensive documentation
|
||||
|
||||
- No dependencies on other libraries
|
||||
|
||||
- Full Unicode support (UTF-8)
|
||||
|
||||
- Extensive test suite
|
||||
|
||||
- No dependencies on other libraries
|
||||
|
||||
Jansson is licensed under the `MIT license`_; see LICENSE in the
|
||||
source distribution for details.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,11 +7,8 @@ Getting Started
|
|||
Compiling and Installing Jansson
|
||||
================================
|
||||
|
||||
This chapter explains how to compile and install the library itself.
|
||||
|
||||
|
||||
Compiling and Installing from a Source Tarball
|
||||
----------------------------------------------
|
||||
The Jansson source is available at
|
||||
http://www.digip.org/jansson/releases/.
|
||||
|
||||
Unpack the source tarball and change to the source directory:
|
||||
|
||||
|
|
@ -34,17 +31,9 @@ the ``--prefix=DIR`` argument to ``./configure``. See ``./configure
|
|||
no options to customize the resulting Jansson binary.)
|
||||
|
||||
The command ``make check`` runs the test suite distributed with
|
||||
Jansson. This step is not strictly necessary, but it may find possible
|
||||
problems that Jansson has on your platform. If any problems are found,
|
||||
please report them.
|
||||
|
||||
.. _autoconf: http://www.gnu.org/software/autoconf/
|
||||
.. _automake: http://www.gnu.org/software/automake/
|
||||
.. _libtool: http://www.gnu.org/software/libtool/
|
||||
|
||||
|
||||
Compiling and Installing from Git
|
||||
---------------------------------
|
||||
Jansson. Python_ is required to run the tests. 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
|
||||
|
|
@ -57,21 +46,45 @@ to use ``autoreconf``::
|
|||
This command creates the ``./configure`` script, which can then be
|
||||
used as described in the previous section.
|
||||
|
||||
.. _autoconf: http://www.gnu.org/software/autoconf/
|
||||
.. _automake: http://www.gnu.org/software/automake/
|
||||
.. _libtool: http://www.gnu.org/software/libtool/
|
||||
.. _Python: http://www.python.org/
|
||||
|
||||
|
||||
Installing Prebuilt Binary Packages
|
||||
-----------------------------------
|
||||
|
||||
Binary ``.deb`` packages for Ubuntu are available in the `Jansson
|
||||
PPA`_ at Launchpad_. Follow the instructions in the PPA ("Read about
|
||||
installing" link) to take the PPA into use. Then install the -dev
|
||||
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::
|
||||
|
||||
apt-get install libjansson-dev
|
||||
sudo apt-get install libjansson-dev
|
||||
|
||||
.. _Jansson PPA: http://launchpad.net/~petri/+archive/ppa
|
||||
.. _this PPA: http://launchpad.net/~petri/+archive/ppa
|
||||
.. _Launchpad: http://launchpad.net/
|
||||
|
||||
|
||||
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::
|
||||
|
||||
cd doc/
|
||||
sphinx-build . .build/html
|
||||
|
||||
... and point your browser to ``.build/html/index.html``. Sphinx_ is
|
||||
required to generate the documentation.
|
||||
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
.. _Sphinx: http://sphinx.pocoo.org/
|
||||
|
||||
|
||||
Compiling Programs Using Jansson
|
||||
================================
|
||||
|
|
|
|||
|
|
@ -120,7 +120,7 @@ int main(int argc, char *argv[])
|
|||
}
|
||||
|
||||
commits = json_object_get(root, "commits");
|
||||
if(!commits || !json_is_array(commits))
|
||||
if(!json_is_array(commits))
|
||||
{
|
||||
fprintf(stderr, "error: commits is not an array\n");
|
||||
return 1;
|
||||
|
|
@ -139,14 +139,14 @@ int main(int argc, char *argv[])
|
|||
}
|
||||
|
||||
id = json_object_get(commit, "id");
|
||||
if(!id || !json_is_string(id))
|
||||
if(!json_is_string(id))
|
||||
{
|
||||
fprintf(stderr, "error: commit %d: id is not a string\n", i + 1);
|
||||
return 1;
|
||||
}
|
||||
|
||||
message = json_object_get(commit, "message");
|
||||
if(!message || !json_is_string(message))
|
||||
if(!json_is_string(message))
|
||||
{
|
||||
fprintf(stderr, "error: commit %d: message is not a string\n", i + 1);
|
||||
return 1;
|
||||
|
|
|
|||
|
|
@ -1,11 +1,33 @@
|
|||
Overview
|
||||
========
|
||||
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.
|
||||
|
||||
|
||||
.. _`MIT license`: http://www.opensource.org/licenses/mit-license.php
|
||||
.. _Jansson: http://www.digip.org/jansson/
|
||||
|
||||
**Contents:**
|
||||
Contents
|
||||
--------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
|
|||
|
|
@ -41,16 +41,12 @@ starts to respond with an error.
|
|||
The GitHub Commits API
|
||||
======================
|
||||
|
||||
The GitHub commits API is used by sending HTTP requests to URLs
|
||||
The `GitHub commits API`_ is used by sending HTTP requests to URLs
|
||||
starting with ``http://github.com/api/v2/json/commits/``. Our program
|
||||
only lists the latest commits, so the rest of the URL is
|
||||
``list/USER/REPOSITORY/BRANCH``, where ``USER``, ``REPOSITORY`` and
|
||||
``BRANCH`` are the GitHub user ID, the name of the repository, and the
|
||||
name of the branch whose commits are to be listed, respectively. The
|
||||
following definitions are used to build the request URL::
|
||||
|
||||
#define URL_FORMAT "http://github.com/api/v2/json/commits/list/%s/%s/master"
|
||||
#define URL_SIZE 256
|
||||
name of the branch whose commits are to be listed, respectively.
|
||||
|
||||
GitHub responds with a JSON object of the following form:
|
||||
|
||||
|
|
@ -78,10 +74,13 @@ function::
|
|||
static char *request(const char *url);
|
||||
|
||||
It takes the URL as a parameter, preforms a HTTP GET request, and
|
||||
returns a newly allocated string that contains the response body. For
|
||||
full details, refer to :download:`the code <github_commits.c>`, as the
|
||||
actual implementation is not important here.
|
||||
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
|
||||
<github_commits.c>`, as the actual implementation is not important
|
||||
here.
|
||||
|
||||
.. _GitHub commits API: http://develop.github.com/p/commits.html
|
||||
|
||||
.. _tutorial-the-program:
|
||||
|
||||
|
|
@ -96,6 +95,12 @@ First the includes::
|
|||
Like all the programs using Jansson, we need to include
|
||||
:file:`jansson.h`.
|
||||
|
||||
The following definitions are used to build the GitHub commits API
|
||||
request URL::
|
||||
|
||||
#define URL_FORMAT "http://github.com/api/v2/json/commits/list/%s/%s/master"
|
||||
#define URL_SIZE 256
|
||||
|
||||
The following function is used when formatting the result to find the
|
||||
first newline in the commit message::
|
||||
|
||||
|
|
@ -161,22 +166,24 @@ variable right after decoding it. If :cfunc:`json_loads()` fails, it
|
|||
returns *NULL* and sets error information to the :ctype:`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.
|
||||
This check is really only to be sure, because we can assume that the
|
||||
GitHub API returns correct JSON to us.
|
||||
|
||||
Next, we'll extract the ``commits`` array from the JSON response::
|
||||
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`.
|
||||
|
||||
First, we'll extract the ``commits`` array from the JSON response::
|
||||
|
||||
commits = json_object_get(root, "commits");
|
||||
if(!commits || !json_is_array(commits))
|
||||
if(!json_is_array(commits))
|
||||
{
|
||||
fprintf(stderr, "error: commits is not an array\n");
|
||||
return 1;
|
||||
}
|
||||
|
||||
This is the array that contains objects describing latest commits in
|
||||
the repository. If the key ``commits`` doesn't exist,
|
||||
:cfunc:`json_object_get()` returns *NULL*. We also check that the
|
||||
returned value really is an array.
|
||||
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.
|
||||
|
||||
Then we proceed to loop over all the commits in the array::
|
||||
|
||||
|
|
@ -196,22 +203,20 @@ Then we proceed to loop over all the commits in the array::
|
|||
The function :cfunc:`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()`.
|
||||
We also check that the resulting value is a JSON object. (The
|
||||
structure of the response JSON was explained in
|
||||
:ref:`tutorial-github-commits-api`).
|
||||
We also check that the resulting value is a JSON object.
|
||||
|
||||
Next we'll extract the commit ID and commit message, and check that
|
||||
they both are JSON strings::
|
||||
|
||||
id = json_object_get(commit, "id");
|
||||
if(!id || !json_is_string(id))
|
||||
if(!json_is_string(id))
|
||||
{
|
||||
fprintf(stderr, "error: commit %d: id is not a string\n", i + 1);
|
||||
return 1;
|
||||
}
|
||||
|
||||
message = json_object_get(commit, "message");
|
||||
if(!message || !json_is_string(message))
|
||||
if(!json_is_string(message))
|
||||
{
|
||||
fprintf(stderr, "error: commit %d: message is not a string\n", i + 1);
|
||||
return 1;
|
||||
|
|
@ -230,7 +235,7 @@ from a JSON string using :cfunc:`json_string_value()`::
|
|||
}
|
||||
|
||||
After sending the HTTP request, we decoded the JSON text using
|
||||
:cfunc:`json_loads()`, remember? It returns a *new reference* to a
|
||||
:cfunc:`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 :cfunc:`json_decref()`. This way
|
||||
Jansson can release the resources::
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue