---

Master Guessing Game in Gleam: Complete Learning Path

The Guessing Game is a foundational project in programming that teaches user interaction, state management, and control flow. This guide provides a comprehensive walkthrough of building it in Gleam, covering core concepts like I/O, random number generation, recursion, and robust error handling with Gleam's powerful type system.

---

Have you ever wanted to build something that feels alive, something that talks back to you? For many developers, that journey begins with a simple yet powerful project: the guessing game. It's the "Hello, World!" of interactive applications, a rite of passage that transforms abstract code into a tangible conversation between human and machine.

But building this classic game in a modern, functional language like Gleam offers a unique and enlightening experience. You're not just learning to handle input and print output; you're diving headfirst into concepts like immutability, type safety, and expressive pattern matching. This exclusive kodikra.com module will guide you from zero to hero, showing you how to leverage Gleam's features to write code that is not only correct but also clean, readable, and incredibly robust.

What is the Guessing Game Project?

At its heart, the Guessing Game is a simple command-line application with a clear objective. The program first thinks of a secret random number within a predefined range (e.g., 1 to 100). It then repeatedly prompts the user to guess what that number is.

After each guess, the program provides feedback: it tells the user if their guess was too high, too low, or correct. This cycle continues until the user successfully guesses the secret number, at which point the program congratulates them and terminates. It's a fundamental exercise in building a feedback loop, a core pattern in all interactive software.

While the logic is straightforward, implementing it touches upon several critical programming skills. You'll learn to manage program flow, process user input, convert data types, compare values, and handle potential errors gracefully. It’s a perfect microcosm of a larger application's lifecycle.

---

Why Build This in Gleam?

Choosing Gleam for this project isn't just about learning a new syntax; it's about embracing a different, more disciplined way of thinking about software. Gleam runs on the Erlang BEAM, the same virtual machine that powers ultra-reliable systems like WhatsApp. This heritage brings significant advantages, even to a small project like this.

• Unshakeable Type Safety: Gleam's static type system is your guardian angel. It catches a huge class of errors at compile time, long before your users ever see them. You'll never have to worry about a "5" being accidentally added to the number 10; the compiler simply won't allow it. This forces you to handle data conversions explicitly and safely.
• Explicit Error Handling with Result: Forget about unexpected null exceptions. In Gleam, operations that can fail (like parsing a string into an integer) return a Result(ok_value, error_value) type. This makes error handling a mandatory and visible part of your code, leading to far more resilient applications.
• Functional Purity & Immutability: By default, all data in Gleam is immutable. You don't change variables; you create new ones. This eliminates complex bugs related to shared mutable state and makes your program's logic much easier to reason about. The game loop will be implemented with recursion, a cornerstone of functional programming.
• Clean, Readable Syntax: Gleam's syntax is inspired by languages like Elm, Rust, and Go, prioritizing clarity and simplicity. This makes your code a pleasure to write and, more importantly, easy for others (and your future self) to read and understand.
• Seamless Erlang & Elixir Interop: Gleam doesn't reinvent the wheel. For functionalities like random number generation, you can effortlessly call battle-tested functions from Erlang's massive standard library using Gleam's Foreign Function Interface (FFI). This gives you immense power right out of the box.

By building the Guessing Game in Gleam, you are internalizing best practices that are highly valued in the world of robust, scalable backend systems.

---

How the Gleam Guessing Game Works: A Deep Dive

Let's deconstruct the project into its essential components. We'll explore the Gleam-specific code and patterns required for each step. The entire logic will be structured around a recursive function that acts as our main game loop.

Step 1: Setting Up the Project

First, ensure you have Gleam installed. You can create a new project with the Gleam CLI. This command scaffolds a new Gleam application with the necessary file structure and build configuration.

# Create a new Gleam project
gleam new guessing_game

# Navigate into the project directory
cd guessing_game

# Add the gleam_stdlib for extra utilities if needed
gleam add gleam_stdlib

