47m read
Tags: elixir, programming, learning

Introduction

Brief Overview of Elixir

Elixir is a dynamic, functional programming language built on top of the Erlang VM. José Valim created it in 2011 after years of contributing to Ruby on Rails; he wanted Ruby’s expressiveness without its concurrency limitations.valim-motivation The syntax will feel familiar if you’ve spent time with Ruby, and that’s deliberate.ruby-influence

But Elixir isn’t just “Ruby for the BEAM.” It’s a language designed around a specific bet: that concurrency, fault tolerance, and hot code reloading matter more than most language designers think they do. That bet keeps paying off.

Why Elixir Matters

Most languages treat concurrency as an afterthought; something you bolt on with threads, locks, and careful synchronization. Elixir treats it as the foundation. Every process is isolated, lightweight, and supervised — and the runtime has been battle-tested for over three decades in telecom systems that simply cannot go down.beam-telecom

The practical result? You can build systems that handle massive concurrent load without reaching for external tools. WhatsApp managed 900 million users with roughly 50 engineers writing Erlang; Discord processes millions of concurrent users on Elixir.whatsapp-erlang These aren’t toy examples. They’re production systems where failure costs real money.

Elixir’s functional programming model pushes you toward immutability and data transformation — patterns that make code easier to reason about and harder to break. The community is small but productive; the Phoenix web framework, Mix build tool, and Hex package manager form an ecosystem that punches well above its weight class.mix-hex And the language keeps evolving. Elixir 1.0 shipped in 2014; a decade later, the core team still ships meaningful releases without breaking backward compatibility.elixir-1-0

What is Elixir?

Brief History of Elixir

Valim started building Elixir while working on improving Rails’ thread safety. He kept running into walls — Ruby’s Global Interpreter Lock made true parallelism impossible, and the workarounds felt like they were fighting the language rather than working with it. The Erlang VM solved the concurrency problem elegantly, but Erlang’s syntax and tooling hadn’t kept pace with modern developer expectations.

So he built a new language on top of the BEAM.beam-telecom Elixir inherited Erlang’s process model, its fault-tolerance primitives, and its ability to hot-swap code in running systems. What Valim added was a modern syntax influenced by Ruby, a macro system for metaprogramming, and first-class tooling that made the onboarding experience dramatically better.

The first stable release came in September 2014.elixir-1-0 By then, Chris McCord had already started building Phoenix, and the ecosystem was taking shape fast.phoenix-origin

Key Features of the Language

Elixir’s notable features include:

  1. Concurrency and Fault Tolerance: Elixir runs on the Erlang VM, inheriting its process model for building concurrent and resilient applications. Processes are cheap to spawn — we’re talking microseconds and a few kilobytes of memory — and each one is fully isolated.otp-supervision If one process crashes, nothing else goes down with it. That’s not a feature you configure; it’s how the runtime works.

  2. Functional Programming: Elixir is functional at its core. Data is immutable; functions transform data and return new values rather than mutating state in place. This sounds restrictive until you realize how much easier it makes debugging, testing, and reasoning about concurrent code. No shared mutable state means no race conditions.

  3. Syntax and Tooling: The language reads cleanly — influenced by Ruby but not slavishly copying it. Mix handles build automation, dependency management, and task running; Hex provides package management; ExUnit ships with the language for testing. The tooling is opinionated in the right ways.mix-hex

  4. Metaprogramming with Macros: Elixir’s macro system operates on the language’s own AST, which is just regular Elixir data structures.macro-ast This is genuine metaprogramming — you’re transforming code at compile time, not doing string substitution. It’s powerful and, like most powerful things, worth approaching with caution.

  5. Full Erlang Interop: Elixir code calls Erlang functions directly. No wrappers, no FFI, no serialization boundaries. Every Erlang library ever written is available to you. This matters more than it sounds; OTP alone represents decades of battle-tested patterns for building reliable systems.

Elixir’s Place in Functional Programming

Where does Elixir fit among functional languages? It’s not trying to be Haskell. It’s not trying to be Clojure. The type system is dynamic, pattern matching is pervasive, and the emphasis is on operational resilience over compile-time guarantees.haskell-production

