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


-- | Streaming data processing library.
--   
--   <tt>conduit</tt> is a solution to the streaming data problem, allowing
--   for production, transformation, and consumption of streams of data in
--   constant memory. It is an alternative to lazy I/O which guarantees
--   deterministic resource handling, and fits in the same general solution
--   space as <tt>enumerator</tt>/<tt>iteratee</tt> and <tt>pipes</tt>. For
--   a brief tutorial, please see the <a>Data.Conduit</a> module.
--   
--   Release history:
--   
--   <ul>
--   <li><i>1.0</i> Simplified the user-facing interface back to the
--   Source, Sink, and Conduit types, with Producer and Consumer for
--   generic code. Error messages have been simplified, and optional
--   leftovers and upstream terminators have been removed from the external
--   API. Some long-deprecated functions were finally removed.</li>
--   <li><i>0.5</i> The internals of the package are now separated to the
--   .Internal module, leaving only the higher-level interface in the
--   advertised API. Internally, switched to a <tt>Leftover</tt>
--   constructor and slightly tweaked the finalization semantics.</li>
--   <li><i>0.4</i> Inspired by the design of the pipes package: we now
--   have a single unified type underlying <tt>Source</tt>, <tt>Sink</tt>,
--   and <tt>Conduit</tt>. This type is named <tt>Pipe</tt>. There are type
--   synonyms provided for the other three types. Additionally,
--   <tt>BufferedSource</tt> is no longer provided. Instead, the
--   connect-and-resume operator, <tt>$$+</tt>, can be used for the same
--   purpose.</li>
--   <li><i>0.3</i> ResourceT has been greatly simplified, specialized for
--   IO, and moved into a separate package. Instead of hard-coding
--   ResourceT into the conduit datatypes, they can now live around any
--   monad. The Conduit datatype has been enhanced to better allow
--   generation of streaming output. The SourceResult, SinkResult, and
--   ConduitResult datatypes have been removed entirely.</li>
--   <li><i>0.2</i> Instead of storing state in mutable variables, we now
--   use CPS. A <tt>Source</tt> returns the next <tt>Source</tt>, and
--   likewise for <tt>Sink</tt>s and <tt>Conduit</tt>s. Not only does this
--   take better advantage of GHC's optimizations (about a 20% speedup),
--   but it allows some operations to have a reduction in algorithmic
--   complexity from exponential to linear. This also allowed us to remove
--   the <tt>Prepared</tt> set of types. Also, the <tt>State</tt> functions
--   (e.g., <tt>sinkState</tt>) use better constructors for return types,
--   avoiding the need for a dummy state on completion.</li>
--   <li><i>0.1</i> <tt>BufferedSource</tt> is now an abstract type, and
--   has a much more efficient internal representation. The result was a
--   41% speedup on microbenchmarks (note: do not expect speedups anywhere
--   near that in real usage). In general, we are moving towards
--   <tt>BufferedSource</tt> being a specific tool used internally as
--   needed, but using <tt>Source</tt> for all external APIs.</li>
--   <li><i>0.0</i> Initial release.</li>
--   </ul>
@package conduit
@version 1.0.0

module Data.Conduit.Internal

-- | The underlying datatype for all the types in this package. In has six
--   type parameters:
--   
--   <ul>
--   <li><i>l</i> is the type of values that may be left over from this
--   <tt>Pipe</tt>. A <tt>Pipe</tt> with no leftovers would use
--   <tt>Void</tt> here, and one with leftovers would use the same type as
--   the <i>i</i> parameter. Leftovers are automatically provided to the
--   next <tt>Pipe</tt> in the monadic chain.</li>
--   <li><i>i</i> is the type of values for this <tt>Pipe</tt>'s input
--   stream.</li>
--   <li><i>o</i> is the type of values for this <tt>Pipe</tt>'s output
--   stream.</li>
--   <li><i>u</i> is the result type from the upstream <tt>Pipe</tt>.</li>
--   <li><i>m</i> is the underlying monad.</li>
--   <li><i>r</i> is the result type.</li>
--   </ul>
--   
--   A basic intuition is that every <tt>Pipe</tt> produces a stream of
--   output values (<i>o</i>), and eventually indicates that this stream is
--   terminated by sending a result (<i>r</i>). On the receiving end of a
--   <tt>Pipe</tt>, these become the <i>i</i> and <i>u</i> parameters.
--   
--   Since 0.5.0
data Pipe l i o u m r

-- | Provide new output to be sent downstream. This constructor has three
--   fields: the next <tt>Pipe</tt> to be used, a finalization function,
--   and the output value.
HaveOutput :: (Pipe l i o u m r) -> (m ()) -> o -> Pipe l i o u m r

-- | Request more input from upstream. The first field takes a new input
--   value and provides a new <tt>Pipe</tt>. The second takes an upstream
--   result value, which indicates that upstream is producing no more
--   results.
NeedInput :: (i -> Pipe l i o u m r) -> (u -> Pipe l i o u m r) -> Pipe l i o u m r

-- | Processing with this <tt>Pipe</tt> is complete, providing the final
--   result.
Done :: r -> Pipe l i o u m r

-- | Require running of a monadic action to get the next <tt>Pipe</tt>.
PipeM :: (m (Pipe l i o u m r)) -> Pipe l i o u m r

-- | Return leftover input, which should be provided to future operations.
Leftover :: (Pipe l i o u m r) -> l -> Pipe l i o u m r
newtype ConduitM i o m r
ConduitM :: Pipe i i o () m r -> ConduitM i o m r
unConduitM :: ConduitM i o m r -> Pipe i i o () m r

