base-4.8.0.0: Basic libraries

Copyright (c) The University of Glasgow 2001 BSD-style (see the file libraries/base/LICENSE) libraries@haskell.org provisional portable Trustworthy Haskell2010

Description

The `Functor`, `Monad` and `MonadPlus` classes, with some useful operations on monads.

Synopsis

# Functor and monad classes

class Functor f where Source

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.

Methods

fmap :: (a -> b) -> f a -> f b Source

Instances

 Functor [] Source Functor IO Source Functor Maybe Source Functor ReadP Source Functor ReadPrec Source Functor Last Source Functor First Source Functor STM Source Functor Handler Source Functor ZipList Source Functor Identity Source Functor ArgDescr Source Functor OptDescr Source Functor ArgOrder Source Functor ((->) r) Source Functor (Either a) Source Functor ((,) a) Source Functor (ST s) Source Functor (Proxy *) Source Arrow a => Functor (ArrowMonad a) Source Monad m => Functor (WrappedMonad m) Source Functor (Const m) Source Functor (ST s) Source Functor f => Functor (Alt * f) Source Arrow a => Functor (WrappedArrow a b) Source

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:

• ``return` a `>>=` k  =  k a`
• `m `>>=` `return`  =  m`
• `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.

Minimal complete definition

(>>=)

Methods

(>>=) :: 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.

return :: a -> m a Source

Inject a value into the monadic type.

fail :: String -> m a Source

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.

Instances

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

Monads that also support choice and failure.

Minimal complete definition

Nothing

Methods

mzero :: m a Source

the identity of `mplus`. It should also satisfy the equations

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

mplus :: m a -> m a -> m a Source

an associative operation

Instances

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

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

forever :: Monad m => m a -> m b Source

`forever act` repeats the action infinitely.

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

Replace the contents of a `Maybe Int` with unit:

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

Replace the contents of an `Either Int Int` with unit, resulting in an `Either Int '()'`:

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

Replace every element of a list with unit:

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

Replace the second element of a pair with unit:

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

Discard the result of an `IO` action:

````>>> ````mapM print [1,2]
```1
2
[(),()]
`>>> ````void \$ mapM print [1,2]
```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.

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` `filter` = `(mfilter:: (a -> Bool) -> [a] -> [a]` applicable to any `MonadPlus`, for example `mfilter odd (Just 1) == Just 1` `mfilter odd (Just 2) == Nothing`

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.

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

The `zipWithM` function generalizes `zipWith` to arbitrary monads.

zipWithM_ :: Monad 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 :: Monad m => Int -> m a -> m [a] Source

`replicateM n act` performs the action `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

`guard b` is `pure ()` if `b` is `True`, and `empty` if `b` is `False`.

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

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`

## Strict monadic functions

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

Strict version of `<\$>`.

Since: 4.8.0.0