defmodule Msgpax do
  @moduledoc ~S"""
  This module provides functions for serializing and deserializing Elixir terms
  using the [MessagePack](http://msgpack.org/) format.

  ## Data conversion

  The following table shows how Elixir types are serialized to MessagePack types
  and how MessagePack types are deserialized back to Elixir types.

  Elixir                            | MessagePack   | Elixir
  --------------------------------- | ------------- | -------------
  `nil`                             | nil           | `nil`
  `true`                            | boolean       | `true`
  `false`                           | boolean       | `false`
  `-1`                              | integer       | `-1`
  `1.25`                            | float         | `1.25`
  *N/A*¹                            | NaN           | `Msgpax.NaN`²
  *N/A*¹                            | +infinity     | `Msgpax.Infinity`²
  *N/A*¹                            | -infinity     | `Msgpax.NegInfinity`²
  `:ok`                             | string        | `"ok"`
  `Atom`                            | string        | `"Elixir.Atom"`
  `"text"`                          | string        | `"text"`
  `"\xFF\xFF"`                      | string        | `"\xFF\xFF"`
  `#Msgpax.Bin<"\xFF">`             | binary        | `"\xFF"`³
  `%{foo: "bar"}`                   | map           | `%{"foo" => "bar"}`
  `[foo: "bar"]`                    | map           | `%{"foo" => "bar"}`
  `[1, true]`                       | array         | `[1, true]`
  `#Msgpax.Ext<4, "02:12">`         | extension     | `#Msgpax.Ext<4, "02:12">`
  `#DateTime<2017-12-06 00:00:00Z>` | extension     | `#DateTime<2017-12-06 00:00:00Z>`

  ¹ `Msgpax.Packer` provides helper functions to facilitate the serialization of natively unsupported data types.

  ² NaN and ±infinity are not enabled by default. See `unpack/2` for for more information.

  ³ To deserialize back to `Msgpax.Bin` structs see the `unpack/2` options.
  """

  alias __MODULE__.Packer
  alias __MODULE__.Unpacker

  @doc """
  Serializes the given `term`.

  This function returns iodata by default; if you want to force the result to be
  a binary, you can use `IO.iodata_to_binary/1` or use the `:iodata` option (see
  the "Options" section below).

  This function returns `{:ok, iodata}` if the serialization is successful,
  `{:error, exception}` otherwise, where `exception` is a `Msgpax.PackError`
  struct which can be raised or converted to a more human-friendly error
  message with `Exception.message/1`. See `Msgpax.PackError` for all the
  possible reasons for a packing error.

  ## Options

    * `:iodata` - (boolean) if `true`, this function returns the encoded term as
      iodata, if `false` as a binary. Defaults to `true`.

  ## Examples

      iex> {:ok, packed} = Msgpax.pack("foo")
      iex> IO.iodata_to_binary(packed)
      <<163, 102, 111, 111>>

      iex> Msgpax.pack(20000000000000000000)
      {:error, %Msgpax.PackError{reason: {:too_big, 20000000000000000000}}}

      iex> Msgpax.pack("foo", iodata: false)
      {:ok, <<163, 102, 111, 111>>}

  """
  @spec pack(term, Keyword.t()) :: {:ok, iodata} | {:error, Msgpax.PackError.t() | Exception.t()}
  def pack(term, options \\ []) when is_list(options) do
    iodata? = Keyword.get(options, :iodata, true)

    try do
      Packer.pack(term)
    catch
      :throw, reason ->
        {:error, %Msgpax.PackError{reason: reason}}

      :error, %Protocol.UndefinedError{protocol: Msgpax.Packer} = exception ->
        {:error, exception}
    else
      iodata when iodata? ->
        {:ok, iodata}

      iodata ->
        {:ok, IO.iodata_to_binary(iodata)}
    end
  end

  @doc """
  Works as `pack/1`, but raises if there's an error.

  This function works like `pack/1`, except it returns the `term` (instead of
  `{:ok, term}`) if the serialization is successful or raises a
  `Msgpax.PackError` exception otherwise.

  ## Options

  This function accepts the same options as `pack/2`.

  ## Examples

      iex> "foo" |> Msgpax.pack!() |> IO.iodata_to_binary()
      <<163, 102, 111, 111>>

      iex> Msgpax.pack!(20000000000000000000)
      ** (Msgpax.PackError) too big value: 20000000000000000000

      iex> Msgpax.pack!("foo", iodata: false)
      <<163, 102, 111, 111>>

  """
  @spec pack!(term, Keyword.t()) :: iodata | no_return
  def pack!(term, options \\ []) do
    case pack(term, options) do
      {:ok, result} ->
        result

      {:error, exception} ->
        raise exception
    end
  end

  @doc """
  Serializes `term` and turns the result into a `Msgpax.Fragment`.

  This function returns `{:ok, fragment}` if the serialization is successful,
  `{:error, exception}` otherwise, where `exception` is a `Msgpax.PackError`
  struct which can be raised or converted to a more human-friendly error
  message with `Exception.message/1`. See `Msgpax.PackError` for all the
  possible reasons for a packing error.

  This is useful for optimization, for instance, to avoid packing heavy terms
  repetitively.

  Another good use case for fragments would be data encapsulation. For example,
  if we want to "interpolate" some MessagePack data into the payload without
  having to unpack and pack them.

  ## Options

  This function accepts the same options as `pack/2`.

  ## Examples

      iex> {:ok, fragment} = Msgpax.pack_fragment("HUGE")
      iex> {:ok, packed} = Msgpax.pack([fragment, fragment])
      iex> IO.iodata_to_binary(packed)
      <<146, 164, 72, 85, 71, 69, 164, 72, 85, 71, 69>>

  """
  @spec pack_fragment(term, Keyword.t()) ::
          {:ok, Msgpax.Fragment.t()} | {:error, Msgpax.PackError.t() | Exception.t()}
  def pack_fragment(term, options \\ []) do
    with {:ok, packed} <- Msgpax.pack(term, options) do
      {:ok, Msgpax.Fragment.new(packed)}
    end
  end

  @doc """
  Works as `pack_fragment/2`, but raises if there's an error.

  This function works like `pack_fragment!/2`, except it returns the `fragment` (instead of
  `{:ok, fragment}`) if the serialization is successful or raises a `Msgpax.PackError`
  exception otherwise.

  ## Options

  This function accepts the same options as `pack_fragment/2`.

  ## Examples

      iex> fragment = Msgpax.pack_fragment!("HUGE")
      iex> {:ok, packed} = Msgpax.pack([fragment, fragment])
      iex> IO.iodata_to_binary(packed)
      <<146, 164, 72, 85, 71, 69, 164, 72, 85, 71, 69>>

  """
  @spec pack_fragment!(term, Keyword.t()) :: Msgpax.Fragment.t() | no_return()
  def pack_fragment!(term, options \\ []) do
    case pack_fragment(term, options) do
      {:ok, fragment} -> fragment
      {:error, exception} -> raise exception
    end
  end

  @doc """
  Deserializes part of the given `iodata`.

  This function works like `unpack/2`, but instead of requiring the input to be
  a MessagePack-serialized term with nothing after that, it accepts leftover
  bytes at the end of `iodata` and only deserializes the part of the input that
  makes sense. It returns `{:ok, term, rest}` if deserialization is successful,
  `{:error, exception}` otherwise (where `exception` is a `Msgpax.UnpackError`
  struct).

  See `unpack/2` for more information on the supported options.

  ## Examples

      iex> Msgpax.unpack_slice(<<163, "foo", "junk">>)
      {:ok, "foo", "junk"}

      iex> Msgpax.unpack_slice(<<163, "fo">>)
      {:error, %Msgpax.UnpackError{reason: {:invalid_format, 163}}}

  """
  @spec unpack_slice(iodata, Keyword.t()) :: {:ok, any, binary} | {:error, Msgpax.UnpackError.t()}
  def unpack_slice(iodata, options \\ []) when is_list(options) do
    try do
      iodata
      |> IO.iodata_to_binary()
      |> Unpacker.unpack(options)
    catch
      :throw, reason ->
        {:error, %Msgpax.UnpackError{reason: reason}}
    else
      {value, rest} ->
        {:ok, value, rest}
    end
  end

  @doc """
  Works like `unpack_slice/2` but raises in case of error.

  This function works like `unpack_slice/2`, but returns just `{term, rest}` if
  deserialization is successful and raises a `Msgpax.UnpackError` exception if
  it's not.

  ## Examples

      iex> Msgpax.unpack_slice!(<<163, "foo", "junk">>)
      {"foo", "junk"}

      iex> Msgpax.unpack_slice!(<<163, "fo">>)
      ** (Msgpax.UnpackError) invalid format, first byte: 163

  """
  @spec unpack_slice!(iodata, Keyword.t()) :: {any, binary} | no_return
  def unpack_slice!(iodata, options \\ []) do
    case unpack_slice(iodata, options) do
      {:ok, value, rest} ->
        {value, rest}

      {:error, exception} ->
        raise exception
    end
  end

  @doc """
  Deserializes the given `iodata`.

  This function deserializes the given `iodata` into an Elixir term. It returns
  `{:ok, term}` if the deserialization is successful, `{:error, exception}`
  otherwise, where `exception` is a `Msgpax.UnpackError` struct which can be
  raised or converted to a more human-friendly error message with
  `Exception.message/1`. See `Msgpax.UnpackError` for all the possible reasons
  for an unpacking error.

  ## Options

    * `:binary` - (boolean) if `true`, then binaries are decoded as `Msgpax.Bin`
      structs instead of plain Elixir binaries. Defaults to `false`.

    * `:ext` - (module) a module that implements the `Msgpax.Ext.Unpacker`
      behaviour. For more information, see the docs for `Msgpax.Ext.Unpacker`.

    * `:nonfinite_floats` - (boolean) if `true`, deserializes NaN and ±infinity to
      "signalling" atoms (see the "Data conversion" section), otherwise errors.
      Defaults to `false`.

  ## Examples

      iex> Msgpax.unpack(<<163, "foo">>)
      {:ok, "foo"}

      iex> Msgpax.unpack(<<163, "foo", "junk">>)
      {:error, %Msgpax.UnpackError{reason: {:excess_bytes, "junk"}}}

      iex> packed = Msgpax.pack!(Msgpax.Bin.new(<<3, 18, 122, 27, 115>>))
      iex> {:ok, bin} = Msgpax.unpack(packed, binary: true)
      iex> bin
      #Msgpax.Bin<<<3, 18, 122, 27, 115>>>

  """
  @spec unpack(iodata, Keyword.t()) :: {:ok, any} | {:error, Msgpax.UnpackError.t()}
  def unpack(iodata, options \\ []) do
    case unpack_slice(iodata, options) do
      {:ok, value, <<>>} ->
        {:ok, value}

      {:ok, _, bytes} ->
        {:error, %Msgpax.UnpackError{reason: {:excess_bytes, bytes}}}

      {:error, _} = error ->
        error
    end
  end

  @doc """
  Works like `unpack/2`, but raises in case of errors.

  This function works like `unpack/2`, but it returns `term` (instead of `{:ok,
  term}`) if deserialization is successful, otherwise raises a
  `Msgpax.UnpackError` exception.

  ## Example

      iex> Msgpax.unpack!(<<163, "foo">>)
      "foo"

      iex> Msgpax.unpack!(<<163, "foo", "junk">>)
      ** (Msgpax.UnpackError) found excess bytes: "junk"

      iex> packed = Msgpax.pack!(Msgpax.Bin.new(<<3, 18, 122, 27, 115>>))
      iex> Msgpax.unpack!(packed, binary: true)
      #Msgpax.Bin<<<3, 18, 122, 27, 115>>>

  """
  @spec unpack!(iodata, Keyword.t()) :: any | no_return
  def unpack!(iodata, options \\ []) do
    case unpack(iodata, options) do
      {:ok, value} ->
        value

      {:error, exception} ->
        raise exception
    end
  end
end