-- | Provides a stream of output values, without consuming any input or
--   producing a final result.
--   
--   Since 0.5.0
type Source m o = ConduitM () o m ()

-- | Generalized <a>Source</a>.
--   
--   Since 0.5.0
type Producer m o = forall i. ConduitM i o m ()

-- | Consumes a stream of input values and produces a final result, without
--   producing any output.
--   
--   Since 0.5.0
type Sink i m r = ConduitM i Void m r

-- | Generalized <a>Sink</a> without leftovers.
--   
--   Since 0.5.0
type Consumer i m r = forall o. ConduitM i o m r

-- | Consumes a stream of input values and produces a stream of output
--   values, without producing a final result.
--   
--   Since 0.5.0
type Conduit i m o = ConduitM i o m ()

-- | A <tt>Source</tt> which has been started, but has not yet completed.
--   
--   This type contains both the current state of the <tt>Source</tt>, and
--   the finalizer to be run to close it.
--   
--   Since 0.5.0
data ResumableSource m o
ResumableSource :: (Source m o) -> (m ()) -> ResumableSource m o

-- | Wait for a single input value from upstream, terminating immediately
--   if no data is available.
--   
--   Since 0.5.0
await :: Pipe l i o u m (Maybe i)

-- | This is similar to <tt>await</tt>, but will return the upstream result
--   value as <tt>Left</tt> if available.
--   
--   Since 0.5.0
awaitE :: Pipe l i o u m (Either u i)

