Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

Compose functions

>>> (+1) >.> (*7) <| 1
14

Compose functions

>>> (+1) <.< (*7) <| 1
8

Apply a function

>>> 5 |> (*2)
10

Apply a function

>>> (*2) <| 5
10

Apply a function in a Functor

>>> Just 5 ||> (*2)
Just 10

Apply a function in a Functor

>>> (*2) <|| Just 5
Just 10

Apply a function in a Functor

>>> Just [5] |||> (*2)
Just [10]

Apply a function in a Functor

>>> (*2) <||| Just [5]
Just [10]

Conditional execution of Applicative expressions. For example,

when debug (putStrLn "Debugging")

will output the string Debugging if the Boolean value debug is True, and otherwise do nothing.

The reverse of when.

Like when, but where the test can be monadic.

Like unless, but where the test can be monadic.

Like if, but where the test can be monadic.

Conditional failure of Alternative computations. Defined by

guard True  = pure ()
guard False = empty

Examples

>>> safeDiv 4 0
Nothing
>>> safeDiv 4 2
Just 2

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y | y /= 0    = Just (x `div` y)
            | otherwise = Nothing

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y = do
  guard (y /= 0)
  return (x `div` y)

void value discards or ignores the result of evaluation, such as the return value of an IO action.

Examples

>>> void Nothing
Nothing
>>> void (Just 3)
Just ()

>>> void (Left 8675309)
Left 8675309
>>> void (Right 8675309)
Right ()

>>> void [1,2,3]
[(),(),()]

>>> void (1,2)
(1,())

>>> mapM print [1,2]
1
2
[(),()]
>>> void $ mapM print [1,2]
1
2

Repeat an action indefinitely.

Examples

echoServer :: Socket -> IO ()
echoServer socket = forever $ do
  client <- accept socket
  forkFinally (echo client) (\_ -> hClose client)
  where
    echo :: Handle -> IO ()
    echo client = forever $
      hGetLine client >>= hPutStrLn client

The foldM function is analogous to foldl, except that its result is encapsulated in a monad. Note that foldM works from left-to-right over the list arguments. This could be an issue where (>>) and the `folded function' are not commutative.

foldM f a1 [x1, x2, ..., xm]

==

do
  a2 <- f a1 x1
  a3 <- f a2 x2
  ...
  f am xm

If right-to-left evaluation is required, the input list should be reversed.

Note: foldM is the same as foldlM

Like foldM, but discards the result.

forM is mapM with its arguments flipped. For a version that ignores the results see forM_.

forM_ is mapM_ with its arguments flipped. For a version that doesn't ignore the results see forM.

As of base 4.8.0.0, forM_ is just for_, specialized to Monad.

Composition of catMaybes and forM

>>> let f x = if x > 3 then putStrLn "OK" >> return (Just x) else return Nothing
>>> forMaybeM [0..5] f
OK
OK
[4,5]

Map each element of a structure to a monadic action, evaluate these actions from left to right, and collect the results. For a version that ignores the results see mapM_.

Map each element of a structure to a monadic action, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results see mapM.

As of base 4.8.0.0, mapM_ is just traverse_, specialized to Monad.

Evaluate each monadic action in the structure from left to right, and collect the results. For a version that ignores the results see sequence_.

replicateM n act performs the action n times, gathering the results.

Like replicateM, but discards the result.

This generalizes the list-based filter function.

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

Examples

atomically :: STM a -> IO a

atomically :: STM (IO b) -> IO (IO b)
join       :: IO (IO b)  -> IO b

join . atomically :: STM (IO b) -> IO b

Right-to-left composition of Kleisli arrows. (>=>), with the arguments flipped.

Note how this operator resembles function composition (.):

(.)   ::            (b ->   c) -> (a ->   b) -> a ->   c
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c

Left-to-right composition of Kleisli arrows.

A monadic version of loop, where the predicate returns Left as a seed for the next loop or Right to abort the loop.

Keep running an operation until it becomes False. As an example:

whileM $ do sleep 0.1; notM $ doesFileExist "foo.txt"
readFile "foo.txt"

If you need some state persisted between each test, use loopM.

forM_ with interspersed action

>>> intersperseM_ (putStr ", ") ["1","2","3","4"] putStr
1, 2, 3, 4

Fast for-loop in a Monad (more efficient than forM_ [0..n] for instance).

>>> forLoopM_ (0::Word) (<5) (+1) print
0
1
2
3
4

Fast fort-loop with an accumulated result

>>> let f acc n = acc ++ (if n == 0 then "" else ", ") ++ show n
>>> forLoop (0::Word) (<5) (+1) "" f
"0, 1, 2, 3, 4"

Lift a computation from the argument monad to the constructed monad.