Pipes

This module is the recommended entry point to the pipes library.

Read Pipes.Tutorial if you want a tutorial explaining how to use this library.

The Proxy Monad Transformer

data Proxy a' a b' b m r

A Proxy is a monad transformer that receives and sends information on both an upstream and downstream interface.

The type variables signify:

• a' and a - The upstream interface, where (a')s go out and (a)s come in
• b' and b - The downstream interface, where (b)s go out and (b')s come in
• m - The base monad
• r - The return value

Instances

MonadError e m => MonadError e (Proxy a' a b' b m)

Methods

throwError :: e -> Proxy a' a b' b m a

catchError :: Proxy a' a b' b m a -> (e -> Proxy a' a b' b m a) -> Proxy a' a b' b m a

MonadReader r m => MonadReader r (Proxy a' a b' b m)

Methods

ask :: Proxy a' a b' b m r

local :: (r -> r) -> Proxy a' a b' b m a -> Proxy a' a b' b m a

reader :: (r -> a) -> Proxy a' a b' b m a

MonadState s m => MonadState s (Proxy a' a b' b m)

Methods

get :: Proxy a' a b' b m s

put :: s -> Proxy a' a b' b m ()

state :: (s -> (a, s)) -> Proxy a' a b' b m a

MonadWriter w m => MonadWriter w (Proxy a' a b' b m)

Methods

writer :: (a, w) -> Proxy a' a b' b m a

tell :: w -> Proxy a' a b' b m ()

listen :: Proxy a' a b' b m a -> Proxy a' a b' b m (a, w)

pass :: Proxy a' a b' b m (a, w -> w) -> Proxy a' a b' b m a

MFunctor (Proxy a' a b' b)

Methods

hoist :: Monad m => (forall c. m c -> n c) -> Proxy a' a b' b m b -> Proxy a' a b' b n b

MMonad (Proxy a' a b' b)

Methods

embed :: Monad n => (forall c. m c -> Proxy a' a b' b n c) -> Proxy a' a b' b m b -> Proxy a' a b' b n b

MonadTrans (Proxy a' a b' b)

Methods

lift :: Monad m => m a -> Proxy a' a b' b m a

Monad m => Monad (Proxy a' a b' b m)

Methods

(>>=) :: Proxy a' a b' b m a -> (a -> Proxy a' a b' b m b) -> Proxy a' a b' b m b

(>>) :: Proxy a' a b' b m a -> Proxy a' a b' b m b -> Proxy a' a b' b m b

return :: a -> Proxy a' a b' b m a

fail :: String -> Proxy a' a b' b m a

Monad m => Functor (Proxy a' a b' b m)

Methods

fmap :: (a -> b) -> Proxy a' a b' b m a -> Proxy a' a b' b m b

(<$) :: a -> Proxy a' a b' b m b -> Proxy a' a b' b m a

Monad m => Applicative (Proxy a' a b' b m)

Methods

pure :: a -> Proxy a' a b' b m a

(<*>) :: Proxy a' a b' b m (a -> b) -> Proxy a' a b' b m a -> Proxy a' a b' b m b

(*>) :: Proxy a' a b' b m a -> Proxy a' a b' b m b -> Proxy a' a b' b m b

(<*) :: Proxy a' a b' b m a -> Proxy a' a b' b m b -> Proxy a' a b' b m a

MonadIO m => MonadIO (Proxy a' a b' b m)

Methods

liftIO :: IO a -> Proxy a' a b' b m a

MonadPlus m => Alternative (Proxy a' a b' b m)

Methods

empty :: Proxy a' a b' b m a

(<|>) :: Proxy a' a b' b m a -> Proxy a' a b' b m a -> Proxy a' a b' b m a

some :: Proxy a' a b' b m a -> Proxy a' a b' b m [a]

many :: Proxy a' a b' b m a -> Proxy a' a b' b m [a]

MonadPlus m => MonadPlus (Proxy a' a b' b m)

Methods

mzero :: Proxy a' a b' b m a

mplus :: Proxy a' a b' b m a -> Proxy a' a b' b m a -> Proxy a' a b' b m a

(Monad m, Monoid r) => Monoid (Proxy a' a b' b m r)

Methods

mempty :: Proxy a' a b' b m r

