wafer

defmodule Wafer.Registers do
  @moduledoc """
  This module provides helpful macros for specifying the registers used to
  communicate with your device.

  This can be a massive time saver, and means you can basically just copy them
  straight out of the datasheet.

  See the documentation for `defregister/4` for more information.
  """
  alias Wafer.Chip
  alias Wafer.Conn

  @type register_name :: atom
  @type access_mode :: :ro | :rw | :wo
  @type bytes :: non_neg_integer

  @doc false
  defmacro __using__(_opts) do
    quote do
      import Wafer.Registers
    end
  end

  @doc ~S"""
  Define functions for interacting with a device register.

  ## Parameters
    - `name` - name of the register.
    - `register_address` - the address of the register.
    - `mode` the access mode of the register.
    - `bytes` the number of bytes in the register.

  ## Examples

  ### Read-only registers

  Define a read-only register named `status` at address `0x03` which is a single
  byte wide:

      iex> defregister(:status, 0x03, :ro, 1)

  This will define the following function along with documentation and
  typespecs:

  ```elixir
  def read_status(conn), do: Chip.read_register(conn, 0x03, 1)
  ```

  ### Write-only registers

  Define a write-only register named `int_en` at address `0x02` which is 2 bytes
  wide:

      iex> defregister(:int_en, 0x02, :wo, 2)

  This will define the following functions along with documentation and
  typespecs:

  ```elixir
  def write_int_en(conn, data)
      when is_binary(data) and byte_size(data) == 2,
      do: Chip.write_register(conn, 0x2, data)

  def write_int_en(_conn, data),
      do: {:error, "Argument error: #{inspect(data)}"}
  ```

  ### Read-write registers.

  Define a read-write register named `config` at address `0x01`.

      iex> defregister(:config, 0x01, :rw, 1)

  In addition to defining `read_config/1` and `write_config/2` as per the
  examples above it will also generate the following functions along with
  documentation and typespecs:

  ```elixir
  def swap_config(conn, data)
      when is_binary(data) and byte_size(data) == 1,
      do: Chip.swap_register(conn, 0x01, data)

  def swap_config(_conn, data),
      do: {:error, "Argument error: #{inspect(data)}"}

  def update_config(conn, callback)
      when is_function(callback, 1) do
        with {:ok, data} <- Chip.read_register(conn, 0x01, 1),
             new_data when is_binary(new_data) and byte_size(new_data) == 1 <- callback.(data),
             {:ok, conn} <- Chip.write_register(conn, 0x01, new_data),
             do: {:ok, conn}
      end

  def update_config(_conn, _callback),
      do: {:error, "Argument error: callback should be an arity 1 function"}
  ```

  """
  @spec defregister(atom, non_neg_integer, :ro | :rw | :wo, non_neg_integer) :: Macro.t()
  defmacro defregister(name, register_address, :ro, bytes)
           when is_atom(name) and is_integer(register_address) and register_address >= 0 and
                  is_integer(bytes) and bytes >= 0 do
    empty_bytes = 1..bytes |> Enum.map_join(", ", fn _ -> 0 end)

    quote do
      @doc """
      Read the contents of the `#{unquote(name)}` register.

      ## Example

          iex> read_#{unquote(name)}(conn)
          {:ok, <<#{unquote(empty_bytes)}>>}
      """
      @spec unquote(:"read_#{name}")(Conn.t()) :: {:ok, binary} | {:error, reason :: any}
      def unquote(:"read_#{name}")(conn),
        do: Chip.read_register(conn, unquote(register_address), unquote(bytes))
    end
  end

  defmacro defregister(name, register_address, :wo, bytes)
           when is_atom(name) and is_integer(register_address) and register_address >= 0 and
                  is_integer(bytes) and bytes >= 0 do
    empty_bytes = 1..bytes |> Enum.map_join(", ", fn _ -> 0 end)

    quote do
      @doc """
      Write new contents to the `#{unquote(name)}` register.

      ## Example

          iex> write_#{unquote(name)}(conn, <<#{unquote(empty_bytes)}>>)
          {:ok, _conn}
      """
      @spec unquote(:"write_#{name}")(Conn.t(), data :: binary) ::
              {:ok, Conn.t()} | {:error, reason :: any}
      def unquote(:"write_#{name}")(conn, data)
          when is_binary(data) and byte_size(data) == unquote(bytes),
          do: Chip.write_register(conn, unquote(register_address), data)

      def unquote(:"write_#{name}")(_conn, data), do: {:error, "Argument error: #{inspect(data)}"}
    end
  end

  # credo:disable-for-next-line Credo.Check.Refactor.CyclomaticComplexity
  defmacro defregister(name, register_address, :rw, bytes)
           when is_atom(name) and is_integer(register_address) and register_address >= 0 and
                  is_integer(bytes) and bytes >= 0 do
    empty_bytes = 1..bytes |> Enum.map_join(", ", fn _ -> 0 end)
    bits = bytes * 8

    quote do
      @doc """
      Read the contents of the `#{unquote(name)}` register.

      ## Example

          iex> read_#{unquote(name)}(conn)
          {:ok, <<#{unquote(empty_bytes)}>>}
      """
      @spec unquote(:"read_#{name}")(Conn.t()) :: {:ok, binary} | {:error, reason :: any}
      def unquote(:"read_#{name}")(conn),
        do: Chip.read_register(conn, unquote(register_address), unquote(bytes))

      @doc """
      Write new contents to the `#{unquote(name)}` register.

      ## Example

          iex> write_#{unquote(name)}(conn, <<#{unquote(empty_bytes)}>>)
          {:ok, _conn}
      """
      @spec unquote(:"write_#{name}")(Conn.t(), data :: binary) ::
              {:ok, Conn.t()} | {:error, reason :: any}
      def unquote(:"write_#{name}")(conn, data)
          when is_binary(data) and byte_size(data) == unquote(bytes),
          do: Chip.write_register(conn, unquote(register_address), data)

      def unquote(:"write_#{name}")(_conn, data), do: {:error, "Argument error: #{inspect(data)}"}

      @doc """
      Swap the contents of the `#{unquote(name)}` register.

      Reads the contents of the register, then replaces it, returning the
      previous contents.  Some drivers may implement this atomically.

      ## Example

          iex> swap_#{unquote(name)}(conn, <<#{unquote(empty_bytes)}>>)
          {:ok, <<#{unquote(empty_bytes)}>>, _conn}
      """
      @spec unquote(:"swap_#{name}")(Conn.t(), data :: binary) ::
              {:ok, Conn.t()} | {:error, reason :: any}
      def unquote(:"swap_#{name}")(conn, data)
          when is_binary(data) and byte_size(data) == unquote(bytes),
          do: Chip.swap_register(conn, unquote(register_address), data)

      def unquote(:"swap_#{name}")(_conn, data), do: {:error, "Argument error: #{inspect(data)}"}

      @doc """
      Update the contents of the `#{unquote(name)}` register using a
      transformation function.

      ## Example

          iex> transform = fn <<data::size(#{unquote(bits)})>> -> <<(data * 2)::size(#{unquote(bits)})>> end
          ...> update_#{unquote(name)}(conn, transform)
          {:ok, _conn}
      """
      @spec unquote(:"update_#{name}")(
              Conn.t(),
              (<<_::_*unquote(bits)>> -> <<_::_*unquote(bits)>>)
            ) :: {:ok, Conn.t()} | {:error, reason :: any}
      def unquote(:"update_#{name}")(conn, callback) when is_function(callback, 1) do
        with {:ok, old_data} <-
               Chip.read_register(conn, unquote(register_address), unquote(bytes)),
             new_data when is_binary(new_data) and byte_size(new_data) == unquote(bytes) <-
               callback.(old_data),
             do: Chip.write_register(conn, unquote(register_address), new_data)
      end

      def unquote(:"update_#{name}")(_conn, _callback),
        do: {:error, "Argument error: callback should be an arity 1 function"}
    end
  end

  @doc """
  Define functions for interacting with a device register with common defaults.

  ## Examples

  When specified with an access mode, assumes a 1 byte register:

      iex> defregister(:status, 0x03, :ro)

  When specified with a byte size, assumes a `:rw` register:

      iex> defregister(:config, 0x02, 2)

  """
  @spec defregister(atom, non_neg_integer, :ro | :rw | :wo | non_neg_integer) :: Macro.t()
  defmacro defregister(name, register_address, mode) when mode in ~w[ro rw wo]a do
    quote do
      defregister(unquote(name), unquote(register_address), unquote(mode), 1)
    end
  end

  defmacro defregister(name, register_address, bytes) when is_integer(bytes) and bytes >= 0 do
    quote do
      defregister(unquote(name), unquote(register_address), :rw, unquote(bytes))
    end
  end
end