Module Prelude.PreludeMonad

This package provides the Monad class and related classes and functions.

The class hierarchy is derived from the (Haskell) proposal The Other Prelude but the traditional method names have been kept.

The functions in this library use the following naming conventions:

 filter ::               (a -> Bool)   -> [a] -> [a]
 filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]
 sequence  :: Monad m => [m a] -> m [a]
 sequence_ :: Monad m => [m a] -> m ()
 sum :: Num a => [a] -> a
 msum :: MonadPlus m => [m a] -> m a

This package is implementation specific insofar as the compiler may assume that certain items are defined here in a certain way. Changes may thus lead to compiler crashes or java code that will be rejected by the java compiler.

In particular, desugared do expressions will reference Monad, Bind.>>= and Monad.>>.

This package is implicitly imported and besides the additional stuff covers most of what one would get by importing Control.Monad and Control.Applicative in Haskell.

Imports

Table of Content

Definitions

class Functor f

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

Known Instances

Either, ST, ->, (,), [], (,,)

Member Functions

fmapFunctor f ⇒ (a → b) → f a → f b
infixl  4

Map a function over a Functor

An infix operator that is aliased to Functor.fmap is <$>

class Functor f ⇒ Apply f

Known Instances

Either, ST, [], ->

Member Functions

<*>Apply f ⇒ f (a→b) → f a → f b
infixl  4
class (Functor p, Apply p) ⇒ Applicative p

A functor with application, providing operations to

A minimal complete definition must include implementations of these functions satisfying the following laws:

identity
pure id <*> v = v
composition
pure (•) <> u <> v <> w = u <> (v <*> w)
homomorphism
pure f <*> pure x = pure (f x)
interchange
u <> pure y = pure ($ y) <> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

  u *> v = pure (const id)  <*> u <*> v
  u <* v = pure const <*> u <*> v

As a consequence of these laws, the Functor instance for f will satisfy

 fmap f x = pure f <*> x

If f is also a Monad, it should satisfy

 (<*>) = ap

(which implies that Applicative.pure and Apply.<*> satisfy the applicative functor laws).

Minimal complete definition: Applicative.pure and Apply.<*>.

Known Instances

Either, ST, [], ->

Member Functions

*>Applicative p ⇒ p a → p b → p b
infixl  4

Sequence actions, discarding the value of the first argument.

<*Applicative p ⇒ p a → p b → p a
infixl  4

Sequence actions, discarding the value of the second argument.

pureApplicative p ⇒ a → p a

Lift a value

applyApply p ⇒ p (a→b) → p a → p b
liftAApplicative f ⇒ (a → b) → f a → f b
liftA2Applicative f ⇒ (a → b → c) → f a → f b → f c
liftA3Applicative f ⇒ (a → b → c → d) → f a → f b → f c → f d
liftA4Applicative f ⇒ (a → b → c → d → e) → f a → f b → f c → f d → f e
liftA5Applicative f ⇒ (a → b → c → d → e → g) → f a → f b → f c → f d → f e → f g
class (Functor f, Apply f) ⇒ Bind f

Known Instances

Either, ->, ST, []

Member Functions

>>=Bind f ⇒ f a → (a → f b) → f b
infixl  3

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

class Functor f ⇒ Alt f

Member Functions

<|>Alt f ⇒ f a → f a → f a
infixl  3
class (Functor f, Alt f) ⇒ Plus f

Member Functions

pzeroPlus f ⇒ f a
class (Functor f, Apply f, Bind f, Applicative f, Monad f, Alt f, Plus f) ⇒ MonadAlt f

Member Functions

<+>MonadAlt f ⇒ f a → f a → f a
infixr  13
class (Functor m, Apply m, Bind m, Applicative m) ⇒ Monad m

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 Frege programmer, however, it is best to think of a monad as an abstract datatype of actions.

Frege’s do expressions provide a convenient syntax for writing monadic expressions.

Instances of Monad should satisfy the following laws:

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

Since instances of Monad are also instances of Functor, they additionally shall satisfy the law:

 fmap f xs == xs >>= pure • f

which is also the default implementation of Functor.fmap.

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

Minimal complete definition: Bind.>>= and Applicative.pure

Known Instances

Either, ->, ST, []

Member Functions

