Skip to content
LumenaryAcademy
Foundations 55 min

Functions, modules and the pipe operator

Anonymous and named functions, clauses and guards, recursion instead of loops, and pipelines that read top to bottom.

Code tested · 4AI-draftedAwaiting review by a computer scientist
MotivationH

Programs made of functions

In an object-oriented language, code is organised around objects: data bundled with the methods that change it. Elixir has no objects. Data is plain and immutable, and code is a collection of functions that take data in and return new data out. Functions are grouped into modules, which are simply named collections of functions with no state of their own.

That might sound restrictive, but it gives you something valuable: a function's result depends only on its arguments (apart from deliberate side effects such as printing or sending a message). You can understand, test and reuse a function on its own, without first setting up the object it belongs to.

Elixir functions also bring two features that change how you write everyday code. The first is that a function can have several clauses, each with its own pattern, so the shape of the input chooses which code runs, exactly like the case expressions from the last lesson. The second is the pipe operator |>, which lets you write a chain of transformations in the order they happen, the way you would describe them aloud. By the end of this lesson both will feel natural.

DefinitionsH

Anonymous functions and captures

An anonymous function is created with fn ... -> ... end and stored like any other value. Call it with a dot before the parentheses:

elixir
add = fn a, b -> a + b end
IO.puts(add.(2, 3))

# Several clauses, chosen by pattern, like a case expression.
describe = fn
  0 -> "zero"
  n when n < 0 -> "negative"
  _ -> "positive"
end

IO.puts(describe.(-4))

# A closure remembers the values it could see when it was created.
make_greeter = fn greeting -> fn name -> "#{greeting}, #{name}!" end end
hola = make_greeter.("Hola")
IO.puts(hola.("Lucía"))

# The capture operator: &Module.function/arity names an existing function...
upcase = &String.upcase/1
IO.puts(upcase.("quiet"))

# ...and &(...) builds a small function, with &1, &2 for its arguments.
triple = &(&1 * 3)
IO.inspect(Enum.map([1, 2, 3], triple))
IO.inspect(Enum.map(["a", "b"], &String.duplicate(&1, 3)))

It prints:

text
5
negative
Hola, Lucía!
QUIET
[3, 6, 9]
["aaa", "bbb"]

The dot in add.(2, 3) is not decoration: it tells the reader, and the compiler, that add is a variable holding a function, not a named function called add. make_greeter returns a function that closes over greeting; hola remembers "Hola" long after make_greeter finished.

The capture operator & has two uses. &String.upcase/1 turns a named function into a value you can pass around. &(&1 * 3) is shorthand for fn x -> x * 3 end, where &1 is the first argument, &2 the second, and so on. Use the short form for tiny functions; once it has more than one operator or argument, a full fn is easier to read.

Worked examplesH

Named functions in modules

Named functions live in modules. def defines a public function, defp a private one, visible only inside its module. A function is identified by its name and its arity (number of arguments), written name/arity: String.split/1 and String.split/2 are two different functions that happen to share a name.

elixir
defmodule Shipping do
  @moduledoc "Shipping costs for a small online shop, in cents."

  @free_threshold 50_00
  @rates %{standard: 4_99, express: 12_99}

  @doc "The shipping cost for an order total, in cents."
  def cost(total, speed \\ :standard)

  def cost(total, :standard) when total >= @free_threshold, do: 0
  def cost(_total, speed) when is_map_key(@rates, speed), do: @rates[speed]

  def cost(_total, speed) do
    raise ArgumentError, "unknown shipping speed: #{inspect(speed)}"
  end

  def format(cents) when is_integer(cents) and cents >= 0 do
    "#{div(cents, 100)}.#{pad(rem(cents, 100))}"
  end

  defp pad(n) when n < 10, do: "0#{n}"
  defp pad(n), do: Integer.to_string(n)
end

