Skip to content

Commit f453854

Browse files
zuiderkwastzuiderkwast
committed
Update generated docs
1 parent 246ac98 commit f453854

File tree

1 file changed

+75
-10
lines changed

1 file changed

+75
-10
lines changed

‎doc/jsone.md‎

Lines changed: 75 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ datetime_format() = iso8601
7272

7373

7474
<pre><code>
75-
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} | <a href="#type-common_option">common_option()</a>
75+
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} | stream | <a href="#type-common_option">common_option()</a>
7676
</code></pre>
7777

7878
`object_format`: <br />
@@ -114,13 +114,21 @@ the last such instance.
114114
- If the value is `last` then the last duplicate key/value is returned.
115115
- default: `first`<br />
116116

117+
`stream`: <br />
118+
119+
Decode the input in multiple chunks. Instead of a result or error,
120+
`{incomplete, fun()}` is returned. The returned fun takes a single argument
121+
and it should called to continue the decoding. When all the input has been
122+
provided, the fun should be called with `end_stream` or `end_json` to signal
123+
the end of input and then the fun returns a result or an error.
124+
117125

118126

119127
### <a name="type-encode_option">encode_option()</a> ###
120128

121129

122130
<pre><code>
123-
encode_option() = native_utf8 | native_forward_slash | canonical_form | {float_format, [<a href="#type-float_format_option">float_format_option()</a>]} | {datetime_format, <a href="#type-datetime_encode_format">datetime_encode_format()</a>} | {object_key_type, string | scalar | value} | {space, non_neg_integer()} | {indent, non_neg_integer()} | {map_unknown_value, fun((term()) -&gt; {ok, <a href="#type-json_value">json_value()</a>} | error)} | <a href="#type-common_option">common_option()</a>
131+
encode_option() = native_utf8 | native_forward_slash | canonical_form | {float_format, [<a href="#type-float_format_option">float_format_option()</a>]} | {datetime_format, <a href="#type-datetime_encode_format">datetime_encode_format()</a>} | {object_key_type, string | scalar | value} | {space, non_neg_integer()} | {indent, non_neg_integer()} | {map_unknown_value, undefined | fun((term()) -&gt; {ok, <a href="#type-json_value">json_value()</a>} | error)} | skip_undefined | <a href="#type-common_option">common_option()</a>
124132
</code></pre>
125133

