yajl

Overview

Yet Another JSON Library. YAJL is a small event-driven (SAX-style) JSON parser written in ANSI C, and a small validating JSON generator. YAJL is released under the ISC license.

Documentation

Documentation generated by CXref from source is available for release-2.1.

Code

Get it on github: https://github.com/robohack/yajl

Support

You can Github issues for support.

Download

You can also clone the project with Git by running:

$ git clone git://github.com/robohack/yajl

Features

Simple Interface

Largely because YAJL is event driven, the interface is very concise object oriented C. The interface is not cluttered with data representation, that bit is left up to higher level code. Indeed it should be possible to port most existing JSON libraries onto YAJL if so desired.

portable

It's all ANSI C. It's been successfully compiled on many NetBSD ports, as well as on debian linux, OSX 10.4 i386 & ppc, OSX 10.5 i386, winXP, FreeBSD 4.10, FreeBSD 6.1 amd64, FreeBSD 7 i386, and windows vista. More platforms and binaries as time permits.

Stream parsing

YAJL remembers all state required to support restarting parsing. This allows parsing to occur incrementally as data is read off a disk or network.

Fast

A second motivation for writing YAJL, was that many available free JSON parsers fall over on large or complex inputs. YAJL is careful to minimize memory copying and input re-scanning when possible. The result is a parser that should be fast enough for most applications or tunable for any application. On my mac pro (2.66 ghz) it takes 1s to verify a 60meg json file. Minimizing that same file with json_reformat takes 4s.

Low resource consumption

Largely because YAJL deals with streams, it's possible to parse JSON in low memory environments. Oftentimes with other parsers an application must hold both the input text and the memory representation of the tree in memory at one time. With YAJL you can incrementally read the input stream and hold only the in memory representation. Or for filtering or validation tasks, it's not required to hold the entire input text in memory.

sample programs

included in the source are a couple sample programs to demonstrate and test yajl:
json_reformat: a minimizer and beautifier in one.
json_verify: a JSON verifier.

comments in JSON

If you're dead set on using JSON throughout your system, you'll probably end up using it for your configuration files too. A little crazy, perhaps. But so am I. At parser allocation time you may specify a configuration parameter to allow comments inside the JSON input text. This is supported in versions 0.2.0 and above.

Example Programmatic Usage In C

#include <yajl/yajl_parse.h>
#include <yajl/yajl_gen.h>

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/* non-zero when we're reformatting a stream */
static int s_streamReformat = 0;

#define GEN_AND_RETURN(func)                                          \
    {                                                                 \
        yajl_gen_status __stat = func;                                \
        if (__stat == yajl_gen_generation_complete && s_streamReformat) { \
            yajl_gen_reset(g, "\n");                                    \
            __stat = func;                                              \
        }                                                               \
        return __stat == yajl_gen_status_ok;                            \
    }

static int reformat_null(void * ctx)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_null(g));
}

static int reformat_boolean(void * ctx, int boolean)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_bool(g, boolean));
}

static int reformat_number(void * ctx, const char * s, size_t l)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_number(g, s, l));
}

static int reformat_string(void * ctx, const unsigned char * stringVal,
                           size_t stringLen)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_string(g, stringVal, stringLen));
}

static int reformat_map_key(void * ctx, const unsigned char * stringVal,
                            size_t stringLen)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_string(g, stringVal, stringLen));
}

static int reformat_start_map(void * ctx)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_map_open(g));
}

static int reformat_end_map(void * ctx)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_map_close(g));
}

static int reformat_start_array(void * ctx)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_array_open(g));
}

static int reformat_end_array(void * ctx)
{
    yajl_gen g = (yajl_gen) ctx;
    GEN_AND_RETURN(yajl_gen_array_close(g));
}

static yajl_callbacks callbacks = {
    reformat_null,
    reformat_boolean,
    NULL,
    NULL,
    reformat_number,
    reformat_string,
    reformat_start_map,
    reformat_map_key,
    reformat_end_map,
    reformat_start_array,
    reformat_end_array
};

#ifndef EXIT_USAGE
# define EXIT_USAGE	2
#endif

static void
usage(const char * progname)
{
    fprintf(stderr, "%s: reformat json from stdin\n"
            "usage:  json_reformat [options]\n"
            "    -e escape any forward slashes (for embedding in HTML)\n"
            "    -m minimize json rather than beautify (default)\n"
            "    -s reformat a stream of multiple json entites\n"
            "    -u allow invalid UTF8 inside strings during parsing\n",
            progname);
    exit(EXIT_USAGE);
}