Haskell optimizes for correctness at the type level; Elixir optimizes for systems that stay up when things go wrong. Scala tries to bridge object-oriented and functional paradigms on the JVM; Elixir doesn’t bother with objects at all. Clojure shares Elixir’s emphasis on immutability but targets the JVM’s ecosystem rather than the BEAM’s concurrency model.

The distinction matters because it shapes what you build. Elixir excels at long-running services, real-time communication, and systems where “restart the failed component” is a better strategy than “prevent all failures at compile time.” That’s not every application. But for the ones where it fits, nothing else comes particularly close.pattern-matching-erlang

Getting Started with Elixir

Setting Up the Environment

The fastest way to install Elixir is through your operating system’s package manager. On macOS, brew install elixir handles everything; on Ubuntu, apt-get install elixir works but often ships an older version. For any serious work, use a version manager like asdf instead.asdf-version-manager

# Install asdf plugin and Elixir
asdf plugin add elixir
asdf install elixir 1.16.1-otp-26
asdf global elixir 1.16.1-otp-26

Verify the installation:

$ elixir --version
Erlang/OTP 26 [erts-14.2.1] [source] [64-bit]

Elixir 1.16.1 (compiled with Erlang/OTP 26)

You’ll notice the output shows both versions. That’s not incidental; your Elixir version and your Erlang/OTP version are a pair, and mismatches between them cause real problems. Pay attention to both.

Interactive Elixir (IEx)

IEx is Elixir’s interactive shell; it’s the first tool you should reach for when learning the language and the last tool you’ll stop using when you’re experienced. Start it by typing iex in your terminal:

$ iex
Erlang/OTP 26 [erts-14.2.1]

Interactive Elixir (1.16.1) - press Ctrl+C to exit
iex(1)>

IEx is more than a REPL. It’s a documentation browser, a type inspector, and a debugging environment. The helper functions are worth memorizing:

iex> h Enum.map           # documentation for Enum.map
iex> h Enum.map/2         # documentation for the 2-arity version specifically
iex> i "hello"            # type information for a value
iex> i :world             # works for any term
iex> v()                  # the result of the last expression
iex> c "my_file.ex"       # compile a file and load it into the session

The h helper alone is worth the price of admission. Elixir’s documentation lives inside the compiled modules themselves — not on a website, not in a separate file, but embedded in the bytecode. When you call h Enum.map/2, IEx pulls the @doc attribute directly from the compiled module and renders it in your terminal. That means the docs you read in IEx are always in sync with the code you’re running.iex-dot-iex

Basic Commands with Mix

Mix is Elixir’s build tool; it handles project creation, compilation, testing, dependency management, and custom tasks. You’ll use it constantly.

$ mix new greeting
* creating README.md
* creating .formatter.exs
* creating .gitignore
* creating mix.exs
* creating lib
* creating lib/greeting.ex
* creating test
* creating test/test_helper.exs
* creating test/greeting_test.exs

That gives you a working project with tests, a formatter configuration, and a mix.exs file that defines your project’s dependencies and metadata. Run the tests:

$ cd greeting
$ mix test
Compiling 1 file (.ex)
..
Finished in 0.03 seconds (0.03s async, 0.00s sync)
1 test, 0 failures

Compilation happened automatically. Mix knows what needs rebuilding and does it before running tests; you don’t manage a separate compile step. That sounds minor until you’ve spent time in ecosystems where the build process is its own project.

Basic Syntax and Constructs

Data Types

Elixir’s type system is dynamic, but the set of built-in types is small and well-defined. You’ll use all of them within your first week.

Integers and Floats

Integers in Elixir have arbitrary precision; there’s no overflow, no maximum size, no silent truncation. If you need to compute the factorial of 1000, the language won’t stop you.

iex> 1_000_000          # underscores for readability
1000000
iex> 0xFF               # hexadecimal
255
iex> 0b1010             # binary
10
iex> 0o777              # octal
511

Floats are 64-bit IEEE 754 doubles. They require a dot with at least one digit on each side:

iex> 3.14
3.14
iex> 1.0e-10
1.0e-10

