srcs/toolbox/json.c

/* 
 * Copyright (c) 2005-2012 by KoanLogic s.r.l. - All rights reserved.  
 */

#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <math.h>

#include <toolbox/json.h>
#include <toolbox/carpal.h>
#include <toolbox/misc.h>
#include <toolbox/memory.h>
#include <toolbox/lexer.h>

/* Internal representation of any JSON value. */
struct u_json_s
{
    u_json_type_t type;

    char fqn[U_JSON_FQN_SZ];    /* Fully qualified name of this (sub)object. */
    char key[U_TOKEN_SZ];       /* Local name, if applicable (i.e. !anon) */
    char val[U_TOKEN_SZ];       /* If applicable, i.e. (!OBJECT && !ARRAY) */

    /* Parent container. */
    struct u_json_s *parent;            

    /* Nodes at the same level as this one (if any). */
    TAILQ_ENTRY(u_json_s) siblings;

    /* Children nodes' list when i.e. (ARRAY || OBJECT). */
    TAILQ_HEAD(u_json_chld_s, u_json_s) children;

    unsigned int depth;         /* Depth of this node in the decoded tree. */

    /* Cacheing machinery. */
    unsigned int icur, count;   /* Aux stuff used when indexing arrays. */
    u_hmap_t *map;              /* Alias reference to the global cache. */
};

/* Pointer to the name part of .fqn */
#define U_JSON_OBJ_NAME(jo) \
        ((jo->parent != NULL) ? jo->fqn + strlen(p->fqn) : jo->fqn)

#define U_JSON_OBJ_IS_CONTAINER(jo) \
        ((jo->type == U_JSON_TYPE_OBJECT) || (jo->type == U_JSON_TYPE_ARRAY))

#define U_JSON_OBJ_IS_BOOL(jo) \
        ((jo->type == U_JSON_TYPE_TRUE) || (jo->type == U_JSON_TYPE_FALSE))