IO.puts(Shipping.format(Shipping.cost(23_50)))
IO.puts(Shipping.format(Shipping.cost(80_00)))
IO.puts(Shipping.format(Shipping.cost(80_00, :express)))
IO.puts(Shipping.format(5))
IO.inspect(function_exported?(Shipping, :pad, 1))

It prints:

text
4.99
0.00
12.99
0.05
false

There is a lot packed into that module:

  • Module attributes such as @free_threshold are constants fixed at compile time. @moduledoc and @doc are special attributes holding documentation, which h Shipping.cost in iex will show you.
  • def cost(total, speed \\ :standard) is a function head: no body, just a declaration that speed defaults to :standard. When a function with defaults has several clauses, Elixir wants the defaults declared once, in a head like this. Defaults actually create two functions, cost/1 and cost/2.
  • The clauses are tried in order. Free standard shipping for orders of 50.00 or more must come before the general clause, or it would never be chosen.
  • Guards (when ...) refine a pattern with a condition. Only a fixed set of expressions is allowed in guards (comparisons, arithmetic, type checks such as is_integer/1, is_map_key/2, map_size/1 and a few more), because guards must be fast and free of side effects. If a guard raises an error, the clause simply does not match.
  • The do: form (def pad(n), do: ...) is a one-line shorthand for do ... end.
  • Money is kept in integer cents, avoiding the floating-point surprise from the previous lesson.
  • pad/1 is private, so function_exported?/3 reports that the outside world cannot call it.

Elixir naming conventions carry meaning. A function ending in ? returns a boolean (String.contains?/2). A function ending in ! raises an exception on failure instead of returning {:error, reason}, and usually has a sibling without the ! (File.read/1 and File.read!/1). Functions that are allowed in guards begin with is_.

Inside a module you will also see four directives that control how names and code are brought in. alias MyApp.Accounts.User lets you write User instead of the full name. import Integer, only: [is_even: 1] makes functions callable without their module prefix; use it sparingly and always with only:. require Logger is needed before using a module's macros. And use GenServer runs code from another module to inject definitions into yours; you will use it for GenServers and tests.

Module names can contain dots, as in Shop.Cart or MyApp.Accounts.User, and projects use them to group related modules by feature. The dots are only part of the name: there is no runtime hierarchy, Shop.Cart is not "inside" Shop in any way that affects behaviour, and either can exist without the other. A module defined inside another one (defmodule Shop do defmodule Cart do ... end end) simply gets the combined name Shop.Cart and an automatic alias within the outer module.

ComputationC

Recursion instead of loops

Elixir has no while loop and no for loop that changes a counter, because there is nothing to change. Repetition is expressed with recursion: a function that calls itself on a smaller problem, with a clause for the smallest problem of all. Lists, built as a head and a tail, fit this perfectly.

elixir
defmodule MyList do
  # Body recursion: the addition happens after the recursive call returns.
  def sum([]), do: 0
  def sum([head | tail]), do: head + sum(tail)

  # Tail recursion: the recursive call is the last thing the function does,
  # and the running total travels along in an accumulator.
  def sum_tail(list), do: sum_tail(list, 0)
  defp sum_tail([], acc), do: acc
  defp sum_tail([head | tail], acc), do: sum_tail(tail, acc + head)

  # Run-length encoding: "aaabcc" becomes [{"a", 3}, {"b", 1}, {"c", 2}].
  def encode(string), do: string |> String.graphemes() |> encode([])

  defp encode([], acc), do: Enum.reverse(acc)
  defp encode([g | rest], [{g, n} | acc]), do: encode(rest, [{g, n + 1} | acc])
  defp encode([g | rest], acc), do: encode(rest, [{g, 1} | acc])
end

IO.puts(MyList.sum([4, 8, 15, 16, 23, 42]))
IO.puts(MyList.sum_tail(Enum.to_list(1..1_000_000)))
IO.inspect(MyList.encode("aaabccddddé"))

It prints:

