-spec decode(binary() | iolist()) -> term().

Decode a JSON binary or iolist to an Erlang term. JSON objects are returned as maps (default). Raises {parse_error, Msg} on invalid input.

Examples

1> glazer_json:decode(<<"{\"a\":1,\"b\":[true,null,3.5]}">>).
#{<<"a">> => 1, <<"b">> => [true, null, 3.5]}

2> glazer_json:decode(<<"not json">>).
** exception error: {parse_error,<<"...">>}

-spec decode(binary() | iolist(), decode_opts()) -> term().

Decode a JSON binary or iolist to an Erlang term with options (see decode_opts/0). Raises {parse_error, Reason} on invalid input.

Examples

%% Object keys as atoms
1> glazer_json:decode(<<"{\"a\":1}">>, [{keys, atom}]).
#{a => 1}

%% JSON null as the atom `nil`
2> glazer_json:decode(<<"{\"a\":null}">>, [use_nil]).
#{<<"a">> => nil}

%% Objects as jiffy-style proplist tuples
3> glazer_json:decode(<<"{\"a\":1}">>, [object_as_tuple]).
{[{<<"a">>, 1}]}

-spec 'decode!'(binary() | iolist()) -> term().

Decode a JSON binary to an Erlang term. Equivalent to decode/1, provided for API parity with Elixir's JSON.decode!/1. Raises {parse_error, Reason} on invalid input.

Examples

1> glazer_json:'decode!'(<<"{\"a\":1}">>).
#{<<"a">> => 1}

-spec encode(term()) -> binary().

Encode an Erlang term to a JSON binary.

Raises {encode_error, {Msg, Term}} if Data contains a value that cannot be represented as JSON (e.g. an improper list, a pid, or an unsupported tuple).

Examples

