From c53b762d50543b076e1e3fa8230621c32c27d292 Mon Sep 17 00:00:00 2001
From: Michael van der Gulik <mikevdg@gulik.co.nz>
Date: Tue, 7 Jun 2022 15:39:49 +1200
Subject: [PATCH] More stream documentation.

As a beginner, I was confused about how streams were used. This is some extra documentation and example that others might find useful.
---
 src/Turtle/Tutorial.hs | 47 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/src/Turtle/Tutorial.hs b/src/Turtle/Tutorial.hs
index 26cf472..07a2c36 100644
--- a/src/Turtle/Tutorial.hs
+++ b/src/Turtle/Tutorial.hs
@@ -888,6 +888,53 @@ import Turtle
 -- > FilePath "/tmp/ssh-vREYGbWGpiCa"
 -- > FilePath "/tmp/.ICE-unix
 --
+-- To process a stream, you pass the stream as output of one function to 
+-- another in the usual way. For example:
+--
+-- @
+-- ghci> view $ input "foo.txt"
+-- Line "license.txt"
+-- Line "README.md"
+-- Line "README.md"
+-- Line "index.html"
+-- ghci> view $ uniq $ input "foo.txt"
+-- Line "license.txt"
+-- Line "README.md"
+-- Line "index.html"
+-- @ 
+-- 
+-- If you prefer your 'pipes' to flow from left to right, you can use the `&` 
+-- operator. 
+-- 
+-- @
+-- ghci> input "foo.txt" & uniq & view
+-- Line "license.txt"
+-- Line "README.md"
+-- Line "index.html"
+-- @
+--
+-- Alternatively, the Flow library will achieve the same result using a syntax
+-- more familiar to shell users:
+--
+-- @
+-- ghci> import Flow
+-- ghci> input "foo.txt" |> uniq |> view
+-- Line "license.txt"
+-- Line "README.md"
+-- Line "index.html"
+-- @
+--
+-- These streams are plain Haskell monads, meaning that they support the 
+-- standard operations that you can do with monads:
+--
+-- @
+-- ghci> view $ input "foo.txt" >>= pure . fromText . lineToText
+-- FilePath "license.txt"
+-- FilePath "README.md"
+-- FilePath "README.md"
+-- FilePath "index.html"
+-- @
+--
 -- You can build your own `Shell` streams using a few primitive operations,
 --
 -- The first primitive is `empty`, which represents an empty stream of values: