cat-bookmarker/deps/jason/lib/jason.ex

defmodule Jason do
  @moduledoc """
  A blazing fast JSON parser and generator in pure Elixir.
  """

  alias Jason.{Encode, Decoder, DecodeError, EncodeError, Formatter}

  @type escape :: :json | :unicode_safe | :html_safe | :javascript_safe
  @type maps :: :naive | :strict

  @type encode_opt :: {:escape, escape} | {:maps, maps} | {:pretty, boolean | Formatter.opts()}

  @type keys :: :atoms | :atoms! | :strings | :copy | (String.t() -> term)

  @type strings :: :reference | :copy

  @type floats :: :native | :decimals

  @type objects :: :maps | :ordered_objects

  @type decode_opt :: {:keys, keys} | {:strings, strings} | {:floats, floats} | {:objects, objects}

  @doc """
  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:

      * `:native` (default) - Native conversion from binary to float using `:erlang.binary_to_float/1`,
      * `:decimals` - uses `Decimal.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 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}}
  """
  @spec decode(iodata, [decode_opt]) :: {:ok, term} | {:error, DecodeError.t()}
  def decode(input, opts \\ []) do
    input = IO.iodata_to_binary(input)
    Decoder.parse(input, format_decode_opts(opts))
  end

  @doc """
  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 decode!(iodata, [decode_opt]) :: term | no_return
  def decode!(input, opts \\ []) do
    case decode(input, opts) do
      {:ok, result} -> result
      {:error, error} -> raise error
    end
  end

  @doc """
  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]) ::
          {:ok, String.t()} | {:error, EncodeError.t() | Exception.t()}
  def encode(input, opts \\ []) do
    case do_encode(input, format_encode_opts(opts)) do
      {:ok, result} -> {:ok, IO.iodata_to_binary(result)}
      {:error, error} -> {:error, error}
    end
  end

  @doc """
  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!(term, [encode_opt]) :: String.t() | no_return
  def encode!(input, opts \\ []) do
    case do_encode(input, format_encode_opts(opts)) do
      {:ok, result} -> IO.iodata_to_binary(result)
      {:error, error} -> raise error
    end
  end

  @doc """
  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]) ::
          {:ok, iodata} | {:error, EncodeError.t() | Exception.t()}
  def encode_to_iodata(input, opts \\ []) do
    do_encode(input, format_encode_opts(opts))
  end

  @doc """
  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>>

  """
  @spec encode_to_iodata!(term, [encode_opt]) :: iodata | no_return
  def encode_to_iodata!(input, opts \\ []) do
    case do_encode(input, format_encode_opts(opts)) do
      {:ok, result} -> result
      {:error, error} -> raise error
    end
  end

  defp do_encode(input, %{pretty: true} = opts) do
    case Encode.encode(input, opts) do
      {:ok, encoded} -> {:ok, Formatter.pretty_print_to_iodata(encoded)}
      other -> other
    end
  end

  defp do_encode(input, %{pretty: pretty} = opts) when pretty !== false do
    case Encode.encode(input, opts) do
      {:ok, encoded} -> {:ok, Formatter.pretty_print_to_iodata(encoded, pretty)}
      other -> other
    end
  end

  defp do_encode(input, opts) do
    Encode.encode(input, opts)
  end

  defp format_encode_opts(opts) do
    Enum.into(opts, %{escape: :json, maps: :naive})
  end

  defp format_decode_opts(opts) do
    Enum.into(opts, %{keys: :strings, strings: :reference, floats: :native, objects: :maps})
  end
end