# Module jsone # * [Description](#description) * [Data Types](#types) * [Function Index](#index) * [Function Details](#functions) JSON decoding/encoding module. <a name="types"></a> ## Data Types ## ### <a name="type-decode_option">decode_option()</a> ### <pre><code> decode_option() = {object_format, tuple | proplist | map} </code></pre> object_format: <br /> - Decoded JSON object format <br /> - `tuple`: An object is decoded as `{[]}` if it is empty, otherwise `{[{Key, Value}]}`. <br /> - `proplist`: An object is decoded as `[{}]` if it is empty, otherwise `[{Key, Value}]`. <br /> - `map`: An object is decoded as `#{}` if it is empty, otherwise `#{Key => Value}`. <br /> - default: `map` <br /> ### <a name="type-encode_option">encode_option()</a> ### <pre><code> encode_option() = native_utf8 | {float_format, [<a href="#type-float_format_option">float_format_option()</a>]} | {object_key_type, string | scalar | value} | {space, non_neg_integer()} | {indent, non_neg_integer()} </code></pre> `native_utf8`: <br /> - Encodes UTF-8 characters as a human-readable(non-escaped) string <br /> `{float_format, Optoins}`: - Encodes a `float()` value in the format which specified by `Options` <br /> - default: `[{scientific, 20}]` <br /> `object_key_type`: - Allowable object key type <br /> - `string`: Only string values are allowed (i.e. `json_string()` type) <br /> - `scalar`: In addition to `string`, following values are allowed: nulls, booleans, numerics (i.e. `json_scalar()` type) <br /> - `value`: Any json compatible values are allowed (i.e. `json_value()` type) <br /> - default: `string` <br /> - NOTE: If `scalar` or `value` option is specified, non `json_string()` key will be automatically converted to a `binary()` value (e.g. `1` => `<<"1">>`, `#{}` => `<<"{}">>`) <br /> `{space, N}`: <br /> - Inserts `N` spaces after every commna and colon <br /> - default: `0` <br /> `{indent, N}`: <br /> - Inserts a newline and `N` spaces for each level of indentation <br /> - default: `0` <br /> ### <a name="type-float_format_option">float_format_option()</a> ### <pre><code> float_format_option() = {scientific, Decimals::0..249} | {decimals, Decimals::0..253} | compact </code></pre> `scientific`: <br /> - The float will be formatted using scientific notation with `Decimals` digits of precision. <br /> `decimals`: <br /> - The encoded string will contain at most `Decimals` number of digits past the decimal point. <br /> - If `compact` is provided the trailing zeros at the end of the string are truncated. <br /> For more details, see [erlang:flaot_to_list/2](http://erlang.org/doc/man/erlang.md#float_to_list-2). ``` > jsone:encode(1.23). <<"1.22999999999999998224e+00">> > jsone:encode(1.23, [{float_format, [{scientific, 4}]}]). <"1.2300e+00">> > jsone:encode(1.23, [{float_format, [{scientific, 1}]}]). <<"1.2e+00">> > jsone:encode(1.23, [{float_format, [{decimals, 4}]}]). <<"1.2300">> > jsone:encode(1.23, [{float_format, [{decimals, 4}, compact]}]). <<"1.23">> ``` ### <a name="type-json_array">json_array()</a> ### <pre><code> json_array() = [<a href="#type-json_value">json_value()</a>] </code></pre> ### <a name="type-json_boolean">json_boolean()</a> ### <pre><code> json_boolean() = boolean() </code></pre> ### <a name="type-json_number">json_number()</a> ### <pre><code> json_number() = number() </code></pre> ### <a name="type-json_object">json_object()</a> ### <pre><code> json_object() = <a href="#type-json_object_format_tuple">json_object_format_tuple()</a> | <a href="#type-json_object_format_proplist">json_object_format_proplist()</a> | <a href="#type-json_object_format_map">json_object_format_map()</a> </code></pre> ### <a name="type-json_object_format_map">json_object_format_map()</a> ### <pre><code> json_object_format_map() = #{} </code></pre> ### <a name="type-json_object_format_proplist">json_object_format_proplist()</a> ### <pre><code> json_object_format_proplist() = [{}] | <a href="#type-json_object_members">json_object_members()</a> </code></pre> ### <a name="type-json_object_format_tuple">json_object_format_tuple()</a> ### <pre><code> json_object_format_tuple() = {<a href="#type-json_object_members">json_object_members()</a>} </code></pre> ### <a name="type-json_object_members">json_object_members()</a> ### <pre><code> json_object_members() = [{<a href="#type-json_string">json_string()</a>, <a href="#type-json_value">json_value()</a>}] </code></pre> ### <a name="type-json_scalar">json_scalar()</a> ### <pre><code> json_scalar() = <a href="#type-json_boolean">json_boolean()</a> | <a href="#type-json_number">json_number()</a> | <a href="#type-json_string">json_string()</a> </code></pre> ### <a name="type-json_string">json_string()</a> ### <pre><code> json_string() = binary() | atom() </code></pre> NOTE: `decode/1` always returns `binary()` value ### <a name="type-json_value">json_value()</a> ### <pre><code> json_value() = <a href="#type-json_number">json_number()</a> | <a href="#type-json_string">json_string()</a> | <a href="#type-json_array">json_array()</a> | <a href="#type-json_object">json_object()</a> | <a href="#type-json_boolean">json_boolean()</a> | null </code></pre> <a name="index"></a> ## Function Index ## <table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#decode-1">decode/1</a></td><td>Equivalent to <a href="#decode-2"><tt>decode(Json, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#decode-2">decode/2</a></td><td>Decodes an erlang term from json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#encode-1">encode/1</a></td><td>Equivalent to <a href="#encode-2"><tt>encode(JsonValue, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#encode-2">encode/2</a></td><td>Encodes an erlang term into json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#try_decode-1">try_decode/1</a></td><td>Equivalent to <a href="#try_decode-2"><tt>try_decode(Json, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#try_decode-2">try_decode/2</a></td><td>Decodes an erlang term from json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#try_encode-1">try_encode/1</a></td><td>Equivalent to <a href="#try_encode-2"><tt>try_encode(JsonValue, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#try_encode-2">try_encode/2</a></td><td>Encodes an erlang term into json text (a utf8 encoded binary).</td></tr></table> <a name="functions"></a> ## Function Details ## <a name="decode-1"></a> ### decode/1 ### <pre><code> decode(Json::binary()) -> <a href="#type-json_value">json_value()</a> </code></pre> <br /> Equivalent to [`decode(Json, [])`](#decode-2). <a name="decode-2"></a> ### decode/2 ### <pre><code> decode(Json::binary(), Options::[<a href="#type-decode_option">decode_option()</a>]) -> <a href="#type-json_value">json_value()</a> </code></pre> <br /> Decodes an erlang term from json text (a utf8 encoded binary) Raises an error exception if input is not valid json ``` > jsone:decode(<<"1">>, []). 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) ``` <a name="encode-1"></a> ### encode/1 ### <pre><code> encode(JsonValue::<a href="#type-json_value">json_value()</a>) -> binary() </code></pre> <br /> Equivalent to [`encode(JsonValue, [])`](#encode-2). <a name="encode-2"></a> ### encode/2 ### <pre><code> encode(JsonValue::<a href="#type-json_value">json_value()</a>, Options::[<a href="#type-encode_option">encode_option()</a>]) -> binary() </code></pre> <br /> 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]). <<"[1,null,2]">> > jsone:encode([1, hoge, 2]). % 'hoge' atom is not a json value ** exception error: bad argument in function jsone_encode:value/3 called as jsone_encode:value(hoge,[{array_values,[2]}],<<"[1,">>) in call from jsone:encode/1 (src/jsone.erl, line 97) ``` <a name="try_decode-1"></a> ### try_decode/1 ### <pre><code> try_decode(Json::binary()) -> {ok, <a href="#type-json_value">json_value()</a>, Remainings::binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}} </code></pre> <br /> Equivalent to [`try_decode(Json, [])`](#try_decode-2). <a name="try_decode-2"></a> ### try_decode/2 ### <pre><code> try_decode(Json::binary(), Options::[<a href="#type-decode_option">decode_option()</a>]) -> {ok, <a href="#type-json_value">json_value()</a>, Remainings::binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}} </code></pre> <br /> 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">>, []). {error,{badarg,[{jsone_decode,number_integer_part, [<<"wrong json">>,1,[],<<>>], [{line,208}]}]}} ``` <a name="try_encode-1"></a> ### try_encode/1 ### <pre><code> try_encode(JsonValue::<a href="#type-json_value">json_value()</a>) -> {ok, binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}} </code></pre> <br /> Equivalent to [`try_encode(JsonValue, [])`](#try_encode-2). <a name="try_encode-2"></a> ### try_encode/2 ### <pre><code> try_encode(JsonValue::<a href="#type-json_value">json_value()</a>, Options::[<a href="#type-encode_option">encode_option()</a>]) -> {ok, binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}} </code></pre> <br /> Encodes an erlang term into json text (a utf8 encoded binary) ``` > jsone:try_encode([1, null, 2]). {ok,<<"[1,null,2]">>} > jsone:try_encode([1, hoge, 2]). % 'hoge' atom is not a json value {error,{badarg,[{jsone_encode,value, [hoge,[{array_values,[2]}],<<"[1,">>], [{line,86}]}]}} ```