do
This package brings Haskell-style type classes to Erlang, including monads, applicatives, functors, and traversables. It provides implementations of commonly used class instances, as well as useful utility functions.
Installation
To install the latest release from hex, add
do to the deps in your rebar3 config file:
{do, "1.10.3"}
What's in the box
The do package implements either,
list, and
maybe monads. For a complete overview
of types and functions, refer to do_types.hrl and
do's docs on hex.
fmap
Use the ?fmap macro or do:fmap/2 to map functions over functors:
-include_lib("do/include/do.hrl").
increment(N) ->
N + 1.
fmap_either() ->
{ok, 2} = ?fmap(fun increment/1, {ok, 1}),
{error, reason} = ?fmap(fun increment/1, {error, reason}).
fmap_maybe() ->
{just, 2} = ?fmap(fun increment/1, {just, 1}),
nothing = ?fmap(fun increment/1, nothing).
fmap_list() ->
[2, 3, 4] = ?fmap(fun increment/1, [1, 2, 3]).
fmap_map() ->
#{a => 2} = ?fmap(fun increment/1, #{a => 1}).sequence
Use the ?sequence macro or do:sequence/1 to sequence a traversable of
applicatives. For example:
-include_lib("do/include/do.hrl").
sequence_list() ->
{ok, [1, 2, 3]} = ?sequence([{ok, 1}, {ok, 2}, {ok, 3}]),
{error, reason} = ?sequence([{ok, 1}, {error, reason}, {ok, 3}]).
sequence_map() ->
{just, #{a => 1, b => 2}} = ?sequence(#{a => {just, 1}, b => {just, 2}}),
nothing = ?sequence(#{a => {just, 1}, b => nothing}).
sequence_either() ->
[{ok, 1}] = ?sequence({ok, [1]}),
[] = ?sequence({ok, []}).
bind
Use the ?bind macro or do:bind/2 to bind (>>=) a function that returns a
monad to a monad of the same type. In case of the
either monad:
-include_lib("do/include/do.hrl").
increment_either(N) when is_integer(N) ->
{ok, N + 1};
increment_either(_) ->
{error, no_int}.
bind_either() ->
{ok, 2} = ?bind({ok, 1}, fun increment_either/1),
{error, no_int} = ?bind({ok, foo}, fun increment_either/1),
{error, reason} = ?bind({error, reason}, fun increment_either/1).For the maybe monad:
increment_maybe(N) when is_integer(N) ->
{just, N + 1};
increment_maybe(_) ->
nothing.
bind_maybe() ->
{just, 2} = ?bind({just, 1}, fun increment_maybe/1),
nothing = ?bind({just, foo}, fun increment_maybe/1),
nothing = ?bind(nothing, fun increment_maybe/1).For the list monad:
increment_list(N) when is_integer(N) ->
[N + 1];
increment_maybe(_) ->
[].
bind_list() ->
[2] = ?bind([1], fun increment_list/1),
[] = ?bind([foo], fun increment_list/1),
[] = ?bind([], fun increment_maybe/1).then
Use the ?then macro or do:then/2 to chain (>>) monadic expressions of the
same type. The second argument to ?then is wrapped in a thunk that will only
be executed if the first argument indicates success. For example:
-include_lib("do/include/do.hrl").
increment(N) when is_integer(N) ->
[N + 1];
increment(_) ->
[].
then_list() ->
[2] = ?then([5], increment(1)),
[] = ?then([5], increment(foo)),
[] = ?then([], increment(1)).liftm
Use the ?liftm macro to lift a function into a monad. For example:
-include_lib("do/include/do.hrl").
liftm_either() ->
{ok, 3} = ?liftm(fun erlang:'+'/2, {ok, 1}, {ok, 2}),
{error, reason} = ?liftm(fun erlang:'+'/2, {ok, 1}, {error, reason}).Arguments to ?liftm are evaluated lazily. In the following example
1 + 1 will never be evaluated:
-include_lib("do/include/do.hrl").
liftm_either() ->
{error, reason} = ?liftm(fun erlang:'+'/2, {error, reason}, {ok, 1 + 1}).do
Use the ?do macro or do:do/2 to consecutively bind (>>= or >>) monads
and functions. The macro takes a start value (a monad), and a list of functions.
The functions must each take either 0 or 1 argument(s) and must return a monad.
On execution, the start value is passed to the first function, and is then
piped through consecutive functions using bind or then. For example (with
either monad):
-include_lib("do/include/do.hrl").
increment(N) when is_integer(N) ->
{ok, N + 1};
increment(_) ->
{error, no_int}.
int_to_bin(N) when is_integer(N) ->
{ok, integer_to_binary(N)};
int_to_bin(_) ->
{error, no_int}.
do_either() ->
{ok, 4} = ?do({ok, 1}, [ fun increment/1,
fun increment/1,
fun increment/1 ]),
{error, no_int} = ?do({ok, 1}, [ fun increment/1,
fun int_to_bin/1,
fun increment/1 ]).
