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


-- | Streaming data processing library.
--   
--   Conduits are an approach to the streaming data problem. It is meant as
--   an alternative to enumerators/iterators, hoping to address the same
--   issues with different trade-offs based on real-world experience with
--   enumerators. For more information, see
--   <a>http://www.yesodweb.com/book/conduits</a>.
--   
--   Release history:
--   
--   <ul>
--   <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 0.4.2

module Data.Conduit.Internal

-- | The underlying datatype for all the types in this package. In has four
--   type parameters:
--   
--   <ul>
--   <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>m</i> is the underlying monad.</li>
--   <li><i>r</i> is the result type.</li>
--   </ul>
--   
--   Note that <i>o</i> and <i>r</i> are inherently different. <i>o</i> is
--   the type of the stream of values this <tt>Pipe</tt> will produce and
--   send downstream. <i>r</i> is the final output of this <tt>Pipe</tt>.
--   
--   <tt>Pipe</tt>s can be composed via the <a>pipe</a> function. To do so,
--   the output type of the left pipe much match the input type of the left
--   pipe, and the result type of the left pipe must be unit <tt>()</tt>.
--   This is due to the fact that any result produced by the left pipe must
--   be discarded in favor of the result of the right pipe.
--   
--   Since 0.4.0
data Pipe i o m r

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

-- | Request more input from upstream. The first field takes a new input
--   value and provides a new <tt>Pipe</tt>. The second is for early
--   termination. It gives a new <tt>Pipe</tt> which takes no input from
--   upstream. This allows a <tt>Pipe</tt> to provide a final stream of
--   output values after no more input is available from upstream.
NeedInput :: (i -> Pipe i o m r) -> (Pipe i o m r) -> Pipe i o m r

-- | Processing with this <tt>Pipe</tt> is complete. Provides an optional
--   leftover input value and and result.
Done :: (Maybe i) -> r -> Pipe i o m r

-- | Require running of a monadic action to get the next <tt>Pipe</tt>.
--   Second field is an early cleanup function. Technically, this second
--   field could be skipped, but doing so would require extra operations to
--   be performed in some cases. For example, for a <tt>Pipe</tt> pulling
--   data from a file, it may be forced to pull an extra, unneeded chunk
--   before closing the <tt>Handle</tt>.
PipeM :: (m (Pipe i o m r)) -> (Finalize m r) -> Pipe i o m r

-- | A <tt>Pipe</tt> which provides a stream of output values, without
--   consuming any input. The input parameter is set to <tt>Void</tt> to
--   indicate that this <tt>Pipe</tt> takes no input. A <tt>Source</tt> is
--   not used to produce a final result, and thus the result parameter is
--   set to <tt>()</tt>.
--   
--   Since 0.4.0
type Source m a = Pipe Void a m ()

-- | A <tt>Pipe</tt> which consumes a stream of input values and produces a
--   final result. It cannot produce any output values, and thus the output
--   parameter is set to <tt>Void</tt>. In other words, it is impossible to
--   create a <tt>HaveOutput</tt> constructor for a <tt>Sink</tt>.
--   
--   Since 0.4.0
type Sink i m r = Pipe i Void m r

-- | A <tt>Pipe</tt> which consumes a stream of input values and produces a
--   stream of output values. It does not produce a result value, and thus
--   the result parameter is set to <tt>()</tt>.
--   
--   Since 0.4.0
type Conduit i m o = Pipe i o m ()

-- | A cleanup action to be performed.
--   
--   Previously, we just had a plain action. However, most <tt>Pipe</tt>s
--   simply have empty cleanup actions, and storing a large set of them
--   wastes memory. But having strict fields and distinguishing between
--   pure and impure actions, we can keep memory usage constant, and only
--   allocate memory for the actual actions we have to track.
--   
--   Since 0.4.1
data Finalize m r
FinalizePure :: r -> Finalize m r
FinalizeM :: (m r) -> Finalize m r

-- | Perform any close actions available for the given <tt>Pipe</tt>.
--   
--   Since 0.4.0
pipeClose :: Monad m => Pipe i o m r -> Finalize 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, and
--   any leftovers from the right pipe will be discarded.
--   
--   This is in fact a wrapper around <a>pipeResume</a>. This function
--   closes the left <tt>Pipe</tt> returns by <tt>pipeResume</tt> and
--   returns only the result.
--   
--   Since 0.4.0
pipe :: Monad m => Pipe a b m () -> Pipe b c m r -> Pipe a c m r

