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
Link to this function

extract_exhaustive(opts, params)

View Source

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}}
Link to this function

extract_exhaustive!(opts, params)

View Source

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
Link to this function

extract_permissive(opts, params)

View Source

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]