Data.Conduit

Core datatype of the conduit package. This type represents a general component which can consume a stream of input values i, produce a stream of output values o, perform actions in the m monad, and produce a final result r. The type synonyms provided here are simply wrappers around this type.

Since 1.3.0

Provides a stream of output values, without consuming any input or producing a final result.

Since 0.5.0

Consumes a stream of input values and produces a stream of output values, without producing a final result.

Since 0.5.0

Consumes a stream of input values and produces a final result, without producing any output.

type Sink i m r = ConduitT i Void m r

Since 0.5.0

Same as ConduitT, for backwards compat

Combine two Conduits together into a new Conduit (aka fuse).

Output from the upstream (left) conduit will be fed into the downstream (right) conduit. Processing will terminate when downstream (right) returns. Leftover data returned from the right Conduit will be discarded.

Equivalent to fuse and =$=, however the latter is deprecated and will be removed in a future version.

Note that, while this operator looks like categorical composition (from Control.Category), there are a few reasons it's different:

• The position of the type parameters to ConduitT do not match. We would need to change ConduitT i o m r to ConduitT r m i o, which would preclude a Monad or MonadTrans instance.

• The result value from upstream and downstream are allowed to differ between upstream and downstream. In other words, we would need the type signature here to look like ConduitT a b m r -> ConduitT b c m r -> ConduitT a c m r.

• Due to leftovers, we do not have a left identity in Conduit. This can be achieved with the underlying Pipe datatype, but this is not generally recommended. See https://stackoverflow.com/a/15263700.

Equivalent to using runConduit and .| together.

Since 1.2.3

Named function synonym for .|

Equivalent to .| and =$=. However, the latter is deprecated and will be removed in a future version.

Since 1.2.3

The connect operator, which pulls data from a source and pushes to a sink. If you would like to keep the Source open to be used for other operations, use the connect-and-resume operator $$+.

Since 0.4.0

A synonym for =$= for backwards compatibility.

Since 0.4.0

A synonym for =$= for backwards compatibility.

Since 0.4.0

Deprecated fusion operator.

Since 0.4.0

Fuse two ConduitTs together, and provide the return value of both. Note that this will force the entire upstream ConduitT to be run to produce the result value, even if the downstream terminates early.

Since 1.1.5

Like fuseBoth, but does not force consumption of the Producer. In the case that the Producer terminates, the result value is provided as a Just value. If it does not terminate, then a Nothing value is returned.

One thing to note here is that "termination" here only occurs if the Producer actually yields a Nothing value. For example, with the Producer mapM_ yield [1..5], if five values are requested, the Producer has not yet terminated. Termination only occurs when the sixth value is awaited for and the Producer signals termination.

Since 1.2.4

Same as fuseBoth, but ignore the return value from the downstream Conduit. Same caveats of forced consumption apply.

Since 1.1.5

Wait for a single input value from upstream. If no data is available, returns Nothing. Once await returns Nothing, subsequent calls will also return Nothing.

Since 0.5.0

Send a value downstream to the next component to consume. If the downstream component terminates, this call will never return control.

Since 0.5.0

Send a monadic value downstream for the next component to consume.

Provide a single piece of leftover input to be consumed by the next component in the current monadic binding.

Note: it is highly encouraged to only return leftover values from input already consumed from upstream.

Run a pipeline until processing completes.

Since 1.2.1

Run a pure pipeline until processing completes, i.e. a pipeline with Identity as the base monad. This is equivalient to runIdentity . runConduit.

Run a pipeline which acquires resources with ResourceT, and then run the ResourceT transformer. This is equivalent to runResourceT . runConduit.

Bracket a conduit computation between allocation and release of a resource. Two guarantees are given about resource finalization:

1. It will be prompt. The finalization will be run as early as possible.

2. It is exception safe. Due to usage of resourcet, the finalization will be run in the event of any exceptions.

Since 0.5.0

Catch all exceptions thrown by the current component of the pipeline.

Note: this will not catch exceptions thrown by other components! For example, if an exception is thrown in a Source feeding to a Sink, and the Sink uses catchC, the exception will not be caught.

Due to this behavior (as well as lack of async exception safety), you should not try to implement combinators such as onException in terms of this primitive function.

Note also that the exception handling will not be applied to any finalizers generated by this conduit.

Since 1.0.11

The same as flip catchC.

Since 1.0.11

A version of try for use within a pipeline. See the comments in catchC for more details.

Since 1.0.11

The connect-and-resume operator. This does not close the Conduit, but instead returns it to be used again. This allows a Conduit to be used incrementally in a large program, without forcing the entire program to live in the Sink monad.

Leftover data returned from the Sink will be discarded.

Mnemonic: connect + do more.

Since 1.0.17

Continue processing after usage of =$$+. Connect a SealedConduitT to a sink and return the output of the sink together with a new SealedConduitT.

Since 1.0.17

Same as =$$++, but doesn't include the updated SealedConduitT.

NOTE In previous versions, this would cause finalizers to run. Since version 1.3.0, there are no finalizers in conduit.

Since 1.0.17

A wrapper for defining an Applicative instance for Sources which allows to combine sources together, generalizing zipSources. A combined source will take input yielded from each of its Sources until any of them stop producing output.

Since 1.0.13

Coalesce all values yielded by all of the Sources.

Implemented on top of ZipSource and as such, it exhibits the same short-circuiting behavior as ZipSource. See that data type for more details. If you want to create a source that yields *all* values from multiple sources, use sequence_.

Since 1.0.13

A wrapper for defining an Applicative instance for Sinks which allows to combine sinks together, generalizing zipSinks. A combined sink distributes the input to all its participants and when all finish, produces the result. This allows to define functions like

sequenceSinks :: (Monad m)
          => [ConduitT i Void m r] -> ConduitT i Void m [r]
sequenceSinks = getZipSink . sequenceA . fmap ZipSink

Note that the standard Applicative instance for conduits works differently. It feeds one sink with input until it finishes, then switches to another, etc., and at the end combines their results.

This newtype is in fact a type constrained version of ZipConduit, and has the same behavior. It's presented as a separate type since (1) it historically predates ZipConduit, and (2) the type constraining can make your code clearer (and thereby make your error messages more easily understood).

Since 1.0.13

Send incoming values to all of the Sink providing, and ultimately coalesce together all return values.

Implemented on top of ZipSink, see that data type for more details.

Since 1.0.13

Provides an alternative Applicative instance for ConduitT. In this instance, every incoming value is provided to all ConduitTs, and output is coalesced together. Leftovers from individual ConduitTs will be used within that component, and then discarded at the end of their computation. Output and finalizers will both be handled in a left-biased manner.

As an example, take the following program:

main :: IO ()
main = do
    let src = mapM_ yield [1..3 :: Int]
        conduit1 = CL.map (+1)
        conduit2 = CL.concatMap (replicate 2)
        conduit = getZipConduit $ ZipConduit conduit1 <* ZipConduit conduit2
        sink = CL.mapM_ print
    src $$ conduit =$ sink

It will produce the output: 2, 1, 1, 3, 2, 2, 4, 3, 3

Since 1.0.17

Provide identical input to all of the Conduits and combine their outputs into a single stream.

Implemented on top of ZipConduit, see that data type for more details.

Since 1.0.17