README.md

[![Hex.pm](https://img.shields.io/hexpm/v/jaxon.svg)](https://hex.pm/packages/jaxon)

------------------------------------

# 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](https://hexdocs.pm/jaxon/)

## :muscle:   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


## :running:  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?**

## :rocket:  Installation

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

## :thinking:  How to use it

### Decode a binary into events

```elixir
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 decoding

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

```elixir
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


```elixir
: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.
```

Developed at [Sqlify.io](https://sqlify.io) for big data JSON parsing.