Master Tisbury Treasure Hunt in Gleam: Complete Learning Path

The Tisbury Treasure Hunt module is a core part of the Kodikra Gleam curriculum, designed to teach fundamental functional programming concepts through an engaging, narrative-driven challenge. It focuses on mastering data structure traversal, pattern matching, and recursion—three pillars of writing elegant, robust, and idiomatic Gleam code.

The Challenge: Lost in a Maze of Data

Have you ever found yourself staring at a deeply nested JSON response from an API, a complex configuration file, or a convoluted state object in your application? It can feel like being lost in a labyrinth. Your goal is simple—extract one specific piece of information—but the path is obscured by layers of objects, arrays, and inconsistent structures. Traditional imperative loops and conditional chains quickly become a tangled mess of `if/else` statements, making the code hard to read, debug, and maintain.

This struggle is a common pain point for developers transitioning to functional languages. The tools and thought processes are different. This is where the Tisbury Treasure Hunt module shines. It transforms this frustrating challenge into an exciting adventure. Instead of fighting with complex data, you'll learn to navigate it with precision and grace, using Gleam's powerful features to write code that is not only correct but also beautifully expressive.

What is the Tisbury Treasure Hunt Module?

The Tisbury Treasure Hunt is a practical coding challenge from the exclusive Kodikra learning path that simulates searching for a hidden treasure within a complex, nested map. The map isn't a simple grid; it's a recursive data structure where each location can contain other locations, creating a tree-like hierarchy. Your task is to write a Gleam function that can traverse this map and find the treasure's location.

At its core, this module is a vehicle for teaching you how to think functionally about data traversal. It forces you to abandon traditional loops in favor of more declarative and safer techniques like pattern matching and recursion. You'll work with custom data types, a cornerstone of Gleam's static typing, to model the problem domain accurately.

The Core Data Structures

Before you can find the treasure, you must understand the map. The problem is defined using Gleam's custom types, which provide compile-time guarantees about the shape of your data. This is a massive advantage, as it eliminates entire classes of runtime errors.

Here are the essential types you'll work with:

// The treasure you're looking for
pub type Treasure {
  AztecGold
}

// The different types of locations on the map
pub type Location {
  Pub
  Well
  Oak
}

// The main map structure, which is recursive
pub type Quadrant {
  // A direct location that might hold the treasure
  Plain(Location, Treasure)
  // A location that points to another quadrant (the recursive part)
  Quadrant(Location, Quadrant)
  // A location that branches into four sub-quadrants
  Quarters(Location, Quadrant, Quadrant, Quadrant, Quadrant)
}

Notice the recursive nature of the Quadrant type. A Quadrant can contain another Quadrant, which can contain more quadrants, and so on. This elegant structure perfectly models the nested nature of the treasure map and is the key to the entire challenge.

Why Mastering This Module is Crucial for Your Gleam Journey

While finding a fictional treasure is fun, the skills you acquire in this module are directly applicable to real-world software development. The patterns used here are not academic exercises; they are the bread and butter of professional Gleam programming.

Mastering this module will equip you to:

Parse Complex API Responses: Modern web applications frequently consume JSON APIs with deep, nested structures. Pattern matching is the most effective way to safely destructure these responses and extract the data you need.
Manage Application State: In state management patterns (like those found in front-end frameworks or server-side applications), the application state is often a complex tree. Updating this state immutably often involves traversing it, a task perfectly suited for recursion.
Build Compilers and Interpreters: At the heart of any language processor is an Abstract Syntax Tree (AST). Traversing and transforming this tree to generate code or interpret it involves the exact recursive patterns you'll learn here.
Write Safer, More Declarative Code: Gleam's compiler can check your pattern matching for exhaustiveness. This means it can warn you if you've forgotten to handle a possible case, preventing subtle bugs that might otherwise only appear at runtime. This leads to incredibly robust and self-documenting code.

Ultimately, this module teaches you to "think in Gleam." It moves you away from an imperative mindset ("do this, then do that") to a declarative one ("if the data looks like this, the result is that"). This shift is fundamental to unlocking the full power of functional programming.

