View Source Kword (Kword v0.1.0)
A library of keyword-list handling functions to complement Keyword
Use Case
Elixir keyword lists as a common representation of optional arguments to functions feels a bit clunky. You may find yourself writing something like:
def update_user_details(opts \\ []) do
opts = Keyword.validate!(opts, [:name, :email, role: :guest, gender: :unspecified])
name = Keyword.fetch!(opts, :name)
email = Keyword.fetch!(opts, :email)
...
end
The intent of Kword is to enable list matching (there's an order of parameters in the second argument) and to write instead:
def update_user_details(opts \\ []) do
[name, email | _rest] = Kword.extract!(opts, [:name, :email, role: :guest, gender: :unspecified])
...
end
If you want to ensure required parameters are in fact supplied, use extract
or extract!
.
If you don't want to allow parameters that aren't specified, use extract_exhaustive
or extract_exhaustive!
.
And if you just want to pluck values out of a keyword list in the order specified, use extract_permissive
which will default parameters to nil that have no default specified.
Installation
If available in Hex, the package can be installed
by adding kword
to your list of dependencies in mix.exs
:
def deps do
[
{:kword, "~> 0.1.0"}
]
end
Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/kword.
Summary
Functions
Like Keyword.validate/2
except in place of a keyword list in the return value, it returns a list
of values in the order they appear in the second argument.
Like Keyword.validate!/2
except instead of returning a keyword list, it returns a list of values
in the order they appear in the second argument.
Like extract/2
except any keys supplied in opts that are not declared in params result in an error tuple.
Like extract_exhaustive/2
but raises an ArgumentError
with the first key that was unexpected,
Map over params
, each element of which is either an atom or a 2-tuple {atom, default}, getting
the value of the first occurrence of the atom key in the keyword list opts
, and if not found the
default is used, or nil if there is no default.
Functions
Like Keyword.validate/2
except in place of a keyword list in the return value, it returns a list
of values in the order they appear in the second argument.
Like Keyword.validate!/2
except instead of returning a keyword list, it returns a list of values
in the order they appear in the second argument.
Examples
iex> Kword.extract!([x: 1, y: 2, z: 3, w: 4], [:w, x: 10, a: 7])
[4, 1, 7]
iex> Kword.extract!([x: 1, y: 2, z: 3], [:w, x: 10, a: 7])
** (ArgumentError) Missing key :w
Like extract/2
except any keys supplied in opts that are not declared in params result in an error tuple.
Examples
iex> Kword.extract_exhaustive([x: 1], [:x, y: 7])
{:ok, [1, 7]}
iex> Kword.extract_exhaustive([x: 1, z: 3], [:x, y: 7])
{:error, {:unexpected, :z}}
Like extract_exhaustive/2
but raises an ArgumentError
with the first key that was unexpected,
Examples
iex> Kword.extract_exhaustive!([x: 1], [:x, y: 7])
[1, 7]
iex> Kword.extract_exhaustive!([x: 1, z: 3], [:x, y: 7])
** (ArgumentError) Unexpected key :z
Map over params
, each element of which is either an atom or a 2-tuple {atom, default}, getting
the value of the first occurrence of the atom key in the keyword list opts
, and if not found the
default is used, or nil if there is no default.
Examples
iex> Kword.extract_permissive([x: 1, y: 2, z: 3], [:w, x: 10, a: 7, b: 8])
[nil, 1, 7, 8]