Fix all the code blocks in the markdown files

Author: adithyaov

docs/User/Explanatory/unified-abstractions.md

@@ -79,11 +79,15 @@ API.
 This simple console echo program shows the simplicity of Streamly API
 and its similarity with the list API:
 
-```haskell
+```haskell unshared
+import Data.Function ((&))
+import qualified Streamly.Data.Stream as Stream
+import qualified Streamly.Data.Fold as Fold
+
 echo =
       Stream.repeatM getLine
     & Stream.mapM putStrLn
-    & Stream.drain
+    & Stream.fold Fold.drain
 ```
 
 Streamly uses dual representation for streams. On top it uses Scott
@@ -105,20 +109,35 @@ programmers use for what you call nested loops in imperative
 programming. List transformers are the basic implementations for
 non-determinism.
 
-The stream monad in Streamly is a list-transformer with behavior similar
-to the list monad. It provides the functionality provided by `list-t` or
-`logict` packages for free.  Here is an example of nested looping using
-the serial stream monad:
+You can use `Streamly.Data.Stream.MkType` to create a custom type and specify
+the behaviour of non-determinism. The basic `concatMap` would result in a
+list-transformer with behavior similar to the list monad. It provides the
+functionality provided by `list-t` or `logict` packages for free.  Here is an
+example of nested looping using the new type:
 
 ```haskell
-import qualified Streamly.Prelude as S
-
-loops = do
-    x <- Stream.fromFoldable [1,2]
-    y <- Stream.fromFoldable [3,4]
-    Stream.fromEffect $ print (x, y)
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE UndecidableInstances #-}
+
+import Streamly.Data.Stream.Prelude (Stream, MonadAsync)
+import qualified Streamly.Data.Stream.Prelude as Stream
+import qualified Streamly.Data.StreamK as StreamK
+import Streamly.Data.Stream.MkType
+
+bindSerial :: Monad m => Stream m a -> (a -> Stream m b) -> Stream m b
+bindSerial = flip Stream.concatMap
+$(mkCrossType "CrossT" "bindSerial" False)
+
+loopsCross :: Stream IO ()
+loopsCross = unCrossT $ do
+    x <- CrossT $ Stream.fromList [1,2]
+    y <- CrossT $ Stream.fromList [3,4]
+    CrossT $ Stream.fromEffect $ print (x, y)
 ```
 
+`Streamly.Data.Stream.CrossStream` and `Streamly.Data.StreamK.CrossStreamK`
+provide the same functionality as `CrossT` type created above.
+
 Moreover, the list transformer in Streamly can be concurrent. The Scott
 encoding of streams also avoids the quadratic performance issue of
 `logict`.
@@ -142,12 +161,18 @@ concurrent round-robin scheduling of streams.
 
 The monad instance provides a convenient way to combine streams in
 different ways. It is just non-determinism with different flavors of
-scheduling behavior.  The example from the previous section can be run
-with interleaved scheduling behavior as follows, without changing the
-code at all:
+scheduling behavior. The scheduling behavior can be controlled as follows.
 
 ```haskell
-main = Stream.drain $ Stream.fromWserial loops
+bindWSerialK = StreamK.bindWith StreamK.interleave
+bindWSerial a f = StreamK.toStream $ bindWSerialK (StreamK.fromStream a) (StreamK.fromStream . f)
+$(mkCrossType "WSerialT" "bindWSerial" True)
+
+loopsWSerial :: Stream IO ()
+loopsWSerial = unWSerialT $ do
+    x <- WSerialT $ Stream.fromList [1,2]
+    y <- WSerialT $ Stream.fromList [3,4]
+    WSerialT $ Stream.fromEffect $ print (x, y)
 ```
 
 Scheduling is fundamental to expressing many common programming problems
@@ -159,6 +184,9 @@ Please see [mini kanren implementation using streamly](https://github.com/compos
 
 The same combinators that are used for serial streams e.g. 'unfoldrM',
 'replicateM', 'repeatM' work concurrently when used at the appropriate type.
+
+There are several concurrent combinators in streamly which are prefixed with
+`par`. These combinators fit into the default composition very cleanly.
 It allows concurrent programs to be written declaratively and composed
 idiomatically. They are not much different than serial programs.  See
 [Streamly vs async](/docs/User/HowTo/streamly-vs-async.md)
@@ -168,18 +196,33 @@ Streamly provides concurrent scheduling and looping similar to to
 [OpenMP](https://en.wikipedia.org/wiki/OpenMP) and
 [Cilk](https://en.wikipedia.org/wiki/Cilk) but with a more declarative
 style.  The list transformer example can be run with concurrent
-execution of loop iterations as follows, without changing the code at
-all:
+execution of loop iterations as follows:
 
 ```haskell
