This module defines the theoretical framework underpinning this library

The RespondT monad transformer is equivalent to ListT over the downstream output. The RespondT Kleisli category corresponds to the "respond" category.

The RequestT monad transformer is equivalent to ListT over the upstream output. The RequestT Kleisli category corresponds to the "request" category.

Unlike ListT from transformers, these monad transformers are correct by construction and always satisfy the monad and monad transformer laws.

First, all proxies sit at the intersection of five categories:

• The Kleisli category (all proxies are monads)

 return >=> f = f

 f >=> return = f

 (f >=> g) >=> h = f >=> (g >=> h)

• The "request" category

 request \>\ f = f

 f \>\ request = f

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

• The "respond" category

 respond />/ f = f

 f />/ respond = f

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

• The "pull" category

 pull >-> f = f

 f >-> pull = f

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

• The "push" category

 push >~> f = f

 f >~> push = f

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

Second, (turn .) transforms each streaming category into its dual:

• The "request" category

 turn . request = respond

 turn . (f \>\ g) = turn . f \<\ turn . g

• The "respond" category

 turn . respond = request

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

• The "pull" category

 turn . pull = push

 turn . (f >-> g) = turn . f <~< turn . g

• The "push" category

 turn . push = pull

 turn . (f >~> g) = turn . f <-< turn . g

Third, all proxies are monad transformers and must satisfy the monad transformer laws, using:

• lift = lift_P

Fourth, all proxies are functors in the category of monads and must satisfy the functor laws, using:

• hoist = hoist_P

Fifth, (\>\) and (/>/) both define functors between Kleisli categories

 a \>\ (b >=> c) = (a \>\ b) >=> (a \>\ c)

 a \>\ return = return

 (b >=> c) />/ a = (b />/ a) >=> (c />/ a)

 return />/ a = return

Sixth, all proxies must satisfy these additional Proxy laws:

 p \>\ lift . f = lift . f

 p \>\ respond  = respond

 lift . f />/ p = lift . f

 request />/  p = request

 pull = request >=> respond >=> pull

 push = respond >=> request >=> push

 p1 >-> lift . f = lift . f

 p1 >-> (lift . f >=> respond >=> p2) = lift . f >=> respond >=> (p1 >-> p2)

 (lift . g >=> respond >=> p1) >-> (lift . f >=> request >=> lift . h >=> p2)
     = lift . (f >=> g >=> h) >=> (p1 >-> p2)

 (lift . g >=> request >=> p1) >-> (lift . f >=> request >=> p2)
     = lift . (f >=> g) >=> request >=> (p1 >~> p2)

 lift . f >~> p2 = lift . f

 (lift . f >=> request >=> p1) >~> p2 = lift . f >=> request >=> (p1 >~> p2)

 (lift . f >=> respond >=> lift . h >=> p1) >~> (lift . g >=> request >=> p2)
     = lift . (f >=> g >=> h) >=> (p1 >~> p2)

 (lift . f >=> respond >=> p1) >~> (lift . g >=> respond >=> p2)
     = lift . (f >=> g) >=> (p1 >-> p2)

The ProxyInternal and MonadPlusP type classes duplicate methods from more familiar type classes. These duplicate methods serve two purposes.

First, this library requires type class instances that would otherwise be impossible to define without providing higher-kinded constraints. Rather than use the following illegal polymorphic constraint:

 instance (forall a' a b' b . MonadTrans (p a' a b' b)) => ...

... the instance can instead use the following Haskell98 constraint:

 instance (Proxy p) => ...

Second, these type classes don't require the FlexibleContexts extension to use and substantially clean up constraints in type signatures. They convert messy constraints like this:

 p :: (MonadP (p a' a b' b m), MonadTrans (p a' a b' b)) => ...

.. into cleaner and more general constraints like this:

 p :: (Proxy p) => ...

ProxyInternal and MonadPlusP exist solely for internal type class plumbing and I discourage you from using the methods in these classes unless you enjoy making your code less readable. Instead, you can use all the original type classes as long as you embed your proxy code within at least one proxy transformer (or IdentityP if don't use any transformers). The type-class machinery will then automatically convert the messier and less polymorphic constraints to the simpler and more general constraints.

For example, consider the following almost-correct definition for mapMD (from Control.Proxy.Prelude.Base):

 import Control.Monad.Trans.Class
 import Control.Proxy

 mapMD f = foreverK $ \a' -> do
     a <- request a'
     b <- lift (f a)
     respond b

The compiler infers the following messy constraint:

 mapMD
  :: (Monad m, Monad (p x a x b m), MonadTrans (p x a x b), Proxy p)
  => (a -> m b) -> x -> p x a x b m r

Instead, you can embed the code in the IdentityP proxy transformer by wrapping it in runIdentityK:

 --        |difference|  
 mapMD f = runIdentityK $ foreverK $ \a' -> do
     a <- request a'
     b <- lift (f a)
     respond b

... and now the compiler collapses all the constraints into the Proxy constraint:

 mapMD :: (Monad m, Proxy p) => (a -> m b) -> x -> p x a x b m r

You do not incur any performance penalty for writing polymorphic code or embedding it in IdentityP. This library employs several rewrite RULES which transform your polymorphic code into the equivalent type-specialized hand-tuned code. These rewrite rules fire very robustly and they do not require any assistance on your part from compiler pragmas like INLINE, NOINLINE or SPECIALIZE.

If you nest proxies within proxies:

 example () = do
     request ()
     lift $ request ()
     lift $ lift $ request ()

... then you can still keep the nice constraints using:

 example () = runIdentityP . hoist (runIdentityP . hoist runIdentityP) $ do
     request ()
     lift $ request ()
     lift $ lift $ request ()

You don't need to use runIdentityP / runIdentityK if you use any other proxy transformers (In fact you can't, it's a type error). The following code example illustrates this, where the throw command (from the EitherP proxy transformer) suffices to guide the compiler to the cleaner type signature:

 import Control.Monad
 import Control.Proxy
 import qualified Control.Proxy.Trans.Either as E

 example :: (Monad m, Proxy p) => () -> Producer (EitherP String p) Char m ()
 example () = do
     c <- request ()
     when (c == ' ') $ E.throw "Error: received space"
     respond c

These will be removed in version 4.0.0