int
main(int argc, char ** argv)
{
    yajl_handle hand;
    static unsigned char fileData[65536];
    /* generator config */
    yajl_gen g;
    yajl_status stat;
    size_t rd;
    int retval = 0;
    int a = 1;

g = yajl_gen_alloc(NULL);
    yajl_gen_config(g, yajl_gen_beautify, 1);
    yajl_gen_config(g, yajl_gen_validate_utf8, 1);

/* ok.  open file.  let's read and parse */
    hand = yajl_alloc(&callbacks, NULL, (void *) g);
    /* and let's allow comments by default */
    yajl_config(hand, yajl_allow_comments, 1);

/* check arguments.*/
    while ((a < argc) && (argv[a][0] == '-') && (strlen(argv[a]) > 1)) {
        unsigned int i;
        for ( i=1; i < strlen(argv[a]); i++) {
            switch (argv[a][i]) {
                case 'm':
                    yajl_gen_config(g, yajl_gen_beautify, 0);
                    break;
                case 's':
                    yajl_config(hand, yajl_allow_multiple_values, 1);
                    s_streamReformat = 1;
                    break;
                case 'u':
                    yajl_config(hand, yajl_dont_validate_strings, 1);
                    break;
                case 'e':
                    yajl_gen_config(g, yajl_gen_escape_solidus, 1);
                    break;
                default:
                    fprintf(stderr, "unrecognized option: '%c'\n\n",
                            argv[a][i]);
                    usage(argv[0]);
            }
        }
        ++a;
    }
    if (a < argc) {
        usage(argv[0]);
    }

for (;;) {
        rd = fread((void *) fileData, (size_t) 1, sizeof(fileData) - 1, stdin);

if (rd == 0) {
            if (!feof(stdin)) {
                fprintf(stderr, "error on file read.\n");
                retval = 1;
            }
            break;
        }
        fileData[rd] = 0;

stat = yajl_parse(hand, fileData, rd);

if (stat != yajl_status_ok) {
            break;
        } else {
            const unsigned char * buf;
            size_t len;
            yajl_gen_get_buf(g, &buf, &len);
            fwrite(buf, (size_t) 1, len, stdout);
            yajl_gen_clear(g);
        }
    }

if (stat != yajl_status_ok) {
        unsigned char * str = yajl_get_error(hand, 1, fileData, rd);
        fprintf(stderr, "%s", (const char *) str);
        yajl_free_error(hand, str);
        retval = 1;
    } else {
        stat = yajl_complete_parse(hand);
    }

yajl_gen_free(g);
    yajl_free(hand);

return retval;
}

License

Copyright (c) 2007-2011, Lloyd Hilaiel 

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Related projects

yajl-ruby - ruby bindings for YAJL
yajl-objc - Objective-C bindings for YAJL
YAJL IO bindings (for the IO language)
Python bindings come in two flavors, py-yajl OR yajl-py
yajl-js - node.js bindings (mirrored to github).
lua-yajl - lua bindings
ooc-yajl - ooc bindings
yajl-tcl - tcl bindings
JSON-YAJL - perl bindings
yajl-d - D bindings for YAJL
YAJL-Fort - Fortran bindings for YAJL

Contributors

Many people have helped hone yajl to a fine edge, they have my deep appreciation for taking the time to give back. Here they are in alphabetical order (if I missed anyone, please tell me. It's been a while and my memory is bad):

Adam McLaurin
Andrei Soroker
Artem S Vybornov (@vibornoff)
Bobby Powers (@bpowers)
Mr. Baptiste (@bapt)
Brian Lopez (@brianmario)
Brian Maher (@brimworks)
Conrad Irwin (@ConradIrwin)
Daniel P. Berrange
Eric Bergstrome
Florian Forster (@octo)
Greg A. Woods (@robohack)
Greg Olszewski (@gno)
Hatem Nassrat
John Stamp (@jstamp)
Karl Adam (@thekarladam)
Karl Lehenbauer
Mark de Does
Michael Hanson (@michaelrhanson)
Mirek Rusin (@mirek)
Neville Franks
R. Tyler Croy (@rtyler)
Randall E. Barker (@bluemarvin)
Rick (@technoweenie)
Robert Geiger
Robert Varga
Timothy J. Wood
Vitali Lovich

Original Author

Lloyd Hilaiel (lloyd 4t hilaiel d0t com)