Outcome: functional and composable option and result types for Lua. Outcome's API is heavily inspired and based up the Rust Option and Result types.
The API documentation can be read online at http://mtdowling.com/outcome/.
The Option type is used to contain a non-nil result that may or may not be
present. An Option that has no value is None. If an Option has a value, the
value can be retrieved using unwrap()
. Calling unwrap()
on a None Option
will result in an error.
Returning an Option type from a function rather than returning a value that may
be nil
helps to avoid null pointer errors and provides composable
abstractions over the result.
Examples
local outcome = require "outcome"
-- Options are either None or Some.
assert(outcome.none():isNone())
assert(outcome.some("foo"):isSome())
-- You can map over the value in an Option.
local result = outcome.some(1)
:map(function(value) return value + 1 end)
:unwrap()
assert(result == 2)
-- Raises an error with the message provided in expect.
outcome.none():expect("Expected a value"):
-- You can provide a default value when unwrapping an Option.
assert("foo" == outcome.none():unwrapOr("foo"))
Result<T, E>
is a type used for returning and propagating errors.
There are two kinds of Result objects:
- Ok: the result contains a successful value.
- Err: The result contains an error value.
Examples
local outcome = require "outcome"
local Result = outcome.Result
-- Results are either Ok or Err.
assert(outcome.ok("ok value"):isOk())
assert(outcome.err("error value"):isErr())
-- You can map over the Ok value in a Result.
local result = outcome.ok(1)
:map(function(value) return value + 1 end)
:unwrap()
assert(result == 2)
-- Raises an error with the message provided in expect.
outcome.err("error value"):expect("Result was not Ok"):
-- You can provide a default value when unwrapping a Result.
assert("foo" == outcome.err("error value"):unwrapOr("foo"))
Just copy outcome.lua
wherever you want it. Then write this in any Lua file
where you want to use it:
local outcome = require "outcome"
You can also install Outcome using luarocks:
luarocks install outcome
This project uses busted for testing. If you want to run the tests, you will have to install busted first.
luarocks install busted
After busted is installed, execute the following command to run the tests:
make test
There's a really simply benchmark tool that can be run using the following command:
make bench