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}}}

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}}}

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]}"}}

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}

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]

opts_drop/3 take a derivable opts, key and delete all occurences of the key returning {ok, opts}.

It essentially wraps Keyword.delete/2.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_drop(:a)
{:ok, [b: 2, c: 3]}

iex> [a: 11, b: 21, c: 31, a: 12, b: 22, c: 32, a: 13, b: 23, c: 33] |> opts_drop([:a, :c])
{:ok, [b: 21, b: 22, b: 23]}

iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_drop([:b, "a"])
...> error |> Exception.message
"bad key \"a\" for: [:b, \"a\"]"

iex> {:error, error} = 42 |> opts_drop(:a)
...> error |> Exception.message
"opts not derivable, got: 42"

iex> {:error, error} = [{:a, 1}, {:b, 2}, {"c", 3}] |> opts_drop(:a)
...> error |> Exception.message
"opts not derivable, got: [{:a, 1}, {:b, 2}, {\"c\", 3}]"

opts_fetch/2 take a derivable opts and key and and returns the last value for the key (or default) as {:ok, value}.

Note this is different to Keyword.fetch/2 that returns the first value.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_fetch(:a)
{:ok, 1}

iex> [a: 11, b: 21, c: 31, a: 12, b: 22, c: 32, a: 13, b: 23, c: 33] |> opts_fetch(:c)
{:ok, 33}

iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_fetch(:d)
...> error |> Exception.message
"key :d not found in: [a: 1, b: 2, c: 3]"

iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_fetch("a")
...> error |> Exception.message
"key invalid, got: a"

iex> {:error, error} = 42 |> opts_fetch(:a)
...> error |> Exception.message
"opts not derivable, got: 42"

iex> {:error, error} = [{:a, 1}, {:b, 2}, {"c", 3}] |> opts_fetch(:a)
...> error |> Exception.message
"opts not derivable, got: [{:a, 1}, {:b, 2}, {\"c\", 3}]"

opts_get/3 take a derivable opts, key and default and returns the last value for the key (or default) as {:ok, value_or_default}.

Note this is different to Keyword.get/3 that returns the first value.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_get(:a)
{:ok, 1}

iex> [a: 11, b: 21, c: 31, a: 12, b: 22, c: 32, a: 13, b: 23, c: 33] |> opts_get(:c)
{:ok, 33}

iex> [a: 1, b: 2, c: 3] |> opts_get(:d, 4)
{:ok, 4}

iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_get("a")
...> error |> Exception.message
"key invalid, got: a"

iex> {:error, error} = 42 |> opts_get(:a)
...> error |> Exception.message
"opts not derivable, got: 42"

iex> {:error, error} = [{:a, 1}, {:b, 2}, {"c", 3}] |> opts_get(:a)
...> error |> Exception.message
"opts not derivable, got: [{:a, 1}, {:b, 2}, {\"c\", 3}]"

opts_get_values/3 take a derivable opts, key and default and, if the derived opts has the key, returns the values (Keyword.get_values/21).

Otherwise the “listified” (List.wrap/1) default is returned.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_get_values(:a)
{:ok, [1]}

iex> [a: 11, b: 21, c: 31, a: 12, b: 22, c: 32, a: 13, b: 23, c: 33] |> opts_get_values(:c)
{:ok, [31, 32, 33]}

iex> [a: 1, b: 2, c: 3] |> opts_get_values(:d, 4)
{:ok, [4]}

iex> [a: 1, b: 2, c: 3] |> opts_get_values(:d, [41, 42, 43])
{:ok, [41, 42, 43]}

iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_get_values("a")
...> error |> Exception.message
"key invalid, got: a"

iex> {:error, error} = 42 |> opts_get_values(:a)
...> error |> Exception.message
"opts not derivable, got: 42"

opts_maybe_canonical_keys/2 takes a derivable opts, together with a key alias dict.

If an opts key exists in the dictionary, it is replaced with its (canonical) value. Otherwise the key is unchanged.

{:ok, opts} is returned.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_maybe_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_maybe_canonical_keys(%{a: :x, b: :y, c: :z})
{:ok, [x: 11, p: 1, y: 22, q: 2, z: 33, r: 3]}

opts_merge/ takes one or more derivable opts, merges them and returns {:ok, opts}.

Any other argument causes {:error, error} to be returned.

Examples

iex> [] |> opts_merge
{:ok, []}

iex> [a: 1, b: 2, c: 3] |> opts_merge
{:ok, [a: 1, b: 2, c: 3]}

iex> [[a: 1], [b: 2], [c: 3]] |> opts_merge
{:ok, [a: 1, b: 2, c: 3]}

iex> %{a: 1, b: 2, c: 3} |> opts_merge
{:ok, [a: 1, b: 2, c: 3]}

iex> [%{a: 1, b: 2, c: 3}, [d: 4]] |> opts_merge
{:ok, [a: 1, b: 2, c: 3, d: 4]}

