protox

defmodule Protox do
  @moduledoc ~S'''
  Use this module to generate the Elixir structs corresponding to a set of protobuf definitions
  and to encode/decode instances of these structures.

  ## Elixit structs generation examples
  From a set of files:
      defmodule Dummy do
        use Protox,
          files: [
            "./defs/foo.proto",
            "./defs/bar.proto",
            "./defs/baz/fiz.proto",
          ]
      end

  From a string:
      defmodule Dummy do
        use Protox,
          schema: """
          syntax = "proto3";
          package fiz;

          message Baz {
          }

          message Foo {
            map<int32, Baz> b = 2;
          }
          """
      end

  The generated modules respect the package declaration. For instance, in the above example,
  both the `Fiz.Baz` and `Fiz.Foo` modules will be generated.

  ## Encoding/decoding
  For the rest of this module documentation, we suppose the following protobuf messages are defined:
      defmodule Dummy do
        use Protox,
          schema: """
            syntax = "proto3";
            package fiz;

            message Baz {
            }

            enum Enum {
              FOO = 0;
              BAR = 1;
            }

            message Foo {
              Enum a = 1;
              map<int32, Baz> b = 2;
            }
          """,
          namespace: Namespace

        use Protox,
          schema: """
          syntax = "proto3";

          message Msg {
            map<int32, string> msg_k = 8;
          }
          """

        use Protox,
          schema: """
          syntax = "proto3";

          message Sub {
            int32 a = 1;
          }
          """
      end

  See each function documentation to see how they are used to encode and decode protobuf messages.
  '''

  defmacro __using__(opts) do
    {opts, _} = Code.eval_quoted(opts)

    {paths, opts} = get_paths(opts)
    {files, opts} = get_files(opts)

    {:ok, file_descriptor_set} = Protox.Protoc.run(files, paths)

    %{enums: enums, messages: messages} = Protox.Parse.parse(file_descriptor_set, opts)

    quote do
      unquote(make_external_resources(files))
      unquote(Protox.Define.define(enums, messages, opts))
    end
  end

  @doc """
  Throwing version of `decode/2`.
  """
  @doc since: "1.6.0"
  @spec decode!(binary(), atom()) :: struct() | no_return()
  def decode!(binary, msg_module) do
    msg_module.decode!(binary)
  end

  @doc """
  Decode a binary into a protobuf message.

  ## Examples
      iex> binary = <<66, 7, 8, 1, 18, 3, 102, 111, 111, 66, 7, 8, 2, 18, 3, 98, 97, 114>>
      iex> {:ok, msg} = Protox.decode(binary, Msg)
      iex> msg
      %Msg{msg_k: %{1 => "foo", 2 => "bar"}}

      iex> binary = <<66, 7, 8, 1, 18, 3, 102, 111, 66, 7, 8, 2, 18, 3, 98, 97, 114>>
      iex> {:error, reason} = Protox.decode(binary, Msg)
      iex> reason
      %Protox.IllegalTagError{message: "Field with illegal tag 0"}
  """
  @doc since: "1.6.0"
  @spec decode(binary(), atom()) :: {:ok, struct()} | {:error, any()}
  def decode(binary, msg_module) do
    msg_module.decode(binary)
  end

  @doc """
  Throwing version of `encode/1`.
  """
  @doc since: "1.6.0"
  @spec encode!(struct()) :: iodata() | no_return()
  def encode!(msg) do
    msg.__struct__.encode!(msg)
  end

  @doc """
  Encode a protobuf message into IO data.

  ## Examples
      iex> msg = %Namespace.Fiz.Foo{a: 3, b: %{1 => %Namespace.Fiz.Baz{}}}
      iex> {:ok, iodata} = Protox.encode(msg)
      iex> :binary.list_to_bin(iodata)
      <<8, 3, 18, 4, 8, 1, 18, 0>>

      iex> msg = %Namespace.Fiz.Foo{a: "should not be a string"}
      iex> {:error, reason} = Protox.encode(msg)
      iex> reason
      %Protox.EncodingError{field: :a, message: "Could not encode field :a (invalid field value)"}

  """
  @doc since: "1.6.0"
  @spec encode(struct()) :: {:ok, iodata()} | {:error, any()}
  def encode(msg) do
    msg.__struct__.encode(msg)
  end

  @doc """
  ## Errors
  This function returns a tuple `{:error, reason}` if:
  - `input` could not be decoded to JSON; `reason` is a `Protox.JsonDecodingError` error

  ## JSON library configuration
  The default library to decode JSON is [`Jason`](https://github.com/michalmuskala/jason).
  However, you can chose to use [`Poison`](https://github.com/devinus/poison):
      iex> Protox.json_decode("{\\"a\\":\\"BAR\\"}", Namespace.Fiz.Foo, json_decoder: Poison)
      {:ok, %Namespace.Fiz.Foo{__uf__: [], a: :BAR, b: %{}}}

  You can also use another library as long as it exports an `decode!` function. You can easily
  create a module to wrap a library that would not have this interface (like [`jiffy`](https://github.com/davisp/jiffy)):
      defmodule Jiffy do
        def decode!(input) do
          :jiffy.decode(input, [:return_maps, :use_nil])
        end
      end
  """
  @doc since: "1.6.0"
  @spec json_decode(iodata(), atom(), keyword()) :: {:ok, struct()} | {:error, any()}
  def json_decode(input, message_module, opts \\ []) do
    message_module.json_decode(input, opts)
  end

  @doc """
  Throwing version of `json_decode/2`.
  """
  @doc since: "1.6.0"
  @spec json_decode!(iodata(), atom(), keyword()) :: iodata() | no_return()
  def json_decode!(input, message_module, opts \\ []) do
    message_module.json_decode!(input, opts)
  end

  @doc """
  Export a proto3 message to JSON as IO data.

  ## Errors
  This function returns a tuple `{:error, reason}` if:
  - `msg` could not be encoded to JSON; `reason` is a `Protox.JsonEncodingError` error

  ## Examples
      iex> msg = %Namespace.Fiz.Foo{a: :BAR}
      iex> {:ok, iodata} = Protox.json_encode(msg)
      iex> iodata
      ["{", ["\\"a\\"", ":", "\\"BAR\\""], "}"]

      iex> msg = %Sub{a: 42}
      iex> {:ok, iodata} = Protox.json_encode(msg)
      iex> iodata
      ["{", ["\\"a\\"", ":", "42"], "}"]

      iex> msg = %Msg{msg_k: %{1 => "foo", 2 => "bar"}}
      iex> {:ok, iodata} = msg |> Protox.json_encode()
      iex> :binary.list_to_bin(iodata)
      "{\\"msgK\\":{\\"2\\":\\"bar\\",\\"1\\":\\"foo\\"}}"

  ## JSON library configuration
  The default library to encode values (i.e. mostly to escape strings) to JSON  is [`Jason`](https://github.com/michalmuskala/jason).
  However, you can chose to use [`Poison`](https://github.com/devinus/poison):
      iex> msg = %Namespace.Fiz.Foo{a: :BAR}
      iex> Protox.json_encode(msg, json_encoder: Poison)
      {:ok, ["{", ["\\"a\\"", ":", "\\"BAR\\""], "}"]}

  You can also use another library as long as it exports an `encode!` function, which is expected to return objects as maps and `nil`
  to represent `null`.
  You can easily create a module to wrap a library that would not have this interface (like [`jiffy`](https://github.com/davisp/jiffy)):
      defmodule Jiffy do
        defdelegate encode!(msg), to: :jiffy, as: :encode
      end

  ## Encoding specifications
  See https://developers.google.com/protocol-buffers/docs/proto3#json for the specifications
  of the encoding.
  """
  @doc since: "1.6.0"
  @spec json_encode(struct(), keyword()) :: {:ok, iodata()} | {:error, any()}
  def json_encode(msg, opts \\ []) do
    msg.__struct__.json_encode(msg, opts)
  end

  @doc """
  Throwing version of `json_encode/1`.
  """
  @doc since: "1.6.0"
  @spec json_encode!(struct(), keyword()) :: iodata() | no_return()
  def json_encode!(msg, opts \\ []) do
    msg.__struct__.json_encode!(msg, opts)
  end

  # -- Private

  defp get_paths(opts) do
    case Keyword.pop(opts, :paths) do
      {nil, opts} -> get_path(opts)
      {ps, opts} -> {Enum.map(ps, &Path.expand/1), opts}
    end
  end

  defp get_path(opts) do
    case Keyword.pop(opts, :path) do
      {nil, opts} -> {nil, opts}
      {p, opts} -> {[Path.expand(p)], opts}
    end
  end

  defp get_files(opts) do
    case Keyword.pop(opts, :schema) do
      {<<text::binary>>, opts} ->
        filename = "#{Base.encode16(:crypto.hash(:sha, text))}.proto"
        filepath = [Mix.Project.build_path(), filename] |> Path.join() |> Path.expand()
        File.write!(filepath, text)
        {[filepath], opts}

      {nil, opts} ->
        {files, opts} = Keyword.pop(opts, :files)
        {Enum.map(files, &Path.expand/1), opts}
    end
  end

  defp make_external_resources(files) do
    Enum.map(files, fn file -> quote(do: @external_resource(unquote(file))) end)
  end
end