126134
`native_utf8`: <br />
@@ -156,8 +164,13 @@ encode_option() = native_utf8 | native_forward_slash | canonical_form | {float_f
156164
- Inserts a newline and `N` spaces for each level of indentation <br />
157165
- default: `0` <br />
158166

167+
`skip_undefined`: <br />
168+
- If specified, each entry having `undefined` value in a object isn't included in the result JSON <br />
169+
159170
`{map_unknown_value, Fun}`: <br />
160-
- If specified, unknown values encountered during an encoding process are converted to `json_value()` by applying `Fun`.
171+
- If `Fun` is a function, unknown values encountered during an encoding process are converted to `json_value()` by applying `Fun`. <br />
172+
- If `Fun` is `undefined`, the encoding results in an error if there are unknown values. <br />
173+
- default: `term_to_json_string/1` <br />
161174

162175

163176

@@ -175,7 +188,7 @@ float_format_option() = {scientific, Decimals::0..249} | {decimals, Decimals::0.
175188
- The encoded string will contain at most `Decimals` number of digits past the decimal point. <br />
176189
- If `compact` is provided the trailing zeros at the end of the string are truncated. <br />
177190

178-
For more details, see [erlang:float_to_list/2](http://erlang.org/doc/man/erlang.html#float_to_list-2).
191+
For more details, see [erlang:float_to_list/2](http://erlang.org/doc/man/erlang.md#float_to_list-2).
179192

180193
```
181194
> jsone:encode(1.23).
@@ -192,6 +205,16 @@ For more details, see [erlang:float_to_list/2](http://erlang.org/doc/man/erlang.
192205

193206

194207

208+
### <a name="type-incomplete">incomplete()</a> ###
209+
210+
211+
<pre><code>
212+
incomplete() = {incomplete, function()}
213+
</code></pre>
214+
215+
216+
217+
195218
### <a name="type-json_array">json_array()</a> ###
196219

197220

@@ -236,7 +259,7 @@ json_object() = <a href="#type-json_object_format_tuple">json_object_format_tupl
236259

237260

238261
<pre><code>
239-
json_object_format_map() = #{}
262+
json_object_format_map() = map()
240263
</code></pre>
241264

242265

@@ -392,7 +415,7 @@ utc_offset_seconds() = -86399..86399
392415
## Function Index ##
393416

394417

395-
<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>
418+
<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="#ip_address_to_json_string-1">ip_address_to_json_string/1</a></td><td>Convert an IP address into a text representation.</td></tr><tr><td valign="top"><a href="#term_to_json_string-1">term_to_json_string/1</a></td><td>Converts the given term <code>X</code> to its string representation (i.e., the result of <code>io_lib:format("~p", [X])</code>).</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>
396419

397420

398421
<a name="functions"></a>
@@ -404,7 +427,7 @@ utc_offset_seconds() = -86399..86399
404427
### decode/1 ###
405428

406429
<pre><code>
407-
decode(Json::binary()) -&gt; <a href="#type-json_value">json_value()</a>
430+
decode(Json::binary()) -&gt; <a href="#type-json_value">json_value()</a> | <a href="#type-incomplete">incomplete()</a>
408431
</code></pre>
409432
<br />
410433

@@ -415,7 +438,7 @@ Equivalent to [`decode(Json, [])`](#decode-2).
415438
### decode/2 ###
416439

417440
<pre><code>
418-
decode(Json::binary(), Options::[<a href="#type-decode_option">decode_option()</a>]) -&gt; <a href="#type-json_value">json_value()</a>
441+
decode(Json::binary(), Options::[<a href="#type-decode_option">decode_option()</a>]) -&gt; <a href="#type-json_value">json_value()</a> | <a href="#type-incomplete">incomplete()</a>
419442
</code></pre>
420443
<br />
421444

@@ -467,12 +490,53 @@ Raises an error exception if input is not an instance of type `json_value()`
467490
in call from jsone:encode/1 (src/jsone.erl, line 97)
468491
```
469492

493+
<a name="ip_address_to_json_string-1"></a>
494+
495+
### ip_address_to_json_string/1 ###
496+
497+
<pre><code>
498+
ip_address_to_json_string(X::<a href="inet.md#type-ip_address">inet:ip_address()</a> | any()) -&gt; {ok, <a href="#type-json_string">json_string()</a>} | error
499+
</code></pre>
500+
<br />
501+
502+
Convert an IP address into a text representation.
503+
504+
This function can be specified as the value of the `map_unknown_value` encoding option.
505+
506+
This function formats IPv6 addresses by following the recommendation defined in RFC 5952.
507+
Note that the trailing 32 bytes of special IPv6 addresses such as IPv4-Compatible (::X.X.X.X),
508+
IPv4-Mapped (::ffff:X.X.X.X), IPv4-Translated (::ffff:0:X.X.X.X) and IPv4/IPv6 translation
509+
(64:ff9b::X.X.X.X and 64:ff9b:1::X.X.X.X ~ 64:ff9b:1:ffff:ffff:ffff:X.X.X.X) are formatted
510+
using the IPv4 format.
511+
512+
```
513+
> EncodeOpt = [{map_unknown_value, fun jsone:ip_address_to_json_string/1}].
514+
> jsone:encode(#{ip => {127, 0, 0, 1}}, EncodeOpt).
515+
<<"{\"ip\":\"127.0.0.1\"}">>
516+
> {ok, Addr} = inet:parse_address("2001:DB8:0000:0000:0001:0000:0000:0001").
517+
> jsone:encode(Addr, EncodeOpt).
518+
<<"\"2001:db8::1:0:0:1\"">>
519+
> jsone:encode([foo, {0, 0, 0, 0, 0, 16#FFFF, 16#7F00, 16#0001}], EncodeOpt).
520+
<<"[\"foo\",\"::ffff:127.0.0.1\"]">>
521+
```
522+
523+
<a name="term_to_json_string-1"></a>
524+
525+
### term_to_json_string/1 ###
526+
527+
<pre><code>
528+
term_to_json_string(X::term()) -&gt; {ok, <a href="#type-json_string">json_string()</a>} | error
529+
</code></pre>
530+
<br />
531+
532+
Converts the given term `X` to its string representation (i.e., the result of `io_lib:format("~p", [X])`).
533+
470534
<a name="try_decode-1"></a>
471535

472536
### try_decode/1 ###
473537

474538
<pre><code>
475-
try_decode(Json::binary()) -&gt; {ok, <a href="#type-json_value">json_value()</a>, Remainings::binary()} | {error, {Reason::term(), [<a href="#type-stack_item">stack_item()</a>]}}
539+
try_decode(Json::binary()) -&gt; {ok, <a href="#type-json_value">json_value()</a>, Remainings::binary()} | <a href="#type-incomplete">incomplete()</a> | {error, {Reason::term(), [<a href="#type-stack_item">stack_item()</a>]}}
476540
</code></pre>
477541
<br />
478542

@@ -483,7 +547,7 @@ Equivalent to [`try_decode(Json, [])`](#try_decode-2).
483547
### try_decode/2 ###
484548

485549
<pre><code>
486-
try_decode(Json::binary(), Options::[<a href="#type-decode_option">decode_option()</a>]) -&gt; {ok, <a href="#type-json_value">json_value()</a>, Remainings::binary()} | {error, {Reason::term(), [<a href="#type-stack_item">stack_item()</a>]}}
550+
try_decode(Json::binary(), Options::[<a href="#type-decode_option">decode_option()</a>]) -&gt; {ok, <a href="#type-json_value">json_value()</a>, Remainings::binary()} | <a href="#type-incomplete">incomplete()</a> | {error, {Reason::term(), [<a href="#type-stack_item">stack_item()</a>]}}
487551
</code></pre>
488552
<br />
489553

@@ -528,3 +592,4 @@ Encodes an erlang term into json text (a utf8 encoded binary)
528592
[hoge,[{array_values,[2]}],<<"[1,">>],
529593
[{line,86}]}]}}
530594
```
595+

0 commit comments

Comments
 (0)