moar

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

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

  There are three main functions, each of which takes an opts enumerable as input. `get/3` extracts
  one value from the opts with an optional default value. `pop/3` is like `get/3` but removes the opt from opts
  and returns the opt and the remaining opts as a tuple. `take/2` extracts multiple values from the opts
  with optional default values for some or all keys.

  `get/3`, `pop/3`, and `take/2` differ from their `Map` and `Keyword` counterparts in the following ways:
  * `get/3`, `pop/3`, and `take/2` accept any enumerable, including maps, keyword lists, and mixed lists like
    `[:a, :b, c: 3, d: 4]`.
  * `get/3`, `pop/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), and will default valueless keys (e.g., `:a` in `[:a, b: 2]`) to `true` unless a
    different default is specified. The corresponding `Map` and `Keyword` functions only fall back to
    the default value if the value is exactly `nil`, and `Keyword` functions don't support valueless keys.
  * `get/3`, `pop/3`, and `take/2` allow 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 """
  Deletes an opt given a key, a {key, value}, or a function that accepts opts and a map, list, or term.

  ```elixir
  iex> Moar.Opts.delete(%{a: 1, b: 2}, :a)
  %{b: 2}

  iex> Moar.Opts.delete([a: 1, b: 2], :a)
  [b: 2]

  iex> Moar.Opts.delete([:a, b: 2], :a)
  [b: 2]

  iex> Moar.Opts.delete([a: 1, b: 2], :a, 1)
  [b: 2]

  iex> Moar.Opts.delete([a: 1, b: 2], :a, 99)
  [a: 1, b: 2]

  iex> Moar.Opts.delete([:a, b: 2], :a, 1)
  [:a, b: 2]

  iex> Moar.Opts.delete([:trim, :downcase, :reverse], fn k -> k == :downcase end)
  [:trim, :reverse]

  iex> Moar.Opts.delete([a: 1, b: 2, c: 3, d: 4], fn {_k, v} -> Integer.mod(v, 2) == 0 end)
  [a: 1, c: 3]
  ```
  """
  @spec delete(map() | list(), any()) :: map() | list()
  @spec delete(map() | list(), any(), any()) :: map() | list()

  def delete(input, fun) when is_function(fun) and is_map(input) do
    Enum.reduce(input, %{}, fn
      {k, v}, acc -> if fun.({k, v}), do: acc, else: Map.put(acc, k, v)
    end)
  end

  def delete(input, fun) when is_function(fun) and is_list(input) do
    List.foldr(input, [], fn
      {k, v}, acc -> if fun.({k, v}), do: acc, else: [{k, v} | acc]
      k, acc -> if fun.(k), do: acc, else: [k | acc]
    end)
  end

  def delete(input, fun) when is_function(fun) do
    if fun.(input),
      do: input,
      else: nil
  end

  def delete(input, key) do
    delete(input, fn
      {k, _v} -> k == key
      k -> k == key
    end)
  end

  def delete(input, key, value) do
    delete(input, fn
      {k, v} -> k == key && v == value
      _ -> false
    end)
  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, b: 2] |> Moar.Opts.get(:a)
  true

  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
    Enum.find_value(input, fn
      {k, v} -> k == key && Moar.Term.presence(v)
      k -> k == key && Moar.Term.presence(default, true)
    end) || default
  end

  @doc """
  Removes an opt from the opts (via `get/3`), returning `{opt, remaining_opts}`.

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

  iex> [:a, b: 2] |> Moar.Opts.pop(:a)
  {true, [b: 2]}
  ```
  """
  @spec pop(Enum.t(), binary() | atom(), any()) :: {any(), Enum.t()}
  def pop(input, key, default \\ nil)

  def pop(input, key, default) when is_list(input) do
    value = get(input, key, default)

    list =
      cond do
        key in input -> List.delete(input, key)
        Keyword.has_key?(input, key) -> Keyword.delete(input, key)
        :else -> input
      end

    {value, list}
  end

  def pop(input, key, default) when is_map(input),
    do: {get(input, key, default), Map.delete(input, key)}

  @doc """
  Replace an opt.

  ```elixir
  iex> Moar.Opts.replace(%{a: 1, b: 2}, {:a, 1}, {:a, 100})
  %{a: 100, b: 2}

  iex> Moar.Opts.replace([a: 1, b: 2], {:a, 1}, {:a, 100})
  [a: 100, b: 2]

  iex> Moar.Opts.replace([:a, b: 2], :a, :aa)
  [:aa, b: 2]
  ```
  """
  @spec replace(map(), {any(), any()}, {any(), any()}) :: map()
  @spec replace(list(), {any(), any()} | any(), any()) :: list()

  def replace(opts, {key, value}, {replacement_key, replacement_value}) when is_map(opts) do
    Enum.reduce(opts, %{}, fn {k, v}, acc ->
      if key == k && value == v,
        do: Map.put(acc, replacement_key, replacement_value),
        else: Map.put(acc, k, v)
    end)
  end

  def replace(opts, {key, value}, replacement) when is_list(opts) do
    List.foldr(opts, [], fn {k, v}, acc ->
      if key == k && value == v,
        do: [replacement | acc],
        else: [{k, v} | acc]
    end)
  end

  def replace(opts, key, replacement) when is_list(opts) do
    List.foldr(opts, [], fn k, acc ->
      if key == k,
        do: [replacement | acc],
        else: [k | acc]
    end)
  end

  @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`, returns `nil`, or returns 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, b: 2] |> Moar.Opts.take([:a, :c])
  %{a: true, 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
    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