| Safe Haskell | None |
|---|---|
| Language | GHC2021 |
GHC.Utils.Monad
Description
Utilities related to Monad and Applicative classes Mostly for backwards compatibility.
Synopsis
- class Functor f => Applicative (f :: Type -> Type) where
- (<$>) :: Functor f => (a -> b) -> f a -> f b
- class Monad m => MonadFix (m :: Type -> Type) where
- mfix :: (a -> m a) -> m a
- class Monad m => MonadIO (m :: Type -> Type) where
- zipWith3M :: Monad m => (a -> b -> c -> m d) -> [a] -> [b] -> [c] -> m [d]
- zipWith3M_ :: Monad m => (a -> b -> c -> m d) -> [a] -> [b] -> [c] -> m ()
- zipWith4M :: Monad m => (a -> b -> c -> d -> m e) -> [a] -> [b] -> [c] -> [d] -> m [e]
- zipWithAndUnzipM :: Monad m => (a -> b -> m (c, d)) -> [a] -> [b] -> m ([c], [d])
- zipWith3MNE :: Monad m => (a -> b -> c -> m d) -> NonEmpty a -> NonEmpty b -> NonEmpty c -> m (NonEmpty d)
- mapAndUnzipM :: Applicative m => (a -> m (b, c)) -> [a] -> m ([b], [c])
- mapAndUnzip3M :: Monad m => (a -> m (b, c, d)) -> [a] -> m ([b], [c], [d])
- mapAndUnzip4M :: Monad m => (a -> m (b, c, d, e)) -> [a] -> m ([b], [c], [d], [e])
- mapAndUnzip5M :: Monad m => (a -> m (b, c, d, e, f)) -> [a] -> m ([b], [c], [d], [e], [f])
- mapAccumLM :: (Monad m, Traversable t) => (acc -> x -> m (acc, y)) -> acc -> t x -> m (acc, t y)
- mapSndM :: (Applicative m, Traversable f) => (b -> m c) -> f (a, b) -> m (f (a, c))
- concatMapM :: (Monad m, Traversable f) => (a -> m [b]) -> f a -> m [b]
- mapMaybeM :: Applicative m => (a -> m (Maybe b)) -> [a] -> m [b]
- anyM :: (Monad m, Foldable f) => (a -> m Bool) -> f a -> m Bool
- allM :: (Monad m, Foldable f) => (a -> m Bool) -> f a -> m Bool
- orM :: Monad m => m Bool -> m Bool -> m Bool
- foldlM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
- foldlM_ :: (Monad m, Foldable t) => (a -> b -> m a) -> a -> t b -> m ()
- foldrM :: (Foldable t, Monad m) => (a -> b -> m b) -> b -> t a -> m b
- foldMapM :: (Applicative m, Foldable t, Monoid b) => (a -> m b) -> t a -> m b
- whenM :: Monad m => m Bool -> m () -> m ()
- unlessM :: Monad m => m Bool -> m () -> m ()
- filterOutM :: Applicative m => (a -> m Bool) -> [a] -> m [a]
- partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a])
Documentation
class Functor f => Applicative (f :: Type -> Type) where Source #
A functor with application, providing operations to
A minimal complete definition must include implementations of pure
and one of either <*> or liftA2. If it defines both, then they must behave
the same as their default definitions:
(<*>) =liftA2id
liftA2f x y = f<$>x<*>y
Further, any definition must satisfy the following:
- Identity
pureid<*>v = v- Composition
pure(.)<*>u<*>v<*>w = u<*>(v<*>w)- Homomorphism
puref<*>purex =pure(f x)- Interchange
u
<*>purey =pure($y)<*>u
The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:
As a consequence of these laws, the Functor instance for f will satisfy
It may be useful to note that supposing
forall x y. p (q x y) = f x . g y
it follows from the above that
liftA2p (liftA2q u v) =liftA2f u .liftA2g v
If f is also a Monad, it should satisfy
(which implies that pure and <*> satisfy the applicative functor laws).
Methods
Lift a value into the Structure.
Examples
>>>pure 1 :: Maybe IntJust 1
>>>pure 'z' :: [Char]"z"
>>>pure (pure ":D") :: Maybe [String]Just [":D"]
(<*>) :: f (a -> b) -> f a -> f b infixl 4 Source #
Sequential application.
A few functors support an implementation of <*> that is more
efficient than the default one.
Example
Used in combination with (<$>)(<*>)
>>>data MyState = MyState {arg1 :: Foo, arg2 :: Bar, arg3 :: Baz}
>>>produceFoo :: Applicative f => f Foo>>>produceBar :: Applicative f => f Bar>>>produceBaz :: Applicative f => f Baz
>>>mkState :: Applicative f => f MyState>>>mkState = MyState <$> produceFoo <*> produceBar <*> produceBaz
liftA2 :: (a -> b -> c) -> f a -> f b -> f c Source #
Lift a binary function to actions.
Some functors support an implementation of liftA2 that is more
efficient than the default one. In particular, if fmap is an
expensive operation, it is likely better to use liftA2 than to
fmap over the structure and then use <*>.
This became a typeclass method in 4.10.0.0. Prior to that, it was
a function defined in terms of <*> and fmap.
Example
>>>liftA2 (,) (Just 3) (Just 5)Just (3,5)
>>>liftA2 (+) [1, 2, 3] [4, 5, 6][5,6,7,6,7,8,7,8,9]
(*>) :: f a -> f b -> f b infixl 4 Source #
Sequence actions, discarding the value of the first argument.
Examples
If used in conjunction with the Applicative instance for Maybe,
you can chain Maybe computations, with a possible "early return"
in case of Nothing.
>>>Just 2 *> Just 3Just 3
>>>Nothing *> Just 3Nothing
Of course a more interesting use case would be to have effectful computations instead of just returning pure values.
>>>import Data.Char>>>import GHC.Internal.Text.ParserCombinators.ReadP>>>let p = string "my name is " *> munch1 isAlpha <* eof>>>readP_to_S p "my name is Simon"[("Simon","")]
(<*) :: f a -> f b -> f a infixl 4 Source #
Sequence actions, discarding the value of the second argument.
Instances
(<$>) :: Functor f => (a -> b) -> f a -> f b infixl 4 Source #
An infix synonym for fmap.
The name of this operator is an allusion to $.
Note the similarities between their types:
($) :: (a -> b) -> a -> b (<$>) :: Functor f => (a -> b) -> f a -> f b
Whereas $ is function application, <$> is function
application lifted over a Functor.
Examples
Convert from a Maybe IntMaybe
Stringshow:
>>>show <$> NothingNothing
>>>show <$> Just 3Just "3"
Convert from an Either Int IntEither IntString using show:
>>>show <$> Left 17Left 17
>>>show <$> Right 17Right "17"
Double each element of a list:
>>>(*2) <$> [1,2,3][2,4,6]
Apply even to the second element of a pair:
>>>even <$> (2,2)(2,True)
class Monad m => MonadFix (m :: Type -> Type) where Source #
Monads having fixed points with a 'knot-tying' semantics.
Instances of MonadFix should satisfy the following laws:
- Purity
mfix(return. h) =return(fixh)- Left shrinking (or Tightening)
mfix(\x -> a >>= \y -> f x y) = a >>= \y ->mfix(\x -> f x y)- Sliding
mfix(liftMh . f) =liftMh (mfix(f . h))h.- Nesting
mfix(\x ->mfix(\y -> f x y)) =mfix(\x -> f x x)
This class is used in the translation of the recursive do notation
supported by GHC and Hugs.
Methods
Instances
class Monad m => MonadIO (m :: Type -> Type) where Source #
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:
Methods
liftIO :: IO a -> m a Source #
Lift a computation from the IO monad.
This allows us to run IO computations in any monadic stack, so long as it supports these kinds of operations
(i.e. IO is the base monad for the stack).
Example
import Control.Monad.Trans.State -- from the "transformers" library printState :: Show s => StateT s IO () printState = do state <- get liftIO $ print state
Had we omitted liftIO
• Couldn't match type ‘IO’ with ‘StateT s IO’ Expected type: StateT s IO () Actual type: IO ()
The important part here is the mismatch between StateT s IO () and IO ()
Luckily, we know of a function that takes an IO a(m a): liftIO
> evalStateT printState "hello" "hello" > evalStateT printState 3 3
Instances
zipWith3M_ :: Monad m => (a -> b -> c -> m d) -> [a] -> [b] -> [c] -> m () Source #
zipWithAndUnzipM :: Monad m => (a -> b -> m (c, d)) -> [a] -> [b] -> m ([c], [d]) Source #
zipWith3MNE :: Monad m => (a -> b -> c -> m d) -> NonEmpty a -> NonEmpty b -> NonEmpty c -> m (NonEmpty d) Source #
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.
mapAndUnzip3M :: Monad m => (a -> m (b, c, d)) -> [a] -> m ([b], [c], [d]) Source #
mapAndUnzipM for triples
mapAndUnzip4M :: Monad m => (a -> m (b, c, d, e)) -> [a] -> m ([b], [c], [d], [e]) Source #
mapAndUnzip5M :: Monad m => (a -> m (b, c, d, e, f)) -> [a] -> m ([b], [c], [d], [e], [f]) Source #
Arguments
| :: (Monad m, Traversable t) | |
| => (acc -> x -> m (acc, y)) | combining function |
| -> acc | initial state |
| -> t x | inputs |
| -> m (acc, t y) | final state, outputs |
Monadic version of mapAccumL
mapSndM :: (Applicative m, Traversable f) => (b -> m c) -> f (a, b) -> m (f (a, c)) Source #
Monadic version of mapSnd
concatMapM :: (Monad m, Traversable f) => (a -> m [b]) -> f a -> m [b] Source #
Monadic version of concatMap
mapMaybeM :: Applicative m => (a -> m (Maybe b)) -> [a] -> m [b] Source #
Applicative version of mapMaybe
anyM :: (Monad m, Foldable f) => (a -> m Bool) -> f a -> m Bool Source #
Monadic version of any, aborts the computation at the first True value
allM :: (Monad m, Foldable f) => (a -> m Bool) -> f a -> m Bool Source #
Monad version of all, aborts the computation at the first False value
foldlM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b Source #
Left-to-right monadic fold over the elements of a structure.
Given a structure t with elements (a, b, ..., w, x, y), the result of
a fold with an operator function f is equivalent to:
foldlM f z t = do
aa <- f z a
bb <- f aa b
...
xx <- f ww x
yy <- f xx y
return yy -- Just @return z@ when the structure is emptyFor a Monad m, given two functions f1 :: a -> m b and f2 :: b -> m c,
their Kleisli composition (f1 >=> f2) :: a -> m c is defined by:
(f1 >=> f2) a = f1 a >>= f2
Another way of thinking about foldlM is that it amounts to an application
to z of a Kleisli composition:
foldlM f z t =
flip f a >=> flip f b >=> ... >=> flip f x >=> flip f y $ zThe monadic effects of foldlM are sequenced from left to right.
If at some step the bind operator ( short-circuits (as with, e.g.,
>>=)mzero in a MonadPlus), the evaluated effects will be from an initial
segment of the element sequence. If you want to evaluate the monadic
effects in right-to-left order, or perhaps be able to short-circuit after
processing a tail of the sequence of elements, you'll need to use foldrM
instead.
If the monadic effects don't short-circuit, the outermost application of
f is to the rightmost element y, so that, ignoring effects, the result
looks like a left fold:
((((z `f` a) `f` b) ... `f` w) `f` x) `f` y
Examples
Basic usage:
>>>let f a e = do { print e ; return $ e : a }>>>foldlM f [] [0..3]0 1 2 3 [3,2,1,0]
foldlM_ :: (Monad m, Foldable t) => (a -> b -> m a) -> a -> t b -> m () Source #
Monadic version of foldl that discards its result
foldrM :: (Foldable t, Monad m) => (a -> b -> m b) -> b -> t a -> m b Source #
Right-to-left monadic fold over the elements of a structure.
Given a structure t with elements (a, b, c, ..., x, y), the result of
a fold with an operator function f is equivalent to:
foldrM f z t = do
yy <- f y z
xx <- f x yy
...
bb <- f b cc
aa <- f a bb
return aa -- Just @return z@ when the structure is emptyFor a Monad m, given two functions f1 :: a -> m b and f2 :: b -> m c,
their Kleisli composition (f1 >=> f2) :: a -> m c is defined by:
(f1 >=> f2) a = f1 a >>= f2
Another way of thinking about foldrM is that it amounts to an application
to z of a Kleisli composition:
foldrM f z t = f y >=> f x >=> ... >=> f b >=> f a $ z
The monadic effects of foldrM are sequenced from right to left, and e.g.
folds of infinite lists will diverge.
If at some step the bind operator ( short-circuits (as with, e.g.,
>>=)mzero in a MonadPlus), the evaluated effects will be from a tail of the
element sequence. If you want to evaluate the monadic effects in
left-to-right order, or perhaps be able to short-circuit after an initial
sequence of elements, you'll need to use foldlM instead.
If the monadic effects don't short-circuit, the outermost application of
f is to the leftmost element a, so that, ignoring effects, the result
looks like a right fold:
a `f` (b `f` (c `f` (... (x `f` (y `f` z))))).
Examples
Basic usage:
>>>let f i acc = do { print i ; return $ i : acc }>>>foldrM f [] [0..3]3 2 1 0 [0,1,2,3]
foldMapM :: (Applicative m, Foldable t, Monoid b) => (a -> m b) -> t a -> m b Source #
Monadic version of foldMap
whenM :: Monad m => m Bool -> m () -> m () Source #
Monadic version of when, taking the condition in the monad
unlessM :: Monad m => m Bool -> m () -> m () Source #
Monadic version of unless, taking the condition in the monad
filterOutM :: Applicative m => (a -> m Bool) -> [a] -> m [a] Source #
Like filterM, only it reverses the sense of the test.
partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a]) Source #
Monadic version of partition