-- | Same as <a>pipe</a>, but retain both the new left pipe and the
--   leftovers from the right pipe. The two components are combined
--   together into a single pipe and returned, together with the result of
--   the right pipe.
--   
--   Note: we're biased towards checking the right side first to avoid
--   pulling extra data which is not needed. Doing so could cause data
--   loss.
--   
--   Since 0.4.0
pipeResume :: Monad m => Pipe a b m () -> Pipe b c m r -> Pipe a c m (Pipe a b m (), r)

-- | Run a complete pipeline until processing completes.
--   
--   Since 0.4.0
runPipe :: Monad m => Pipe Void Void m r -> m r

-- | A <tt>Sink</tt> has a <tt>Void</tt> type parameter for the output,
--   which makes it difficult to compose with <tt>Source</tt>s and
--   <tt>Conduit</tt>s. This function replaces that parameter with a free
--   variable. This function is essentially <tt>id</tt>; it only modifies
--   the types, not the actions performed.
--   
--   Since 0.4.0
sinkToPipe :: Monad m => Sink i m r -> Pipe i o m r

-- | Wait for a single input value from upstream, and remove it from the
--   stream. Returns <tt>Nothing</tt> if no more data is available.
--   
--   Since 0.4.0
await :: Pipe i o m (Maybe i)

-- | Send a single output value downstream.
--   
--   Since 0.4.0
yield :: Monad m => o -> Pipe i o m ()

-- | Check if input is available from upstream. Will not remove the data
--   from the stream.
--   
--   Since 0.4.0
hasInput :: Pipe i o m Bool

-- | Transform the monad that a <tt>Pipe</tt> lives in.
--   
--   Since 0.4.0
transPipe :: Monad m => (forall a. m a -> n a) -> Pipe i o m r -> Pipe i o n r

-- | Apply a function to all the output values of a <a>Pipe</a>.
--   
--   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 i o1 m r -> Pipe i o2 m r

-- | Perform any necessary finalization actions.
--   
--   Since 0.4.1
runFinalize :: Monad m => Finalize m r -> 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 i o m r -> Pipe i o m r
instance Monad m => Monoid (Pipe i o m ())
instance MonadIO m => MonadIO (Pipe i o m)
instance MonadTrans (Pipe i o)
instance MonadBase base m => MonadBase base (Pipe i o m)
instance Monad m => Monad (Pipe i o m)
instance Monad m => Applicative (Pipe i o m)
instance Monad m => Functor (Pipe i o m)
instance MonadResource m => MonadResource (Finalize m)
instance MonadIO m => MonadIO (Finalize m)
instance MonadThrow m => MonadThrow (Finalize m)
instance MonadTrans Finalize
instance Monad m => Monad (Finalize m)
instance Monad m => Applicative (Finalize m)
instance Monad m => Functor (Finalize m)


-- | The main module, exporting types, utility functions, and fuse and
--   connect operators.
--   
--   There are three main types in this package: <tt>Source</tt> (data
--   producer), <tt>Sink</tt> (data consumer), and <tt>Conduit</tt> (data
--   transformer). All three are in fact type synonyms for the underlying
--   <tt>Pipe</tt> data type.
--   
--   The typical approach to use of this package is:
--   
--   <ul>
--   <li>Compose multiple <tt>Sink</tt>s together using its <tt>Monad</tt>
--   instance.</li>
--   <li>Left-fuse <tt>Source</tt>s and <tt>Conduit</tt>s into new
--   <tt>Conduit</tt>s.</li>
--   <li>Right-fuse <tt>Conduit</tt>s and <tt>Sink</tt>s into new
--   <tt>Sink</tt>s.</li>
--   <li>Middle-fuse two <tt>Conduit</tt>s into a new
--   <tt>Conduit</tt>.</li>
--   <li>Connect a <tt>Source</tt> to a <tt>Sink</tt> to obtain a
--   result.</li>
--   </ul>
module Data.Conduit

