pipes-4.0.0: Compositional pipelines

Safe HaskellTrustworthy

Pipes.Core

Contents

Description

The core functionality for the Proxy monad transformer

Read Pipes.Tutorial if you want a beginners tutorial explaining how to use this library. The documentation in this module targets more advanced users who want to understand the theory behind this library.

This module is not exported by default, and I recommend you use the unidirectional operations exported by the Pipes module if you can. You should only use this module if you require advanced features like:

  • bidirectional communication, or:
  • push-based Pipes.

Synopsis

Proxy Monad Transformer

Diagrammatically, you can think of a Proxy as having the following shape: 

 Upstream | Downstream
     +---------+
     |         |
 a' <==       <== b'
     |         |
 a  ==>       ==> b
     |    |    |
     +----|----+
          v
          r

You can connect proxies together in five different ways:

  • (>+>): connect pull-based streams
  • (>~>): connect push-based streams
  • (\>\): chain folds
  • (/>/): chain unfolds
  • (>=>): sequence proxies

data Proxy a' a b' b m r Source

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) 
MonadReader r m => MonadReader r (Proxy a' a b' b m) 
MonadState s m => MonadState s (Proxy a' a b' b m) 
MonadWriter w m => MonadWriter w (Proxy a' a b' b m) 
MFunctor (Proxy a' a b' b) 
MonadTrans (Proxy a' a b' b) 
Monad m => Monad (Proxy a' a b' b m) 
Monad m => Functor (Proxy a' a b' b m) 
MonadPlus m => MonadPlus (Proxy a' a b' b m) 
Monad m => Applicative (Proxy a' a b' b m) 
MonadPlus m => Alternative (Proxy a' a b' b m) 
MonadIO m => MonadIO (Proxy a' a b' b m) 

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

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

Categories

A Category is a set of components that you can connect with a composition operator, (.), that has an identity, id. The (.) and id must satisfy the following three Category laws: 

-- Left identity
id . f = f

-- Right identity
f . id = f

-- Associativity
(f . g) . h = f . (g . h)

The Proxy type sits at the intersection of five separate categories, four of which are named after their identity: 

                     Identity   | Composition |  Point-ful
                  +-------------+-------------+-------------+
 respond category |   respond   |     />/     |     //>     |
 request category |   request   |     \>\     |     >\\     |
    push category |   push      |     >~>     |     >>~     |
    pull category |   pull      |     >+>     |     +>>     |
 Kleisli category |   return    |     >=>     |     >>=     |
                  +-------------+-------------+-------------+

