Errors

Some function cannot return a sensible result for all possible inputs. And many I/O actions may fail as well. While these functions and actions could throw exceptions, these are not tracked by the Hack type checker.

To make it clear what errors a function may result in, the Option and Awkward classes exist.

Optional values

Option is appropriate when a computation may fail due to just one reason. For example, one can divide by any number except zero:

function divide(float $a, float $b): Option<num> {
    return $b === 0.0 ? Option::none() : Option::some($a / $b);
}

TODO: document map and bind, and a few other functions. Also explain the difference between Option<T> and ?T.

Awkward values

Awkward is similar to Option, but erroneous results can carry an explanation of what went wrong. For example, reading a file may fail for many reasons:

function readFile(string $path): IO<Awkward<Exception, string>> {
    return new IO(function() use($path) {
        try {
            return Awkward::ok(file_get_contents($path));
        } catch (Exception $e) {
            return Awkward::error($e);
        }
    });
}

TODO: document map and bind, and a few other functions.