-- | The underlying datatype for all the types in this package. In has four
--   type parameters:
--   
--   <ul>
--   <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>m</i> is the underlying monad.</li>
--   <li><i>r</i> is the result type.</li>
--   </ul>
--   
--   Note that <i>o</i> and <i>r</i> are inherently different. <i>o</i> is
--   the type of the stream of values this <tt>Pipe</tt> will produce and
--   send downstream. <i>r</i> is the final output of this <tt>Pipe</tt>.
--   
--   <tt>Pipe</tt>s can be composed via the <a>pipe</a> function. To do so,
--   the output type of the left pipe much match the input type of the left
--   pipe, and the result type of the left pipe must be unit <tt>()</tt>.
--   This is due to the fact that any result produced by the left pipe must
--   be discarded in favor of the result of the right pipe.
--   
--   Since 0.4.0
data Pipe i o m r

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

-- | Request more input from upstream. The first field takes a new input
--   value and provides a new <tt>Pipe</tt>. The second is for early
--   termination. It gives a new <tt>Pipe</tt> which takes no input from
--   upstream. This allows a <tt>Pipe</tt> to provide a final stream of
--   output values after no more input is available from upstream.
NeedInput :: (i -> Pipe i o m r) -> (Pipe i o m r) -> Pipe i o m r

-- | Processing with this <tt>Pipe</tt> is complete. Provides an optional
--   leftover input value and and result.
Done :: (Maybe i) -> r -> Pipe i o m r

-- | Require running of a monadic action to get the next <tt>Pipe</tt>.
--   Second field is an early cleanup function. Technically, this second
--   field could be skipped, but doing so would require extra operations to
--   be performed in some cases. For example, for a <tt>Pipe</tt> pulling
--   data from a file, it may be forced to pull an extra, unneeded chunk
--   before closing the <tt>Handle</tt>.
PipeM :: (m (Pipe i o m r)) -> (Finalize m r) -> Pipe i o m r

-- | A <tt>Pipe</tt> which provides a stream of output values, without
--   consuming any input. The input parameter is set to <tt>Void</tt> to
--   indicate that this <tt>Pipe</tt> takes no input. A <tt>Source</tt> is
--   not used to produce a final result, and thus the result parameter is
--   set to <tt>()</tt>.
--   
--   Since 0.4.0
type Source m a = Pipe Void a m ()

-- | A <tt>Pipe</tt> which consumes a stream of input values and produces a
--   stream of output values. It does not produce a result value, and thus
--   the result parameter is set to <tt>()</tt>.
--   
--   Since 0.4.0
type Conduit i m o = Pipe i o m ()

-- | A <tt>Pipe</tt> which consumes a stream of input values and produces a
--   final result. It cannot produce any output values, and thus the output
--   parameter is set to <tt>Void</tt>. In other words, it is impossible to
--   create a <tt>HaveOutput</tt> constructor for a <tt>Sink</tt>.
--   
--   Since 0.4.0
type Sink i m r = Pipe i Void m r

-- | The connect operator, which pulls data from a source and pushes to a
--   sink. There are two ways this process can terminate:
--   
--   <ol>
--   <li>If the <tt>Sink</tt> is a <tt>Done</tt> constructor, the
--   <tt>Source</tt> is closed.</li>
--   <li>If the <tt>Source</tt> is a <tt>Done</tt> constructor, the
--   <tt>Sink</tt> is closed.</li>
--   </ol>
--   
--   In other words, both the <tt>Source</tt> and <tt>Sink</tt> will always
--   be closed. If you would like to keep the <tt>Source</tt> open to be
--   used for another operations, use the connect-and-resume operators
--   <a>$$+</a>.
--   
--   Since 0.4.0
($$) :: Monad m => Source m a -> Sink a m b -> m b

