Current section
Files
Jump to
Current section
Files
lib/option/utility.ex
defmodule Plymio.Option.Utility do
@moduledoc ~S"""
Utility Function for Managing (Keyword) Options ("opts")
## Documentation Terms
In the documentation there are terms, usually in *italics*, used to mean the same thing (e.g. *opts*).
### opts
*opts* is a `Keyword`.
### derivable opts
*derivable opts* is either a `Keyword` or `Map` with `Atom` keys (from which the *opts* can be *derived* simply using `Map.to_list/1`).
### *key*
A *key* is an `Atom`.
### key list
A *key list* is a list of *key*s.
### key spec
A *key spec* is usually a *key list*.
Alternatively a `Map` with `Atom` keys or a `Keyword` can be given and the (unique) keys will be used.
### key alias dict
A *key alias dict* is usually a `Map` with `Atom` keys and values used for canonicalising keys (e.g. as the 2nd argument to `opts_canonical_keys/2`).
Alternatively a `Keyword` with `Atom` values can be given and will be converted on the fly.
### key dict
A *key alias dict* is usually a `Map` with `Atom` keys.
Alternatively a `Keyword` with `Atom` values can be given and will be converted on the fly.
### tuple predicate
A *tuple predicate* is an arity one function that when passed a `{key,value}` tuple returns `true` or `false`.
## Return Values
Many functions support an API that returns either `{:ok, result}` or {`:error, error}` where `error` will be an `Exception`.
The default action for bang function when fielding `{:error, error}` is to raise the `error`.
In many cases the `error` will be a `KeyError` where its `key` field is set to the key, or list of keys, that is missing, unknown, etc.
"""
@type key :: atom
@type keys :: key | [key]
@type alias_key :: key
@type alias_keys :: keys
@type alias_value :: nil | alias_keys
@type aliases_kvs :: [{alias_key, alias_value}]
@type aliases_tuples :: [{alias_key, alias_key}]
@type aliases_dict :: %{optional(alias_key) => alias_key}
@type defaults_map :: %{optional(alias_key) => any}
@type opts :: Keyword.t
@type dict :: %{optional(alias_key) => any}
@type error :: struct
defdelegate opts_take_keys(arg0,arg1), to: Keyword, as: :take
defdelegate opts_drop_keys(arg0,arg1), to: Keyword, as: :drop
defp normalise_key_spec(value)
defp normalise_key_spec(value) when is_list(value) do
cond do
Keyword.keyword?(value) -> {:ok, value |> Keyword.keys |> Enum.uniq}
true ->
value
|> Enum.reject(&is_atom/1)
|> case do
[] -> {:ok, value |> Enum.uniq}
not_atom_keys -> {:error, %KeyError{key: not_atom_keys, term: value}}
end
end
end
defp normalise_key_spec(value) when is_map(value) do
value |> Map.keys |> normalise_key_spec
end
defp normalise_key_spec(value) do
new_error_result(m: "expected enum", v: value)
end
@spec validate_key_list(any) :: {:ok, keys} | {:error, error}
defp validate_key_list(keys)
defp validate_key_list(keys) when is_list(keys) do
keys
|> Enum.reject(&is_atom/1)
|> case do
[] -> {:ok, keys}
not_atoms -> not_atoms |> new_key_error_result(keys)
end
end
defp validate_key_list(keys) do
new_error_result(m: "expected valid key list", v: keys)
end
defp normalise_key_list(keys) do
keys |> validate_key_list
end
@spec validate_key_alias_dict(any) :: {:ok, aliases_dict} | {:error, error}
defp validate_key_alias_dict(dict)
defp validate_key_alias_dict(dict) when is_map(dict) do
with true <- dict |> Map.keys |> Enum.all?(&is_atom/1),
true <- dict |> Map.values |> Enum.all?(&is_atom/1) do
{:ok, dict}
else
false -> new_error_result(m: "expected valid key alias dictionary", v: dict)
end
end
@spec normalise_key_alias_dict(any) :: {:ok, aliases_dict} | {:error, error}
defp normalise_key_alias_dict(dict)
defp normalise_key_alias_dict(dict) when is_map(dict) do
dict |> validate_key_alias_dict
end
defp normalise_key_alias_dict(dict) when is_list(dict) do
cond do
Keyword.keyword?(dict) -> dict |> Enum.into(%{}) |> validate_key_alias_dict
true ->
new_error_result(m: "expected valid alias dictionary", v: dict)
end
end
defp normalise_key_alias_dict(dict) do
new_error_result(m: "expected valid alias dictionary", v: dict)
end
@spec validate_key_dict(any) :: {:ok, aliases_dict} | {:error, error}
defp validate_key_dict(dict)
defp validate_key_dict(dict) when is_map(dict) do
with true <- dict |> Map.keys |> Enum.all?(&is_atom/1) do
{:ok, dict}
else
false -> new_error_result(m: "expected valid key dictionary", v: dict)
end
end
@spec normalise_key_dict(any) :: {:ok, aliases_dict} | {:error, error}
defp normalise_key_dict(dict)
defp normalise_key_dict(dict) when is_map(dict) do
dict |> validate_key_dict
end
defp normalise_key_dict(dict) when is_list(dict) do
cond do
Keyword.keyword?(dict) -> dict |> Enum.into(%{})
true ->
new_error_result(m: "expected valid key dictionary", v: dict)
end
end
defp normalise_key_dict(dict) do
new_error_result(m: "expected valid key dictionary", v: dict)
end
@doc false
defp opts_index_normalise(opts, index)
defp opts_index_normalise(opts, index)
when is_list(opts) and is_integer(index) and index >= 0 do
{:ok, index}
end
defp opts_index_normalise(opts, index)
when is_list(opts) and is_integer(index) and index < 0 do
{:ok, length(opts) + index}
end
defp opts_index_normalise(opts, _index) when not is_list(opts) do
new_error_result(m: "opts invalid", v: opts)
end
defp opts_index_normalise(_opts, index) when not is_integer(index) do
new_error_result(m: "index invalid", v: index)
end
defp opts_index_validate(opts, index)
when is_list(opts) and is_integer(index) do
with {:ok, index} <- opts |> opts_index_normalise(index) do
index_max = length(opts) - 1
case index do
x when x >= 0 -> x
x -> index_max + x + 1
end
|> fn
ndx when ndx < 0 -> new_error_result(m: :index_too_small, v: ndx)
ndx when ndx > index_max -> new_error_result(m: :index_too_large, v: ndx)
ndx -> {:ok, ndx}
end.()
else
{:error, _} = result -> result
end
end
defp opts_index_validate(opts, _index) when not is_list(opts) do
new_error_result(m: "opts invalid", v: opts)
end
defp opts_index_validate(_opts, index) when not is_integer(index) do
new_error_result(m: "index invalid", v: index)
end
defp opts_indices_validate(opts, indices)
defp opts_indices_validate(opts, nil) do
{:ok, opts |> Enum.with_index |> Enum.map(&(elem(&1,1)))}
end
defp opts_indices_validate(opts, indices) when is_list(opts) do
indices
|> List.wrap
|> Enum.reduce({[],[]},
fn index, {valid_indices,invalid_indices} ->
case opts |> opts_index_validate(index) do
{:ok, index} -> {[index | valid_indices], invalid_indices}
{:error, _} -> {valid_indices, [index | invalid_indices]}
end
end)
|> case do
{valid_indices, []} -> {:ok, valid_indices |> Enum.reverse}
{_valid_indices, invalid_indices} ->
case invalid_indices |> length do
1 -> new_error_result(m: "index invalid", v: invalid_indices |> hd)
_ -> new_error_result(m: "indices invalid", v: invalid_indices |> Enum.reverse)
end
end
end
@doc ~S"""
`opts_normalise/` expects a *derivable opts* and returns `{:ok, opts}`.
Any other argument causes `{:error, error}` to be returned.
## Examples
iex> [] |> opts_normalise
{:ok, []}
iex> %{a: 1, b: 2, c: 3} |> opts_normalise
{:ok, [a: 1, b: 2, c: 3]}
iex> %{"a" => 1, :b => 2, :c => 3} |> opts_normalise
{:error, %KeyError{key: "a", term: %{:b => 2, :c => 3, "a" => 1}}}
iex> 42 |> opts_normalise
{:error, %ArgumentError{message: "expected valid derivable opts; got: 42"}}
iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_normalise
{:ok, [a: nil, b: [:b1], c: [:c1, :c2, :c3]]}
"""
@spec opts_normalise(any) :: {:ok, opts} | {:error, error}
def opts_normalise(value) do
cond do
Keyword.keyword?(value) -> {:ok, value}
is_map(value) ->
value
|> Map.to_list
|> fn tuples ->
tuples
|> Keyword.keyword?
|> case do
true -> {:ok, tuples}
_ ->
tuples
|> Keyword.keys
|> Enum.reject(&is_atom/1)
|> new_key_error_result(value)
end
end.()
true -> new_error_result(m: "expected valid derivable opts", v: value)
end
end
@doc ~S"""
`opts_normalise!/1` calls `opts_normalise/1` and if the result is `{:ok, opts}` returns `opts`.
## Examples
iex> [] |> opts_normalise!
[]
iex> %{a: 1, b: 2, c: 3} |> opts_normalise!
[a: 1, b: 2, c: 3]
iex> %{"a" => 1, :b => 2, :c => 3} |> opts_normalise!
** (KeyError) key "a" not found in: %{:b => 2, :c => 3, "a" => 1}
iex> 42 |> opts_normalise!
** (ArgumentError) expected valid derivable opts; got: 42
iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_normalise!
[a: nil, b: [:b1], c: [:c1, :c2, :c3]]
"""
@spec opts_normalise!(any) :: opts | no_return
def opts_normalise!(opts) do
case opts |> opts_normalise do
{:ok, opts} -> opts
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_normalise_map/` expects a *derivable opts* as argument.
If the argument is a `Map`, with `Atom` keys, it returns `{:ok, argument}` directly.
If the argument is a `Keyword`, with `Atom` keys, it returns `{:ok, argument |> Enum.into(%{})}`.
Any other argument causes `{:error, error}` to be returned.
## Examples
iex> [] |> opts_normalise_map
{:ok, %{}}
iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_normalise_map
{:ok, %{a: nil, b: [:b1], c: [:c1, :c2, :c3]}}
iex> %{a: 1, b: 2, c: 3} |> opts_normalise_map
{:ok, %{a: 1, b: 2, c: 3}}
iex> %{"a" => 1, :b => 2, :c => 3} |> opts_normalise_map
{:error, %KeyError{key: ["a"], term: %{:b => 2, :c => 3, "a" => 1}}}
iex> 42 |> opts_normalise_map
{:error, %ArgumentError{message: "expected valid derivable opts; got: 42"}}
"""
@spec opts_normalise_map(any) :: {:ok, opts} | {:error, error}
def opts_normalise_map(value) do
cond do
Keyword.keyword?(value) -> {:ok, value |> Enum.into(%{})}
is_map(value) ->
with {:ok, _} <- value |> normalise_key_spec do
{:ok, value}
else
{:error, %KeyError{} = error} -> {:error, struct!(error, term: value)}
{:error, _} = result -> result
end
true -> new_error_result(m: "expected valid derivable opts", v: value)
end
end
@doc ~S"""
`opts_normalise_map!/1` call `opts_normalise_map/1` and if the result is `{:ok, map}` returns `map`.
## Examples
iex> [] |> opts_normalise_map!
%{}
iex> [a: 1, b: 2, c: 3] |> opts_normalise_map!
%{a: 1, b: 2, c: 3}
iex> %{a: 1, b: 2, c: 3} |> opts_normalise_map!
%{a: 1, b: 2, c: 3}
iex> %{"a" => 1, :b => 2, :c => 3} |> opts_normalise_map!
** (KeyError) key ["a"] not found in: %{:b => 2, :c => 3, "a" => 1}
iex> 42 |> opts_normalise_map!
** (ArgumentError) expected valid derivable opts; got: 42
"""
@spec opts_normalise_map!(any) :: opts | no_return
def opts_normalise_map!(opts) do
case opts |> opts_normalise_map do
{:ok, map} -> map
{:error, %KeyError{} = error} -> raise struct!(error, term: opts)
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_validate/1` returns `{:ok, opts}` if the argument is an *opts*.
Any other argument causes `{:error, error}` to be returned.
## Examples
iex> [] |> opts_validate
{:ok, []}
iex> %{a: 1, b: 2, c: 3} |> opts_validate
{:error, %ArgumentError{message: "validate opts failed; got: %{a: 1, b: 2, c: 3}"}}
iex> %{"a" => 1, :b => 2, :c => 3} |> opts_validate
{:error, %ArgumentError{message: "validate opts failed; got: %{:b => 2, :c => 3, \"a\" => 1}"}}
iex> 42 |> opts_validate
{:error, %ArgumentError{message: "validate opts failed; got: 42"}}
iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_validate
{:ok, [a: nil, b: [:b1], c: [:c1, :c2, :c3]]}
"""
@spec opts_validate(any) :: {:ok, opts} | {:error, error}
def opts_validate(value) do
case Keyword.keyword?(value) do
true -> {:ok, value}
_ -> new_error_result(m: "validate opts failed", v: value)
end
end
@doc ~S"""
`opts_validate!/1` calls `opts_validate/1` and, if the result is `{:ok, opts}`, returns `opts`.
## Examples
iex> [] |> opts_validate!
[]
iex> %{a: 1, b: 2, c: 3} |> opts_validate!
** (ArgumentError) validate opts failed; got: %{a: 1, b: 2, c: 3}
iex> %{"a" => 1, :b => 2, :c => 3} |> opts_validate!
** (ArgumentError) validate opts failed; got: %{:b => 2, :c => 3, "a" => 1}
iex> 42 |> opts_validate!
** (ArgumentError) validate opts failed; got: 42
iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_validate!
[a: nil, b: [:b1], c: [:c1, :c2, :c3]]
"""
@spec opts_validate!(opts) :: opts | no_return
def opts_validate!(opts) do
case opts |> opts_validate do
{:ok, opts} -> opts
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_create_aliases_tuples/1` takes an *opts* where the keys are the canonical key names, and their values are zero (nil), one or more aliases for the canonical key.
A `Keyword` is returned where each key is an alias and its value the canonical key.
The canonical key also has an entry for itself with the same value.
## Examples
iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_create_aliases_tuples
[a: :a, b: :b, b1: :b, c: :c, c1: :c, c2: :c, c3: :c]
"""
@spec opts_create_aliases_tuples(aliases_kvs) :: aliases_tuples
def opts_create_aliases_tuples(aliases) do
aliases
|> Enum.map(fn
{k,nil} -> {k,k}
{k,a} ->
[k | a |> List.wrap]
|> Enum.uniq
|> Enum.map(fn a -> {a,k} end)
end)
|> List.flatten
end
@doc ~S"""
`opts_create_aliases_dict/1` does the same job as `opts_create_aliases_tuples/1` but returns a *key alias dict*.
## Examples
iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_create_aliases_dict
%{a: :a, b: :b, b1: :b, c: :c, c1: :c, c2: :c, c3: :c}
"""
@spec opts_create_aliases_dict(aliases_kvs) :: aliases_dict
def opts_create_aliases_dict(aliases) do
aliases
|> opts_create_aliases_tuples
|> Enum.into(%{})
end
@doc ~S"""
`opts_create_defstruct/2` takes an *opts*, together with a defaults map, and returns an *opts* where each value if the value of the key in the defaults map (with default `nil`).
`opts_create_defstruct/2` creates an argument suitable for use with `Kernel.defstruct/1`
The defaults map must contain *only* keys that are also in the opts list; any unknown keys will raise a `KeyError.`
## Examples
iex> [a: 1, b: :two, c: "tre", d: nil] |> opts_create_defstruct(%{a: 42, b: "two"})
[a: 42, b: "two", c: nil, d: nil]
iex> [a: 1, b: :two, c: "tre", d: nil] |> opts_create_defstruct(%{a: 42, b: "two", x: 1})
** (KeyError) key [:x] not found in: [a: 1, b: :two, c: "tre", d: nil]
"""
@spec opts_create_defstruct(opts, defaults_map) :: opts
def opts_create_defstruct(struct_kvs, defaults_map \\ %{})
def opts_create_defstruct(struct_kvs, defaults_map)
when is_map(defaults_map) and (map_size(defaults_map) == 0) do
struct_kvs |> Enum.map(fn {k,_v} -> {k,nil} end)
end
def opts_create_defstruct(struct_kvs, defaults_map)
when is_map(defaults_map) do
# do not allow keys in the default that aren't in the struct_kvs
# too dangerous as hard to spot e.g default with wrong name
struct_map = struct_kvs |> Map.new(fn {k,_v} -> {k, nil} end)
defaults_map
# get rid of known keys
|> Enum.reject(fn {k,_v} -> struct_map |> Map.has_key?(k) end)
|> Keyword.keys
|> case do
# no unknown keys
[] -> nil
unknown_keys ->
raise KeyError, key: unknown_keys, term: struct_kvs
end
struct_kvs
|> Enum.map(fn {k,_v} -> {k, defaults_map |> Map.get(k)} end)
end
@doc ~S"""
`opts_crue_defstruct/2` takes a *derivable opts*, together with a defaults map, and returns `{:ok, opts}` where each value is the value of the key in the defaults map (with default `nil`).
`opts_crue_defstruct/2` creates an argument suitable for use with `Kernel.defstruct/1`
The defaults map must contain *only* keys that are also in the opts list; any unknown keys will cause `{:error, error}`, where `error` is a `KeyError`, to be returned.
## Examples
iex> [a: 1, b: :two, c: "tre", d: nil] |> opts_crue_defstruct(%{a: 42, b: "two"})
{:ok, [a: 42, b: "two", c: nil, d: nil]}
iex> [a: 1, b: :two, c: "tre", d: nil] |> opts_crue_defstruct(%{a: 42, b: "two", x: 1})
{:error, %KeyError{key: :x, term: [a: 1, b: :two, c: "tre", d: nil]}}
"""
@spec opts_crue_defstruct(opts, defaults_map) :: {:ok, opts} | {:error, error}
def opts_crue_defstruct(struct_kvs, defaults_map \\ %{})
def opts_crue_defstruct(struct_kvs, defaults_map)
when is_map(defaults_map) and (map_size(defaults_map) == 0) do
{:ok, struct_kvs |> Enum.map(fn {k,_v} -> {k,nil} end)}
end
def opts_crue_defstruct(struct_kvs, defaults_map)
when is_map(defaults_map) do
with {:ok, struct_kvs} <- struct_kvs |> opts_normalise do
# do not allow keys in the default that aren't in the struct_kvs
# too dangerous as hard to spot e.g default with wrong name
struct_map = struct_kvs |> Map.new(fn {k,_v} -> {k, nil} end)
defaults_map
# get rid of known keys
|> Enum.reject(fn {k,_v} -> struct_map |> Map.has_key?(k) end)
|> Keyword.keys
|> case do
# no unknown keys
[] -> {:ok, struct_kvs |> Enum.map(fn {k,_v} -> {k, defaults_map |> Map.get(k)} end)}
unknown_keys -> unknown_keys |> new_key_error_result(struct_kvs)
end
else
{:error, _} = result -> result
end
end
@doc ~S"""
`opts_crue_defstruct!/2` calls `opts_crue_defstruct/2` and if the result is `{:ok, opts}` returns `opts`.
## Examples
iex> [a: 1, b: :two, c: "tre", d: nil] |> opts_crue_defstruct!(%{a: 42, b: "two"})
[a: 42, b: "two", c: nil, d: nil]
iex> [a: 1, b: :two, c: "tre", d: nil] |> opts_crue_defstruct!(%{a: 42, b: "two", x: 1})
** (KeyError) key :x not found in: [a: 1, b: :two, c: "tre", d: nil]
"""
@spec opts_crue_defstruct!(opts, defaults_map) :: opts | no_return
def opts_crue_defstruct!(struct_kvs, defaults_map \\ %{})
def opts_crue_defstruct!(opts, defaults_map) do
case opts_crue_defstruct(opts, defaults_map) do
{:ok, opts} -> opts
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_avoir_keys/2` takes an *opts* and a *key spec*.
If all of the keys are present in the `opts`, its returns `{:ok, opts}`.
If there are any missing keys, `{:error, error}`, where `error` is a `KeyError`, will be returned.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys([:a, :b, :c])
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys(%{a: 1, b: 2, c: 3})
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys([:a, :b, :d, :a])
{:error, %KeyError{key: :d, term: [a: 1, b: 2, c: 3]}}
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys(%{x: nil, y: nil, z: nil})
{:error, %KeyError{key: [:x, :y, :z], term: [a: 1, b: 2, c: 3]}}
"""
@spec opts_avoir_keys(any, any) :: {:ok, opts} | {:error, error}
def opts_avoir_keys(opts, keys)
def opts_avoir_keys(opts, keys) do
with {:ok, opts_keys} <- opts |> normalise_key_spec,
{:ok, wanted_keys} <- keys |> normalise_key_spec do
wanted_keys -- opts_keys
|> case do
# none missing
[] -> {:ok, opts}
missing_keys -> missing_keys |> new_key_error_result(opts)
end
else
{:error, _} = result -> result
end
end
@doc ~S"""
`opts_avoir_keys?/2` calls `opts_avoir_keys/2` and if the result is `{:ok, _}`, returns `true`, else `false`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys?([:a, :b, :c])
true
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys?(%{a: 1, b: 2, c: 3})
true
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys?([:a, :b, :d, :a])
false
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys?(%{x: nil, y: nil, z: nil})
false
"""
@spec opts_avoir_keys?(any, any) :: true | false
def opts_avoir_keys?(opts, keys) do
case opts_avoir_keys(opts, keys) do
{:ok, _} -> true
_ -> false
end
end
@doc ~S"""
`opts_avoir_keys!/2` calls `opts_avoir_keys/2` and if the result is `{:ok, opts}`, returns `opts`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys!([:a, :b, :c])
[a: 1, b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys!(%{a: 1, b: 2, c: 3})
[a: 1, b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys!([:a, :b, :d, :a])
** (KeyError) key :d not found in: [a: 1, b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_avoir_keys!(%{x: nil, y: nil, z: nil})
** (KeyError) key [:x, :y, :z] not found in: [a: 1, b: 2, c: 3]
"""
@spec opts_avoir_keys!(any, any) :: opts | no_return
def opts_avoir_keys!(opts, keys) do
case opts_avoir_keys(opts, keys) do
{:ok, opts} -> opts
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_has_keys/2` takes an *opts*, together with a list or dictionary (map) of wanted `keys`.
If all of the `keys` are present in the `opts`, its returns `{:ok, opts}`.
If there are any missing keys, `{:error, {present_opts, missing_keys}}` is returned, where the
`present_opts` include *only* the tuples for the wanted keys (i.e. result of `Keyword.take/2` for the wanted keys).
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_has_keys([:a, :b, :c])
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_has_keys(%{a: 1, b: 2, c: 3})
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_has_keys([:a, :b, :d, :a])
{:error, {[a: 1, b: 2], [:d]}}
iex> [a: 1, b: 2, c: 3] |> opts_has_keys(%{x: nil, y: nil, z: nil})
{:error, {[], [:x, :y, :z]}}
"""
@spec opts_has_keys(opts, keys) :: {:ok, opts} | {:error, {opts,opts}}
@spec opts_has_keys(opts, dict) :: {:ok, opts} | {:error, {opts,opts}}
def opts_has_keys(opts, keys_or_dict)
def opts_has_keys(opts, dict) when is_map(dict) do
opts
|> opts_has_keys(dict |> Map.keys)
end
def opts_has_keys(opts, keys) when is_list(keys) do
opts_keys = opts |> Keyword.keys |> Enum.uniq
wanted_keys = keys |> Enum.uniq
wanted_keys -- opts_keys
|> case do
# none missing
[] -> {:ok, opts}
missing_keys ->
wanted_tuples = opts |> opts_take_keys(wanted_keys)
{:error, {wanted_tuples, missing_keys}}
end
end
@doc ~S"""
`opts_has_keys?/2` calls `opts_has_keys/2` and if the result is `{:ok, _}`, returns `true`, else `false`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_has_keys?([:a, :b, :c])
true
iex> [a: 1, b: 2, c: 3] |> opts_has_keys?(%{a: 1, b: 2, c: 3})
true
iex> [a: 1, b: 2, c: 3] |> opts_has_keys?([:a, :b, :d, :a])
false
iex> [a: 1, b: 2, c: 3] |> opts_has_keys?(%{x: nil, y: nil, z: nil})
false
"""
@spec opts_has_keys?(opts, keys) :: true | false
@spec opts_has_keys?(opts, dict) :: true | false
def opts_has_keys?(opts, keys) do
case opts_has_keys(opts, keys) do
{:ok, _} -> true
_ -> false
end
end
@doc ~S"""
`opts_has_keys!/2` calls `opts_has_keys/2` and if the result is `{:ok, opts}`, returns `opts`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_has_keys!([:a, :b, :c])
[a: 1, b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_has_keys!(%{a: 1, b: 2, c: 3})
[a: 1, b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_has_keys!([:a, :b, :d, :a])
** (KeyError) key [:d] not found in: [a: 1, b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_has_keys!(%{x: nil, y: nil, z: nil})
** (KeyError) key [:x, :y, :z] not found in: [a: 1, b: 2, c: 3]
"""
@spec opts_has_keys!(opts, keys) :: opts | no_return
@spec opts_has_keys!(opts, dict) :: opts | no_return
def opts_has_keys!(opts, keys) do
case opts_has_keys(opts, keys) do
{:ok, x} -> x
{:error, {_present_tuples, missing_keys}} ->
raise KeyError, key: missing_keys, term: opts
end
end
@doc ~S"""
`opts_canon_keys!/2` takes an *opts*, together with a lookup dictionary and replaces each key with its canonical value from the dictionary. Unknown keys raise a `KeyError`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_canon_keys!(%{a: :x, b: :y, c: :z})
[x: 1, y: 2, z: 3]
iex> [x: 1, y: 3, z: 3] |> opts_canon_keys!(%{a: 1, b: 2, c: 3})
** (KeyError) key :x not found in: %{a: 1, b: 2, c: 3}
"""
@spec opts_canon_keys!(opts, dict) :: opts | no_return
def opts_canon_keys!(opts, dict) when is_map(dict) do
opts |> Enum.map(fn {k,v} -> {dict |> Map.fetch!(k), v} end)
end
@doc ~S"""
`opts_canon_keys/2` takes an *opts*, together with either a dictionary (map) or (keyword) list of aliases.
If a dictionary is provided, each key in the `opts` is replaced with its (canonical) value from the dictionary, returning `{:ok, transformed_opts}`.
If a (keyword) list of aliases is provided, the aliases are first converted into a dictionary by `opts_create_aliases_dict/1` and the dictionary used as described above.
If there are any unknown keys, `{:error, {known_opts, unknown_opts}}` is returned.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_canon_keys(%{a: :x, b: :y, c: :z})
{:ok, [x: 1, y: 2, z: 3]}
iex> [a: 11, p: 1, b: 22, q: 2, c: 33, r: 3] |> opts_canon_keys(%{a: :x, b: :y, c: :z})
{:error, {[x: 11, y: 22, z: 33], [p: 1, q: 2, r: 3]}}
iex> [a: 1, b: 2, c: 3] |> opts_canon_keys([a_canon: :a, b_canon: [:b], c_canon: [:c, :cc]])
{:ok, [a_canon: 1, b_canon: 2, c_canon: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_canon_keys([a_canon: :a, b_canon: nil, c_canon: [:c, :cc]])
{:error, {[a_canon: 1, c_canon: 3], [b: 2]}}
"""
@spec opts_canon_keys(opts, dict) :: {:ok, opts} | {:error, {opts, opts}}
@spec opts_canon_keys(opts, opts) :: {:ok, opts} | {:error, {opts, opts}}
def opts_canon_keys(opts, dict) when is_map(dict) do
opts
# split into known and unknown keys
|> Enum.split_with(fn {k,_v} -> Map.has_key?(dict, k) end)
|> case do
# no unknown keys
{known_tuples, []} ->
{:ok, opts_canon_keys!(known_tuples, dict)}
{known_tuples, unknown_tuples} ->
{:error, {opts_canon_keys!(known_tuples, dict), unknown_tuples}}
end
end
def opts_canon_keys(opts, aliases) when is_list(aliases) do
opts
|> opts_canon_keys(aliases |> opts_create_aliases_dict)
end
@doc ~S"""
`opts_canonical_keys/2` takes a *derivable opts*, together with a *key alias dict*.
Each key in the `opts` is replaced with its (canonical) value from the dictionary, returning `{:ok, canon_opts}`.
If there are any unknown keys, `{:error, error}`, where `error` is a `KeyError`, will be returned.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_canonical_keys(%{a: :x, b: :y, c: :z})
{:ok, [x: 1, y: 2, z: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_canonical_keys([a: :x, b: :y, c: :z])
{:ok, [x: 1, y: 2, z: 3]}
iex> [a: 11, p: 1, b: 22, q: 2, c: 33, r: 3] |> opts_canonical_keys(%{a: :x, b: :y, c: :z})
{:error, %KeyError{key: [:p, :q, :r], term: %{a: :x, b: :y, c: :z}}}
iex> [a: 1, b: 2, c: 3] |> opts_canonical_keys([a_canon: :a, b_canon: [:b], c_canon: [:c, :cc]])
{:error, %ArgumentError{message: "expected valid key alias dictionary; got: %{a_canon: :a, b_canon: [:b], c_canon: [:c, :cc]}"}}
"""
@spec opts_canonical_keys(any, any) :: {:ok, opts} | {:error, error}
def opts_canonical_keys(opts, dict) do
with {:ok, opts} <- opts |> opts_normalise,
{:ok, dict} <- dict |> normalise_key_alias_dict do
opts
# reject known_keys
|> Enum.reject(fn {k,_v} -> Map.has_key?(dict, k) end)
|> case do
# no unknown keys
[] ->
canon_tuples = opts
|> Enum.map(fn{k,v} -> {Map.get(dict,k), v} end)
{:ok, canon_tuples}
unknown_tuples -> unknown_tuples |> new_key_error_result(dict)
end
else
{:error, _} = result -> result
end
end
@doc ~S"""
`opts_canonical_keys!/2` calls `opts_canonical_keys/2` and if the result is `{:ok, opts}` returns `opts`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_canonical_keys!(%{a: :x, b: :y, c: :z})
[x: 1, y: 2, z: 3]
iex> [a: 1, b: 2, c: 3] |> opts_canonical_keys!([a: :x, b: :y, c: :z])
[x: 1, y: 2, z: 3]
iex> [x: 1, y: 3, z: 3] |> opts_canonical_keys!(%{a: 1, b: 2, c: 3})
** (ArgumentError) expected valid key alias dictionary; got: %{a: 1, b: 2, c: 3}
"""
@spec opts_canonical_keys!(any, any) :: opts | no_return
def opts_canonical_keys!(opts, dict) do
with {:ok, opts} <- opts |> opts_canonical_keys(dict) do
opts
else
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_sort_keys/` takes a *derivable opts*, together with a list of sort keys, and returns the opts sorted in the sort keys order. Duplicate keys follow one after another.
Any keys found but not given in the sort keys follow the sorted keys in the returned opts.
Any key in the sort list not found in the opts is ignored.
## Examples
iex> [a: 1, b: 2, c: 3, d: 4] |> opts_sort_keys
[a: 1, b: 2, c: 3, d: 4]
iex> [a: 1, b: 2, c: 3, d: 4] |> opts_sort_keys([:c, :a])
[c: 3, a: 1, b: 2, d: 4]
iex> [] |> opts_sort_keys([:c, :a])
[]
iex> [a: 11, b: 2, c: 3, a: 12, d: 4] |> opts_sort_keys([:c, :a])
[c: 3, a: 11, a: 12, b: 2, d: 4]
iex> [a: 11, b: 21, c: 3, a: 12, d: 4, b: 22] |> opts_sort_keys([:d, :x, :b, :z])
[d: 4, b: 21, b: 22, a: 11, c: 3, a: 12]
"""
@spec opts_sort_keys(any, any) :: {:ok, opts} | {:error, error}
def opts_sort_keys(opts, keys \\ [])
def opts_sort_keys([], _keys) do
[]
end
def opts_sort_keys(opts, keys) do
sort_keys = keys |> Enum.uniq
sort_dict = sort_keys |> Map.new(fn k -> {k,nil} end)
# partition the opts into sort and other keys
{sorted_tuples, remain_tuples} = opts
|> Enum.split_with(fn {k,_v} -> Map.has_key?(sort_dict, k) end)
# collect the sorted_tuples for same key
sort_keys
|> Enum.flat_map(fn k ->
sorted_tuples
|> Keyword.get_values(k)
|> Enum.map(fn v -> {k,v} end)
end)
|> Kernel.++(remain_tuples)
end
@doc ~S"""
`opts_take_keys!/1` takes an *opts*, together with a *key list* and returns the *opts* with just the supplied keys.
It any of the keys are not found, raises a `KeyError` citing the missing keys.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_take_keys!([:c, :a])
[a: 1, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_take_keys!([:d, :a])
** (KeyError) key [:d] not found in: [a: 1, b: 2, c: 3]
"""
@spec opts_take_keys!(opts, keys) :: opts
def opts_take_keys!(opts, keys \\ [])
def opts_take_keys!([], _keys) do
[]
end
def opts_take_keys!(opts, []) when is_list(opts) do
[]
end
def opts_take_keys!(opts, keys) when is_list(keys) do
opts
|> opts_take_keys(keys)
# check all keys present
|> opts_has_keys(keys)
|> case do
{:ok, new_opts} -> new_opts
{:error, {_present_opts, missing_keys}} ->
raise KeyError, key: missing_keys, term: opts
end
end
@doc ~S"""
`opts_drop_keys!/1` takes an *opts*, together with a *key list* and returns the *opts* without the supplied keys.
It any of the keys are not found, raises a `KeyError` citing the missing keys.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_drop_keys!([:b])
[a: 1, c: 3]
iex> [a: 11, b: 21, c: 3, b: 22, a: 12] |> opts_drop_keys!([:b])
[a: 11, c: 3, a: 12]
iex> [a: 1, b: 2, c: 3] |> opts_drop_keys!([:d, :a])
** (KeyError) key [:d] not found in: [a: 1, b: 2, c: 3]
"""
@spec opts_drop_keys!(opts, keys) :: opts
def opts_drop_keys!(opts, keys \\ [])
def opts_drop_keys!([], _keys) do
[]
end
def opts_drop_keys!(opts, []) when is_list(opts) do
[]
end
def opts_drop_keys!(opts, keys) when is_list(keys) do
opts
|> opts_has_keys(keys)
|> case do
{:ok, _} -> opts |> opts_drop_keys(keys)
{:error, {_present_opts, missing_keys}} ->
raise KeyError, key: missing_keys, term: opts
end
end
@doc ~S"""
`opts_filter/2` takes a *derivable opts*, together with a *tuple predicate* and returns `{:ok, opts}` where `opts` has all the 2tuples the *tuple predicate* return `true` for.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_filter(&(&1))
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_filter(
...> fn
...> {:a,_} -> true
...> _ -> false
...> end)
{:ok, [a: 1]}
iex> %{a: 1, b: 2, c: 3} |> opts_filter(
...> fn
...> {:a,_} -> false
...> _ -> true
...> end)
{:ok, [b: 2, c: 3]}
iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_filter(:not_a_function)
...> match?(%ArgumentError{message: "expected valid tuple predicate; got: :not_a_function"}, error)
true
iex> {:error, error} = :not_opts |> opts_filter(&(&1))
...> match?(%ArgumentError{message: "expected valid derivable opts; got: :not_opts"}, error)
true
"""
@spec opts_filter(any, any) :: {:ok, opts} | {:error, error}
def opts_filter(opts, fun_pred) when is_function(fun_pred,1) do
with {:ok, opts} <- opts |> opts_normalise do
opts = opts
|> Enum.filter(fun_pred)
{:ok, opts}
else
{:error, _} = result -> result
end
end
def opts_filter(_opts, fun_pred) do
new_error_result(m: "expected valid tuple predicate", v: fun_pred)
end
@doc ~S"""
`opts_filter!/2` calls `opts_filter/2` and if the result is `{:ok, opts}` returns `opts`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_filter!(&(&1))
[a: 1, b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_filter!(
...> fn
...> {:a,_} -> true
...> _ -> false
...> end)
[a: 1]
iex> %{a: 1, b: 2, c: 3} |> opts_filter!(
...> fn
...> {:a,_} -> false
...> _ -> true
...> end)
[b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_filter!(:not_a_function)
** (ArgumentError) expected valid tuple predicate; got: :not_a_function
iex> :not_opts |> opts_filter!(&(&1))
** (ArgumentError) expected valid derivable opts; got: :not_opts
"""
@spec opts_filter!(any, any) :: opts | no_return
def opts_filter!(opts, dict) do
with {:ok, opts} <- opts |> opts_filter(dict) do
opts
else
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_reject/2` takes a *derivable opts*, together with a *tuple predicate* and returns `{:ok, opts}` where `opts` has all the 2tuples the *tuple predicate* returns `false` for.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_reject(&(&1))
{:ok, []}
iex> [a: 1, b: 2, c: 3] |> opts_reject(
...> fn
...> {:a,_} -> true
...> _ -> false
...> end)
{:ok, [b: 2, c: 3]}
iex> %{a: 1, b: 2, c: 3} |> opts_reject(
...> fn
...> {:a,_} -> false
...> _ -> true
...> end)
{:ok, [a: 1]}
iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_reject(:not_a_function)
...> match?(%ArgumentError{message: "expected valid tuple predicate; got: :not_a_function"}, error)
true
iex> {:error, error} = :not_opts |> opts_reject(&(&1))
...> match?(%ArgumentError{message: "expected valid derivable opts; got: :not_opts"}, error)
true
"""
@spec opts_reject(any, any) :: {:ok, opts} | {:error, error}
def opts_reject(opts, fun_pred) when is_function(fun_pred,1) do
with {:ok, opts} <- opts |> opts_normalise do
opts = opts
|> Enum.reject(fun_pred)
{:ok, opts}
else
{:error, _} = result -> result
end
end
def opts_reject(_opts, fun_pred) do
new_error_result(m: "expected valid tuple predicate", v: fun_pred)
end
@doc ~S"""
`opts_reject!/2` calls `opts_reject/2` and if the result is `{:ok, opts}` returns `opts`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_reject!(&(&1))
[]
iex> [a: 1, b: 2, c: 3] |> opts_reject!(
...> fn
...> {:a,_} -> true
...> _ -> false
...> end)
[b: 2, c: 3]
iex> %{a: 1, b: 2, c: 3} |> opts_reject!(
...> fn
...> {:a,_} -> false
...> _ -> true
...> end)
[a: 1]
iex> [a: 1, b: 2, c: 3] |> opts_reject!(:not_a_function)
** (ArgumentError) expected valid tuple predicate; got: :not_a_function
iex> :not_opts |> opts_reject!(&(&1))
** (ArgumentError) expected valid derivable opts; got: :not_opts
"""
@spec opts_reject!(any, any) :: opts | no_return
def opts_reject!(opts, dict) do
with {:ok, opts} <- opts |> opts_reject(dict) do
opts
else
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_predicate/2` takes a *derivable opts*, together with a *tuple predicate* and returns `{:ok, opts}` if all the 2tuples pass the *tuple predicate*.
If any of the *opts* fail the *tuple predicate*, {:error, error} is returned where `error` will be a `KeyError` whose `key` field contains all the keys that failed.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_predicate(&(&1))
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_predicate(fn {_k,v} -> v |> is_integer end)
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_predicate(
...> fn
...> {:a,_} -> true
...> _ -> false
...> end)
{:error, %KeyError{key: [:b, :c], term: [a: 1, b: 2, c: 3]}}
iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_predicate(:not_a_function)
...> match?(%ArgumentError{message: "expected valid tuple predicate; got: :not_a_function"}, error)
true
iex> {:error, error} = :not_opts |> opts_predicate(&(&1))
...> match?(%ArgumentError{message: "expected valid derivable opts; got: :not_opts"}, error)
true
"""
@spec opts_predicate(any, any) :: {:ok, opts} | {:error, error}
def opts_predicate(opts, fun_pred) when is_function(fun_pred,1) do
with {:ok, norm_opts} <- opts |> opts_normalise do
norm_opts
|> Enum.split_with(fun_pred)
|> case do
{pass_opts, []} -> {:ok, pass_opts}
{_pass_opts, fail_opts} ->
# build a KeyError with failing keys
fail_keys = fail_opts |> Keyword.keys |> Enum.uniq
{:error, %KeyError{key: fail_keys, term: opts}}
end
else
{:error, _} = result -> result
end
end
def opts_predicate(_opts, fun_pred) do
new_error_result(m: "expected valid tuple predicate", v: fun_pred)
end
@doc ~S"""
`opts_predicate!/2` calls `opts_predicate/2` and if the result is `{:ok, opts}` returns `opts`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_predicate(&(&1))
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_predicate(fn {_k,v} -> v |> is_integer end)
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_predicate(
...> fn
...> {:a,_} -> true
...> _ -> false
...> end)
{:error, %KeyError{key: [:b, :c], term: [a: 1, b: 2, c: 3]}}
iex> [a: 1, b: 2, c: 3] |> opts_predicate!(:not_a_function)
** (ArgumentError) expected valid tuple predicate; got: :not_a_function
iex> :not_opts |> opts_predicate!(&(&1))
** (ArgumentError) expected valid derivable opts; got: :not_opts
"""
@spec opts_predicate!(any, any) :: opts | no_return
def opts_predicate!(opts, dict) do
with {:ok, opts} <- opts |> opts_predicate(dict) do
opts
else
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_filter_keys/2` takes a *derivable opts* and a *key spec* and returns `{:ok, opts}` where `opts` has all keys from the original *derivable opts* that appear in the *key spec*.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_filter_keys([:a, :b, :c])
{:ok, [a: 1, b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_filter_keys([b: :want_b, c: :and_c])
{:ok, [b: 2, c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_filter_keys(%{a: 42, b: nil})
{:ok, [a: 1, b: 2]}
iex> [a: 1, b: 2, c: 3] |> opts_filter_keys(:not_a_key_spec)
{:error, %ArgumentError{message: "expected enum; got: :not_a_key_spec"}}
iex> :not_opts |> opts_filter_keys([:a, :b, :c])
{:error, %ArgumentError{message: "expected valid derivable opts; got: :not_opts"}}
"""
@spec opts_filter_keys(any, any) :: {:ok, opts} | {:error, error}
def opts_filter_keys(opts, keys)
def opts_filter_keys(opts, keys) do
with {:ok, filter_keys} <- keys |> normalise_key_spec do
filter_map = filter_keys |> Map.new(fn k -> {k, nil} end)
filter_pred = fn {k,_v} -> filter_map |> Map.has_key?(k) end
with {:ok, _filter_opts} = result <- opts |> opts_filter(filter_pred) do
result
else
{:error, _} = result -> result
end
else
{:error, _} = result -> result
end
end
@doc ~S"""
`opts_filter_keys!/2` calls `opts_filter_keys/2` and if the result is `{:ok, opts}`, returns `opts`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_filter_keys!([:a, :b, :c])
[a: 1, b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_filter_keys!([b: :want_b, c: :and_c])
[b: 2, c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_filter_keys!(%{a: 42, b: nil})
[a: 1, b: 2]
iex> [a: 1, b: 2, c: 3] |> opts_filter_keys!(:not_a_key_spec)
** (ArgumentError) expected enum; got: :not_a_key_spec
iex> :not_opts |> opts_filter_keys!([:a, :b, :c])
** (ArgumentError) expected valid derivable opts; got: :not_opts
"""
@spec opts_filter_keys!(any, any) :: opts | no_return
def opts_filter_keys!(opts, keys) do
case opts_filter_keys(opts, keys) do
{:ok, opts} -> opts
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_reject_keys/2` takes a *derivable opts* and a *key spec* and returns `{:ok, opts}` where `opts` has all keys from the original *derivable opts* that **do not** appear in the *key spec*.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_reject_keys([:a, :b, :c])
{:ok, []}
iex> [a: 1, b: 2, c: 3] |> opts_reject_keys([b: "b value", c: :dont_want_this_key])
{:ok, [a: 1]}
iex> [a: 1, b: 2, c: 3] |> opts_reject_keys(%{a: nil, b: nil})
{:ok, [c: 3]}
iex> [a: 1, b: 2, c: 3] |> opts_reject_keys(:not_a_key_spec)
{:error, %ArgumentError{message: "expected enum; got: :not_a_key_spec"}}
iex> :not_opts |> opts_reject_keys([:a, :b, :c])
{:error, %ArgumentError{message: "expected valid derivable opts; got: :not_opts"}}
"""
@spec opts_reject_keys(any, any) :: {:ok, opts} | {:error, error}
def opts_reject_keys(opts, keys)
def opts_reject_keys(opts, keys) do
with {:ok, reject_keys} <- keys |> normalise_key_spec do
reject_map = reject_keys |> Map.new(fn k -> {k, nil} end)
reject_pred = fn {k,_v} -> reject_map |> Map.has_key?(k) end
with {:ok, _reject_opts} = result <- opts |> opts_reject(reject_pred) do
result
else
{:error, _} = result -> result
end
else
{:error, _} = result -> result
end
end
@doc ~S"""
`opts_reject_keys!/2` calls `opts_reject_keys/2` and if the result is `{:ok, opts}`, returns `opts`.
## Examples
iex> [a: 1, b: 2, c: 3] |> opts_reject_keys!([:a, :b, :c])
[]
iex> [a: 1, b: 2, c: 3] |> opts_reject_keys!([b: "b value", c: :dont_want_this_key])
[a: 1]
iex> [a: 1, b: 2, c: 3] |> opts_reject_keys!(%{a: nil, b: nil})
[c: 3]
iex> [a: 1, b: 2, c: 3] |> opts_reject_keys!(:not_a_key_spec)
** (ArgumentError) expected enum; got: :not_a_key_spec
iex> :not_opts |> opts_reject_keys!([:a, :b, :c])
** (ArgumentError) expected valid derivable opts; got: :not_opts
"""
@spec opts_reject_keys!(any, any) :: opts | no_return
def opts_reject_keys!(opts, keys) do
case opts_reject_keys(opts, keys) do
{:ok, opts} -> opts
{:error, error} -> raise error
end
end
@doc ~S"""
`opts_fetch_key_values/2` takes a *derivable opts* and a *key* and returns the values of the *key* as `{:ok, values}` where `values` will be a list.
One of more indices can be provided to select the values at specific indices; the default is to return all values from `Keyword.get_values/2`.
Note indices *must* be relative to the result of `Keyword.get_values/2` **not** the indices of the original *opts*
Values are returned in the same order as the indices. Indices may be repeated. Indices are validated; asking for an unknown/impossible index will cause an error.
## Examples
The default is to return *all* the values for a *key* i.e same as `Keyword.get_values/2`:
iex> [a: 1, b: 2, c: 3] |> opts_fetch_key_values(:a)
{:ok, [1]}
This examples show multiple values being returned:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values(:a)
{:ok, [11, 12, 13]}
Here the last value for the key is returned:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values(:a, -1)
{:ok, [13]}
Here only the first value is wanted:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values(:a, 0)
{:ok, [11]}
Values at different indices:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values(:a, [1,-1])
{:ok, [12, 13]}
Note order of the values is same order as the indices:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values(:a, [-2,0,-1])
{:ok, [12, 11, 13]}
The same index/indices can be repeated:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values(:a, [-2,0,-2,-1,0])
{:ok, [12, 11, 12, 13, 11]}
Indices are validated:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values(:a, 99)
{:error, %ArgumentError{message: "index invalid; got: 99"}}
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values(:a, :not_an_index)
{:error, %ArgumentError{message: "index invalid; got: :not_an_index"}}
"""
@spec opts_fetch_key_values(any, any) :: {:ok, opts} | {:error, error}
def opts_fetch_key_values(opts, key, indicies \\ nil)
def opts_fetch_key_values(opts, key, nil) do
with {:ok, norm_opts} <- opts |> opts_normalise,
true <- norm_opts |> Keyword.has_key?(key) do
{:ok, norm_opts |> Keyword.get_values(key)}
else
false -> new_key_error_result(key, opts)
{:error, _} = result -> result
end
end
def opts_fetch_key_values(opts, key, indices) do
with {:ok, norm_opts} <- opts |> opts_normalise,
true <- norm_opts |> Keyword.has_key?(key) do
key_values = norm_opts |> Keyword.get_values(key)
with {:ok, indices} <- key_values |> opts_indices_validate(indices) do
indices
|> List.wrap
|> Enum.reduce({[],[]},
fn index, {known_values,missing_indices} ->
with {:ok, value} <- key_values |> Enum.fetch(index) do
{[value | known_values], missing_indices}
else
:error -> {known_values, [index | missing_indices]}
end
end)
|> case do
{known_values, []} -> {:ok, known_values |> Enum.reverse}
{_known_values, missing_indices} ->
new_key_error_result(missing_indices, key_values)
end
else
{:error, _} = result -> result
end
else
false -> new_key_error_result(key, opts)
{:error, _} = result -> result
end
end
@doc ~S"""
`opts_fetch_key_values!/2` takes a *derivable opts* and a *key* and returns the values of the *key* as `{:ok, values}`.
One of more indices can be provided to select the values at specific indices; the default is to return all values from `Keyword.get_values/2`.
Note indices *must* be relative to the result of `Keyword.get_values/2` **not** the indices of the original *opts*
Values are returned in the order they are given in the indices. Indices may be repeated.
## Examples
The default is to return *all* the values for a *key*:
iex> [a: 1, b: 2, c: 3] |> opts_fetch_key_values!(:a)
[1]
This examples show multiple values being returned:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values!(:a)
[11, 12, 13]
Here the last value for the key is returned:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values!(:a, -1)
[13]
Here the first value is wanted:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values!(:a, 0)
[11]
Values at different indices:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values!(:a, [1,-1])
[12, 13]
Note order of the values is same as order of the indices
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values!(:a, [-2,0,-1])
[12, 11, 13]
The same index/indices can be requested more than once:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values!(:a, [-2,0,-2,-1,0])
[12, 11, 12, 13, 11]
Indices are validated:
iex> [a: 11, b: 2, a: 12, c: 3, a: 13] |> opts_fetch_key_values!(:a, :not_an_index)
** (ArgumentError) index invalid; got: :not_an_index
"""
@spec opts_fetch_key_values!(any, any, any) :: list | no_return
def opts_fetch_key_values!(opts, key, indices \\ nil)
def opts_fetch_key_values!(opts, key, indices) do
case opts_fetch_key_values(opts, key, indices) do
{:ok, values} -> values
{:error, error} -> raise error
end
end
@doc ~S"""
`canon_keys!/2` takes a *key list* together with a lookup dictionary and replaces each key with its canonical value from the dictionary. Unknown keys raise a `KeyError`.
## Examples
iex> [:a, :b, :c] |> canon_keys!(%{a: 1, b: 2, c: 3})
[1,2,3]
iex> [:x] |> canon_keys!(%{a: 1, b: 2, c: 3})
** (KeyError) key :x not found in: %{a: 1, b: 2, c: 3}
"""
@spec canon_keys!(alias_keys, dict) :: alias_keys | no_return
def canon_keys!(keys, dict) when is_map(dict) do
keys |> Enum.map(fn k -> dict |> Map.fetch!(k) end)
end
@doc ~S"""
`canon_keys/2` takes a *key list* together with a lookup dictionary and replaces each key with its canonical value from the dictionary, returning `{:ok, canon_keys}`.
If there are any unknown keys, `{:error, {canon_known_keys, unknown_keys}}` will be returned.
## Examples
iex> [:a, :b, :c] |> canon_keys(%{a: 1, b: 2, c: 3})
{:ok, [1,2,3]}
iex> [:a, :x, :b, :y, :c, :z] |> canon_keys(%{a: 1, b: 2, c: 3})
{:error, {[1, 2, 3], [:x, :y, :z]}}
"""
@spec canon_keys(alias_keys, dict) :: {:ok, alias_keys} | {:error, error}
def canon_keys(keys, dict) when is_map(dict) do
keys
# split into known and unknown keys
|> Enum.split_with(fn k -> Map.has_key?(dict, k) end)
|> case do
# no unknown keys
{known_keys, []} ->
{:ok, known_keys |> canon_keys!(dict)}
{known_keys, unknown_keys} ->
{:error, {known_keys |> canon_keys!(dict), unknown_keys}}
end
end
@doc ~S"""
`canonical_keys/2` takes a *key list* and *key alias dict* and replaces each key with its canonical value from the dictionary, returning `{:ok, canonical_keys}`.
If there are any unknown keys `{:error, error}`, where `error` is a `KeyError`, will be returned.
## Examples
iex> [:a, :b, :c] |> canonical_keys(%{a: :p, b: :q, c: :r})
{:ok, [:p,:q,:r]}
iex> [:a, :b, :c] |> canonical_keys(%{a: 1, b: 2, c: 3})
{:ok, [1,2,3]}
iex> [:a, :x, :b, :y, :c, :z] |> canonical_keys(%{a: 1, b: 2, c: 3})
{:error, %KeyError{key: [:x, :y, :z], term: %{a: 1, b: 2, c: 3}}}
"""
@spec canonical_keys(alias_keys, any) :: {:ok, alias_keys} | {:error, error}
def canonical_keys(keys, dict) do
with {:ok, keys} <- keys |> normalise_key_list,
{:ok, dict} <- dict |> normalise_key_dict do
keys
|> Enum.reject(fn k -> Map.has_key?(dict, k) end)
|> case do
# no unknown keys
[] ->
canon_keys = keys |> Enum.map(fn k -> dict |> Map.get(k) end)
{:ok, canon_keys}
unknown_keys ->
unknown_keys |> new_key_error_result(dict)
end
else
{:error, _} = result -> result
end
end
@doc ~S"""
`canonical_keys!/2` calls `canonical_keys/2` and if the result is `{:ok, canonical_keys}` returns `canonical_keys`.
## Examples
iex> [:a, :b, :c] |> canonical_keys!(%{a: :p, b: :q, c: :r})
[:p,:q,:r]
iex> [:a, :b, :c] |> canonical_keys!(%{a: 1, b: 2, c: 3})
[1,2,3]
iex> [:a, :x, :b, :y, :c, :z] |> canonical_keys!(%{a: 1, b: 2, c: 3})
** (KeyError) key [:x, :y, :z] not found in: %{a: 1, b: 2, c: 3}
"""
@spec canonical_keys!(alias_keys, dict) :: alias_keys | no_return
def canonical_keys!(keys, dict) do
with {:ok, keys} <- keys |> canonical_keys(dict) do
keys
else
{:error, error} -> raise error
end
end
@doc ~S"""
`canonical_key/2` takes a key together with a *key dict* and replaces the key with its canonical value from the dictionary, returning `{:ok, canonical_key}`.
If the key is unknown, `{:error, error}`, `error` is a `KeyError`, will be returned.
## Examples
iex> :b |> canonical_key(%{a: :p, b: :q, c: :r})
{:ok, :q}
iex> :a |> canonical_key(%{a: 1, b: 2, c: 3})
{:ok, 1}
iex> :x |> canonical_key(%{a: 1, b: 2, c: 3})
{:error, %KeyError{key: :x, term: %{a: 1, b: 2, c: 3}}}
"""
@spec canonical_key(alias_key, any) :: {:ok, alias_key} | {:error, error}
def canonical_key(key, dict) do
with {:ok, dict} <- dict |> normalise_key_dict,
{:ok, keys} <- [key] |> canonical_keys(dict) do
{:ok, keys |> hd}
else
{:error, %KeyError{} = error} -> {:error, error |> struct!(key: key)}
{:error, _} = result -> result
end
end
@doc ~S"""
`canonical_key!/2` calls `canonical_key/2` and if the result is `{:ok, canonical_key}` returns `canonical_key`.
## Examples
iex> :a |> canonical_key!(%{a: 1, b: 2, c: 3})
1
iex> :b |> canonical_key!(%{a: :p, b: :q, c: :r})
:q
iex> :x |> canonical_key!(%{a: 1, b: 2, c: 3})
** (KeyError) key :x not found in: %{a: 1, b: 2, c: 3}
"""
@spec canonical_key!(alias_key, dict) :: alias_key | no_return
def canonical_key!(key, dict) do
with {:ok, key} <- key |> canonical_key(dict) do
key
else
{:error, error} -> raise error
end
end
@doc ~S"""
`maybe_canon_keys/2` takes a *key list* together with a lookup dictionary and, if the key is in the dictionary, replaces it with its value. Unknown keys are passed through unchanged.
## Examples
iex> [:a, :b, :c] |> maybe_canon_keys(%{a: 1, b: 2, c: 3})
[1, 2, 3]
iex> [:x, :a] |> maybe_canon_keys(%{a: 1, b: 2, c: 3})
[:x, 1]
"""
@spec maybe_canon_keys(alias_keys, dict) :: alias_keys
def maybe_canon_keys(keys, dict) when is_map(dict) do
keys
|> Enum.map(fn k ->
case dict |> Map.has_key?(k) do
true -> dict |> Map.fetch!(k)
_ -> k
end
end)
end
@doc ~S"""
`list_wrap_flat_just/1` wraps a value (if not already a list), flattens and removes `nils` at the *first / top* level.
## Examples
iex> [{:a, 1}, nil, [{:b1, 12}, nil, {:b2, [nil, 22, nil]}], nil, {:c, 3}] |> list_wrap_flat_just
[a: 1, b1: 12, b2: [nil, 22, nil], c: 3]
iex> [[[nil, 42, nil]]] |> list_wrap_flat_just
[42]
"""
@spec list_wrap_flat_just(any) :: [any]
def list_wrap_flat_just(value) do
value
|> List.wrap
|> List.flatten
|> Enum.reject(&is_nil/1)
end
@doc ~S"""
`list_wrap_flat_just_uniq/1` wraps a value (if not already a list), flattens, removes `nils` at
the *first / top* level, and deletes duplicates (using `Enum.uniq/1`)
## Examples
iex> [{:a, 1}, nil, [{:b1, 12}, nil, {:b2, [nil, 22, nil]}], nil, {:c, 3}, {:a, 1}, {:b1, 12}] |> list_wrap_flat_just_uniq
[a: 1, b1: 12, b2: [nil, 22, nil], c: 3]
iex> [nil, [42, [42, 42, nil]], 42] |> list_wrap_flat_just_uniq
[42]
"""
@spec list_wrap_flat_just_uniq(any) :: [any]
def list_wrap_flat_just_uniq(value) do
value
|> List.wrap
|> List.flatten
|> Enum.reject(&is_nil/1)
|> Enum.uniq
end
defp normalise_error_message(value)
defp normalise_error_message(value) when is_binary(value) do
value
end
defp normalise_error_message(value) when is_atom(value) do
value |> to_string
end
defp normalise_error_message(value) do
value |> inspect
end
defp normalise_error_value(value)
defp normalise_error_value(value) do
"got: #{value |> inspect}"
end
defp new_error_result(opts)
defp new_error_result(opts) do
message = [
m: &normalise_error_message/1,
v: &normalise_error_value/1,
]
|> Enum.reduce([],fn {k,fun}, texts ->
opts
|> Keyword.has_key?(k)
|> case do
true ->
text = opts |> Keyword.get(k) |> fun.()
[text | texts]
_ -> texts
end
end)
|> Enum.reverse
|> Enum.join("; ")
{:error, %ArgumentError{message: message}}
end
defp new_key_error(values, term) do
cond do
Keyword.keyword?(values) -> values |> Keyword.keys
is_list(values) -> values
true -> raise ArgumentError, message: "expected opts or keys; got: #{inspect values}"
end
|> Enum.uniq
|> case do
[key] -> %KeyError{key: key, term: term}
keys -> %KeyError{key: keys, term: term}
end
end
defp new_key_error_result(values, term) do
{:error, new_key_error(values, term)}
end
end