Pipes.Cliff.Examples

Examples using Pipes.Cliff. You will want to look at the source code itself; viewing just the Haddocks will not help you much. You can view the source using Haddock if you used --hyperlink-source when building the library or if you are viewing this on Hackage; look for the Source link. Or, you can find the source at

https://github.com/massysett/pipes-cliff/blob/master/lib/Pipes/Cliff/Examples.hs

Be sure to use the -threaded option when compiling code that uses Pipes.Cliff, including this code; see the warning in Pipes.Cliff for more details.

Notice throughout how pipelines that move data from one process to another typically are run in the background using conveyor, which spawns a thread. You have to make sure all these threads are running concurrently so that data flows through your pipeline (a shell does this sort of thing for you.)

Documentation

produceNumbers :: Monad m => Producer ByteString m r

Produces a stream of ByteString, where each ByteString is a shown integer. This is an infinite stream. In the examples below we'll send this infinite stream off into a Unix pipeline, a feat that would be very difficult and clumsy without a framework like pipes.

numsToLess :: IO (Maybe ExitCode, ExitCode)

Streams an infinite list of numbers to less. The Effect that streams values to the process is run in the background by using conveyor, even though there is only one subprocess. This is typically what you want. Shows off how you can use Pipes.Cliff even for non-finite Producers. Don't try to go to the end of the input in less, though. When you quit less, you will get broken pipe warnings printed to standard error. This is normal. To suppress them, see the handler option.

alphaNumbers :: IO (ExitCode, ExitCode)

Streams an infinite list of numbers to tr and then to less. Perfectly useless, but shows how to build pipelines. Also squlches warning messages using the handler option.

standardOutputAndError :: IO ByteString

Produces an infinite stream of numbers, sends it to tr for some mangling, and then to sh, which will copy each line both to standard output and to standard error. From sh, standard output is then sent off to less, and standard error is sent to a separate thread which will collect the results and return them.

This example shows you how to write a pipeline that deals with both standard output and standard error.

It's also interesting to note here that because of the buffering that happens in various places throughout the pipeline, and because less itself also buffers its input, the output you will see from the sh process's standard error will be much longer than the output the user actually viewed in less.

limitedAlphaNumbers :: IO (Maybe ExitCode, ExitCode)

Like alphaNumbers but just sends a limited number of numbers to cat. A useful test to make sure that pipelines shut down automatically.

alphaNumbersByteString :: IO ByteString

Produces a finite list of numbers, sends it to tr for some mangling, and then puts the results into a ByteString for further processing. This example shows how you can use this library to place the results of a pipeline into a simple strict data type.

standardOutputAndErrorBracketed :: IO ByteString

So far, all examples have ignored the issue of exception safety. Here's an example that properly uses bracket to make sure that all resource allocations are cleaned up if there is an exception. Otherwise, it's identical to standardOutputAndError. You can put some do notation sugar in here and eliminate all the hanging lambdas and $s by using the ContT monad from transformers (I did not write the example that way to avoid incurring a direct dependency on transformers).