-- | Wait for input forever, calling the given inner <tt>Pipe</tt> for each
--   piece of new input. Returns the upstream result type.
--   
--   Since 0.5.0
awaitForever :: Monad m => (i -> Pipe l i o r m r') -> Pipe l i o r m r

-- | Send a single output value downstream. If the downstream <tt>Pipe</tt>
--   terminates, this <tt>Pipe</tt> will terminate as well.
--   
--   Since 0.5.0
yield :: Monad m => o -> Pipe l i o u m ()

-- | Similar to <tt>yield</tt>, but additionally takes a finalizer to be
--   run if the downstream <tt>Pipe</tt> terminates.
--   
--   Since 0.5.0
yieldOr :: Monad m => o -> m () -> Pipe l i o u m ()

-- | Provide a single piece of leftover input to be consumed by the next
--   pipe in the current monadic binding.
--   
--   <i>Note</i>: it is highly encouraged to only return leftover values
--   from input already consumed from upstream.
--   
--   Since 0.5.0
leftover :: l -> Pipe l i o u m ()

-- | Perform some allocation and run an inner <tt>Pipe</tt>. Two guarantees
--   are given about resource finalization:
--   
--   <ol>
--   <li>It will be <i>prompt</i>. The finalization will be run as early as
--   possible.</li>
--   <li>It is exception safe. Due to usage of <tt>resourcet</tt>, the
--   finalization will be run in the event of any exceptions.</li>
--   </ol>
--   
--   Since 0.5.0
bracketP :: MonadResource m => IO a -> (a -> IO ()) -> (a -> Pipe l i o u m r) -> Pipe l i o u m r

-- | Add some code to be run when the given <tt>Pipe</tt> cleans up.
--   
--   Since 0.4.1
addCleanup :: Monad m => (Bool -> m ()) -> Pipe l i o u m r -> Pipe l i o u m r

-- | The identity <tt>Pipe</tt>.
--   
--   Since 0.5.0
idP :: Monad m => Pipe l a a r m r

-- | Compose a left and right pipe together into a complete pipe. The left
--   pipe will be automatically closed when the right pipe finishes.
--   
--   Since 0.5.0
pipe :: Monad m => Pipe l a b r0 m r1 -> Pipe Void b c r1 m r2 -> Pipe l a c r0 m r2

-- | Same as <a>pipe</a>, but automatically applies <a>injectLeftovers</a>
--   to the right <tt>Pipe</tt>.
--   
--   Since 0.5.0
pipeL :: Monad m => Pipe l a b r0 m r1 -> Pipe b b c r1 m r2 -> Pipe l a c r0 m r2

-- | Connect a <tt>Source</tt> to a <tt>Sink</tt> until the latter closes.
--   Returns both the most recent state of the <tt>Source</tt> and the
--   result of the <tt>Sink</tt>.
--   
--   We use a <tt>ResumableSource</tt> to keep track of the most recent
--   finalizer provided by the <tt>Source</tt>.
--   
--   Since 0.5.0
connectResume :: Monad m => ResumableSource m o -> Sink o m r -> m (ResumableSource m o, r)

-- | Run a pipeline until processing completes.
--   
--   Since 0.5.0
runPipe :: Monad m => Pipe Void () Void () m r -> m r

-- | Transforms a <tt>Pipe</tt> that provides leftovers to one which does
--   not, allowing it to be composed.
--   
--   This function will provide any leftover values within this
--   <tt>Pipe</tt> to any calls to <tt>await</tt>. If there are more
--   leftover values than are demanded, the remainder are discarded.
--   
--   Since 0.5.0
injectLeftovers :: Monad m => Pipe i i o u m r -> Pipe l i o u m r
(>+>) :: Monad m => Pipe l a b r0 m r1 -> Pipe Void b c r1 m r2 -> Pipe l a c r0 m r2

-- | Same as <a>&gt;+&gt;</a>, but reverse the order of the arguments.
--   
--   Since 0.5.0
(<+<) :: Monad m => Pipe Void b c r1 m r2 -> Pipe l a b r0 m r1 -> Pipe l a c r0 m r2
sourceToPipe :: Monad m => Source m o -> Pipe l i o u m ()
sinkToPipe :: Monad m => Sink i m r -> Pipe l i o u m r
conduitToPipe :: Monad m => Conduit i m o -> Pipe l i o u m ()

-- | Convert a <a>Source</a> into a <a>Producer</a>.
--   
--   Since 1.0.0
toProducer :: Monad m => Source m a -> Producer m a

-- | Convert a <a>Sink</a> into a <a>Consumer</a>.
--   
--   Since 1.0.0
toConsumer :: Monad m => Sink a m b -> Consumer a m b

-- | Transform the monad that a <tt>Pipe</tt> lives in.
--   
--   Note that the monad transforming function will be run multiple times,
--   resulting in unintuitive behavior in some cases. For a fuller
--   treatment, please see:
--   
--   
--   <a>https://github.com/snoyberg/conduit/wiki/Dealing-with-monad-transformers</a>
--   
--   Since 0.4.0
transPipe :: Monad m => (forall a. m a -> n a) -> Pipe l i o u m r -> Pipe l i o u n r

-- | Apply a function to all the output values of a <tt>Pipe</tt>.
--   
--   This mimics the behavior of <a>fmap</a> for a <a>Source</a> and
--   <a>Conduit</a> in pre-0.4 days.
--   
--   Since 0.4.1
mapOutput :: Monad m => (o1 -> o2) -> Pipe l i o1 u m r -> Pipe l i o2 u m r

-- | Same as <a>mapOutput</a>, but use a function that returns
--   <tt>Maybe</tt> values.
--   
--   Since 0.5.0
mapOutputMaybe :: Monad m => (o1 -> Maybe o2) -> Pipe l i o1 u m r -> Pipe l i o2 u m r

-- | Apply a function to all the input values of a <tt>Pipe</tt>.
--   
--   Since 0.5.0
mapInput :: Monad m => (i1 -> i2) -> (l2 -> Maybe l1) -> Pipe l2 i2 o u m r -> Pipe l1 i1 o u m r

-- | Convert a list into a source.
--   
--   Since 0.3.0
sourceList :: Monad m => [a] -> Pipe l i a u m ()

-- | Returns a tuple of the upstream and downstream results. Note that this
--   will force consumption of the entire input stream.
--   
--   Since 0.5.0
withUpstream :: Monad m => Pipe l i o u m r -> Pipe l i o u m (u, r)

-- | Unwraps a <tt>ResumableSource</tt> into a <tt>Source</tt> and a
--   finalizer.
--   
--   A <tt>ResumableSource</tt> represents a <tt>Source</tt> which has
--   already been run, and therefore has a finalizer registered. As a
--   result, if we want to turn it into a regular <tt>Source</tt>, we need
--   to ensure that the finalizer will be run appropriately. By
--   appropriately, I mean:
--   
--   <ul>
--   <li>If a new finalizer is registered, the old one should not be
--   called. * If the old one is called, it should not be called
--   again.</li>
--   </ul>
--   
--   This function returns both a <tt>Source</tt> and a finalizer which
--   ensures that the above two conditions hold. Once you call that
--   finalizer, the <tt>Source</tt> is invalidated and cannot be used.
--   
--   Since 0.5.2
unwrapResumable :: MonadIO m => ResumableSource m o -> m (Source m o, m ())
instance Monad m => Functor (ConduitM i o m)
instance Monad m => Applicative (ConduitM i o m)
instance Monad m => Monad (ConduitM i o m)
instance MonadIO m => MonadIO (ConduitM i o m)
instance MonadTrans (ConduitM i o)
instance MonadThrow m => MonadThrow (ConduitM i o m)
instance MonadActive m => MonadActive (ConduitM i o m)
instance MonadResource m => MonadResource (ConduitM i o m)
instance Monad m => Monoid (ConduitM i o m ())
instance MonadBase base m => MonadBase base (ConduitM i o m)
instance MonadResource m => MonadResource (Pipe l i o u m)
instance Monad m => Monoid (Pipe l i o u m ())
instance MonadActive m => MonadActive (Pipe l i o u m)
instance MonadThrow m => MonadThrow (Pipe l i o u m)
instance MonadIO m => MonadIO (Pipe l i o u m)
instance MonadTrans (Pipe l i o u)
instance MonadBase base m => MonadBase base (Pipe l i o u m)
instance Monad m => Monad (Pipe l i o u m)
instance Monad m => Applicative (Pipe l i o u m)
instance Monad m => Functor (Pipe l i o u m)


-- | Utility functions from older versions of <tt>conduit</tt>. These
--   should be considered deprecated, as there are now easier ways to
--   handle their use cases. This module is provided solely for backwards
--   compatibility.
module Data.Conduit.Util

-- | Combines two sources. The new source will stop producing once either
--   source has been exhausted.
--   
--   Since 0.3.0
zip :: Monad m => Source m a -> Source m b -> Source m (a, b)

-- | Combines two sinks. The new sink will complete when both input sinks
--   have completed.
--   
--   Any leftovers are discarded.
--   
--   Since 0.4.1
zipSinks :: Monad m => Sink i m r -> Sink i m r' -> Sink i m (r, r')


