Home
access-behaviour
Elixir

Master Basketball Website in Elixir: Complete Learning Path

Master Basketball Website in Elixir: Complete Learning Path

Effortlessly manage and transform deeply nested data structures in Elixir using the powerful `get_in`, `put_in`, and `update_in` macros. This guide provides a comprehensive walkthrough, from core concepts to practical application, enabling you to write cleaner, safer, and more expressive Elixir code.

Have you ever found yourself wrestling with a complex data structure, like a JSON response from an API? You need to extract a value buried four levels deep, and your code becomes a fragile, unreadable chain of square brackets and pattern matches: data["user"]["profile"]["settings"]["theme"]. What happens if the "profile" key is missing? Your application crashes with a `KeyError` or a `MatchError`. This is a common pain point that leads to brittle code filled with defensive checks. But what if there was a more elegant, functional, and robust way to navigate and manipulate these structures? In Elixir, there is, and it will fundamentally change how you handle complex data.

What Exactly Are Elixir's "in" Macros for Data Access?

In the world of functional programming and immutability, safely accessing and updating nested data is paramount. Elixir provides a suite of brilliant macros built into its Kernel module specifically for this purpose: get_in/2, put_in/2, and update_in/2. These are not just simple helper functions; they are your primary tools for interacting with any data structure that implements the Access behaviour, such as maps, keyword lists, and even your own custom structs.

At their core, these macros allow you to specify a "path" of keys or indexes to traverse into a nested structure. Instead of chaining accessors, you provide a single list representing the path. This approach is declarative, readable, and, most importantly, safe—it gracefully handles cases where an intermediate key does not exist, preventing runtime errors.

Let's break down the main players:

  • get_in(data, path): This macro is for reading data. It traverses the data structure using the list of keys in path. If the full path exists, it returns the value at the end. If any key along the path is missing, it immediately stops and returns nil without raising an error.
  • put_in(data, path, value): This is for writing or replacing data. It traverses the data structure to the end of the path and replaces the value there with the new value. Crucially, due to Elixir's immutability, it doesn't modify the original data; it returns a completely new data structure with the change applied. If the path doesn't exist, it will create it.
  • update_in(data, path, function): This is for transforming existing data. It's similar to put_in, but instead of a static value, you provide a function. It finds the value at the end of the path, applies the function to it, and puts the result back into a new copy of the data structure. If the path doesn't exist, it does nothing and returns the original data.

These tools are fundamental to idiomatic Elixir development, especially when dealing with application state, API responses, or complex configuration files.

  ● Start with Nested Data (e.g., a Map)
  │
  ├─ Path: [:players, 0, :stats, :points]
  │
  ▼
┌──────────────────┐
│   Choose Macro   │
└────────┬─────────┘
         │
  ┌──────┴──────┐
  │             │
  ▼             ▼
get_in       put_in/update_in
  │             │
  │             ├─ New Value or Function
  │             │
  ▼             ▼
◆ Path Valid? ◆ ◆ Path Valid? ◆
╱         ╲     ╱         ╲
Yes       No   Yes         No
│         │     │           │
▼         ▼     ▼           ▼
Return    Return  Return      Return
Value     `nil`   New Data    Original Data
  │         │     │           │
  └─────────┴─────┴───────────┘
            │
            ▼
        ● End

Why Is This Approach Essential in Modern Elixir?

The "why" behind these macros is rooted in the core principles of Elixir and the BEAM virtual machine: fault tolerance and functional programming. Writing code that anticipates failure and handles it gracefully is a cornerstone of building robust systems.

Embracing Immutability and Safety

In languages with mutable data, changing a nested value can have unintended side effects across your application. Elixir's immutable-by-default nature prevents this. When you use put_in or update_in, you are guaranteed that the original data structure remains untouched. This makes your state transformations predictable and easy to reason about.

Consider the alternative: manual, chained access. 


# The "unsafe" way
team = %{name: "Warriors", players: [%{name: "Steph Curry"}]}
# This will crash if :stats is missing!
team[:players][0][:stats][:points]

# The "safe" but verbose way
with %{stats: stats} <- team[:players][0],
     %{points: points} <- stats do
  points
else
  _ -> nil
end

The `with` statement is powerful but adds significant boilerplate for a simple data retrieval. The get_in macro simplifies this dramatically:


