View Source jhn_json (jhn_stdlib v5.1.0)

A JSON stream library based on:

The JavaScript Object Notation (JSON) Data Interchange Format (rfc8259)

JavaScript Object Notation (JSON) Pointer (rfc6901)

JavaScript Object Notation (JSON) Patch (rfc6902)

JSON Merge Patch (rfc7396)

JSON is represented as follows:

value : true | false | null | object | array | number | string

pointer : top | [integer | string | '-']

patch : [object]

merge : object

object : map

array : [value]

string : UTF-8 binary

number : integer() | float()

true : atom(true)

false : atom(false)

null : atom(null)

Strings can be represented by atoms when generating JSON, but will not not be generated when converting JSON to erlang or any of the functions returning JSON.

When converting Erlang terms to JSON iolists are generated but it can generate a binary if so instructed.

Objects as maps, multiple occurrences of the members is not supported.

Summary

Functions

Decodes the binary if a JSON Pointer into the Erlang respresentation and if a JSON value into a structured Erlang term and the remaining binary is ignored.

Supports the decoding of when supplied with the the option stream as the option with no options works as decode/1. Decoding a stream of JSON the functions returns either a tuple of a complete json value and the remainder of the stream (binary) or {more, Continuation} where subsequent calls to decode/2 is made with futher data and the Continuation as the second argument. Options are: stream -> enables the decoding of a stream of JSON values.

Encodes the structured Erlang term as an iolist. Equivalent of encode(Term, iolist) -> JSON.

Encodes the structured Erlang term as an iolist or binary. Encode will raise an exception if the erlang term is not well formed. Options are: pointer -> the term represents a pointer binary -> a binary is returned iolist -> an iolist is returned (default)

Selects and decodes a Fragment of a JSON document based on the Pointer. Both the pointer and the JSON can be either a binary or the Erlang representation. If the JSON is a binary and not the complete JSON fragment eval/2 returns {more, Continuation} and eval is called again with Continuation and more of the stream as eval(Continuation, Binary).

Selects and decodes a Fragment of a JSON document based on the Pointer. Both the pointer and the JSON can be either a binary or the Erlang representation. If the JSON is a binary and not the complete JSON fragment eval/3 returns {more, Continuation} and eval is called again with Continuation and more of the stream as eval(Continuation, Binary).

Merge applies a JSON Merge Patch to the JSON represented as Erlang returning a new JSON object represented as Erlang.

Picks the first json on a stream and returns that and the rest or {more, Continuation} where Continuation is used in a call to decode(Binary, Continuation).

Picks the first json on a stream given a continuation and returns that and the rest or {more Continuation} is if it was not a complete value.

Patch applies the JSON Patch to a JSON value represented as Erlang returning the patched JSON or error if one of the test operations in the JSON Patch failed.

Types

-type acc() :: [{jstring(), json()}].
-type array() :: [json()].
-type complete() :: boolean().
-type cont() ::
          {decode, stack()} |
          {object, {complete(), expect()}, acc(), stack()} |
          {array, {first(), complete()}, array(), stack()} |
          {string, binary(), stack()} |
          {unescape, binary(), stack()} |
          {number, stage(), phase(), list(), stack()}.
-type eval_cont() ::
          {eval_binary, path(), stream(), path()} |
          {eval_dash, expect(), integer(), stream(), path()} |
          {eval_array, integer(), expect(), stream(), path(), path()} |
          {eval_object, binary(), expect(), stream(), path(), path()} |
          {eval_key, binary(), stream(), path(), path()} |
          {skip_value, skip_cont()} |
          {skip_base, string(), skip_cont()} |
          {skip_object, expect(), skip_cont()} |
          {skip_string, skip_cont()} |
          {skip_colon, boolean(), skip_cont()} |
          {skip_number, skip_cont()} |
          {unwind, path(), json()} |
          {unwind_array, unwind_cont()} |
          {unwind_object, unwind_cont()} |
          {unwind_name, unwind_cont()} |
          {unwind_colon, unwind_cont()} |
          {unwind_string, unwind_cont()} |
          {unwind_value, unwind_cont()} |
          {unwind_number, unwind_cont()} |
          {unwind_base, string(), unwind_cont()} |
          {decode, path(), cont()}.
