jason

v1.1.2

jason v1.1.2 Jason View Source

A blazing fast JSON parser and generator in pure Elixir.

Link to this section Summary

Types

decode_opt()
encode_opt()
escape()
keys()
maps()
strings()

Functions

decode!(input, opts \\ [])

Parses a JSON value from input iodata

decode(input, opts \\ [])

Parses a JSON value from input iodata

encode!(input, opts \\ [])

Generates JSON corresponding to input

encode(input, opts \\ [])

Generates JSON corresponding to input

encode_to_iodata!(input, opts \\ [])

Generates JSON corresponding to input and returns iodata

encode_to_iodata(input, opts \\ [])

Generates JSON corresponding to input and returns iodata

Link to this section Types

Link to this type decode_opt() View Source 
decode_opt() :: {:keys, keys()} | {:strings, strings()}
Link to this type encode_opt() View Source 
encode_opt() ::
  {:escape, escape()}
  | {:maps, maps()}
  | {:pretty, true | Jason.Formatter.opts()}
Link to this type escape() View Source 
escape() :: :json | :unicode_safe | :html_safe | :javascript_safe
Link to this type keys() View Source 
keys() :: :atoms | :atoms! | :strings | :copy | (String.t() -> term())
Link to this type maps() View Source 
maps() :: :naive | :strict
Link to this type strings() View Source 
strings() :: :reference | :copy

Link to this section Functions

Link to this function decode!(input, opts \\ []) View Source 
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')
Link to this function decode(input, opts \\ []) View Source 
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 using String.to_atom/1,
    • :atoms! - keys are converted to atoms using String.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.

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}}
Link to this function encode!(input, opts \\ []) View Source 
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>>
Link to this function encode(input, opts \\ []) View Source 
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 JavaSciprt.
    • :html_safe - similar to :javascript, but also escapes the / caracter 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:

Examples 

iex> Jason.encode(%{a: 1})
{:ok, ~S|{"a":1}|}

iex> Jason.encode("\xFF")
{:error, %Jason.EncodeError{message: "invalid byte 0xFF in <<255>>"}}
Link to this function encode_to_iodata!(input, opts \\ []) View Source 
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>>
Link to this function encode_to_iodata(input, opts \\ []) View Source 
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>>"}}