-- 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.16


-- | 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 :: Type -> Type) r
Request :: a' -> (a -> Proxy a' a b' b m r) -> Proxy a' a b' b (m :: Type -> Type) r
Respond :: b -> (b' -> Proxy a' a b' b m r) -> Proxy a' a b' b (m :: Type -> Type) r
M :: m (Proxy a' a b' b m r) -> Proxy a' a b' b (m :: Type -> Type) r
Pure :: r -> Proxy a' a b' b (m :: Type -> Type) 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 :: Functor 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 :: forall (m :: Type -> Type) a' a b' b r. 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.Internal.Base.Functor m => GHC.Internal.Base.Applicative (Pipes.Internal.Proxy a' a b' b m)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Functor (Pipes.Internal.Proxy a' a b' b m)
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.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (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 GHC.Internal.Control.Monad.Fail.MonadFail m => GHC.Internal.Control.Monad.Fail.MonadFail (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Pipes.Internal.Proxy a' a b' b m)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Monad (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.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Pipes.Internal.Proxy a' a b' b m)
instance Control.Monad.Trans.Class.MonadTrans (Pipes.Internal.Proxy a' a b' b)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Pipes.Internal.Proxy a' a b' b m)
instance (GHC.Internal.Base.Functor m, GHC.Internal.Base.Monoid r, GHC.Internal.Base.Semigroup r) => GHC.Internal.Base.Monoid (Pipes.Internal.Proxy a' a b' b m r)
instance (GHC.Internal.Base.Functor m, GHC.Internal.Base.Semigroup r) => GHC.Internal.Base.Semigroup (Pipes.Internal.Proxy a' a b' b m r)


-- | 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 :: Type -> Type) 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 :: forall (m :: Type -> Type) a x' x a'. Functor 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.
(/>/) :: forall (m :: Type -> Type) a x' x b' b a' c' c. 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'
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>)
(//>) :: forall (m :: Type -> Type) x' x b' b a' c' c. Functor 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 :: forall (m :: Type -> Type) a' a y' y. Functor 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.
(\>\) :: forall (m :: Type -> Type) b' a' a y' y b c' c. 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
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>)
(>\\) :: forall (m :: Type -> Type) b' a' a y' y b 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
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 :: forall (m :: Type -> Type) a a' r. Functor 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.
(>~>) :: forall (m :: Type -> Type) _a a' a b' b r c' c. 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
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>)
(>>~) :: forall (m :: Type -> Type) a' a b' b r c' c. Functor 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 :: forall (m :: Type -> Type) a' a r. Functor 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.
(>+>) :: forall (m :: Type -> Type) b' a' a b r _c' c' c. 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
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>)
(+>>) :: forall (m :: Type -> Type) b' a' a b r c' c. Functor 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 :: forall (m :: Type -> Type) a' a b' b r. Functor 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 :: Type -> Type) 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 :: Type -> Type) r = forall x' x. () => Proxy x' x () b m r

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

-- | Like <a>Client</a>, but with a polymorphic type
type Client' a' a (m :: Type -> Type) 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 :: Type -> Type) r = forall x' x. () => Proxy x' x b' b m r

-- | Equivalent to (<a>/&gt;/</a>) with the arguments flipped
(\<\) :: forall (m :: Type -> Type) b x' x c' c b' a a'. 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'
infixl 4 \<\

-- | Equivalent to (<a>\&gt;\</a>) with the arguments flipped
(/</) :: forall (m :: Type -> Type) c' b' b x' x c a' a. 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
infixr 5 /</

-- | Equivalent to (<a>&gt;~&gt;</a>) with the arguments flipped
(<~<) :: forall (m :: Type -> Type) b b' c' c r a a'. 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
infixl 8 <~<

-- | Equivalent to (<a>&gt;&gt;~</a>) with the arguments flipped
(~<<) :: forall (m :: Type -> Type) b b' c' c r a' a. Functor 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
(<+<) :: forall (m :: Type -> Type) c' b' b c r a' a. 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
infixr 7 <+<