<*>Monad m ⇒ m (a→b) → m a → m b
infixl  4
>>Monad m ⇒ m a → m b → m b
infixl  3

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

fmapMonad m ⇒ (a → b) → m a → m b
infixl  4
joinMonad m ⇒ m (m a) → m a

The Monad.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.

class (Functor m, Apply m, Bind m, Applicative m, Monad m) ⇒ MonadFail m

The MonadFail class augments Monad by adding the MonadFail.fail operation. This operation is not part of the mathematical definition of a monad.

Known Instances

[], Either, ST

Member Functions

failMonadFail m ⇒ String → m a

Fail with a message.

class (Functor mz, Apply mz, Bind mz, Applicative mz, Monad mz) ⇒ MonadZero mz

A Monad with a left identity.

Known Instances

[]

Member Functions

mzeroMonadZero mz ⇒ mz a

This value should satisfy left zero:

 mzero >>= f = mzero   
class (Functor mp, Apply mp, Bind mp, Applicative mp, Monad mp, MonadZero mp) ⇒ MonadPlus mp

A Monad that also supports choice and failure and observes the following laws:

 mzero `mplus`  v = v
 v `mplus` mzero  = v
 (a `mplus` b) `mplus` c = a `mplus` (b `mplus` c)
 (a `mplus` b) >>= f = (a >>= f) `mplus` (b >>= f)

Known Instances

[]

Member Functions

mplusMonadPlus mp ⇒ mp a → mp a → mp a
infixr  13

an associative operation

class (Functor mo, Apply mo, Bind mo, Applicative mo, Monad mo, MonadZero mo) ⇒ MonadOr mo

Member Functions

orElseMonadOr mo ⇒ mo a → mo a → mo a
=<<Bind α ⇒ (γ→α β) → α γ → α β
infixr  2

=<< is the same as Bind.>>= with the arguments flipped

>=>Bind α ⇒ (β→α δ) → (δ→α γ) → β → α γ
infixr  3

left to right Kleisli composition of monads

<=<Bind β ⇒ (α→β γ) → (δ→β α) → δ → β γ
infixr  3

Right-to-left Kleisli composition of monads. (>=>), with the arguments flipped

foreverMonad γ ⇒ γ β → γ α

nowarn: deep recursion possible

repeat action forever

voidFunctor β ⇒ β α → β ()

discard or ignore result of evaluation, such as the return value of an IO action.

msumMonadPlus α ⇒ [α β] → α β

msum generalizes the list-based ListMonoid.concat function.

filterM ∷ (Applicative α, Bind α) ⇒ (β→α Bool) → [β] → α [β]

filterM generalizes the list-based filter function.

shortFilterM ∷ (Bind β, Applicative β) ⇒ (α→β Bool) → [α] → β [α]

Version of filterM that works on small lists with length < 1000 only.

Beware of stack overflow, and use filterM, when in doubt.

replicateMMonad m ⇒ Int → m a → m [a]

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

replicateM_Monad m ⇒ Int → m a → m ()

Like replicateM, but discards the result.

apMonad α ⇒ α (γ→β) → α γ → α β

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

       pure f `ap` x1 `ap` ... `ap` xn

is equivalent to

       liftMn f x1 x2 ... xn
liftMMonad m ⇒ (a → b) → m a → m b

Promote a function to a monad.

liftM2 ∷ (Applicative δ, Bind δ) ⇒ (α→β→γ) → δ α → δ β → δ γ

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 ∷ (Applicative α, Bind α) ⇒ (δ→ε→γ→β) → α δ → α ε → α γ → α β

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

liftM4 ∷ (Applicative ε, Bind ε) ⇒ (δ→β→γ→α→ζ) → ε δ → ε β → ε γ → ε α → ε ζ

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

liftM5 ∷ (Applicative γ, Bind γ) ⇒ (α→ζ→η→δ→ε→β) → γ α → γ ζ → γ η → γ δ → γ ε → γ β

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

mapAndUnzipM ∷ (Applicative δ, Bind δ) ⇒ (γ→δ (β, α)) → [γ] → δ ([β], [α])

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 ∷ (Applicative γ, Bind γ) ⇒ (α→β→γ δ) → [α][β] → γ [δ]

The zipWithM function generalizes zipWith to arbitrary monads.

zipWithM_Monad β ⇒ (δ→α→β γ) → [δ][α] → β ()

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