# The clean, safe, and idiomatic Elixir way
team = %{name: "Warriors", players: [%{name: "Steph Curry"}]}
get_in(team, [:players, 0, :stats, :points])
#=> nil (no crash!)

Enhancing Code Readability and Maintainability

Code is read far more often than it is written. The in macros make your intent crystal clear. A developer looking at your code can immediately understand that you are performing a deep traversal of a data structure. The path, a simple list of keys, is self-documenting.

This clarity becomes even more important as data structures grow in complexity. Instead of deciphering a long chain of function calls or nested `case` statements, you see a single, expressive line of code.

The Power of the `Access` Behaviour

The true genius behind these macros is the Access behaviour. It's a protocol that defines how to get, pop, and update values within a data structure. By default, Maps and Keyword Lists implement this behaviour. This means you can use the same get_in syntax for different data types.

Furthermore, you can implement the Access behaviour for your own custom structs. This allows you to integrate your domain-specific data types seamlessly into this powerful data manipulation ecosystem, making your own code just as ergonomic as Elixir's built-in types.

How to Implement Nested Data Manipulation: A Practical Guide

Let's dive into practical, hands-on examples using the context of a basketball website. We'll manage data for teams, players, and their statistics. We will run these examples in an Interactive Elixir shell (`iex`).

Setting Up Your Data

First, open your terminal and start an `iex` session:


$ iex
Erlang/OTP 26 [erts-14.2.1] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit:ns]

Interactive Elixir (1.16.0) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)>

Now, let's define our nested map representing a basketball team.


iex(1)> team_data = %{
...(1)>   name: "Phoenix Suns",
...(1)>   city: "Phoenix",
...(1)>   conference: "Western",
...(1)>   stats: %{wins: 51, losses: 31},
...(1)>   players: [
...(1)>     %{name: "Devin Booker", position: "SG", stats: %{points_per_game: 27.8}},
...(1)>     %{name: "Kevin Durant", position: "SF", stats: %{points_per_game: 29.1}},
...(1)>     %{name: "Bradley Beal", position: "SG", stats: %{points_per_game: 19.1}}
...(1)>   ]
...(1)> }

Reading Data with `get_in/2`

The goal of `get_in` is to safely retrieve a value. Let's try getting Kevin Durant's points per game.

The path to this value is: first the :players key, then the second element of the list (index 1), then the :stats key, and finally the :points_per_game key.


iex(2)> path_to_kd_ppg = [:players, 1, :stats, :points_per_game]
iex(3)> get_in(team_data, path_to_kd_ppg)
29.1

Now, what if we try to access a key that doesn't exist? For instance, let's look for a `championships` key within the team's stats.


iex(4)> get_in(team_data, [:stats, :championships])
nil

Notice how it returns nil instead of crashing. This is the primary benefit of get_in. It allows you to probe for data without needing to write complex error-handling logic.

# `get_in` Logic Flow

    ● Start with Data & Path
      data: team_data
      path: [:players, 1, :stats, :points_per_game]
      │
      ▼
┌───────────────────┐
│ get_in(data, path)│
└─────────┬─────────┘
          │
          ▼
    ◆ Access :players ?
          │ Yes
          ▼
    ◆ Access index 1 ?
          │ Yes
          ▼
    ◆ Access :stats ?
          │ Yes
          ▼
    ◆ Access :points_per_game ?
   ╱           ╲
  Yes           No (or any previous step fails)
  │              │
  ▼              ▼
┌───────────┐  ┌───────────┐
│ Return 29.1 │  │ Return nil│
└───────────┘  └───────────┘
      │              │
      └──────┬───────┘
             ▼
           ● End

Updating Data with `put_in/3` and `update_in/3`

Now let's imagine we need to update our data. Suppose there's a trade, and we need to update a player's name. We'll use put_in to replace the value entirely.


# Let's change Bradley Beal's position to Point Guard (PG)
iex(5)> path_to_beal_pos = [:players, 2, :position]
iex(6)> new_team_data = put_in(team_data, path_to_beal_pos, "PG")

# Let's inspect the new data for the third player
iex(7)> get_in(new_team_data, [:players, 2])
%{name: "Bradley Beal", position: "PG", stats: %{points_per_game: 19.1}}

