Documentation

Similar to a conduit from the conduit package.

For a Pipe i o u m a, you have:

• i: Type of input stream (the things you can await)
• o: Type of output stream (the things you yield)
• u: Type of the result of the upstream pipe (Outputted when upstream pipe terminates)
• m: Underlying monad (the things you can lift)
• a: Result type when pipe terminates (outputted when finished, with pure or return)

Some specializations:

• If i is (), the pipe is a source --- it doesn't need anything to produce items. It will pump out items on its own, for pipes downstream to receive and process.
• If o is Void, the pipe is a sink --- it will never yield anything downstream. It will consume items from things upstream, and produce a result (a) if and when it terminates.
• If u is Void, then the pipe's upstream is limitless, and never terminates. This means that you can use awaitSurely instead of await, to get await a value that is guaranteed to come. You'll get an i instead of a Maybe i.
• If a is Void, then the pipe never terminates --- it will keep on consuming and/or producing values forever. If this is a sink, it means that the sink will never terminate, and so runPipe will also never terminate. If it is a source, it means that if you chain something downstream with .|, that downstream pipe can use awaitSurely to guarantee something being passed down.

Applicative and Monadic sequencing of pipes chains by exhaustion.

do pipeX
   pipeY
   pipeZ

is a pipe itself, that behaves like pipeX until it terminates, then pipeY until it terminates, then pipeZ until it terminates. The Monad instance allows you to choose "which pipe to behave like next" based on the terminating result of a previous pipe.

do x <- pipeX
   pipeBasedOn x

Usually you would use it by chaining together pipes with .| and then running the result with runPipe.

runPipe $ someSource
       .| somePipe
       .| someOtherPipe
       .| someSink

See .| and runPipe for more information on usage.

For a "prelude" of commonly used Pipes, see Data.Conduino.Combinators.

Base functor of Pipe.

A pipe fundamentally has the ability to await and the ability to yield. The other functionality are implemented.

• Lifting effects is implemented by the MonadTrans and MonadIO instances that FT gives.
• Ending with a result is implemented by the Applicative instance's pure that FT gives.
• Applicative and monadic sequenceing "after a pipe is done" is implemented by the Applicative and Monad instances that FT gives.

On top of these we implement .| and other combinators based on the structure that FT gives. For some functions, it can be easier to use an alternative encoding, RecPipe, which is the same thing but explicitly recursive.

Await on upstream output. Will block until it receives an i (expected input type) or a u if the upstream pipe terminates.

Send output downstream.

Map over the input type, output type, and upstream result type.

If you want to map over the result type, use fmap.

(Contravariantly) map over the expected input type.

Map over the downstream output type.

If you want to map over the result type, use fmap.

(Contravariantly) map over the upstream result type.

Transform the underlying monad of a pipe.

Note that if you are trying to work with monad transformers, this is probably not what you want. See Data.Conduino.Lift for tools for working with underlying monad transformers.

A version of Pipe that uses explicit, concrete recursion instead of church-encoding like Pipe. Some functions --- especially ones that combine multiple pipes into one --- are easier to implement in this form.

Convert from a Pipe to a RecPipe. While most of this library is defined in terms of Pipe, it can be easier to write certain low-level pipe combining functions in terms of RecPipe than Pipe.

Convert a RecPipe back into a Pipe.

Convenint wrapper over toRecPipe and fromRecPipe.

Since: 0.2.1.0

Turn a Pipe that runs over StateT into a "state-modifying Pipe", that returns the final state when it terminates.

The main usage of this is to "isolate" the state from other pipes in the same chain. For example, of p, q, and r are all pipes under StateT, then:

    p
 .| q
 .| r

will all share underlying state, and each can modify the state that they all three share. We essentially have global state.

However, if you use runStateP, you can all have them use different encapsulated states.

    void (runStateP s0 p)
 .| void (runStateP s1 q)
 .| runStateP s2 r

In this case, each of those three chained pipes will use their own internal states, without sharing.

This is also useful if you want to chain a pipe over StateT with pipes that don't use state at all: for example if a and b are "non-stateful" pipes (not over StateT), you can do:

    a
 .| void (runStateP s1 q)
 .| b

And a and b will be none the wiser to the fact that q uses StateT internally.

Note to avoid the usage of void, evalStateP might be more useful.

Since: 0.2.1.0