7 mapM, mapM_, forM, forM_, sequence, sequence_, (=<<), (>=>), (<=<),
8 forever, void, join, msum, filterM, mapAndUnzipM, zipWithM,
9 zipWithM_, foldM, foldM_, replicateM, replicateM_, guard, when,
10 unless, liftM, liftM2, liftM3, liftM4, liftM5, ap
11 ) where\end{verbatim}}
16 \par
19 }
21 \item[\begin{tabular}{@{}l}
22 class\ Functor\ f\ where
24 The \haddockid{Functor} class is used for types that can be mapped over.
25 Instances of \haddockid{Functor} should satisfy the following laws:
26 \par
27 \begin{quote}
29 fmap id == id
30 fmap (f . g) == fmap f . fmap g
31 \end{verbatim}}
32 \end{quote}
34 satisfy these laws.
35 \par
39 \item[\begin{tabular}{@{}l}
40 fmap\ ::\ (a\ ->\ b)\ ->\ f\ a\ ->\ f\ b
41 \end{tabular}]
45 \item[\begin{tabular}{@{}l}
46 instance\ Functor\ {\char 91}{\char 93}\\instance\ Functor\ IO\\instance\ Functor\ Maybe\\instance\ Ix\ i\ =>\ Functor\ (Array\ i)
47 \end{tabular}]
50 \item[\begin{tabular}{@{}l}
54 a concept from a branch of mathematics known as \emph{category theory}.
55 From the perspective of a Haskell programmer, however, it is best to
56 think of a monad as an \emph{abstract datatype} of actions.
59 \par
61 \par
63 \par
64 \begin{quote}
66 return a >>= k == k a
67 m >>= return == m
68 m >>= (\x -> k x >>= h) == (m >>= k) >>= h
69 \end{verbatim}}
70 \end{quote}
72 \par
73 \begin{quote}
75 fmap f xs == xs >>= return . f
76 \end{verbatim}}
77 \end{quote}
79 defined in the \haddocktt{Prelude} satisfy these laws.
80 \par
84 \item[\begin{tabular}{@{}l}
85 (>>=)\ ::\ m\ a\ ->\ (a\ ->\ m\ b)\ ->\ m\ b
87 Sequentially compose two actions, passing any value produced
88 by the first as an argument to the second.
89 \par
93 \item[\begin{tabular}{@{}l}
94 (>>)\ ::\ m\ a\ ->\ m\ b\ ->\ m\ b
96 Sequentially compose two actions, discarding any value produced
97 by the first, like sequencing operators (such as the semicolon)
98 in imperative languages.
99 \par
103 \item[\begin{tabular}{@{}l}
104 return\ ::\ a\ ->\ m\ a
106 Inject a value into the monadic type.
107 \par
111 \item[\begin{tabular}{@{}l}
112 fail\ ::\ String\ ->\ m\ a
114 Fail with a message. This operation is not part of the
115 mathematical definition of a monad, but is invoked on pattern-match
116 failure in a \haddocktt{do} expression.
117 \par
122 \item[\begin{tabular}{@{}l}
124 \end{tabular}]
127 \item[\begin{tabular}{@{}l}
130 Monads that also support choice and failure.
131 \par
135 \item[\begin{tabular}{@{}l}
136 mzero\ ::\ m\ a
138 the identity of \haddockid{mplus}. It should also satisfy the equations
139 \par
140 \begin{quote}
142 mzero >>= f = mzero
143 v >> mzero = mzero
144 \end{verbatim}}
145 \end{quote}
147 in the mtl package does not satisfy the second one).
148 \par
152 \item[\begin{tabular}{@{}l}
153 mplus\ ::\ m\ a\ ->\ m\ a\ ->\ m\ a
155 an associative operation
156 \par
161 \item[\begin{tabular}{@{}l}
163 \end{tabular}]
165 \section{Functions
166 }
167 \subsection{Naming conventions
168 }
169 The functions in this library use the following naming conventions:
170 \par
171 \begin{itemize}
172 \item
173 A postfix '\haddocktt{M}' always stands for a function in the Kleisli category:
175 (modulo currying) and nowhere else. So, for example,
176 \par
178 \end{itemize}
179 \begin{quote}
181 filter :: (a -> Bool) -> [a] -> [a]
182 filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]
183 \end{verbatim}}
184 \end{quote}
185 \begin{itemize}
186 \item
188 Thus, for example:
189 \par
191 \end{itemize}
192 \begin{quote}
194 sequence :: Monad m => [m a] -> m [a]
195 sequence_ :: Monad m => [m a] -> m ()
196 \end{verbatim}}
197 \end{quote}
198 \begin{itemize}
199 \item
200 A prefix '\haddocktt{m}' generalizes an existing function to a monadic form.
201 Thus, for example:
202 \par
204 \end{itemize}
205 \begin{quote}
207 sum :: Num a => [a] -> a
208 msum :: MonadPlus m => [m a] -> m a
209 \end{verbatim}}
210 \end{quote}
213 }
215 \item[\begin{tabular}{@{}l}
216 mapM\ ::\ Monad\ m\ =>\ (a\ ->\ m\ b)\ ->\ {\char 91}a{\char 93}\ ->\ m\ {\char 91}b{\char 93}
219 \par
223 \item[\begin{tabular}{@{}l}
224 mapM{\char '137}\ ::\ Monad\ m\ =>\ (a\ ->\ m\ b)\ ->\ {\char 91}a{\char 93}\ ->\ m\ ()
226 \haddocktt{mapM{\char '137}\ f} is equivalent to \haddocktt{sequence{\char '137}\ .\ map\ f}.
227 \par
231 \item[\begin{tabular}{@{}l}
232 forM\ ::\ Monad\ m\ =>\ {\char 91}a{\char 93}\ ->\ (a\ ->\ m\ b)\ ->\ m\ {\char 91}b{\char 93}
235 \par
239 \item[\begin{tabular}{@{}l}
240 forM{\char '137}\ ::\ Monad\ m\ =>\ {\char 91}a{\char 93}\ ->\ (a\ ->\ m\ b)\ ->\ m\ ()
243 \par
247 \item[\begin{tabular}{@{}l}
248 sequence\ ::\ Monad\ m\ =>\ {\char 91}m\ a{\char 93}\ ->\ m\ {\char 91}a{\char 93}
250 Evaluate each action in the sequence from left to right,
251 and collect the results.
252 \par
256 \item[\begin{tabular}{@{}l}
257 sequence{\char '137}\ ::\ Monad\ m\ =>\ {\char 91}m\ a{\char 93}\ ->\ m\ ()
259 Evaluate each action in the sequence from left to right,
260 and ignore the results.
261 \par
265 \item[\begin{tabular}{@{}l}
266 (=<<)\ ::\ Monad\ m\ =>\ (a\ ->\ m\ b)\ ->\ m\ a\ ->\ m\ b
268 Same as \haddockid{>>=}, but with the arguments interchanged.
269 \par
273 \item[\begin{tabular}{@{}l}
274 (>=>)\ ::\ Monad\ m\ =>\ (a\ ->\ m\ b)\ ->\ (b\ ->\ m\ c)\ ->\ a\ ->\ m\ c
276 Left-to-right Kleisli composition of monads.
277 \par
281 \item[\begin{tabular}{@{}l}
282 (<=<)\ ::\ Monad\ m\ =>\ (b\ ->\ m\ c)\ ->\ (a\ ->\ m\ b)\ ->\ a\ ->\ m\ c
285 \par
289 \item[\begin{tabular}{@{}l}
290 forever\ ::\ Monad\ m\ =>\ m\ a\ ->\ m\ b
292 \haddocktt{forever\ act} repeats the action infinitely.
293 \par
297 \item[\begin{tabular}{@{}l}
298 void\ ::\ Functor\ f\ =>\ f\ a\ ->\ f\ ()
300 \haddocktt{void\ value} discards or ignores the result of evaluation, such as the return value of an \haddockid{IO} action.
301 \par
304 \subsection{Generalisations of list functions
305 }
307 \item[\begin{tabular}{@{}l}
308 join\ ::\ Monad\ m\ =>\ m\ (m\ a)\ ->\ m\ a
310 The \haddockid{join} function is the conventional monad join operator. It is used to
311 remove one level of monadic structure, projecting its bound argument into the
312 outer level.
313 \par
317 \item[\begin{tabular}{@{}l}
318 msum\ ::\ MonadPlus\ m\ =>\ {\char 91}m\ a{\char 93}\ ->\ m\ a
320 This generalizes the list-based \haddockid{concat} function.
321 \par
325 \item[\begin{tabular}{@{}l}
326 filterM\ ::\ Monad\ m\ =>\ (a\ ->\ m\ Bool)\ ->\ {\char 91}a{\char 93}\ ->\ m\ {\char 91}a{\char 93}
328 This generalizes the list-based \haddockid{filter} function.
329 \par
333 \item[\begin{tabular}{@{}l}
334 mapAndUnzipM\ ::\ Monad\ m\ =>\ (a\ ->\ m\ (b,\ c))\ ->\ {\char 91}a{\char 93}\ ->\ m\ ({\char 91}b{\char 93},\ {\char 91}c{\char 93})
336 The \haddockid{mapAndUnzipM} function maps its first argument over a list, returning
337 the result as a pair of lists. This function is mainly used with complicated
338 data structures or a state-transforming monad.
339 \par
343 \item[\begin{tabular}{@{}l}
344 zipWithM\ ::\ Monad\ m\ =>\ (a\ ->\ b\ ->\ m\ c)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ m\ {\char 91}c{\char 93}
347 \par
351 \item[\begin{tabular}{@{}l}
352 zipWithM{\char '137}\ ::\ Monad\ m\ =>\ (a\ ->\ b\ ->\ m\ c)\ ->\ {\char 91}a{\char 93}\ ->\ {\char 91}b{\char 93}\ ->\ m\ ()
354 \haddockid{zipWithM{\char '137}} is the extension of \haddockid{zipWithM} which ignores the final result.
355 \par
359 \item[\begin{tabular}{@{}l}
360 foldM\ ::\ Monad\ m\ =>\ (a\ ->\ b\ ->\ m\ a)\ ->\ a\ ->\ {\char 91}b{\char 93}\ ->\ m\ a
362 The \haddockid{foldM} function is analogous to \haddockid{foldl}, except that its result is
363 encapsulated in a monad. Note that \haddockid{foldM} works from left-to-right over
364 the list arguments. This could be an issue where \haddocktt{(>>)} and the folded
365 function' are not commutative.
366 \par
367 \begin{quote}
369 foldM f a1 [x1, x2, ..., xm ]
370 \end{verbatim}}
371 \end{quote}
372 ==
373 \par
374 \begin{quote}
376 do
377 a2 <- f a1 x1
378 a3 <- f a2 x2
379 ...
380 f am xm
381 \end{verbatim}}
382 \end{quote}
383 If right-to-left evaluation is required, the input list should be reversed.
384 \par
388 \item[\begin{tabular}{@{}l}
389 foldM{\char '137}\ ::\ Monad\ m\ =>\ (a\ ->\ b\ ->\ m\ a)\ ->\ a\ ->\ {\char 91}b{\char 93}\ ->\ m\ ()
392 \par
396 \item[\begin{tabular}{@{}l}
397 replicateM\ ::\ Monad\ m\ =>\ Int\ ->\ m\ a\ ->\ m\ {\char 91}a{\char 93}
400 gathering the results.
401 \par
405 \item[\begin{tabular}{@{}l}
406 replicateM{\char '137}\ ::\ Monad\ m\ =>\ Int\ ->\ m\ a\ ->\ m\ ()
409 \par
412 \subsection{Conditional execution of monadic expressions
413 }
415 \item[\begin{tabular}{@{}l}
416 guard\ ::\ MonadPlus\ m\ =>\ Bool\ ->\ m\ ()
420 \par
424 \item[\begin{tabular}{@{}l}
425 when\ ::\ Monad\ m\ =>\ Bool\ ->\ m\ ()\ ->\ m\ ()
427 Conditional execution of monadic expressions. For example,
428 \par
429 \begin{quote}
431 when debug (putStr "Debugging\n")
432 \end{verbatim}}
433 \end{quote}
435 and otherwise do nothing.
436 \par
440 \item[\begin{tabular}{@{}l}
441 unless\ ::\ Monad\ m\ =>\ Bool\ ->\ m\ ()\ ->\ m\ ()
444 \par
448 }
450 \item[\begin{tabular}{@{}l}
451 liftM\ ::\ Monad\ m\ =>\ (a1\ ->\ r)\ ->\ m\ a1\ ->\ m\ r
453 Promote a function to a monad.
454 \par
458 \item[\begin{tabular}{@{}l}
459 liftM2\ ::\ Monad\ m\ =>\ (a1\ ->\ a2\ ->\ r)\ ->\ m\ a1\ ->\ m\ a2\ ->\ m\ r
461 Promote a function to a monad, scanning the monadic arguments from
462 left to right. For example,
463 \par
464 \begin{quote}
466 liftM2 (+) [0,1] [0,2] = [0,2,1,3]
467 liftM2 (+) (Just 1) Nothing = Nothing
468 \end{verbatim}}
469 \end{quote}
473 \item[\begin{tabular}{@{}l}
474 liftM3\ ::\ Monad\ m\ =>\ (a1\ ->\ a2\ ->\ a3\ ->\ r)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ m\ a1\ ->\ m\ a2\ ->\ m\ a3\ ->\ m\ r
476 Promote a function to a monad, scanning the monadic arguments from
477 left to right (cf. \haddockid{liftM2}).
478 \par
482 \item[\begin{tabular}{@{}l}
483 liftM4\ ::\ Monad\ m\ =>\ (a1\ ->\ a2\ ->\ a3\ ->\ a4\ ->\ r)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ m\ a1\ ->\ m\ a2\ ->\ m\ a3\ ->\ m\ a4\ ->\ m\ r
485 Promote a function to a monad, scanning the monadic arguments from
486 left to right (cf. \haddockid{liftM2}).
487 \par
491 \item[\begin{tabular}{@{}l}
492 liftM5\ ::\ Monad\ m\ =>\ (a1\ ->\ a2\ ->\ a3\ ->\ a4\ ->\ a5\ ->\ r)\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ m\ a1\ ->\ m\ a2\ ->\ m\ a3\ ->\ m\ a4\ ->\ m\ a5\ ->\ m\ r
494 Promote a function to a monad, scanning the monadic arguments from
495 left to right (cf. \haddockid{liftM2}).
496 \par
500 \item[\begin{tabular}{@{}l}
501 ap\ ::\ Monad\ m\ =>\ m\ (a\ ->\ b)\ ->\ m\ a\ ->\ m\ b
503 In many situations, the \haddockid{liftM} operations can be replaced by uses of
504 \haddockid{ap}, which promotes function application.
505 \par
506 \begin{quote}
508 return f ap x1 ap ... ap` xn
509 \end{verbatim}}
510 \end{quote}
511 is equivalent to
512 \par
513 \begin{quote}
515 liftMn f x1 x2 ... xn
516 \end{verbatim}}
517 \end{quote}