Modulepipes-4.3.16Haskell2010

Pipes.Core

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.

13 types
23 values

Packagepipes-4.3.16
Exports36
LanguageHaskell2010
LicenceBSD-3-Clause
SourceCore.hs

Proxy Monad Transformer

2 declarations

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:

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

datadata Proxy a' a b' b (m :: Type -> Type) 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

Instances16MFunctor, MonadError, MonadReader, MonadState, MonadWriter, MonadTrans, …

MFunctor (Proxy a' a b' b)Defined in pipes-4.3.16 · Pipes.Internal
MonadError e m => MonadError e (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
MonadReader r m => MonadReader r (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
MonadState s m => MonadState s (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
MonadWriter w m => MonadWriter w (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
MonadTrans (Proxy a' a b' b)Defined in pipes-4.3.16 · Pipes.Internal
MMonad (Proxy a' a b' b)Defined in pipes-4.3.16 · Pipes.Internal
Functor m => Monad (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
Functor m => Functor (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
MonadFail m => MonadFail (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
Functor m => Applicative (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
MonadIO m => MonadIO (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
MonadCatch m => MonadCatch (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
MonadThrow m => MonadThrow (Proxy a' a b' b m)Defined in pipes-4.3.16 · Pipes.Internal
(Functor m, Semigroup r) => Semigroup (Proxy a' a b' b m r)Defined in pipes-4.3.16 · Pipes.Internal
(Functor m, Monoid r, Semigroup r) => Monoid (Proxy a' a b' b m r)Defined in pipes-4.3.16 · Pipes.Internal

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

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

Categories

0 declarations

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 :: Functor m
       =>  a -> Proxy x' x a' a m a'

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

(/>/) :: Functor 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')

          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'

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

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

valuerespond :: Functor m => a -> Proxy x' x a' a m a'

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

respond is the identity of the respond category.

value(/>/)

:: Functor 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.

value(//>)

:: Functor 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 :: Functor m
        =>  a' -> Proxy a' a y' y m a

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

(\>\) :: Functor 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

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

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

valuerequest :: Functor m => a' -> Proxy a' a y' y m a

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

request is the identity of the request category.

value(\>\)

:: Functor 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.

value(>\\)

:: Functor 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  :: Functor m
      =>  a -> Proxy a' a a' a m r

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

(>~>) :: Functor 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

valuepush :: Functor m => a -> Proxy a' a a' a m r

Forward responses followed by requests

push = respond >=> request >=> push

push is the identity of the push category.

value(>~>)

:: Functor 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.

value(>>~)

:: Functor 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 a 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  :: Functor m
      =>  a' -> Proxy a' a a' a m r

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

(>+>) :: Functor 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

valuepull :: Functor m => a' -> Proxy a' a a' a m r

Forward requests followed by responses:

pull = request >=> respond >=> pull

pull is the identity of the pull category.

value(>+>)

:: Functor 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.

value(+>>)

:: Functor 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

valuereflect :: Functor m => Proxy a' a b' b m r -> Proxy b b' a a' m r

Switch the upstream and downstream ends

Concrete Type Synonyms

7 declarations

typetype X = Void

The empty type, used to close output ends

typetype Effect = Proxy X () () X

An effect in the base monad

Effects neither await nor yield

typetype Producer b = Proxy X () () b

Producers can only yield

typetype Pipe a b = Proxy () a () b

Pipes can both await and yield

typetype Consumer a = Proxy () a () X

Consumers can only await

typetype Client a' a = Proxy a' a () X

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

Clients only request and never respond.

typetype Server b' b = Proxy X () b' b

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

Servers only respond and never request.

Polymorphic Type Synonyms

5 declarations

typetype Effect' (m :: Type -> Type) r = forall x' x y' y. Proxy x' x y' y m r

Like Effect, but with a polymorphic type

typetype Producer' b (m :: Type -> Type) r = forall x' x. Proxy x' x () b m r

Like Producer, but with a polymorphic type

typetype Consumer' a (m :: Type -> Type) r = forall y' y. Proxy () a y' y m r

Like Consumer, but with a polymorphic type

typetype Client' a' a (m :: Type -> Type) r = forall y' y. Proxy a' a y' y m r

Like Client, but with a polymorphic type

typetype Server' b' b (m :: Type -> Type) r = forall x' x. Proxy x' x b' b m r

Like Server, but with a polymorphic type

Flipped operators

8 declarations

value(\<\)

:: Functor 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

value(/</)

:: Functor 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

value(<~<)

:: Functor 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

value(~<<)

:: Functor 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

value(<+<)

:: Functor 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

value(<\\)

:: Functor 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

value(//<)

:: Functor 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

value(<<+)

:: Functor 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

Re-exports

1 declaration

valueclosed :: X -> a

Use closed to "handle" impossible outputs