sequence ∷ (Applicative α, Bind α) ⇒ [α β] → α [β]

Turn a list of monadic values [m a] into a monadic value with a list m [a]

 sequence [Just 1, Just 3, Just 2] = Just [1,2,3]

This version of sequence runs in constant stack space, but needs heap space proportional to the size of the input list.

shortSequence ∷ (Applicative β, Bind β) ⇒ [β α] → β [α]

A version of sequence that uses the stack and may overflow with longer lists.

A length of about 500 should be ok in most cases.

sequence_Monad β ⇒ [β α] → β ()

fold (Monad.>>) over a list of monadic values for side effects

mapM ∷ (Applicative β, Bind β) ⇒ (α→β γ) → [α] → β [γ]

mapM f is equivalent to sequence • map f

mapM_Monad β ⇒ (α→β γ) → [α] → β ()

mapM_ f is equivalent to sequence_ • map f

forM ∷ (Applicative β, Bind β) ⇒ [γ] → (γ→β α) → β [α]

forM xs f = mapM_ f xs

forM_Monad γ ⇒ [α] → (α→γ β) → γ ()
for ∷ (Monad m, ListSource listSource) ⇒ listSource e → (e → m a) → m ()

for listSource f is a Java-friendly alias for forM_ that works on any list source

foldM ∷ (Applicative β, Bind β) ⇒ (γ→α→β γ) → γ → [α] → β γ

foldM f a xs folds a monadic function f over the list xs.

shortFoldM ∷ (Applicative α, Bind α) ⇒ (β→γ→α β) → β → [γ] → α β

shortFoldM is suitable only for lists with a length way below 1000.

Beware of stack overflow and use foldM instead.

foldM_Monad β ⇒ (α→γ→β α) → α → [γ] → β ()

foldM_ is the same as foldM, but discards the result

guardMonadZero α ⇒ Bool → α ()

guard b is pure () if b is true, and MonadZero.mzero otherwise.

whenApplicative α ⇒ Bool → α () → α ()

when condition monadic returns /action/ of type Monad m => m () if /condition/ is true, otherwise Applicative.pure ().

unlessApplicative α ⇒ Bool → α () → α ()

opposite of when

type Reader = ->
runReader ∷ (r → a) → r → a
mapReader ∷ (a → b) → (r → a) → r → b
withReader ∷ (e → r) → (r → a) → e → a

Instances

instance Applicative (-> a)

Member Functions

*> ∷ (α→γ) → (α→β) → α → β
infixl  4

inherited from Applicative.*>

<* ∷ (β→α) → (β→γ) → β → α
infixl  4

inherited from Applicative.<*

<*> ∷ (γ→β→α) → (γ→β) → γ → α
infixl  4
fmap ∷ (β → α) → (γ→β) → γ → α
infixl  4
pureα → β → α
instance Functor (a)

Member Functions

fmap ∷ (γ → β) → (α, γ) → (α, β)
infixl  4
instance Functor (a, b)

Member Functions

fmap ∷ (β → δ) → (α, γ, β) → (α, γ, δ)
infixl  4
instance Functor []

Member Functions

fmap ∷ (β → α) → [β] → [α]
infixl  4
instance MonadFail (Either String)

Member Functions

failString → (String | α)
instance MonadFail (ST s)

Member Functions

failStringST β α
instance MonadFail []

Member Functions

failString → [α]
instance MonadPlus []

Member Functions

mplus[α] → [α] → [α]
infixr  13
mzero ∷ [α]
instance Monad (-> a)

Member Functions

>> ∷ (β→α) → (β→γ) → β → γ
infixl  3
>>= ∷ (α→γ) → (γ → α→β) → α → β
infixl  3
join ∷ (β→β→α) → β → α

inherited from Monad.join

pureα → β → α
instance Monad (Either a)

Member Functions

*> ∷ (α | γ) → (α | β) → (α | β)
infixl  4

inherited from Applicative.*>

<* ∷ (γ | β) → (γ | α) → (γ | β)
infixl  4

inherited from Applicative.<*

<*> ∷ (β | α→γ) → (β | α) → (β | γ)
infixl  4

inherited from Monad.<*>

>>(α | γ) → (α | β) → (α | β)
infixl  3

inherited from Monad.>>