Each composition operator has a "point-ful" version, analogous to how (>>=) is the point-ful version of (>=>). For example, (//>) is the point-ful version of (/>/). The convention is that the odd character out faces the argument that is a function.

Respond

The respond category closely corresponds to the generator design pattern.

The respond category obeys the category laws, where respond is the identity and (/>/) is composition: 

-- Left identity
respond />/ f = f

-- Right identity
f />/ respond = f

-- Associativity
(f />/ g) />/ h = f />/ (g />/ h)

The following diagrams show the flow of information: 

respond :: (Monad m)
       =>  a -> Proxy x' x a' a m a'

          a
          |
     +----|----+
     |    |    |
 x' <==   \ /==== a'
     |     X   |
 x  ==>   / \===> a
     |    |    |
     +----|----+
          v 
          a'

(/>/) :: (Monad m)
      => (a -> Proxy x' x b' b m a')
      -> (b -> Proxy x' x c' c m b')
      -> (a -> Proxy x' x b' b m a')

          a                   /===> b                      a
          |                  /      |                      |
     +----|----+            /  +----|----+            +----|----+
     |    v    |           /   |    v    |            |    v    |
 x' <==       <== b' <==\ / x'<==       <== c'    x' <==       <== c'
     |    f    |         X     |    g    |     =      | f />/ g |
 x  ==>       ==> b  ===/ \ x ==>       ==> c     x  ==>       ==> c'
     |    |    |           \   |    |    |            |    |    |
     +----|----+            \  +----|----+            +----|----+
          v                  \      v                      v
          a'                  \==== b'                     a'

respond :: Monad m => a -> Proxy x' x a' a m a'Source

Send a value of type a downstream and block waiting for a reply of type a'

respond is the identity of the respond category.

(/>/)Source

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 two unfolds, creating a new unfold 

(f />/ g) x = f x //> g

(/>/) is the composition operator of the respond category.

(//>)Source

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' 

(p //> f) replaces each respond in p with f.

Point-ful version of (/>/)

Request

The request category closely corresponds to the iteratee design pattern.

The request category obeys the category laws, where request is the identity and (\>\) is composition: 

-- Left identity
request \>\ f = f

-- Right identity
f \>\ request = f

-- Associativity
(f \>\ g) \>\ h = f \>\ (g \>\ h)

The following diagrams show the flow of information: 

request :: (Monad m)
        =>  a' -> Proxy a' a y' y m a

          a'
          |
     +----|----+
     |    |    |
 a' <=====/   <== y'
     |         |
 a  ======\   ==> y
     |    |    |
     +----|----+
          v
          a

(\>\) :: (Monad m)
      => (b' -> Proxy a' a y' y m b)
      -> (c' -> Proxy b' b y' y m c)
      -> (c' -> Proxy a' a y' y m c)

          b'<=====\                c'                     c'
          |        \               |                      |
     +----|----+    \         +----|----+            +----|----+
     |    v    |     \        |    v    |            |    v    |
 a' <==       <== y'  \== b' <==       <== y'    a' <==       <== y'
     |    f    |              |    g    |     =      | f \>\ g |
 a  ==>       ==> y   /=> b  ==>       ==> y     a  ==>       ==> y
     |    |    |     /        |    |    |            |    |    |
     +----|----+    /         +----|----+            +----|----+
          v        /               v                      v
          b ======/                c                      c

request :: Monad m => a' -> Proxy a' a y' y m aSource

Send a value of type a' upstream and block waiting for a reply of type a

request is the identity of the request category.

(\>\)Source

Arguments

:: Monad m 
=> (b' -> Proxy a' a y' y m b) 
-> (c' -> Proxy b' b y' y m c) 
-> c' -> Proxy a' a y' y m c 

Compose two folds, creating a new fold 

(f \>\ g) x = f >\\ g x

(\>\) is the composition operator of the request category.

(>\\)Source

Arguments

:: Monad m 
=> (b' -> Proxy a' a y' y m b) 
-> Proxy b' b y' y m c 
-> Proxy a' a y' y m c 

(f >\\ p) replaces each request in p with f.

Point-ful version of (\>\)

Push

The push category closely corresponds to push-based Unix pipes.

The push category obeys the category laws, where push is the identity and (>~>) is composition: 

-- Left identity
push >~> f = f

-- Right identity
f >~> push = f

-- Associativity
(f >~> g) >~> h = f >~> (g >~> h)

The following diagram shows the flow of information: 

push  :: (Monad m)
      =>  a -> Proxy a' a a' a m r

          a
          |
     +----|----+
     |    v    |
 a' <============ a'
     |         |
 a  ============> a
     |    |    |
     +----|----+
          v
          r

(>~>) :: (Monad m)
      => (a -> Proxy a' a b' b m r)
      -> (b -> Proxy b' b c' c m r)
      -> (a -> Proxy a' a c' c m r)

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

push :: Monad m => a -> Proxy a' a a' a m rSource

Forward responses followed by requests 

push = respond >=> request >=> push

push is the identity of the push category.

(>~>)Source

Arguments

:: Monad m 
=> (_a -> Proxy a' a b' b m r) 
-> (b -> Proxy b' b c' c m r) 
-> _a -> Proxy a' a c' c m r 

Compose two proxies blocked while requesting data, creating a new proxy blocked while requesting data 

(f >~> g) x = f x >>~ g

(>~>) is the composition operator of the push category.

(>>~)Source

Arguments

:: Monad m 
=> Proxy a' a b' b m r 
-> (b -> Proxy b' b c' c m r) 
-> Proxy a' a c' c m r 

(p >>~ f) pairs each respond in p with an request in f.

Point-ful version of (>~>)

Pull

The pull category closely corresponds to pull-based Unix pipes.

The pull category obeys the category laws, where pull is the identity and (>+>) is composition: 

-- Left identity
pull >+> f = f

-- Right identity
f >+> pull = f

-- Associativity
(f >+> g) >+> h = f >+> (g >+> h)

The following diagrams show the flow of information: 

pull  :: (Monad m)
      =>  a' -> Proxy a' a a' a m r

          a'
          |
     +----|----+
     |    v    |
 a' <============ a'
     |         |
 a  ============> a
     |    |    |
     +----|----+
          v
          r

(>+>) :: (Monad m)
      -> (b' -> Proxy a' a b' b m r)
      -> (c' -> Proxy b' b c' c m r)
      -> (c' -> Proxy a' a c' c m r)

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

pull :: Monad m => a' -> Proxy a' a a' a m rSource

Forward requests followed by responses: 

pull = request >=> respond >=> pull

pull is the identity of the pull category.

(>+>)Source

Arguments

:: Monad m 
=> (b' -> Proxy a' a b' b m r) 
-> (_c' -> Proxy b' b c' c m r) 
-> _c' -> Proxy a' a c' c m r 

Compose two proxies blocked in the middle of responding, creating a new proxy blocked in the middle of responding 

(f >+> g) x = f +>> g x

(>+>) is the composition operator of the pull category.

(+>>)Source

Arguments

:: Monad m 
=> (b' -> Proxy a' a b' b m r) 
-> Proxy b' b c' c m r 
-> Proxy a' a c' c m r 

(f +>> p) pairs each request in p with a respond in f.

Point-ful version of (>+>)

Reflect

(reflect .) transforms each streaming category into its dual:

  • The request category is the dual of the respond category 
reflect . respond = request

reflect . (f />/ g) = reflect . f /</ reflect . g

reflect . request = respond

reflect . (f \>\ g) = reflect . f \<\ reflect . g
  • The pull category is the dual of the push category 
reflect . push = pull

reflect . (f >~> g) = reflect . f <+< reflect . g

reflect . pull = push

reflect . (f >+> g) = reflect . f <~< reflect . g

reflect :: Monad m => Proxy a' a b' b m r -> Proxy b b' a a' m rSource

Switch the upstream and downstream ends

Concrete Type Synonyms

type Effect = Proxy Void () () VoidSource

An effect in the base monad

Effects neither await nor yield

type Producer b = Proxy Void () () bSource

Producers can only yield

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

Pipes can both await and yield

type Consumer a = Proxy () a () VoidSource

Consumers can only await

type Client a' a = Proxy a' a () VoidSource

Client a' a sends requests of type a' and receives responses of type a.

Clients only request and never respond.

type Server b' b = Proxy Void () b' bSource

Server b' b receives requests of type b' and sends responses of type b.

Servers only respond and never request.

Polymorphic Type Synonyms

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

Like Effect, but with a polymorphic type

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

Like Producer, but with a polymorphic type

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

Like Consumer, but with a polymorphic type

type Client' a' a m r = forall y' y. Proxy a' a y' y m rSource

Like Client, but with a polymorphic type

type Server' b' b m r = forall x' x. Proxy x' x b' b m rSource

Like Server, but with a polymorphic type

Flipped operators

(\<\)Source

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' 

Equivalent to (/>/) with the arguments flipped

(/</)Source

Arguments

:: Monad m 
=> (c' -> Proxy b' b x' x m c) 
-> (b' -> Proxy a' a x' x m b) 
-> c' -> Proxy a' a x' x m c 

Equivalent to (\>\) with the arguments flipped

(<~<)Source

Arguments

:: Monad m 
=> (b -> Proxy b' b c' c m r) 
-> (a -> Proxy a' a b' b m r) 
-> a -> Proxy a' a c' c m r 

Equivalent to (>~>) with the arguments flipped

(~<<)Source

Arguments

:: Monad m 
=> (b -> Proxy b' b c' c m r) 
-> Proxy a' a b' b m r 
-> Proxy a' a c' c m r 

Equivalent to (>>~) with the arguments flipped

(<+<)Source

Arguments

:: Monad m 
=> (c' -> Proxy b' b c' c m r) 
-> (b' -> Proxy a' a b' b m r) 
-> c' -> Proxy a' a c' c m r 

Equivalent to (>+>) with the arguments flipped

(<\\)Source

Arguments

:: Monad m 
=> (b -> Proxy x' x c' c m b') 
-> Proxy x' x b' b m a' 
-> Proxy x' x c' c m a' 

Equivalent to (//>) with the arguments flipped

(//<)Source

Arguments

:: Monad m 
=> Proxy b' b y' y m c 
-> (b' -> Proxy a' a y' y m b) 
-> Proxy a' a y' y m c 

Equivalent to (>\\) with the arguments flipped

(<<+)Source

Arguments

:: Monad m 
=> Proxy b' b c' c m r 
-> (b' -> Proxy a' a b' b m r) 
-> Proxy a' a c' c m r 

Equivalent to (+>>) with the arguments flipped