One sharp edge: the / operator always returns a float, even for integer operands. 10 / 2 gives you 5.0, not 5. If you want integer division, use div/2.division-float

Booleans and Atoms

Booleans in Elixir are the atoms true and false. That’s not a simplification; it’s literally how the language implements them.

iex> true == :true
true
iex> is_atom(false)
true

Atoms are constants where the name is the value. They’re stored in an atom table at the VM level — created once, referenced by index after that. You’ve already seen :true and :false; you’ll encounter :ok and :error constantly in real code, because Elixir uses {:ok, result} and {:error, reason} tuples as its standard return convention.atom-table

iex> :ok
:ok
iex> :error
:error
iex> :my_custom_status
:my_custom_status

Atoms are cheap to compare — it’s a pointer comparison, not a string comparison — which is why they show up everywhere in pattern matching and function dispatch.

Strings and Charlists

Strings in Elixir are UTF-8 encoded binaries. Double quotes.

iex> name = "Allan"
"Allan"
iex> "Hello, #{name}"       # string interpolation
"Hello, Allan"
iex> String.length("cafe\u0301")  # handles Unicode correctly
5
iex> byte_size("cafe\u0301")      # bytes vs characters
6

Charlists use single quotes and are actually lists of integer codepoints. They exist because Erlang represents strings this way, and you need them when calling Erlang functions directly.charlist-erlang

iex> 'hello'
~c"hello"
iex> 'hello' == [104, 101, 108, 108, 111]
true
iex> is_list('hello')
true

This trips up every newcomer. If you see ~c"hello" in your IEx output, you’re looking at a charlist. If IEx prints a list of small integers and you expected a string, those integers happen to be printable ASCII codepoints, so IEx renders them as a charlist. It’s confusing. Acknowledge it, learn the distinction, move on.

Lists

Lists in Elixir are linked lists. Not arrays. Not vectors. Linked lists. That means prepending is O(1) and getting the length is O(n).

iex> list = [1, 2, 3, 4, 5]
[1, 2, 3, 4, 5]
iex> [0 | list]              # prepend: O(1)
[0, 1, 2, 3, 4, 5]
iex> length(list)             # traverses entire list: O(n)
5
iex> hd(list)                 # head: first element
1
iex> tl(list)                 # tail: everything else
[2, 3, 4, 5]

The [head | tail] syntax is fundamental. You’ll see it in pattern matching, recursion, and list construction; it’s the primary way Elixir programs process lists.

Lists can hold mixed types. [1, :two, "three", 4.0] is perfectly valid. Whether it’s a good idea depends on your use case.

Tuples

Tuples store elements contiguously in memory. Access by index is O(1); modifying an element creates a new tuple.

iex> tuple = {:ok, "hello", 42}
{:ok, "hello", 42}
iex> elem(tuple, 0)
:ok
iex> elem(tuple, 1)
"hello"
iex> tuple_size(tuple)
3

The convention in Elixir is to use tuples for fixed-size collections with known structure and lists for variable-length collections. You’ll see {:ok, value} and {:error, reason} as return values from almost every function that can fail — this convention is so pervasive that fighting it is pointless.

Control Structures

Elixir has control flow constructs, but you’ll reach for them less than you expect. Pattern matching in function heads replaces most conditional logic in idiomatic code. Still, you need to know them.

if and unless

iex> if true do
...>   "yes"
...> else
...>   "no"
...> end
"yes"

iex> unless false do
...>   "this runs"
...> end
"this runs"

Two things to know. First, if and unless are macros, not special forms — they’re built on top of case using the macro system.if-unless-macro Second, only false and nil are falsy. Everything else is truthy. Zero is truthy. The empty string is truthy. The empty list is truthy. If you’re coming from JavaScript or Python, this will save you from an entire category of bugs.

iex> if 0, do: "truthy"
"truthy"
iex> if "", do: "truthy"
"truthy"
iex> if nil, do: "falsy", else: "this one"
"this one"

case

case evaluates an expression and matches the result against a set of patterns. This is where pattern matching starts to shine as control flow:

iex> case File.read("config.json") do
...>   {:ok, contents} ->
...>     IO.puts("Got #{byte_size(contents)} bytes")
...>   {:error, :enoent} ->
...>     IO.puts("File not found")
...>   {:error, reason} ->
...>     IO.puts("Error: #{reason}")
...> end

Each clause is a pattern. The first matching pattern wins; the rest are ignored. If nothing matches, you get a CaseClauseError at runtime — so add a catch-all _ clause when you’re not sure you’ve covered every case.

Guards let you add conditions beyond structural matching:

case value do
  x when is_integer(x) and x > 0 -> "positive integer"
  x when is_integer(x) -> "non-positive integer"
  _ -> "not an integer"
end

In practice, case is the workhorse. Experienced Elixir developers use it far more than if; the pattern-matching syntax pushes you toward handling different shapes of data explicitly rather than checking boolean conditions.

cond

cond evaluates a series of conditions and executes the first one that’s truthy. It’s the construct you reach for when you have multiple conditions that aren’t based on matching a single value:

cond do
  age < 13 -> "child"
  age < 18 -> "teenager"
  age < 65 -> "adult"
  true     -> "senior"
end

The final true clause is a catch-all. Without it, you’ll get a CondClauseError if none of the conditions match. In practice, I rarely use cond; most multi-branch logic maps better onto case with pattern matching or multiple function clauses. But when you’re comparing computed values against thresholds, cond reads more naturally than a chain of if/else if.

Functions in Elixir

Functions are the primary unit of code organization in Elixir. Everything is a function call — even things that look like keywords. if, unless, def — all macros, all function calls under the hood.

Defining Functions

Named functions live inside modules. def creates a public function; defp creates a private one:

defmodule Greeter do
  def hello(name) do
    "Hello, #{name}!"
  end

  defp format_name(name) do
    String.capitalize(name)
  end
end
iex> Greeter.hello("world")
"Hello, world!"
iex> Greeter.format_name("world")
** (UndefinedFunctionError) function Greeter.format_name/1 is undefined or private

Private functions are invisible outside the module. No reflection tricks, no “we’re all adults here” escape hatches — defp means private, and the compiler enforces it.

For single-expression functions, there’s a short syntax:

def hello(name), do: "Hello, #{name}!"

Same function. Shorter notation. Use it when the body fits on one line; don’t force multi-line logic into this form.

Function Naming and Arity

Elixir has naming conventions that carry actual semantic meaning. A trailing ? indicates the function returns a boolean:

iex> String.contains?("hello world", "world")
true
iex> Enum.empty?([])
true

A trailing ! indicates the function raises an exception on failure instead of returning an error tuple:

iex> File.read("missing.txt")
{:error, :enoent}
iex> File.read!("missing.txt")
** (File.Error) could not read file "missing.txt": no such file or directory

The ? and ! aren’t just conventions; they’re enforced expectations. If you see read!, you know it either succeeds or raises. If you see read, you know it returns {:ok, ...} or {:error, ...}. This consistency across the ecosystem saves real debugging time.

Arity — the number of arguments a function takes — is part of the function’s identity. Greeter.hello/1 and Greeter.hello/2 are entirely separate functions as far as the BEAM is concerned.arity-identity

defmodule Greeter do
  def hello(), do: "Hello, stranger!"
  def hello(name), do: "Hello, #{name}!"
  def hello(first, last), do: "Hello, #{first} #{last}!"
end
iex> Greeter.hello()
"Hello, stranger!"
iex> Greeter.hello("Allan")
"Hello, Allan!"
iex> Greeter.hello("Allan", "MacGregor")
"Hello, Allan MacGregor!"

Three functions. Same name. Different arities. The BEAM dispatches to the correct one based on the number of arguments you pass. When you refer to a function in documentation or conversation, you always include the arity: Enum.map/2, String.split/3, IO.puts/1.

Anonymous Functions

Anonymous functions are defined with fn -> end and called with the dot operator:

iex> add = fn a, b -> a + b end
#Function<...>
iex> add.(1, 2)
3

That dot before the parentheses is mandatory.dot-notation It’s the syntactic marker that tells both the compiler and the reader “this is calling an anonymous function bound to a variable, not a named function.” It looks odd at first. You stop noticing after a day.