Your main logic will reside in the src/guessing_game.gleam file. The entry point for any Gleam application is the main function.

Step 2: Generating a Secret Number

Gleam's standard library is intentionally minimal. For functionality like generating cryptographically secure random numbers, we tap into the underlying Erlang runtime. We'll define an external function using Gleam's FFI to call Erlang's crypto:strong_rand_uniform/1 function.

In src/guessing_game.gleam, you'll start by defining this external function and your main function.

// Import necessary functions
import gleam/io
import gleam/int
import gleam/result

// Define an external Erlang function using FFI
// This function takes an integer `N` and returns a random integer from 0 to N-1.
@external(erlang, "crypto", "strong_rand_uniform")
fn random_uniform(max: Int) -> Int

pub fn main() {
  // We want a number from 1 to 100.
  // Erlang's function is 0-based, so we ask for a number up to 99 (0-99)
  // and then add 1 to the result.
  let secret_number = random_uniform(100) + 1
  
  io.println("I've picked a number between 1 and 100. Try to guess it!")
  
  // Start the game loop
  game_loop(secret_number)
}

Here, the @external attribute tells the Gleam compiler that random_uniform is implemented elsewhere (in the crypto module of Erlang). This is a powerful feature for leveraging the entire BEAM ecosystem.

ASCII Diagram: Overall Game Flow

This diagram illustrates the high-level execution flow of our application, from start to finish.

    ● Start
    │
    ▼
  ┌────────────────────────┐
  │ main() function called │
  └───────────┬────────────┘
              │
              ▼
    ┌────────────────────┐
    │ Generate Secret    │
    │ Number (1-100)     │
    └──────────┬─────────┘
               │
               ▼
    ┌────────────────────┐
    │ Call game_loop()   │
    │ with secret number │
    └──────────┬─────────┘
               │
               ▼
          [Recursive Game Loop]
               │
               ▼
    ┌────────────────────┐
    │ Print "Correct!"   │
    └──────────┬─────────┘
               │
               ▼
            ● End

Step 3: The Recursive Game Loop

In functional programming, loops are typically implemented with recursion. We'll create a game_loop function that takes the secret number as an argument. Inside this function, it will prompt for input, process it, and then—crucially—call itself again to continue the loop until the correct number is guessed.

fn game_loop(secret_number: Int) {
  io.print("Please input your guess: ")
  
  // Read a line of input from the user
  let input = io.read_line()
  
  // The 'use' keyword is syntactic sugar for handling Results.
  // It unwraps the Ok value or returns early with the Error.
  // Here we chain operations that can fail.
  use guess <- result.try(
    // 1. Trim whitespace from the input string
    string.trim(input)
    // 2. Try to parse the string into an integer
    |> int.parse()
  )

  // Compare the guess with the secret number
  case int.compare(guess, secret_number) {
    // The Order type has three possible values: Less, Greater, or Equal
    Less -> {
      io.println("Too low!")
      game_loop(secret_number) // Recurse to continue the game
    }
    Greater -> {
      io.println("Too high!")
      game_loop(secret_number) // Recurse to continue the game
    }
    Equal -> {
      io.println("You win! The number was indeed " <> int.to_string(secret_number) <> ".")
      // Don't recurse, ending the loop
    }
  }
}

Let's break down the key Gleam features used here:

• io.read_line(): This function reads from standard input and returns a String.
• The Pipe Operator |>: This operator takes the result of the expression on its left and passes it as the first argument to the function on its right. It makes data transformation pipelines incredibly readable.
• int.parse(): This is where Gleam's safety shines. It doesn't just return an integer. It returns a Result(Int, ParseIntError). If the user types "hello", it returns an Error, preventing your program from crashing.
• case Expression: This is Gleam's powerful pattern matching construct. We use it to compare the user's guess to the secret number. The int.compare function returns an Order type, which can be Less, Greater, or Equal. The case expression lets us handle each possibility cleanly and exhaustively.
• Recursion: Notice how game_loop calls itself in the Less and Greater branches. This is the recursive call that keeps the game going. When the guess is Equal, the function simply returns, breaking the chain of calls and ending the game.