-- | Let's start off with a few simple examples of <tt>conduit</tt> usage.
--   First, a file copy utility:
--   
--   <pre>
--   &gt;&gt;&gt; :load Data.Conduit.Binary
--   
--   &gt;&gt;&gt; runResourceT $ sourceFile "input.txt" $$ sinkFile "output.txt"
--   </pre>
--   
--   <tt>runResourceT</tt> is a function provided by the <tt>resourcet</tt>
--   package, and ensures that resources are properly cleaned up, even in
--   the presence of exceptions. The type system will enforce that
--   <tt>runResourceT</tt> is called as needed. The remainder of this
--   tutorial will not discuss <tt>runResourceT</tt>; please see the
--   documentation in <tt>resourcet</tt> for more information.
--   
--   Looking at the rest of our example, there are three components to
--   understand: <tt>sourceFile</tt>, <tt>sinkFile</tt>, and the
--   <tt>$$</tt> operator (called "connect"). These represent the most
--   basic building blocks in <tt>conduit</tt>: a <tt>Source</tt> produces
--   a stream of values, a <tt>Sink</tt> consumes such a stream, and
--   <tt>$$</tt> will combine these together.
--   
--   In the case of file copying, there was no value produced by the
--   <tt>Sink</tt>. However, often times a <tt>Sink</tt> will produce some
--   result value. For example:
--   
--   <pre>
--   &gt;&gt;&gt; :load Data.Conduit.List
--   
--   &gt;&gt;&gt; :module +Prelude
--   
--   &gt;&gt;&gt; sourceList [1..10] $$ fold (+) 0
--   55
--   </pre>
--   
--   <tt>sourceList</tt> is a convenience function for turning a list into
--   a <tt>Source</tt>. <tt>fold</tt> implements a strict left fold for
--   consuming the input stream.
--   
--   The next major aspect to the <tt>conduit</tt> library is the
--   <tt>Conduit</tt> type. This type represents a stream
--   <i>transformer</i>. In order to use a <tt>Conduit</tt>, we must
--   <i>fuse</i> it with either a <tt>Source</tt> or <tt>Sink</tt>. For
--   example:
--   
--   <pre>
--   &gt;&gt;&gt; :load Data.Conduit.List
--   
--   &gt;&gt;&gt; :module +Prelude
--   
--   &gt;&gt;&gt; sourceList [1..10] $= Data.Conduit.List.map (+1) $$ consume
--   [2,3,4,5,6,7,8,9,10,11]
--   </pre>
--   
--   Notice the addition of the <tt>$=</tt>, or <i>left fuse</i> operator.
--   This combines a <tt>Source</tt> and a <tt>Conduit</tt> into a new
--   <tt>Source</tt>, which can then be connected to a <tt>Sink</tt> (in
--   this case, <tt>consume</tt>). We can similarly perform <i>right
--   fusion</i> to combine a <tt>Conduit</tt> and <tt>Sink</tt>, or
--   <i>middle fusion</i> to combine two <tt>Conduit</tt>s.
--   
--   A number of very common functions are provided in the
--   <a>Data.Conduit.List</a> module. Many of these functions correspond
--   very closely to standard Haskell functions.
--   
--   In addition to connecting and fusing components together, we can also
--   build up more sophisticated components through monadic composition.
--   For example, to create a <tt>Sink</tt> that ignores the first 3
--   numbers and returns the sum of the remaining numbers, we can use:
--   
--   <pre>
--   &gt;&gt;&gt; :load Data.Conduit.List
--   
--   &gt;&gt;&gt; :module +Prelude
--   
--   &gt;&gt;&gt; sourceList [1..10] $$ Data.Conduit.List.drop 3 &gt;&gt; fold (+) 0
--   49
--   </pre>
--   
--   In some cases, we might end up consuming more input than we needed,
--   and want to provide that input to the next component in our monadic
--   chain. We refer to this as <i>leftovers</i>. The simplest example of
--   this is <tt>peek</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; :load Data.Conduit.List
--   
--   &gt;&gt;&gt; :set -XNoMonomorphismRestriction
--   
--   &gt;&gt;&gt; :module +Prelude
--   
--   &gt;&gt;&gt; let sink = do { first &lt;- peek; total &lt;- fold (+) 0; return (first, total) }
--   
--   &gt;&gt;&gt; sourceList [1..10] $$ sink
--   (Just 1,55)
--   </pre>
--   
--   Notice that, although we "consumed" the first value from the stream
--   via <tt>peek</tt>, it was still available to <tt>fold</tt>. This idea
--   becomes even more important when dealing with chunked data such as
--   <tt>ByteString</tt>s or <tt>Text</tt>.
--   
--   <i>Final note</i>: Notice in the types below that <tt>Source</tt>,
--   <tt>Sink</tt>, and <tt>Conduit</tt> are just type aliases. This will
--   be explained later. Another important aspect is resource finalization,
--   which will also be covered below.
module Data.Conduit

-- | Provides a stream of output values, without consuming any input or
--   producing a final result.
--   
--   Since 0.5.0
type Source m o = ConduitM () o m ()

-- | Consumes a stream of input values and produces a stream of output
--   values, without producing a final result.
--   
--   Since 0.5.0
type Conduit i m o = ConduitM i o m ()

-- | Consumes a stream of input values and produces a final result, without
--   producing any output.
--   
--   Since 0.5.0
type Sink i m r = ConduitM i Void m r

-- | The connect operator, which pulls data from a source and pushes to a
--   sink. When either side closes, the other side will immediately be
--   closed as well. If you would like to keep the <tt>Source</tt> open to
--   be used for another operations, use the connect-and-resume operator
--   <a>$$+</a>.
--   
--   Since 0.4.0
($$) :: Monad m => Source m a -> Sink a m b -> m b

