Keyword lists

What keyword lists are

A keyword list is a list of two-item tuples whose first element is an atom. It carries options, settings, and tagged values.

The list keeps order and allows repeated keys, which maps do not promise.

erl

1> [{name, "Ada"}, {age, 36}].
[{name,"Ada"},{age,36}]
2> [{tag, a}, {tag, b}].
[{tag,a},{tag,b}]

Read a value

The proplists module reads, deletes, and replaces entries by key. get_value answers the first value for a key, or a default you give it.

A missing key is not an error here, which makes keyword lists the friendly way to pass options.

erl

1> Opts = [{mode, fast}, {retries, 3}].
[{mode,fast},{retries,3}]
2> proplists:get_value(mode, Opts).
fast
3> proplists:get_value(timeout, Opts, 5000).
5000

Build one

Most code builds keyword lists by hand, at the call site. They are the standard shape for function options across the Erlang world.

The syntax reads like the settings panel of a tool: key, value, key, value. This module reads the port and timeout out of its options; save it as opts.erl.

-module(opts). -export([connect/2, port/1]). connect(Host, Opts) -> Port = proplists:get_value(port, Opts, 5432), Timeout = proplists:get_value(timeout, Opts, 5000), {connect, Host, Port, Timeout}. port(Opts) -> proplists:get_value(port, Opts).

erlc opts.erl
erl

1> opts:connect("db.local", [{port, 5433}]).
{connect,"db.local",5433,5000}
2> opts:port([]).
undefined

Why they endure

Keyword lists predate maps and stay because of two small gifts: order matters, and a key may repeat. Both matter for options and for tagged values in messages.

When order or repetition matters, reach for a keyword list; when lookup speed matters, reach for a map.

erl

1> proplists:get_all_values(tag, [{tag, a}, {tag, b}]).
[a,b]
2> proplists:get_value(tag, [{tag, a}, {tag, b}]).
a

Next: Erlang idioms and clean code

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is a keyword list?

    Answer

    A list of two-item tuples whose first element is an atom

    Each entry is a pair such as {port, 5432}, and the whole thing is an ordinary list.

  2. Which property does a keyword list have that a map does not?

    Answer

    A fixed order and repeated keys

    A list keeps its order and may hold {tag, a} and {tag, b}; a map keeps one value per key.

  3. What does proplists:get_value(port, Opts) answer when the key is missing?

    Answer

    undefined

    Without a default, get_value/2 answers the atom undefined instead of failing.

  4. What does proplists:get_value(timeout, Opts, 5000) answer when the key is missing?

    Answer

    5000

    The third argument is the default that comes back when no entry matches.

  5. What does proplists:get_all_values(tag, [{tag, a}, {tag, b}]) answer?

    Answer

    [a,b]

    get_all_values/2 collects every value for the key, in list order.

  6. What does opts:connect("db.local", [{port, 5433}]) answer?

    Answer

    {connect,"db.local",5433,5000}

    The module reads the port from the options and falls back to 5000 for the timeout.

  7. What does opts:port([]) answer?

    Answer

    undefined

    port/1 calls get_value/2 with no default, and the empty list has no entry.

  8. Which module is the standard toolbox for keyword lists?

    Answer

    proplists

    proplists reads, deletes and replaces property entries by key.

  9. When is a map the better choice than a keyword list?

    Answer

    When lookup speed matters

    Maps are built for lookup; lists are built for order and repetition.

  10. Why are keyword lists the common shape for function options?

    Answer

    A missing option can answer a default instead of failing

    get_value with a default keeps optional settings optional, and the call site stays readable.

The examples on this page were compiled and run with Erlang/OTP 27 (erts-15.2.7.14) on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev