-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Compositional pipelines
--   
--   <a>pipes</a> is a clean and powerful stream processing library that
--   lets you build and connect reusable streaming components
--   
--   Advantages over traditional streaming libraries:
--   
--   <ul>
--   <li><i>Concise API</i>: Use simple commands like <a>for</a>,
--   (<a>&gt;-&gt;</a>), <a>await</a>, and <a>yield</a></li>
--   <li><i>Blazing fast</i>: Implementation tuned for speed, including
--   shortcut fusion</li>
--   <li><i>Lightweight Dependency</i>: <tt>pipes</tt> is small and
--   compiles very rapidly, including dependencies</li>
--   <li><i>Elegant semantics</i>: Use practical category theory</li>
--   <li><i>ListT</i>: Correct implementation of <a>ListT</a> that
--   interconverts with pipes</li>
--   <li><i>Bidirectionality</i>: Implement duplex channels</li>
--   <li><i>Extensive Documentation</i>: Second to none!</li>
--   </ul>
--   
--   Import <a>Pipes</a> to use the library.
--   
--   Read <a>Pipes.Tutorial</a> for an extensive tutorial.
@package pipes
@version 4.3.4


-- | This is an internal module, meaning that it is unsafe to import unless
--   you understand the risks.
--   
--   This module provides a fast implementation by weakening the monad
--   transformer laws. These laws do not hold if you can pattern match on
--   the constructors, as the following counter-example illustrates:
--   
--   <pre>
--   <a>lift</a> <a>.</a> <a>return</a> = <a>M</a> <a>.</a> <a>return</a> <a>.</a> <a>Pure</a>
--   
--   <a>return</a> = <a>Pure</a>
--   
--   <a>lift</a> <a>.</a> <a>return</a> /= <a>return</a>
--   </pre>
--   
--   You do not need to worry about this if you do not import this module,
--   since the other modules in this library do not export the constructors
--   or export any functions which can violate the monad transformer laws.
module Pipes.Internal

-- | A <a>Proxy</a> is a monad transformer that receives and sends
--   information on both an upstream and downstream interface.
--   
--   The type variables signify:
--   
--   <ul>
--   <li><tt>a'</tt> and <tt>a</tt> - The upstream interface, where
--   <tt>(a')</tt>s go out and <tt>(a)</tt>s come in</li>
--   <li><tt>b'</tt> and <tt>b</tt> - The downstream interface, where
--   <tt>(b)</tt>s go out and <tt>(b')</tt>s come in</li>
--   <li><tt>m </tt> - The base monad</li>
--   <li><tt>r </tt> - The return value</li>
--   </ul>
data Proxy a' a b' b m r
Request :: a' -> (a -> Proxy a' a b' b m r) -> Proxy a' a b' b m r
Respond :: b -> (b' -> Proxy a' a b' b m r) -> Proxy a' a b' b m r
M :: (m (Proxy a' a b' b m r)) -> Proxy a' a b' b m r
Pure :: r -> Proxy a' a b' b m r

-- | <a>unsafeHoist</a> is like <a>hoist</a>, but faster.
--   
--   This is labeled as unsafe because you will break the monad transformer
--   laws if you do not pass a monad morphism as the first argument. This
--   function is safe if you pass a monad morphism as the first argument.
unsafeHoist :: Monad m => (forall x. m x -> n x) -> Proxy a' a b' b m r -> Proxy a' a b' b n r

-- | The monad transformer laws are correct when viewed through the
--   <a>observe</a> function:
--   
--   <pre>
--   <a>observe</a> (<a>lift</a> (<a>return</a> r)) = <a>observe</a> (<a>return</a> r)
--   
--   <a>observe</a> (<a>lift</a> (m <a>&gt;&gt;=</a> f)) = <a>observe</a> (<a>lift</a> m <a>&gt;&gt;=</a> <a>lift</a> <a>.</a> f)
--   </pre>
--   
--   This correctness comes at a small cost to performance, so use this
--   function sparingly.
--   
--   This function is a convenience for low-level <tt>pipes</tt>
--   implementers. You do not need to use <a>observe</a> if you stick to
--   the safe API.
observe :: Monad m => Proxy a' a b' b m r -> Proxy a' a b' b m r

-- | The empty type, used to close output ends
type X = Void

-- | Use <a>closed</a> to "handle" impossible outputs
closed :: X -> a
instance GHC.Base.Monad m => GHC.Base.Functor (Pipes.Internal.Proxy a' a b' b m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Pipes.Internal.Proxy a' a b' b m)
instance GHC.Base.Monad m => GHC.Base.Monad (Pipes.Internal.Proxy a' a b' b m)
instance (GHC.Base.Monad m, GHC.Base.Monoid r) => GHC.Base.Monoid (Pipes.Internal.Proxy a' a b' b m r)
instance Control.Monad.Trans.Class.MonadTrans (Pipes.Internal.Proxy a' a b' b)
instance Control.Monad.Morph.MFunctor (Pipes.Internal.Proxy a' a b' b)
instance Control.Monad.Morph.MMonad (Pipes.Internal.Proxy a' a b' b)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Pipes.Internal.Proxy a' a b' b m)


-- | The core functionality for the <a>Proxy</a> monad transformer
--   
--   Read <a>Pipes.Tutorial</a> 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 <a>Pipes</a> module if you
--   can. You should only use this module if you require advanced features
--   like:
--   
--   <ul>
--   <li>bidirectional communication, or:</li>
--   <li>push-based <a>Pipe</a>s.</li>
--   </ul>
module Pipes.Core

-- | A <a>Proxy</a> is a monad transformer that receives and sends
--   information on both an upstream and downstream interface.
--   
--   The type variables signify:
--   
--   <ul>
--   <li><tt>a'</tt> and <tt>a</tt> - The upstream interface, where
--   <tt>(a')</tt>s go out and <tt>(a)</tt>s come in</li>
--   <li><tt>b'</tt> and <tt>b</tt> - The downstream interface, where
--   <tt>(b)</tt>s go out and <tt>(b')</tt>s come in</li>
--   <li><tt>m </tt> - The base monad</li>
--   <li><tt>r </tt> - The return value</li>
--   </ul>
data Proxy a' a b' b m r

-- | Run a self-contained <a>Effect</a>, converting it back to the base
--   monad
runEffect :: Monad m => Effect m r -> m r

-- | Send a value of type <tt>a</tt> downstream and block waiting for a
--   reply of type <tt>a'</tt>
--   
--   <a>respond</a> is the identity of the respond category.
respond :: Monad m => a -> Proxy x' x a' a m a'

-- | Compose two unfolds, creating a new unfold
--   
--   <pre>
--   (f <a>/&gt;/</a> g) x = f x <a>//&gt;</a> g
--   </pre>
--   
--   (<a>/&gt;/</a>) is the composition operator of the respond category.
(/>/) :: 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')
infixr 4 />/

-- | <tt>(p //&gt; f)</tt> replaces each <a>respond</a> in <tt>p</tt> with
--   <tt>f</tt>.
--   
--   Point-ful version of (<a>/&gt;/</a>)
(//>) :: Monad m => Proxy x' x b' b m a' -> (b -> Proxy x' x c' c m b') -> Proxy x' x c' c m a'
infixl 3 //>

-- | Send a value of type <tt>a'</tt> upstream and block waiting for a
--   reply of type <tt>a</tt>
--   
--   <a>request</a> is the identity of the request category.
request :: Monad m => a' -> Proxy a' a y' y m a

-- | Compose two folds, creating a new fold
--   
--   <pre>
--   (f <a>\&gt;\</a> g) x = f <a>&gt;\\</a> g x
--   </pre>
--   
--   (<a>\&gt;\</a>) is the composition operator of the request category.
(\>\) :: 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)
infixl 5 \>\

-- | <tt>(f &gt;\\ p)</tt> replaces each <a>request</a> in <tt>p</tt> with
--   <tt>f</tt>.
--   
--   Point-ful version of (<a>\&gt;\</a>)
(>\\) :: Monad m => (b' -> Proxy a' a y' y m b) -> Proxy b' b y' y m c -> Proxy a' a y' y m c
infixr 4 >\\

-- | Forward responses followed by requests
--   
--   <pre>
--   <a>push</a> = <a>respond</a> <a>&gt;=&gt;</a> <a>request</a> <a>&gt;=&gt;</a> <a>push</a>
--   </pre>
--   
--   <a>push</a> is the identity of the push category.
push :: Monad m => a -> Proxy a' a a' a m r

-- | Compose two proxies blocked while <a>request</a>ing data, creating a
--   new proxy blocked while <a>request</a>ing data
--   
--   <pre>
--   (f <a>&gt;~&gt;</a> g) x = f x <a>&gt;&gt;~</a> g
--   </pre>
--   
--   (<a>&gt;~&gt;</a>) is the composition operator of the push category.
(>~>) :: 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)
infixr 8 >~>

-- | <tt>(p &gt;&gt;~ f)</tt> pairs each <a>respond</a> in <tt>p</tt> with
--   a <a>request</a> in <tt>f</tt>.
--   
--   Point-ful version of (<a>&gt;~&gt;</a>)
(>>~) :: Monad m => Proxy a' a b' b m r -> (b -> Proxy b' b c' c m r) -> Proxy a' a c' c m r
infixl 7 >>~

-- | Forward requests followed by responses:
--   
--   <pre>
--   <a>pull</a> = <a>request</a> <a>&gt;=&gt;</a> <a>respond</a> <a>&gt;=&gt;</a> <a>pull</a>
--   </pre>
--   
--   <a>pull</a> is the identity of the pull category.
pull :: Monad m => a' -> Proxy a' a a' a m r

-- | Compose two proxies blocked in the middle of <a>respond</a>ing,
--   creating a new proxy blocked in the middle of <a>respond</a>ing
--   
--   <pre>
--   (f <a>&gt;+&gt;</a> g) x = f <a>+&gt;&gt;</a> g x
--   </pre>
--   
--   (<a>&gt;+&gt;</a>) is the composition operator of the pull category.
(>+>) :: 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)
infixl 7 >+>

-- | <tt>(f +&gt;&gt; p)</tt> pairs each <a>request</a> in <tt>p</tt> with
--   a <a>respond</a> in <tt>f</tt>.
--   
--   Point-ful version of (<a>&gt;+&gt;</a>)
(+>>) :: Monad m => (b' -> Proxy a' a b' b m r) -> Proxy b' b c' c m r -> Proxy a' a c' c m r
infixr 6 +>>

-- | Switch the upstream and downstream ends
reflect :: Monad m => Proxy a' a b' b m r -> Proxy b b' a a' m r

-- | The empty type, used to close output ends
type X = Void

-- | An effect in the base monad
--   
--   <a>Effect</a>s neither <a>await</a> nor <a>yield</a>
type Effect = Proxy X () () X

-- | <a>Producer</a>s can only <a>yield</a>
type Producer b = Proxy X () () b

-- | <a>Pipe</a>s can both <a>await</a> and <a>yield</a>
type Pipe a b = Proxy () a () b

-- | <a>Consumer</a>s can only <a>await</a>
type Consumer a = Proxy () a () X

-- | <tt>Client a' a</tt> sends requests of type <tt>a'</tt> and receives
--   responses of type <tt>a</tt>.
--   
--   <a>Client</a>s only <a>request</a> and never <a>respond</a>.
type Client a' a = Proxy a' a () X

-- | <tt>Server b' b</tt> receives requests of type <tt>b'</tt> and sends
--   responses of type <tt>b</tt>.
--   
--   <a>Server</a>s only <a>respond</a> and never <a>request</a>.
type Server b' b = Proxy X () b' b

-- | Like <a>Effect</a>, but with a polymorphic type
type Effect' m r = forall x' x y' y. Proxy x' x y' y m r

-- | Like <a>Producer</a>, but with a polymorphic type
type Producer' b m r = forall x' x. Proxy x' x () b m r

-- | Like <a>Consumer</a>, but with a polymorphic type
type Consumer' a m r = forall y' y. Proxy () a y' y m r

-- | Like <a>Client</a>, but with a polymorphic type
type Client' a' a m r = forall y' y. Proxy a' a y' y m r

-- | Like <a>Server</a>, but with a polymorphic type
type Server' b' b m r = forall x' x. Proxy x' x b' b m r

-- | Equivalent to (<a>/&gt;/</a>) with the arguments flipped
(\<\) :: 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')
infixl 4 \<\

-- | Equivalent to (<a>\&gt;\</a>) with the arguments flipped
(/</) :: 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)
infixr 5 /</

-- | Equivalent to (<a>&gt;~&gt;</a>) with the arguments flipped
(<~<) :: 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)
infixl 8 <~<

-- | Equivalent to (<a>&gt;&gt;~</a>) with the arguments flipped
(~<<) :: Monad m => (b -> Proxy b' b c' c m r) -> Proxy a' a b' b m r -> Proxy a' a c' c m r
infixr 7 ~<<

-- | Equivalent to (<a>&gt;+&gt;</a>) with the arguments flipped
(<+<) :: 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)
infixr 7 <+<

-- | Equivalent to (<a>//&gt;</a>) with the arguments flipped
(<\\) :: Monad m => (b -> Proxy x' x c' c m b') -> Proxy x' x b' b m a' -> Proxy x' x c' c m a'
infixr 3 <\\

-- | Equivalent to (<a>&gt;\\</a>) with the arguments flipped
(//<) :: Monad m => Proxy b' b y' y m c -> (b' -> Proxy a' a y' y m b) -> Proxy a' a y' y m c
infixl 4 //<

-- | Equivalent to (<a>+&gt;&gt;</a>) with the arguments flipped
(<<+) :: Monad m => Proxy b' b c' c m r -> (b' -> Proxy a' a b' b m r) -> Proxy a' a c' c m r
infixl 6 <<+

-- | Use <a>closed</a> to "handle" impossible outputs
closed :: X -> a


-- | Many actions in base monad transformers cannot be automatically
--   <a>lift</a>ed. These functions lift these remaining actions so that
--   they work in the <a>Proxy</a> monad transformer.
--   
--   See the mini-tutorial at the bottom of this module for example code
--   and typical use cases where this module will come in handy.
module Pipes.Lift

-- | Distribute <a>Proxy</a> over a monad transformer
distribute :: (Monad m, MonadTrans t, MFunctor t, Monad (t m), Monad (t (Proxy a' a b' b m))) => Proxy a' a b' b (t m) r -> t (Proxy a' a b' b m) r

-- | Wrap the base monad in <a>ExceptT</a>
exceptP :: Monad m => Proxy a' a b' b m (Either e r) -> Proxy a' a b' b (ExceptT e m) r

-- | Run <a>ExceptT</a> in the base monad
runExceptP :: Monad m => Proxy a' a b' b (ExceptT e m) r -> Proxy a' a b' b m (Either e r)

-- | Catch an error in the base monad
catchError :: Monad m => Proxy a' a b' b (ExceptT e m) r -> (e -> Proxy a' a b' b (ExceptT e m) r) -> Proxy a' a b' b (ExceptT e m) r

-- | Catch an error using a catch function for the base monad
liftCatchError :: Monad m => (m (Proxy a' a b' b m r) -> (e -> m (Proxy a' a b' b m r)) -> m (Proxy a' a b' b m r)) -> (Proxy a' a b' b m r -> (e -> Proxy a' a b' b m r) -> Proxy a' a b' b m r)

-- | Wrap the base monad in <a>MaybeT</a>
maybeP :: Monad m => Proxy a' a b' b m (Maybe r) -> Proxy a' a b' b (MaybeT m) r

-- | Run <a>MaybeT</a> in the base monad
runMaybeP :: Monad m => Proxy a' a b' b (MaybeT m) r -> Proxy a' a b' b m (Maybe r)

-- | Wrap the base monad in <a>ReaderT</a>
readerP :: Monad m => (i -> Proxy a' a b' b m r) -> Proxy a' a b' b (ReaderT i m) r

-- | Run <a>ReaderT</a> in the base monad
runReaderP :: Monad m => i -> Proxy a' a b' b (ReaderT i m) r -> Proxy a' a b' b m r

-- | Wrap the base monad in <a>StateT</a>
stateP :: Monad m => (s -> Proxy a' a b' b m (r, s)) -> Proxy a' a b' b (StateT s m) r

-- | Run <a>StateT</a> in the base monad
runStateP :: Monad m => s -> Proxy a' a b' b (StateT s m) r -> Proxy a' a b' b m (r, s)

-- | Evaluate <a>StateT</a> in the base monad
evalStateP :: Monad m => s -> Proxy a' a b' b (StateT s m) r -> Proxy a' a b' b m r

-- | Execute <a>StateT</a> in the base monad
execStateP :: Monad m => s -> Proxy a' a b' b (StateT s m) r -> Proxy a' a b' b m s

-- | Wrap the base monad in <a>WriterT</a>
writerP :: (Monad m, Monoid w) => Proxy a' a b' b m (r, w) -> Proxy a' a b' b (WriterT w m) r

-- | Run <a>WriterT</a> in the base monad
runWriterP :: (Monad m, Monoid w) => Proxy a' a b' b (WriterT w m) r -> Proxy a' a b' b m (r, w)

-- | Execute <a>WriterT</a> in the base monad
execWriterP :: (Monad m, Monoid w) => Proxy a' a b' b (WriterT w m) r -> Proxy a' a b' b m w

-- | Wrap the base monad in <a>RWST</a>
rwsP :: (Monad m, Monoid w) => (i -> s -> Proxy a' a b' b m (r, s, w)) -> Proxy a' a b' b (RWST i w s m) r

-- | Run <a>RWST</a> in the base monad
runRWSP :: (Monad m, Monoid w) => r -> s -> Proxy a' a b' b (RWST r w s m) d -> Proxy a' a b' b m (d, s, w)

-- | Evaluate <a>RWST</a> in the base monad
evalRWSP :: (Monad m, Monoid w) => r -> s -> Proxy a' a b' b (RWST r w s m) d -> Proxy a' a b' b m (d, w)

-- | Execute <a>RWST</a> in the base monad
execRWSP :: (Monad m, Monoid w) => r -> s -> Proxy a' a b' b (RWST r w s m) d -> Proxy a' a b' b m (s, w)


-- | This module is the recommended entry point to the <tt>pipes</tt>
--   library.
--   
--   Read <a>Pipes.Tutorial</a> if you want a tutorial explaining how to
--   use this library.
module Pipes

-- | A <a>Proxy</a> is a monad transformer that receives and sends
--   information on both an upstream and downstream interface.
--   
--   The type variables signify:
--   
--   <ul>
--   <li><tt>a'</tt> and <tt>a</tt> - The upstream interface, where
--   <tt>(a')</tt>s go out and <tt>(a)</tt>s come in</li>
--   <li><tt>b'</tt> and <tt>b</tt> - The downstream interface, where
--   <tt>(b)</tt>s go out and <tt>(b')</tt>s come in</li>
--   <li><tt>m </tt> - The base monad</li>
--   <li><tt>r </tt> - The return value</li>
--   </ul>
data Proxy a' a b' b m r

-- | The empty type, used to close output ends
type X = Void

-- | An effect in the base monad
--   
--   <a>Effect</a>s neither <a>await</a> nor <a>yield</a>
type Effect = Proxy X () () X

-- | Like <a>Effect</a>, but with a polymorphic type
type Effect' m r = forall x' x y' y. Proxy x' x y' y m r

-- | Run a self-contained <a>Effect</a>, converting it back to the base
--   monad
runEffect :: Monad m => Effect m r -> m r

-- | <a>Producer</a>s can only <a>yield</a>
type Producer b = Proxy X () () b

-- | Like <a>Producer</a>, but with a polymorphic type
type Producer' b m r = forall x' x. Proxy x' x () b m r

-- | Produce a value
--   
--   <pre>
--   <a>yield</a> :: <a>Monad</a> m =&gt; a -&gt; <a>Pipe</a> x a m ()
--   </pre>
yield :: Monad m => a -> Producer' a m ()

-- | <tt>(for p body)</tt> loops over <tt>p</tt> replacing each
--   <a>yield</a> with <tt>body</tt>.
--   
--   <pre>
--   <a>for</a> :: <a>Monad</a> m =&gt; <a>Producer</a> b m r -&gt; (b -&gt; <a>Effect</a>       m ()) -&gt; <a>Effect</a>       m r
--   <a>for</a> :: <a>Monad</a> m =&gt; <a>Producer</a> b m r -&gt; (b -&gt; <a>Producer</a>   c m ()) -&gt; <a>Producer</a>   c m r
--   <a>for</a> :: <a>Monad</a> m =&gt; <a>Pipe</a>   x b m r -&gt; (b -&gt; <a>Consumer</a> x   m ()) -&gt; <a>Consumer</a> x   m r
--   <a>for</a> :: <a>Monad</a> m =&gt; <a>Pipe</a>   x b m r -&gt; (b -&gt; <a>Pipe</a>     x c m ()) -&gt; <a>Pipe</a>     x c m r
--   </pre>
--   
--   The following diagrams show the flow of information:
--   
--   <pre>
--                                 .---&gt;   b
--                                /        |
--      +-----------+            /   +-----|-----+                 +---------------+
--      |           |           /    |     v     |                 |               |
--      |           |          /     |           |                 |               |
--   x ==&gt;    p    ==&gt; b   ---'   x ==&gt;   body  ==&gt; c     =     x ==&gt; <a>for</a> p body  ==&gt; c
--      |           |                |           |                 |               |
--      |     |     |                |     |     |                 |       |       |
--      +-----|-----+                +-----|-----+                 +-------|-------+
--            v                            v                               v
--            r                            ()                              r
--   </pre>
--   
--   For a more complete diagram including bidirectional flow, see
--   <a>Pipes.Core#respond-diagram</a>.
for :: Monad m => Proxy x' x b' b m a' -> (b -> Proxy x' x c' c m b') -> Proxy x' x c' c m a'

-- | Compose loop bodies
--   
--   <pre>
--   (<a>~&gt;</a>) :: <a>Monad</a> m =&gt; (a -&gt; <a>Producer</a> b m r) -&gt; (b -&gt; <a>Effect</a>       m ()) -&gt; (a -&gt; <a>Effect</a>       m r)
--   (<a>~&gt;</a>) :: <a>Monad</a> m =&gt; (a -&gt; <a>Producer</a> b m r) -&gt; (b -&gt; <a>Producer</a>   c m ()) -&gt; (a -&gt; <a>Producer</a>   c m r)
--   (<a>~&gt;</a>) :: <a>Monad</a> m =&gt; (a -&gt; <a>Pipe</a>   x b m r) -&gt; (b -&gt; <a>Consumer</a> x   m ()) -&gt; (a -&gt; <a>Consumer</a> x   m r)
--   (<a>~&gt;</a>) :: <a>Monad</a> m =&gt; (a -&gt; <a>Pipe</a>   x b m r) -&gt; (b -&gt; <a>Pipe</a>     x c m ()) -&gt; (a -&gt; <a>Pipe</a>     x c m r)
--   </pre>
--   
--   The following diagrams show the flow of information:
--   
--   <pre>
--            a                    .---&gt;   b                              a
--            |                   /        |                              |
--      +-----|-----+            /   +-----|-----+                 +------|------+
--      |     v     |           /    |     v     |                 |      v      |
--      |           |          /     |           |                 |             |
--   x ==&gt;    f    ==&gt; b   ---'   x ==&gt;    g    ==&gt; c     =     x ==&gt;   f <a>~&gt;</a> g  ==&gt; c
--      |           |                |           |                 |             |
--      |     |     |                |     |     |                 |      |      |
--      +-----|-----+                +-----|-----+                 +------|------+
--            v                            v                              v
--            r                            ()                             r
--   </pre>
--   
--   For a more complete diagram including bidirectional flow, see
--   <a>Pipes.Core#respond-diagram</a>.
(~>) :: 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')
infixr 4 ~>

-- | (<a>~&gt;</a>) with the arguments flipped
(<~) :: 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')
infixl 4 <~

-- | <a>Consumer</a>s can only <a>await</a>
type Consumer a = Proxy () a () X

-- | Like <a>Consumer</a>, but with a polymorphic type
type Consumer' a m r = forall y' y. Proxy () a y' y m r

-- | Consume a value
--   
--   <pre>
--   <a>await</a> :: <a>Monad</a> m =&gt; <a>Pipe</a> a y m a
--   </pre>
await :: Monad m => Consumer' a m a

-- | <tt>(draw &gt;~ p)</tt> loops over <tt>p</tt> replacing each
--   <a>await</a> with <tt>draw</tt>
--   
--   <pre>
--   (<a>&gt;~</a>) :: <a>Monad</a> m =&gt; <a>Effect</a>       m b -&gt; <a>Consumer</a> b   m c -&gt; <a>Effect</a>       m c
--   (<a>&gt;~</a>) :: <a>Monad</a> m =&gt; <a>Consumer</a> a   m b -&gt; <a>Consumer</a> b   m c -&gt; <a>Consumer</a> a   m c
--   (<a>&gt;~</a>) :: <a>Monad</a> m =&gt; <a>Producer</a>   y m b -&gt; <a>Pipe</a>     b y m c -&gt; <a>Producer</a>   y m c
--   (<a>&gt;~</a>) :: <a>Monad</a> m =&gt; <a>Pipe</a>     a y m b -&gt; <a>Pipe</a>     b y m c -&gt; <a>Pipe</a>     a y m c
--   </pre>
--   
--   The following diagrams show the flow of information:
--   
--   <pre>
--      +-----------+                 +-----------+                 +-------------+
--      |           |                 |           |                 |             |
--      |           |                 |           |                 |             |
--   a ==&gt;    f    ==&gt; y   .---&gt;   b ==&gt;    g    ==&gt; y     =     a ==&gt;   f <a>&gt;~</a> g  ==&gt; y
--      |           |     /           |           |                 |             |
--      |     |     |    /            |     |     |                 |      |      |
--      +-----|-----+   /             +-----|-----+                 +------|------+
--            v        /                    v                              v
--            b   ----'                     c                              c
--   </pre>
--   
--   For a more complete diagram including bidirectional flow, see
--   <a>Pipes.Core#request-diagram</a>.
(>~) :: Monad m => Proxy a' a y' y m b -> Proxy () b y' y m c -> Proxy a' a y' y m c
infixr 5 >~

-- | (<a>&gt;~</a>) with the arguments flipped
(~<) :: Monad m => Proxy () b y' y m c -> Proxy a' a y' y m b -> Proxy a' a y' y m c
infixl 5 ~<

-- | <a>Pipe</a>s can both <a>await</a> and <a>yield</a>
type Pipe a b = Proxy () a () b

-- | The identity <a>Pipe</a>, analogous to the Unix <tt>cat</tt> program
cat :: Monad m => Pipe a a m r

-- | <a>Pipe</a> composition, analogous to the Unix pipe operator
--   
--   <pre>
--   (<a>&gt;-&gt;</a>) :: <a>Monad</a> m =&gt; <a>Producer</a> b m r -&gt; <a>Consumer</a> b   m r -&gt; <a>Effect</a>       m r
--   (<a>&gt;-&gt;</a>) :: <a>Monad</a> m =&gt; <a>Producer</a> b m r -&gt; <a>Pipe</a>     b c m r -&gt; <a>Producer</a>   c m r
--   (<a>&gt;-&gt;</a>) :: <a>Monad</a> m =&gt; <a>Pipe</a>   a b m r -&gt; <a>Consumer</a> b   m r -&gt; <a>Consumer</a> a   m r
--   (<a>&gt;-&gt;</a>) :: <a>Monad</a> m =&gt; <a>Pipe</a>   a b m r -&gt; <a>Pipe</a>     b c m r -&gt; <a>Pipe</a>     a c m r
--   </pre>
--   
--   The following diagrams show the flow of information:
--   
--   <pre>
--      +-----------+     +-----------+                 +-------------+
--      |           |     |           |                 |             |
--      |           |     |           |                 |             |
--   a ==&gt;    f    ==&gt; b ==&gt;    g    ==&gt; c     =     a ==&gt;  f <a>&gt;-&gt;</a> g  ==&gt; c
--      |           |     |           |                 |             |
--      |     |     |     |     |     |                 |      |      |
--      +-----|-----+     +-----|-----+                 +------|------+
--            v                 v                              v
--            r                 r                              r
--   </pre>
--   
--   For a more complete diagram including bidirectional flow, see
--   <a>Pipes.Core#pull-diagram</a>.
(>->) :: Monad m => Proxy a' a () b m r -> Proxy () b c' c m r -> Proxy a' a c' c m r
infixl 7 >->

-- | (<a>&gt;-&gt;</a>) with the arguments flipped
(<-<) :: Monad m => Proxy () b c' c m r -> Proxy a' a () b m r -> Proxy a' a c' c m r
infixr 7 <-<

-- | The list monad transformer, which extends a monad with non-determinism
--   
--   <a>return</a> corresponds to <a>yield</a>, yielding a single value
--   
--   (<a>&gt;&gt;=</a>) corresponds to <a>for</a>, calling the second
--   computation once for each time the first computation <a>yield</a>s.
newtype ListT m a
Select :: Producer a m () -> ListT m a
[enumerate] :: ListT m a -> Producer a m ()

-- | Run a self-contained <a>ListT</a> computation
runListT :: Monad m => ListT m a -> m ()

-- | <a>Enumerable</a> generalizes <a>Foldable</a>, converting effectful
--   containers to <a>ListT</a>s.
--   
--   Instances of <a>Enumerable</a> must satisfy these two laws:
--   
--   <pre>
--   toListT (return r) = return r
--   
--   toListT $ do x &lt;- m  =  do x &lt;- toListT m
--                f x           toListT (f x)
--   </pre>
--   
--   In other words, <a>toListT</a> is monad morphism.
class Enumerable t
toListT :: (Enumerable t, Monad m) => t m a -> ListT m a

-- | Consume the first value from a <a>Producer</a>
--   
--   <a>next</a> either fails with a <a>Left</a> if the <a>Producer</a>
--   terminates or succeeds with a <a>Right</a> providing the next value
--   and the remainder of the <a>Producer</a>.
next :: Monad m => Producer a m r -> m (Either r (a, Producer a m r))

-- | Convert a <a>Foldable</a> to a <a>Producer</a>
each :: (Monad m, Foldable f) => f a -> Producer' a m ()

-- | Convert an <a>Enumerable</a> to a <a>Producer</a>
every :: (Monad m, Enumerable t) => t m a -> Producer' a m ()

-- | Discards a value
discard :: Monad m => a -> m ()

-- | Data structures that can be folded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--   </pre>
--   
--   This is suitable even for abstract types, as the monoid is assumed to
--   satisfy the monoid laws. Alternatively, one could define
--   <tt>foldr</tt>:
--   
--   <pre>
--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--   </pre>
--   
--   <tt>Foldable</tt> instances are expected to satisfy the following
--   laws:
--   
--   <pre>
--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--   </pre>
--   
--   <pre>
--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--   </pre>
--   
--   <pre>
--   fold = foldMap id
--   </pre>
--   
--   <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
--   should all be essentially equivalent to <tt>foldMap</tt> forms, such
--   as
--   
--   <pre>
--   sum = getSum . foldMap Sum
--   </pre>
--   
--   but may be less defined.
--   
--   If the type is also a <a>Functor</a> instance, it should satisfy
--   
--   <pre>
--   foldMap f = fold . fmap f
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   foldMap f . fmap g = foldMap (f . g)
--   </pre>
class Foldable (t :: * -> *)
instance GHC.Base.Monad m => GHC.Base.Functor (Pipes.ListT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Pipes.ListT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Pipes.ListT m)
instance Data.Foldable.Foldable m => Data.Foldable.Foldable (Pipes.ListT m)
instance (GHC.Base.Monad m, Data.Traversable.Traversable m) => Data.Traversable.Traversable (Pipes.ListT m)
instance Control.Monad.Trans.Class.MonadTrans Pipes.ListT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Pipes.ListT m)
instance GHC.Base.Monad m => GHC.Base.Alternative (Pipes.ListT m)
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Pipes.ListT m)
instance Control.Monad.Morph.MFunctor Pipes.ListT
instance Control.Monad.Morph.MMonad Pipes.ListT
instance GHC.Base.Monad m => GHC.Base.Monoid (Pipes.ListT m a)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Pipes.ListT m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Pipes.ListT m)
instance Control.Monad.Reader.Class.MonadReader i m => Control.Monad.Reader.Class.MonadReader i (Pipes.ListT m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Pipes.ListT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Pipes.ListT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Pipes.ListT m)
instance GHC.Base.Monad m => Control.Monad.Zip.MonadZip (Pipes.ListT m)
instance Pipes.Enumerable Pipes.ListT
instance Pipes.Enumerable Control.Monad.Trans.Identity.IdentityT
instance Pipes.Enumerable Control.Monad.Trans.Maybe.MaybeT
instance Pipes.Enumerable (Control.Monad.Trans.Except.ExceptT e)


-- | General purpose utilities
--   
--   The names in this module clash heavily with the Haskell Prelude, so I
--   recommend the following import scheme:
--   
--   <pre>
--   import Pipes
--   import qualified Pipes.Prelude as P  -- or use any other qualifier you prefer
--   </pre>
--   
--   Note that <a>String</a>-based <a>IO</a> is inefficient. The
--   <a>String</a>-based utilities in this module exist only for simple
--   demonstrations without incurring a dependency on the <tt>text</tt>
--   package.
--   
--   Also, <a>stdinLn</a> and <a>stdoutLn</a> remove and add newlines,
--   respectively. This behavior is intended to simplify examples. The
--   corresponding <tt>stdin</tt> and <tt>stdout</tt> utilities from
--   <tt>pipes-bytestring</tt> and <tt>pipes-text</tt> preserve newlines.
module Pipes.Prelude

-- | Read <a>String</a>s from <a>stdin</a> using <a>getLine</a>
--   
--   Terminates on end of input
stdinLn :: MonadIO m => Producer' String m ()

-- | <a>read</a> values from <a>stdin</a>, ignoring failed parses
readLn :: (MonadIO m, Read a) => Producer' a m ()

-- | Read <a>String</a>s from a <a>Handle</a> using <a>hGetLine</a>
--   
--   Terminates on end of input
fromHandle :: MonadIO m => Handle -> Producer' String m ()

-- | Repeat a monadic action indefinitely, <a>yield</a>ing each result
repeatM :: Monad m => m a -> Producer' a m r

-- | Repeat a monadic action a fixed number of times, <a>yield</a>ing each
--   result
--   
--   <pre>
--   replicateM  0      x = return ()
--   
--   replicateM (m + n) x = replicateM m x &gt;&gt; replicateM n x  -- 0 &lt;= {m,n}
--   </pre>
replicateM :: Monad m => Int -> m a -> Producer' a m ()

-- | The natural unfold into a <a>Producer</a> with a step function and a
--   seed
--   
--   <pre>
--   unfoldr next = id
--   </pre>
unfoldr :: Monad m => (s -> m (Either r (a, s))) -> s -> Producer a m r

-- | Write <a>String</a>s to <a>stdout</a> using <a>putStrLn</a>
--   
--   Unlike <a>toHandle</a>, <a>stdoutLn</a> gracefully terminates on a
--   broken output pipe
stdoutLn :: MonadIO m => Consumer' String m ()

-- | Write <a>String</a>s to <a>stdout</a> using <a>putStrLn</a>
--   
--   This does not handle a broken output pipe, but has a polymorphic
--   return value
stdoutLn' :: MonadIO m => Consumer' String m r

-- | Consume all values using a monadic function
mapM_ :: Monad m => (a -> m ()) -> Consumer' a m r

-- | <a>print</a> values to <a>stdout</a>
print :: (MonadIO m, Show a) => Consumer' a m r

-- | Write <a>String</a>s to a <a>Handle</a> using <a>hPutStrLn</a>
toHandle :: MonadIO m => Handle -> Consumer' String m r

-- | <a>discard</a> all incoming values
drain :: Monad m => Consumer' a m r

-- | Apply a function to all values flowing downstream
--   
--   <pre>
--   map id = cat
--   
--   map (g . f) = map f &gt;-&gt; map g
--   </pre>
map :: Monad m => (a -> b) -> Pipe a b m r

-- | Apply a monadic function to all values flowing downstream
--   
--   <pre>
--   mapM return = cat
--   
--   mapM (f &gt;=&gt; g) = mapM f &gt;-&gt; mapM g
--   </pre>
mapM :: Monad m => (a -> m b) -> Pipe a b m r

-- | Convert a stream of actions to a stream of values
sequence :: Monad m => Pipe (m a) a m r

-- | Apply a function to all values flowing downstream, and forward each
--   element of the result.
mapFoldable :: (Monad m, Foldable t) => (a -> t b) -> Pipe a b m r

-- | <tt>(filter predicate)</tt> only forwards values that satisfy the
--   predicate.
--   
--   <pre>
--   filter (pure True) = cat
--   
--   filter (liftA2 (&amp;&amp;) p1 p2) = filter p1 &gt;-&gt; filter p2
--   </pre>
filter :: Monad m => (a -> Bool) -> Pipe a a m r

-- | <tt>(filterM predicate)</tt> only forwards values that satisfy the
--   monadic predicate
--   
--   <pre>
--   filterM (pure (pure True)) = cat
--   
--   filterM (liftA2 (liftA2 (&amp;&amp;)) p1 p2) = filterM p1 &gt;-&gt; filterM p2
--   </pre>
filterM :: Monad m => (a -> m Bool) -> Pipe a a m r

-- | <tt>(take n)</tt> only allows <tt>n</tt> values to pass through
--   
--   <pre>
--   take 0 = return ()
--   
--   take (m + n) = take m &gt;&gt; take n
--   </pre>
--   
--   <pre>
--   take &lt;infinity&gt; = cat
--   
--   take (min m n) = take m &gt;-&gt; take n
--   </pre>
take :: Monad m => Int -> Pipe a a m ()

-- | <tt>(takeWhile p)</tt> allows values to pass downstream so long as
--   they satisfy the predicate <tt>p</tt>.
--   
--   <pre>
--   takeWhile (pure True) = cat
--   
--   takeWhile (liftA2 (&amp;&amp;) p1 p2) = takeWhile p1 &gt;-&gt; takeWhile p2
--   </pre>
takeWhile :: Monad m => (a -> Bool) -> Pipe a a m ()

-- | <tt>(takeWhile' p)</tt> is a version of takeWhile that returns the
--   value failing the predicate.
--   
--   <pre>
--   takeWhile' (pure True) = cat
--   
--   takeWhile' (liftA2 (&amp;&amp;) p1 p2) = takeWhile' p1 &gt;-&gt; takeWhile' p2
--   </pre>
takeWhile' :: Monad m => (a -> Bool) -> Pipe a a m a

-- | <tt>(drop n)</tt> discards <tt>n</tt> values going downstream
--   
--   <pre>
--   drop 0 = cat
--   
--   drop (m + n) = drop m &gt;-&gt; drop n
--   </pre>
drop :: Monad m => Int -> Pipe a a m r

-- | <tt>(dropWhile p)</tt> discards values going downstream until one
--   violates the predicate <tt>p</tt>.
--   
--   <pre>
--   dropWhile (pure False) = cat
--   
--   dropWhile (liftA2 (||) p1 p2) = dropWhile p1 &gt;-&gt; dropWhile p2
--   </pre>
dropWhile :: Monad m => (a -> Bool) -> Pipe a a m r

-- | Flatten all <a>Foldable</a> elements flowing downstream
concat :: (Monad m, Foldable f) => Pipe (f a) a m r

-- | Outputs the indices of all elements that match the given element
elemIndices :: (Monad m, Eq a) => a -> Pipe a Int m r

-- | Outputs the indices of all elements that satisfied the predicate
findIndices :: Monad m => (a -> Bool) -> Pipe a Int m r

-- | Strict left scan
--   
--   <pre>
--   Control.Foldl.purely scan :: Monad m =&gt; Fold a b -&gt; Pipe a b m r
--   </pre>
scan :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Pipe a b m r

-- | Strict, monadic left scan
--   
--   <pre>
--   Control.Foldl.impurely scan :: Monad m =&gt; FoldM a m b -&gt; Pipe a b m r
--   </pre>
scanM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Pipe a b m r

-- | Apply an action to all values flowing downstream
--   
--   <pre>
--   chain (pure (return ())) = cat
--   
--   chain (liftA2 (&gt;&gt;) m1 m2) = chain m1 &gt;-&gt; chain m2
--   </pre>
chain :: Monad m => (a -> m ()) -> Pipe a a m r

-- | Parse <a>Read</a>able values, only forwarding the value if the parse
--   succeeds
read :: (Monad m, Read a) => Pipe String a m r

-- | Convert <a>Show</a>able values to <a>String</a>s
show :: (Monad m, Show a) => Pipe a String m r

-- | Evaluate all values flowing downstream to WHNF
seq :: Monad m => Pipe a a m r

-- | Create a <a>Pipe</a> from a <a>ListT</a> transformation
--   
--   <pre>
--   loop (k1 &gt;=&gt; k2) = loop k1 &gt;-&gt; loop k2
--   
--   loop return = cat
--   </pre>
loop :: Monad m => (a -> ListT m b) -> Pipe a b m r

-- | Strict fold of the elements of a <a>Producer</a>
--   
--   <pre>
--   Control.Foldl.purely fold :: Monad m =&gt; Fold a b -&gt; Producer a m () -&gt; m b
--   </pre>
fold :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Producer a m () -> m b

-- | Strict fold of the elements of a <a>Producer</a> that preserves the
--   return value
--   
--   <pre>
--   Control.Foldl.purely fold' :: Monad m =&gt; Fold a b -&gt; Producer a m r -&gt; m (b, r)
--   </pre>
fold' :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Producer a m r -> m (b, r)

-- | Strict, monadic fold of the elements of a <a>Producer</a>
--   
--   <pre>
--   Control.Foldl.impurely foldM :: Monad m =&gt; FoldM a b -&gt; Producer a m () -&gt; m b
--   </pre>
foldM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Producer a m () -> m b

-- | Strict, monadic fold of the elements of a <a>Producer</a>
--   
--   <pre>
--   Control.Foldl.impurely foldM' :: Monad m =&gt; FoldM a b -&gt; Producer a m r -&gt; m (b, r)
--   </pre>
foldM' :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Producer a m r -> m (b, r)

-- | <tt>(all predicate p)</tt> determines whether all the elements of
--   <tt>p</tt> satisfy the predicate.
all :: Monad m => (a -> Bool) -> Producer a m () -> m Bool

-- | <tt>(any predicate p)</tt> determines whether any element of
--   <tt>p</tt> satisfies the predicate.
any :: Monad m => (a -> Bool) -> Producer a m () -> m Bool

-- | Determines whether all elements are <a>True</a>
and :: Monad m => Producer Bool m () -> m Bool

-- | Determines whether any element is <a>True</a>
or :: Monad m => Producer Bool m () -> m Bool

-- | <tt>(elem a p)</tt> returns <a>True</a> if <tt>p</tt> has an element
--   equal to <tt>a</tt>, <a>False</a> otherwise
elem :: (Monad m, Eq a) => a -> Producer a m () -> m Bool

-- | <tt>(notElem a)</tt> returns <a>False</a> if <tt>p</tt> has an element
--   equal to <tt>a</tt>, <a>True</a> otherwise
notElem :: (Monad m, Eq a) => a -> Producer a m () -> m Bool

-- | Find the first element of a <a>Producer</a> that satisfies the
--   predicate
find :: Monad m => (a -> Bool) -> Producer a m () -> m (Maybe a)

-- | Find the index of the first element of a <a>Producer</a> that
--   satisfies the predicate
findIndex :: Monad m => (a -> Bool) -> Producer a m () -> m (Maybe Int)

-- | Retrieve the first element from a <a>Producer</a>
head :: Monad m => Producer a m () -> m (Maybe a)

-- | Index into a <a>Producer</a>
index :: Monad m => Int -> Producer a m () -> m (Maybe a)

-- | Retrieve the last element from a <a>Producer</a>
last :: Monad m => Producer a m () -> m (Maybe a)

-- | Count the number of elements in a <a>Producer</a>
length :: Monad m => Producer a m () -> m Int

-- | Find the maximum element of a <a>Producer</a>
maximum :: (Monad m, Ord a) => Producer a m () -> m (Maybe a)

-- | Find the minimum element of a <a>Producer</a>
minimum :: (Monad m, Ord a) => Producer a m () -> m (Maybe a)

-- | Determine if a <a>Producer</a> is empty
null :: Monad m => Producer a m () -> m Bool

-- | Compute the sum of the elements of a <a>Producer</a>
sum :: (Monad m, Num a) => Producer a m () -> m a

-- | Compute the product of the elements of a <a>Producer</a>
product :: (Monad m, Num a) => Producer a m () -> m a

-- | Convert a pure <a>Producer</a> into a list
toList :: Producer a Identity () -> [a]

-- | Convert an effectful <a>Producer</a> into a list
--   
--   Note: <a>toListM</a> is not an idiomatic use of <tt>pipes</tt>, but I
--   provide it for simple testing purposes. Idiomatic <tt>pipes</tt> style
--   consumes the elements immediately as they are generated instead of
--   loading all elements into memory.
toListM :: Monad m => Producer a m () -> m [a]

-- | Convert an effectful <a>Producer</a> into a list alongside the return
--   value
--   
--   Note: <a>toListM'</a> is not an idiomatic use of <tt>pipes</tt>, but I
--   provide it for simple testing purposes. Idiomatic <tt>pipes</tt> style
--   consumes the elements immediately as they are generated instead of
--   loading all elements into memory.
toListM' :: Monad m => Producer a m r -> m ([a], r)

-- | Zip two <a>Producer</a>s
zip :: Monad m => (Producer a m r) -> (Producer b m r) -> (Producer' (a, b) m r)

-- | Zip two <a>Producer</a>s using the provided combining function
zipWith :: Monad m => (a -> b -> c) -> (Producer a m r) -> (Producer b m r) -> (Producer' c m r)

-- | Transform a <a>Consumer</a> to a <a>Pipe</a> that reforwards all
--   values further downstream
tee :: Monad m => Consumer a m r -> Pipe a a m r

-- | Transform a unidirectional <a>Pipe</a> to a bidirectional <a>Proxy</a>
--   
--   <pre>
--   generalize (f &gt;-&gt; g) = generalize f &gt;+&gt; generalize g
--   
--   generalize cat = pull
--   </pre>
generalize :: Monad m => Pipe a b m r -> x -> Proxy x a x b m r


-- | Conventional Haskell stream programming forces you to choose only two
--   of the following three features:
--   
--   <ul>
--   <li>Effects</li>
--   <li>Streaming</li>
--   <li>Composability</li>
--   </ul>
--   
--   If you sacrifice <i>Effects</i> you get Haskell's pure and lazy lists,
--   which you can transform using composable functions in constant space,
--   but without interleaving effects.
--   
--   If you sacrifice <i>Streaming</i> you get <a>mapM</a>, <a>forM</a> and
--   "ListT done wrong", which are composable and effectful, but do not
--   return a single result until the whole list has first been processed
--   and loaded into memory.
--   
--   If you sacrifice <i>Composability</i> you write a tightly coupled
--   read, transform, and write loop in <a>IO</a>, which is streaming and
--   effectful, but is not modular or separable.
--   
--   <tt>pipes</tt> gives you all three features: effectful, streaming, and
--   composable programming. <tt>pipes</tt> also provides a wide variety of
--   stream programming abstractions which are all subsets of a single
--   unified machinery:
--   
--   <ul>
--   <li>effectful <a>Producer</a>s (like generators),</li>
--   <li>effectful <a>Consumer</a>s (like iteratees),</li>
--   <li>effectful <a>Pipe</a>s (like Unix pipes), and:</li>
--   <li><a>ListT</a> done right.</li>
--   </ul>
--   
--   All of these are connectable and you can combine them together in
--   clever and unexpected ways because they all share the same underlying
--   type.
--   
--   <tt>pipes</tt> requires a basic understanding of monad transformers,
--   which you can learn about by reading either:
--   
--   <ul>
--   <li>the paper "Monad Transformers - Step by Step",</li>
--   <li>part III "Monads in the Real World" of the tutorial "All About
--   Monads",</li>
--   <li>chapter 18 of "Real World Haskell" on monad transformers, or:</li>
--   <li>the documentation of the <tt>transformers</tt> library.</li>
--   </ul>
--   
--   If you want a Quick Start guide to <tt>pipes</tt>, read the
--   documentation in <a>Pipes.Prelude</a> from top to bottom.
--   
--   This tutorial is more extensive and explains the <tt>pipes</tt> API in
--   greater detail and illustrates several idioms.
module Pipes.Tutorial
