View Source Jason (jason v1.4.3)
A blazing fast JSON parser and generator in pure Elixir.
Summary
Functions
Parses a JSON value from input
iodata.
Parses a JSON value from input
iodata.
Generates JSON corresponding to input
.
Generates JSON corresponding to input
.
Generates JSON corresponding to input
and returns iodata.
Generates JSON corresponding to input
and returns iodata.
Types
@type encode_opt() :: {:escape, escape()} | {:maps, maps()} | {:pretty, boolean() | Jason.Formatter.opts()}
@type escape() :: :json | :unicode_safe | :html_safe | :javascript_safe
@type floats() :: :native | :decimals
@type maps() :: :naive | :strict
@type objects() :: :maps | :ordered_objects
@type strings() :: :reference | :copy
Functions
@spec decode(iodata(), [decode_opt()]) :: {:ok, term()} | {:error, Jason.DecodeError.t()}
Parses a JSON value from input
iodata.
Options
:keys
- controls how keys in objects are decoded. Possible values are::strings
(default) - decodes keys as binary strings,:atoms
- keys are converted to atoms usingString.to_atom/1
,:atoms!
- keys are converted to atoms usingString.to_existing_atom/1
,- custom decoder - additionally a function accepting a string and returning a key is accepted.
:strings
- controls how strings (including keys) are decoded. Possible values are::reference
(default) - when possible tries to create a sub-binary into the original:copy
- always copies the strings. This option is especially useful when parts of the decoded data will be stored for a long time (in ets or some process) to avoid keeping the reference to the original data.
:floats
- controls how floats are decoded. Possible values are::native
(default) - Native conversion from binary to float using:erlang.binary_to_float/1
,:decimals
- usesDecimal.new/1
to parse the binary into a Decimal struct with arbitrary precision.
:objects
- controls how objects are decoded. Possible values are::maps
(default) - objects are decoded as maps:ordered_objects
- objects are decoded asJason.OrderedObject
structs
Decoding keys to atoms
The :atoms
option uses the String.to_atom/1
call that can create atoms at runtime.
Since the atoms are not garbage collected, this can pose a DoS attack vector when used
on user-controlled data.
Examples
iex> Jason.decode("{}")
{:ok, %{}}
iex> Jason.decode("invalid")
{:error, %Jason.DecodeError{data: "invalid", position: 0, token: nil}}
@spec decode!(iodata(), [decode_opt()]) :: term() | no_return()
Parses a JSON value from input
iodata.
Similar to decode/2
except it will unwrap the error tuple and raise
in case of errors.
Examples
iex> Jason.decode!("{}")
%{}
iex> Jason.decode!("invalid")
** (Jason.DecodeError) unexpected byte at position 0: 0x69 ("i")
@spec encode(term(), [encode_opt()]) :: {:ok, String.t()} | {:error, Jason.EncodeError.t() | Exception.t()}
Generates JSON corresponding to input
.
The generation is controlled by the Jason.Encoder
protocol,
please refer to the module to read more on how to define the protocol
for custom data types.
Options
:escape
- controls how strings are encoded. Possible values are::json
(default) - the regular JSON escaping as defined by RFC 7159.:javascript_safe
- additionally escapes the LINE SEPARATOR (U+2028) and PARAGRAPH SEPARATOR (U+2029) characters to make the produced JSON valid JavaScript.:html_safe
- similar to:javascript_safe
, but also escapes the/
character to prevent XSS.:unicode_safe
- escapes all non-ascii characters.
:maps
- controls how maps are encoded. Possible values are::strict
- checks the encoded map for duplicate keys and raises if they appear. For example%{:foo => 1, "foo" => 2}
would be rejected, since both keys would be encoded to the string"foo"
.:naive
(default) - does not perform the check.
:pretty
- controls pretty printing of the output. Possible values are:true
to pretty print with default configuration- a keyword of options as specified by
Jason.Formatter.pretty_print/2
.
Examples
iex> Jason.encode(%{a: 1})
{:ok, ~S|{"a":1}|}
iex> Jason.encode("\xFF")
{:error, %Jason.EncodeError{message: "invalid byte 0xFF in <<255>>"}}
@spec encode!(term(), [encode_opt()]) :: String.t() | no_return()
Generates JSON corresponding to input
.
Similar to encode/1
except it will unwrap the error tuple and raise
in case of errors.
Examples
iex> Jason.encode!(%{a: 1})
~S|{"a":1}|
iex> Jason.encode!("\xFF")
** (Jason.EncodeError) invalid byte 0xFF in <<255>>
@spec encode_to_iodata(term(), [encode_opt()]) :: {:ok, iodata()} | {:error, Jason.EncodeError.t() | Exception.t()}
Generates JSON corresponding to input
and returns iodata.
This function should be preferred to encode/2
, if the generated
JSON will be handed over to one of the IO functions or sent
over the socket. The Erlang runtime is able to leverage vectorised
writes and avoid allocating a continuous buffer for the whole
resulting string, lowering memory use and increasing performance.
Examples
iex> {:ok, iodata} = Jason.encode_to_iodata(%{a: 1})
iex> IO.iodata_to_binary(iodata)
~S|{"a":1}|
iex> Jason.encode_to_iodata("\xFF")
{:error, %Jason.EncodeError{message: "invalid byte 0xFF in <<255>>"}}
@spec encode_to_iodata!(term(), [encode_opt()]) :: iodata() | no_return()
Generates JSON corresponding to input
and returns iodata.
Similar to encode_to_iodata/1
except it will unwrap the error tuple
and raise in case of errors.
Examples
iex> iodata = Jason.encode_to_iodata!(%{a: 1})
iex> IO.iodata_to_binary(iodata)
~S|{"a":1}|
iex> Jason.encode_to_iodata!("\xFF")
** (Jason.EncodeError) invalid byte 0xFF in <<255>>