Result, option and binding operators

A sign-up form takes a name, an age and a 6-digit PIN code, and 4 things can go wrong in one submission: the name may be too short, the age not a whole number, the age outside 1 to 120, or the PIN not a valid 6 digits. OCaml’s result and option types carry each failure back as a value the type checker refuses to let the caller forget, instead of raising an exception that a missing handler turns into a stopped program.

You will report errors with the standard result and option types, combine fallible steps with let* from Result.Syntax, design error types with closed or polymorphic variants, and choose between exceptions and results for an API.

Result and option carry a failure as a value

The resultresult: The OCaml standard variant type ('a, 'e) result = Ok of 'a | Error of 'e, used to return either an answer or a reason there is none; Result.bind and Result.map compose steps that return it. type, ('a, 'e) result = Ok of 'a | Error of 'e, is the standard way to return either an answer or a reason there is none. Each step of a sign-up for an Indian user returns one: validate_name gives Ok name or Error Short_name, parse_age gives Ok n or Error (Not_a_number s) or Error (Age_out_of_range n), and parse_pin checks the 6-digit PIN code (UPU guide, PDF) with Error (Bad_pin s) when the text is not exactly 6 digits or, as this form also requires, starts with 0.

The optionoption: The standard variant type 'a option = None | Some of 'a, used for a result that may be missing instead of a null value. More in “Variants, options and recursive types” type carries a failure that has nothing to say about itself: List.assoc_opt returns None when the key is missing because the only reason is that nothing was there, and int_of_string_opt does the same for a text that is not a number. An option is either Some v or None, and nothing else. Reach for result when the reason matters, and option when the caller only needs to know whether there is an answer. Convert from one to the other with Result.to_option and Option.to_result ~none:

Result.map f r applies f inside an Ok; an Error passes through unchanged. The session below runs validate_name through Result.map String.uppercase_ascii, which turns Ok "Asha" into Ok "ASHA" and leaves Error Short_name as it is.

A chain of result steps stops at the first error

Result.bind o f is f v when o is Ok v, and o itself when it is Error _. One call of it per step chains the three validate steps, so that an Error from any one of them skips the rest and reaches the caller untouched. Step through signup on the four submissions the session runs:

from session import toplevel

# The free core: a sign-up form takes a name, an age and a 6-digit PIN code (India Post postal index number).
# Each step may fail. We carry each failure as a value with Result.t, chain the three steps with Result.Syntax
# let* in OCaml 5.5.1, and also show the one-line fallback (let ( let* ) = Result.bind) for older compilers.
toplevel("""
type signup_error =
  | Short_name
  | Not_a_number of string
  | Age_out_of_range of int
  | Bad_pin of string
;;

let validate_name s =
  if String.length s >= 2 then Ok s else Error Short_name
;;

let parse_age s =
  match int_of_string_opt s with
  | None -> Error (Not_a_number s)
  | Some n when n >= 1 && n <= 120 -> Ok n
  | Some n -> Error (Age_out_of_range n)
;;

let parse_pin s =
  let digits_only = String.for_all (fun c -> c >= '0' && c <= '9') s in
  if String.length s = 6 && digits_only && s.[0] <> '0'
  then Ok s
  else Error (Bad_pin s)
;;

let signup name age pin =
  let open Result.Syntax in
  let* n = validate_name name in
  let* a = parse_age age in
  let* p = parse_pin pin in
  Ok (n, a, p)
;;

let cases = [
  ("Asha", "25", "560001");
  ("A", "25", "560001");
  ("Asha", "twenty", "560001");
  ("Asha", "25", "012345");
];;

List.map (fun (n, a, p) -> signup n a p) cases;;

(* Older OCaml compilers (before 5.4) have no Result.Syntax, so define let* yourself. *)
let ( let* ) = Result.bind;;

let signup_classic name age pin =
  let* n = validate_name name in
  let* a = parse_age age in
  let* p = parse_pin pin in
  Ok (n, a, p)
;;

List.map (fun (n, a, p) -> signup_classic n a p) cases;;

(* Result.map changes a value inside Ok; Error passes through unchanged. *)
Result.map String.uppercase_ascii (validate_name "Asha");;
Result.map String.uppercase_ascii (validate_name "A");;
""")

$ ocaml
OCaml version 5.5.1
Enter #help;; for help.

# type signup_error =
    | Short_name
    | Not_a_number of string
    | Age_out_of_range of int
    | Bad_pin of string
  ;;
          type signup_error =
    Short_name
  | Not_a_number of string
  | Age_out_of_range of int
  | Bad_pin of string
# 
  let validate_name s =
    if String.length s >= 2 then Ok s else Error Short_name
  ;;
      val validate_name : string -> (string, signup_error) result = <fun>
# 
  let parse_age s =
    match int_of_string_opt s with
    | None -> Error (Not_a_number s)
    | Some n when n >= 1 && n <= 120 -> Ok n
    | Some n -> Error (Age_out_of_range n)
  ;;
            val parse_age : string -> (int, signup_error) result = <fun>