How to Solve the Treasure Hunt: The Core Logic Explained

The solution to the Tisbury Treasure Hunt hinges on two primary Gleam features: the case expression for pattern matching and recursive function calls for traversal. Let's break down how these pieces fit together.

The Power of Pattern Matching with `case`

A case expression in Gleam allows you to inspect the structure of a value and execute different code branches based on which pattern it matches. It's like a super-powered `switch` statement that can destructure complex data types.

For the treasure hunt, your main function will take a Quadrant and use a case expression to determine what kind of quadrant it is.

import tisbury.{Quadrant, Location, Treasure}

pub fn find_treasure(quadrant: Quadrant) -> #(Location, Treasure) {
  case quadrant {
    // What goes here?
  }
}

You'll need to fill in the patterns for each variant of the Quadrant type:

The `Plain` case: This is your "base case." If the quadrant is a `Plain`, it contains the treasure directly. You've found it! You can extract the Location and Treasure and return them.
The `Quadrant` case: This is a recursive step. If the quadrant is a `Quadrant`, it contains another quadrant. The treasure isn't here, but you know where to look next. You must call your `find_treasure` function again on the inner quadrant.
The `Quarters` case: This is the most complex recursive step. The quadrant branches into four sub-quadrants. You must search each one. This often involves calling your `find_treasure` function on each of the four inner quadrants.

ASCII Logic Flow: Recursive Traversal

The logic for traversing the map can be visualized as a recursive descent. The function dives deeper into the structure until it hits a `Plain`, which is the base case that stops the recursion.

    ● Start with a Quadrant
    │
    ▼
  ┌───────────────────┐
  │ find_treasure(q)  │
  └─────────┬─────────┘
            │
            ▼
    ◆ What is q's type?
   ╱         │         ╲
 Plain   Quadrant(inner)  Quarters(q1,q2,q3,q4)
  │            │                    │
  ▼            │                    ▼
┌─────────┐    │              ┌───────────────────┐
│ Success!│    └─────⟶ Recurse │ find_treasure(q1) │
│ Return  │            on inner │ find_treasure(q2) │
│ Treasure│                     │ ...               │
└─────────┘                     └───────────────────┘

Embracing Recursion

Recursion is when a function calls itself. In functional programming, it's the standard way to perform repetitive tasks on data structures, especially tree-like ones. The treasure map is a perfect example of a tree.

A correct recursive function has two essential parts:

Base Case(s): A condition that stops the recursion. In our case, it's finding a Plain(location, treasure). Without a base case, the function would call itself forever, leading to a stack overflow.
Recursive Step(s): The part of the function that calls itself, but with a "smaller" or "simpler" version of the problem. Here, it's calling find_treasure on an inner quadrant, which brings us one step closer to the base case.

Here's a simplified skeleton of the recursive logic within the `case` expression:

pub fn find_treasure(quadrant: Quadrant) -> #(Location, Treasure) {
  case quadrant {
    // Base Case: We found the treasure!
    Plain(location, treasure) -> #(location, treasure)

    // Recursive Step 1: Look inside the next quadrant
    Quadrant(_, next_quadrant) -> find_treasure(next_quadrant)

    // Recursive Step 2: This one is more complex.
    // You'll need to search all four sub-quadrants.
    // Gleam's `result.try` or a series of calls might be needed.
    Quarters(_, q1, q2, q3, q4) -> {
      // Logic to search q1, then q2, etc.
      // This is the heart of the challenge!
      // A common pattern is to try each one until a result is found.
      find_treasure(q1) 
      // This is not complete code, but illustrates the idea.
    }
  }
}

The beauty of this approach is its declarative nature. The code reads like a description of the data structure itself, making it far more intuitive to understand than a complex series of nested loops and flags.

The Learning Path: Your Capstone Challenge

This module centers around a single, comprehensive exercise that ties all these concepts together. By completing it, you will have demonstrated a solid understanding of some of Gleam's most powerful features.

