Skip to content

Decoding

Jump to bottom
Eric Pailleau edited this page Aug 8, 2018 · 28 revisions

Decoding

Exported functions

  • jason:decode/1
jason:decode(binary() | list() | atom()) -> term() | no_return()
  • jason:decode/2
jason:decode(binary() | list() | atom(), Options) -> term() | no_return() | {ok, Term} | {error, Reason}
  • jason:decode_file/1
  • jason:decode_file/2 Same than 'decode/x'. POSIX error code returned on file access error.

Options

Arity 2 functions accept a property list of {key, Value} tuples.

Key Value type Value Comment
mode atom() struct, proplist, map, record Output mode. struct default.
return atom() tuple Return mode.
to list() Path to non existing or empty file Export Record definitions to file.
records [{atom(), [atom(), ...]},...] [{RecName, RecFields}, ...] (List of) Record definitions
records [atom(), ...] Module name(s) where record(s) declared Extract record info from (list of) module (slower)
binary atom() k, v, kv Return respectively keys, values or both as binary
aliases See records See records Same than records but (dumpable) argonaut modules will be created

When using records, argonaut modules are not created when a match is found between declaration and data. When using aliases instead, the argonaut modules helpers will be created and can be dumped on disk also.

Data Input

jason:decode/x functions can accept binary, string and even atom data to decode.

Tip : it is worth noting that using atom in Erlang shell is easier than using string or binary for character escaping . For your mental health, use atoms in the shell for short JSON statements !

1> jason:decode('["a","b\\""]').              % Atom (but limited to 255 characters !)
[<<"a">>,<<"b\"">>]
2> jason:decode(<<"[\"a\",\"b\\\"\"]">>).     % Binary
[<<"a">>,<<"b\"">>]
3> jason:decode("[\"a\",\"b\\\"\"]").         % String
[<<"a">>,<<"b\"">>]

Return value

decode functions

By default, returns Erlang term on success, or throw {Line, Reason} exception on error.

Using option {return, tuple} let return {ok, Term} or {error, {Line, Reason}}.

% Success
1> jason:decode('{"ab": "cd"}').    
[{<<"ab">>,<<"cd">>}]
2> jason:decode('{"ab": "cd"}', [{return, tuple}]).
{ok,[{<<"ab">>,<<"cd">>}]}
3> jason:decode('{"ab": "cd"}', [{return, tuple}, {mode, map}, {binary, k}]).
{ok,#{<<"ab">> => "cd"}}
4> jason:decode('{"ab": "cd"}', [{return, tuple}, {mode, map}, {binary, v}]).
{ok,#{ab => <<"cd">>}}
5> jason:decode('{"ab": "cd"}', [{return, tuple}, {mode, map}, {binary, kv}]).
{ok,#{<<"ab">> => <<"cd">>}}

% Error
1> jason:decode('{"ab": "cd"').
** exception throw: {1,"syntax error before end"}
     in function  jason:decode/2 (src/jason.erl, line 211)
2> jason:decode('{"ab": "cd"', [{return, tuple}]).
{error,{1,"syntax error before end"}}

decode_file functions

Same than decode functions, but POSIX atom error returned instead {Line, Reason} on IO errors.

1> jason:decode_file("/tmp/notfound").         
** exception throw: enoent
     in function  jason:decode_file/2 (src/jason.erl, line 246)
 
2> jason:decode_file("/tmp/notfound", [{return, tuple}]).         
{error,enoent}
Clone this wiki locally