Copyright | (c) The University of Glasgow 2001 |
---|---|

License | BSD-style (see the file libraries/base/LICENSE) |

Maintainer | libraries@haskell.org |

Stability | provisional |

Portability | portable |

Safe Haskell | Trustworthy |

Language | Haskell2010 |

- class Functor f where
- fmap :: (a -> b) -> f a -> f b

- class Applicative m => Monad m where
- class (Alternative m, Monad m) => MonadPlus m where
- mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)
- mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()
- forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
- forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m ()
- sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
- sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
- (=<<) :: Monad m => (a -> m b) -> m a -> m b
- (>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
- (<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
- forever :: Monad m => m a -> m b
- void :: Functor f => f a -> f ()
- join :: Monad m => m (m a) -> m a
- msum :: (Foldable t, MonadPlus m) => t (m a) -> m a
- mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a
- filterM :: Monad m => (a -> m Bool) -> [a] -> m [a]
- mapAndUnzipM :: Monad m => (a -> m (b, c)) -> [a] -> m ([b], [c])
- zipWithM :: Monad m => (a -> b -> m c) -> [a] -> [b] -> m [c]
- zipWithM_ :: Monad m => (a -> b -> m c) -> [a] -> [b] -> m ()
- foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
- foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m ()
- replicateM :: Monad m => Int -> m a -> m [a]
- replicateM_ :: Monad m => Int -> m a -> m ()
- guard :: Alternative f => Bool -> f ()
- when :: Applicative f => Bool -> f () -> f ()
- unless :: Applicative f => Bool -> f () -> f ()
- liftM :: Monad m => (a1 -> r) -> m a1 -> m r
- liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
- liftM3 :: Monad m => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r
- liftM4 :: Monad m => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r
- liftM5 :: Monad m => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r
- ap :: Monad m => m (a -> b) -> m a -> m b
- (<$!>) :: Monad m => (a -> b) -> m a -> m b

# Functor and monad classes

The `Functor`

class is used for types that can be mapped over.
Instances of `Functor`

should satisfy the following laws:

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

The instances of `Functor`

for lists, `Maybe`

and `IO`

satisfy these laws.

Functor [] | |

Functor IO | |

Functor Maybe | |

Functor ReadP | |

Functor ReadPrec | |

Functor Last | |

Functor First | |

Functor STM | |

Functor Handler | |

Functor ZipList | |

Functor Identity | |

Functor ArgDescr | |

Functor OptDescr | |

Functor ArgOrder | |

Functor ((->) r) | |

Functor (Either a) | |

Functor ((,) a) | |

Functor (ST s) | |

Functor (Proxy *) | |

Arrow a => Functor (ArrowMonad a) | |

Monad m => Functor (WrappedMonad m) | |

Functor (Const m) | |

Functor (ST s) | |

Functor f => Functor (Alt * f) | |

Arrow a => Functor (WrappedArrow a b) |

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 laws:

Furthermore, the `Monad`

and `Applicative`

operations should relate as follows:

The above laws imply:

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.

(>>=) :: forall a b. m a -> (a -> m b) -> m b infixl 1 Source

Sequentially compose two actions, passing any value produced by the first as an argument to the second.

(>>) :: forall a b. m a -> m b -> m b infixl 1 Source

Sequentially compose two actions, discarding any value produced by the first, like sequencing operators (such as the semicolon) in imperative languages.

Inject a value into the monadic type.

Fail with a message. This operation is not part of the
mathematical definition of a monad, but is invoked on pattern-match
failure in a `do`

expression.

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

Monads that also support choice and failure.

Nothing

# Functions

## Naming conventions

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:

sum :: Num a => [a] -> a msum :: MonadPlus m => [m a] -> m a

## Basic `Monad`

functions

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

.

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

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 Kleisli composition of monads.

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

Right-to-left Kleisli composition of monads. `(`

, with the arguments flipped`>=>`

)

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

discards or ignores the result of evaluation, such
as the return value of an `void`

value`IO`

action.

#### Examples

Replace the contents of a

with unit:`Maybe`

`Int`

`>>>`

Nothing`void Nothing`

`>>>`

Just ()`void (Just 3)`

Replace the contents of an

with unit,
resulting in an `Either`

`Int`

`Int`

:`Either`

`Int`

'()'

`>>>`

Left 8675309`void (Left 8675309)`

`>>>`

Right ()`void (Right 8675309)`

Replace every element of a list with unit:

`>>>`

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

Replace the second element of a pair with unit:

`>>>`

(1,())`void (1,2)`

Discard the result of an `IO`

action:

`>>>`

1 2 [(),()]`mapM print [1,2]`

`>>>`

1 2`void $ mapM print [1,2]`

## Generalisations of list functions

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.

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

This generalizes the list-based `filter`

function.

mapAndUnzipM :: Monad 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-transforming monad.

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.

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

Like `foldM`

, but discards the result.

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

performs the action `replicateM`

n act`n`

times,
gathering the results.

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

Like `replicateM`

, but discards the result.

## Conditional execution of monadic expressions

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

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`

.

## Monadic lifting operators

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`

).