text
108
500000500000
[{"a", 3}, {"b", 1}, {"c", 2}, {"d", 4}, {"é", 1}]

sum/1 reads like a definition: the sum of an empty list is 0, and the sum of a non-empty list is its head plus the sum of its tail. Each call waits for the next to return, so the BEAM keeps a stack frame per element until it reaches the end.

sum_tail/2 carries the running total in an accumulator. Its recursive call is the very last thing it does (a tail call), so the BEAM reuses the current frame instead of adding one: tail recursion runs in constant stack space, the functional equivalent of a loop. The public sum_tail/1 hides the accumulator from callers, a pattern you will see everywhere.

encode/2 shows how much a pattern can say. The second clause, encode([g | rest], [{g, n} | acc]), uses the variable g twice: it only matches when the next grapheme is the same one the accumulator is currently counting. Building the result backwards and reversing it once at the end is the standard idiom, because adding to the front of a list is cheap and adding to the end is not.

In practice you will write explicit recursion less often than you might expect: the Enum module, the subject of the next lesson, already contains map, filter, reduce and dozens more, all built on this idea. But knowing how they work lets you write the cases they do not cover.

Worked examplesH

The pipe operator

Here is a small text-processing task written the nested way:

elixir
Enum.take(Enum.sort_by(Enum.frequencies(String.split(String.downcase(text))), fn {_, n} -> -n end), 3)

You have to read it from the inside out. The pipe operator x |> f(y) means f(x, y): it passes the value on its left as the first argument of the call on its right. With it, the same computation reads in the order it happens:

elixir
text = """
The river runs past the mill and the mill turns, and the miller
sings to the river while the river runs on to the sea.
"""

text
|> String.downcase()
|> String.split(~r/[^\p{L}]+/u, trim: true)
|> Enum.frequencies()
|> Enum.sort_by(fn {word, count} -> {-count, word} end)
|> Enum.take(4)
|> IO.inspect()

# then/2 pipes into a function that does not take the value first;
# tap/2 runs a side effect and passes the value through unchanged.
21
|> tap(&IO.puts("starting with #{&1}"))
|> Kernel.*(2)
|> then(&Integer.pow(2, &1))
|> IO.puts()

It prints:

text
[{"the", 7}, {"river", 3}, {"and", 2}, {"mill", 2}]
starting with 21
4398046511104

The text uses a heredoc, a multi-line string between triple quotes. ~r/.../u is a regular expression sigil; \p{L} matches any letter in any script, so the split works for words in Yoruba or Vietnamese as well as English. Sorting by {-count, word} puts higher counts first and breaks ties alphabetically, because tuples compare element by element.

The second pipeline shows the escape hatches. Kernel.*(2) is the multiplication operator called as an ordinary function, so 21 |> Kernel.*(2) is 21 * 2. then/2 lets you pipe into a position other than the first (here the exponent of Integer.pow/2), and tap/2 lets you look at a value mid-pipeline without changing it.

This is why Elixir libraries put the data being transformed as the first argument of their functions: String.split(string, pattern), Map.put(map, key, value), Enum.map(list, fun). Follow the same convention in your own modules, and your functions will slot into pipelines naturally.

Note

When a pipeline misbehaves, add |> dbg() at the end. The dbg/2 macro (added in Elixir 1.14) prints the code of each step of the pipeline next to its result; started as iex --dbg pry, the shell instead pauses at that point so you can inspect the variables. Remove it before you commit; the formatter and code review will remind you if you forget.

ExplanationH

How Elixir developers write functions

Knowing the syntax is half the job; the other half is the set of habits that make Elixir code easy to read six months later. These are the ones you will see in well-kept codebases.

Let the shape of the input choose the clause. When the decision depends on what the arguments look like, write several clauses rather than one function with a case inside. When it depends on something computed partway through, use case there. Both are pattern matching; the question is only where the decision naturally lives.