>>=(α | γ) → (γ → (α | β)) → (α | β)
infixl  3
fmap ∷ (α → γ) → (β | α) → (β | γ)
infixl  4
join(α | (α | β)) → (α | β)

inherited from Monad.join

pure ∷ α → (β | α)
instance Monad (ST s)

Member Functions

*>ST β α → ST β γ → ST β γ
infixl  4

inherited from Applicative.*>

<*ST α γ → ST α β → ST α γ
infixl  4

inherited from Applicative.<*

<*>ST γ (β→α) → ST γ β → ST γ α
infixl  4

inherited from Monad.<*>

>>ST γ βST γ α → ST γ α
infixl  3
>>=ST u a → (a → ST u b) → ST u b
infixl  3
fmap ∷ (α → γ) → ST β αST β γ
infixl  4
joinST α (ST α β)ST α β

inherited from Monad.join

pure ∷ α → ST β α
instance Monad []

Member Functions

*> ∷ [α] → [β] → [β]
infixl  4

inherited from Applicative.*>

<* ∷ [β] → [α] → [β]
infixl  4

inherited from Applicative.<*

<*> ∷ [β→α] → [β] → [α]
infixl  4

inherited from Monad.<*>

>>[α] → [β] → [β]
infixl  3

inherited from Monad.>>

>>=[β] → (β → [α]) → [α]
infixl  3
join[[α]] → [α]

inherited from Monad.join

pure ∷ α → [α]

Functions and Values by Type

String → (String | α)

MonadFail_Either.fail

String → [α]

MonadFail_[].fail

[[α]] → [α]

Monad_[].join

[α] → [α] → [α]

MonadPlus_[].mplus

α → [α]

Monad_[].pure

Applicative α ⇒ Bool → α () → α ()

unless, when

MonadZero α ⇒ Bool → α ()

guard

[α]

MonadPlus_[].mzero

(r → a) → r → a

runReader

(β → α) → [β] → [α]

Functor_[].fmap

(β→β→α) → β → α

Monad_->.join

(α | (α | β)) → (α | β)

Monad_Either.join

ST α (ST α β) → ST α β

Monad_ST.join

StringST β α

MonadFail_ST.fail

[β→α] → [β] → [α]

Monad_[].<*>

[α] → [β] → [β]

Monad_[].>>, Monad_[].*>

[β] → (β → [α]) → [α]

Monad_[].>>=

[β] → [α] → [β]

Monad_[].<*

α → β → α

Applicative_->.pure, Monad_->.pure

α → (β | α)

Monad_Either.pure

α → ST β α

Monad_ST.pure

Alt f ⇒ f a → f a → f a

Alt.<|>

Applicative p ⇒ a → p a

Applicative.pure

(Applicative α, Bind α) ⇒ (β→α Bool) → [β] → α [β]

filterM

(Applicative α, Bind α) ⇒ [α β] → α [β]

sequence

(Applicative β, Bind β) ⇒ [β α] → β [α]

shortSequence

(Bind β, Applicative β) ⇒ (α→β Bool) → [α] → β [α]

shortFilterM

Functor β ⇒ β α → β ()

void

Monad m ⇒ m (m a) → m a

Monad.join

Monad m ⇒ Int → m a → m [a]

replicateM

Monad m ⇒ Int → m a → m ()

replicateM_

Monad β ⇒ [β α] → β ()

sequence_

MonadAlt f ⇒ f a → f a → f a

MonadAlt.<+>

MonadFail m ⇒ String → m a

MonadFail.fail

MonadOr mo ⇒ mo a → mo a → mo a

MonadOr.orElse

MonadPlus mp ⇒ mp a → mp a → mp a

MonadPlus.mplus

MonadPlus α ⇒ [α β] → α β

msum

MonadZero mz ⇒ mz a

MonadZero.mzero

Plus f ⇒ f a

Plus.pzero

(a → b) → (r → a) → r → b

mapReader

(e → r) → (r → a) → e → a

withReader

(α → γ) → (β | α) → (β | γ)

Monad_Either.fmap

(α → γ) → ST β α → ST β γ

Monad_ST.fmap

(β → α) → (γ→β) → γ → α

Applicative_->.fmap

(γ → β) → (α, γ) → (α, β)

Functor_(,).fmap