mappend :: Proxy a' a b' b m r -> Proxy a' a b' b m r -> Proxy a' a b' b m r

mconcat :: [Proxy a' a b' b m r] -> Proxy a' a b' b m r

data X

The empty type, used to close output ends

When Data.Void is merged into base, this will change to:

type X = Void

type Effect = Proxy X () () X

An effect in the base monad

Effects neither await nor yield

type Effect' m r = forall x' x y' y. Proxy x' x y' y m r

Like Effect, but with a polymorphic type

runEffect :: Monad m => Effect m r -> m r

Run a self-contained Effect, converting it back to the base monad

Producers

Use yield to produce output and (~>) / for to substitute yields.

yield and (~>) obey the Category laws:

-- Substituting 'yield' with 'f' gives 'f'
yield ~> f = f

-- Substituting every 'yield' with another 'yield' does nothing
f ~> yield = f

-- 'yield' substitution is associative
(f ~> g) ~> h = f ~> (g ~> h)

These are equivalent to the following "for loop laws":

-- Looping over a single yield simplifies to function application
for (yield x) f = f x

-- Re-yielding every element of a stream returns the original stream
for s yield = s

-- Nested for loops can become a sequential for loops if the inner loop
-- body ignores the outer loop variable
for s (\a -> for (f a) g) = for (for s f) g = for s (f ~> g)

type Producer b = Proxy X () () b

Producers can only yield

type Producer' b m r = forall x' x. Proxy x' x () b m r

Like Producer, but with a polymorphic type

yield :: Monad m => a -> Producer' a m ()

Produce a value

yield :: Monad m => a -> Pipe x a m ()

for

Arguments

:: Monad m

=> Proxy x' x b' b m a'

