View source for API Documentation (version 1.0.x)



=Getting started=

Using '''zzjson''' from within your code needs the inclusion of <tt>zzjson.h</tt>.
<pre>#include <zzjson.h></pre>
After that, all '''zzjson''' functions and datatypes are available to your program. Be sure to link with <tt>-lzzjson</tt> and <tt>-lm</tt>.

=Datatypes=

==Callbacks configuration==

'''zzjson''' does not use any memory allocation or file i/o functions directly. Instead, it uses a callback mechanism if it needs to allocate or free a block of memory or when it needs to read or write a character. This way, the user can supply their own memory manager and '''zzjson''' does not care whether bytes are coming from a file, from memory or over a network connection.

Most '''zzjson''' functions below take a pointer to a <tt>ZZJSON_CONFIG</tt> struct as its first argument. This struct descibes what functions to use.

<pre>typedef struct ZZJSON_CONFIG {
    int strictness;
    void *ihandle;
    int (*getchar)(void *ihandle);
    int (*ungetchar)(int c, void *ihandle);
    void *(*malloc)(size_t size);
    void *(*calloc)(size_t nmemb, size_t size);
    void (*free)(void *ptr);
    void *(*realloc)(void *ptr, size_t size);
    void *ehandle;
    void (*error)(void *ehandle, const char *format, ...);
    void *ohandle;
    int (*print)(void *ohandle, const char *format, ...);
    int (*putchar)(int c, void *handle);
} ZZJSON_CONFIG;</pre>

The callback function prototypes resemble common libc functions, so if you don't need any special functionality, you can just assign those. For example, the parser input routines can be defined as <tt>fgetc()</tt> and <tt>ungetc()</tt> and the input handle <tt>void *ihandle</tt> will be of type <tt>FILE *</tt>. <tt>error()</tt> and <tt>print()</tt> are similar to <tt>fprintf()</tt>, although <tt>error()</tt> is not supposed to return an <tt>int</tt> for obvious reasons.

The strictness field defines how strict the parser should follow the JSON standard. See the description <tt>zzjson_parse()</tt> below.

==ZZJSON struct==

A lot of functions either return or take as an argument a pointer to a <tt>ZZJSON</tt> structure. This is the basic building block of a parsed or created JSON object or array. Look at <tt>zzjson.h</tt> for details. Normally, you won't have to be bothered by the internal structure of a <tt>ZZJSON</tt> struct, but it might be helpful if you want to write, for example, your own traversal function. Keep in mind that the next field is only used when <tt>ZZJSON</tt> is of type <tt>ZZJSON_ARRAY</tt> or <tt>ZZJSON_OBJECT</tt>.

=Functions=

==Parsing==

<pre>ZZJSON *zzjson_parse(ZZJSON_CONFIG *config);</pre>

<tt>zzjson_parse()</tt> reads consecutive bytes through the callback functions defined in <tt>config</tt>. If everything goes well, it returns a pointer to a <tt>ZZJSON</tt> struct. This pointer can later be handed over to querying functions or to <tt>zzjson_print()</tt>. In case an error occurred, <tt>zzjson_parse()</tt> returns <tt>NULL</tt> and an appropriate error message is printed through <tt>config->error()</tt>. Memory is allocated by using the functions specified in <tt>config</tt>.

The behaviour of the parser in case of parse errors can be influenced by setting the <tt>config->strictness</tt> field. If it's zero or <tt>ZZJSON_VERY_STRICT</tt> it will not allow anything that violates the standard. Several flags can be set to be a little more loose in interpreting the incoming bytestream. Possible flags are:

<tt>ZZJSON_ALLOW_EXTRA_COMMA</tt>
: This will parse the following sequences as if the extra comma was not there, which is otherwise invalid:
<pre>{ "hello" : "world", }
[ 3, 1, 4, 1, 5, ]</pre>

<tt>ZZJSON_ALLOW_ILLEGAL_ESCAPE</tt>
: This will allow escaped characters that have no special meaning. It'll convert them to normal characters.
<pre>{ "foo" : "b\ar" }</pre>