Learn Tisbury Treasure Hunt step by step
This is the capstone challenge. You will be given the data type definitions and tasked with implementing the find_treasure function. Success requires a perfect blend of pattern matching on custom types and correct application of recursion to navigate the nested data structure. It's a fantastic way to solidify your functional programming mindset.

Where These Concepts Are Applied in the Real World

The skills from the Tisbury Treasure Hunt are not confined to puzzles. They are essential for building robust, real-world applications with Gleam.

Web Backends: When building a web server, you'll constantly deal with incoming data (JSON payloads, query parameters) and internal state. Pattern matching is the safest way to validate and destructure this data. For example, processing a webhook from a service like Stripe or GitHub involves matching on an `event_type` field and handling the corresponding data payload.
Data Processing Pipelines: Imagine a pipeline that ingests logs. Each log entry can have a different structure (e.g., `Info`, `Warning`, `Error(details)`). A recursive function with pattern matching can process a stream of these logs, transforming them, filtering them, or aggregating statistics.
Front-end Development (via Gleam/Lustre): In frameworks that use a centralized state store (like Elm, Redux, or Lustre for Gleam), the application state is a single, large data structure. When an action occurs (e.g., a button click), a reducer function uses pattern matching to determine how to update the state immutably. This often involves recursively updating a nested part of the state tree.
Tooling and Compilers: As mentioned, parsing source code generates an Abstract Syntax Tree (AST). Tools like formatters, linters, or compilers must walk this tree to perform their tasks. This is almost always done with a set of mutually recursive functions that pattern match on the different types of nodes in the AST (`FunctionDeclaration`, `VariableAssignment`, `IfExpression`, etc.).

ASCII Logic Flow: Pattern Matching Decision Tree

This diagram shows how a `case` expression acts as a clean decision tree for handling different data shapes, which is fundamental to the applications above.

      ● Input Data (e.g., Quadrant, API Response)
      │
      ▼
  ┌───────────┐
  │   case    │
  └─────┬─────┘
        │
┌───────┴───────┐
│ Pattern Match │
└───────┬───────┘
        │
◆ Shape A? ├─⟶ Execute Logic A
        │
◆ Shape B? ├─⟶ Execute Logic B
        │
◆ Shape C? ├─⟶ Execute Logic C
        │
◆ _ (default)? ├─⟶ Handle Fallback
        │
        ▼
      ● Result

Best Practices and Common Pitfalls

As you tackle this module, keep these tips and potential traps in mind. They will help you write cleaner code and avoid common frustrations.

Pros and Cons of This Approach

Every architectural pattern has trade-offs. Understanding them is key to being an effective engineer.

Pros (Why We Use This Pattern)	Cons / Risks (What to Watch Out For)
Compile-Time Safety: Gleam's exhaustiveness checking for `case` expressions prevents you from forgetting a possible data variant, eliminating a huge category of runtime errors.	Stack Overflow Risk: With extremely deep data structures (thousands of levels), a naive recursive function can exceed the call stack limit. Gleam on the BEAM mitigates this with Tail Call Optimization (TCO), but you must structure your code correctly to benefit from it.
High Readability: The code structure mirrors the data structure it operates on. This makes the logic self-documenting and easier to reason about compared to imperative loops with complex conditions.	Initial Learning Curve: For developers coming from an object-oriented or imperative background, thinking recursively and declaratively can take some getting used to.
Immutability by Default: This pattern works seamlessly with immutable data, which is the default in Gleam. This avoids side effects and makes code easier to test and parallelize.	Performance Overheads: In some very specific, performance-critical scenarios, a highly optimized iterative solution might outperform a recursive one due to function call overhead (though this is less of a concern on the BEAM VM).

Common Pitfalls

