ghc/lib/std/Monad.lhs

   1 %
   2 % (c) The AQUA Project, Glasgow University, 1994-1996
   3 %
   4 \section[Monad]{Module @Monad@}
   5
   6 \begin{code}
   7 {-# OPTIONS -fno-implicit-prelude #-}
   8
   9 module Monad (
  10     Functor(..),
  11     Monad(..), MonadZero(..), MonadPlus(..),
  12
  13     -- Prelude monad functions
  14     accumulate, sequence,
  15     mapM, mapM_, guard, filter, concat, applyM,
  16
  17     -- Standard Monad interface:
  18     join,           -- :: (Monad m) => m (m a) -> m a
  19     mapAndUnzipM,   -- :: (Monad m) => (a -> m (b,c)) -> [a] -> m ([b], [c])
  20     zipWithM,       -- :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m [c]
  21     zipWithM_,      -- :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m ()
  22     foldM,          -- :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
  23     when,           -- :: (Monad m) => Bool -> m () -> m ()
  24     unless,         -- :: (Monad m) => Bool -> m () -> m ()
  25     ap,             -- :: (Monad m) => (m (a -> b)) -> (m a) -> m b
  26     liftM, liftM2,
  27     liftM3, liftM4,
  28     liftM5
  29   ) where
  30
  31 import PrelList
  32 import PrelTup
  33 import PrelBase
  34 \end{code}
  35
  36 %*********************************************************
  37 %*                                                      *
  38 \subsection{Functions mandated by the Prelude}
  39 %*                                                      *
  40 %*********************************************************
  41
  42 \begin{code}
  43 accumulate      :: Monad m => [m a] -> m [a]
  44 accumulate []     = return []
  45 accumulate (m:ms) = do { x <- m; xs <- accumulate ms; return (x:xs) }
  46
  47 sequence        :: Monad m => [m a] -> m ()
  48 sequence        =  foldr (>>) (return ())
  49
  50 mapM            :: Monad m => (a -> m b) -> [a] -> m [b]
  51 mapM f as       =  accumulate (map f as)
  52
  53 mapM_           :: Monad m => (a -> m b) -> [a] -> m ()
  54 mapM_ f as      =  sequence (map f as)
  55
  56 guard           :: MonadZero m => Bool -> m ()
  57 guard p         =  if p then return () else zero
  58
  59 -- This subsumes the list-based filter function.
  60
  61 {-# SPECIALISE filter :: (a -> Bool) -> [a] -> [a] #-}
  62 filter          :: MonadZero m => (a -> Bool) -> m a -> m a
  63 filter p        =  applyM (\x -> if p x then return x else zero)
  64
  65 -- This subsumes the list-based concat function.
  66
  67 {-# SPECIALISE concat :: [[a]] -> [a] #-}
  68 concat          :: MonadPlus m => [m a] -> m a
  69 concat          =  foldr (++) zero
  70
  71 {-# SPECIALISE applyM :: (a -> [b]) -> [a] -> [b] #-}
  72 applyM          :: Monad m => (a -> m b) -> m a -> m b
  73 applyM f x      =  x >>= f
  74 \end{code}
  75
  76
  77 %*********************************************************
  78 %*                                                      *
  79 \subsection{Other monad functions}
  80 %*                                                      *
  81 %*********************************************************
  82
  83 \begin{code}
  84 join             :: (Monad m) => m (m a) -> m a
  85 join x           = x >>= id
  86
  87 mapAndUnzipM     :: (Monad m) => (a -> m (b,c)) -> [a] -> m ([b], [c])
  88 mapAndUnzipM f xs = accumulate (map f xs) >>= return . unzip
  89
  90 zipWithM         :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m [c]
  91 zipWithM f xs ys = accumulate (zipWith f xs ys)
  92
  93 zipWithM_ :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m ()
  94 zipWithM_ f xs ys = sequence (zipWith f xs ys)
  95
  96 foldM            :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
  97 foldM f a []     = return a
  98 foldM f a (x:xs) = f a x >>= \fax -> foldM f fax xs
  99
 100 unless           :: (Monad m) => Bool -> m () -> m ()
 101 unless p s       =  if p then return () else s
 102
 103 when             :: (Monad m) => Bool -> m () -> m ()
 104 when p s         =  if p then s else return ()
 105
 106 ap :: (Monad m) => m (a->b) -> m a -> m b
 107 ap = liftM2 ($)
 108
 109 liftM   :: (Monad m) => (a1 -> r) -> m a1 -> m r
 110 liftM2  :: (Monad m) => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
 111 liftM3  :: (Monad m) => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r
 112 liftM4  :: (Monad m) => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r
 113 liftM5  :: (Monad m) => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r
 114
 115 liftM f m1              = do { x1 <- m1; return (f x1) }
 116 liftM2 f m1 m2          = do { x1 <- m1; x2 <- m2; return (f x1 x2) }
 117 liftM3 f m1 m2 m3       = do { x1 <- m1; x2 <- m2; x3 <- m3; return (f x1 x2 x3) }
 118 liftM4 f m1 m2 m3 m4    = do { x1 <- m1; x2 <- m2; x3 <- m3; x4 <- m4; return (f x1 x2 x3 x4) }
 119 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) }
 120
 121 \end{code}