ASCII Diagram: Recursive Loop Logic

This diagram details the decision-making process inside a single iteration of our game_loop function.

    ● Enter game_loop(secret)
    │
    ▼
  ┌──────────────────┐
  │ Prompt for guess │
  └────────┬─────────┘
           │
           ▼
  ┌──────────────────┐
  │ Read User Input  │
  │ (as String)      │
  └────────┬─────────┘
           │
           ▼
    ◆ Parse to Int?
   ╱               ╲
 Ok(guess)         Error
  │                   │
  ▼                   ▼
┌───────────┐      ┌──────────────────┐
│ case guess <=> secret │      │ Print error msg  │
└─────┬─────┘      │ & Recurse        │
      │              └──────────────────┘
      ▼
  ┌───────────┬───────────┬───────────┐
  │ Less      │ Greater   │ Equal     │
  ▼           ▼           ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ "Too low" │ "Too high"│ Exit Loop │
│ & Recurse │ & Recurse │ (Return)  │
└─────────┘ └─────────┘ └─────────┘

Step 4: Handling Invalid Input

What if the user types "cat" instead of a number? Our current code using result.try would cause the function to exit immediately. We can make it more user-friendly by explicitly handling the Error case from int.parse.

Let's refine the game_loop function to give the user a helpful message.

fn game_loop(secret_number: Int) {
  io.print("Please input your guess: ")
  let input = io.read_line()

  // Instead of 'use', we'll use a 'case' expression on the result
  case int.parse(string.trim(input)) {
    // If parsing is successful, we get Ok(guess)
    Ok(guess) -> {
      case int.compare(guess, secret_number) {
        Less -> {
          io.println("Too low!")
          game_loop(secret_number)
        }
        Greater -> {
          io.println("Too high!")
          game_loop(secret_number)
        }
        Equal ->
          io.println("You win!")
      }
    }
    // If parsing fails, we get an Error
    Error(_) -> {
      io.println("That's not a valid number. Please try again.")
      // We still recurse to give the user another chance
      game_loop(secret_number)
    }
  }
}

This version is more robust. It catches the parsing error, informs the user, and then calls game_loop again, effectively asking for input again without crashing or exiting the program. This demonstrates the power of handling the Result type explicitly.

---

Where This Pattern is Applied (Real-World Applications)

The core loop of "prompt, read, validate, process" is everywhere in software engineering. While a guessing game is simple, the skills you learn are directly transferable to more complex applications:

• Interactive Command-Line Tools (CLIs): Any tool that asks a user for configuration settings, confirmation (y/n), or data input uses this exact pattern.
• Data Validation & Sanitization: The process of parsing a string to an integer and handling the error is a form of data validation. This is critical in web backends when processing form data or API requests.
• Simple Bots (Discord, Slack): A bot that waits for a command, parses it, and then acts upon it is following a more advanced version of this loop.
• ATMs and Kiosks: The software on an ATM follows a stateful loop: wait for card, prompt for PIN, validate, show menu, process transaction, repeat.
- Wizard-style Installers: Software installers that guide you through multiple steps (Next, Next, Finish) are built on this sequential input-and-process model.

Mastering this fundamental loop in Gleam prepares you to build reliable, interactive systems that don't fall over at the first sign of unexpected input.

---

Pros & Cons of This Approach

Every project is a learning tool with its own strengths and limitations. Understanding these helps you see the bigger picture and know what to learn next.