Forgetting the Base Case: The most common mistake in recursion. If you don't have a condition to stop the function from calling itself, you'll get an infinite loop and a stack overflow error. Always write your base case first!
Non-Exhaustive Patterns: While the Gleam compiler is excellent at catching this, you can sometimes write logic that assumes a certain structure which might not hold true. Always consider every possible variant of your custom types.
Incorrectly Passing State: In more complex recursive functions, you might need to pass along an "accumulator" or some other state. Forgetting to pass the updated state in the recursive call is a frequent source of bugs. (This is less of a concern in the basic treasure hunt, but crucial in more advanced problems).

Frequently Asked Questions (FAQ)

What exactly is pattern matching in Gleam?: Pattern matching is a mechanism for checking a value against a series of patterns. If a pattern matches, the code associated with that pattern is executed. It's more powerful than a simple `switch` statement because it can also destructure data, binding parts of the value to new variables. For example, the pattern `Plain(location, treasure)` not only checks if the value is a `Plain` variant but also extracts its contents into the `location` and `treasure` variables.
Why use recursion instead of a `for` or `while` loop for this problem?: Gleam, like many functional languages, doesn't have traditional `for` or `while` loops. Recursion is the idiomatic way to perform iteration. More importantly, recursion is a more natural fit for traversing recursive data structures like trees or the treasure map. The code's structure elegantly mirrors the data's structure, which is much harder to achieve with a flat loop.
What is a "base case" in recursion and why is it so important?: A base case is the condition that terminates a recursive function. It's the "bottom" of the recursive calls. In the Tisbury Treasure Hunt, the base case is when the quadrant is a `Plain`. This is the point where the treasure is found, and the function can return a value directly without calling itself again. Without a base case, the function would call itself indefinitely, leading to a stack overflow error.
How does Gleam's type system help in the Tisbury Treasure Hunt?: Gleam's static type system provides guarantees before you even run your code. By defining the `Quadrant`, `Location`, and `Treasure` types, you tell the compiler exactly what the "map" can look like. This allows the compiler to perform exhaustiveness checking on your `case` expressions, ensuring you've handled every possible shape of the `Quadrant` type. This prevents entire classes of runtime errors, like trying to access a field that doesn't exist.
Is it possible to solve this problem without recursion?: Yes, it's technically possible to solve tree traversal problems iteratively using an explicit stack data structure to keep track of the nodes to visit. However, this approach is almost always more complex and less readable in a functional language like Gleam. The language and its ecosystem are designed around recursion, and the BEAM VM (which Gleam compiles to) is highly optimized for it through Tail Call Optimization.
What is the BEAM VM and why is it good for recursion?: The BEAM is the virtual machine that powers Erlang, Elixir, and Gleam (on the Erlang target). It was designed from the ground up for concurrent and highly reliable systems. One of its key features is Tail Call Optimization (TCO). When a function's very last action is to call itself (a "tail call"), the BEAM can reuse the current stack frame instead of creating a new one. This turns the recursion into a loop under the hood, allowing for infinite recursion without ever running out of memory (i.e., no stack overflow).
How does this module prepare me for more advanced Gleam topics?: Mastering data structures, pattern matching, and recursion is the foundation for almost everything else in Gleam. These skills are prerequisites for understanding more advanced topics like working with OTP (for building concurrent applications), processing data streams, and implementing complex business logic in a robust and maintainable way.

Conclusion: Your Adventure Awaits

The Tisbury Treasure Hunt module is more than just a coding puzzle; it's a fundamental lesson in functional problem-solving. By completing it, you will have gained proficiency in three of Gleam's most critical features: custom types, pattern matching, and recursion. You will have shifted your mindset from an imperative "how-to" approach to a declarative "what-is" approach, which is the key to writing clean, safe, and expressive functional code.

The patterns you learn here will appear again and again in your journey. They are the tools you will use to build robust servers, parse complex data, and manage application state with confidence. Now, it's time to embark on the hunt.

Disclaimer: All code examples are based on the latest stable version of Gleam at the time of writing. Language features and syntax may evolve in future versions.

Back to Gleam Guide

Published by Kodikra — Your trusted Gleam learning resource.

kodikra

Search this blog

Master Tisbury Treasure Hunt in Gleam: Complete Learning Path