@@ -52,6 +52,23 @@ when False f = pure ()
5252
5353||| Fold using Alternative
5454|||
55−||| This is called `asum` in Haskell.
55+||| If you have a left-biased alternative operator `<|>`, then `choice`
56+||| performs left-biased choice from a list of alternatives, which means that
57+||| it evaluates to the left-most non-`empty` alternative.
58+|||
59+||| If the list is empty, or all values in it are `empty`, then it
60+||| evaluates to `empty`.
61+|||
62+||| Example:
63+|||
64+||| ```
65+||| -- given a parser expression like:
66+||| expr = literal <|> keyword <|> funcall
67+|||
68+||| -- choice lets you write this as:
69+||| expr = choice [literal, keyword, funcall]
70+||| ```
71+|||
72+||| Note: In Haskell, `choice` is called `asum`.
5673choice : (Foldable t, Alternative f) => t (f a) -> f a
5774choice x = foldr (<|>) empty x