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, "2.0.2"}

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 ]).