-main = Stream.drain $ Stream.fromAhead loops
+bindAhead :: MonadAsync m => Stream m a -> (a -> Stream m b) -> Stream m b
+bindAhead = flip (Stream.parConcatMap (Stream.ordered True))
+$(mkCrossType "AheadT" "bindAhead" True)
+
+loopsAhead :: Stream IO ()
+loopsAhead = unAheadT $ do
+    x <- AheadT $ Stream.fromList [1,2]
+    y <- AheadT $ Stream.fromList [3,4]
+    AheadT $ Stream.fromEffect $ print (x, y)
 ```
 
 And interleaving with concurrent execution of the loop iterations can be
 written like this:
 
 ```haskell
-main = Stream.drain $ Stream.fromWAsync loops
+bindWAsync :: MonadAsync m => Stream m a -> (a -> Stream m b) -> Stream m b
+bindWAsync = flip (Stream.parConcatMap (Stream.interleaved True))
+$(mkCrossType "WAsyncT" "bindWAsync" True)
+
+loopsWAsync :: Stream IO ()
+loopsWAsync = unWAsyncT $ do
+    x <- WAsyncT $ Stream.fromList [1,2]
+    y <- WAsyncT $ Stream.fromList [3,4]
+    WAsyncT $ Stream.fromEffect $ print (x, y)
 ```
 
 All this comes with no change in the streaming APIs.

docs/User/HowTo/faq.md

@@ -13,41 +13,45 @@ together to create a single transformed stream.
 
 Distributing a value to a stream of consumers concurrently:
 
-```haskell ghci
-{-# LANGUAGE FlexibleContexts #-}
-
-import Data.Function ((&))
-import qualified Streamly.Data.Fold as Fold
-import qualified Streamly.Data.Stream.Prelude as Stream
+```haskell docspec
+>>> :set -XFlexibleContexts
+>>> import Data.Function ((&))
+>>> import qualified Streamly.Data.Fold as Fold
+>>> import qualified Streamly.Data.Stream.Prelude as Stream
 
+>>> :{
 f1 x =
     Stream.fromList [return . (+ 1), return . (+ 2)] -- Stream of functions
         & fmap ($ x)                                 -- Stream of lazy actions
         & Stream.parSequence (Stream.ordered True)   -- Evaluate concurrently
         & Stream.fold Fold.toList                    -- Fold to list
+:}
 ```
 
 Use `parZipWith` to zip streams concurrently. Here, we zip three singleton
 streams:
 
-```haskell ghci
-
+```haskell docspec
+>>> :{
 f2 x =
   let app = Stream.parZipWith id ($)
   in (,,)
       `fmap` Stream.fromEffect (return $ show x)
       `app`  Stream.fromEffect (return $ x + 1)
       `app`  Stream.fromEffect (return $ fromIntegral x / 2)
   & Stream.fold Fold.one
+:}
 ```
 
 Applying a function concurrently to your input stream:
 
-```haskell ghci
+```haskell docspec
+>>> :{
 g f xs =
   Stream.fromList xs
     & Stream.parMapM (Stream.ordered True) f
     & Stream.fold Fold.toList
+:}
 ```
 
 You can now use the concurrent map to pipe each element through multiple
@@ -66,22 +70,25 @@ create a zip Applicative newtype so that you can use the `Applicative`
 instance.
 
 ```haskell
-{-# LANGUAGE UndecidableInstances #-}
-{-# LANGUAGE FlexibleInstances #-}
-{-# LANGUAGE MultiParamTypeClasses #-}
 {-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE UndecidableInstances #-}
 
-import Streamly.Internal.Data.Stream.TypeGen
+import Control.Monad.Trans.Control (MonadBaseControl)
+import Streamly.Data.Stream.Prelude (MonadAsync, Stream)
+import qualified Streamly.Data.Stream.Prelude as Stream
+import Streamly.Data.Stream.MkType
 
-app = parZipWith id ($)
-$(mkZippingType "ZipConcurrent" "app" True)
+app :: MonadAsync m => Stream m (a -> b) -> Stream m a -> Stream m b
+app = Stream.parZipWith id ($)
+$(mkZipType "ZipConcurrent" "app" True)
 ```
 
 ## Sliding Window
 
 The `createOfLast` fold can be used to create a stream of sliding windows.
 
 ```haskell docspec
+>>> :set -Wno-deprecations
 >>> import qualified Streamly.Data.Array as Array
 >>> :{
   Stream.fromList [1,2,3,4,5::Int]

docs/User/HowTo/streamly-vs-async.md

@@ -48,11 +48,12 @@ stream folding operations can also be used, see the docs for more details.
 Use the following imports to run the snippets shown below:
 
 ```haskell
-import Streamly
-import Streamly.Prelude ((|:))
-import qualified Streamly.Prelude as S
+import qualified Streamly.Data.Stream.Prelude as S
+import qualified Streamly.Data.Fold as F
 import qualified Data.Text as Text
 import Control.Concurrent (threadDelay)
+import Control.Exception (Exception, SomeException)
+import Control.Monad.Catch (throwM, try)
 ```
 
 Let us simulate a URL fetch with a delay of `n` seconds using the following
@@ -71,7 +72,7 @@ You can run any number of actions concurrently. For example, to fetch two URLs
 concurrently:
 
 ```haskell
-  urls <- S.toList $ fromParallel $ getURL 2 |: getURL 1 |: S.nil
+getUrlsConcurrently = S.parSequence id $ S.fromList [getURL 2, getURL 1]
 ```
 
 This would return the results in their arrival order i.e. first 1 and then 2.
@@ -81,26 +82,25 @@ concurrently, and even though URL 1 arrives before URL 2 the results will
 return 2 first and then 1.
 
 ```haskell
-  urls <- S.toList $ fromAhead $ getURL 2 |: getURL 1 |: S.nil
+getUrlsOrdered = S.parSequence (S.ordered True) $ S.fromList [getURL 2, getURL 1]
 ```
 
 ### concurrently_
 
 Use `drain` instead of `toList` to run the actions but ignore the results:
 
 ```haskell
-  S.drain $ fromParallel $ getURL 1 |: getURL 2 |: S.nil
+drainUrlsConcurrently = S.fold F.drain $ S.parMapM id getURL $ S.fromList [1, 2]
 ```
 
-### Concurrent Applicative
+### Concurrent Zipping
 
 If the actions that you are executing result in different output types you can
-use applicative zip to collect the results or to directly apply them to a
-function:
+use zip to collect the results or to directly apply them to a function:
 
 ```haskell
-  tuples <- S.toList $ fromZipAsync $
-              (,) <$> S.fromEffect (getURLString 1) <*> S.fromEffect (getURLText 2)
+concurrentZipping =
+    S.parZipWith id (,) (S.fromEffect (getURLString 1)) (S.fromEffect (getURLText 2))
 ```
 
 ### race
@@ -114,14 +114,14 @@ We can run multiple actions concurrently and take the first result that
 arrives:
 
 ```haskell
-  urls <- S.toList $ S.take 1 $ fromParallel $ getURL 1 |: getURL 2 |: S.nil
+fastest = S.toList $ S.take 1 $ S.parSequence id $ S.fromList [getURL 1, getURL 2]
 ```
 
 After the first result arrives, the rest of the actions are canceled
 automatically.  In general, we can take first `n` results as they arrive:
 
 ```haskell
-  urls <- S.toList $ S.take 2 $ fromParallel $ getURL 1 |: getURL 2 |: S.nil
+fastestN n = S.toList $ S.take n $ S.parSequence id $ S.fromList [getURL 1, getURL 2]
 ```
 
 #### `race` Using Exceptions
@@ -133,54 +133,38 @@ exception to communicate the result. As soon as the first result arrives all
 other actions will be canceled, for example:
 
 ```haskell
-  data Result = Result String deriving Show
-  instance Exception Result
-
-  main = do
-      url <- try $ S.drain $ fromParallel $
-                   (getURL 2 >>= throwM . Result)
-                |: (getURL 1 >>= throwM . Result)
-                |: S.nil
-      case url of
-          Left (e :: SomeException) -> print e
-          Right _ -> undefined
+data Result = Result String deriving Show
+instance Exception Result
+
+raceUsingExceptions = do
+    url <- try $ S.fold F.drain $ S.parSequence id $ S.fromList
+               [ (getURL 2 >>= throwM . Result)
+               , (getURL 1 >>= throwM . Result)
+               ]
+    case url of
+        Left (e :: SomeException) -> print e
+        Right _ -> undefined
 ```
 
 ### mapConcurrently
 
-There are many ways to map concurrently on a container and collect the results:
-
-You can create a concurrent stream from a `Foldable` container of monadic
-actions:
-
-```haskell
-  urls <- S.toList $ fromAhead $ S.fromFoldableM $ fmap getURL [1..3]
-```
-
-You can first convert a `Foldable` into a stream and then map an action on the
-stream concurrently:
+There are many ways to map concurrently on a container and collect the results.
+The recommended way is to first convert itinto a stream and then map an action
+on the stream concurrently:
 
 ```haskell
-  urls <- S.toList $ fromAhead $ S.mapM getURL $ foldMap return [1..3]
-```
-
-You can map a monadic action to a `Foldable` container to convert it into a
-stream and at the same time fold it:
-
-```haskell
-  urls <- S.toList $ fromAhead $ foldMap (S.fromEffect . getURL) [1..3]
+mapConcurrently = S.toList $ S.parMapM id getURL $ S.fromList [1..3]
 ```
 
 ### replicateConcurrently
 
 Streamly has not just the equivalent of `replicateConcurrently` which is
-`replicateM` but many more ways to generate concurrent streams, for example,
-`|:`, `unfoldrM`, `repeatM`, `iterateM`, `fromFoldableM` etc. See the
-[Streamly.Prelude](https://hackage.haskell.org/package/streamly/docs/Streamly-Prelude.html)
-module documentation for more details.
+`parReplicateM` but many more ways to generate concurrent streams, for example,
+`parRepeatM`, `parBuffered`, etc. See the `Streamly.Data.Stream.Prelude` module
+documentation for more details.
 
 ```haskell
-  xs <- S.toList $ fromParallel $ S.replicateM 2 $ getURL 1
+replicateConcurrently = S.toList $ S.parReplicateM id 2 $ getURL 1
 ```
 
 ### Functor
@@ -191,14 +175,15 @@ concurrently.
 To map serially just use `fmap`:
 
 ```haskell
-  xs <- S.toList $ fromParallel $ fmap (+1) $ return 1 |: return 2 |: S.nil
+serialMap = S.toList $ fmap (+1) (S.fromList [1, 2] :: S.Stream IO Int)
+
 ```
 
-To map a monadic action concurrently on all elements of the stream use `mapM`:
+To map a monadic action concurrently on all elements of the stream use `parMapM`:
 
 ```haskell
-  xs <- S.toList $ fromParallel $ S.mapM (\x -> return (x + 1))
-                           $ return 1 |: return 2 |: S.nil
+concurrentMap =
+    S.toList $ S.parMapM id (\x -> pure (x + 1) :: IO Int) $ S.fromList [1, 2]
 ```
 
 ### Semigroup