1> glazer_json:encode(#{<<"a">> => 1, <<"b">> => [true, null, 3.5]}).
<<"{\"a\":1,\"b\":[true,null,3.5]}">>

2> glazer_json:encode(<<"hello">>).
<<"\"hello\"">>

3> glazer_json:encode(123456789012345678901234567890).
<<"123456789012345678901234567890">>

4> glazer_json:encode([1|2]).
** exception error: {encode_error,{<<"improper list">>,2}}

-spec encode(term(), encode_opts()) -> binary().

Encode an Erlang term to a JSON binary with options (see encode_opts/0).

Raises {encode_error, {Msg, Term}} if Data contains a value that cannot be represented as JSON.

Examples

%% Pretty-print with two-space indentation
1> glazer_json:encode(#{a => 1}, [pretty]).
<<"{\n  \"a\": 1\n}">>

%% Escape non-ASCII characters as \\uXXXX
2> glazer_json:encode(<<"héllo"/utf8>>, [uescape]).
<<"\"h\\u00e9llo\"">>

%% Encode the atom `nil` as JSON null
3> glazer_json:encode(#{<<"a">> => nil}, [use_nil]).
<<"{\"a\":null}">>

%% A binary with an invalid UTF-8 byte (0x80 is a lone continuation byte)
%% is copied through verbatim by default, yielding output that is not
%% valid UTF-8/JSON
4> glazer_json:encode(<<"a", 128, "b">>).
<<"\"a", 128, "b\"">>

%% force_utf8 replaces the invalid byte with U+FFFD (encoded as 0xEF 0xBF 0xBD)
5> glazer_json:encode(<<"a", 128, "b">>, [force_utf8]).
<<"\"a", 239, 191, 189, "b\"">>

%% force_utf8 + uescape further escapes the replacement character
6> glazer_json:encode(<<"a", 128, "b">>, [force_utf8, uescape]).
<<"\"a\\ufffdb\"">>

-spec 'encode!'(term()) -> binary().

Encode an Erlang term to a JSON binary. Equivalent to encode/1, provided for API parity with Elixir's JSON.encode!/1. Raises {encode_error, Msg} if Data cannot be encoded.

Examples

1> glazer_json:'encode!'(#{<<"a">> => 1}).
<<"{\"a\":1}">>

-spec 'encode_to_iodata!'(term()) -> iodata().

Encode an Erlang term to JSON as iodata. Equivalent to encode/1 (which already returns a binary, itself valid iodata), provided for API parity with Elixir's JSON.encode_to_iodata!/1. Raises {encode_error, Msg} if Data cannot be encoded.

Examples

1> glazer_json:'encode_to_iodata!'(#{<<"a">> => 1}).
<<"{\"a\":1}">>

-spec minify(binary() | iolist()) -> binary().

Minify a JSON binary or iolist, removing all unnecessary whitespace.

Examples

1> glazer_json:minify(<<"{\n  \"a\": 1,\n  \"b\": [1, 2, 3]\n}">>).
<<"{\"a\":1,\"b\":[1,2,3]}">>

-spec prettify(binary() | iolist()) -> binary().

Pretty-print a JSON binary or iolist with indentation.

Examples

1> glazer_json:prettify(<<"{\"a\":1,\"b\":[1,2,3]}">>).
<<"{\n   \"a\": 1,\n   \"b\": [\n      1,\n      2,\n      3\n   ]\n}">>

2> glazer_json:prettify(<<"{}">>).
<<"{}">>

-spec query(binary() | iolist(), binary() | iolist()) -> {ok, [term()]} | {error, query_reason()}.

Run a jq Filter program against a JSON binary or iolist Input, returning one Erlang term per value produced by the filter (in the order they are emitted by jq).

Requires glazer to have been built against libjq; if libjq was not available at build time, this returns {error, jq_not_available}.

A runtime error raised by the filter itself (e.g. via jq's error/0,1) is returned as {error, Msg} where Msg is the binary message produced by jq.

Examples

1> glazer_json:query(<<"{\"a\":[1,2,3]}">>, <<".a[]">>).
{ok,[1,2,3]}

2> glazer_json:query(<<"{\"a\":1}">>, <<".b">>).
{ok,[null]}

3> glazer_json:query(<<"not json">>, <<".">>).
{error, invalid_input}

-spec query(binary() | iolist(), binary() | iolist(), decode_opts()) ->
               {ok, [term()]} | {error, query_reason()}.

Like query/2, but decodes each result term using DecodeOpts (see decode/2).

Examples

1> glazer_json:query(<<"{\"a\":[1,2,3]}">>, <<".a">>, [{keys, atom}]).
{ok, [[1,2,3]]}

2> glazer_json:query(<<"{\"a\":null}">>, <<".a">>, [use_nil]).
{ok, [nil]}

-spec read_file(file:name_all()) -> term().

Read Filename and decode its contents as JSON.

Raises {parse_error, Reason} if the file's contents aren't valid JSON, or a binary "Filename: Reason" message (see file:format_error/1) if the file can't be read.

Example

1> glazer_json:read_file("data.json").
#{<<"a">> => 1}

-spec read_file(file:name_all(), decode_opts()) -> term().

Read Filename and decode its contents as JSON, with decode options (see decode/2).

-spec scan(binary() | iolist()) -> {complete, non_neg_integer()} | {incomplete, scan_state()}.

Locate the end of the next complete top-level JSON value in Bin, without decoding it.

Returns:

• {complete, EndOffset} - a complete value spans binary:part(Bin, 0, EndOffset); the rest of Bin (if any) is left over for the next call
• {incomplete, ScanState} - Bin doesn't yet contain a complete value; feed more data via scan/2 once it's available, passing the entire unconsumed remainder (this Bin, with new bytes appended) plus ScanState

This is the low-level primitive behind stream_feed/2; most callers should use the stream_* API instead.

Example

Slicing off complete values from a buffer of concatenated JSON:

1> Buf0 = <<"{\"a\":1} {\"b\":2}">>,
2> {complete, End1} = glazer_json:scan(Buf0).
{complete, 7}
3> <<Val1:End1/binary, Buf1/binary>> = Buf0,
4> Val1.
<<"{\"a\":1}">>
5> Buf1.
<<" {\"b\":2}">>
6> {complete, End2} = glazer_json:scan(Buf1).
{complete, 8}

Resuming a scan once more bytes arrive:

1> {incomplete, S0} = glazer_json:scan(<<"{\"a\":">>).
{incomplete, {6,1,false,false,true,false}}
2> glazer_json:scan(<<"{\"a\":1}">>, S0).
{complete, 7}

-spec scan(binary() | iolist(), scan_state()) ->
              {complete, non_neg_integer()} | {incomplete, scan_state()}.

Resume scanning Bin (the unconsumed remainder plus newly-appended bytes) from ScanState.

Examples

1> {incomplete, S0} = glazer_json:scan(<<"[1, 2,">>).
{incomplete, {6,1,false,false,true,false}}
2> glazer_json:scan(<<"[1, 2, 3]">>, S0).
{complete, 9}

-spec stream_decoder() -> stream_decoder().

Create a new incremental decoder for feeding JSON in chunks (e.g. from a socket or file), useful when a complete document isn't available up front or when a stream contains a sequence of concatenated/whitespace-separated JSON values (e.g. newline-delimited JSON).

Decoding itself is not incremental — each complete top-level value is still decoded in a single pass via decode/2 using the library's fast whole-buffer decoder. Only the boundary detection (finding where one value ends and the next begins) is incremental, via a small byte-scanner that tracks nesting/string state across chunks.

Example

1> D0 = glazer_json:stream_decoder(),
2> {Vals1, D1} = glazer_json:stream_feed(D0, <<"{\"a\":1} {\"b\":">>),
3> Vals1.
[#{<<"a">> => 1}]
4> {Vals2, _D2} = glazer_json:stream_feed(D1, <<"2}">>),
5> Vals2.
[#{<<"b">> => 2}]

-spec stream_decoder(decode_opts()) -> stream_decoder().

Create a new incremental decoder, passing Opts through to every decode/2 call.

-spec stream_eof(stream_decoder()) -> {ok, [term()]} | {error, term()}.

Signal end-of-stream: decode any remaining buffered bytes as a final value (useful for a trailing bare scalar, e.g. a lone number or true/null, which the scanner can't otherwise distinguish from a value that's still being written to mid-chunk).

Returns {ok, [Term]} with zero or one trailing value, or {error, Reason} if the remaining bytes don't form a complete value.

Example

1> D0 = glazer_json:stream_decoder(),
2> {Vals1, D1} = glazer_json:stream_feed(D0, <<"123">>),
3> Vals1.
[]
4> glazer_json:stream_eof(D1).
{ok, [123]}

A stream that ends mid-value (e.g. a dropped connection) yields an error instead of silently dropping the partial data:

1> D0 = glazer_json:stream_decoder(),
2> {Vals1, D1} = glazer_json:stream_feed(D0, <<"{\"a\":1, \"b\":">>),
3> Vals1.
[]
4> glazer_json:stream_eof(D1).
{error, _Reason}

-spec stream_feed(stream_decoder(), binary() | iolist()) -> {[term()], stream_decoder()}.

Feed a chunk of bytes into the decoder, returning any complete JSON values found so far (in order) along with the updated decoder.

Raises the same exceptions as decode/2 (e.g. Reason) if a value that the scanner deemed complete fails to decode.

Example

Call stream_feed/2 for each chunk received from the source while more data may still arrive, and stream_eof/1 once the source is exhausted to flush any trailing value:

loop(Socket, D0) ->
  case gen_tcp:recv(Socket, 0) of
    {ok, Chunk} ->
      {Vals, D1} = glazer_json:stream_feed(D0, Chunk),
      handle_values(Vals),
      loop(Socket, D1);
    {error, closed} ->
      case glazer_json:stream_eof(D0) of
        {ok, Trailing}  -> handle_values(Trailing);
        {error, Reason} -> handle_truncated_stream(Reason)
      end
  end.

The same decoder fits naturally into a gen_server driving an active-mode socket: keep the stream_decoder() in the process state, feed it from handle_info({tcp, ...}), and flush it on {tcp_closed, ...}:

-module(json_conn).
-behaviour(gen_server).
-export([start_link/1]).
-export([init/1, handle_call/3, handle_cast/2, handle_info/2]).

-record(state, {socket, decoder}).

start_link(Socket) ->
  gen_server:start_link(?MODULE, Socket, []).

init(Socket) ->
  inet:setopts(Socket, [{active, once}]),
  {ok, #state{socket = Socket, decoder = glazer_json:stream_decoder()}}.

handle_info({tcp, Socket, Data}, #state{socket = Socket, decoder = D0} = State) ->
  {Vals, D1} = glazer_json:stream_feed(D0, Data),
  lists:foreach(fun handle_value/1, Vals),
  inet:setopts(Socket, [{active, once}]),
  {noreply, State#state{decoder = D1}};

handle_info({tcp_closed, Socket}, #state{socket = Socket, decoder = D0} = State) ->
  case glazer_json:stream_eof(D0) of
    {ok, Trailing}  -> lists:foreach(fun handle_value/1, Trailing);
    {error, Reason} -> handle_truncated_stream(Reason)
  end,
  {stop, normal, State};

handle_info({tcp_error, Socket, Reason}, #state{socket = Socket} = State) ->
  {stop, Reason, State}.

handle_call(_Request, _From, State) -> {reply, ok, State}.
handle_cast(_Request, State)        -> {noreply, State}.

handle_value(Val) ->
  io:format("received: ~p~n", [Val]).

-spec try_decode(binary() | iolist()) -> {ok, term()} | {error, binary()}.

Decode a JSON binary or iolist, returning {ok, Term} or {error, Reason} instead of raising.

Examples

1> glazer_json:try_decode(<<"{\"a\":1}">>).
{ok, #{<<"a">> => 1}}

2> glazer_json:try_decode(<<"not json">>).
{error, <<"...">>}

-spec try_decode(binary() | iolist(), decode_opts()) -> {ok, term()} | {error, binary()}.

Decode a JSON binary or iolist with options (see decode_opts/0), returning {ok, Term} or {error, Reason} instead of raising.

Examples

1> glazer_json:try_decode(<<"{\"a\":1}">>, [{keys, atom}]).
{ok, #{a => 1}}

2> glazer_json:try_decode(<<"not json">>, [{keys, atom}]).
{error, <<"...">>}

-spec write_file(file:name_all(), term()) -> ok.

Encode Data to JSON and write it to Filename, overwriting any existing file.

Raises a binary "Filename: Reason" message (see file:format_error/1) if the file can't be written.

Example

1> glazer_json:write_file("data.json", #{<<"a">> => 1}).
ok

-spec write_file(file:name_all(), term(), encode_opts()) -> ok.

Encode Data to JSON with encode options (see encode/2) and write it to Filename, overwriting any existing file.