Jiffy - JSON NIFs for Erlang

A JSON parser as a NIF. This is a complete rewrite of the work I did in EEP0018 that was based on Yajl. This new version is a hand crafted state machine that does its best to be as quick and efficient as possible while not placing any constraints on the parsed JSON.

Usage

Jiffy is a simple API. The only thing that might catch you off guard is that the return type of jiffy:encode/1 is an iolist even though it returns a binary most of the time.

A quick note on unicode. Jiffy only understands UTF-8 in binaries. End of story.

Errors are raised as exceptions.

Eshell V5.8.2  (abort with ^G)
1> jiffy:decode(<<"{\"foo\": \"bar\"}">>).
{[{<<"foo">>,<<"bar">>}]}
2> Doc = {[{foo, [<<"bing">>, 2.3, true]}]}.
{[{foo,[<<"bing">>,2.3,true]}]}
3> jiffy:encode(Doc).
<<"{\"foo\":[\"bing\",2.3,true]}">>

jiffy:decode/1,2

• jiffy:decode(IoData)
• jiffy:decode(IoData, Options)

The options for decode are:

• {bytes_per_iter, N} where N >= 0 - This controls the number of bytes that Jiffy will process before yielding back to the VM. The mechanics of this yield are completely hidden from the end user.
• return_maps - Tell Jiffy to return objects using the maps data type on VMs that support it. This raises an error on VMs that don't support maps.
• {null_term, Term} - Returns the specified Term instead of null when decoding JSON. This is for people that wish to use undefined instead of null.
• use_nil - Returns the atom nil instead of null when decoding JSON. This is a short hand for {null_term, nil}.

jiffy:encode/1,2

• jiffy:encode(EJSON)
• jiffy:encode(EJSON, Options)

where EJSON is a valid representation of JSON in Erlang according to the table below.

The options for encode are:

• uescape - Escapes UTF-8 sequences to produce a 7-bit clean output
• pretty - Produce JSON using two-space indentation
• force_utf8 - Force strings to encode as UTF-8 by fixing broken surrogate pairs and/or using the replacement character to remove broken UTF-8 sequences in data.
• {bytes_per_iter, N} where N >= 0 - This controls the number of bytes that Jiffy will generate before yielding back to the VM. The mechanics of this yield are completely hidden from the end user.
• escape_forward_slashes - Escapes the / character which can be useful when encoding URLs in some cases.

Data Format

Erlang                          JSON            Erlang
==========================================================================

null                       -> null           -> null
true                       -> true           -> true
false                      -> false          -> false
"hi"                       -> [104, 105]     -> [104, 105]
<<"hi">>                   -> "hi"           -> <<"hi">>
hi                         -> "hi"           -> <<"hi">>
1                          -> 1              -> 1
1.25                       -> 1.25           -> 1.25
[]                         -> []             -> []
[true, 1.0]                -> [true, 1.0]    -> [true, 1.0]
{[]}                       -> {}             -> {[]}
{[{foo, bar}]}             -> {"foo": "bar"} -> {[{<<"foo">>, <<"bar">>}]}
{[{<<"foo">>, <<"bar">>}]} -> {"foo": "bar"} -> {[{<<"foo">>, <<"bar">>}]}
#{<<"foo">> => <<"bar">>}  -> {"foo": "bar"} -> #{<<"foo">> => <<"bar">>}

N.B. The last entry in this table is only valid for VM's that support the maps data type (i.e., 17.0 and newer) and client code must pass the return_maps option to jiffy:decode/2.

Improvements over EEP0018

Jiffy should be in all ways an improvement over EEP0018. It no longer imposes limits on the nesting depth. It is capable of encoding and decoding large numbers and it does quite a bit more validation of UTF-8 in strings.