diff options
| -rw-r--r-- | README.rst | 6 | ||||
| -rw-r--r-- | doc/gettingstarted.rst | 55 | ||||
| -rw-r--r-- | doc/github_commits.c | 6 | ||||
| -rw-r--r-- | doc/index.rst | 28 | ||||
| -rw-r--r-- | doc/tutorial.rst | 49 |
5 files changed, 92 insertions, 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. diff --git a/doc/gettingstarted.rst b/doc/gettingstarted.rst index 1181588..00dd16a 100644 --- a/doc/gettingstarted.rst +++ b/doc/gettingstarted.rst @@ -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 ================================ diff --git a/doc/github_commits.c b/doc/github_commits.c index 5af01f0..3d8e2cb 100644 --- a/doc/github_commits.c +++ b/doc/github_commits.c @@ -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; diff --git a/doc/index.rst b/doc/index.rst index d4a29a8..1ae9bf3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 diff --git a/doc/tutorial.rst b/doc/tutorial.rst index df930a7..aaeb554 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -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:: |