-- | Left fuse, combining a source and a conduit together into a new
--   source.
--   
--   Both the <tt>Source</tt> and <tt>Conduit</tt> will be closed when the
--   newly-created <tt>Source</tt> is closed.
--   
--   Leftover data from the <tt>Conduit</tt> will be discarded.
--   
--   Since 0.4.0
($=) :: Monad m => Source m a -> Conduit a m b -> Source m b

-- | Right fuse, combining a conduit and a sink together into a new sink.
--   
--   Both the <tt>Conduit</tt> and <tt>Sink</tt> will be closed when the
--   newly-created <tt>Sink</tt> is closed.
--   
--   Leftover data returned from the <tt>Sink</tt> will be discarded.
--   
--   Since 0.4.0
(=$) :: Monad m => Conduit a m b -> Sink b m c -> Sink a m c

-- | Fusion operator, combining two <tt>Conduit</tt>s together into a new
--   <tt>Conduit</tt>.
--   
--   Both <tt>Conduit</tt>s will be closed when the newly-created
--   <tt>Conduit</tt> is closed.
--   
--   Leftover data returned from the right <tt>Conduit</tt> will be
--   discarded.
--   
--   Since 0.4.0
(=$=) :: Monad m => Conduit a m b -> ConduitM b c m r -> ConduitM a c m r
await :: Monad m => Consumer i m (Maybe i)
awaitForever :: Monad m => (i -> ConduitM i o m r) -> ConduitM i o m ()
yield :: Monad m => o -> ConduitM i o m ()
yieldOr :: Monad m => o -> m () -> ConduitM i o m ()
leftover :: i -> ConduitM i o m ()
bracketP :: MonadResource m => IO a -> (a -> IO ()) -> (a -> ConduitM i o m r) -> ConduitM i o m r
addCleanup :: Monad m => (Bool -> m ()) -> ConduitM i o m r -> ConduitM i o m r

-- | A <tt>Source</tt> which has been started, but has not yet completed.
--   
--   This type contains both the current state of the <tt>Source</tt>, and
--   the finalizer to be run to close it.
--   
--   Since 0.5.0
data ResumableSource m o

-- | The connect-and-resume operator. This does not close the
--   <tt>Source</tt>, but instead returns it to be used again. This allows
--   a <tt>Source</tt> to be used incrementally in a large program, without
--   forcing the entire program to live in the <tt>Sink</tt> monad.
--   
--   Mnemonic: connect + do more.
--   
--   Since 0.5.0
($$+) :: Monad m => Source m a -> Sink a m b -> m (ResumableSource m a, b)

-- | Continue processing after usage of <tt>$$+</tt>.
--   
--   Since 0.5.0
($$++) :: Monad m => ResumableSource m a -> Sink a m b -> m (ResumableSource m a, b)

-- | Complete processing of a <tt>ResumableSource</tt>. This will run the
--   finalizer associated with the <tt>ResumableSource</tt>. In order to
--   guarantee process resource finalization, you <i>must</i> use this
--   operator after using <tt>$$+</tt> and <tt>$$++</tt>.
--   
--   Since 0.5.0
($$+-) :: Monad m => ResumableSource m a -> Sink a m b -> m b

-- | Unwraps a <tt>ResumableSource</tt> into a <tt>Source</tt> and a
--   finalizer.
--   
--   A <tt>ResumableSource</tt> represents a <tt>Source</tt> which has
--   already been run, and therefore has a finalizer registered. As a
--   result, if we want to turn it into a regular <tt>Source</tt>, we need
--   to ensure that the finalizer will be run appropriately. By
--   appropriately, I mean:
--   
--   <ul>
--   <li>If a new finalizer is registered, the old one should not be
--   called. * If the old one is called, it should not be called
--   again.</li>
--   </ul>
--   
--   This function returns both a <tt>Source</tt> and a finalizer which
--   ensures that the above two conditions hold. Once you call that
--   finalizer, the <tt>Source</tt> is invalidated and cannot be used.
--   
--   Since 0.5.2
unwrapResumable :: MonadIO m => ResumableSource m o -> m (Source m o, m ())
transPipe :: Monad m => (forall a. m a -> n a) -> ConduitM i o m r -> ConduitM i o n r
mapOutput :: Monad m => (o1 -> o2) -> ConduitM i o1 m r -> ConduitM i o2 m r
mapOutputMaybe :: Monad m => (o1 -> Maybe o2) -> ConduitM i o1 m r -> ConduitM i o2 m r
mapInput :: Monad m => (i1 -> i2) -> (i2 -> Maybe i1) -> ConduitM i2 o m r -> ConduitM i1 o m r

-- | Generalized <a>Source</a>.
--   
--   Since 0.5.0
type Producer m o = forall i. ConduitM i o m ()

-- | Generalized <a>Sink</a> without leftovers.
--   
--   Since 0.5.0
type Consumer i m r = forall o. ConduitM i o m r

-- | Convert a <a>Source</a> into a <a>Producer</a>.
--   
--   Since 1.0.0
toProducer :: Monad m => Source m a -> Producer m a

-- | Convert a <a>Sink</a> into a <a>Consumer</a>.
--   
--   Since 1.0.0
toConsumer :: Monad m => Sink a m b -> Consumer a m b

-- | Provide for a stream of data that can be flushed.
--   
--   A number of <tt>Conduit</tt>s (e.g., zlib compression) need the
--   ability to flush the stream at some point. This provides a single
--   wrapper datatype to be used in all such circumstances.
--   
--   Since 0.3.0
data Flush a
Chunk :: a -> Flush a
Flush :: Flush a