Importantly, the original team_data variable is unchanged. This is immutability in action.

Now, what if we want to modify a value based on its current state? For example, let's add 5 wins to the team's record. This is a perfect use case for update_in, which takes a function.


# The function `&(&1 + 5)` is shorthand for `fn(current_wins) -> current_wins + 5 end`
iex(8)> path_to_wins = [:stats, :wins]
iex(9)> updated_wins_data = update_in(team_data, path_to_wins, &(&1 + 5))

# Let's inspect the new stats
iex(10)> get_in(updated_wins_data, [:stats])
%{losses: 31, wins: 56}

If you try to use update_in on a path that doesn't exist, it does nothing and simply returns the original data structure, maintaining safety.


iex(11)> update_in(team_data, [:stats, :championships], &(&1 + 1))
# Returns the original team_data map because :championships does not exist.

Where This Pattern Shines: Real-World Applications

The "Basketball Website" module from the kodikra Elixir learning path is a fantastic introduction, but these functions are used everywhere in professional Elixir development.

  • Phoenix LiveView State Management: In LiveView, the state of your component is held in a socket.assigns map. When a user interacts with the page, you frequently need to update nested data within this state. update_in is the go-to tool for applying changes immutably, triggering Phoenix to efficiently re-render only the changed parts of the UI.
  • Parsing External API Responses: When you consume a third-party API, you can't always trust the shape of the JSON response. Using get_in allows you to safely extract the data you need without your application crashing if the API provider changes a field or omits an optional key.
  • Configuration Management: Applications often have complex configuration files (e.g., in YAML or JSON format, parsed into Elixir maps). get_in provides a safe way to read configuration values, with put_in offering a dynamic way to override settings for different environments (e.g., development vs. production).
  • Data Transformation Pipelines: In Ecto and data processing workflows, you often need to transform data as it moves through your system. Chaining `update_in` and `put_in` calls with the pipe operator (`|>`) creates highly readable and declarative pipelines for cleaning, augmenting, and reshaping data. 

# A mini data pipeline example
def process_player_data(player_map) do
  player_map
  |> put_in([:processed_at], DateTime.utc_now())
  |> update_in([:name], &String.upcase/1)
  |> update_in([:stats, :points_per_game], &round/1)
end

Common Pitfalls and Best Practices

While powerful, these macros have nuances. Understanding them will help you avoid common mistakes and write more robust code.

Pros and Cons of Using `in` Macros

Aspect Using `in` Macros (e.g., `get_in`) Manual Chained Access / Pattern Matching
Safety High. Automatically handles `nil` and missing keys, preventing crashes. Low. Prone to `KeyError` or `MatchError` if any part of the path is missing. Requires explicit error handling.
Readability High. The path is a clean, declarative list. Intent is immediately clear. Low to Medium. Can become a long, unreadable chain (`data[:a][:b][:c]`) or verbose `with` block.
Conciseness Excellent. A single line of code for a complex operation. Poor. Requires multiple lines or nested structures for safe access.
Flexibility High. Works with any data structure implementing the `Access` behaviour. Low. Syntax is specific to the data type (e.g., `.` for structs, `[]` for maps).
Performance Slightly slower due to the overhead of function calls for each key in the path. Negligible in almost all web application contexts. Marginally faster for direct access, as it involves fewer function calls. Only relevant in extreme performance-critical hotspots.

Best Practices to Follow

  1. Prefer `get_in` for Reading Optional Data: Any time you are not 100% certain a key will exist, use `get_in`. Reserve direct access (`map[:key]`) for keys you know must be present (e.g., validated data from a database schema).
  2. Use `update_in` for Transformations: When you need to change a value based on its previous state (e.g., incrementing a counter, appending to a list), always reach for `update_in`. It's more expressive than a `get`, transform, and `put` sequence.
  3. Know When `put_in` Creates Paths: Remember that `put_in` will create nested maps if the path does not exist. This can be a powerful feature but might lead to unexpected data shapes if a key is misspelled.
  4. Don't Forget About Structs: While these macros work on maps out-of-the-box, they do not work on structs by default for safety reasons (structs have a defined set of keys). To use them with structs, you must explicitly use the `Access.key/2` helper or derive the `Access` behaviour in your struct definition if appropriate.