Be assertive. If your program cannot do anything sensible when a configuration file is missing, write {:ok, text} = File.read("config.json") and let the MatchError stop it with a clear message, instead of threading an error value through ten functions that cannot handle it either. Match on the values you expect, and let unexpected ones fail loudly. You will see in the Professional lessons how supervisors turn this habit, "let it crash", into a reliability strategy.

Write the data first, and keep functions small. Put the main data as the first argument so the function fits in a pipeline, give it a name that says what it returns, and split it when it grows past what fits on a screen. Private helpers (defp) are free, and good names in them act as documentation.

Document with examples that run. A @doc can contain examples written as iex sessions:

elixir
@doc """
Formats an amount of cents as a decimal string.

    iex> Shipping.format(1250)
    "12.50"

    iex> Shipping.format(7)
    "0.07"
"""
def format(cents) when is_integer(cents) and cents >= 0 do
  ...
end

Add the line doctest Shipping to a test module, and mix test runs every one of those examples and checks the results, so the documentation cannot drift away from the code. Doctests are one of the reasons Elixir library documentation is unusually trustworthy. mix docs, from the ex_doc package, turns the same text into the HTML pages you see on HexDocs.

Let the formatter decide the layout. mix format rewrites your files into the community's standard style: two-space indentation, parentheses on calls, line breaks in long pipelines. Teams run it on save in the editor and check it in continuous integration with mix format --check-formatted, so code review never needs to discuss whitespace.

Common misconceptionsH

Common mistakes

Misconception

"The pipe puts the value in the last argument." It always fills the first argument. "a-b" |> String.split("-") is String.split("a-b", "-"). If the value belongs elsewhere, use then/2 or end the pipeline and call the function normally.

Misconception

"add(1, 2) should work when add holds a function." Without the dot, Elixir looks for a named function add/2. Anonymous functions are always called as add.(1, 2).

Misconception

"Clause order does not matter, the most specific clause wins." Elixir tries clauses strictly from top to bottom. A general clause placed first hides every clause below it; the compiler (and, in Elixir 1.20, the type checker) will often warn that a later clause can never match, so read those warnings.

Misconception

"Tail recursion is always better." For long or unbounded loops (a server's main loop, a million-element list) a tail call keeps memory flat. But body recursion like sum/1 is often just as fast on the BEAM for ordinary list sizes and avoids a final Enum.reverse. Write the clearer version first, and reach for the standard library before either.

Exercises

Exercises

1. Functions, modules and the pipe operator

Warm-upComputational

After square = fn x -> x * x end, which expression returns 16?

Choose one

2. Functions, modules and the pipe operator

Warm-upComputational

What does this line print?

"a,b,c" |> String.split(",") |> Enum.join("-") |> IO.puts()

3. Functions, modules and the pipe operator

CoreComputational

What does this program print?

defmodule Grade do
  def letter(score) when score >= 90, do: "A"
  def letter(score) when score >= 75, do: "B"
  def letter(_), do: "C"
end

IO.puts(Grade.letter(75) <> Grade.letter(89) <> Grade.letter(91))

4. Functions, modules and the pipe operator

CoreHuman

How many public functions (distinct name/arity pairs) does this module define?

defmodule M do
  def greet(name, greeting \\ "Hi"), do: "#{greeting}, #{name}"
  def greet(), do: greet("you")
end

5. Functions, modules and the pipe operator

CoreComputational

What does IO.inspect(Enum.map([1, 2, 3], &(&1 * &1 + 1))) print?

6. Functions, modules and the pipe operator

StretchComputational

What does this program print?

defmodule Count do
  def down(0, acc), do: [0 | acc]
  def down(n, acc), do: down(n - 1, [n | acc])
end

IO.inspect(Count.down(3, []))

7. Functions, modules and the pipe operator

StretchHuman

Which of these definitions of a list-length function is tail recursive?

Choose one

Further reading and resources