iex> {:error, error} = [[d: 4], %{"a" => 1, :b => 2, :c => 3}] |> opts_merge
...> error |> Exception.message
"bad key \"a\" for: %{:b => 2, :c => 3, \"a\" => 1}"

iex> {:error, error} = 42 |> opts_merge
...> error |> Exception.message
"opts not derivable, got: 42"

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> {:error, error} = %{"a" => 1, :b => 2, :c => 3} |> opts_normalise
...> error |> Exception.message
"bad key \"a\" for: %{:b => 2, :c => 3, \"a\" => 1}"

iex> {:error, error} = 42 |> opts_normalise
...> error |> Exception.message
"opts not derivable, got: 42"

iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_normalise
{:ok, [a: nil, b: [:b1], c: [:c1, :c2, :c3]]}

opts_put/3 take a derivable opts, key and a value and appends the {key,value} tuple returnsing {:ok, opts}.

Note this is different to Keyword.put/2 which prepends the new {key,value} tuple and drops all the other for the same key.

Examples

iex> [a: 11, b: 2, c: 3] |> opts_put(:a, 12)
{:ok, [a: 11, b: 2, c: 3, a: 12]}

iex> [a: 1, b: 2, c: 3] |> opts_put(:d, 4)
{:ok, [a: 1, b: 2, c: 3, d: 4]}

iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_put("a", 99)
...> error |> Exception.message
"key invalid, got: a"

iex> {:error, error} = 42 |> opts_put(:a, nil)
...> error |> Exception.message
"opts not derivable, got: 42"

iex> {:error, error} = [{:a, 1}, {:b, 2}, {"c", 3}] |> opts_put(:a, nil)
...> error |> Exception.message
"opts not derivable, got: [{:a, 1}, {:b, 2}, {\"c\", 3}]"

opts_put_new/3 take a derivable opts, key and a value.

If the key already exsists in the derived opts, they are returned unchanged as {:ok, opts}.

Otherwise opts_put/3 is called to append the new {key,value}, again returning {:ok, opts}.

Examples

iex> [a: 11, b: 2, c: 3] |> opts_put_new(:a, 12)
{:ok, [a: 11, b: 2, c: 3]}

iex> [a: 1, b: 2, c: 3] |> opts_put_new(:d, 4)
{:ok, [a: 1, b: 2, c: 3, d: 4]}

iex> {:error, error} = [a: 1, b: 2, c: 3] |> opts_put_new("a", 99)
...> error |> Exception.message
"key invalid, got: a"

iex> {:error, error} = 42 |> opts_put_new(:a)
...> error |> Exception.message
"opts not derivable, got: 42"

iex> {:error, error} = [{:a, 1}, {:b, 2}, {"c", 3}] |> opts_put_new(:a)
...> error |> Exception.message
"opts not derivable, got: [{:a, 1}, {:b, 2}, {\"c\", 3}]"

opts_reduce/3 take a derivable opts, realises the derived opts, and calls Keyword.new/1 to take the last {key, value} tuple for the same key, returning {:ok, reduced_opts}.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_reduce
{:ok, [a: 1, b: 2, c: 3]}

iex> {:ok, opts} = %{a: 1, b: 2, c: 3} |> opts_reduce
...> opts |> Enum.sort
[a: 1, b: 2, c: 3]

iex> [a: 11, b: 21, c: 31, a: 12, b: 22, c: 32, a: 13, b: 23, c: 33] |> opts_reduce
{:ok, [a: 13, b: 23, c: 33]}

iex> {:error, error} = 42 |> opts_reduce
...> error |> Exception.message
"opts not derivable, got: 42"

iex> {:error, error} = [{:a, 1}, {:b, 2}, {"c", 3}] |> opts_reduce
...> error |> Exception.message
"opts not derivable, got: [{:a, 1}, {:b, 2}, {\"c\", 3}]"

opts_take_canonical_keys/2 takes a derivable opts, together with a key alias dict.

It first calls opts_maybe_canonical_keys/2 to convert all known keys to their canonical values, and then takes only the canonical keys returning {:ok, opts}.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_take_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_take_canonical_keys(%{a: :x, b: :y, c: :z})
{:ok, [x: 11, y: 22, z: 33]}

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: "opts invalid, got: %{a: 1, b: 2, c: 3}"}}

iex> %{"a" => 1, :b => 2, :c => 3} |> opts_validate
{:error, %ArgumentError{message: "opts invalid, got: %{:b => 2, :c => 3, \"a\" => 1}"}}

iex> 42 |> opts_validate
{:error, %ArgumentError{message: "opts invalid, got: 42"}}

iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opts_validate
{:ok, [a: nil, b: [:b1], c: [:c1, :c2, :c3]]}

opzioni_flatten/1 takes a value, calls opzioni_normalise/1 and then merges all the individual opts into a single opts.

Examples

iex> [] |> opzioni_flatten
{:ok, []}

iex> [a: 1, b: 2, c: 3] |> opzioni_flatten
{:ok, [a: 1, b: 2, c: 3]}

