-spec decode(JSON, Options) -> term() when JSON :: binary(), Options :: options().

Decodes a binary JSON into a term.

Example:

  1> euneus_decoder:decode(<<"\"foo\"">>, #{}).
  <<"foo">>

Option details:

• codecs - Transforms a JSON binary value into an Erlang term. By returning next, the next codec will be called, or by returning {halt, Term :: term()}, the Term is returned as the value.

  You can use the built-in codecs or your own. Please see the euneus_decoder:codec/0 type for details.

  Default is [].

  Built-in codecs:

  • timestamp - Transforms an ISO 8601 string with milliseconds into an erlang:timestamp/0.

    Example:

      1> euneus_decoder:decode(<<"\"1970-01-01T00:00:00.000Z\"">>, #{codecs => [timestamp]}).
      {0, 0, 0}

  • datetime - Transforms an ISO 8601 string into a calendar:datetime/0.

    Example:

      1> euneus_decoder:decode(<<"\"1970-01-01T00:00:00Z\"">>, #{codecs => [datetime]}).
      {{1970, 01, 01},{00, 00, 00}}

  • ipv4 - Transforms a JSON string into an inet:ip4_address/0.

    Example:

      1> euneus_decoder:decode(<<"\"127.0.0.1\"">>, #{codecs => [ipv4]}).
      {127, 0, 0, 1}

  • ipv6 - Transforms a JSON string into an inet:ip6_address/0.

    Example:

      1> euneus_decoder:decode(<<"\"::\"">>, #{codecs => [ipv6]}).
      {0, 0, 0, 0, 0, 0, 0, 0}
      2> euneus_decoder:decode(<<"\"::1\"">>, #{codecs => [ipv6]}).
      {0, 0, 0, 0, 0, 0, 0, 1}
      3> euneus_decoder:decode(<<"\"::192.168.42.2\"">>, #{codecs => [ipv6]}).
      {0, 0, 0, 0, 0, 0, (192 bsl 8) bor 168, (42 bsl 8) bor 2}
      4> euneus_decoder:decode(<<"\"::ffff:192.168.42.2\"">>, #{codecs => [ipv6]}).
      {0, 0, 0, 0, 0, 16#FFFF, (192 bsl 8) bor 168, (42 bsl 8) bor 2}
      5> euneus_decoder:decode(<<"\"3ffe:b80:1f8d:2:204:acff:fe17:bf38\"">>, #{codecs => [ipv6]}).
      {16#3ffe, 16#b80, 16#1f8d, 16#2, 16#204, 16#acff, 16#fe17, 16#bf38}
      6> euneus_decoder:decode(<<"\"fe80::204:acff:fe17:bf38\"">>, #{codecs => [ipv6]}).
      {16#fe80, 0, 0, 0, 16#204, 16#acff, 16#fe17, 16#bf38}

  • pid - Transforms a JSON string into an erlang:pid/0.

    Example:

      1> euneus_decoder:decode(<<"\"<0.92.0>\"">>, #{codecs => [pid]})
      .. =:= list_to_pid("<0.92.0>").
      true

  • port - Transforms a JSON string into an erlang:port/0.

    Example:

      1> euneus_decoder:decode(<<"\"#Port<0.1>\"">>, #{codecs => [port]})
      .. =:= list_to_port("#Port<0.1>").
      true

  • reference - Transforms a JSON string into an erlang:reference/0.

    Example:

      1> euneus_decoder:decode(<<"\"#Ref<0.314572725.1088159747.110918>\"">>, #{codecs => [reference]})
      .. =:= list_to_ref("#Ref<0.314572725.1088159747.110918>").
      true

  Custom codec example:

    1> euneus:decode(<<"\"foo\"">>, #{codecs => [fun(<<"foo">>) -> {halt, foo} end]}).
    foo

• null - Defines which term should be considered null.

  Default is null.

  Example:

    1> euneus_decoder:decode(<<"null">>, #{null => nil}).
    nil

• binary_to_float - Overrides the default binary to float conversion.

• binary_to_integer - Overrides the default binary to integer conversion..

• array_start - Overrides the json:array_start_fun/0 callback.

• array_push - Overrides the json:array_push_fun/0 callback.

• array_finish - Overrides the json:array_finish_fun/0 callback.

  In addition to the custom function, there are:

  • ordered - Returns the array in the same order as the JSON.

    That's the slower option.

    Example:

      1> euneus_decoder:decode(<<"[1,2,3]">>, #{array_finish => ordered}).
      [1,2,3]

  • reversed - Returns the array in a reversed order.

    That's the faster option.

    Example:

      1> euneus_decoder:decode(<<"[1,2,3]">>, #{array_finish => reversed}).
      [3,2,1]

  Default is ordered.

• object_start - Overrides the json:object_start_fun/0 callback.

• object_keys - Transforms JSON objects key into Erlang term.

  In addition to the custom function, there are:

  • binary - Returns the key as erlang:binary/0.
  • copy - Copies the key via binary:copy/1 returning it as erlang:binary/0.
  • atom - Returns the key as erlang:atom/0 via erlang:binary_to_atom/2.
  • existing_atom - Returns the key as erlang:atom/0 via erlang:binary_to_existing_atom/2.

  Default is binary.

• object_push - Overrides the json:object_push_fun/0 callback.

• object_finish - Overrides the json:object_finish_fun/0 callback.

  In addition to the custom function, there are:

  • map - Returns the object as a erlang:map/0.

    That's the slower option.

    Example:

      1> euneus_decoder:decode(
      ..     <<"{\"a\":\"a\",\"b\":\"b\",\"c\":\"c\"}">>,
      ..     #{object_finish => map}
      .. ).
      #{<<"a">> => <<"a">>,<<"b">> => <<"b">>,<<"c">> => <<"c">>}

  • proplist - Returns the object as an ordered proplists:proplist/0.

    Example:

      1> euneus_decoder:decode(
      ..     <<"{\"a\":\"a\",\"b\":\"b\",\"c\":\"c\"}">>,
      ..     #{object_finish => proplist}
      .. ).
      [{<<"a">>, <<"a">>},{<<"b">>, <<"b">>},{<<"c">>, <<"c">>}]

  • reversed_proplist - Returns the object as a reversed proplists:proplist/0.

    That's the faster option.

    Example:

      1> euneus_decoder:decode(
      ..     <<"{\"a\":\"a\",\"b\":\"b\",\"c\":\"c\"}">>,
      ..     #{object_finish => reversed_proplist}
      .. ).
      [{<<"c">>, <<"c">>},{<<"b">>, <<"b">>},{<<"a">>, <<"a">>}]

  Default is map.

-spec stream_continue(JSON, State) -> stream_result()
                         when JSON :: binary() | end_of_input, State :: stream_state().

Continue parsing a stream of bytes of a JSON value.

Similar to stream_start/2, if the function returns {continue, State} and there is no more data, use end_of_input instead of a binary.

Example:

  1> begin
  .. {continue, State} = euneus_decoder:stream_start(<<"{\"foo\":">>, #{}),
  .. euneus_decoder:stream_continue(<<"1}">>, State)
  .. end.
  {end_of_input,#{<<"foo">> => 1}}

-spec stream_start(JSON, Options) -> stream_result() when JSON :: binary(), Options :: options().

Begin parsing a stream of bytes of a JSON value.

Similar to decode/2 but returns {end_of_input, Term} when a complete JSON value is parsed or returns {continue, State} for incomplete data.

The State can be fed to the stream_continue/2 function when more data is available.