defmodule Moar.Opts do
  # @related [test](/test/opts_test.exs)

  @moduledoc """
  Extracts keys and values from enumerables, especially from function options.

  There are two main functions, each of which takes an opts enumerable as input. `get/3` extracts
  one value from the opts with an optional default value. `take/2` extracts multiple values from the opts
  with optional default values for some or all keys.

  `get/3` and `take/2` differ from their `Map` and `Keyword` counterparts in the following ways:
  * `get/3` and `take/2` accept any enumerable, including maps and keyword lists.
  * `get/3` and `take/2` will fall back to the default value if the given key's value is blank
    as defined by `Moar.Term.blank?/1` (`nil`, empty strings, strings made up only of whitespace,
    empty lists, and empty maps). The corresponding `Map` and `Keyword` functions only fall back to
    the default value if the value is exactly `nil`.
  * `take/2` allows default values to be specified.
  * `take/2` will return the value for a requested key even if the key is not in the input enumerable.

  Example using `get/2` and `get/3`:

  ```elixir
  def build_url(path, opts \\\\ []) do
    %URI{
      path: path,
      host: Moar.Opts.get(opts, :host, "localhost"),
      port: Moar.Opts.get(opts, :port),
      scheme: "https"
    } |> URI.to_string()
  end
  ```

  Examples using `take/2`:

  ```elixir
  # example using pattern matching
  def build_url(path, opts \\ []) do
    %{host: h, port: p} = Moar.Opts.take(opts, [:port, host: "localhost"])
    %URI{path: path, host: h, port: p, scheme: "https"} |> URI.to_string()
  end

  # example rebinding `opts` to the parsed opts
  def build_url(path, opts \\ []) do
    opts = Moar.Opts.take(opts, [:port, host: "localhost"])
    %URI{path: path, host: opts.host, port: opts.port, scheme: "https"} |> URI.to_string()
  end
  ```
  """

  @doc """
  Get the value of `key` from `input`, falling back to optional `default` if the key does not exist,
  or if its value is blank (via `Moar.Term.blank?/1`).

  ```elixir
  iex> [a: 1, b: 2] |> Moar.Opts.get(:a)
  1

  iex> [a: 1, b: 2] |> Moar.Opts.get(:c)
  nil

  iex> [a: 1, b: 2, c: ""] |> Moar.Opts.get(:c)
  nil

  iex> [a: 1, b: 2, c: %{}] |> Moar.Opts.get(:c)
  nil

  iex> [a: 1, b: 2, c: "   "] |> Moar.Opts.get(:c, 300)
  300
  ```
  """
  @spec get(Enum.t(), binary() | atom(), any()) :: any()
  def get(input, key, default \\ nil),
    do: input |> Enum.into(%{}) |> Map.get(key) |> Moar.Term.presence(default)

  @doc """
  Get the value each key in `keys` from `input`, falling back to optional default values for keys that
  do not exist, or for values that are blank (via `Moar.Term.blank?/1`).

  If `key` does not exist in `keys`, return `nil`, or return the default value if provided.

  `keys` is a list of keys (e.g., `[:a, :b]`),
  a keyword list of keys and default values (e.g., `[a: 1, b: 2]`),
  or a hybrid list/keyword list (e.g., `[:a, b: 2]`)

  ```elixir
  iex> [a: 1, b: 2] |> Moar.Opts.take([:a, :c])
  %{a: 1, c: nil}

  iex> [a: 1, b: 2] |> Moar.Opts.take([:a, b: 0, c: 3])
  %{a: 1, b: 2, c: 3}
  ```
  """
  @spec take(Enum.t(), list()) :: map()
  def take(input, keys) do
    input = Enum.into(input, %{})

    Enum.reduce(keys, %{}, fn
      {key, default}, acc -> Map.put(acc, key, get(input, key, default))
      key, acc -> Map.put(acc, key, get(input, key))
    end)
  end
end