# 
  let parse_pin s =
    let digits_only = String.for_all (fun c -> c >= '0' && c <= '9') s in
    if String.length s = 6 && digits_only && s.[0] <> '0'
    then Ok s
    else Error (Bad_pin s)
  ;;
            val parse_pin : string -> (string, signup_error) result = <fun>
# 
  let signup name age pin =
    let open Result.Syntax in
    let* n = validate_name name in
    let* a = parse_age age in
    let* p = parse_pin pin in
    Ok (n, a, p)
  ;;
              val signup :
  string -> string -> string -> (string * int * string, signup_error) result =
  <fun>
# 
  let cases = [
    ("Asha", "25", "560001");
    ("A", "25", "560001");
    ("Asha", "twenty", "560001");
    ("Asha", "25", "012345");
  ];;
            val cases : (string * string * string) list =
  [("Asha", "25", "560001"); ("A", "25", "560001");
   ("Asha", "twenty", "560001"); ("Asha", "25", "012345")]
# 
  List.map (fun (n, a, p) -> signup n a p) cases;;
  - : (string * int * string, signup_error) result list =
[Ok ("Asha", 25, "560001"); Error Short_name; Error (Not_a_number "twenty");
 Error (Bad_pin "012345")]
# 
  (* Older OCaml compilers (before 5.4) have no Result.Syntax, so define let* yourself. *)
  let ( let* ) = Result.bind;;
    val ( let* ) : ('a, 'b) result -> ('a -> ('c, 'b) result) -> ('c, 'b) result =
  <fun>
# 
  let signup_classic name age pin =
    let* n = validate_name name in
    let* a = parse_age age in
    let* p = parse_pin pin in
    Ok (n, a, p)
  ;;
            val signup_classic :
  string -> string -> string -> (string * int * string, signup_error) result =
  <fun>
# 
  List.map (fun (n, a, p) -> signup_classic n a p) cases;;
  - : (string * int * string, signup_error) result list =
[Ok ("Asha", 25, "560001"); Error Short_name; Error (Not_a_number "twenty");
 Error (Bad_pin "012345")]
# 
  (* Result.map changes a value inside Ok; Error passes through unchanged. *)
  Result.map String.uppercase_ascii (validate_name "Asha");;
    - : (string, signup_error) result = Ok "ASHA"
# Result.map String.uppercase_ascii (validate_name "A");;
- : (string, signup_error) result = Error Short_name

The nested-match version of the same chain needs an Error e -> Error e case for every step: nine lines for three steps, where Result.bind writes each step as one line and the chain ends with one Ok. Result.map suits a step that always succeeds (the uppercase example above); Result.bind suits a step that itself returns a result. Mapping a step that returns a result gives a result result, a sign that bind was meant.

Writing the chain with let-star from Result.Syntax

Binding operators are OCaml functions that look like keywords, so a library can give let* the meaning of a chaining function for its own type. The Result.Syntax module (available in OCaml 5.4 and later) defines the binding operatorsbinding operator: An operator such as let* that the programmer defines and OCaml uses to read let* x = e in body as a call of that operator on e and fun x -> body; defined as Option.bind, it chains steps that may give None. More in “Folds over trees, options and other structures” let* and let+, where let* reads as Result.bind, so the signup chain becomes a sequence of let* lines that stops at the first Error. OCaml rewrites let* x = e1 in e2 into ( let* ) e1 (fun x -> e2). let open Result.Syntax in let* name = validate_name ... in let* age = ... in let* pin = ... in Ok (name, age, pin) is the chain of Result.binds the session’s first signup runs. Option.Syntax (available in OCaml 5.5 and later) does the same for options and defines binding operators for Option.bind.

An older compiler without Result.Syntax, from OCaml 4.08, which introduced binding operators, to 5.3, reads let* from the programmer: let ( let* ) = Result.bind turns every later let* in the file into the same chain, with no other code changes. The session’s signup_classic redefines the binding operator and gives the same four outputs as signup. Result.Syntax also defines let+ and and+, which combine independent results into one and keep only the first error — a parallel validator that lists every error of a submission takes a different shape, and so does an error type that must stay open as more parsers are added. The choice between exceptions and result for an API follows how often the step fails and how far the caller is: the parts below work out each of these.

Practise: result, option and let-star

Six questions, two on each idea of this part: result and option, the chain of binds, and let*.

Designing error types: closed variants, polymorphic variants and the chain's inferred type Pro: opens with a Pro, Premium or Ultimate pass

let+ and and+ for independent results, with every error of a submission reported together Pro: opens with a Pro, Premium or Ultimate pass

Choosing exceptions or results for an API, with the monad laws checked on real values Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Key takeaways

• result carries the reason a step failed as a value the type checker will not let the caller drop; option carries a failure that has nothing to say about itself.
• Result.bind, as let* from Result.Syntax since OCaml 5.4, chains fallible steps so that the first Error reaches the caller untouched; let ( let* ) = Result.bind is the one-line fallback on older compilers.
• Result.map applies a function inside Ok and leaves Error alone; Result.get_ok raises Invalid_argument "result is Error _", so reach for a match or Result.value ~default instead.