-- | The connect-and-resume operator. 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.4.0
($$+) :: Monad m => Source m a -> Sink a m b -> m (Source m a, 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>Pipe</tt>s together into a new
--   <tt>Pipe</tt>.
--   
--   Both <tt>Pipe</tt>s will be closed when the newly-created
--   <tt>Pipe</tt> is closed.
--   
--   Leftover data returned from the right <tt>Pipe</tt> will be discarded.
--   
--   Note: in previous versions, this operator would only fuse together two
--   <tt>Conduit</tt>s (known as middle fusion). This operator is
--   generalized to work on all <tt>Pipe</tt>s, including <tt>Source</tt>s
--   and <tt>Sink</tt>s.
--   
--   Since 0.4.0
(=$=) :: Monad m => Pipe a b m () -> Pipe b c m r -> Pipe a c m r

-- | Wait for a single input value from upstream, and remove it from the
--   stream. Returns <tt>Nothing</tt> if no more data is available.
--   
--   Since 0.4.0
await :: Pipe i o m (Maybe i)

-- | Send a single output value downstream.
--   
--   Since 0.4.0
yield :: Monad m => o -> Pipe i o m ()

-- | Check if input is available from upstream. Will not remove the data
--   from the stream.
--   
--   Since 0.4.0
hasInput :: Pipe i o m Bool

-- | Transform the monad that a <tt>Pipe</tt> lives in.
--   
--   Since 0.4.0
transPipe :: Monad m => (forall a. m a -> n a) -> Pipe i o m r -> Pipe i o n r

-- | Apply a function to all the output values of a <a>Pipe</a>.
--   
--   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 i o1 m r -> Pipe i o2 m r

-- | Construct a <a>Source</a> with some stateful functions. This function
--   addresses threading the state value for you.
--   
--   Since 0.3.0
sourceState :: Monad m => state -> (state -> m (SourceStateResult state output)) -> Source m output

-- | A combination of <a>sourceIO</a> and <a>sourceState</a>.
--   
--   Since 0.3.0
sourceStateIO :: MonadResource m => IO state -> (state -> IO ()) -> (state -> m (SourceStateResult state output)) -> Source m output

-- | The return value when pulling in the <tt>sourceState</tt> function.
--   Either indicates no more data, or the next value and an updated state.
--   
--   Since 0.3.0
data SourceStateResult state output
StateOpen :: state -> output -> SourceStateResult state output
StateClosed :: SourceStateResult state output

-- | Construct a <a>Source</a> based on some IO actions for alloc/release.
--   
--   Since 0.3.0
sourceIO :: MonadResource m => IO state -> (state -> IO ()) -> (state -> m (SourceIOResult output)) -> Source m output

-- | The return value when pulling in the <tt>sourceIO</tt> function.
--   Either indicates no more data, or the next value.
--   
--   Since 0.3.0
data SourceIOResult output
IOOpen :: output -> SourceIOResult output
IOClosed :: SourceIOResult output

-- | Construct a <a>Sink</a> with some stateful functions. This function
--   addresses threading the state value for you.
--   
--   Since 0.3.0
sinkState :: Monad m => state -> (state -> input -> m (SinkStateResult state input output)) -> (state -> m output) -> Sink input m output

-- | A helper type for <tt>sinkState</tt>, indicating the result of being
--   pushed to. It can either indicate that processing is done, or to
--   continue with the updated state.
--   
--   Since 0.3.0
data SinkStateResult state input output
StateDone :: (Maybe input) -> output -> SinkStateResult state input output
StateProcessing :: state -> SinkStateResult state input output

-- | Construct a <a>Sink</a>. Note that your push and close functions need
--   not explicitly perform any cleanup.
--   
--   Since 0.3.0
sinkIO :: MonadResource m => IO state -> (state -> IO ()) -> (state -> input -> m (SinkIOResult input output)) -> (state -> m output) -> Sink input m output

-- | A helper type for <tt>sinkIO</tt>, indicating the result of being
--   pushed to. It can either indicate that processing is done, or to
--   continue.
--   
--   Since 0.3.0
data SinkIOResult input output
IODone :: (Maybe input) -> output -> SinkIOResult input output
IOProcessing :: SinkIOResult input output

-- | A helper function for returning a list of values from a
--   <tt>Conduit</tt>.
--   
--   Since 0.3.0
haveMore :: Conduit a m b -> m () -> [b] -> Conduit a m b

-- | Construct a <a>Conduit</a> with some stateful functions. This function
--   addresses threading the state value for you.
--   
--   Since 0.3.0
conduitState :: Monad m => state -> (state -> input -> m (ConduitStateResult state input output)) -> (state -> m [output]) -> Conduit input m output

-- | A helper type for <tt>conduitState</tt>, indicating the result of
--   being pushed to. It can either indicate that processing is done, or to
--   continue with the updated state.
--   
--   Since 0.3.0
data ConduitStateResult state input output
StateFinished :: (Maybe input) -> [output] -> ConduitStateResult state input output
StateProducing :: state -> [output] -> ConduitStateResult state input output

-- | Construct a <a>Conduit</a>.
--   
--   Since 0.3.0
conduitIO :: MonadResource m => IO state -> (state -> IO ()) -> (state -> input -> m (ConduitIOResult input output)) -> (state -> m [output]) -> Conduit input m output

-- | A helper type for <tt>conduitIO</tt>, indicating the result of being
--   pushed to. It can either indicate that processing is done, or to
--   continue.
--   
--   Since 0.3.0
data ConduitIOResult input output
IOFinished :: (Maybe input) -> [output] -> ConduitIOResult input output
IOProducing :: [output] -> ConduitIOResult input output

-- | Helper type for constructing a <tt>Conduit</tt> based on
--   <tt>Sink</tt>s. This allows you to write higher-level code that takes
--   advantage of existing conduits and sinks, and leverages a sink's
--   monadic interface.
--   
--   Since 0.3.0
type SequencedSink state input m output = state -> Sink input m (SequencedSinkResponse state input m output)

-- | Convert a <a>SequencedSink</a> into a <a>Conduit</a>.
--   
--   Since 0.3.0
sequenceSink :: Monad m => state -> SequencedSink state input m output -> Conduit input m output

-- | Specialised version of <a>sequenceSink</a>
--   
--   Note that this function will return an infinite stream if provided a
--   <tt>Sink</tt> which does not consume data. In other words, you
--   probably don't want to do <tt>sequence . return</tt>.
--   
--   Since 0.3.0
sequence :: Monad m => Sink input m output -> Conduit input m output

-- | Return value from a <a>SequencedSink</a>.
--   
--   Since 0.3.0
data SequencedSinkResponse state input m output

-- | Set a new state, and emit some new output.
Emit :: state -> [output] -> SequencedSinkResponse state input m output

-- | End the conduit.
Stop :: SequencedSinkResponse state input m output

-- | Pass control to a new conduit.
StartConduit :: (Conduit input m output) -> SequencedSinkResponse state input m output

-- | 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
instance Show a => Show (Flush a)
instance Eq a => Eq (Flush a)
instance Ord a => Ord (Flush a)
instance Functor Flush


-- | 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 -> Source 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 -> Source 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 close it as soon as
--   possible.
--   
--   Since 0.3.0
sourceIOHandle :: MonadResource m => IO Handle -> Source 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 -> Source m ByteString

-- | Stream all incoming data to the given file.
--   
--   Since 0.3.0
sinkFile :: MonadResource m => FilePath -> Sink 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 -> Sink 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 -> Sink 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

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

-- | Open a file <a>Handle</a> safely by automatically registering a
--   release action.
--   
--   While you are not required to call <tt>hClose</tt> on the resulting
--   handle, you should do so as early as possible to free scarce
--   resources.
--   
--   Since 0.3.0
openFile :: MonadResource m => FilePath -> IOMode -> m Handle

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

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

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

-- | Take the given number of bytes, if available.
--   
--   Since 0.3.0
take :: Monad m => Int -> Sink 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


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

-- | Convert a list into a source.
--   
--   Since 0.3.0
sourceList :: Monad m => [a] -> Source m a

-- | A source that returns nothing. Note that this is just a
--   type-restricted synonym for <a>mempty</a>.
--   
--   Since 0.3.0
sourceNull :: Monad m => Source m a

-- | Generate a source from a seed value.
--   
--   Since 0.4.2
unfold :: Monad m => (b -> Maybe (a, b)) -> b -> Source 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 -> Source m a

-- | A strict left fold.
--   
--   Since 0.3.0
fold :: Monad m => (b -> a -> b) -> b -> Sink 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 -> Sink 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 -> Sink a m ()

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

-- | 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.
--   
--   If both sinks finish on the same chunk, and both report leftover
--   input, arbitrarily yield the left sink's leftover input.
--   
--   Since 0.4.1
zipSinks :: Monad m => Sink i m r -> Sink i m r' -> Sink i m (r, r')

-- | 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 => Sink 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 => Sink 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 => Sink a m ()

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

-- | Apply the action to all values in the stream.
--   
--   Since 0.3.0
mapM_ :: Monad m => (a -> m ()) -> Sink 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 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 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


-- | 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. However, if you consume the content
--   within the ResourceT, you should be safe.
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]