<tt>ZZJSON_ALLOW_CONTROL_CHARS</tt>
: Normally, all control characters (ASCII values 0..31) are invalid. Setting this flag will parse them as being normal characters.
<pre>[ "normally, a string cannot, for example,
contain a newline character" ]</pre>

<tt>ZZJSON_ALLOW_GARBAGE_AT_END</tt>
: This will allow garbage characters after a successful object or array is parsed.
<pre>{ "fubar" : "snafu" } }</pre>

To enable all at once, one can use <tt>config->strictness = ZZJSON_VERY_LOOSE</tt>.

Example:
<pre>ZZJSON_CONFIG config;
...
config.strictness = ZZJSON_ALLOW_EXTRA_COMMA | ZZJSON_ALLOW_GARBAGE_AT_END;</pre>

==Printing==

<pre>int zzjson_print(ZZJSON_CONFIG *config, ZZJSON *zzjson);</pre>

<tt>zzjson_print()</tt> uses <tt>config->putchar()</tt> and <tt>config->print()</tt> to output a textual representation of the specified <tt>ZZJSON</tt> structure, which must either be of type <tt>ZZJSON_ARRAY</tt> or <tt>ZZJSON_OBJECT</tt>.

On success it returns a value >= 0, on error it returns a value < 0.

==Querying==

<pre>ZZJSON *zzjson_object_find_label(ZZJSON *zzjson, char *label);
ZZJSON *zzjson_object_find_labels(ZZJSON *zzjson, ...);
unsigned int zzjson_object_count(ZZJSON *zzjson);
unsigned int zzjson_array_count(ZZJSON *zzjson);</pre>

The query functions can be used to search for specific objects or count the number of entries of an object or array.

<tt>zzjson_object_find_label()</tt> searches for a specific label. <tt>zzjson_object_find_labels()</tt> searches for a list of labels, layer by layer. The list consists of zero or more arguments of type <tt>char *</tt> and must be closed by an argument of value <tt>NULL</tt>.

Consider the following JSON input:
<pre>{
  "Image1" : {
    "Width" : 800, "Height" : 600, "Title" :  "View from 15th Floor",
    "Thumbnail" : {
      "Url" : "http://www.example.com/image/481989943",
      "Height" : 125, "Width" :  "100"
    }
  },
  "Image2" : {
    "Width" : 800, "Height" : 600, "Title" :  "View from 16th Floor",
    "Thumbnail" : {
      "Url" : "http://www.example.com/image/481989943",
      "Height" : 125, "Width" :  "100"
    }
  }
}</pre>

If you want to retrieve all information of <tt>Image2</tt> at once, you can use:
<pre>result = zzjson_object_find_label(zzjson, "Image2");</pre>
<tt>result</tt> will be a pointer to a <tt>ZZJSON</tt> structure of type <tt>ZZJSON_OBJECT</tt>.

If you just want to retrieve something specific, you can use:
<pre>result = zzjson_object_find_labels(zzjson, "Image2", "Thumbnail", "Url", NULL);</pre>
<tt>result</tt> will be a pointer to a <tt>ZZJSON</tt> structure of type <tt>ZZJSON_STRING</tt>.

Keep in mind that internally the data is stored in linked lists and that searching this way is not very fast.

Both <tt>zzjson_object_find_label()</tt> and <tt>zzjson_object_find_labels()</tt> return <tt>NULL</tt> on error.

==Creating==

<pre>ZZJSON *zzjson_create_true(ZZJSON_CONFIG *config);
ZZJSON *zzjson_create_false(ZZJSON_CONFIG *config);
ZZJSON *zzjson_create_null(ZZJSON_CONFIG *config);
ZZJSON *zzjson_create_number_d(ZZJSON_CONFIG *config, double d);
ZZJSON *zzjson_create_number_i(ZZJSON_CONFIG *config, long long i);
ZZJSON *zzjson_create_string(ZZJSON_CONFIG *config, char *s);</pre>

These functions create a <tt>ZZJSON</tt> structure of said type. Memory is allocated through the callbacks specified in <tt>config</tt>. All functions return <tt>NULL</tt> on error. On success, the resulting pointer can later be passed on to one of the functions below to put them inside an array or an object.