(α→γ) → (γ → α→β) → α → β

Monad_->.>>=

(α→γ) → (α→β) → α → β

Applicative_->.*>

(β→α) → (β→γ) → β → α

Applicative_->.<*

(β→α) → (β→γ) → β → γ

Monad_->.>>

(γ→β→α) → (γ→β) → γ → α

Applicative_->.<*>

(α | γ) → (γ → (α | β)) → (α | β)

Monad_Either.>>=

(α | γ) → (α | β) → (α | β)

Monad_Either.>>, Monad_Either.*>

(β | α→γ) → (β | α) → (β | γ)

Monad_Either.<*>

(γ | β) → (γ | α) → (γ | β)

Monad_Either.<*

ST α γ → ST α β → ST α γ

Monad_ST.<*

ST β α → ST β γ → ST β γ

Monad_ST.*>

ST γ (β→α) → ST γ β → ST γ α

Monad_ST.<*>

ST γ β → ST γ α → ST γ α

Monad_ST.>>

Applicative f ⇒ (a → b) → f a → f b

liftA

Applicative p ⇒ p a → p b → p a

Applicative.<*

Applicative p ⇒ p a → p b → p b

Applicative.*>

(Applicative α, Bind α) ⇒ (β→γ→α β) → β → [γ] → α β

shortFoldM

(Applicative β, Bind β) ⇒ (α→β γ) → [α] → β [γ]

mapM

(Applicative β, Bind β) ⇒ (γ→α→β γ) → γ → [α] → β γ

foldM

(Applicative β, Bind β) ⇒ [γ] → (γ→β α) → β [α]

forM

Apply f ⇒ f (a→b) → f a → f b

Apply.<*>

Apply p ⇒ p (a→b) → p a → p b

apply

Bind f ⇒ f a → (a → f b) → f b

Bind.>>=

Bind α ⇒ (γ→α β) → α γ → α β

=<<

Functor f ⇒ (a → b) → f a → f b

Functor.fmap

Monad m ⇒ (a → b) → m a → m b

liftM, Monad.fmap

Monad m ⇒ m (a→b) → m a → m b

Monad.<*>

Monad m ⇒ m a → m b → m b

Monad.>>

Monad α ⇒ α (γ→β) → α γ → α β

ap

Monad β ⇒ (α→γ→β α) → α → [γ] → β ()

foldM_

Monad β ⇒ (α→β γ) → [α] → β ()

mapM_

Monad γ ⇒ [α] → (α→γ β) → γ ()

forM_

Monad γ ⇒ γ β → γ α

forever

(β → δ) → (α, γ, β) → (α, γ, δ)

Functor_(,,).fmap

Applicative f ⇒ (a → b → c) → f a → f b → f c

liftA2

(Applicative γ, Bind γ) ⇒ (α→β→γ δ) → [α] → [β] → γ [δ]

zipWithM

(Applicative δ, Bind δ) ⇒ (α→β→γ) → δ α → δ β → δ γ

liftM2

(Applicative δ, Bind δ) ⇒ (γ→δ (β, α)) → [γ] → δ ([β], [α])

mapAndUnzipM

Bind α ⇒ (β→α δ) → (δ→α γ) → β → α γ

>=>

Bind β ⇒ (α→β γ) → (δ→β α) → δ → β γ

<=<

(Monad m, ListSource listSource) ⇒ listSource e → (e → m a) → m ()

for

Monad β ⇒ (δ→α→β γ) → [δ] → [α] → β ()

zipWithM_

Applicative f ⇒ (a → b → c → d) → f a → f b → f c → f d

liftA3

(Applicative α, Bind α) ⇒ (δ→ε→γ→β) → α δ → α ε → α γ → α β

liftM3

Applicative f ⇒ (a → b → c → d → e) → f a → f b → f c → f d → f e

liftA4

(Applicative ε, Bind ε) ⇒ (δ→β→γ→α→ζ) → ε δ → ε β → ε γ → ε α → ε ζ

liftM4

Applicative f ⇒ (a → b → c → d → e → g) → f a → f b → f c → f d → f e → f g

liftA5

(Applicative γ, Bind γ) ⇒ (α→ζ→η→δ→ε→β) → γ α → γ ζ → γ η → γ δ → γ ε → γ β

liftM5

Valid HTML 4.01 Strict