class Functor f where Source

A type f is a Functor if it provides a function fmap which, given any types a and b lets you apply any function from (a -> b) to turn an f a into an f b, preserving the structure of f. Furthermore f needs to adhere to the following:

Identity

fmap id == id

Composition

fmap (f . g) == fmap f . fmap g

Note, that the second law follows from the free theorem of the type fmap and the first law, so you need only check that the former condition holds.

class Applicative m => Monad m where Source

The Monad class defines the basic operations over a monad, a concept from a branch of mathematics known as category theory. From the perspective of a Haskell programmer, however, it is best to think of a monad as an abstract datatype of actions. Haskell's do expressions provide a convenient syntax for writing monadic expressions.

Instances of Monad should satisfy the following:

Left identity

return a >>= k = k a

Right identity

m >>= return = m

Associativity

m >>= (\x -> k x >>= h) = (m >>= k) >>= h

Furthermore, the Monad and Applicative operations should relate as follows:

• pure = return

• (<*>) = ap

The above laws imply:

• fmap f xs  =  xs >>= return . f

• (>>) = (*>)

and that pure and (<*>) satisfy the applicative functor laws.

The instances of Monad for lists, Maybe and IO defined in the Prelude satisfy these laws.

class Monad m => MonadFail m where Source

When a value is bound in do-notation, the pattern on the left hand side of <- might not match. In this case, this class provides a function to recover.

A Monad without a MonadFail instance may only be used in conjunction with pattern that always match, such as newtypes, tuples, data types with only a single data constructor, and irrefutable patterns (~pat).

Instances of MonadFail should satisfy the following law: fail s should be a left zero for >>=,

fail s >>= f  =  fail s

If your Monad is also MonadPlus, a popular definition is

fail _ = mzero

Since: base-4.9.0.0

class (Alternative m, Monad m) => MonadPlus m where Source

Monads that also support choice and failure.

mzero >>= f  =  mzero
v >> mzero   =  mzero

mzero = empty

mplus = (<|>)

The functions in this library use the following naming conventions:

• A postfix 'M' always stands for a function in the Kleisli category: The monad type constructor m is added to function results (modulo currying) and nowhere else. So, for example,

filter  ::              (a ->   Bool) -> [a] ->   [a]
filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]

• A postfix '_' changes the result type from (m a) to (m ()). Thus, for example:

sequence  :: Monad m => [m a] -> m [a]
sequence_ :: Monad m => [m a] -> m ()

• A prefix 'm' generalizes an existing function to a monadic form. Thus, for example:

filter  ::                (a -> Bool) -> [a] -> [a]
mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a

mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b) Source

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_.

mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m () Source

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.

forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b) Source

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

forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m () Source

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.

sequence :: (Traversable t, Monad m) => t (m a) -> m (t a) Source

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

sequence_ :: (Foldable t, Monad m) => t (m a) -> m () Source

Evaluate each monadic action in the structure from left to right, and ignore the results. For a version that doesn't ignore the results see sequence.

As of base 4.8.0.0, sequence_ is just sequenceA_, specialized to Monad.

(=<<) :: Monad m => (a -> m b) -> m a -> m b infixr 1 Source

Same as >>=, but with the arguments interchanged.

(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c infixr 1 Source

Left-to-right composition of Kleisli arrows.

(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c infixr 1 Source

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

forever :: Applicative f => f a -> f b Source

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

void :: Functor f => f a -> f () Source

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

join :: Monad m => m (m a) -> m a Source

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

msum :: (Foldable t, MonadPlus m) => t (m a) -> m a Source

The sum of a collection of actions, generalizing concat. As of base 4.8.0.0, msum is just asum, specialized to MonadPlus.

mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a Source

Direct MonadPlus equivalent of filter.

Examples

filter = ( mfilter :: (a -> Bool) -> [a] -> [a] )

>>> mfilter odd (Just 1)
Just 1
>>> mfilter odd (Just 2)
Nothing

filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a] Source

This generalizes the list-based filter function.

mapAndUnzipM :: Applicative m => (a -> m (b, c)) -> [a] -> m ([b], [c]) Source

The mapAndUnzipM function maps its first argument over a list, returning the result as a pair of lists. This function is mainly used with complicated data structures or a state monad.

zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c] Source

The zipWithM function generalizes zipWith to arbitrary applicative functors.

zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m () Source

zipWithM_ is the extension of zipWithM which ignores the final result.

foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b Source

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

foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m () Source

Like foldM, but discards the result.

replicateM :: Applicative m => Int -> m a -> m [a] Source

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

replicateM_ :: Applicative m => Int -> m a -> m () Source

Like replicateM, but discards the result.

guard :: Alternative f => Bool -> f () Source

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)

when :: Applicative f => Bool -> f () -> f () Source

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.

unless :: Applicative f => Bool -> f () -> f () Source

The reverse of when.

liftM :: Monad m => (a1 -> r) -> m a1 -> m r Source

Promote a function to a monad.

liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r Source

Promote a function to a monad, scanning the monadic arguments from left to right. For example,

liftM2 (+) [0,1] [0,2] = [0,2,1,3]
liftM2 (+) (Just 1) Nothing = Nothing

liftM3 :: Monad m => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r Source

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

liftM4 :: Monad m => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r Source

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

liftM5 :: Monad m => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r Source

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

ap :: Monad m => m (a -> b) -> m a -> m b Source

In many situations, the liftM operations can be replaced by uses of ap, which promotes function application.

return f `ap` x1 `ap` ... `ap` xn

is equivalent to

liftMn f x1 x2 ... xn

(<$!>) :: Monad m => (a -> b) -> m a -> m b infixl 4 Source

Strict version of <$>.

Since: base-4.8.0.0