View Source euneus_encoder (euneus v2.0.0)

Summary

Functions

Encode a term into an iodata JSON.

Types

-type codec() ::
          timestamp | datetime | ipv4 | ipv6 |
          {records, #{Name :: atom() := {Fields :: [atom()], Size :: pos_integer()}}} |
          codec_callback().
-type codec_callback() :: fun((tuple()) -> next | {halt, term()}).
-type encode(Type) :: fun((Type, json:encoder(), state()) -> iodata()).
-type is_proplist() :: fun((list()) -> boolean()).
-type options() ::
          #{codecs => [codec()],
            nulls => [term()],
            skip_values => [term()],
            key_to_binary => fun((term()) -> binary()),
            sort_keys => boolean(),
            proplists => boolean() | {true, is_proplist()},
            escape => fun((binary()) -> iodata()),
            encode_integer => encode(integer()),
            encode_float => encode(float()),
            encode_atom => encode(atom()),
            encode_list => encode(list()),
            encode_map => encode(map()),
            encode_tuple => encode(tuple()),
            encode_pid => encode(pid()),
            encode_port => encode(port()),
            encode_reference => encode(reference())}.
-opaque state()

Functions

-spec encode(term(), options()) -> iodata().

Encode a term into an iodata JSON.

Example:

  1> euneus_encoder:encode(foo, #{}).
  [$", <<"foo">>, $"]

Option details:

    Note

    For better visualization and understanding, all options examples use euneus:encode/2, which returns a binary.
  • codecs - Transforms tuples into any other Erlang term that will be encoded again into a JSON value. By returning next, the next codec will be called, or by returning {halt, Term :: term()}, the Term will be encoded again.

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

    Default is [].

    Built-in codecs:

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

      Example:

        1> euneus:encode({0, 0, 0}, #{codecs => [timestamp]}).
        <<"\"1970-01-01T00:00:00.000Z\"">>
    • datetime - Transforms a calendar:datetime/0 into an ISO 8601 string.

      Example:

        1> euneus:encode({{1970, 01, 01}, {00, 00, 00}}, #{codecs => [datetime]}).
        <<"\"1970-01-01T00:00:00Z\"">>
    • ipv4 - Transforms an inet:ip4_address/0 into a JSON string.

      Example:

        1> euneus:encode({127, 0, 0, 1}, #{codecs => [ipv4]}).
        <<"\"127.0.0.1\"">>
    • ipv6 - Transforms an inet:ip6_address/0 into a JSON string.

      Example:

        1> euneus:encode({0, 0, 0, 0, 0, 0, 0, 0}, #{codecs => [ipv6]}).
        <<"\"::\"">>
        2> euneus:encode({0, 0, 0, 0, 0, 0, 0, 1}, #{codecs => [ipv6]}).
        <<"\"::1\"">>
        3> euneus:encode(
        ..     {0, 0, 0, 0, 0, 0, (192 bsl 8) bor 168, (42 bsl 8) bor 2},
        ..     #{codecs => [ipv6]}
        .. ).
        <<"\"::192.168.42.2\"">>
        4> euneus:encode(
        ..     {0, 0, 0, 0, 0, 16#FFFF, (192 bsl 8) bor 168, (42 bsl 8) bor 2},
        ..     #{codecs => [ipv6]}
        .. ).
        <<"\"::ffff:192.168.42.2\"">>
        5> euneus:encode(
        ..     {16#3ffe, 16#b80, 16#1f8d, 16#2, 16#204, 16#acff, 16#fe17, 16#bf38},
        ..     #{codecs => [ipv6]}
        .. ).
        <<"\"3ffe:b80:1f8d:2:204:acff:fe17:bf38\"">>
        6> euneus:encode(
        ..     {16#fe80, 0, 0, 0, 16#204, 16#acff, 16#fe17, 16#bf38},
        ..     #{codecs => [ipv6]}
        .. ).
        <<"\"fe80::204:acff:fe17:bf38\"">>
    • records - Transforms records into JSON objects.

      Example:

        1> euneus:encode(
        ..     % Same as '-record(foo, {bar, baz}).'
        ..     {foo, bar, baz},
        ..     #{codecs => [{records, #{
        ..         % Same as 'foo => {record_info(fields, foo), record_info(size, foo)}'
        ..         foo => {[bar, baz], 3}
        ..     }}]}
        .. ).
        <<"{\"bar\":\"bar\",\"baz\":\"baz\"}">>

    Custom codec example:

      1> euneus:encode({foo}, #{codecs => [fun({foo}) -> {halt, foo} end]}).
      <<"\"foo\"">>
  • nulls - Defines which values should be encoded as null.

    Default is [null].

    Example:

      1> euneus:encode([null, nil, foo], #{nulls => [null, nil]}).
      <<"[null,null,\"foo\"]">>
  • skip_values - Defines which map values should be ignored. This option permits achieves the same behavior as Javascript, which ignores undefined values of objects.

    Default is [undefined].

    Example:

      1> euneus:encode(
      ..     #{foo => bar, bar => undefined, baz => null},
      ..     #{skip_values => [undefined, null]}
      .. ).
      <<"{\"foo\":\"bar\"}">>
  • key_to_binary - Overrides the default conversion of map keys to a string.
  • sort_keys - Defines if the object keys should be sorted.

    Default is false.

    Example:

      1> euneus:encode(#{c => c, a => a, b => b}, #{sort_keys => true}).
      <<"{\"a\":\"a\",\"b\":\"b\",\"c\":\"c\"}">>
  • proplists - If true, converts proplists into objects.

    Default is false.

    Example:

      1> euneus:encode([{foo, bar}, baz], #{proplists => true}).
      <<"{\"foo\":\"bar\",\"baz\":true}">>
      2> euneus:encode(
      ..     [{foo, bar}, {baz, true}],
      ..     % Overrides the default is proplist check:
      ..     #{proplists => {true, fun([{_, _} | _]) -> true end}}
      .. ).
      <<"{\"foo\":\"bar\",\"baz\":true}">>
  • escape - Overrides the default string escaping.
  • encode_integer - Overrides the default integer encoder.
  • encode_float - Overrides the default float encoder.
  • encode_atom - Overrides the default atom encoder.
  • encode_list - Overrides the default list encoder.
  • encode_map - Overrides the default map encoder.
  • encode_tuple- Overrides the default tuple encoder.
  • encode_pid - Overrides the default pid encoder.
  • encode_port - Overrides the default port encoder.
  • encode_reference - Overrides the default reference encoder.