/* Lexer methods */
static int u_json_match_value (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_number_first (u_lexer_t *jl);
static int u_json_match_number (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_int (u_lexer_t *jl);
static int u_json_match_frac_first (char c);
static int u_json_match_frac (u_lexer_t *jl);
static int u_json_match_exp_first (char c);
static int u_json_match_exp (u_lexer_t *jl);
static int u_json_match_true_first (u_lexer_t *jl);
static int u_json_match_false_first (u_lexer_t *jl);
static int u_json_match_true (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_false (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_null_first (u_lexer_t *jl);
static int u_json_match_null (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_string (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_string_first (u_lexer_t *jl);
static int u_json_match_escaped_unicode (u_lexer_t *jl);
static int u_json_match_object (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_object_first (u_lexer_t *jl);
static int u_json_match_array (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_array_first (u_lexer_t *jl);
static int u_json_match_pair (u_lexer_t *jl, u_json_t *jo);
static int u_json_match_pair_first (u_lexer_t *jl);

/* Lexer misc stuff. */
static int u_json_match_seq (u_lexer_t *jl, u_json_t *jo, int type, 
        char first, const char *rem, size_t rem_sz);
static const char *u_json_type_str (int type);

/* Objects misc stuff. */
static void u_json_do_print (u_json_t *jo, size_t l, void *opaque);
static void u_json_do_free (u_json_t *jo, size_t l, void *opaque);
static void u_json_do_index (u_json_t *jo, size_t l, void *map);

/* Encode/Decode/Validate. */
static int u_json_do_encode (u_json_t *jo, u_string_t *s);
static int u_json_do_parse (const char *json, u_json_t **pjo, 
        char status[U_LEXER_ERR_SZ]);

/* Needed by hmap_easy* because we are storing pointer data not owned by the
 * hmap. */
static void nopf (void *dummy) { u_unused_args(dummy); return; }

static int u_json_new_container (u_json_type_t type, const char *key, 
        u_json_t **pjo);
static int u_json_new_atom (u_json_type_t type, const char *key, 
        const char *val, char check, u_json_t **pjo);

static int u_json_set_depth (u_json_t *jo, unsigned int depth);

int u_json_new (u_json_t **pjo)
{
    u_json_t *jo = NULL;

    dbg_return_if (pjo == NULL, ~0);

    warn_err_sif ((jo = u_zalloc(sizeof *jo)) == NULL);
    TAILQ_INIT(&jo->children);
    jo->type = U_JSON_TYPE_UNKNOWN;
    jo->key[0] = jo->val[0] = jo->fqn[0] = '\0';
    jo->parent = NULL;
    jo->map = NULL;
    jo->count = 0;
    jo->depth = 0;

    *pjo = jo;

    return 0;
err:
    if (jo)
        u_free(jo);
    return ~0;
}

int u_json_set_type (u_json_t *jo, u_json_type_t type)
{
    dbg_return_if (jo == NULL, ~0);
    dbg_return_ifm (jo->map, ~0, "Cannot set type of a cached object");

    switch (type)
    {
        case U_JSON_TYPE_STRING:
        case U_JSON_TYPE_NUMBER:
        case U_JSON_TYPE_ARRAY:
        case U_JSON_TYPE_OBJECT:
        case U_JSON_TYPE_TRUE:
        case U_JSON_TYPE_FALSE:
        case U_JSON_TYPE_NULL:
        case U_JSON_TYPE_UNKNOWN:
            jo->type = type;
            break;
        default:
           u_err("unhandled type %d", type);
           return ~0;
    }

    return 0;
}

int u_json_set_val (u_json_t *jo, const char *val)
{
    return u_json_set_val_ex(jo, val, 0);
}

/*
 *  \brief  Set the value of a JSON object
 *
 *  Set the value of the JSON object \p jo to the string value pointed by
 *  \p val.  This operation is meaningful only in case the underlying object
 *  is a number or a string, in which case the syntax of the supplied value
 *  can be checked by passing non-0 value to the \p check parameter.
 *
 *  \param  jo      Pointer to a ::u_json_t object
 *  \param  val     Pointer to the (non-NULL) value string
 *  \param  check   Set to non-0 if you need to syntax check \p val
 *
 *  \retval ~0  on failure
 *  \retval  0  on success
 */
int u_json_set_val_ex (u_json_t *jo, const char *val, char check)
{
    u_lexer_t *vl = NULL;

    dbg_return_if (jo == NULL, ~0);
    dbg_return_if (val == NULL, ~0);
    /* Note that cached objects allow for value overwrite. */

    if (check)
    {
        /* XXX The following declaration assumes C99 or C89+support of variable 
         *     length automatic arrays -- as in GCC since at least version 
         *     2.95.3. */
        char qval[strlen(val) + 3]; 

        /* If we are supposed to set a string value, we need to quote it. */
        (void) u_snprintf(qval, sizeof qval, 
                (jo->type == U_JSON_TYPE_STRING) ? "\"%s\"" : "%s", val);

        dbg_err_if (u_lexer_new(qval, &vl));
    }

    /* If requested, pass 'val' through its validator. */
    switch (jo->type)
    {
        case U_JSON_TYPE_STRING:
            dbg_err_if (check && u_json_match_string(vl, NULL));
            break;
        case U_JSON_TYPE_NUMBER:
            dbg_err_if (check && u_json_match_number(vl, NULL));
            break;
        default:
            /* Non-critical error, just emit some debug info. */
            goto end;
    }

    dbg_return_if (u_strlcpy(jo->val, val, sizeof jo->val), ~0);

    /* Fall through. */       
end:
    u_lexer_free(vl);
    return 0;
err:
    u_lexer_free(vl);
    return ~0;
}
int u_json_set_key (u_json_t *jo, const char *key)
{
    dbg_return_if (jo == NULL, ~0);
    dbg_return_ifm (jo->map, ~0, "Cannot set key of a cached object");

    dbg_return_if (u_strlcpy(jo->key, key ? key : "", sizeof jo->key), ~0);

    return 0;
}

int u_json_new_array (const char *key, u_json_t **pjo)
{
    return u_json_new_container(U_JSON_TYPE_ARRAY, key, pjo);
}

int u_json_new_object (const char *key, u_json_t **pjo)
{
    return u_json_new_container(U_JSON_TYPE_OBJECT, key, pjo);
}

int u_json_add (u_json_t *head, u_json_t *jo)
{
    dbg_return_if (head == NULL, ~0);
    dbg_return_if (!U_JSON_OBJ_IS_CONTAINER(head), ~0);
    dbg_return_ifm (head->map, ~0, "Cannot add new child to a cached object");
    dbg_return_if (jo == NULL, ~0);

#ifdef U_JSON_OBJ_DEBUG
    u_con("chld (%p): %s {%s} added at depth %u", 
            jo, u_json_type_str(jo->type), jo->key, jo->depth);
    u_con("prnt (%p): %s {%s} at depth %u\n", 
            head, u_json_type_str(head->type), head->key, head->depth);
#endif  /* U_JSON_OBJ_DEBUG */

    TAILQ_INSERT_TAIL(&head->children, jo, siblings);
    jo->parent = head;

    /* Adjust children counter for array-type parents. */
    if (head->type == U_JSON_TYPE_ARRAY)
        head->count += 1;

    return 0;
}

int u_json_decode (const char *json, u_json_t **pjo)
{
    return u_json_do_parse(json, pjo, NULL);
}

int u_json_validate (const char *json, char status[U_LEXER_ERR_SZ])
{
    /* Just try to validate the input string (do not build the tree). */
    return u_json_do_parse(json, NULL, status);
}

void u_json_free (u_json_t *jo)
{
    size_t dummy = 0;

    if (jo == NULL)
        return;

    /* If there is an associated hmap free it. */
    if (jo->map)
    {
        u_hmap_easy_free(jo->map);
        jo->map = NULL;
    }
 
    /* Walk the tree in post order and free each node while we traverse. */
    u_json_walk(jo, U_JSON_WALK_POSTORDER, dummy, u_json_do_free, NULL);

    return;
}

int u_json_encode (u_json_t *jo, char **ps)
{
    u_string_t *s = NULL;

    dbg_return_if (jo == NULL, ~0);
    dbg_return_if (ps == NULL, ~0);

    dbg_err_if (u_string_create(NULL, 0, &s));
    dbg_err_if (u_json_do_encode(jo, s));
    *ps = u_string_detach_cstr(s);

    return 0;
err:
    if (s)
        u_string_free(s);
    return ~0;
}

void u_json_walk (u_json_t *jo, int strategy, size_t l, 
        void (*cb)(u_json_t *, size_t, void *), void *cb_args)
{
    dbg_return_if (strategy != U_JSON_WALK_PREORDER && 
            strategy != U_JSON_WALK_POSTORDER, );

    if (jo == NULL)
        return;

    if (strategy == U_JSON_WALK_PREORDER && cb)
        cb(jo, l, cb_args);

    /* When recurring into the children branch, increment depth by one. */
    u_json_walk(TAILQ_FIRST(&jo->children), strategy, l + 1, cb, cb_args);

    /* Siblings are at the same depth as the current node. */
    u_json_walk(TAILQ_NEXT(jo, siblings), strategy, l, cb, cb_args);

    if (strategy == U_JSON_WALK_POSTORDER && cb)
        cb(jo, l, cb_args);

    return;
}

void u_json_print (u_json_t *jo)
{
    dbg_return_if (jo == NULL, );

    /* Tree root is at '0' depth. */
    u_json_walk(jo, U_JSON_WALK_PREORDER, 0, u_json_do_print, NULL);

    return;
}

int u_json_index (u_json_t *jo)
{
    size_t u;   /* Unused. */
    u_hmap_opts_t *opts = NULL;
    u_hmap_t *hmap = NULL;

    dbg_return_if (jo == NULL, ~0);
    nop_return_if (jo->map, 0);     /* If already cached, return ok. */
    dbg_return_if (jo->parent, ~0); /* Cache can be created on top-objs only. */

    /* Create the associative array. */
    dbg_err_if (u_hmap_opts_new(&opts));
    dbg_err_if (u_hmap_opts_set_val_type(opts, U_HMAP_OPTS_DATATYPE_POINTER));
    dbg_err_if (u_hmap_opts_set_val_freefunc(opts, nopf));
    dbg_err_if (u_hmap_easy_new(opts, &hmap));
    opts = NULL;

    /* Initialize array elems' indexing. */
    jo->icur = 0;

    /* Walk the tree in pre-order and cache each node while we traverse. */
    u_json_walk(jo, U_JSON_WALK_PREORDER, u, u_json_do_index, hmap);

    /* Attach the associative array to the top level object. */
    jo->map = hmap, hmap = NULL;

    return 0;
err:
    if (opts)
        u_hmap_opts_free(opts);
    if (hmap)
        u_hmap_easy_free(hmap);
    return ~0;
}

int u_json_unindex (u_json_t *jo)
{
    dbg_return_if (jo == NULL, ~0);
    nop_return_if (jo->map == NULL, 0);

    u_hmap_easy_free(jo->map);
    jo->map = NULL;

    return 0;
}

u_json_t *u_json_cache_get (u_json_t *jo, const char *name)
{
    u_json_t *res, *p;
    char fqn[U_JSON_FQN_SZ];

    dbg_return_if (jo == NULL, NULL);
    dbg_return_if (jo->map == NULL, NULL);
    dbg_return_if (name == NULL, NULL);

    if ((p = jo->parent) == NULL)
    {
        /* If 'jo' is top level, 'name' must be fully qualified. */ 
        return (u_json_t *) u_hmap_easy_get(jo->map, name);
    }

    /* Else ('jo' != top): first try 'name' as it were fully qualified. */
    if ((res = (u_json_t *) u_hmap_easy_get(jo->map, name)))
        return res;

    /* If 'name' is relative, we need to prefix it with the parent name 
     * space. */
    dbg_if (u_snprintf(fqn, sizeof fqn, "%s%s", jo->fqn, name));

    return (u_json_t *) u_hmap_easy_get(jo->map, fqn);
}

int u_json_cache_set_tv (u_json_t *jo, const char *name, 
        u_json_type_t type, const char *val)
{
    u_json_t *res;

    dbg_return_if (U_JSON_OBJ_IS_CONTAINER(jo), ~0);
    dbg_return_if (type == U_JSON_TYPE_OBJECT || type == U_JSON_TYPE_ARRAY, ~0);
    /* 'jo' and 'name' will be checked by u_json_cache_get(); 
     * 'val' consistency is checked after type has been set. */

    /* Retrieve the node. */
    dbg_err_if ((res = u_json_cache_get(jo, name)) == NULL);

    /* First set type (in case !unknown) so that we know how to check the
     * subsequent value setting. */
    if (type != U_JSON_TYPE_UNKNOWN)
        res->type = type;

    /* Set value.  The caller must have supplied some non-NULL 'val' in case 
     * the final underlying type is a string or a number. */
    if (res->type == U_JSON_TYPE_STRING || res->type == U_JSON_TYPE_NUMBER)
        dbg_err_if (val == NULL || u_strlcpy(res->val, val, sizeof res->val));

    return 0;
err:
    return ~0;
}

unsigned int u_json_array_count (u_json_t *jo)
{
    dbg_return_if (jo == NULL, 0);
    dbg_return_if (jo->type != U_JSON_TYPE_ARRAY, 0);

    return jo->count;
}

u_json_t *u_json_array_get_nth (u_json_t *jo, unsigned int n)
{
    u_json_t *elem;

    dbg_return_if (jo == NULL, NULL);
    dbg_return_if (jo->type != U_JSON_TYPE_ARRAY, NULL);
    dbg_return_if (n >= jo->count, NULL);

    /* Use cache if available. */
    if (jo->map)
    {
        char elem_fqn[U_JSON_FQN_SZ] = { '\0' };
        dbg_if (u_snprintf(elem_fqn, sizeof elem_fqn, "%s[%u]", jo->fqn, n));
        return u_json_cache_get(jo, elem_fqn);
    }
    
    /* Too bad if we don't have cache in place: we have to go through the 
     * list which is quadratic even with the following silly optimisation.
     * So it's ok for a couple of lookups, but if done systematically it's
     * an overkill.  Freeze instead ! */
    if (n > (jo->count / 2))
    {
        unsigned int r = jo->count - (n + 1);

        TAILQ_FOREACH_REVERSE (elem, &jo->children, u_json_chld_s, siblings)
        {
            if (r == 0)
                return elem;
            r -= 1;
        } 
    }
    else
    {
        TAILQ_FOREACH (elem, &jo->children, siblings)
        {
            if (n == 0)
                return elem;
            n -= 1;
        } 
    }

    /* Unreachable. */
    return NULL;
}

const char *u_json_get_val (u_json_t *jo)
{
    dbg_return_if (jo == NULL, NULL);

    switch (jo->type)
    {
        case U_JSON_TYPE_STRING:
        case U_JSON_TYPE_NUMBER:
            return jo->val;
        case U_JSON_TYPE_TRUE:
            return "true";
        case U_JSON_TYPE_FALSE:
            return "false";
        case U_JSON_TYPE_NULL:
            return "null";
        case U_JSON_TYPE_OBJECT:
        case U_JSON_TYPE_ARRAY:
        case U_JSON_TYPE_UNKNOWN:
        default:
            return NULL;
    }
}

int u_json_get_int (u_json_t *jo, long *pl)
{
    dbg_return_if (jo == NULL, ~0);
    dbg_return_if (jo->type != U_JSON_TYPE_NUMBER, ~0);
    dbg_return_if (pl == NULL, ~0);

    dbg_err_if (u_atol(jo->val, pl));

    return 0;
err:
    return ~0;
}

int u_json_get_real (u_json_t *jo, double *pd)
{
    dbg_return_if (jo == NULL, ~0);
    dbg_return_if (jo->type != U_JSON_TYPE_NUMBER, ~0);
    dbg_return_if (pd == NULL, ~0);

    dbg_err_if (u_atof(jo->val, pd));

    return 0;
err:
    return ~0;
}

int u_json_get_bool (u_json_t *jo, char *pb)
{
    dbg_return_if (jo == NULL, ~0);
    dbg_return_if (pb == NULL, ~0);

    switch (jo->type)
    {
        case U_JSON_TYPE_TRUE:
            *pb = 1;
            break;
        case U_JSON_TYPE_FALSE:
            *pb = 0;
            break;
        default:
            return ~0;
    }

    return 0;
}

const char *u_json_cache_get_val (u_json_t *jo, const char *name)
{
    u_json_t *res = u_json_cache_get(jo, name);

    return u_json_get_val(res);
}

int u_json_cache_get_int (u_json_t *jo, const char *name, long *pval)
{
    u_json_t *res;

    dbg_return_if ((res = u_json_cache_get(jo, name)) == NULL, ~0);

    return u_json_get_int(res, pval);
}

int u_json_cache_get_real (u_json_t *jo, const char *name, double *pval)
{
    u_json_t *res;

    dbg_return_if ((res = u_json_cache_get(jo, name)) == NULL, ~0);

    return u_json_get_real(res, pval);
}

int u_json_cache_get_bool (u_json_t *jo, const char *name, char *pval)
{
    u_json_t *res;

    dbg_return_if ((res = u_json_cache_get(jo, name)) == NULL, ~0);

    return u_json_get_bool(res, pval);
}

int u_json_remove (u_json_t *jo)
{
    u_json_t *p;

    dbg_return_if (jo == NULL, ~0);
    dbg_return_ifm (jo->map, ~0, "Cannot remove (from) a cached object");

    if ((p = jo->parent))
    {            
        /* Fix counters when parent is an array. */
        if (p->type == U_JSON_TYPE_ARRAY)
            p->count -= 1;

        /* Evict from the parent container. */
        TAILQ_REMOVE(&p->children, jo, siblings);
    }

    /* Give back the resources allocated to the node (and its children). */
    u_json_free(jo);

    return 0;
}

int u_json_new_string (const char *key, const char *val, u_json_t **pjo)
{
    return u_json_new_atom(U_JSON_TYPE_STRING, key, val, 1, pjo);
}

int u_json_new_number (const char *key, const char *val, u_json_t **pjo)
{
    return u_json_new_atom(U_JSON_TYPE_NUMBER, key, val, 1, pjo);
}

int u_json_new_real (const char *key, double val, u_json_t **pjo)
{
    char sval[U_TOKEN_SZ], check = 0;

#ifdef HAVE_ISFINITE
    /* Use isfinite() to avoid infinity's and NaN's which would break the
     * JSON syntax. */
    dbg_return_if (!isfinite(val), ~0);
#else
    /* If isfinite() is not available (i.e. !C99), force check in 
     * u_json_new_atom(). */
    check = 1;
#endif  /* HAVE_ISFINITE */

    /* "%g" does exponential (i.e. [+-]d.d...dE[+-]dd) or fixed-point (i.e.
     * [+-]d...d.d...d) notation depending on 'val'.  Both should be compatible
     * with JSON number spec. */ 
    dbg_return_if (u_snprintf(sval, sizeof sval, "%g", val), ~0);

    return u_json_new_atom(U_JSON_TYPE_NUMBER, key, sval, check, pjo);
}

int u_json_new_int (const char *key, long val, u_json_t **pjo)
{
    char sval[U_TOKEN_SZ];

    dbg_return_if (u_snprintf(sval, sizeof sval, "%ld", val), ~0);

    /* Assume 'sval' correctly formatted (no need to validate). */
    return u_json_new_atom(U_JSON_TYPE_NUMBER, key, sval, 0, pjo);
}

int u_json_new_null (const char *key, u_json_t **pjo)
{
    /* No need to validate. */
    return u_json_new_atom(U_JSON_TYPE_NULL, key, NULL, 0, pjo);
}

int u_json_new_bool (const char *key, char val, u_json_t **pjo)
{
    /* No need to validate. */
    return u_json_new_atom(val ? U_JSON_TYPE_TRUE : U_JSON_TYPE_FALSE, 
            key, NULL, 0, pjo);
}

u_json_t *u_json_child_first (u_json_t *jo)
{
    dbg_return_if (jo == NULL, NULL);
    dbg_return_if (!U_JSON_OBJ_IS_CONTAINER(jo), NULL);

    return TAILQ_FIRST(&jo->children);
}

u_json_t *u_json_child_last (u_json_t *jo)
{
    dbg_return_if (jo == NULL, NULL);
    dbg_return_if (!U_JSON_OBJ_IS_CONTAINER(jo), NULL);

    return TAILQ_LAST(&jo->children, u_json_chld_s);
}

int u_json_it (u_json_t *jo, u_json_it_t *it)
{
    dbg_return_if (it == NULL, ~0);

    it->cur = jo;

    return 0;
}

u_json_t *u_json_it_next (u_json_it_t *it)
{
    u_json_t *jo;

    dbg_return_if (it == NULL, NULL);

    if ((jo = it->cur) != NULL)
        it->cur = TAILQ_NEXT(jo, siblings);

    return jo;
}

u_json_t *u_json_it_prev (u_json_it_t *it)
{
    u_json_t *jo;

    dbg_return_if (it == NULL, NULL);

    if ((jo = it->cur) != NULL)
        it->cur = TAILQ_PREV(jo, u_json_chld_s, siblings);

    return jo;
}

static int u_json_do_encode (u_json_t *jo, u_string_t *s)
{
    if (jo == NULL)
        return 0;

    /* Optional key. */
    if (strlen(jo->key))
        dbg_err_if (u_string_aprintf(s, "\"%s\": ", jo->key));

    /* Value. */
    switch (jo->type)
    {
        case U_JSON_TYPE_STRING:
            dbg_err_if (u_string_aprintf(s, "\"%s\"", jo->val));
            break;
        case U_JSON_TYPE_NUMBER:
            dbg_err_if (u_string_aprintf(s, "%s", jo->val));
            break;
        case U_JSON_TYPE_OBJECT:
            dbg_err_if (u_string_aprintf(s, "{ "));
            break;
        case U_JSON_TYPE_ARRAY:
            dbg_err_if (u_string_aprintf(s, "[ "));
            break;
        case U_JSON_TYPE_TRUE:
            dbg_err_if (u_string_aprintf(s, "true"));
            break;
        case U_JSON_TYPE_FALSE:
            dbg_err_if (u_string_aprintf(s, "false"));
            break;
        case U_JSON_TYPE_NULL:
            dbg_err_if (u_string_aprintf(s, "null"));
            break;
        default:
            dbg_err("!");
    }

    /* Explore depth. */
    dbg_err_if (u_json_do_encode(TAILQ_FIRST(&jo->children), s));

    /* Close matching paren. */
    switch (jo->type)
    {
        case U_JSON_TYPE_ARRAY:
            dbg_err_if (u_string_aprintf(s, " ]"));
            break;
        case U_JSON_TYPE_OBJECT:
            dbg_err_if (u_string_aprintf(s, " }"));
            break;
        default:
            break;
    }

    /* When needed, add comma to separate siblings. */
    if (TAILQ_NEXT(jo, siblings))
        dbg_err_if (u_string_aprintf(s, ", "));

    /* Explore horizontally. */
    dbg_err_if (u_json_do_encode(TAILQ_NEXT(jo, siblings), s));

    return 0;
err:
    return ~0;
}

static int u_json_match_value (u_lexer_t *jl, u_json_t *jo)
{
    /* 'jo' can be NULL in case of a validating-only parser. */
    dbg_return_if (jl == NULL, ~0);

    if (u_json_match_string_first(jl))
        dbg_err_if (u_json_match_string(jl, jo));
    else if (u_json_match_number_first(jl))
        dbg_err_if (u_json_match_number(jl, jo));
    else if (u_json_match_object_first(jl))
        dbg_err_if (u_json_match_object(jl, jo));
    else if (u_json_match_array_first(jl))
        dbg_err_if (u_json_match_array(jl, jo));
    else if (u_json_match_true_first(jl))
        dbg_err_if (u_json_match_true(jl, jo));
    else if (u_json_match_false_first(jl))
        dbg_err_if (u_json_match_false(jl, jo));
    else if (u_json_match_null_first(jl))
        dbg_err_if (u_json_match_null(jl, jo));
    else
        U_LEXER_ERR(jl, "value not found at \'%s\'", u_lexer_lookahead(jl));

    return 0;
err:
    return ~0;
}

static int u_json_match_array_first (u_lexer_t *jl)
{
    return (u_lexer_peek(jl) == '[');
}

static int u_json_match_object_first (u_lexer_t *jl)
{
    return (u_lexer_peek(jl) == '{');
}

static int u_json_match_number_first (u_lexer_t *jl)
{
    char r, c = u_lexer_peek(jl);

    if ((r = (c == '-' || isdigit(c))))
        u_lexer_record_lmatch(jl);

    return r;
}

static int u_json_match_pair_first (u_lexer_t *jl)
{
    return u_json_match_string_first(jl);
}

static int u_json_match_false_first (u_lexer_t *jl)
{
    return (u_lexer_peek(jl) == 'f');
}

static int u_json_match_true_first (u_lexer_t *jl)
{
    return (u_lexer_peek(jl) == 't');
}

static int u_json_match_null_first (u_lexer_t *jl)
{
    return (u_lexer_peek(jl) == 'n');
}

static int u_json_match_string_first (u_lexer_t *jl)
{
    char r, c = u_lexer_peek(jl);

    if ((r = (c == '"')))
        u_lexer_record_lmatch(jl);

    return r;
}

/* number ::= INT[FRAC][EXP] */
static int u_json_match_number (u_lexer_t *jl, u_json_t *jo)
{
    char match[U_TOKEN_SZ];

    /* INT is mandatory */
    dbg_err_if (u_json_match_int(jl));

    /* c IN first(FRAC) */
    if (u_json_match_frac_first(u_lexer_peek(jl)))
        dbg_err_if (u_json_match_frac(jl));

    /* c IN first(EXP) */
    if (u_json_match_exp_first(u_lexer_peek(jl)))
        dbg_err_if (u_json_match_exp(jl));

    /* Register right side of the matched number. */
    u_lexer_record_rmatch(jl);

    /* Take care of the fact that the match includes the first non-number char
     * (see u_json_match_{int,exp,frac} for details). */
    (void) u_lexer_get_match(jl, match);
    match[strlen(match) - 1] = '\0';

    /* Push the matched number into the supplied json object. */
    if (jo)
    {
        dbg_err_if (u_json_set_type(jo, U_JSON_TYPE_NUMBER));
        dbg_err_if (u_json_set_val(jo, match));
    }

#ifdef U_JSON_LEX_DEBUG
    u_con("matched number: %s", u_lexer_get_match(jl, match));
#endif  /* U_JSON_LEX_DEBUG */

    return 0;
err:
    return ~0;
}

static int u_json_match_int (u_lexer_t *jl)
{
    char c = u_lexer_peek(jl);

    /* optional minus sign */
    if (c == '-')
        U_LEXER_NEXT(jl, &c);

    /* on '0' as the first char, we're done */
    if (c == '0')
    {
        U_LEXER_NEXT(jl, &c);
        goto end;
    }

    /* [1-9][0-9]+ */
    if (c >= 48 && c <= 57)
        do { U_LEXER_NEXT(jl, &c); } while (isdigit(c));
    else 
        U_LEXER_ERR(jl, "bad int syntax at %s", u_lexer_lookahead(jl));

    /* fall through */
end:
    return 0;
err:
    return ~0;
}

static int u_json_match_exp_first (char c)
{
    return (c == 'e' || c == 'E');
}

static int u_json_match_frac_first (char c)
{
    return (c == '.');
}

static int u_json_match_frac (u_lexer_t *jl)
{
    char c = u_lexer_peek(jl);

    /* Mandatory dot. */
    if (c != '.')
        U_LEXER_ERR(jl, "bad frac syntax at %s", u_lexer_lookahead(jl));

    U_LEXER_NEXT(jl, &c);

    /* [0-9] */
    if (!isdigit(c))
        U_LEXER_ERR(jl, "bad frac syntax at %s", u_lexer_lookahead(jl));

    /* [0-9]* */
    while (isdigit(c))
        U_LEXER_NEXT(jl, &c);

    return 0;
err:
    return ~0;
}

static int u_json_match_exp (u_lexer_t *jl)
{
    char c = u_lexer_peek(jl);

    /* [eE] */
    if (c != 'e' && c != 'E')
        U_LEXER_ERR(jl, "bad exp syntax at %s", u_lexer_lookahead(jl));

    U_LEXER_NEXT(jl, &c);

    /* Optional plus/minus sign. */
    if (c == '+' || c == '-')
        U_LEXER_NEXT(jl, &c);

    /* [0-9] */
    if (!isdigit(c))
        U_LEXER_ERR(jl, "bad exp syntax at %s", u_lexer_lookahead(jl));

    /* [0-9]* */
    while (isdigit(c))
        U_LEXER_NEXT(jl, &c);

    return 0;
err:
    return ~0;
}

static int u_json_match_seq (u_lexer_t *jl, u_json_t *jo, int type, 
        char first, const char *rem, size_t rem_sz)
{
    char c;
    size_t i = 0;

    if ((c = u_lexer_peek(jl)) != first)
    {
        U_LEXER_ERR(jl, "expect \'%c\', got %c at %s", 
                first, c, u_lexer_lookahead(jl));
    }

    for (i = 0; i < rem_sz; i++)
    {
        U_LEXER_SKIP(jl, &c);
        if (c != *(rem + i))
        {
            U_LEXER_ERR(jl, "expect \'%c\', got %c at %s", 
                    *(rem + i), c, u_lexer_lookahead(jl));
        }
    }

    /* Consume last checked char. */
    U_LEXER_SKIP(jl, NULL);

    if (jo)
        dbg_err_if (u_json_set_type(jo, type));

#ifdef U_JSON_LEX_DEBUG
    u_con("matched \'%s\' sequence", u_json_type_str(type));
#endif  /* U_JSON_LEX_DEBUG */
    return 0;
err:
    return ~0;
}

static int u_json_match_null (u_lexer_t *jl, u_json_t *jo)
{
    return u_json_match_seq(jl, jo, U_JSON_TYPE_NULL, 
            'n', "ull", strlen("ull"));
}

static int u_json_match_true (u_lexer_t *jl, u_json_t *jo)
{
    return u_json_match_seq(jl, jo, U_JSON_TYPE_TRUE, 
            't', "rue", strlen("rue"));
}

static int u_json_match_false (u_lexer_t *jl, u_json_t *jo)
{
    return u_json_match_seq(jl, jo, U_JSON_TYPE_FALSE, 
            'f', "alse", strlen("alse"));
}

static int u_json_match_array (u_lexer_t *jl, u_json_t *jo)
{
    char c;
    u_json_t *elem = NULL;

#ifdef U_JSON_LEX_DEBUG
    u_con("ARRAY");
#endif  /* U_JSON_LEX_DEBUG */

    if ((c = u_lexer_peek(jl)) != '[')
    {
        U_LEXER_ERR(jl, "expect \'[\', got %c at %s", 
                c, u_lexer_lookahead(jl));
    }

    /* Parent object is an array. */
    if (jo)
        dbg_err_if (u_json_set_type(jo, U_JSON_TYPE_ARRAY));

    do {
        /* As long as we want to accept empty arrays in this same scan loop, 
         * we could let trailing ',' pass unseen when a value has been already
         * consumed.  So, at each iteration, last non-whitespace char is saved 
         * to 'd' and checked when testing the empty array condition so that
         * we can emit a warn if needed.  
         * NOTE this is done equivalently in u_json_match_object(). */
        char d = u_lexer_peek(jl);

        U_LEXER_SKIP(jl, &c);
        
        if (c == ']')   /* break on empty array */
        {
            if (d == ',')
                u_warn("Trailing \',\' at the end of array !");
            break;
        }

        if (jo)
        {
            /* Create a new object to store next array element. */
            dbg_err_if (u_json_new(&elem));
            dbg_err_if (u_json_set_type(elem, U_JSON_TYPE_UNKNOWN));
            dbg_err_if (u_json_set_depth(elem, jo->depth + 1));
        }

        /* Fetch new value. */
        dbg_err_if (u_json_match_value(jl, elem));

        if (jo)
        {
            /* Push the fetched element to its parent array. */
            dbg_err_if (u_json_add(jo, elem)); 
            elem = NULL;
        }

        /* Consume any trailing white spaces. */
        if (isspace((int) u_lexer_peek(jl)))
            U_LEXER_SKIP(jl, NULL);

    } while (u_lexer_peek(jl) == ',');

    if ((c = u_lexer_peek(jl)) != ']')
    {
        U_LEXER_ERR(jl, "expect \']\', got %c at %s", 
                c, u_lexer_lookahead(jl));
    }

    /* Ignore EOT, shall be catched later. */
    (void) u_lexer_skip(jl, NULL);

    return 0;
err:
    u_json_free(elem);
    return ~0;
}

static int u_json_match_object (u_lexer_t *jl, u_json_t *jo)
{
    char c;

#ifdef U_JSON_LEX_DEBUG
    u_con("OBJECT");
#endif  /* U_JSON_LEX_DEBUG */

    if ((c = u_lexer_peek(jl)) != '{')
    {
        U_LEXER_ERR(jl, "expect \'{\', got %c at %s", 
                c, u_lexer_lookahead(jl));
    }

    if (jo)
        dbg_err_if (u_json_set_type(jo, U_JSON_TYPE_OBJECT));

    do {
        char d = u_lexer_peek(jl);

        U_LEXER_SKIP(jl, &c);

        /* Break on empty object. */
        if (c == '}')
        {
            if (d == ',')
                u_warn("Trailing \',\' at the end of object !");
            break;
        }

        /* Process assignement. */
        dbg_err_if (!u_json_match_pair_first(jl) || u_json_match_pair(jl, jo));

        /* Consume trailing white spaces, if any. */
        if (isspace((int) u_lexer_peek(jl)))
            U_LEXER_SKIP(jl, NULL);

    } while (u_lexer_peek(jl) == ',');

    if ((c = u_lexer_peek(jl)) != '}')
    {
        U_LEXER_ERR(jl, "expect \'}\', got %c at %s", 
                c, u_lexer_lookahead(jl));
    }

    /* Ignore EOT, shall be catched later. */
    (void) u_lexer_skip(jl, NULL);

    return 0;
err:
    return ~0;
}

static int u_json_match_pair (u_lexer_t *jl, u_json_t *jo)
{
    size_t mlen;
    char c, match[U_TOKEN_SZ];
    u_json_t *pair = NULL;

    dbg_return_if (jl == NULL, ~0);

#ifdef U_JSON_LEX_DEBUG
    u_con("PAIR");
#endif  /* U_JSON_LEX_DEBUG */

    /* Here we use the matched string as the 'key' for the associated value, 
     * hence there is no associated json object. */
    dbg_err_if (u_json_match_string(jl, NULL));

    /* Initialize new json object to store the key/value pair. */
    if (jo)
    {
        dbg_err_if (u_json_new(&pair));
        dbg_err_if (u_json_set_depth(pair, jo->depth + 1));
    }

    (void) u_lexer_get_match(jl, match);

    /* Trim trailing '"'. */
    if ((mlen = strlen(match)) >= 1)
        match[mlen - 1] = '\0';

    if (jo)
        dbg_err_if (u_json_set_key(pair, match));

    /* Consume trailing white spaces, if any. */
    if (isspace((int) u_lexer_peek(jl)))
        U_LEXER_SKIP(jl, NULL);

    /* Consume ':' */
    if ((c = u_lexer_peek(jl)) != ':')
    {
        U_LEXER_ERR(jl, "expect \':\', got %c at %s", 
                c, u_lexer_lookahead(jl));
    }

    U_LEXER_SKIP(jl, &c);

    /* Assign value. */
    dbg_err_if (u_json_match_value(jl, pair));

    /* Push the new value to the parent json object. */
    if (jo)
    {
        dbg_err_if (u_json_add(jo, pair));
        pair = NULL;
    }

    return 0;
err:
    u_json_free(pair);
    return ~0;
}

static int u_json_match_string (u_lexer_t *jl, u_json_t *jo)
{
    size_t mlen;
    char c, match[U_TOKEN_SZ];

    /* In case string is matched as an lval (i.e. the key side of a 'pair'),
     * there is no json object. */
    dbg_return_if (jl == NULL, ~0);

#ifdef U_JSON_LEX_DEBUG
    u_con("STRING");
#endif  /* U_JSON_LEX_DEBUG */

    if ((c = u_lexer_peek(jl)) != '"')
        U_LEXER_ERR(jl, "expect \", got %c at %s", c, u_lexer_lookahead(jl));

    U_LEXER_NEXT(jl, &c);

    /* Re-record the left side match pointer (trim leading '"'). */
    u_lexer_record_lmatch(jl);

    while (c != '"')
    {
        if (c == '\\')
        {
            U_LEXER_NEXT(jl, &c);
            switch (c)
            {
                case 'u':
                    dbg_err_if (u_json_match_escaped_unicode(jl));
                    break;
                case '"': case '\\': case '/': case 'b':
                case 'f': case 'n':  case 'r': case 't':
                    U_LEXER_NEXT(jl, &c);
                    break;
                default:
                    U_LEXER_ERR(jl, "invalid char %c in escape", c);
            }
        }
        else if (iscntrl((int) c))
            U_LEXER_ERR(jl, "control character in string", c); 
        else    
            U_LEXER_NEXT(jl, &c);
    }

    /* Record right match pointer.
     * This is a greedy match, which includes the trailing '"', and must
     * be taken into account when pulling out the string. */
    u_lexer_record_rmatch(jl);

    /* Consume last '"'. */
    U_LEXER_NEXT(jl, &c);

#ifdef U_JSON_LEX_DEBUG
    u_con("matched string: \'%s\'", u_lexer_get_match(jl, match));
#endif  /* U_JSON_LEX_DEBUG */

    /* In case the string is matched as an rval, the caller shall
     * supply the json object that has to be set. */
    if (jo)
    {
        dbg_err_if (u_json_set_type(jo, U_JSON_TYPE_STRING));

        /* Remove trailing '"' from match. */
        (void) u_lexer_get_match(jl, match);

        /* Trim trailing '"'. */
        if ((mlen = strlen(match)) >= 1)
            match[mlen - 1] = '\0';

        dbg_err_if (u_json_set_val(jo, match));
    }

    return 0;
err:
    return ~0;
}

static int u_json_match_escaped_unicode (u_lexer_t *jl)
{
    char i, c;

    for (i = 0; i < 4; i++)
    {
        U_LEXER_NEXT(jl, &c);

        if (!isxdigit((int) c))
            U_LEXER_ERR(jl, "non hex digit %c in escaped unicode", c); 
    }

    return 0;
err:
    return ~0;
}

static const char *u_json_type_str (int type)
{
    switch (type)
    {
        case U_JSON_TYPE_STRING:  return "string";
        case U_JSON_TYPE_NUMBER:  return "number";
        case U_JSON_TYPE_ARRAY:   return "array";
        case U_JSON_TYPE_OBJECT:  return "object";
        case U_JSON_TYPE_TRUE:    return "true";
        case U_JSON_TYPE_FALSE:   return "false";
        case U_JSON_TYPE_NULL:    return "null";
        case U_JSON_TYPE_UNKNOWN: default: break;
    }

    return "unknown";
}

static void u_json_do_free (u_json_t *jo, size_t l, void *opaque)
{
    u_unused_args(l, opaque);

    if (jo)
        u_free(jo);

    return;
}

static void u_json_do_print (u_json_t *jo, size_t l, void *opaque)
{
    u_unused_args(opaque);

    dbg_return_if (jo == NULL, );

    switch (jo->type)
    {
        case U_JSON_TYPE_ARRAY:
        case U_JSON_TYPE_OBJECT:
            /* No value. */
            u_con("%*c %s %s", l, ' ', u_json_type_str(jo->type), jo->key);
            break;
        default:
            u_con("%*c %s %s : \'%s\'", l, ' ', 
                    u_json_type_str(jo->type), jo->key, jo->val);
            break;
    }

    return;
}

static void u_json_do_index (u_json_t *jo, size_t l, void *map)
{
    u_json_t *p;
    u_hmap_t *hmap = (u_hmap_t *) map;

    u_unused_args(l);

    if ((p = jo->parent) == NULL)
    {
        /* Root node is named '.', its name and fully qualified name match. */
        (void) u_strlcpy(jo->fqn, ".", sizeof jo->fqn);
    }
    else if (p->type == U_JSON_TYPE_OBJECT)
    {
        /* Nodes in object containers are named after their key. */
        dbg_if (u_snprintf(jo->fqn, sizeof jo->fqn, "%s.%s", p->fqn, jo->key));
    }
    else if (p->type == U_JSON_TYPE_ARRAY)
    {
        /* Nodes in array containers are named after their ordinal position. */
        dbg_if (u_snprintf(jo->fqn, sizeof jo->fqn, "%s[%u]", p->fqn, p->icur));

        /* Increment the counting index in the parent array. */
        p->icur += 1;

        /* In case we have an array inside another array, initialize the 
         * counter for later recursive invocation. */
        if (jo->type == U_JSON_TYPE_ARRAY)
            jo->icur = 0;
    }
    else
        u_warn("Expecting an object, an array, or a top-level node.");

    /* Insert node into the hmap. */
    dbg_if (u_hmap_easy_put(hmap, jo->fqn, (const void *) jo));

    /* Stick the map pointer inside each visited node, so that it can
     * be readily referenced on retrieval. */
    jo->map = map;

#ifdef U_JSON_IDX_DEBUG
    u_con("%p => %s (%s) = %s", jo, jo->fqn, U_JSON_OBJ_NAME(jo), jo->val);
#endif

    return;
}

static int u_json_new_container (u_json_type_t type, const char *key, 
        u_json_t **pjo)
{
    u_json_t *jo = NULL;

    dbg_return_if (pjo == NULL, ~0);

    dbg_err_if (u_json_new(&jo));

    dbg_err_if (u_json_set_type(jo, type));
    dbg_err_if (u_json_set_key(jo, key ? key : ""));

    *pjo = jo;

    return 0;
err:
    if (jo)
        u_json_free(jo);
    return ~0;
}

static int u_json_new_atom (u_json_type_t type, const char *key, 
        const char *val, char check, u_json_t **pjo)
{
    u_json_t *jo = NULL;

    dbg_return_if (pjo == NULL, ~0);

    dbg_err_if (u_json_new(&jo));

    dbg_err_if (u_json_set_type(jo, type));
    dbg_err_if (u_json_set_key(jo, key));

    /* Values are meaningful only in case of string and number objects,
     * "null", "true" and "false" are completely defined by the type. */
    switch (type)
    {
        case U_JSON_TYPE_NUMBER:  
        case U_JSON_TYPE_STRING:  
            dbg_err_if (u_json_set_val_ex(jo, val, check));
        default: break;
    }

    *pjo = jo;

    return 0;
err:
    if (jo)
        u_json_free(jo);
    return ~0;
}

static int u_json_do_parse (const char *json, u_json_t **pjo, 
        char status[U_LEXER_ERR_SZ])
{
    u_json_t *jo = NULL;
    u_lexer_t *jl = NULL;

    /* When 'pjo' is NULL, assume this is a validating-only parser. */
    dbg_return_if (json == NULL, ~0);

    /* Create a disposable lexer context associated to the supplied
     * 'json' string. */
    dbg_err_if (u_lexer_new(json, &jl));

    /* Create top level json object. */
    dbg_err_if (pjo && u_json_new(&jo));

    /* Consume any trailing white space before starting actual parsing. */
    if (u_lexer_eat_ws(jl) == -1)
        U_LEXER_ERR(jl, "Empty JSON text !");

    /* Launch the lexer expecting the input JSON text as a serialized object 
     * or array. */ 
    if (u_json_match_object_first(jl))
        dbg_err_if (u_json_match_object(jl, jo));
    else if (u_json_match_array_first(jl))
        dbg_err_if (u_json_match_array(jl, jo));
    else
        U_LEXER_ERR(jl, "Expect \'{\' or \'[\', got \'%c\'.", u_lexer_peek(jl));

    /* Just warn in case the JSON string has not been completely consumed. */
    if (!u_lexer_eot(jl))
    {
        u_warn("Unparsed trailing text \'%s\' at position %u", 
                u_lexer_lookahead(jl), u_lexer_pos(jl));
    }

    /* Dispose the lexer context. */
    u_lexer_free(jl);

    /* Copy out the broken down tree. */
    if (pjo)
        *pjo = jo;

    return 0;
err:
    /* Copy out the lexer error string (if requested). */
    if (status)
        (void) u_strlcpy(status, u_lexer_geterr(jl), U_LEXER_ERR_SZ);

    u_lexer_free(jl);
    u_json_free(jo);

    return ~0;
}

static int u_json_set_depth (u_json_t *jo, unsigned int depth)
{
    /* Don't let'em smash our stack. */
    warn_err_ifm ((jo->depth = depth) >= U_JSON_MAX_DEPTH,
        "Maximum allowed nesting is %u.", U_JSON_MAX_DEPTH);

    return 0;
err:
    return ~0;
}