View Source Jason (jason v1.4.4)

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 decode_opt() ::
  {:keys, keys()}
  | {:strings, strings()}
  | {:floats, floats()}
  | {:objects, objects()}
@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 keys() :: :atoms | :atoms! | :strings | :copy | (String.t() -> term())
@type maps() :: :naive | :strict
@type objects() :: :maps | :ordered_objects
@type strings() :: :reference | :copy

Functions

Link to this function

decode(input, opts \\ [])

View Source
@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 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.
  • :floats - controls how floats are decoded. Possible values are:

  • :objects - controls how objects are decoded. Possible values are:

    • :maps (default) - objects are decoded as maps
    • :ordered_objects - objects are decoded as Jason.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}}
Link to this function

decode!(input, opts \\ [])

View Source
@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")
Link to this function

encode(input, opts \\ [])

View Source
@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:

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!(input, opts \\ [])

View Source
@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>>
Link to this function

encode_to_iodata(input, opts \\ [])

View Source
@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>>"}}
Link to this function

encode_to_iodata!(input, opts \\ [])

View Source
@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>>