Module jsone

JSON decoding/encoding module.


JSON decoding/encoding module

Data Types


common_option() = undefined_as_null

- Treats undefined in Erlang as the conversion target for null in JSON. This means that undefined will be encoded to null and null will be decoded to undefined


datetime_encode_format() = datetime_format() | {Format::datetime_format(), TimeZone::timezone()}

Datetime encoding format.

The default value of TimeZone is utc.

  % Universal Time
  > jsone:encode({{2000, 3, 10}, {10, 3, 58}}, [{datetime_format, iso8601}]).
  % Local Time (JST)
  > jsone:encode({{2000, 3, 10}, {10, 3, 58}}, [{datetime_format, {iso8601, local}}]).
  % Explicit TimeZone Offset
  > jsone:encode({{2000, 3, 10}, {10, 3, 58}}, [{datetime_format, {iso8601, -2*60*60}}]).


datetime_format() = iso8601


decode_option() = {object_format, tuple | proplist | map} | {allow_ctrl_chars, boolean()} | reject_invalid_utf8 | {keys, binary | atom | existing_atom | attempt_atom} | {duplicate_map_keys, first | last} | common_option()

- Decoded JSON object format
- tuple: An object is decoded as {[]} if it is empty, otherwise {[{Key, Value}]}.
- proplist: An object is decoded as [{}] if it is empty, otherwise [{Key, Value}].
- map: An object is decoded as #{} if it is empty, otherwise #{Key => Value}.
- default: map if OTP version is OTP-17 or more, tuple otherwise

- If the value is true, strings which contain unescaped control characters will be regarded as a legal JSON string
- default: false

- Rejects JSON strings which contain invalid UTF-8 byte sequences

Defines way how object keys are decoded. The default value is binary. The option is compatible with labels option in jsx.
- binary: The key is left as a string which is encoded as binary. It's default and backward compatible behaviour.
- atom: The key is converted to an atom. Results in badarg if Key value regarded as UTF-8 is not a valid atom.
- existing_atom: Returns existing atom. Any key value which is not existing atom raises badarg exception.
- attempt_atom: Returns existing atom as existing_atom but returns a binary string if fails find one.

duplicate_map_keys: says that keys SHOULD be unique, but they don't have to be. Most JSON parsers will either give you the value of the first, or last duplicate property encountered. When object_format is tuple or proplist all duplicates are returned. When object_format is map by default the first instance of a duplicate is returned. Setting duplicate_map_keys to last will change this behaviour to return the last such instance. - If the value is first then the first duplicate key/value is returned.
- If the value is last then the last duplicate key/value is returned. - default: first


encode_option() = native_utf8 | native_forward_slash | canonical_form | {float_format, [float_format_option()]} | {datetime_format, datetime_encode_format()} | {object_key_type, string | scalar | value} | {space, non_neg_integer()} | {indent, non_neg_integer()} | {map_unknown_value, fun((term()) -> {ok, json_value()} | error)} | skip_undefined | common_option()

- Encodes non ASCII UTF-8 characters as a human-readable(non-escaped) string

- Prevents forward slashes in a JSON string from being escaped

- produce a canonical form of a JSON document

{float_format, Options}: - Encodes a float()` value in the format which specified by `Options
- default: [{scientific, 20}]

{datetime_format, Format}`: - Encodes a `calendar:datetime()` value in the format which specified by `Format
- default: {iso8601, utc}