Anonymous functions close over their environment:

iex> greeting = "Hello"
iex> greet = fn name -> "#{greeting}, #{name}!" end
iex> greet.("world")
"Hello, world!"

The capture operator & provides shorthand for creating anonymous functions. These two are equivalent:

iex> Enum.map([1, 2, 3], fn x -> x * 2 end)
[2, 4, 6]
iex> Enum.map([1, 2, 3], &(&1 * 2))
[2, 4, 6]

&1, &2, &3 refer to the first, second, and third arguments. The & capture operator also lets you reference named functions by arity:

iex> Enum.map([1, 2, 3], &Integer.to_string/1)
["1", "2", "3"]

That last form — &Integer.to_string/1 — is the cleanest way to pass a named function as an argument. You’ll use it constantly with Enum.map, Enum.filter, and the rest of the Enum module.

Modules in Elixir

Modules are namespaces for functions; they’re how Elixir organizes code. Every named function lives inside a module. There are no standalone functions at the top level.

Defining Modules

defmodule MyApp.Calculator do
  def add(a, b), do: a + b
  def subtract(a, b), do: a - b
end
iex> MyApp.Calculator.add(10, 5)
15

The dot-separated names look like a hierarchy, but it’s an illusion. MyApp.Calculator is a single atom — :"Elixir.MyApp.Calculator" — not a nested structure.module-atoms There’s no inherent parent-child relationship between MyApp and MyApp.Calculator; the dots are a naming convention that tooling respects but the runtime doesn’t enforce.

Multiple modules can live in the same file. One module per file is a convention, not a rule. Mix expects lib/my_app/calculator.ex for MyApp.Calculator, but that’s Mix’s opinion, not a language constraint.

Module Attributes

Module attributes serve two purposes: compile-time constants and metadata.

defmodule MyApp.Config do
  @timeout 5_000
  @max_retries 3

  def timeout, do: @timeout
  def max_retries, do: @max_retries
end
iex> MyApp.Config.timeout()
5000

Attributes are resolved at compile time. @timeout is replaced with 5000 during compilation; there’s no runtime lookup. This makes them fast — faster than reading from application configuration — but it also means you can’t change them without recompiling the module.module-attributes-compile

The most common module attributes are built-in:

defmodule MyApp.Parser do
  @moduledoc """
  Parses configuration files in TOML format.

  Handles nested tables, arrays of tables,
  and inline tables per the TOML v1.0 spec.
  """

  @doc """
  Parses a TOML string into an Elixir map.

  Returns `{:ok, map}` on success or `{:error, reason}` on failure.

  ## Examples

      iex> MyApp.Parser.parse("name = \\"Allan\\"")
      {:ok, %{"name" => "Allan"}}
  """
  def parse(input) when is_binary(input) do
    # implementation
  end
end

@moduledoc and @doc are not comments. They’re compiled into the module’s bytecode and accessible at runtime through Code.fetch_docs/1. ExDoc reads them to generate HTML documentation; ExUnit reads @doc blocks to run doctests. The ## Examples section in that @doc attribute? ExUnit will execute the iex> lines as tests if you add doctest MyApp.Parser to your test file.

Documentation is a first-class citizen in Elixir. Not an afterthought, not a nice-to-have — the language gives you h/1 in IEx, @doc/@moduledoc annotations, and a documentation compiler that ships with the standard toolchain. Most languages treat docs as something external. Elixir treats them as part of the code.

Basic Operations

Arithmetic

iex> 2 + 3
5
iex> 10 - 4
6
iex> 3 * 7
21
iex> 10 / 3        # always returns a float
3.3333333333333335
iex> div(10, 3)    # integer division
3
iex> rem(10, 3)    # remainder (not modulo — the sign follows the dividend)
1

The div/2 and rem/2 distinction matters. / always returns a float because Elixir made a deliberate choice: 10 / 2 returning 5.0 is more predictable than sometimes returning an integer and sometimes a float depending on whether the division is exact. Other languages — Python 2 infamously — got this wrong and had to fix it later.

Comparison

