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.

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

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.

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'

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

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

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

(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