A tour of the Haskell Monad functions

This reference guide describes monad and functor functions in the modules Prelude and Control.Monad.
It describes functions of The Haskell 98 Library Report only; example code is limited to Haskell 2010.
The lines in the "Usage" sections, starting with "> " are commands/expressions typed in a Hugs 98 shell.
For most of the examples, it is necessary to give the command :l Control.Monad first;
in some cases, source code must be entered in a file and the file must be loaded.
If you have any suggestions for improvement,
send me an e-mail
(remove "REMOVE-THIS." from the address.)

Acknowledgements:

For this reference manual, "A tour of the Haskell Prelude",
by Bernie Pope and Arjan van IJzendoorn was used as an example.

The example at fail,
summing lists of two elements, was written by Yitzchak Gale.

Some books on Haskell:

takes the contents of monad m and passes it
to function f as a parameter.
It may be useful when used as a parameter of a higher order function,
or one can use it as a more readable way of coding, in some cases.

This operator is essentially the same as
(>>=), but does
not pass the contents of the monad to the function
specified as second parameter. It can be used to define
the order in which actions take place.

takes the contents of monad m and passes it to function f as a parameter.
>>= is one of the two basic operators of
the Monad class (the other is return).
Any instantiation of >>= and
return must obey the following laws:

ap applies a function inside a monad to a value
inside a monad of the same type.
A call to liftMn can often be replaced by one or more
calls to ap:

return f `ap` x1 `ap` ... `ap` xn

is the same as:

liftMn f x1 x2 ... xn

definition:

ap = liftM2 ($)

usage:

Apply a list of functions to a list of values:
> [(+ 1), (+ 2)] `ap` [1, 2, 3]
[2, 3, 4, 3, 4, 5]
Apply a function in the Maybe monad to a value
in the Maybe monad:
> Just (+ 1) `ap` Just 1
Just 2
Apply a function, with two parameters, in the
Maybe monad, to two values in the Maybe monad:
> Just (*) `ap` (Just 2) `ap` (Just 3)
Just 6
> return cos `ap` Just pi
Just (-1.0)

fail is to be called in case a
certain condition is not met. When using the IO () version of
fail, the program is
interrupted; in other monads, the effect is less drastic;
the list version, for example, returns an empty list.

filterM p xs filters out all elements
of xs that do not fulfill the
predicate p, where
p is a function that returns a value
of type Monad m => m Bool; the result
is a list inside a monad of the same type.

fmap f x lets function f operate on
x, even though x has a different type
then f was designed for. fmap is
defined for the types Maybe, IO and
[] in Prelude. In case of lists,
fmap behaves exactly like map and
liftM; in case of the Maybe monad, fmap
behaves like liftM.
Every instance of fmap should satisfy the following laws:

mapAndUnzipM mf xs takes a monadic function
mf (having type
(Monad m) => (a -> m (b,c)))
and applies it to each element in list
xs; the resulting list of two-tuples
is then unzipped, the final result is a two-tuple of lists inside a monad.

mapM mf xs takes a monadic function
mf (having type
Monad m => (a -> m b))
and applies it to each element in list
xs; the result is a list inside a monad.
The difference between mapM and
mapM_ is, that mapM
returns a list of the results, while mapM_
returns an empty result.

mapM_ mf xs takes a monadic function
mf (having type
Monad m => (a -> m b))
and applies it to each element in list
xs; the result of each action is not stored.
The difference between mapM and
mapM_ is, that mapM
returns a list of the results, while mapM_
returns an empty result.

return is one of the two basic operators of the
Monad class (the other is >>= (called "bind")).
One could say, it converts a value to a monad containing this value;
the type of this monad depends on the type of the expression.
Any instantiation of >>= and
return must obey the laws mentioned at the desciption of
(>>=)

sequence xs evaluates all monadic
values in the list xs,
from left to right, and returns a list of the "contents" of
these monads, placing this list in a monad of the same type.
Note, that "evaluating" can be interpreted as "performing an
action", for example in the case of print.
The difference between sequence and
sequence_ is that sequence
returns a list of the results, while sequence_
returns an empty result.

sequence_ xs evaluates all monadic
values in the list xs,
from left to right, and returns () inside a monad.
Note, that "evaluating" can be read as "performing an action".
The difference between sequence and
sequence_ is that sequence
returns a list of the results, while sequence_
returns an empty result.