iex> 1 == 1.0      # value equality
true
iex> 1 === 1.0     # strict equality (types must match)
false
iex> 1 != 2
true
iex> 1 !== 1.0
true
iex> 1 < 2
true
iex> "a" > "b"
false

The == vs === distinction is straightforward: == compares values and allows integer-float coercion; === requires the types to match. 1 == 1.0 is true; 1 === 1.0 is false. Pick the one that matches your intent.

Elixir allows comparison between any types using a defined structural ordering: number < atom < reference < function < port < pid < tuple < map < list < bitstring.type-ordering This sounds academic until you try to sort a list containing mixed types — it works, deterministically, every time.

Logical

Elixir has two sets of logical operators with different strictness:

# Strict boolean operators — arguments must be true or false
iex> true and false
false
iex> true or false
true
iex> not true
false
iex> not 0            # ArgumentError — 0 is not a boolean
** (ArgumentError)

# Truthy/falsy operators — any value accepted
iex> nil && "hello"
nil
iex> 0 && "hello"     # 0 is truthy
"hello"
iex> nil || "default"
"default"
iex> !nil
true
iex> !0
false

and, or, not require actual booleans on the left side. &&, ||, ! work with truthy and falsy values. Use the strict versions when you know you’re working with booleans; use the relaxed versions when you want nil-coalescing or default-value behavior. Mixing them up produces confusing ArgumentError messages.

The || operator is particularly useful for defaults:

iex> config_value = nil
iex> timeout = config_value || 5_000
5000

And && short-circuits, which makes it useful for conditional chains:

iex> user = %{name: "Allan", email: "allan@example.com"}
iex> user && user.name
"Allan"

The Pipe Operator

This deserves mention even in a fundamentals article. The pipe operator |> takes the result of the expression on the left and passes it as the first argument to the function on the right:

# Without pipe
String.upcase(String.trim("  hello  "))

# With pipe
"  hello  "
|> String.trim()
|> String.upcase()

Both produce "HELLO". The piped version reads top-to-bottom, left-to-right, in the order operations actually happen. The nested version requires you to read inside-out.

The pipe operator is one of those features that genuinely changes how you write code. Once you have it, going back to nested function calls in other languages feels wrong — like reading a sentence backwards. Elixir inherited it from F# via Erlang proposals, and it fits naturally because of the convention that the primary data argument comes first in function signatures.pipe-operator

Pattern Matching

Pattern matching is the feature that reshapes how you think about code. Everything you’ve seen so far — data types, functions, control structures — connects through pattern matching. It’s not a convenience; it’s the core mechanism.

The Match Operator

In Elixir, = is not assignment. It’s the match operator. The left side is a pattern; the right side is evaluated; the operator attempts to make them match.

iex> x = 1
1
iex> 1 = x
1
iex> 2 = x
** (MatchError) no match of right hand side value: 1

That second line — 1 = x — succeeds because x is already bound to 1, so the pattern matches. The third line fails because 2 doesn’t match the value 1. This is a fundamentally different mental model from assignment in imperative languages; = asserts a relationship, it doesn’t create one.

Destructuring follows directly from this:

iex> {status, count} = {:ok, 42}
{:ok, 42}
iex> status
:ok
iex> count
42

iex> [head | tail] = [1, 2, 3, 4]
[1, 2, 3, 4]
iex> head
1
iex> tail
[2, 3, 4]

The pattern on the left side binds variables to the corresponding parts of the data structure on the right. This works with tuples, lists, maps — any data structure. The underscore _ ignores a position:

iex> {:ok, _} = {:ok, "don't care about this value"}
{:ok, "don't care about this value"}

Pattern Matching in Function Calls

The real power shows up in function heads. Multiple function clauses with different patterns replace if/else chains:

defmodule HttpHandler do
  def handle_response({:ok, %{status: 200, body: body}}) do
    {:ok, body}
  end

  def handle_response({:ok, %{status: 404}}) do
    {:error, :not_found}
  end

  def handle_response({:ok, %{status: status}}) when status >= 500 do
    {:error, :server_error}
  end

  def handle_response({:error, reason}) do
    {:error, reason}
  end
end

Each clause matches a specific shape of input. The BEAM dispatches to the first matching clause. No if status == 200, no switch statement, no method overloading — just patterns.