-- | Equivalent to (<a>//&gt;</a>) with the arguments flipped
(<\\) :: forall (m :: Type -> Type) b x' x c' c b' a'. Functor 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
(//<) :: forall (m :: Type -> Type) b' b y' y c a' a. Functor 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
(<<+) :: forall (m :: Type -> Type) b' b c' c r a' a. Functor 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


-- | 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 :: Type -> Type) 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 :: Type -> Type) 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 :: Type -> Type) 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>Producer</a> a m ()
--   <a>yield</a> :: <a>Monad</a> m =&gt; a -&gt; <a>Pipe</a>   x a m ()
--   </pre>
yield :: forall (m :: Type -> Type) a x' x. Functor m => a -> Proxy x' x () 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>Functor</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>Functor</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>Functor</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>Functor</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 :: forall (m :: Type -> Type) x' x b' b a' c' c. Functor 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>Functor</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>Functor</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>Functor</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>Functor</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>.
(~>) :: forall (m :: Type -> Type) a x' x b' b a' c' c. 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'
infixr 4 ~>

-- | (<a>~&gt;</a>) with the arguments flipped
(<~) :: forall (m :: Type -> Type) b x' x c' c b' a a'. 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'
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 :: Type -> Type) r = forall y' y. () => Proxy () a y' y m r

-- | Consume a value
--   
--   <pre>
--   <a>await</a> :: <a>Functor</a> m =&gt; <a>Pipe</a> a y m a
--   </pre>
await :: forall (m :: Type -> Type) a. Functor 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>Functor</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>Functor</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>Functor</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>Functor</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>.
(>~) :: forall (m :: Type -> Type) a' a y' y b c. Functor 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
(~<) :: forall (m :: Type -> Type) b y' y c a' a. Functor 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 :: forall (m :: Type -> Type) a r. Functor m => Pipe a a m r