-type expect() :: name | comma | colon.
-type first() :: boolean().
-type json() :: true | false | null | number() | jstring() | object() | array().
-type jstring() :: binary().
-type merge() :: object().
-type name() :: jstring().
-type next_cont() :: _.
-type object() :: #{jstring() => json()}.
-type opt() :: stream | decode | pointer | binary.
-type opts() :: [opt()].
-type patch() :: [object()].
-type path() :: [integer() | binary()].
-type phase() :: int | float | exp.
-type pointer() :: top | ['-' | integer() | jstring() | atom()].
-type skip_cont() ::
          {eval_binary, path(), stream(), path()} |
          {eval_dash, expect(), integer(), stream(), path()} |
          {eval_array, integer(), expect(), stream(), path(), path()} |
          {eval_object, binary(), expect(), stream(), path(), path()} |
          {skip_object, expect(), skip_cont()} |
          {skip_array, expect(), skip_cont()} |
          {skip_value, skip_cont()}.
-type stack() :: [{array, array()} | {name, acc()} | {value, {name(), acc()}}].
-type stage() :: sign | zero | pre | post.
-type stream() :: boolean().
-type unwind_cont() ::
          {unwind, path(), json()} | {unwind_array, unwind_cont()} | {unwind_object, unwind_cont()}.

Functions

-spec decode(binary()) -> json() | pointer().

Decodes the binary if a JSON Pointer into the Erlang respresentation and if a JSON value into a structured Erlang term and the remaining binary is ignored.

-spec decode(binary(), cont() | opts()) -> pointer() | json() | {json(), binary()} | {more, cont()}.

Supports the decoding of when supplied with the the option stream as the option with no options works as decode/1. Decoding a stream of JSON the functions returns either a tuple of a complete json value and the remainder of the stream (binary) or {more, Continuation} where subsequent calls to decode/2 is made with futher data and the Continuation as the second argument. Options are: stream -> enables the decoding of a stream of JSON values.

-spec encode(json()) -> iodata().

Encodes the structured Erlang term as an iolist. Equivalent of encode(Term, iolist) -> JSON.

-spec encode(json() | pointer(), opts()) -> iolist() | binary().

Encodes the structured Erlang term as an iolist or binary. Encode will raise an exception if the erlang term is not well formed. Options are: pointer -> the term represents a pointer binary -> a binary is returned iolist -> an iolist is returned (default)

-spec eval(binary() | pointer(), binary() | json()) -> json() | {more, cont()} | {error, _};
          (eval_cont(), binary()) -> {json(), binary()} | {more, cont()} | {error, _}.

Selects and decodes a Fragment of a JSON document based on the Pointer. Both the pointer and the JSON can be either a binary or the Erlang representation. If the JSON is a binary and not the complete JSON fragment eval/2 returns {more, Continuation} and eval is called again with Continuation and more of the stream as eval(Continuation, Binary).

-spec eval(binary() | pointer(), binary() | json(), opts()) ->
              json() | {json(), binary()} | {more, cont()} | {error, _}.

Selects and decodes a Fragment of a JSON document based on the Pointer. Both the pointer and the JSON can be either a binary or the Erlang representation. If the JSON is a binary and not the complete JSON fragment eval/3 returns {more, Continuation} and eval is called again with Continuation and more of the stream as eval(Continuation, Binary).

-spec merge(merge(), json()) -> json().

Merge applies a JSON Merge Patch to the JSON represented as Erlang returning a new JSON object represented as Erlang.

-spec next(binary()) -> {binary(), binary()} | {more, next_cont()}.

Picks the first json on a stream and returns that and the rest or {more, Continuation} where Continuation is used in a call to decode(Binary, Continuation).

-spec next(binary(), next_cont()) -> {binary(), binary()} | {more, next_cont()}.

Picks the first json on a stream given a continuation and returns that and the rest or {more Continuation} is if it was not a complete value.

-spec patch(patch(), json()) -> json() | error.

Patch applies the JSON Patch to a JSON value represented as Erlang returning the patched JSON or error if one of the test operations in the JSON Patch failed.