<pre>ZZJSON *zzjson_create_array(ZZJSON_CONFIG *config, ...);
ZZJSON *zzjson_create_object(ZZJSON_CONFIG *config, ...);</pre>

<tt>zzjson_create_array()</tt> takes a list of zero or more pointers to <tt>ZZJSON</tt> structures, terminated by a <tt>NULL</tt> pointer. The structures are stored in the specified order.

<tt>zzjson_create_object()</tt> takes a list of zero or more pairs of <tt>char *label</tt> and <tt>ZZJSON *</tt>, terminated by a single <tt>NULL</tt> pointer. The label-value-pairs are stored in the specified order.

Both functions return a pointer to the newly created array or object. In case of an error, they return <tt>NULL</tt>. If you run out of memory during construction of the array or object, all newly allocated memory is freed before returning <tt>NULL</tt>. The specified arguments (ZZJSON structures and labels) are not freed.

<pre>ZZJSON *zzjson_array_prepend(ZZJSON_CONFIG *config, ZZJSON *array,
                                                    ZZJSON *val);
ZZJSON *zzjson_array_append (ZZJSON_CONFIG *config, ZZJSON *array,
                                                    ZZJSON *val);
ZZJSON *zzjson_object_prepend(ZZJSON_CONFIG *config, ZZJSON *object,
                                        char *label, ZZJSON *val);
ZZJSON *zzjson_object_append (ZZJSON_CONFIG *config, ZZJSON *object,
                                        char *label, ZZJSON *val);</pre>

The specified value or label-value-pair is either prepended or appended to the specified array or object. The return value is either <tt>NULL</tt> on error, or a pointer to the array or object with the new value or label-value-pair append or prepended. In case of a successful append, the return value is equal to the array or object passed to the function.

Keep in mind that internally all data is stored in a linked list. Therefore, prepending is fast (Big-O(1)) and appending is slow (Big-O(n)).

==Freeing==

<pre>void zzjson_free(ZZJSON_CONFIG *config, ZZJSON *zzjson);</pre>

<tt>zzjson_free()</tt> frees all memory currently in use by the specified <tt>ZZJSON</tt> structure and everything it links to (labels, values, strings, et cetera). It uses <tt>config->free</tt> to do the freeing.

=Sample Unicode callback functions=

Included in the <tt>unicode/</tt> directory are sample Unicode callbacks. They work by converting all Unicode encodings on-the-fly to plain ASCII with \u escaped Unicode characters and back again when printing. All Unicode callback functions take a pointer to a <tt>UNIContext</tt> structure as an argument.

==UNIContext==

<pre>typedef struct UNIContext {
    void *ihandle;
    int (*getchar)(void *ihandle);
    int (*ungetchar)(int c, void *ihandle);
    UNIType type;
    unsigned int bigendian;
    unsigned int bufp;
    char ungetcbuf[UNGETCBUFSIZ];
    unsigned int escape;
    unsigned int unival;
    void *ohandle;
    int (*putchar)(int c, void *ohandle);
    unsigned int ostate;
    unsigned int xunival;
    void *ehandle;
    void (*error)(void *ehandle, const char *format, ...);
} UNIContext;</pre>

The <tt>UNIContext</tt> structure contains callbacks itself. These could point to basic <tt>libc</tt> functions like <tt>getchar()</tt> and <tt>putchar()</tt> or to user-supplied special purpose callback functions. The rest of the fields should be initialized to zero and should not be touched by the application. They represent internal states used by the Unicode callback functions.

==Functions==

<pre>int unicode_getchar(UNIContext *uc);
int unicode_ungetchar(int c, UNIContext *uc);
int unicode_putchar(int c, UNIContext *uc);
int unicode_print(UNIContext *uc, const char *fmt, ...);</pre>

=Using '''zzjson''' from C++=

You can use '''zzjson''' from C++ like any other C library. Just include <tt>zzjson.h</tt> from within the right linkage specification:
<pre>extern "C" {
#include "zzjson.h"
}</pre>
After that, you can use '''zzjson''' as you would with any C functions included in C++. Be sure to link with <tt>-lzzjson</tt> and <tt>-lm</tt>.