glazer (glazer v0.1.5)
View SourceFast JSON encoding and decoding using the glaze C++ library.
By default JSON null is represented as the atom null. To change it
application-wide, set the null env key in your config:
{glazer, [{null, nil}]}.See also [https://github.com/stephenberry/glaze]
Summary
Functions
Decode a JSON binary or iolist to an Erlang term. JSON objects are returned as maps (default).
Decode a JSON binary or iolist to an Erlang term with options.
Decode a JSON number string to a big integer.
Encode an Erlang term to a JSON binary.
Encode an Erlang term to a JSON binary with options.
Encode a big integer to its JSON string representation.
Minify a JSON binary or iolist, removing all unnecessary whitespace.
Pretty-print a JSON binary or iolist with two-space indentation.
Locate the end of the next complete top-level JSON value in Bin, without
decoding it.
Resume scanning Bin (the unconsumed remainder plus newly-appended bytes) from ScanState.
Create a new incremental decoder for feeding JSON in chunks (e.g. from a socket or file), useful when a complete document isn't available up front or when a stream contains a sequence of concatenated/whitespace-separated JSON values (e.g. newline-delimited JSON).
Create a new incremental decoder, passing Opts through to every decode/2 call.
Signal end-of-stream: decode any remaining buffered bytes as a final value
(useful for a trailing bare scalar, e.g. a lone number or true/null,
which the scanner can't otherwise distinguish from a value that's still
being written to mid-chunk).
Feed a chunk of bytes into the decoder, returning any complete JSON values found so far (in order) along with the updated decoder.
Types
-type decode_opt() :: return_maps | object_as_tuple | use_nil | {null_term, atom()} | {keys, atom | existing_atom | binary}.
-type decode_opts() :: [decode_opt()].
Decode options:
return_maps- decode JSON objects as Erlang maps (default)object_as_tuple- decode JSON objects as{[{K, V}]}proplistsuse_nil- use the atomnilfor JSON null{null_term, Atom}- useAtomfor JSON null{keys, atom}- decode object keys as atoms{keys, existing_atom}- decode keys as existing atoms, fall back to binary{keys, binary}- decode keys as binaries (default)
-type encode_opt() :: pretty | uescape | force_utf8 | use_nil | {null_term, atom()}.
-type encode_opts() :: [encode_opt()].
Encode options:
pretty- pretty-print the JSON outputuescape- escape non-ASCII characters as \uXXXX sequencesforce_utf8- fix invalid UTF-8 sequences before encodinguse_nil- encode the atomnilas JSONnull{null_term, Atom}- encodeAtomas JSONnull
-type scan_state() :: tuple().
-opaque stream_decoder()
Functions
Decode a JSON binary or iolist to an Erlang term. JSON objects are returned as maps (default).
-spec decode(binary() | iolist(), decode_opts()) -> term().
Decode a JSON binary or iolist to an Erlang term with options.
Decode a JSON number string to a big integer.
Encode an Erlang term to a JSON binary.
-spec encode(term(), encode_opts()) -> binary().
Encode an Erlang term to a JSON binary with options.
Encode a big integer to its JSON string representation.
Minify a JSON binary or iolist, removing all unnecessary whitespace.
Pretty-print a JSON binary or iolist with two-space indentation.
-spec scan(binary() | iolist()) -> {complete, non_neg_integer()} | {incomplete, scan_state()}.
Locate the end of the next complete top-level JSON value in Bin, without
decoding it.
Returns:
{complete, EndOffset}- a complete value spansbinary:part(Bin, 0, EndOffset); the rest ofBin(if any) is left over for the next call{incomplete, ScanState}-Bindoesn't yet contain a complete value; feed more data viascan/2once it's available, passing the entire unconsumed remainder (thisBin, with new bytes appended) plusScanState
This is the low-level primitive behind stream_feed/2;
most callers should use the stream_* API instead.
-spec scan(binary() | iolist(), scan_state()) -> {complete, non_neg_integer()} | {incomplete, scan_state()}.
Resume scanning Bin (the unconsumed remainder plus newly-appended bytes) from ScanState.
-spec stream_decoder() -> stream_decoder().
Create a new incremental decoder for feeding JSON in chunks (e.g. from a socket or file), useful when a complete document isn't available up front or when a stream contains a sequence of concatenated/whitespace-separated JSON values (e.g. newline-delimited JSON).
Decoding itself is not incremental — each complete top-level value is
still decoded in a single pass via decode/2 using the
library's fast whole-buffer decoder. Only the boundary detection (finding
where one value ends and the next begins) is incremental, via a small
byte-scanner that tracks nesting/string state across chunks.
Example
1> D0 = glazer:stream_decoder(),
2> {Vals1, D1} = glazer:stream_feed(D0, <<"{\\"a\\":1} {\\"b\\":">>),
3> Vals1.
[#{<<"a">> => 1}]
4> {Vals2, _D2} = glazer:stream_feed(D1, <<"2}">>),
5> Vals2.
[#{<<"b">> => 2}]-spec stream_decoder(decode_opts()) -> stream_decoder().
Create a new incremental decoder, passing Opts through to every decode/2 call.
-spec stream_eof(stream_decoder()) -> {ok, [term()]} | {error, term()}.
Signal end-of-stream: decode any remaining buffered bytes as a final value
(useful for a trailing bare scalar, e.g. a lone number or true/null,
which the scanner can't otherwise distinguish from a value that's still
being written to mid-chunk).
Returns {ok, [Term]} with zero or one trailing value, or {error, Reason} if the remaining bytes don't form a complete value.
-spec stream_feed(stream_decoder(), binary() | iolist()) -> {[term()], stream_decoder()}.
Feed a chunk of bytes into the decoder, returning any complete JSON values found so far (in order) along with the updated decoder.
Raises the same exceptions as decode/2 (e.g.
{parse_error, Reason}) if a value that the scanner deemed complete fails
to decode.