Pros (Strengths of this Project)	Cons (Limitations & Next Steps)
Excellent Introduction to I/O: Provides hands-on experience with reading from and writing to the console, a fundamental skill.	Stateless Nature: The game has no memory. It can't track high scores or the number of guesses without adding more complexity.
Reinforces Type Safety: Forces you to deal with data conversions (String to Int) and error handling via the Result type.	Blocking I/O: The io.read_line() call blocks the entire program. This is fine here but unsuitable for high-concurrency servers.
Practical Use of Recursion: A perfect, easy-to-understand example of how recursion is used for looping in functional languages.	Single-player Only: The current architecture doesn't support multiplayer functionality.
Introduces FFI: Shows how to leverage powerful libraries from the host platform (Erlang) to extend Gleam's capabilities.	No GUI: It's a command-line-only application, which limits its user-friendliness for a non-technical audience.

---

The Kodikra Learning Path Module

You are now ready to apply these concepts by building the project yourself. The following kodikra module provides a complete, test-driven environment to guide you through the implementation step by step, ensuring you master each concept before moving on.

• Guessing Game: This is the core challenge. You will implement the full logic discussed above, from generating a random number to handling user input in a robust, recursive loop. This exercise solidifies your understanding of I/O, error handling, and control flow in Gleam.

  Learn Guessing Game step by step

Completing this module from the exclusive kodikra.com curriculum will give you the confidence and foundational skills needed to tackle more complex challenges in Gleam and functional programming.

---

Frequently Asked Questions (FAQ)

Why use recursion instead of a `while` loop in Gleam?

Gleam, like many functional languages, does not have traditional for or while loop statements. It favors recursion and higher-order functions (like list.map) for iteration. Recursion, especially when optimized by the compiler (Tail Call Optimization), is a powerful and expressive way to handle looping logic without mutable state, which aligns with functional programming principles.

How does Gleam's `Result` type improve code quality?

The Result(Ok, Error) type makes potential failures explicit in a function's signature. It forces the programmer to acknowledge and handle both the success and failure paths. This eliminates an entire class of bugs common in other languages, such as null pointer exceptions or unhandled errors, leading to more robust and predictable code.

What is FFI and why is it needed for random numbers here?

FFI stands for Foreign Function Interface. It's a mechanism that allows a program written in one language to call functions from another language. We use it here because Gleam's standard library is kept lean and focused. Instead of reinventing a secure random number generator, Gleam provides an easy way to use the highly optimized, battle-tested one that already exists in its host platform, Erlang.

Can I build a web version of this game with Gleam?

Yes, absolutely! While this module focuses on the command line, Gleam can also compile to JavaScript. You could use a Gleam web framework like Lustre to build the front-end logic for this game, running it entirely in the browser. For a backend, you could use a Gleam web server framework like Wisp to handle game logic on the server.

What is Tail Call Optimization (TCO)?

TCO is a compiler optimization where a recursive function call at the very end of a function is transformed into a simple jump, much like a loop. This prevents the call stack from growing with each recursive call, avoiding a "stack overflow" error. The Erlang BEAM (and thus Gleam) has excellent support for TCO, making recursion a safe and efficient way to write loops.

What are the best next steps after completing this module?

After mastering the Guessing Game, a great next step is to explore concepts that build upon it. Try modifying the game to track the number of guesses. Then, move on to other kodikra modules that introduce data structures like lists and records, or explore building a simple web server with Wisp. See the complete Gleam guide for more learning paths.

---

Conclusion: Your First Interactive Gleam App

You have now journeyed through the core logic and philosophy of building a simple interactive application in Gleam. The Guessing Game is more than just a toy project; it's a practical lesson in writing safe, explicit, and functional code. You've learned how to handle user I/O, leverage the Erlang ecosystem through FFI, manage errors gracefully with the Result type, and implement control flow using recursive functions.

These skills are the bedrock of creating reliable software. As you continue your journey with the Gleam learning path on kodikra.com, you will find these patterns repeating in more complex and powerful applications. The discipline that Gleam instills from the very beginning will pay dividends throughout your programming career.

Disclaimer: All code examples are written for Gleam v1.x and are compatible with Erlang/OTP 26+. The Gleam ecosystem is actively developing, so always consult the official documentation for the latest updates and best practices.

---

Published by Kodikra — Your trusted Gleam learning resource.