Module jhn_json

A JSON stream library based on:.

Copyright © (C) 2021-2024, Jan Henry Nystrom <JanHenryNystrom@gmail.com> -------------------------------------------------------------------

Authors: Jan Henry Nystrom (JanHenryNystrom@gmail.com).

Description

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.

Data Types

acc()

acc() = [{jstring(), json()}]

array()

array() = [json()]

complete()

complete() = boolean()

cont()

cont() = {decode, stack()} | {object, {complete(), expect()}, acc(), stack()} | {array, {first(), complete()}, array(), stack()} | {string, binary(), stack()} | {unescape, binary(), stack()} | {number, stage(), phase(), list(), stack()}

eval_cont()

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()}

expect()

expect() = name | comma | colon

first()

first() = boolean()

json()

json() = true | false | null | number() | jstring() | object() | array()

jstring()

jstring() = binary()

merge()

merge() = object()

name()

name() = jstring()

next_cont()

next_cont() = term()

object()

object() = #{jstring() => json()}

opt()

opt() = stream | decode | pointer | binary

opts()

opts() = [opt()]

patch()

patch() = [object()]

path()

path() = [integer() | binary()]

phase()

phase() = int | float | exp

pointer()

pointer() = top | ['-' | integer() | jstring() | atom()]

skip_cont()

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()}

stack()

stack() = [{array, array()} | {name, acc()} | {value, {name(), acc()}}]

stage()

stage() = sign | zero | pre | post

stream()

stream() = boolean()

unwind_cont()

unwind_cont() = {unwind, path(), json()} | {unwind_array, unwind_cont()} | {unwind_object, unwind_cont()}

Function Index

decode/1 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.
decode/2 Supports the decoding of when supplied with the the option stream as the option with no options works as decode/1.
encode/1 Encodes the structured Erlang term as an iolist.
encode/2 Encodes the structured Erlang term as an iolist or binary.
eval/2 Selects and decodes a Fragment of a JSON document based on the Pointer.
eval/3 Selects and decodes a Fragment of a JSON document based on the Pointer.
merge/2 Merge applies a JSON Merge Patch to the JSON represented as Erlang returning a new JSON object represented as Erlang.
next/1 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).
next/2 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/2 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.

Function Details

decode/1

decode(B::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.

decode/2

decode(B::binary(), X2::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.

encode/1

encode(Object::json()) -> iodata()

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

encode/2

encode(T::json() | pointer(), X2::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)

eval/2

eval(Pointer::binary() | pointer(), T::binary() | json()) -> json() | {more, cont()} | {error, term()}

eval(Pointer::eval_cont(), T::binary()) -> {json(), binary()} | {more, cont()} | {error, term()}

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).

eval/3

eval(Pointer::binary() | pointer(), B::binary() | json(), Opts::opts()) -> json() | {json(), binary()} | {more, cont()} | {error, term()}

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/2

merge(Patch::merge(), JSON::json()) -> json()

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

next/1

next(B::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).

next/2

next(T::binary(), X2::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.

patch/2

patch(Ops::patch(), JSON::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.


Generated by EDoc