defmodule DigitalToken do
  @moduledoc """
  Functions to validate, search and retrieve digital token
  data sourced from the [DTIF registry](https://dtif.org).

  """

  defstruct [
    header: nil,
    informative: nil,
    metadata: nil,
    normative: nil
  ]

  @typedoc """
  The structure of data matching that hosted in
  the [DTIF registry](https://dtif.org)/

  """
  @type t :: %__MODULE__{
    header: map(),
    informative: map(),
    metadata: map(),
    normative: map()
  }

  @typedoc """
  token_id is a random 9-character
  string defined by the [dtif registry](https://dtif.org)
  that uniquely identifies a digital token.

  """
  @type token_id :: String.t()

  @typedoc """
  A digital token may have zero of more short
  names associated with it. They are arbitrary
  strings, usually three or four characters in
  length. For example "BTC", "ETH" and "DOGE".

  """
  @type short_name :: String.t()

  @typedoc """
  A mapping of digital token identifiers
  to the registry data for that token.

  """
  @type token_map :: %{
    token_id() => t()
  }

  @typedoc """
  A mapping from a short name to token
  identifier.

  """
  @type short_name_map :: %{
    short_name() => token_id()
  }

  @typedoc """
  A mapping of digital token identifiers
  to a currency symbol for that token.

  """
  @type symbol_map :: %{
    token_id() => String.t()
  }

  defguard is_digital_token(token_id) when is_binary(token_id) and byte_size(token_id) == 9

  @doc """
  Returns a map of the digital tokens in the
  [dtif registry](https://dtif.org).

  """
  @spec tokens :: token_map()
  def tokens do
    DigitalToken.Data.tokens()
  end

  @doc """
  Returns a mapping of digital token short
  names to digital token identifiers.

  """
  @spec short_names :: short_name_map()
  def short_names do
    DigitalToken.Data.short_names()
  end

  @doc """
  Returns a mapping of digital token identifiers
  names to a currency symbol.

  """
  @spec symbols :: symbol_map()
  def symbols do
    DigitalToken.Data.symbols()
  end

  @doc """
  Validates a token identifier or short name
  and returns the token identifier or an error.

  ## Arguments

  * `id` is any token identifier or short name

  ## Returns

  * `{:ok, token_id}` or

  * `{:error, {exception, id}}`

  ## Example

      iex> DigitalToken.validate_token("BTC")
      {:ok, "4H95J0R2X"}

      iex> DigitalToken.validate_token("Bitcoin")
      {:ok, "4H95J0R2X"}

      iex> DigitalToken.validate_token "4H95J0R2X"
      {:ok, "4H95J0R2X"}

      iex> DigitalToken.validate_token("Nothing")
      {:error, {DigitalToken.UnknownTokenError, "Nothing"}}

  """
  @spec validate_token(token_id() | short_name()) ::
    {:ok, token_id()} | {:error, {module(), any()}}
  def validate_token(id) do
    cond do
      Map.has_key?(tokens(), id) ->
        {:ok, id}

      token = Map.get(short_names(), id) ->
        {:ok, token}

      id ->
        {:error, unknown_token_error(id)}
    end
  end

  @doc """
  Returns the short name of a digital token.

  ## Arguments

  * `token_id` is any validate digitial token identifier.

  ## Returns

  * `{:ok, short_name}` where `short_name` is either
    the first short name in `token.informative.short_names` or
    the token long name if there are no short names.

  * `{:error, {exceoption, reason}}`

  ## Examples

      iex> DigitalToken.short_name "BTC"
      {:ok, "BTC"}

      iex> DigitalToken.short_name "4H95J0R2X"
      {:ok, "BTC"}

      iex> DigitalToken.short_name "W0HBX7RC4"
      {:ok, "Terra"}

  """
  @spec short_name(token_id) :: {:ok, String.t()} | {:error, {module(), String.t}}
  def short_name(token_id) do
    with {:ok, token} <- get_token(token_id) do
      case Map.get(token.informative, :short_names) do
        [first | _rest] -> {:ok, first}
        _other -> {:ok, token.informative.long_name}
      end
    end
  end

  @doc """
  Returns the long name of a digital token.

  ## Arguments

  * `token_id` is any validate digitial token identifier.

  ## Returns

  * `{:ok, long_name}` where `long_name` is the token's
    registered name.

  * `{:error, {exceoption, reason}}`

  ## Examples

      iex> DigitalToken.long_name "BTC"
      {:ok, "Bitcoin"}

      iex> DigitalToken.long_name "4H95J0R2X"
      {:ok, "Bitcoin"}

      iex> DigitalToken.long_name "W0HBX7RC4"
      {:ok, "Terra"}

  """
  @spec long_name(token_id) :: {:ok, String.t()} | {:error, {module(), String.t}}
  def long_name(token_id) do
    with {:ok, token} <- get_token(token_id) do
      Map.fetch(token.informative, :long_name)
    end
  end

  @doc """
  Returns a currency symbol used in number formatting.

  ## Arguements

  * `token_id` is any validate digitial token identifier.

  * `style` is a number in the range `1` to `4` as follows:
      * `1` is the token's symbol, if it exists
      * `2` is the token's short name as a proxy for a currency code
      * `3` is the token's long name
      * `4` is the token's symbol as a proxy for a narrow currency symbol

  ## Returns

  * `{:ok, symbol}` or

  * `{:error, {exception, reason}}`

  ## Examples

      iex> DigitalToken.symbol "BTC", 1
      {:ok, "₿"}

      iex> DigitalToken.symbol "BTC", 2
      {:ok, "BTC"}

      iex> DigitalToken.symbol "BTC", 3
      {:ok, "Bitcoin"}

      iex> DigitalToken.symbol "BTC", 4
      {:ok, "₿"}

      iex> DigitalToken.symbol "ETH", 4
      {:ok, "Ξ"}

      iex> DigitalToken.symbol "DOGE", 4
      {:ok, "Ð"}

      iex> DigitalToken.symbol "DODGY", 4
      {:error, {DigitalToken.UnknownTokenError, "DODGY"}}

  """
  @spec symbol(token_id, 1..4) :: {:ok, String.t()} | {:error, {module(), String.t}}
  def symbol(token_id, style) when style in [1, 4] do
    with {:ok, token_id} <- validate_token(token_id),
         {:ok, symbol} <- Map.fetch(symbols(), token_id) do
      {:ok, symbol}
    else
      :error -> short_name(token_id)
      other_error -> other_error
    end
  end

  def symbol(token_id, 2)  do
    short_name(token_id)
  end

  def symbol(token_id, 3) do
    long_name(token_id)
  end

  @doc """
  Returns the registry data for a given token
  identifier.

  ## Arugments

  * `id` is any token identifier or short name

  ## Returns

  * `{:ok, registry_data}` or

  * `{:error, {exception, id}}`

  ## Example

      DigitalToken.get_token("BTC")
      #=> {:ok,
       %DigitalToken{
         header: %{
           dlt_type: :blockchain,
           dti: "4H95J0R2X",
           dti_type: :native,
           template_version: #Version<1.0.0>
         },
         informative: %{
           long_name: "Bitcoin",
           public_distributed_ledger_indication: false,
           short_names: ["BTC", "XBT"],
           unit_multiplier: 100000000,
           url: "https://github.com/bitcoin/bitcoin"
         },
         metadata: %{
           .....

  """
  @spec get_token(token_id() | short_name()) :: {:ok, t()} | {:error, {module(), any()}}
  def get_token(id) do
    with {:ok, token} <- validate_token(id) do
      {:ok, Map.fetch!(tokens(), token)}
    end
  end

  @doc """
  Returns the registry data for a given token
  identifier.

  ## Arugments

  * `id` is any token identifier or short name

  ## Returns

  * `registry_data` or

  * raises an exception

  ## Example

      DigitalToken.get_token("BTC")
      #=> %DigitalToken{
         header: %{
           dlt_type: :blockchain,
           dti: "4H95J0R2X",
           dti_type: :native,
           template_version: #Version<1.0.0>
         },
         informative: %{
           long_name: "Bitcoin",
           public_distributed_ledger_indication: false,
           short_names: ["BTC", "XBT"],
           unit_multiplier: 100000000,
           url: "https://github.com/bitcoin/bitcoin"
         },
         metadata: %{
           .....

  """
  @spec get_token!(token_id() | short_name()) :: t() | no_return()
  def get_token!(id) do
    case get_token(id) do
      {:ok, token} -> token
      {:error, {exception, id}} -> raise exception, id
    end
  end

  defp unknown_token_error(id) do
    {DigitalToken.UnknownTokenError, id}
  end
end