View Source Euneus
An incredibly flexible and performant JSON parser, generator and formatter in pure Erlang.
Euneus is built on the top of the new OTP json module.
Both encoder and decoder fully conform to RFC 8259 and ECMA 404 standards and are tested using JSONTestSuite.
Detailed examples and further explanation can be found at hexdocs.
Installation
Erlang
% rebar.config
{deps, [
json_polyfill, % Required only for OTP < 27
{euneus, "2.4.0"}
]}.
Elixir
# mix.exs
defp deps do
[
{:json_polyfill, "~> 0.1"}, # Required only for OTP < 27
{:euneus, "~> 2.4"}
]
end
Or consider using Exneus:
# mix.exs
defp deps do
[
{:json_polyfill, "~> 0.1"}, # Required only for OTP < 27
{:exneus, "~> 0.1"}
]
end
Exneus is a wrapper of Euneus for Elixir.
Basic usage
1> euneus:encode(#{age => 68, name => <<"Joe Armstrong">>, nationality => <<"British">>}).
<<"{\"name\":\"Joe Armstrong\",\"age\":68,\"nationality\":\"British\"}">>
2> euneus:decode(v(1)).
#{<<"age">> => 68,<<"name">> => <<"Joe Armstrong">>,<<"nationality">> => <<"British">>}
Encode
The functions euneus:encode/1
euneus:encode/2
encodes an Erlang term into a binary JSON.
The second argument of euneus:encode/2
are options.
Please see the euneus_encoder
documentation
for more examples and detailed explanation.
The data mapping and error reasons can be found in the OTP json encode function documentation.
Decode
The functions euneus:decode/1
and euneus:decode/2
decodes a binary JSON into an Erlang term.
The second argument of euneus:decode/2
are options.
Please see the euneus_decoder
documentation
for more examples and detailed explanation.
The data mapping and error reasons can be found in the OTP json decode function documentation.
Stream
Three functions provide JSON decode streaming:
euneus:decode_stream_start/1
- Equivalent toeuneus:decode_stream_start(JSON, #{})
;euneus:decode_stream_start/2
- Begin parsing a stream of bytes of a JSON value;euneus:decode_stream_continue/2
- Continue parsing a stream of bytes of a JSON value.
Please see the euneus_decoder
documentation
for more examples and detailed explanation.
Format
Two functions provide JSON formatting:
euneus:minify/1
- Removes any extra spaces and new line characters;euneus:format/2
- Formats the JSON by passing custom options.
Please see the euneus_formatter
documentation
for more examples and detailed explanation.
Benchmark
The benchmarks are implemented very simply, but they are a good start foroptimizing
Euneus since no optimizations have been made. You will find the benchmark commands
in euneus_benchmarker
, and data and tests under the test folder.
[!IMPORTANT] For the first benchmark run, bootstrapping
erlperf
is required:$ rebar3 as benchmark shell 1> euneus_benchmarker:bootstrap(). ===> Verifying dependencies... ===> Analyzing applications... ===> Compiling erlperf ===> Building escript for erlperf... ok
Results
Setup:
- OS : Linux
- CPU: 12th Gen Intel(R) Core(TM) i9-12900HX
- VM : Erlang/OTP 27 [erts-15.0.1] [source] [64-bit] [smp:24:24] [ds:24:24:10] [async-threads:1] [jit:ns]
$ rebar3 as benchmark shell
1> euneus_benchmarker:encode_benchmark().
Code || Samples Avg StdDev Median P99 Iteration Rel
jiffy 1 3 26 36.69% 25 36 38474 us 100%
euneus 1 3 20 38.20% 18 29 49197 us 78%
thoas 1 3 10 36.06% 9 14 100 ms 38%
2> euneus_benchmarker:decode_benchmark().
Code || Samples Avg StdDev Median P99 Iteration Rel
euneus 1 3 24 2.44% 24 24 42268 us 100%
jiffy 1 3 19 3.09% 19 19 53589 us 79%
thoas 1 3 14 0.00% 14 14 71452 us 59%
Sponsors
If you like this tool, please consider sponsoring me. I'm thankful for your never-ending support :heart:
I also accept coffees :coffee:
License
Copyright (c) 2024 William Fank Thomé
Euneus is 100% open-source and community-driven. All components are available under the Apache 2 License on GitHub.
See LICENSE.md for more information.