-- | The Resource transformer. This transformer keeps track of all
--   registered actions, and calls them upon exit (via
--   <a>runResourceT</a>). Actions may be registered via <a>register</a>,
--   or resources may be allocated atomically via <a>allocate</a>.
--   <tt>allocate</tt> corresponds closely to <tt>bracket</tt>.
--   
--   Releasing may be performed before exit via the <a>release</a>
--   function. This is a highly recommended optimization, as it will ensure
--   that scarce resources are freed early. Note that calling
--   <tt>release</tt> will deregister the action, so that a release action
--   will only ever be called once.
--   
--   Since 0.3.0
data ResourceT (m :: * -> *) a :: (* -> *) -> * -> *

-- | A <tt>Monad</tt> which allows for safe resource allocation. In theory,
--   any monad transformer stack included a <tt>ResourceT</tt> can be an
--   instance of <tt>MonadResource</tt>.
--   
--   Note: <tt>runResourceT</tt> has a requirement for a
--   <tt>MonadBaseControl IO m</tt> monad, which allows control operations
--   to be lifted. A <tt>MonadResource</tt> does not have this requirement.
--   This means that transformers such as <tt>ContT</tt> can be an instance
--   of <tt>MonadResource</tt>. However, the <tt>ContT</tt> wrapper will
--   need to be unwrapped before calling <tt>runResourceT</tt>.
--   
--   Since 0.3.0
class (MonadThrow m, MonadUnsafeIO m, MonadIO m, Applicative m) => MonadResource (m :: * -> *)

-- | A <tt>Monad</tt> which can throw exceptions. Note that this does not
--   work in a vanilla <tt>ST</tt> or <tt>Identity</tt> monad. Instead, you
--   should use the <a>ExceptionT</a> transformer in your stack if you are
--   dealing with a non-<tt>IO</tt> base monad.
--   
--   Since 0.3.0
class Monad m => MonadThrow (m :: * -> *)
monadThrow :: (MonadThrow m, Exception e) => e -> m a

-- | A <tt>Monad</tt> based on some monad which allows running of some
--   <a>IO</a> actions, via unsafe calls. This applies to <a>IO</a> and
--   <a>ST</a>, for instance.
--   
--   Since 0.3.0
class Monad m => MonadUnsafeIO (m :: * -> *)
unsafeLiftIO :: MonadUnsafeIO m => IO a -> m a

-- | Unwrap a <a>ResourceT</a> transformer, and call all registered release
--   actions.
--   
--   Note that there is some reference counting involved due to
--   <a>resourceForkIO</a>. If multiple threads are sharing the same
--   collection of resources, only the last call to <tt>runResourceT</tt>
--   will deallocate the resources.
--   
--   Since 0.3.0
runResourceT :: MonadBaseControl IO m => ResourceT m a -> m a

-- | The express purpose of this transformer is to allow
--   non-<tt>IO</tt>-based monad stacks to catch exceptions via the
--   <a>MonadThrow</a> typeclass.
--   
--   Since 0.3.0
newtype ExceptionT (m :: * -> *) a :: (* -> *) -> * -> *
ExceptionT :: m (Either SomeException a) -> ExceptionT a
runExceptionT :: ExceptionT a -> m (Either SomeException a)

-- | Same as <a>runExceptionT</a>, but immediately <a>throw</a> any
--   exception returned.
--   
--   Since 0.3.0
runExceptionT_ :: Monad m => ExceptionT m a -> m a

-- | Run an <tt>ExceptionT Identity</tt> stack.
--   
--   Since 0.4.2
runException :: ExceptionT Identity a -> Either SomeException a

-- | Run an <tt>ExceptionT Identity</tt> stack, but immediately
--   <a>throw</a> any exception returned.
--   
--   Since 0.4.2
runException_ :: ExceptionT Identity a -> a
class MonadBase b m => MonadBaseControl (b :: * -> *) (m :: * -> *) | m -> b
instance Show a => Show (Flush a)
instance Eq a => Eq (Flush a)
instance Ord a => Ord (Flush a)
instance Functor Flush


-- | Higher-level functions to interact with the elements of a stream. Most
--   of these are based on list functions.
--   
--   Note that these functions all deal with individual elements of a
--   stream as a sort of "black box", where there is no introspection of
--   the contained elements. Values such as <tt>ByteString</tt> and
--   <tt>Text</tt> will likely need to be treated specially to deal with
--   their contents properly (<tt>Word8</tt> and <tt>Char</tt>,
--   respectively). See the <a>Data.Conduit.Binary</a> and
--   <a>Data.Conduit.Text</a> modules.
module Data.Conduit.List
sourceList :: Monad m => [a] -> Producer m a

-- | A source that outputs no values. Note that this is just a
--   type-restricted synonym for <a>mempty</a>.
--   
--   Since 0.3.0
sourceNull :: Monad m => Producer m a

-- | Generate a source from a seed value.
--   
--   Since 0.4.2
unfold :: Monad m => (b -> Maybe (a, b)) -> b -> Producer m a

-- | Enumerate from a value to a final value, inclusive, via <a>succ</a>.
--   
--   This is generally more efficient than using <tt>Prelude</tt>'s
--   <tt>enumFromTo</tt> and combining with <tt>sourceList</tt> since this
--   avoids any intermediate data structures.
--   
--   Since 0.4.2
enumFromTo :: (Enum a, Eq a, Monad m) => a -> a -> Producer m a

-- | Produces an infinite stream of repeated applications of f to x.
iterate :: Monad m => (a -> a) -> a -> Producer m a

