jsone/README.md

jsone (0.2.3)

An Erlang library for encoding, decoding JSON data.

Features

• Provides simple encode/decode function only
• RFC4627-compliant
• Supports UTF-8 encoded binary
• Pure Erlang
• Highly Efficient
  • Maybe one of the fastest JSON library (except those which are implemented in NIF)
    • See Benchmark
  • Decode function is written in continuation-passing style(CPS)
    • CPS facilitates application of 'creation of sub binary delayed' optimization
    • See also Erlang Efficiency Guide

QuickStart

# clone
$ git clone git://github.com/sile/jsone.git
$ cd jsone

# If you want to use HiPE enabled version, please execute following command.
# $ git checkout hipe

# compile
$ make compile

# run tests
$ make eunit

# dialyze
$ make dialyze

# Erlang shell
$ make start
1> jsone:decode(<<"[1,2,3]">>).
[1,2,3]

Usage Example

%% Decode
> jsone:decode(<<"[1,2,3]">>).
[1,2,3]

> jsone:decode(<<"{\"1\":2}">>).
{[{<<"1">>,2}]}

> jsone:try_decode(<<"[1,2,3] \"next value\"">>). % try_decode/1 returns remaining (unconsumed binary)
{ok,[1,2,3],<<" \"next value\"">>}

% error: raises exception
> jsone:decode(<<"1.x">>).
** exception error: bad argument
     in function  jsone_decode:number_fraction_part_rest/6
        called as jsone_decode:number_fraction_part_rest(<<"x">>,1,1,0,[],<<>>)
     in call from jsone:decode/1 (src/jsone.erl, line 71)

% error: returns {error, Reason}
> jsone:try_decode(<<"1.x">>).
{error,{badarg,[{jsone_decode,number_fraction_part_rest,
                              [<<"x">>,1,1,0,[],<<>>],
                              [{line,228}]}]}}


%% Encode
> jsone:encode([1,2,3]).
<<"[1,2,3]">>

> jsone:encode({[{<<"key">>, <<"value">>}]}).
<<"{\"key\":\"value\"}">>

% error: raises exception
> jsone:encode({[{key, <<"value">>}]}). % non binary key is not allowed
** exception error: bad argument
     in function  jsone_encode:object_members/3
        called as jsone_encode:object_members([{key,<<"value">>}],[],<<"{">>)
     in call from jsone:encode/1 (src/jsone.erl, line 97)

% error: returns {error, Reason}
> jsone:try_encode({[{key, <<"value">>}]}).
{error,{badarg,[{jsone_encode,object_members,
                              [[{key,<<"value">>}],[],<<"{">>],
                              [{line,138}]}]}}

Data Mapping (Erlang <=> JSON)

	Erlang	JSON
number	123	123
null	null	null
boolean	true	true
string	<<"abc">>	"abc"
array	[1,2,3]	[1,2,3]
object	{[{<<"key">>, <<"value">>}]}	{"key":"value"}

API

See EDoc Document

Benchmark

Environment/Method

• OS: CentOS 6.5
• CPU: Intel(R) Xeon(R) CPU E5-2680 v2 @ 2.80GHz (x8)
• Erlang/OTP: R17.1
• Benchmark Tool: erl_json_test
• CompileOption: [native, {hipe, [o3]}]

Target

• jiffy-0.11.3 (NIF)
• jsone-v0.2.3 (HiPE)
• jsonerl (HiPE)
• jsonx (NIF)
• jsx-v2.0.1 (HiPE)
• mochijson2 (HiPE)
• yawsjson2 (HiPE)

Decode Result

• column: module name
• row: data size (bytes)
• cell: elapsed time (micro seconds)

| | jiffy | jsone | jsonerl | jsonx | jsx | mochijson2 | yawsjson2 | |------------------:|------:|------:|--------:|------:|------:|-----------:|----------:| | 559 (1x) | 12 | 11 | 61 | 7 | 50 | 28 | 37 | | 1583 (3x) | 24 | 25 | 66 | 15 | 134 | 68 | 84 | | 4637 (9x) | 65 | 86 | 178 | 36 | 410 | 186 | 311 | | 13914 (27x) | 189 | 271 | 533 | 109 | 1466 | 550 | 582 | | 41542 (81x) | 525 | 813 | 1578 | 299 | 4684 | 1599 | 1939 | | 124726 (243x) | 1549 | 2406 | 4709 | 852 | 14562 | 4799 | 6123 |

Encode Result

• column: module name
• row: data size (bytes)
• cell: elapsed time (micro seconds)

| | jiffy | jsone | jsonerl | jsonx | jsx | mochijson2 | yawsjson2 | |------------------:|------:|------:|--------:|------:|------:|-----------:|----------:| | 559 (1x) | 14 | 19 | 21 | 8 | 83 | 19 | 15 | | 1583 (3x) | 29 | 49 | 65 | 14 | 228 | 61 | 42 | | 4637 (9x) | 77 | 133 | 229 | 36 | 638 | 225 | 161 | | 13914 (27x) | 215 | 393 | 737 | 101 | 1993 | 664 | 435 | | 41542 (81x) | 621 | 1172 | 2058 | 300 | 6237 | 2310 | 1192 | | 124726 (243x) | 1830 | 3968 | 5842 | 828 | 17032 | 6979 | 5266 |