defmodule Player do
  defstruct [:name, :stats]
end

player_struct = %Player{name: "Luka Dončić", stats: %{points: 33.9}}

# This will FAIL because Player is a struct
# get_in(player_struct, [:stats, :points])

# This is the correct way for structs
import Kernel, except: [get_in: 2] # Avoid ambiguity
Access.get(player_struct, :stats) # Get the stats map first
|> get_in([:points]) # Then use get_in on the inner map

Your Learning Path: The Basketball Website Module

Now it's time to apply this knowledge. The core exercise in this kodikra module challenges you to implement functions that perform these very operations. By working through it, you will solidify your understanding and gain practical experience.

  • Learn Basketball Website step by step: In this hands-on module, you will build a set of functions to extract and organize data from a nested map representing information from a basketball website. This is the perfect practical test of your skills with `get_in`.

Completing this module will not only teach you the syntax but also the mindset required to effectively manipulate data in a functional, immutable way. It's a critical step on your journey to becoming a proficient Elixir developer. Continue your learning by exploring our complete Elixir guide.

Frequently Asked Questions (FAQ)

1. What is the difference between `put_in` and `update_in`?

put_in/3 takes a static value and places it at the target path, creating the path if it doesn't exist. update_in/3 takes a function, applies it to the existing value at the path, and uses the function's return value as the new value. If the path doesn't exist, update_in does nothing.

2. Why does `get_in` return `nil` instead of raising an error?

This is a core design choice for fault tolerance. In many cases, missing data is an expected state, not an exceptional one. Returning `nil` allows the program to continue and lets the developer handle the absence of a value gracefully, often using pattern matching or a `case` statement, without crashing the process.

3. Can I use these macros with lists of lists or other combinations?

Yes. The path is a list of keys or integer indexes. You can mix and match them to traverse any combination of nested maps and lists. For example, [:teams, 0, :players, 2, :name] is a perfectly valid path.

4. Is there a performance cost to using `get_in` over direct access?

Yes, there is a minor performance overhead because `get_in` has to iterate through the path and perform a function call for each key. However, this cost is almost always negligible in the context of a web application. The benefits of safety and readability far outweigh the micro-optimization of direct access unless you have identified a specific, performance-critical bottleneck in your code.

5. How do I provide a default value if `get_in` returns `nil`?

The idiomatic way to provide a default value is to use the `||` operator, which returns the right-hand side if the left-hand side is `nil` or `false`.


# Example: Default to 0 if points are not found
points = get_in(player_data, [:stats, :points]) || 0
6. What is `get_and_update_in`?

get_and_update_in/3 is another powerful macro in the family. It's like `update_in`, but it returns a tuple containing two elements: the value that was found at the path *before* the update, and the new data structure with the update applied. This is very useful when you need to know the old value and apply the change in a single atomic operation.

7. Can I create my own custom "path" elements for `get_in`?

Absolutely. The `Access` behaviour is the key. You can create custom functions that act as path elements. For example, `Access.all()` can be used in a path to update every element in a list, and `Access.key(:some_key, :default_value)` can be used to provide a default. This is an advanced topic but showcases the immense flexibility of the system.

Conclusion: Your New Superpower for Data Manipulation

Mastering get_in, put_in, and update_in is a significant milestone in your Elixir journey. These macros are more than just convenient helpers; they represent a fundamental shift towards writing safer, more declarative, and more maintainable code. By embracing this pattern, you move away from imperative, error-prone data access and adopt a functional approach that aligns perfectly with Elixir's philosophy of building robust, fault-tolerant systems.

You've learned the what, why, and how of these essential tools. You've seen their real-world applications in Phoenix and data pipelines and understand the best practices to avoid common pitfalls. Now, the next step is to put this theory into practice. Dive into the Basketball Website module from the exclusive kodikra.com curriculum and start building your muscle memory. As you progress, you'll find yourself reaching for these macros instinctively, leading to cleaner code and more resilient applications.

Disclaimer: All code examples and best practices are based on Elixir 1.16+ and are expected to be forward-compatible. The core concepts of the `Access` behaviour and `Kernel` macros are stable features of the language.

Published by Kodikra — Your trusted Elixir learning resource.

Post a Comment