Results, Options, and Error Handling

Errors as Values

• Python raises an exception when something goes wrong and expects callers to catch it with try/except
• But nothing in the type signature tells you whether a function might raise or what kind of exception to expect
• In Gleam, a function that might fail returns a Result, and the type signature makes that explicit
• Result(a, e) is a type with two variants:
  • Ok(value) carries a successful result
  • Error(reason) carries a failure description
• The type of reason is up to you
  • While String is convenient for examples, Gleam developers usually prefer an explicit custom error type so that the compiler can check that every error case is handled
  • A custom error type is just another type definition:
• A caller cannot use the value inside Ok without handling the Error case
  • The compiler enforces this

Parsing and Dividing Safely

fn parse_int(s: String) -> Result(Int, String) {
  case int.parse(s) {
    Ok(n) -> Ok(n)
    Error(_) -> Error("not an integer: " <> s)
  }
}

• int.parse(s) from the standard library returns Result(Int, Nil)
  • It returns Ok(n) if the string is a valid integer
  • It returns Error(Nil) if not; the error carries no information
• The function wraps the result to provide a String error message instead
• Compare to Python's int(s)
  • Raises ValueError on bad input
  • But no way to know this from the function's type

fn safe_divide(a: Int, b: Int) -> Result(Int, String) {
  case b {
    0 -> Error("division by zero")
    _ -> Ok(a / b)
  }
}

Ok(42)
Error("not an integer: not a number")
Ok(5)
Error("division by zero")

• safe_divide returns Error("division by zero") instead of crashing with a ZeroDivisionError
• The case b { 0 -> … _ -> … } pattern is idiomatic for this kind of guard
• Any caller that uses safe_divide must handle both Ok and Error

Transforming Results

• Often want to apply a function to the value inside Ok without unwrapping it manually
• result.map(r, f) applies f to the value inside Ok and rewraps it
• result.try(r, f) is similar but f returns a Result, so the double-wrapping Ok(Ok(v)) is avoided
  • Most Gleam developers use result.try more often than result.map
• result.map_error transforms the error value in Error
• result.unwrap extracts the value from Ok or returns a default

  io.println(string.inspect(ok_int(42) |> result.map(fn(x) { x + 1 })))
  io.println(string.inspect(error_str("oops") |> result.map(fn(x) { x + 1 })))

Ok(43)
Error("oops")

• result.map(r, f) applies f to the value inside Ok(v) and returns Ok(f(v))
  • If r is Error(e), result.map returns Error(e) unchanged
• This avoids a case expression when you only care about the success path

The Option Type

• Option(a) is a type with two variants
  • Some(value) wraps a present value
  • None represents absence
• Option is used mostly for optional fields in records and optional function parameters
  • For return types that might fail, Result is usually preferred
  • Result can carry an error message; Option cannot

fn option_inspect(opt: option.Option(Int)) -> String {
  case opt {
    option.Some(n) -> "got " <> int.to_string(n)
    option.None -> "nothing"
  }
}

• Option(Int) is exactly like Python's Optional[int]
• case opt { Some(n) -> ... None -> ... } is the standard way to unwrap it
• The compiler will not let you use n outside the Some arm

fn first_positive(nums: List(Int)) -> option.Option(Int) {
  case nums {
    [] -> option.None
    [x, ..] if x > 0 -> option.Some(x)
    [_, ..rest] -> first_positive(rest)
  }
}

"got 42"
"nothing"
Some(99)
None
Some(3)
None

• [x, .._rest] if x > 0 combines a list pattern with a guard
  • If the head x is positive, return Some(x) immediately
  • Otherwise, recurse on the tail
• An empty list or an all-negative list reaches [] -> None
• This is equivalent to Python's next((x for x in items if x > 0), None) but the return type makes the "might be absent" case explicit

Guidelines for Handling Errors

• Return Result whenever a function might fail for an externally visible reason (e.g., bad input, missing file, or network error)
• Return Option when absence is the only failure mode
• Use let assert Ok(x) = ... only when failure truly cannot happen (like initialising a known-good constant at startup)
  • It panics on Error
  • Unlike Python's assert, which is a statement that checks a condition, Gleam's let assert matches a pattern and creates a variable

  let assert Ok(n) = int.parse("42")
  io.println("parsed: " <> int.to_string(n))

parsed: 42

• Use result.try and result.map for short transformations
• Prefer custom error types over String for the error type in non-trivial programs

A Note on Assertions

• Gleam also allows bare assertions like assert left == right
  • Panics if the condition is not true
• Used less often than the let assert form
  • Most functions return Result, and if it's Ok(val), we usually want the value
• Discussed more in the section on modules

Check Understanding

Exercises