-- | <a>Pipe</a> composition, analogous to the Unix pipe operator
--   
--   <pre>
--   (<a>&gt;-&gt;</a>) :: <a>Functor</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>Functor</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>Functor</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>Functor</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>.
(>->) :: forall (m :: Type -> Type) a' a b r c' c. Functor 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
(<-<) :: forall (m :: Type -> Type) b c' c r a' a. Functor 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
--   
--   The type variables signify:
--   
--   <ul>
--   <li><tt>m</tt> - The base monad</li>
--   <li><tt>a</tt> - The values that the computation <a>yield</a>s
--   throughout its execution</li>
--   </ul>
--   
--   For basic construction and composition of <a>ListT</a> computations,
--   much can be accomplished using common typeclass methods.
--   
--   <ul>
--   <li><a>return</a> corresponds to <a>yield</a>, yielding a single
--   value.</li>
--   <li>(<a>&gt;&gt;=</a>) corresponds to <a>for</a>, calling the second
--   computation once for each time the first computation
--   <a>yield</a>s.</li>
--   <li><a>mempty</a> neither <a>yield</a>s any values nor produces any
--   effects in the base monad.</li>
--   <li>(<a>&lt;&gt;</a>) sequences two computations, <a>yield</a>ing all
--   the values of the first followed by all the values of the second.</li>
--   <li><a>lift</a> converts an action in the base monad into a ListT
--   computation which performs the action and <a>yield</a>s a single
--   value.</li>
--   </ul>
--   
--   <a>ListT</a> is a newtype wrapper for <a>Producer</a>. You will likely
--   need to use <a>Select</a> and <a>enumerate</a> to convert back and
--   forth between these two types to take advantage of all the
--   <a>Producer</a>-related utilities that <a>Pipes.Prelude</a> has to
--   offer.
--   
--   <ul>
--   <li>To lift a plain list into a <a>ListT</a> computation, first apply
--   <a>each</a> to turn the list into a <a>Producer</a>. Then apply the
--   <a>Select</a> constructor to convert from <a>Producer</a> to
--   <a>ListT</a>.</li>
--   <li>For other ways to construct <a>ListT</a> computations, see the
--   “Producers” section in <a>Pipes.Prelude</a> to build <a>Producer</a>s.
--   These can then be converted to <a>ListT</a> using <a>Select</a>.</li>
--   <li>To aggregate the values from a <a>ListT</a> computation (for
--   example, to compute the sum of a <a>ListT</a> of numbers), first apply
--   <a>enumerate</a> to obtain a <a>Producer</a>. Then see the “Folds”
--   section in <a>Pipes.Prelude</a> to proceed.</li>
--   </ul>
newtype ListT (m :: Type -> Type) a
Select :: Producer a m () -> ListT (m :: Type -> Type) a
[enumerate] :: ListT (m :: Type -> Type) 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 :: Type -> Type -> Type -> Type)
toListT :: forall (m :: Type -> Type) a. (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>
--   
--   <pre>
--   <a>each</a> :: (<a>Functor</a> m, <a>Foldable</a> f) =&gt; f a -&gt; <a>Producer</a> a m ()
--   </pre>
each :: forall (m :: Type -> Type) f a x' x. (Functor m, Foldable f) => f a -> Proxy x' x () a m ()

-- | Convert an <a>Enumerable</a> to a <a>Producer</a>
--   
--   <pre>
--   <a>every</a> :: (<a>Monad</a> m, <a>Enumerable</a> t) =&gt; t m a -&gt; <a>Producer</a> a m ()
--   </pre>
every :: forall (m :: Type -> Type) t a x' x. (Monad m, Enumerable t) => t m a -> Proxy x' x () a m ()

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

-- | <tt><a>void</a> value</tt> discards or ignores the result of
--   evaluation, such as the return value of an <a>IO</a> action.
--   
--   <h4><b>Examples</b></h4>
--   
--   Replace the contents of a <tt><a>Maybe</a> <a>Int</a></tt> with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void Nothing
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; void (Just 3)
--   Just ()
--   </pre>
--   
--   Replace the contents of an <tt><a>Either</a> <a>Int</a>
--   <a>Int</a></tt> with unit, resulting in an <tt><a>Either</a>
--   <a>Int</a> <tt>()</tt></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; void (Left 8675309)
--   Left 8675309
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; void (Right 8675309)
--   Right ()
--   </pre>
--   
--   Replace every element of a list with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void [1,2,3]
--   [(),(),()]
--   </pre>
--   
--   Replace the second element of a pair with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void (1,2)
--   (1,())
--   </pre>
--   
--   Discard the result of an <a>IO</a> action:
--   
--   <pre>
--   &gt;&gt;&gt; mapM print [1,2]
--   1
--   2
--   [(),()]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; void $ mapM print [1,2]
--   1
--   2
--   </pre>
void :: Functor f => f a -> f ()

-- | Monads that also support choice and failure.
class (Alternative m, Monad m) => MonadPlus (m :: Type -> Type)

-- | The identity of <a>mplus</a>. It should also satisfy the equations
--   
--   <pre>
--   mzero &gt;&gt;= f  =  mzero
--   v &gt;&gt; mzero   =  mzero
--   </pre>
--   
--   The default definition is
--   
--   <pre>
--   mzero = <a>empty</a>
--   </pre>
mzero :: MonadPlus m => m a

-- | An associative operation. The default definition is
--   
--   <pre>
--   mplus = (<a>&lt;|&gt;</a>)
--   </pre>
mplus :: MonadPlus m => m a -> m a -> m a

-- | A monad in the category of monads, using <a>lift</a> from
--   <a>MonadTrans</a> as the analog of <a>return</a> and <a>embed</a> as
--   the analog of (<a>=&lt;&lt;</a>):
--   
--   <pre>
--   embed lift = id
--   
--   embed f (lift m) = f m
--   
--   embed g (embed f t) = embed (\m -&gt; embed g (f m)) t
--   </pre>
class (MFunctor t, MonadTrans t) => MMonad (t :: Type -> Type -> Type -> Type)

-- | Embed a newly created <a>MMonad</a> layer within an existing layer
--   
--   <a>embed</a> is analogous to (<a>=&lt;&lt;</a>)
embed :: forall (n :: Type -> Type) m b. (MMonad t, Monad n) => (forall a. () => m a -> t n a) -> t m b -> t n b

-- | A functor in the category of monads, using <a>hoist</a> as the analog
--   of <a>fmap</a>:
--   
--   <pre>
--   hoist (f . g) = hoist f . hoist g
--   
--   hoist id = id
--   </pre>
class MFunctor (t :: Type -> Type -> k -> Type)

-- | Lift a monad morphism from <tt>m</tt> to <tt>n</tt> into a monad
--   morphism from <tt>(t m)</tt> to <tt>(t n)</tt>
--   
--   The first argument to <a>hoist</a> must be a monad morphism, even
--   though the type system does not enforce this
hoist :: forall m n (b :: k). (MFunctor t, Monad m) => (forall a. () => m a -> n a) -> t m b -> t n b

-- | The Foldable class represents data structures that can be reduced to a
--   summary value one element at a time. Strict left-associative folds are
--   a good fit for space-efficient reduction, while lazy right-associative
--   folds are a good fit for corecursive iteration, or for folds that
--   short-circuit after processing an initial subsequence of the
--   structure's elements.
--   
--   Instances can be derived automatically by enabling the
--   <tt>DeriveFoldable</tt> extension. For example, a derived instance for
--   a binary tree might be:
--   
--   <pre>
--   {-# LANGUAGE DeriveFoldable #-}
--   data Tree a = Empty
--               | Leaf a
--               | Node (Tree a) a (Tree a)
--       deriving Foldable
--   </pre>
--   
--   A more detailed description can be found in the <b>Overview</b>
--   section of <a>Data.Foldable#overview</a>.
--   
--   For the class laws see the <b>Laws</b> section of
--   <a>Data.Foldable#laws</a>.
class Foldable (t :: Type -> Type)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Alternative (Pipes.ListT m)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Applicative (Pipes.ListT m)
instance Pipes.Enumerable (Control.Monad.Trans.Except.ExceptT e)
instance Pipes.Enumerable Control.Monad.Trans.Identity.IdentityT
instance Pipes.Enumerable Pipes.ListT
instance Pipes.Enumerable Control.Monad.Trans.Maybe.MaybeT
instance GHC.Internal.Data.Foldable.Foldable m => GHC.Internal.Data.Foldable.Foldable (Pipes.ListT m)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Functor (Pipes.ListT m)
instance Control.Monad.Morph.MFunctor Pipes.ListT
instance Control.Monad.Morph.MMonad Pipes.ListT
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Pipes.ListT m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Pipes.ListT m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Control.Monad.Fail.MonadFail (Pipes.ListT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Pipes.ListT m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.Monad (Pipes.ListT m)
instance GHC.Internal.Base.Monad m => GHC.Internal.Base.MonadPlus (Pipes.ListT m)
instance Control.Monad.Reader.Class.MonadReader i m => Control.Monad.Reader.Class.MonadReader i (Pipes.ListT m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Pipes.ListT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Pipes.ListT m)
instance Control.Monad.Trans.Class.MonadTrans Pipes.ListT
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Pipes.ListT m)
instance GHC.Internal.Base.Monad m => Control.Monad.Zip.MonadZip (Pipes.ListT m)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Monoid (Pipes.ListT m a)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Semigroup (Pipes.ListT m a)
instance (GHC.Internal.Base.Functor m, GHC.Internal.Data.Traversable.Traversable m) => GHC.Internal.Data.Traversable.Traversable (Pipes.ListT m)


-- | 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 :: forall (m :: Type -> Type) t a' a b' b r. (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 :: forall (m :: Type -> Type) a' a b' b e r. 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 :: forall (m :: Type -> Type) a' a b' b e r. 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 :: forall (m :: Type -> Type) a' a b' b e r. 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 :: forall (m :: Type -> Type) a' a b' b r. 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 :: forall (m :: Type -> Type) a' a b' b r. 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 :: forall (m :: Type -> Type) i a' a b' b r. 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 :: forall (m :: Type -> Type) i a' a b' b r. 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 :: forall (m :: Type -> Type) s a' a b' b r. 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 :: forall (m :: Type -> Type) s a' a b' b r. 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 :: forall (m :: Type -> Type) s a' a b' b r. 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 :: forall (m :: Type -> Type) s a' a b' b r. 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 :: forall (m :: Type -> Type) w a' a b' b r. (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 :: forall (m :: Type -> Type) w a' a b' b r. (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 :: forall (m :: Type -> Type) w a' a b' b r. (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 :: forall (m :: Type -> Type) w i s a' a b' b r. (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 :: forall (m :: Type -> Type) w r s a' a b' b d. (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 :: forall (m :: Type -> Type) w r s a' a b' b d. (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 :: forall (m :: Type -> Type) w r s a' a b' b d. (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)


-- | 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 :: forall (m :: Type -> Type). MonadIO m => Producer' String m ()

-- | <a>read</a> values from <a>stdin</a>, ignoring failed parses
readLn :: forall (m :: Type -> Type) a. (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
--   
--   <pre>
--   <a>fromHandle</a> :: <a>MonadIO</a> m =&gt; <a>Handle</a> -&gt; <a>Producer</a> <a>String</a> m ()
--   </pre>
fromHandle :: forall (m :: Type -> Type) x' x. MonadIO m => Handle -> Proxy x' x () String m ()

-- | Repeat a monadic action indefinitely, <a>yield</a>ing each result
--   
--   <a>repeatM</a> :: <a>Monad</a> m =&gt; m a -&gt; <a>Producer</a> a m r
repeatM :: Monad m => m a -> Proxy x' x () 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>
--   
--   <pre>
--   <a>replicateM</a> :: <a>Monad</a> m =&gt; Int -&gt; m a -&gt; <a>Producer</a> a m ()
--   </pre>
replicateM :: Monad m => Int -> m a -> Proxy x' x () 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 :: forall (m :: Type -> Type). 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' :: forall (m :: Type -> Type) r. 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 :: forall (m :: Type -> Type) a r. (MonadIO m, Show a) => Consumer' a m r

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

-- | <a>discard</a> all incoming values
drain :: forall (m :: Type -> Type) a r. Functor 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 :: forall (m :: Type -> Type) a b r. Functor 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 :: forall (m :: Type -> Type) t a b r. (Functor 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
--   
--   filter f = mapMaybe (\a -&gt; a &lt;$ guard (f a))
--   </pre>
filter :: forall (m :: Type -> Type) a r. Functor m => (a -> Bool) -> Pipe a a m r

-- | <tt>(mapMaybe f)</tt> yields <a>Just</a> results of <tt>f</tt>.
--   
--   Basic laws:
--   
--   <pre>
--   mapMaybe (f &gt;=&gt; g) = mapMaybe f &gt;-&gt; mapMaybe g
--   
--   mapMaybe (pure @Maybe . f) = mapMaybe (Just . f) = map f
--   
--   mapMaybe (const Nothing) = drain
--   </pre>
--   
--   As a result of the second law,
--   
--   <pre>
--   mapMaybe return = mapMaybe Just = cat
--   </pre>
mapMaybe :: forall (m :: Type -> Type) a b r. Functor m => (a -> Maybe b) -> Pipe a b 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
--   
--   filterM f = wither (\a -&gt; (\b -&gt; a &lt;$ guard b) &lt;$&gt; f a)
--   </pre>
filterM :: Monad m => (a -> m Bool) -> Pipe a a m r

-- | <tt>(wither f)</tt> forwards <a>Just</a> values produced by the
--   monadic action.
--   
--   Basic laws:
--   
--   <pre>
--   wither (runMaybeT . (MaybeT . f &gt;=&gt; MaybeT . g)) = wither f &gt;-&gt; wither g
--   
--   wither (runMaybeT . lift . f) = wither (fmap Just . f) = mapM f
--   
--   wither (pure . f) = mapMaybe f
--   </pre>
--   
--   As a result of the second law,
--   
--   <pre>
--   wither (runMaybeT . return) = cat
--   </pre>
--   
--   As a result of the third law,
--   
--   <pre>
--   wither (pure . const Nothing) = wither (const (pure Nothing)) = drain
--   </pre>
wither :: Monad m => (a -> m (Maybe b)) -> Pipe a b 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 :: forall (m :: Type -> Type) a. Functor 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 :: forall (m :: Type -> Type) a. Functor 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' :: forall (m :: Type -> Type) a. Functor 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 :: forall (m :: Type -> Type) a r. Functor 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 :: forall (m :: Type -> Type) a r. Functor m => (a -> Bool) -> Pipe a a m r

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

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

-- | Outputs the indices of all elements that satisfied the predicate
findIndices :: forall (m :: Type -> Type) a r. Functor 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 :: forall (m :: Type -> Type) x a b r. Functor m => (x -> a -> x) -> x -> (x -> b) -> Pipe a b m r

-- | Strict, monadic left scan
--   
--   <pre>
--   Control.Foldl.impurely scanM :: Monad m =&gt; FoldM m a 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 :: forall (m :: Type -> Type) a r. (Functor m, Read a) => Pipe String a m r

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

-- | Evaluate all values flowing downstream to WHNF
seq :: forall (m :: Type -> Type) a r. Functor 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 :: forall (m :: Type -> Type) a b r. 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 :: forall (m :: Type -> Type) a r b x' x. Monad m => Producer a m r -> Producer b m r -> Proxy x' x () (a, b) m r

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

-- | Transform a <a>Consumer</a> to a <a>Pipe</a> that reforwards all
--   values further downstream
tee :: forall (m :: Type -> Type) a r. 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 :: forall (m :: Type -> Type) a b r x. 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
