Jaxon

Jaxon is an efficient and simple SAX-based JSON parser for Elixir, it's main goal is to be able to parse JSON data of any size with a very small memory footprint.

Online documentation

💪 Features

• Event based parsing: Parses data as it comes, no need to hold everything in memory, perfect for consuming large JSON streams of any size
• Pausable partial parsing: Pass a portion of your JSON and then resume parsing when you have the rest
• No schema restrictions: It only decodes JSON to Erlang terms

🏃 To do

• Reading with JSON path: Make an Elixir stream from a list of JSON path expressions.
• Better and more informative errors
• Unicode support in strings
• Benchmarking
• JSON encoding?

🚀 Installation

def deps do
  [
    {:jaxon, "~> 0.1.0"} # or {:jaxon, git: "https://github.com/boudra/jaxon.git", ref: "master"}
  ]
end

🤔 How to use

Event-based parsing

decoder =
    Jaxon.make_decoder()
    |> Jaxon.update_decoder("{\"jaxon\":\"rocks\",\"array\":[1,2]}")

# every decode/1 call with return a different parsing event
iex> Jaxon.decode(decoder)

# For the passed binary, the events will be:

iex> Jaxon.consume(decoder)
[
:start_object,
{:key, "jaxon"},
{:string, "rocks"},
{:key, "array"},
:start_array,
{:integer, 1},
{:integer, 2},
:end_array,
:end_object,
:end
]

Partial parsing

This is very useful when you're streaming JSON from the network or disk.

iex> d = Jaxon.make_decoder()
iex> d = Jaxon.update_decoder(d, "{\"whoo")

iex> d = Jaxon.decode(d)
:start_object

iex> {:incomplete, rest} = Jaxon.decode(d)
{:incomplete, "\"whoo"}

iex> d = Jaxon.update_decoder(d, rest <> "ps\":\":)\"}")
iex> Jaxon.decode(d)
{:key, "whoops"}

iex> Jaxon.decode(d)
{:string, ":)"}

iex> Jaxon.decode(d)
:end_object

iex> Jaxon.decode(d)
:end

Possible events returned

:start_object
:end_object
:start_array
:end_array
{:key, binary}
{:string, binary}
{:integer, integer}
{:decimal, float}
{:boolean, boolean}
nil
{:incomplete, binary}
:end
:error

License

Copyright © 2018 Mohamed Boudra <mohamed@boudra.me>

This project is under the Apache 2.0 license. See the LICENSE file for more details.