-> (b -> Proxy x' x c' c m b')

-> Proxy x' x c' c m a'

(for p body) loops over p replacing each yield with body.

for :: Monad m => Producer b m r -> (b -> Effect       m ()) -> Effect       m r
for :: Monad m => Producer b m r -> (b -> Producer   c m ()) -> Producer   c m r
for :: Monad m => Pipe   x b m r -> (b -> Consumer x   m ()) -> Consumer x   m r
for :: Monad m => Pipe   x b m r -> (b -> Pipe     x c m ()) -> Pipe     x c m r

The following diagrams show the flow of information:

                              .--->   b
                             /        |
   +-----------+            /   +-----|-----+                 +---------------+
   |           |           /    |     v     |                 |               |
   |           |          /     |           |                 |               |
x ==>    p    ==> b   ---'   x ==>   body  ==> c     =     x ==> for p body  ==> c
   |           |                |           |                 |               |
   |     |     |                |     |     |                 |       |       |
   +-----|-----+                +-----|-----+                 +-------|-------+
         v                            v                               v
         r                            ()                              r

For a more complete diagram including bidirectional flow, see Pipes.Core.

(~>) infixr 4

Arguments

:: Monad m

=> (a -> Proxy x' x b' b m a')

-> (b -> Proxy x' x c' c m b')

-> a -> Proxy x' x c' c m a'

Compose loop bodies

(~>) :: Monad m => (a -> Producer b m r) -> (b -> Effect       m ()) -> (a -> Effect       m r)
(~>) :: Monad m => (a -> Producer b m r) -> (b -> Producer   c m ()) -> (a -> Producer   c m r)
(~>) :: Monad m => (a -> Pipe   x b m r) -> (b -> Consumer x   m ()) -> (a -> Consumer x   m r)
(~>) :: Monad m => (a -> Pipe   x b m r) -> (b -> Pipe     x c m ()) -> (a -> Pipe     x c m r)

The following diagrams show the flow of information:

         a                    .--->   b                              a
         |                   /        |                              |
   +-----|-----+            /   +-----|-----+                 +------|------+
   |     v     |           /    |     v     |                 |      v      |
   |           |          /     |           |                 |             |
x ==>    f    ==> b   ---'   x ==>    g    ==> c     =     x ==>   f ~> g  ==> c
   |           |                |           |                 |             |
   |     |     |                |     |     |                 |      |      |
   +-----|-----+                +-----|-----+                 +------|------+
         v                            v                              v
         r                            ()                             r

For a more complete diagram including bidirectional flow, see Pipes.Core.

(<~) infixl 4

Arguments

:: Monad m

=> (b -> Proxy x' x c' c m b')

-> (a -> Proxy x' x b' b m a')

-> a -> Proxy x' x c' c m a'

(~>) with the arguments flipped

Consumers

Use await to request input and (>~) to substitute awaits.

await and (>~) obey the Category laws:

-- Substituting every 'await' with another 'await' does nothing
await >~ f = f

-- Substituting 'await' with 'f' gives 'f'
f >~ await = f

-- 'await' substitution is associative
(f >~ g) >~ h = f >~ (g >~ h)

type Consumer a = Proxy () a () X

Consumers can only await

type Consumer' a m r = forall y' y. Proxy () a y' y m r

Like Consumer, but with a polymorphic type

await :: Monad m => Consumer' a m a

Consume a value

await :: Monad m => Pipe a y m a

(>~) infixr 5

Arguments

:: Monad m

=> Proxy a' a y' y m b

-> Proxy () b y' y m c

-> Proxy a' a y' y m c

(draw >~ p) loops over p replacing each await with draw

(>~) :: Monad m => Effect       m b -> Consumer b   m c -> Effect       m c
(>~) :: Monad m => Consumer a   m b -> Consumer b   m c -> Consumer a   m c
(>~) :: Monad m => Producer   y m b -> Pipe     b y m c -> Producer   y m c
(>~) :: Monad m => Pipe     a y m b -> Pipe     b y m c -> Pipe     a y m c

The following diagrams show the flow of information:

   +-----------+                 +-----------+                 +-------------+
   |           |                 |           |                 |             |
   |           |                 |           |                 |             |
a ==>    f    ==> y   .--->   b ==>    g    ==> y     =     a ==>   f >~ g  ==> y
   |           |     /           |           |                 |             |
   |     |     |    /            |     |     |                 |      |      |
   +-----|-----+   /             +-----|-----+                 +------|------+
         v        /                    v                              v
         b   ----'                     c                              c

For a more complete diagram including bidirectional flow, see Pipes.Core.

(~<) infixl 5

Arguments

:: Monad m

=> Proxy () b y' y m c

-> Proxy a' a y' y m b

-> Proxy a' a y' y m c

(>~) with the arguments flipped

Pipes

Use await and yield to build Pipes and (>->) to connect Pipes.

cat and (>->) obey the Category laws:

-- Useless use of cat
cat >-> f = f

-- Redirecting output to cat does nothing
f >-> cat = f

-- The pipe operator is associative
(f >-> g) >-> h = f >-> (g >-> h)

type Pipe a b = Proxy () a () b

Pipes can both await and yield

cat :: Monad m => Pipe a a m r

The identity Pipe, analogous to the Unix cat program

(>->) infixl 7

Arguments

:: Monad m

=> Proxy a' a () b m r

-> Proxy () b c' c m r

-> Proxy a' a c' c m r

Pipe composition, analogous to the Unix pipe operator

(>->) :: Monad m => Producer b m r -> Consumer b   m r -> Effect       m r
(>->) :: Monad m => Producer b m r -> Pipe     b c m r -> Producer   c m r
(>->) :: Monad m => Pipe   a b m r -> Consumer b   m r -> Consumer a   m r
(>->) :: Monad m => Pipe   a b m r -> Pipe     b c m r -> Pipe     a c m r

The following diagrams show the flow of information:

   +-----------+     +-----------+                 +-------------+
   |           |     |           |                 |             |
   |           |     |           |                 |             |
a ==>    f    ==> b ==>    g    ==> c     =     a ==>  f >-> g  ==> c
   |           |     |           |                 |             |
   |     |     |     |     |     |                 |      |      |
   +-----|-----+     +-----|-----+                 +------|------+
         v                 v                              v
         r                 r                              r

For a more complete diagram including bidirectional flow, see Pipes.Core.

(<-<) infixr 7

Arguments

:: Monad m

=> Proxy () b c' c m r

-> Proxy a' a () b m r

-> Proxy a' a c' c m r

(>->) with the arguments flipped

ListT

newtype ListT m a

The list monad transformer, which extends a monad with non-determinism

return corresponds to yield, yielding a single value

(>>=) corresponds to for, calling the second computation once for each time the first computation yields.

Constructors

Select

Fields

• enumerate :: Producer a m ()

Instances

MFunctor ListT

Methods

hoist :: Monad m => (forall a. m a -> n a) -> ListT m b -> ListT n b

MonadTrans ListT

Methods

lift :: Monad m => m a -> ListT m a

Enumerable ListT

Methods

toListT :: Monad m => ListT m a -> ListT m a

MonadError e m => MonadError e (ListT m)

Methods

throwError :: e -> ListT m a

catchError :: ListT m a -> (e -> ListT m a) -> ListT m a

MonadReader i m => MonadReader i (ListT m)

Methods

ask :: ListT m i

local :: (i -> i) -> ListT m a -> ListT m a

reader :: (i -> a) -> ListT m a

MonadState s m => MonadState s (ListT m)

Methods

get :: ListT m s

put :: s -> ListT m ()

state :: (s -> (a, s)) -> ListT m a

MonadWriter w m => MonadWriter w (ListT m)

Methods

writer :: (a, w) -> ListT m a

tell :: w -> ListT m ()

listen :: ListT m a -> ListT m (a, w)

pass :: ListT m (a, w -> w) -> ListT m a

Monad m => Monad (ListT m)

Methods

(>>=) :: ListT m a -> (a -> ListT m b) -> ListT m b

(>>) :: ListT m a -> ListT m b -> ListT m b

return :: a -> ListT m a

fail :: String -> ListT m a

Monad m => Functor (ListT m)

Methods

fmap :: (a -> b) -> ListT m a -> ListT m b

(<$) :: a -> ListT m b -> ListT m a

Monad m => Applicative (ListT m)

Methods

pure :: a -> ListT m a

(<*>) :: ListT m (a -> b) -> ListT m a -> ListT m b

(*>) :: ListT m a -> ListT m b -> ListT m b

(<*) :: ListT m a -> ListT m b -> ListT m a

MonadIO m => MonadIO (ListT m)

Methods

liftIO :: IO a -> ListT m a

Monad m => Alternative (ListT m)

Methods

empty :: ListT m a

(<|>) :: ListT m a -> ListT m a -> ListT m a

some :: ListT m a -> ListT m [a]

many :: ListT m a -> ListT m [a]

Monad m => MonadPlus (ListT m)

Methods

mzero :: ListT m a

mplus :: ListT m a -> ListT m a -> ListT m a

Monad m => Monoid (ListT m a)

Methods

mempty :: ListT m a

mappend :: ListT m a -> ListT m a -> ListT m a

mconcat :: [ListT m a] -> ListT m a

runListT :: Monad m => ListT m a -> m ()

Run a self-contained ListT computation

class Enumerable t where

Enumerable generalizes Foldable, converting effectful containers to ListTs.

Instances of Enumerable must satisfy these two laws:

toListT (return r) = return r

toListT $ do x <- m  =  do x <- toListT m
             f x           toListT (f x)

In other words, toListT is monad morphism.

Minimal complete definition

toListT

Methods

toListT :: Monad m => t m a -> ListT m a

Instances

Enumerable MaybeT

Methods

toListT :: Monad m => MaybeT m a -> ListT m a

Enumerable ListT

Methods

toListT :: Monad m => ListT m a -> ListT m a

Enumerable (ErrorT e)

Methods

toListT :: Monad m => ErrorT e m a -> ListT m a

Enumerable (IdentityT *)

Methods

toListT :: Monad m => IdentityT * m a -> ListT m a

Utilities

next :: Monad m => Producer a m r -> m (Either r (a, Producer a m r))

Consume the first value from a Producer

next either fails with a Left if the Producer terminates or succeeds with a Right providing the next value and the remainder of the Producer.

each :: (Monad m, Foldable f) => f a -> Producer' a m ()

Convert a Foldable to a Producer

every :: (Monad m, Enumerable t) => t m a -> Producer' a m ()

Convert an Enumerable to a Producer

discard :: Monad m => a -> m ()

Discards a value

Re-exports

Control.Monad re-exports void

Control.Monad.IO.Class re-exports MonadIO.

Control.Monad.Trans.Class re-exports MonadTrans.

Control.Monad.Morph re-exports MFunctor.

Data.Foldable re-exports Foldable (the class name only).

module Control.Monad

module Control.Monad.IO.Class

module Control.Monad.Trans.Class

module Control.Monad.Morph

module Data.Foldable