| 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 |
Control.Monad
Contents
- 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
class Functor f where
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
Instances
| 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
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.
Minimal complete definition
Methods
(>>=) :: forall a b. m a -> (a -> m b) -> m b infixl 1
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
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
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
Monads that also support choice and failure.
Minimal complete definition
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 constructormis 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)
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)
sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
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 ()
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
Same as >>=, but with the arguments interchanged.
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c infixr 1
Left-to-right Kleisli composition of monads.
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c infixr 1
Right-to-left Kleisli composition of monads. (, with the arguments flipped>=>)
void :: Functor f => f a -> f ()
discards or ignores the result of evaluation, such
as the return value of an void valueIO action.
Examples
Replace the contents of a with unit:Maybe Int
>>>void NothingNothing>>>void (Just 3)Just ()
Replace the contents of an with unit,
resulting in an Either Int Int: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
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.
mapAndUnzipM :: Monad m => (a -> m (b, c)) -> [a] -> m ([b], [c])
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
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 xmIf 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 ()
Like foldM, but discards the result.
replicateM :: Monad m => Int -> m a -> m [a]
performs the action replicateM n actn times,
gathering the results.
replicateM_ :: Monad m => Int -> m a -> m ()
Like replicateM, but discards the result.
Conditional execution of monadic expressions
when :: Applicative f => Bool -> f () -> f ()
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 ()
The reverse of when.
Monadic lifting operators
liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
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
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
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
Promote a function to a monad, scanning the monadic arguments from
left to right (cf. liftM2).