This changes how you design interfaces. Instead of writing one function with branching logic inside, you write multiple clauses that each handle one shape of data. The function’s type signature emerges from its patterns. Reading the function heads tells you exactly what shapes of data the function accepts and how it handles each one.

defmodule Factorial do
  def of(0), do: 1
  def of(n) when n > 0, do: n * of(n - 1)
end
iex> Factorial.of(5)
120
iex> Factorial.of(0)
1

Two clauses. The base case matches 0 and returns 1. The recursive case matches any positive integer and recurses. That’s the complete implementation; there’s nothing to add. The patterns make the logic self-documenting.

The Pin Operator

By default, = rebinds variables on the left side. The pin operator ^ prevents rebinding; it asserts that the existing value must match.

iex> x = 1
1
iex> x = 2       # rebinds x to 2
2
iex> ^x = 2      # asserts x (which is 2) matches 2
2
iex> ^x = 3      # fails: x is 2, not 3
** (MatchError) no match of right hand side value: 3

Without the pin, x = 3 would succeed by rebinding x. With the pin, ^x = 3 fails because you’re asserting that the current value of x equals 3.

Where this becomes essential is in function heads and case clauses:

defmodule Router do
  def route(method, path)

  def route("GET", "/"), do: :index
  def route("GET", "/about"), do: :about
  def route(method, path), do: {:error, :not_found, method, path}
end

Now suppose you want to match against a dynamic value:

def handle(expected_token, request) do
  case request do
    %{token: ^expected_token} -> :authorized
    _ -> :unauthorized
  end
end

The ^expected_token doesn’t match any token; it matches specifically the value that expected_token was bound to when the function was called. Without the pin, token would bind to whatever value was in the map, and the match would always succeed. That’s a bug that the pin operator exists to prevent.pin-operator-origin

The pin operator trips people up more than any other single concept in Elixir. The confusion is always the same: “Why didn’t my match fail? I expected it to compare against my variable.” The answer is almost always a missing ^. If you’re matching in a case or function head and you want to compare against an existing binding rather than create a new one, pin it.

Conclusion

We’ve covered the ground floor of Elixir: types, functions, modules, operations, control structures, and pattern matching. That’s enough to read most Elixir code and write simple programs. But it’s also only the surface.

What I keep coming back to after years with this language is how pattern matching and immutability rewire your instincts. You stop thinking about mutating state and start thinking about transforming data. You stop writing if chains and start writing function clauses. The shift is subtle at first; then one day you open a Python file and wonder why you’re manually checking types inside a function body instead of letting the function signature do it for you.

The hard parts haven’t arrived yet. Maps, keyword lists, and structs — which we’ll cover in the next article — introduce Elixir’s approach to structured data. After that comes the real mountain: processes, OTP, GenServers, and supervision trees. That’s where the language goes from “nice syntax” to “this solves problems other languages can’t.” But you need this foundation first. Pattern matching shows up in every process message handler. Tuples are how every process communicates. The {:ok, value} / {:error, reason} convention is how supervisors decide whether to restart a child.

None of that will make sense without the fundamentals sitting solid. So write some code. Break things in IEx. Get confused by charlists and annoyed by the pin operator. That’s the process working.

References

  • Elixir Official Getting Started Guide — the single best starting resource; concise, accurate, and maintained by the core team.
  • HexDocs: Elixir Standard Library — complete API reference with examples for every module and function.
  • Elixir School — community-maintained lessons covering fundamentals through advanced topics.
  • Jurić, Saša. Elixir in Action, Third Edition. Manning, 2024 — the most thorough treatment of how Elixir works at the runtime level; especially strong on processes and OTP.
  • Thomas, Dave. Programming Elixir 1.6. Pragmatic Bookshelf, 2018 — focuses on the “think different” aspect of moving from OOP to functional; good for developers coming from Ruby or Python.
  • Exercism Elixir Track — practice problems with mentored feedback; the best way to build fluency after reading documentation.

What do you think of what I said?

Share with me your thoughts. You can tweet me at @allanmacgregor.

Other articles that may interest you

Mastering Elixir in 2024: A study path