[project @ 2001-03-23 16:36:20 by simonmar]
[ghc-hetmet.git] / ghc / lib / std / Monad.lhs
1 % -----------------------------------------------------------------------------
2 % $Id: Monad.lhs,v 1.11 2000/06/30 13:39:35 simonmar Exp $
3 %
4 % (c) The University of Glasgow, 1994-2000
5 %
6
7 \section[Monad]{Module @Monad@}
8
9 \begin{code}
10 module Monad 
11     ( MonadPlus (   -- class context: Monad
12           mzero     -- :: (MonadPlus m) => m a
13         , mplus     -- :: (MonadPlus m) => m a -> m a -> m a
14         )
15     , join          -- :: (Monad m) => m (m a) -> m a
16     , guard         -- :: (MonadPlus m) => Bool -> m ()
17     , when          -- :: (Monad m) => Bool -> m () -> m ()
18     , unless        -- :: (Monad m) => Bool -> m () -> m ()
19     , ap            -- :: (Monad m) => (m (a -> b)) -> (m a) -> m b
20     , msum          -- :: (MonadPlus m) => [m a] -> m a
21     , filterM       -- :: (Monad m) => (a -> m Bool) -> [m a] -> m [a]
22     , mapAndUnzipM  -- :: (Monad m) => (a -> m (b,c)) -> [a] -> m ([b], [c])
23     , zipWithM      -- :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m [c]
24     , zipWithM_     -- :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m ()
25     , foldM         -- :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m a 
26     
27     , liftM         -- :: (Monad m) => (a -> b) -> (m a -> m b)
28     , liftM2        -- :: (Monad m) => (a -> b -> c) -> (m a -> m b -> m c)
29     , liftM3        -- :: ...
30     , liftM4        -- :: ...
31     , liftM5        -- :: ...
32
33     , Monad((>>=), (>>), return, fail)
34     , Functor(fmap)
35
36     , mapM          -- :: (Monad m) => (a -> m b) -> [a] -> m [b]
37     , mapM_         -- :: (Monad m) => (a -> m b) -> [a] -> m ()
38     , sequence      -- :: (Monad m) => [m a] -> m [a]
39     , sequence_     -- :: (Monad m) => [m a] -> m ()
40     , (=<<)         -- :: (Monad m) => (a -> m b) -> m a -> m b
41     ) where
42
43 import Prelude
44 \end{code}
45
46 %*********************************************************
47 %*                                                      *
48 \subsection{Monadic classes: @MonadPlus@}
49 %*                                                      *
50 %*********************************************************
51
52
53 \begin{code}
54 class Monad m => MonadPlus m where
55   mzero :: m a
56   mplus :: m a -> m a -> m a
57
58 instance MonadPlus [] where
59    mzero = []
60    mplus = (++)
61
62 instance MonadPlus Maybe where
63    mzero = Nothing
64
65    Nothing `mplus` ys  = ys
66    xs      `mplus` _ys = xs
67 \end{code}
68
69
70 %*********************************************************
71 %*                                                      *
72 \subsection{Functions mandated by the Prelude}
73 %*                                                      *
74 %*********************************************************
75
76 \begin{code}
77 guard           :: MonadPlus m => Bool -> m ()
78 guard pred
79  | pred      = return ()
80  | otherwise = mzero
81
82 -- This subsumes the list-based filter function.
83
84 filterM         :: (Monad m) => ( a -> m Bool ) -> [a] -> m [a]
85 filterM _predM []     = return []
86 filterM  predM (x:xs) = do
87    flg <- predM x
88    ys  <- filterM predM xs
89    return (if flg then x:ys else ys)
90
91 -- This subsumes the list-based concat function.
92
93 msum        :: MonadPlus m => [m a] -> m a
94 {-# INLINE msum #-}
95 msum        =  foldr mplus mzero
96 \end{code}
97
98
99 %*********************************************************
100 %*                                                      *
101 \subsection{Other monad functions}
102 %*                                                      *
103 %*********************************************************
104
105 \begin{code}
106 join             :: (Monad m) => m (m a) -> m a
107 join x           = x >>= id
108
109 mapAndUnzipM     :: (Monad m) => (a -> m (b,c)) -> [a] -> m ([b], [c])
110 mapAndUnzipM f xs = sequence (map f xs) >>= return . unzip
111
112 zipWithM         :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m [c]
113 zipWithM f xs ys = sequence (zipWith f xs ys)
114
115 zipWithM_ :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m ()
116 zipWithM_ f xs ys = sequence_ (zipWith f xs ys)
117
118 foldM            :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
119 foldM _ a []     = return a
120 foldM f a (x:xs) = f a x >>= \fax -> foldM f fax xs
121
122 unless           :: (Monad m) => Bool -> m () -> m ()
123 unless p s       =  if p then return () else s
124
125 when             :: (Monad m) => Bool -> m () -> m ()
126 when p s         =  if p then s else return ()
127
128 ap :: (Monad m) => m (a->b) -> m a -> m b
129 ap = liftM2 ($)
130
131 liftM   :: (Monad m) => (a1 -> r) -> m a1 -> m r
132 liftM2  :: (Monad m) => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
133 liftM3  :: (Monad m) => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r
134 liftM4  :: (Monad m) => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r
135 liftM5  :: (Monad m) => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r
136
137 liftM f m1              = do { x1 <- m1; return (f x1) }
138 liftM2 f m1 m2          = do { x1 <- m1; x2 <- m2; return (f x1 x2) }
139 liftM3 f m1 m2 m3       = do { x1 <- m1; x2 <- m2; x3 <- m3; return (f x1 x2 x3) }
140 liftM4 f m1 m2 m3 m4    = do { x1 <- m1; x2 <- m2; x3 <- m3; x4 <- m4; return (f x1 x2 x3 x4) }
141 liftM5 f m1 m2 m3 m4 m5 = do { x1 <- m1; x2 <- m2; x3 <- m3; x4 <- m4; x5 <- m5; return (f x1 x2 x3 x4 x5) }
142
143 \end{code}