-- | A strict left fold.
--   
--   Since 0.3.0
fold :: Monad m => (b -> a -> b) -> b -> Consumer a m b

-- | A monoidal strict left fold.
--   
--   Since 0.5.3
foldMap :: (Monad m, Monoid b) => (a -> b) -> Consumer a m b

-- | Take some values from the stream and return as a list. If you want to
--   instead create a conduit that pipes data to another sink, see
--   <a>isolate</a>. This function is semantically equivalent to:
--   
--   <pre>
--   take i = isolate i =$ consume
--   </pre>
--   
--   Since 0.3.0
take :: Monad m => Int -> Consumer a m [a]

-- | Ignore a certain number of values in the stream. This function is
--   semantically equivalent to:
--   
--   <pre>
--   drop i = take i &gt;&gt; return ()
--   </pre>
--   
--   However, <tt>drop</tt> is more efficient as it does not need to hold
--   values in memory.
--   
--   Since 0.3.0
drop :: Monad m => Int -> Consumer a m ()

-- | Take a single value from the stream, if available.
--   
--   Since 0.3.0
head :: Monad m => Consumer a m (Maybe a)

-- | Look at the next value in the stream, if available. This function will
--   not change the state of the stream.
--   
--   Since 0.3.0
peek :: Monad m => Consumer a m (Maybe a)

-- | Consume all values from the stream and return as a list. Note that
--   this will pull all values into memory. For a lazy variant, see
--   <a>Data.Conduit.Lazy</a>.
--   
--   Since 0.3.0
consume :: Monad m => Consumer a m [a]

-- | Ignore the remainder of values in the source. Particularly useful when
--   combined with <a>isolate</a>.
--   
--   Since 0.3.0
sinkNull :: Monad m => Consumer a m ()

-- | A monadic strict left fold.
--   
--   Since 0.3.0
foldM :: Monad m => (b -> a -> m b) -> b -> Consumer a m b

-- | Apply the action to all values in the stream.
--   
--   Since 0.3.0
mapM_ :: Monad m => (a -> m ()) -> Consumer a m ()

-- | Apply a transformation to all values in a stream.
--   
--   Since 0.3.0
map :: Monad m => (a -> b) -> Conduit a m b

-- | Apply a transformation that may fail to all values in a stream,
--   discarding the failures.
--   
--   Since 0.5.1
mapMaybe :: Monad m => (a -> Maybe b) -> Conduit a m b

-- | Filter the <tt>Just</tt> values from a stream, discarding the
--   <tt>Nothing</tt> values.
--   
--   Since 0.5.1
catMaybes :: Monad m => Conduit (Maybe a) m a

-- | Apply a transformation to all values in a stream, concatenating the
--   output values.
--   
--   Since 0.3.0
concatMap :: Monad m => (a -> [b]) -> Conduit a m b

-- | <a>concatMap</a> with an accumulator.
--   
--   Since 0.3.0
concatMapAccum :: Monad m => (a -> accum -> (accum, [b])) -> accum -> Conduit a m b

-- | Grouping input according to an equality function.
--   
--   Since 0.3.0
groupBy :: Monad m => (a -> a -> Bool) -> Conduit a m [a]

-- | Ensure that the inner sink consumes no more than the given number of
--   values. Note this this does <i>not</i> ensure that the sink consumes
--   all of those values. To get the latter behavior, combine with
--   <a>sinkNull</a>, e.g.:
--   
--   <pre>
--   src $$ do
--       x &lt;- isolate count =$ do
--           x &lt;- someSink
--           sinkNull
--           return x
--       someOtherSink
--       ...
--   </pre>
--   
--   Since 0.3.0
isolate :: Monad m => Int -> Conduit a m a

-- | Keep only values in the stream passing a given predicate.
--   
--   Since 0.3.0
filter :: Monad m => (a -> Bool) -> Conduit a m a

-- | Apply a monadic transformation to all values in a stream.
--   
--   If you do not need the transformed values, and instead just want the
--   monadic side-effects of running the action, see <a>mapM_</a>.
--   
--   Since 0.3.0
mapM :: Monad m => (a -> m b) -> Conduit a m b

-- | Apply a monadic action on all values in a stream.
--   
--   This <tt>Conduit</tt> can be used to perform a monadic side-effect for
--   every value, whilst passing the value through the <tt>Conduit</tt>
--   as-is.
--   
--   <pre>
--   iterM f = mapM (\a -&gt; f a &gt;&gt;= \() -&gt; return a)
--   </pre>
--   
--   Since 0.5.6
iterM :: Monad m => (a -> m ()) -> Conduit a m a

-- | Apply a monadic transformation that may fail to all values in a
--   stream, discarding the failures.
--   
--   Since 0.5.1
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> Conduit a m b

-- | Apply a monadic transformation to all values in a stream,
--   concatenating the output values.
--   
--   Since 0.3.0
concatMapM :: Monad m => (a -> m [b]) -> Conduit a m b

-- | <a>concatMapM</a> with an accumulator.
--   
--   Since 0.3.0
concatMapAccumM :: Monad m => (a -> accum -> m (accum, [b])) -> accum -> Conduit a m b

-- | Run a <tt>Pipe</tt> repeatedly, and output its result value
--   downstream. Stops when no more input is available from upstream.
--   
--   Since 0.5.0
sequence :: Monad m => Consumer i m o -> Conduit i m o


-- | Functions for interacting with bytes.
module Data.Conduit.Binary

