A polyfill for the OTP json module (EEP68)
APACHE-2.0 License
This lib is just a copy of the json
module proposed in EEP 68 and introduced in OTP 27 by Michał Muskała.
Its intent is to act as a polyfill for apps that cannot currently be updated to OTP 27 or higher.
The module and function names are exactly the same. Then, when your app supports OTP >= 27, just remove this lib from the dependencies.
% rebar.config
{deps, [{json_polyfill, "0.1.4"}]}.
# mix.exs
def deps do
[{:json_polyfill, "~> 0.1.4"}]
end
Generates JSON corresponding to Term
.
Supports basic data mapping:
Erlang | JSON |
---|---|
integer() | float() |
Number |
true | false |
Boolean |
null |
Null |
binary() |
String |
atom() |
String |
list() |
Array |
#{binary() => _} |
Object |
#{atom() => _} |
Object |
#{integer() => _} |
Object |
This is equivalent to encode(Term, fun json:encode_value/2)
.
> iolist_to_binary(json:encode(#{foo => <<"bar">>})).
<<"{\"foo\":\"bar\"}">>
Generates JSON corresponding to Term
.
Can be customised with the Encoder
callback. The callback will be recursively called for all the data to be encoded and is expected to return the corresponding encoded JSON as iodata.
Various encode_*
functions in this module can be used to help in constructing such callbacks.
An encoder that uses a heuristic to differentiate object-like lists of key-value pairs from plain lists:
> encoder([{_, _} | _] = Value, Encode) -> json:encode_key_value_list(Value, Encode);
> encoder(Other, Encode) -> json:encode_value(Other, Encode).
> custom_encode(Value) -> json:encode(Value, fun(Value, Encode) -> encoder(Value, Encode) end).
> iolist_to_binary(custom_encode([{a, []}, {b, 1}])).
<<"{\"a\":[],\"b\":1}">>
Parses a JSON value from Binary
.
Supports basic data mapping:
JSON | Erlang |
---|---|
Number | integer() | float() |
Boolean | true | false |
Null | null |
String | binary() |
Object | #{binary() => _} |
error(unexpected_end)
if Binary
contains incomplete JSON valueerror({invalid_byte, Byte})
if Binary
contains unexpected byte or invalid UTF-8 byteerror({invalid_sequence, Bytes})
if Binary
contains invalid UTF-8 escape> json:decode(<<"{\"foo\": 1}">>).
#{<<"foo">> => 1}
Parses a JSON value from Binary
.
Similar to decode/1
except the decoding process can be customized with the callbacks specified in Decoders
. The callbacks will use the Acc
value as the initial accumulator.
Any leftover, unparsed data in Binary
will be returned.
All callbacks are optional. If not provided, they will fall back to implementations used by the decode/1
function:
array_start
: fun(_) -> [] end
array_push
: fun(Elem, Acc) -> [Elem | Acc] end
array_finish
: fun(Acc, OldAcc) -> {lists:reverse(Acc), OldAcc} end
object_start
: fun(_) -> [] end
object_push
: fun(Key, Value, Acc) -> [{Key, Value} | Acc] end
object_finish
: fun(Acc, OldAcc) -> {maps:from_list(Acc), OldAcc} end
float
: fun erlang:binary_to_float/1
integer
: fun erlang:binary_to_integer/1
string
: fun (Value) -> Value end
null
: the atom null
error({invalid_byte, Byte})
if Binary
contains unexpected byte or invalid UTF-8 byteerror({invalid_sequence, Bytes})
if Binary
contains invalid UTF-8 escapeerror(unexpected_end)
if Binary
contains incomplete JSON valueDecoding object keys as atoms:
> Push = fun(Key, Value, Acc) -> [{binary_to_existing_atom(Key), Value} | Acc] end.
> json:decode(<<"{\"foo\": 1}">>, ok, #{object_push => Push}).
{#{foo => 1},ok,<<>>}
Erlang/OTP is released under the Apache License 2.0.
%CopyrightBegin%
Copyright Ericsson AB 2010-2024. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
%CopyrightEnd%