object_key_type: - Allowable object key type
- string: Only string values are allowed (i.e. json_string() type)
- scalar: In addition to string, following values are allowed: nulls, booleans, numerics (i.e. json_scalar() type)
- value: Any json compatible values are allowed (i.e. json_value() type)
- default: string
- NOTE: If scalar or value option is specified, non json_string() key will be automatically converted to a binary() value (e.g. 1 => <<"1">>, #{} => <<"{}">>)

{space, N}:
- Inserts N spaces after every commna and colon
- default: 0

{indent, N}:
- Inserts a newline and N spaces for each level of indentation
- default: 0

- If speficied, each entry having undefined value in a object isn't included in the result JSON

{map_unknown_value, Fun}`: <br /> - If specified, unknown values encountered during an encoding process are converted to `json_value()` by applying `Fun.


float_format_option() = {scientific, Decimals::0..249} | {decimals, Decimals::0..253} | compact

- The float will be formatted using scientific notation with Decimals digits of precision.

- The encoded string will contain at most Decimals number of digits past the decimal point.
- If compact is provided the trailing zeros at the end of the string are truncated.

For more details, see erlang:float_to_list/2.

  > jsone:encode(1.23).
  > jsone:encode(1.23, [{float_format, [{scientific, 4}]}]).
  > jsone:encode(1.23, [{float_format, [{scientific, 1}]}]).
  > jsone:encode(1.23, [{float_format, [{decimals, 4}]}]).
  > jsone:encode(1.23, [{float_format, [{decimals, 4}, compact]}]).


json_array() = [json_value()]


json_boolean() = boolean()


json_number() = number()


json_object() = json_object_format_tuple() | json_object_format_proplist() | json_object_format_map()


json_object_format_map() = map()


json_object_format_proplist() = [{}] | json_object_members()


json_object_format_tuple() = {json_object_members()}


json_object_members() = [{json_string(), json_value()}]


json_scalar() = json_boolean() | json_number() | json_string()


json_string() = binary() | atom() | calendar:datetime()

NOTE: decode/1 always returns binary() value


json_term() = {{json, iolist()}} | {{json_utf8, unicode:chardata()}}

json_term() allows inline already encoded JSON value. json variant expects byte encoded utf8 data values as list members. json_utf8 expect Unicode code points as list members. Binaries are copied "as is" in both variants except json_utf8 will check if binary contain valid UTF-8 encoded data. In short, json uses erlang:iolist_to_binary/1 and json_utf8 uses unicode:chardata_to_binary/1 for encoding.

A simple example is worth a thousand words.

  1> S = "hélo".
  2> shell:strings(false).
  3> S.
  4> B = jsone:encode({{json, S}}).  % invalid UTF-8
  5> B2 = jsone:encode({{json_utf8, S}}). % valid UTF-8
  6> jsone:encode({{json, B}}).
  7> jsone:encode({{json_utf8, B}}).
  ** exception error: {invalid_json_utf8,<<104>>,<<233,108,111>>}
       in function  jsone_encode:value/4
          called as jsone_encode:value({json_utf8,<<104,233,108,111>>},
       in call from jsone:encode/2 (/home/hynek/work/altworx/jsone/_build/default/lib/jsone/src/jsone.erl, line 302)
  8> jsone:encode({{json_utf8, B2}}).
  9> shell:strings(true).
  10> jsone:encode({{json_utf8, B2}}).
  11> jsone:encode({{json, binary_to_list(B2)}}). % UTF-8 encoded list leads to valid UTF-8


json_value() = json_number() | json_string() | json_array() | json_object() | json_boolean() | null | undefined | json_term()


stack_item() = {Module::module(), Function::atom(), Arity::arity() | (Args::[term()]), Location::[{file, Filename::string()} | {line, Line::pos_integer()}]}

An item in a stack back-trace.

Note that the erlang module already defines the same stack_item/0 type, but it is not exported from the module. So, maybe as a temporary measure, we redefine this type for passing full dialyzer analysis.


timezone() = utc | local | utc_offset_seconds()


utc_offset_seconds() = -86399..86399

Function Index

decode/1Equivalent to decode(Json, []).
decode/2Decodes an erlang term from json text (a utf8 encoded binary).
encode/1Equivalent to encode(JsonValue, []).
encode/2Encodes an erlang term into json text (a utf8 encoded binary).
try_decode/1Equivalent to try_decode(Json, []).
try_decode/2Decodes an erlang term from json text (a utf8 encoded binary).
try_encode/1Equivalent to try_encode(JsonValue, []).
try_encode/2Encodes an erlang term into json text (a utf8 encoded binary).

Function Details


decode(Json::binary()) -> json_value()

Equivalent to decode(Json, []).


decode(Json::binary(), Options::[decode_option()]) -> json_value()

Decodes an erlang term from json text (a utf8 encoded binary)

Raises an error exception if input is not valid json

  > jsone:decode(<<"1">>, []).
  > jsone:decode(<<"wrong json">>, []).
  ** exception error: bad argument
      in function  jsone_decode:number_integer_part/4
         called as jsone_decode:number_integer_part(<<"wrong json">>,1,[],<<>>)
      in call from jsone:decode/1 (src/jsone.erl, line 71)


encode(JsonValue::json_value()) -> binary()

Equivalent to encode(JsonValue, []).


encode(JsonValue::json_value(), Options::[encode_option()]) -> binary()

Encodes an erlang term into json text (a utf8 encoded binary)

Raises an error exception if input is not an instance of type json_value()

  > jsone:encode([1, null, 2]).
  > jsone:encode([1, self(), 2]).  % A pid is not a json value
  ** exception error: bad argument
       in function  jsone_encode:value/3
          called as jsone_encode:value(<0,34,0>,[{array_values,[2]}],<<"[1,">>)
       in call from jsone:encode/1 (src/jsone.erl, line 97)


try_decode(Json::binary()) -> {ok, json_value(), Remainings::binary()} | {error, {Reason::term(), [stack_item()]}}

Equivalent to try_decode(Json, []).


try_decode(Json::binary(), Options::[decode_option()]) -> {ok, json_value(), Remainings::binary()} | {error, {Reason::term(), [stack_item()]}}

Decodes an erlang term from json text (a utf8 encoded binary)

  > jsone:try_decode(<<"[1,2,3] \"next value\"">>, []).
  {ok,[1,2,3],<<" \"next value\"">>}
  > jsone:try_decode(<<"wrong json">>, []).
                                [<<"wrong json">>,1,[],<<>>],


try_encode(JsonValue::json_value()) -> {ok, binary()} | {error, {Reason::term(), [stack_item()]}}

Equivalent to try_encode(JsonValue, []).


try_encode(JsonValue::json_value(), Options::[encode_option()]) -> {ok, binary()} | {error, {Reason::term(), [stack_item()]}}

Encodes an erlang term into json text (a utf8 encoded binary)

  > jsone:try_encode([1, null, 2]).
  > jsone:try_encode([1, hoge, 2]).  % 'hoge' atom is not a json value

Generated by EDoc