iex> [[a: 1], [b: 2], [c: 3]] |> opzioni_flatten
{:ok, [a: 1, b: 2, c: 3]}

iex> [[a: 1], [[b: 2], [c: 3]]] |> opzioni_flatten
{:ok, [a: 1, b: 2, c: 3]}

iex> %{a: 1, b: 2, c: 3} |> opzioni_flatten
{:ok, [a: 1, b: 2, c: 3]}

iex> {:ok, opts} = [[a: 1, b: 2, c: 3], %{x: 10, y: 11, z: 12}] |> opzioni_flatten
...> opts |> Enum.sort
[a: 1, b: 2, c: 3, x: 10, y: 11, z: 12]

iex> {:error, error} = %{"a" => 1, :b => 2, :c => 3} |> opzioni_flatten
...> error |> Exception.message
"bad key \"a\" for: %{:b => 2, :c => 3, \"a\" => 1}"

iex> {:error, error} = 42 |> opzioni_flatten
...> error |> Exception.message
"opzioni invalid, got: 42"

iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opzioni_flatten
{:ok, [a: nil, b: [:b1], c: [:c1, :c2, :c3]]}

opzioni_merge/ takes one or more opzioni, normalises each one and merges them to return {:ok, opzioni}.

Empty opts are removed.

Any other argument causes {:error, error} to be returned.

Examples

iex> [] |> opzioni_merge
{:ok, []}

iex> [a: 1, b: 2, c: 3] |> opzioni_merge
{:ok, [[a: 1, b: 2, c: 3]]}

iex> [[a: 1], [b: 2], [c: 3]] |> opzioni_merge
{:ok, [[a: 1], [b: 2], [c: 3]]}

iex> [[[a: 1], [b: 2]], [c: 3], [[d: 4]]] |> opzioni_merge
{:ok, [[a: 1], [b: 2], [c: 3], [d: 4]]}

iex> [[a: 1], [], [b: 2], [], [c: 3]] |> opzioni_merge
{:ok, [[a: 1], [b: 2], [c: 3]]}

iex> %{a: 1, b: 2, c: 3} |> opzioni_merge
{:ok, [[a: 1, b: 2, c: 3]]}

iex> [%{a: 1, b: 2, c: 3}, [d: 4]] |> opzioni_merge
{:ok, [[a: 1, b: 2, c: 3], [d: 4]]}

iex> {:error, error} = [[d: 4], %{"a" => 1, :b => 2, :c => 3}] |> opzioni_merge
...> error |> Exception.message
"bad key \"a\" for: %{:b => 2, :c => 3, \"a\" => 1}"

iex> {:error, error} = 42 |> opzioni_merge
...> error |> Exception.message
"opzioni invalid, got: 42"

opzioni_normalise/1 takes a value tries to normalise it into an opzioni, returning {:ok, opzioni}.

Any other argument causes {:error, error} to be returned.

Examples

iex> [] |> opzioni_normalise
{:ok, []}

iex> [a: 1, b: 2, c: 3] |> opzioni_normalise
{:ok, [[a: 1, b: 2, c: 3]]}

iex> %{a: 1, b: 2, c: 3} |> opzioni_normalise
{:ok, [[a: 1, b: 2, c: 3]]}

iex> [ [a: 1, b: 2, c: 3], %{x: 10, y: 11, z: 12}] |> opzioni_normalise
{:ok, [[a: 1, b: 2, c: 3], [x: 10, y: 11, z: 12]]}

iex> {:error, error} = %{"a" => 1, :b => 2, :c => 3} |> opzioni_normalise
...> error |> Exception.message
"bad key \"a\" for: %{:b => 2, :c => 3, \"a\" => 1}"

iex> {:error, error} = 42 |> opzioni_normalise
...> error |> Exception.message
"opzioni invalid, got: 42"

iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> opzioni_normalise
{:ok, [[a: nil, b: [:b1], c: [:c1, :c2, :c3]]]}

opzioni_validate/1 takes a value and validates it is an opzioni, returning {:ok, opzioni}.

Any other argument causes {:error, error} to be returned.

Examples

iex> [] |> opzioni_validate
{:ok, []}

iex> [[a: 1, b: 2, c: 3]] |> opzioni_validate
{:ok, [[a: 1, b: 2, c: 3]]}

iex> {:error, error} = [a: 1, b: 2, c: 3] |> opzioni_validate
...> error |> Exception.message
"opts invalid, got: {:a, 1}"

iex> {:error, error} = %{a: 1, b: 2, c: 3} |> opzioni_validate
...> error |> Exception.message
"opzioni invalid, got: %{a: 1, b: 2, c: 3}"

iex> {:error, error} = [[a: 1, b: 2, c: 3], %{x: 10, y: 11, z: 12}] |> opzioni_validate
...> error |> Exception.message
"opts invalid, got: %{x: 10, y: 11, z: 12}"

iex> {:error, error} = 42 |> opzioni_validate
...> error |> Exception.message
"opzioni invalid, got: 42"