The use Expression

The Nesting Problem

• When you call several functions that each return Result, you need to unwrap each one before using it
• A single case is fine; three in a row is hard to read

  let ok_result = case parse_int("30") {
    Error(reason) -> Error(reason)
    Ok(total) ->
      case parse_int("6") {
        Error(reason) -> Error(reason)
        Ok(divisor) ->
          case safe_divide(total, divisor) {
            Error(reason) -> Error(reason)
            Ok(quotient) -> validate_positive(quotient)
          }
      }
  }
  io.println(string.inspect(ok_result))

Ok(5)
Error("division by zero")

• parse_int converts a string to an integer, returning Error if the string is invalid
• safe_divide divides two integers, returning Error if the denominator is zero
• validate_positive checks that a number is positive, returning Error if it is not
• Every step adds another level of indentation
  • The actual computation (validate_positive(quotient)) is buried at the innermost level
• When any step fails, every outer Error(reason) -> Error(reason) arm just re-wraps and propagates the same error without adding any information

  let err_result = case parse_int("30") {
    Error(reason) -> Error(reason)
    Ok(total) ->
      case parse_int("0") {
        Error(reason) -> Error(reason)
        Ok(divisor) ->
          case safe_divide(total, divisor) {
            Error(reason) -> Error(reason)
            Ok(quotient) -> validate_positive(quotient)
          }
      }
  }
  io.println(string.inspect(err_result))

• Replacing "6" with "0" causes safe_divide to return an error
  • The two outer arms still just pass the error along unchanged

Flattening with use

• use rewrites nested callback as a flat sequence of steps
  • This is called syntactic sugar because it sweetens the language
  • Translating the easy-to-read form into the basic form is called desugaring
  • This is what passes for wit among language designers
• result.try(result, callback) calls callback with the value inside Ok(x), or returns Error unchanged without calling the callback at all

  let ok_result = {
    use total <- result.try(parse_int("30"))
    use divisor <- result.try(parse_int("6"))
    use quotient <- result.try(safe_divide(total, divisor))
    validate_positive(quotient)
  }
  io.println(string.inspect(ok_result))

Ok(5)
Error("division by zero")

• Each use line extracts the value from Ok and binds it to a name
• If any step returns Error, the whole block short-circuits and produces that error immediately
  • The remaining steps are never evaluated
  • Because when result.try receives an Error, it returns it directly without calling the callback
• The final expression is the result of the whole block
• Compare the two versions: the use form reads like a plain sequence of steps

  let err_result = {
    use total <- result.try(parse_int("30"))
    use divisor <- result.try(parse_int("0"))
    use quotient <- result.try(safe_divide(total, divisor))
    validate_positive(quotient)
  }
  io.println(string.inspect(err_result))

• parse_int("0") succeeds (zero is a valid integer), so divisor is bound to 0
• safe_divide(30, 0) returns Error("division by zero")
• The block short-circuits there; validate_positive is never called

How use Works

• use is not special-cased for Result: it is a general rewrite rule
• use x <- f(a, b) followed by a block of code is equivalent to:

f(a, b, fn(x) {
  body
})

• The x in fn(x) is exactly the same binding as the x introduced by use x <-
  • The rewrite is one-for-one, so the name carries over directly
• In other words: call f with its normal arguments plus one extra argument, a function that takes x and contains the rest of the block
• The function that receives the callback decides what to do with it
  • result.try calls the callback only when its first argument is Ok(x), and propagates Error unchanged otherwise
• Any function whose last parameter is a callback works with use
• If the callback takes no arguments, omit the binding: use <- f(a, b)

use Beyond Results

• Because use is just a rewrite, it works with any function that accepts a callback

  with_greeting("long form", fn(greeting) { io.println(greeting) })

  {
    use greeting <- with_greeting("with use")
    io.println(greeting)
  }

• with_greeting takes a name and a callback, and passes the constructed greeting to the callback
• Both forms produce the same output
  • use just removes the anonymous function syntax
• The use form expands to exactly the same call as the explicit version:

with_greeting("with use", fn(greeting) {
  io.println(greeting)
})

  {
    use item <- list.each([1, 2, 3])
    io.println(int.to_string(item))
  }

Hello, long form!
Hello, with use!
1
2
3

• list.each calls the callback once for each element of the list
• use item <- list.each([1, 2, 3]) is equivalent to writing list.each([1, 2, 3], fn(item) { ... })
• The rest of the block becomes the body of the anonymous function
  • No curly braces because it's a single expression

Guidelines for use

• Use use x <- result.try(...) when chaining three or more fallible operations
  • For one or two operations, a case expression is often clearer
• Prefer result.try for chaining; use result.map only for single-step transformations
• use does not catch errors; it propagates them exactly as nested case would
• Any function that takes a callback as its last argument works with use, not just functions from the result module
• Do not nest use blocks inside use blocks; if you feel tempted to do so, extract a helper function instead

Further Reading

• The Gleam language tour covers use with additional examples, including a discussion of how it relates to monadic bind in other languages.

Check Understanding

result.try(expr, fn(x) {
  rest of block
})

Exercises

let result = {
  use name <- result.try(find_user(id))
  use score <- result.try(fetch_score(name))
  Ok(score * 2)
}