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
  • It can be a String, a custom error type, or anything else
• 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 does exactly that.

  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

fn option_inspect(opt: Option(Int)) -> String {
  case opt {
    Some(n) -> "got " <> int.to_string(n)
    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(Int) {
  case nums {
    [] -> None
    [x, .._rest] if x > 0 -> 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 lst if x > 0), None) but the return type makes the "might be absent" case explicit

Chaining with use

• When you have several operations that each return Result, nesting case expressions becomes unpleasant quickly
• use is syntactic sugar that flattens this nesting

  let result = {
    use x <- result.try(parse_int("10"))
    use y <- result.try(parse_int("20"))
    use z <- result.try(safe_divide(x + y, 3))
    Ok(z * 2)
  }
  io.println(string.inspect(result))

• use x <- result.try(parse_int("10")) is equivalent to:

case parse_int("10") {
  Ok(x) -> ...rest of block...
  Error(e) -> Error(e)
}

• Reading top to bottom: parse 10, parse 20, divide their sum by 3, double the result
• Each use line binds a name from the Ok value or short-circuits with the Error
• The final expression Ok(z * 2) is the result of the whole block

  let fail = {
    use x <- result.try(parse_int("10"))
    use y <- result.try(parse_int("bad"))
    use z <- result.try(safe_divide(x + y, 3))
    Ok(z * 2)
  }
  io.println(string.inspect(fail))

Ok(20)
Error("not an integer: bad")

• parse_int("bad") returns Error("not an integer: bad")
• The use expression short-circuits at that point
  • safe_divide is never called
  • The whole block evaluates to Error("not an integer: bad")
• Analogous to Python's try/except, but the short-circuiting is explicit in the types rather than hidden in the runtime

Guidelines for Handling Errors

• Return Result whenever a function might fail for an externally visible reason (bad input, missing file, 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
• Use result.map and result.try for short transformations
• Use use for chains of three or more fallible operations

Check Understanding

Exercises