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