1 {-# LANGUAGE CPP, NoImplicitPrelude #-}
3 -----------------------------------------------------------------------------
5 -- Module : Control.Monad
6 -- Copyright : (c) The University of Glasgow 2001
7 -- License : BSD-style (see the file libraries/base/LICENSE)
9 -- Maintainer : libraries@haskell.org
10 -- Stability : provisional
11 -- Portability : portable
13 -- The 'Functor', 'Monad' and 'MonadPlus' classes,
14 -- with some useful operations on monads.
18 -- * Functor and monad classes
21 , Monad((>>=), (>>), return, fail)
23 , MonadPlus ( -- class context: Monad
24 mzero -- :: (MonadPlus m) => m a
25 , mplus -- :: (MonadPlus m) => m a -> m a -> m a
29 -- ** Naming conventions
32 -- ** Basic @Monad@ functions
34 , mapM -- :: (Monad m) => (a -> m b) -> [a] -> m [b]
35 , mapM_ -- :: (Monad m) => (a -> m b) -> [a] -> m ()
36 , forM -- :: (Monad m) => [a] -> (a -> m b) -> m [b]
37 , forM_ -- :: (Monad m) => [a] -> (a -> m b) -> 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 , (>=>) -- :: (Monad m) => (a -> m b) -> (b -> m c) -> (a -> m c)
42 , (<=<) -- :: (Monad m) => (b -> m c) -> (a -> m b) -> (a -> m c)
43 , forever -- :: (Monad m) => m a -> m b
46 -- ** Generalisations of list functions
48 , join -- :: (Monad m) => m (m a) -> m a
49 , msum -- :: (MonadPlus m) => [m a] -> m a
50 , mfilter -- :: (MonadPlus m) => (a -> Bool) -> m a -> m a
51 , filterM -- :: (Monad m) => (a -> m Bool) -> [a] -> m [a]
52 , mapAndUnzipM -- :: (Monad m) => (a -> m (b,c)) -> [a] -> m ([b], [c])
53 , zipWithM -- :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m [c]
54 , zipWithM_ -- :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m ()
55 , foldM -- :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
56 , foldM_ -- :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m ()
57 , replicateM -- :: (Monad m) => Int -> m a -> m [a]
58 , replicateM_ -- :: (Monad m) => Int -> m a -> m ()
60 -- ** Conditional execution of monadic expressions
62 , guard -- :: (MonadPlus m) => Bool -> m ()
63 , when -- :: (Monad m) => Bool -> m () -> m ()
64 , unless -- :: (Monad m) => Bool -> m () -> m ()
66 -- ** Monadic lifting operators
68 , liftM -- :: (Monad m) => (a -> b) -> (m a -> m b)
69 , liftM2 -- :: (Monad m) => (a -> b -> c) -> (m a -> m b -> m c)
74 , ap -- :: (Monad m) => m (a -> b) -> m a -> m b
80 #ifdef __GLASGOW_HASKELL__
85 #ifdef __GLASGOW_HASKELL__
88 -- -----------------------------------------------------------------------------
89 -- Prelude monad functions
91 -- | Same as '>>=', but with the arguments interchanged.
92 {-# SPECIALISE (=<<) :: (a -> [b]) -> [a] -> [b] #-}
93 (=<<) :: Monad m => (a -> m b) -> m a -> m b
96 -- | Evaluate each action in the sequence from left to right,
97 -- and collect the results.
98 sequence :: Monad m => [m a] -> m [a]
99 {-# INLINE sequence #-}
100 sequence ms = foldr k (return []) ms
102 k m m' = do { x <- m; xs <- m'; return (x:xs) }
104 -- | Evaluate each action in the sequence from left to right,
105 -- and ignore the results.
106 sequence_ :: Monad m => [m a] -> m ()
107 {-# INLINE sequence_ #-}
108 sequence_ ms = foldr (>>) (return ()) ms
110 -- | @'mapM' f@ is equivalent to @'sequence' . 'map' f@.
111 mapM :: Monad m => (a -> m b) -> [a] -> m [b]
113 mapM f as = sequence (map f as)
115 -- | @'mapM_' f@ is equivalent to @'sequence_' . 'map' f@.
116 mapM_ :: Monad m => (a -> m b) -> [a] -> m ()
118 mapM_ f as = sequence_ (map f as)
120 #endif /* __GLASGOW_HASKELL__ */
122 -- -----------------------------------------------------------------------------
123 -- The MonadPlus class definition
125 -- | Monads that also support choice and failure.
126 class Monad m => MonadPlus m where
127 -- | the identity of 'mplus'. It should also satisfy the equations
129 -- > mzero >>= f = mzero
130 -- > v >> mzero = mzero
133 -- | an associative operation
134 mplus :: m a -> m a -> m a
136 instance MonadPlus [] where
140 instance MonadPlus Maybe where
143 Nothing `mplus` ys = ys
146 -- -----------------------------------------------------------------------------
147 -- Functions mandated by the Prelude
149 -- | @'guard' b@ is @'return' ()@ if @b@ is 'True',
150 -- and 'mzero' if @b@ is 'False'.
151 guard :: (MonadPlus m) => Bool -> m ()
152 guard True = return ()
155 -- | This generalizes the list-based 'filter' function.
157 filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]
158 filterM _ [] = return []
159 filterM p (x:xs) = do
162 return (if flg then x:ys else ys)
164 -- | 'forM' is 'mapM' with its arguments flipped
165 forM :: Monad m => [a] -> (a -> m b) -> m [b]
169 -- | 'forM_' is 'mapM_' with its arguments flipped
170 forM_ :: Monad m => [a] -> (a -> m b) -> m ()
174 -- | This generalizes the list-based 'concat' function.
176 msum :: MonadPlus m => [m a] -> m a
178 msum = foldr mplus mzero
182 -- | Left-to-right Kleisli composition of monads.
183 (>=>) :: Monad m => (a -> m b) -> (b -> m c) -> (a -> m c)
184 f >=> g = \x -> f x >>= g
186 -- | Right-to-left Kleisli composition of monads. @('>=>')@, with the arguments flipped
187 (<=<) :: Monad m => (b -> m c) -> (a -> m b) -> (a -> m c)
190 -- | @'forever' act@ repeats the action infinitely.
191 forever :: (Monad m) => m a -> m b
192 {-# INLINABLE forever #-} -- See Note [Make forever INLINABLE]
193 forever a = a >> forever a
195 {- Note [Make forever INLINABLE]
197 If you say x = forever a
198 you'll get x = a >> a >> a >> a >> ... etc ...
199 and that can make a massive space leak (see Trac #5205)
201 In some monads, where (>>) is expensive, this might be the right
202 thing, but not in the IO monad. We want to specialise 'forever' for
203 the IO monad, so that eta expansion happens and there's no space leak.
204 To achieve this we must make forever INLINABLE, so that it'll get
205 specialised at call sites.
207 Still delicate, though, because it depends on optimisation. But there
208 really is a space/time tradeoff here, and only optimisation reveals
212 -- | @'void' value@ discards or ignores the result of evaluation, such as the return value of an 'IO' action.
213 void :: Functor f => f a -> f ()
214 void = fmap (const ())
216 -- -----------------------------------------------------------------------------
217 -- Other monad functions
219 -- | The 'join' function is the conventional monad join operator. It is used to
220 -- remove one level of monadic structure, projecting its bound argument into the
222 join :: (Monad m) => m (m a) -> m a
225 -- | The 'mapAndUnzipM' function maps its first argument over a list, returning
226 -- the result as a pair of lists. This function is mainly used with complicated
227 -- data structures or a state-transforming monad.
228 mapAndUnzipM :: (Monad m) => (a -> m (b,c)) -> [a] -> m ([b], [c])
229 mapAndUnzipM f xs = sequence (map f xs) >>= return . unzip
231 -- | The 'zipWithM' function generalizes 'zipWith' to arbitrary monads.
232 zipWithM :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m [c]
233 zipWithM f xs ys = sequence (zipWith f xs ys)
235 -- | 'zipWithM_' is the extension of 'zipWithM' which ignores the final result.
236 zipWithM_ :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m ()
237 zipWithM_ f xs ys = sequence_ (zipWith f xs ys)
239 {- | The 'foldM' function is analogous to 'foldl', except that its result is
240 encapsulated in a monad. Note that 'foldM' works from left-to-right over
241 the list arguments. This could be an issue where @('>>')@ and the `folded
242 function' are not commutative.
245 > foldM f a1 [x1, x2, ..., xm]
255 If right-to-left evaluation is required, the input list should be reversed.
258 foldM :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
259 foldM _ a [] = return a
260 foldM f a (x:xs) = f a x >>= \fax -> foldM f fax xs
262 -- | Like 'foldM', but discards the result.
263 foldM_ :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m ()
264 foldM_ f a xs = foldM f a xs >> return ()
266 -- | @'replicateM' n act@ performs the action @n@ times,
267 -- gathering the results.
268 replicateM :: (Monad m) => Int -> m a -> m [a]
269 replicateM n x = sequence (replicate n x)
271 -- | Like 'replicateM', but discards the result.
272 replicateM_ :: (Monad m) => Int -> m a -> m ()
273 replicateM_ n x = sequence_ (replicate n x)
275 {- | Conditional execution of monadic expressions. For example,
277 > when debug (putStr "Debugging\n")
279 will output the string @Debugging\\n@ if the Boolean value @debug@ is 'True',
280 and otherwise do nothing.
283 when :: (Monad m) => Bool -> m () -> m ()
284 when p s = if p then s else return ()
286 -- | The reverse of 'when'.
288 unless :: (Monad m) => Bool -> m () -> m ()
289 unless p s = if p then return () else s
291 -- | Promote a function to a monad.
292 liftM :: (Monad m) => (a1 -> r) -> m a1 -> m r
293 liftM f m1 = do { x1 <- m1; return (f x1) }
295 -- | Promote a function to a monad, scanning the monadic arguments from
296 -- left to right. For example,
298 -- > liftM2 (+) [0,1] [0,2] = [0,2,1,3]
299 -- > liftM2 (+) (Just 1) Nothing = Nothing
301 liftM2 :: (Monad m) => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
302 liftM2 f m1 m2 = do { x1 <- m1; x2 <- m2; return (f x1 x2) }
304 -- | Promote a function to a monad, scanning the monadic arguments from
305 -- left to right (cf. 'liftM2').
306 liftM3 :: (Monad m) => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r
307 liftM3 f m1 m2 m3 = do { x1 <- m1; x2 <- m2; x3 <- m3; return (f x1 x2 x3) }
309 -- | Promote a function to a monad, scanning the monadic arguments from
310 -- left to right (cf. 'liftM2').
311 liftM4 :: (Monad m) => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r
312 liftM4 f m1 m2 m3 m4 = do { x1 <- m1; x2 <- m2; x3 <- m3; x4 <- m4; return (f x1 x2 x3 x4) }
314 -- | Promote a function to a monad, scanning the monadic arguments from
315 -- left to right (cf. 'liftM2').
316 liftM5 :: (Monad m) => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r
317 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) }
319 {- | In many situations, the 'liftM' operations can be replaced by uses of
320 'ap', which promotes function application.
322 > return f `ap` x1 `ap` ... `ap` xn
326 > liftMn f x1 x2 ... xn
330 ap :: (Monad m) => m (a -> b) -> m a -> m b
334 -- -----------------------------------------------------------------------------
335 -- Other MonadPlus functions
337 -- | Direct 'MonadPlus' equivalent of 'filter'
338 -- @'filter'@ = @(mfilter:: (a -> Bool) -> [a] -> [a]@
339 -- applicable to any 'MonadPlus', for example
340 -- @mfilter odd (Just 1) == Just 1@
341 -- @mfilter odd (Just 2) == Nothing@
343 mfilter :: (MonadPlus m) => (a -> Bool) -> m a -> m a
346 if p a then return a else mzero
350 The functions in this library use the following naming conventions:
352 * A postfix \'@M@\' always stands for a function in the Kleisli category:
353 The monad type constructor @m@ is added to function results
354 (modulo currying) and nowhere else. So, for example,
356 > filter :: (a -> Bool) -> [a] -> [a]
357 > filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]
359 * A postfix \'@_@\' changes the result type from @(m a)@ to @(m ())@.
362 > sequence :: Monad m => [m a] -> m [a]
363 > sequence_ :: Monad m => [m a] -> m ()
365 * A prefix \'@m@\' generalizes an existing function to a monadic form.
368 > sum :: Num a => [a] -> a
369 > msum :: MonadPlus m => [m a] -> m a