-- | Stream the contents of a file as binary data.
--   
--   Since 0.3.0
sourceFile :: MonadResource m => FilePath -> Producer m ByteString

-- | Stream the contents of a <a>Handle</a> as binary data. Note that this
--   function will <i>not</i> automatically close the <tt>Handle</tt> when
--   processing completes, since it did not acquire the <tt>Handle</tt> in
--   the first place.
--   
--   Since 0.3.0
sourceHandle :: MonadIO m => Handle -> Producer m ByteString

-- | An alternative to <a>sourceHandle</a>. Instead of taking a pre-opened
--   <a>Handle</a>, it takes an action that opens a <a>Handle</a> (in read
--   mode), so that it can open it only when needed and closed it as soon
--   as possible.
--   
--   Since 0.3.0
sourceIOHandle :: MonadResource m => IO Handle -> Producer m ByteString

-- | Stream the contents of a file as binary data, starting from a certain
--   offset and only consuming up to a certain number of bytes.
--   
--   Since 0.3.0
sourceFileRange :: MonadResource m => FilePath -> Maybe Integer -> Maybe Integer -> Producer m ByteString

-- | Stream all incoming data to the given file.
--   
--   Since 0.3.0
sinkFile :: MonadResource m => FilePath -> Consumer ByteString m ()

-- | Stream all incoming data to the given <a>Handle</a>. Note that this
--   function will <i>not</i> automatically close the <tt>Handle</tt> when
--   processing completes.
--   
--   Since 0.3.0
sinkHandle :: MonadIO m => Handle -> Consumer ByteString m ()

-- | An alternative to <a>sinkHandle</a>. Instead of taking a pre-opened
--   <a>Handle</a>, it takes an action that opens a <a>Handle</a> (in write
--   mode), so that it can open it only when needed and close it as soon as
--   possible.
--   
--   Since 0.3.0
sinkIOHandle :: MonadResource m => IO Handle -> Consumer ByteString m ()

-- | Stream the contents of the input to a file, and also send it along the
--   pipeline. Similar in concept to the Unix command <tt>tee</tt>.
--   
--   Since 0.3.0
conduitFile :: MonadResource m => FilePath -> Conduit ByteString m ByteString

-- | Stream the chunks from a lazy bytestring.
--   
--   Since 0.5.0
sourceLbs :: Monad m => ByteString -> Producer m ByteString

-- | Return the next byte from the stream, if available.
--   
--   Since 0.3.0
head :: Monad m => Consumer ByteString m (Maybe Word8)

-- | Ignore all bytes while the predicate returns <tt>True</tt>.
--   
--   Since 0.3.0
dropWhile :: Monad m => (Word8 -> Bool) -> Consumer ByteString m ()

-- | Take the given number of bytes, if available.
--   
--   Since 0.3.0
take :: Monad m => Int -> Consumer ByteString m ByteString

-- | Drop up to the given number of bytes.
--   
--   Since 0.5.0
drop :: Monad m => Int -> Consumer ByteString m ()

-- | Ensure that only up to the given number of bytes are consume by the
--   inner sink. Note that this does <i>not</i> ensure that all of those
--   bytes are in fact consumed.
--   
--   Since 0.3.0
isolate :: Monad m => Int -> Conduit ByteString m ByteString

-- | Return all bytes while the predicate returns <tt>True</tt>.
--   
--   Since 0.3.0
takeWhile :: Monad m => (Word8 -> Bool) -> Conduit ByteString m ByteString

-- | Split the input bytes into lines. In other words, split on the LF byte
--   (10), and strip it from the output.
--   
--   Since 0.3.0
lines :: Monad m => Conduit ByteString m ByteString


-- | Handle streams of text.
--   
--   Parts of this code were taken from enumerator and adapted for
--   conduits.
module Data.Conduit.Text

-- | A specific character encoding.
--   
--   Since 0.3.0
data Codec

-- | Convert text into bytes, using the provided codec. If the codec is not
--   capable of representing an input character, an exception will be
--   thrown.
--   
--   Since 0.3.0
encode :: MonadThrow m => Codec -> Conduit Text m ByteString

-- | Convert bytes into text, using the provided codec. If the codec is not
--   capable of decoding an input byte sequence, an exception will be
--   thrown.
--   
--   Since 0.3.0
decode :: MonadThrow m => Codec -> Conduit ByteString m Text

-- | Since 0.3.0
utf8 :: Codec

-- | Since 0.3.0
utf16_le :: Codec

-- | Since 0.3.0
utf16_be :: Codec

-- | Since 0.3.0
utf32_le :: Codec

-- | Since 0.3.0
utf32_be :: Codec

-- | Since 0.3.0
ascii :: Codec

-- | Since 0.3.0
iso8859_1 :: Codec

-- | Emit each line separately
--   
--   Since 0.4.1
lines :: Monad m => Conduit Text m Text
instance Typeable TextException
instance Show TextException
instance Exception TextException
instance Show Codec


-- | Use lazy I/O for consuming the contents of a source. Warning: All
--   normal warnings of lazy I/O apply. In particular, if you are using
--   this with a <tt>ResourceT</tt> transformer, you must force the list to
--   be evaluated before exiting the <tt>ResourceT</tt>.
module Data.Conduit.Lazy

-- | Use lazy I/O to consume all elements from a <tt>Source</tt>.
--   
--   This function relies on <a>monadActive</a> to determine if the
--   underlying monadic state has been closed.
--   
--   Since 0.3.0
lazyConsume :: (MonadBaseControl IO m, MonadActive m) => Source m a -> m [a]
