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.
-
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. -
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. -
What does
proplists:get_value(port, Opts)answer when the key is missing?Answer
undefinedWithout a default,
get_value/2answers the atomundefinedinstead of failing. -
What does
proplists:get_value(timeout, Opts, 5000)answer when the key is missing?Answer
5000The third argument is the default that comes back when no entry matches.
-
What does
proplists:get_all_values(tag, [{tag, a}, {tag, b}])answer?Answer
[a,b]get_all_values/2collects every value for the key, in list order. -
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.
-
What does
opts:port([])answer?Answer
undefinedport/1callsget_value/2with no default, and the empty list has no entry. -
Which module is the standard toolbox for keyword lists?
Answer
proplistsproplistsreads, deletes and replaces property entries by key. -
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.
-
Why are keyword lists the common shape for function options?
Answer
A missing option can answer a default instead of failing
get_valuewith 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