-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | an elementary streaming prelude and general stream type.
--   
--   This package contains two modules, <a>Streaming</a> and
--   <a>Streaming.Prelude</a>. The principal module,
--   <a>Streaming.Prelude</a>, exports an elementary streaming prelude
--   focused on a simple "source" or "producer" type, namely <tt>Stream (Of
--   a) m r</tt>. This is a sort of effectful version of <tt>([a],r)</tt>
--   in which successive elements of type <tt>a</tt> arise from some sort
--   of monadic action before the succession ends with a value of type
--   <tt>r</tt>. Everything in the library is organized to make programming
--   with this type as simple as possible, by the simple expedient of
--   making it as close to <tt>Prelude</tt> and <tt>Data.List</tt> as
--   possible. Thus for example the trivial program
--   
--   <pre>
--   &gt;&gt;&gt; S.sum $ S.take 3 (S.readLn :: Stream (Of Int) IO ())
--   1&lt;Enter&gt;
--   2&lt;Enter&gt;
--   3&lt;Enter&gt;
--   6 :&gt; ()
--   </pre>
--   
--   sums the first three valid integers from user input. Similarly,
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.map (map toUpper) $ S.take 2 S.stdinLn
--   hello&lt;Enter&gt;
--   HELLO
--   world!&lt;Enter&gt;
--   WORLD!
--   </pre>
--   
--   upper-cases the first two lines from stdin as they arise, and sends
--   them to stdout. And so on, with filtering, mapping, breaking,
--   chunking, zipping, unzipping, replicating and so forth: we program
--   with streams of <tt>Int</tt>s or <tt>String</tt>s directly as if they
--   constituted something like a list. That's because streams really do
--   constitute something like a list, and the associated operations can
--   mostly have the same names. (A few, like <tt>reverse</tt>, don't
--   stream and thus disappear; others like <tt>unzip</tt> are here given
--   properly streaming formulation for the first time.) And we everywhere
--   oppose "extracting a pure list from IO", which is the origin of
--   typical Haskell memory catastrophes. Basically any case where you are
--   tempted to use <tt>mapM</tt>, <tt>replicateM</tt>, <tt>traverse</tt>
--   or <tt>sequence</tt> with Haskell lists, you would do better to use
--   something like <tt>Stream (Of a) m r</tt>. The type signatures are a
--   little fancier, but the programs themselves are mostly the same. <i>In
--   fact, they are mostly simpler.</i> Thus, consider the trivial demo
--   program mentioned in <a>this SO question</a>
--   
--   <pre>
--   main = mapM newIORef [1..10^8::Int] &gt;&gt;= mapM readIORef &gt;&gt;= mapM_ print
--   </pre>
--   
--   The new user notices that this exhausts memory, and worries about the
--   efficiency of Haskell <tt>IORefs</tt>. But of course it exhausts
--   memory! Look what it says! The problem is immediately cured by writing
--   
--   <pre>
--   main = S.print $ S.mapM readIORef $ S.mapM newIORef $ S.each [1..10^8::Int]
--   </pre>
--   
--   which really does what the other program was meant to do, uses no more
--   memory than <tt>hello-world</tt>, <i>and is simpler anyway</i>, since
--   it doesn't involve the detour of "extracting a list from IO". Almost
--   every use of list <tt>mapM</tt>, <tt>replicateM</tt>,
--   <tt>traverse</tt> and <tt>sequence</tt> produces this problem on a
--   smaller scale. People get used to it, as if it were characteristic of
--   Haskell programs to use a lot of memory. But in truth "extracting a
--   list or sequence from IO" is mostly just bad practice pure and simple.
--   Of course, <tt>mapM</tt>, <tt>replicateM</tt>, <tt>traverse</tt> and
--   <tt>sequence</tt> make sense for lists, under certain conditions! But
--   <tt>unsafePerformIO</tt> also makes sense under certain conditions.
--   
--   The <a>Streaming</a> module exports the general type, <tt>Stream f m
--   r</tt>, which can be used to stream successive distinct steps
--   characterized by <i>any</i> functor <tt>f</tt>, though we are mostly
--   interested in organizing computations of the form <tt>Stream (Of a) m
--   r</tt>. The streaming-IO libraries have various devices for dealing
--   with effectful variants of <tt>[a]</tt> or <tt>([a],r)</tt> in which
--   the emergence of successive elements somehow depends on IO. But it is
--   only with the general type <tt>Stream f m r</tt>, or some equivalent,
--   that one can envisage (for example) the connected streaming of their
--   sorts of stream - as one makes lists of lists in the Haskell
--   <tt>Prelude</tt> and <tt>Data.List</tt>. One needs some such type if
--   we are to express properly streaming equivalents of e.g.
--   
--   <pre>
--   group :: Ord a =&gt; [a] -&gt; [[a]]
--   chunksOf :: Int -&gt; [a] -&gt; [[a]]
--   lines :: [Char] -&gt; [[Char]] -- but similarly with byte streams, etc.
--   </pre>
--   
--   to mention a few obviously desirable operations. (This is explained
--   more elaborately in the <a>readme</a> below.)
--   
--   One could of course throw something like the present <tt>Stream</tt>
--   type on top of a prior stream concept: this is how <tt>pipes</tt> and
--   <tt>pipes-group</tt> (which are very much our model here) use
--   <tt>FreeT</tt>. But once one grasps the iterable stream concept needed
--   to express those functions then one will also see that, with it, one
--   is <i>already</i> in possession of a complete elementary streaming
--   library - since one possesses <tt>Stream ((,) a) m r</tt> or
--   equivalently <tt>Stream (Of a) m r</tt>. This is the type of a
--   'generator' or 'producer' or 'source' or whatever you call an
--   effectful stream of items. <i>The present Streaming.Prelude is thus
--   the simplest streaming library that can replicate anything like the
--   API of the Prelude and Data.List</i>.
--   
--   The emphasis of the library is on interoperation; for the rest its
--   advantages are: extreme simplicity, re-use of intuitions the user has
--   gathered from mastery of <tt>Prelude</tt> and <tt>Data.List</tt>, and
--   a total and systematic rejection of type synonyms. The two conceptual
--   pre-requisites are some comprehension of monad transformers and some
--   familiarity with 'rank 2 types'. It is hoped that experimentation with
--   this simple material, starting with the ghci examples in
--   <tt>Streaming.Prelude</tt>, will give people who are new to these
--   concepts some intuition about their importance. The most fundamental
--   purpose of the library is to express elementary streaming ideas
--   without reliance on a complex framework, but in a way that integrates
--   transparently with the rest of Haskell, using ideas - e.g. rank 2
--   types, which are here implicit or explicit in most mapping - that the
--   user can carry elsewhere, rather than chaining her understanding to
--   the curiosities of a so-called streaming IO framework (as necessary as
--   that is for certain purposes.)
--   
--   See the <a>readme</a> below for further explanation, including the
--   examples linked there. Elementary usage can be divined from the ghci
--   examples in <tt>Streaming.Prelude</tt> and perhaps from this rough
--   beginning of a <a>tutorial</a>. Note also the <a>streaming
--   bytestring</a> and <a>streaming utils</a> packages. Questions about
--   usage can be put raised on StackOverflow with the tag
--   <tt>[haskell-streaming]</tt>, or as an issue on Github, or on the
--   <a>pipes list</a> (the package understands itself as part of the pipes
--   'ecosystem'.)
--   
--   The simplest form of interoperation with <a>pipes</a> is accomplished
--   with this isomorphism:
--   
--   <pre>
--   Pipes.unfoldr Streaming.next        :: Stream (Of a) m r   -&gt; Producer a m r
--   Streaming.unfoldr Pipes.next        :: Producer a m r      -&gt; Stream (Of a) m r
--   </pre>
--   
--   Interoperation with <a>io-streams</a> is thus:
--   
--   <pre>
--   Streaming.reread IOStreams.read     :: InputStream a       -&gt; Stream (Of a) IO ()
--   IOStreams.unfoldM Streaming.uncons  :: Stream (Of a) IO () -&gt; IO (InputStream a)
--   </pre>
--   
--   With <a>conduit</a> one might use, e.g.:
--   
--   <pre>
--   Conduit.unfoldM Streaming.uncons                        :: Stream (Of a) m () -&gt; Source m a
--   \str -&gt; Streaming.mapM_ Conduit.yield (hoist lift str)  :: Stream (Of o) m r  -&gt; ConduitM i o m r
--   \src -&gt; hoist lift str $$ Conduit.mapM_ Streaming.yield :: Source m a         -&gt; Stream (Of a) m ()
--   </pre>
--   
--   These conversions should never be more expensive than a single
--   <tt>&gt;-&gt;</tt> or <tt>=$=</tt>. The simplest interoperation with
--   regular Haskell lists is provided by, say
--   
--   <pre>
--   Streaming.each                                 :: [a]               -&gt; Stream (Of a) m ()
--   Streaming.toList_                              :: Stream (Of a) m r -&gt; m [a]
--   </pre>
--   
--   The latter of course accumulates the whole list in memory, and is
--   mostly what we are trying to avoid. Every use of <tt>Prelude.mapM
--   f</tt> should be reconceived as using the composition
--   <tt>Streaming.toList_ . Streaming.mapM f . Streaming.each</tt> with a
--   view to considering whether the accumulation required by
--   <tt>Streaming.toList_</tt> is really necessary.
--   
--   Here are the results of some <a>microbenchmarks</a> based on the
--   <a>benchmarks</a> included in the machines package:
--   
--   
--   Because these are microbenchmarks for individual functions, they
--   represent a sort of "worst case"; many other factors can influence the
--   speed of a complex program.
@package streaming
@version 0.2.3.1

module Data.Functor.Of

-- | A left-strict pair; the base functor for streams of individual
--   elements.
data Of a b
(:>) :: !a -> b -> Of a b
infixr 5 :>
instance GHC.Generics.Generic1 (Data.Functor.Of.Of a)
instance GHC.Generics.Generic (Data.Functor.Of.Of a b)
instance Data.Traversable.Traversable (Data.Functor.Of.Of a)
instance (GHC.Show.Show a, GHC.Show.Show b) => GHC.Show.Show (Data.Functor.Of.Of a b)
instance (GHC.Read.Read a, GHC.Read.Read b) => GHC.Read.Read (Data.Functor.Of.Of a b)
instance (GHC.Classes.Ord a, GHC.Classes.Ord b) => GHC.Classes.Ord (Data.Functor.Of.Of a b)
instance Data.Foldable.Foldable (Data.Functor.Of.Of a)
instance (GHC.Classes.Eq a, GHC.Classes.Eq b) => GHC.Classes.Eq (Data.Functor.Of.Of a b)
instance (Data.Data.Data a, Data.Data.Data b) => Data.Data.Data (Data.Functor.Of.Of a b)
instance (GHC.Base.Semigroup a, GHC.Base.Semigroup b) => GHC.Base.Semigroup (Data.Functor.Of.Of a b)
instance (GHC.Base.Monoid a, GHC.Base.Monoid b) => GHC.Base.Monoid (Data.Functor.Of.Of a b)
instance GHC.Base.Functor (Data.Functor.Of.Of a)
instance Data.Bifunctor.Bifunctor Data.Functor.Of.Of
instance Data.Bifoldable.Bifoldable Data.Functor.Of.Of
instance Data.Bitraversable.Bitraversable Data.Functor.Of.Of
instance GHC.Base.Monoid a => GHC.Base.Applicative (Data.Functor.Of.Of a)
instance GHC.Base.Monoid a => GHC.Base.Monad (Data.Functor.Of.Of a)
instance GHC.Show.Show a => Data.Functor.Classes.Show1 (Data.Functor.Of.Of a)
instance GHC.Classes.Eq a => Data.Functor.Classes.Eq1 (Data.Functor.Of.Of a)
instance GHC.Classes.Ord a => Data.Functor.Classes.Ord1 (Data.Functor.Of.Of a)
instance Data.Functor.Classes.Show2 Data.Functor.Of.Of
instance Data.Functor.Classes.Eq2 Data.Functor.Of.Of
instance Data.Functor.Classes.Ord2 Data.Functor.Of.Of

module Streaming.Internal
data Stream f m r
Step :: !f (Stream f m r) -> Stream f m r
Effect :: m (Stream f m r) -> Stream f m r
Return :: r -> Stream f m r

-- | Build a <tt>Stream</tt> by unfolding steps starting from a seed. See
--   also the specialized <a>unfoldr</a> in the prelude.
--   
--   <pre>
--   unfold inspect = id -- modulo the quotient we work with
--   unfold Pipes.next :: Monad m =&gt; Producer a m r -&gt; Stream ((,) a) m r
--   unfold (curry (:&gt;) . Pipes.next) :: Monad m =&gt; Producer a m r -&gt; Stream (Of a) m r
--   </pre>
unfold :: (Monad m, Functor f) => (s -> m (Either r (f s))) -> s -> Stream f m r

-- | Repeat a functorial layer, command or instruction a fixed number of
--   times.
--   
--   <pre>
--   replicates n = takes n . repeats
--   </pre>
replicates :: (Monad m, Functor f) => Int -> f () -> Stream f m ()

-- | Repeat a functorial layer (a "command" or "instruction") forever.
repeats :: (Monad m, Functor f) => f () -> Stream f m r

-- | Repeat an effect containing a functorial layer, command or instruction
--   forever.
repeatsM :: (Monad m, Functor f) => m (f ()) -> Stream f m r

-- | Wrap an effect that returns a stream
--   
--   <pre>
--   effect = join . lift
--   </pre>
effect :: (Monad m, Functor f) => m (Stream f m r) -> Stream f m r

-- | Wrap a new layer of a stream. So, e.g.
--   
--   <pre>
--   S.cons :: Monad m =&gt; a -&gt; Stream (Of a) m r -&gt; Stream (Of a) m r
--   S.cons a str = wrap (a :&gt; str)
--   </pre>
--   
--   and, recursively:
--   
--   <pre>
--   S.each :: (Monad m, Foldable t) =&gt; t a -&gt; Stream (Of a) m ()
--   S.each = foldr (\a b -&gt; wrap (a :&gt; b)) (return ())
--   </pre>
--   
--   The two operations
--   
--   <pre>
--   wrap :: (Monad m, Functor f )   =&gt; f (Stream f m r) -&gt; Stream f m r
--   effect :: (Monad m, Functor f ) =&gt; m (Stream f m r) -&gt; Stream f m r
--   </pre>
--   
--   are fundamental. We can define the parallel operations <tt>yields</tt>
--   and <tt>lift</tt> in terms of them
--   
--   <pre>
--   yields :: (Monad m, Functor f )  =&gt; f r -&gt; Stream f m r
--   yields = wrap . fmap return
--   lift ::  (Monad m, Functor f )   =&gt; m r -&gt; Stream f m r
--   lift = effect . fmap return
--   </pre>
wrap :: (Monad m, Functor f) => f (Stream f m r) -> Stream f m r

-- | <tt>yields</tt> is like <tt>lift</tt> for items in the streamed
--   functor. It makes a singleton or one-layer succession.
--   
--   <pre>
--   lift :: (Monad m, Functor f)    =&gt; m r -&gt; Stream f m r
--   yields ::  (Monad m, Functor f) =&gt; f r -&gt; Stream f m r
--   </pre>
--   
--   Viewed in another light, it is like a functor-general version of
--   <tt>yield</tt>:
--   
--   <pre>
--   S.yield a = yields (a :&gt; ())
--   </pre>
yields :: (Monad m, Functor f) => f r -> Stream f m r

-- | Reflect a church-encoded stream; cp. <tt>GHC.Exts.build</tt>
--   
--   <pre>
--   streamFold return_ effect_ step_ (streamBuild psi) = psi return_ effect_ step_
--   </pre>
streamBuild :: (forall b. (r -> b) -> (m b -> b) -> (f b -> b) -> b) -> Stream f m r

-- | Construct an infinite stream by cycling a finite one
--   
--   <pre>
--   cycles = forever
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 
--   </pre>
cycles :: (Monad m, Functor f) => Stream f m () -> Stream f m r
delays :: (MonadIO m, Applicative f) => Double -> Stream f m r

-- | <a>never</a> interleaves the pure applicative action with the return
--   of the monad forever. It is the <a>empty</a> of the <a>Alternative</a>
--   instance, thus
--   
--   <pre>
--   never &lt;|&gt; a = a
--   a &lt;|&gt; never = a
--   </pre>
--   
--   and so on. If w is a monoid then <tt>never :: Stream (Of w) m r</tt>
--   is the infinite sequence of <a>mempty</a>, and <tt>str1 &lt;|&gt;
--   str2</tt> appends the elements monoidally until one of streams ends.
--   Thus we have, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.take 2 $ S.stdinLn &lt;|&gt; S.repeat " " &lt;|&gt; S.stdinLn  &lt;|&gt; S.repeat " " &lt;|&gt; S.stdinLn
--   1&lt;Enter&gt;
--   2&lt;Enter&gt;
--   3&lt;Enter&gt;
--   1 2 3
--   4&lt;Enter&gt;
--   5&lt;Enter&gt;
--   6&lt;Enter&gt;
--   4 5 6
--   </pre>
--   
--   This is equivalent to
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.take 2 $ foldr (&lt;|&gt;) never [S.stdinLn, S.repeat " ", S.stdinLn, S.repeat " ", S.stdinLn ]
--   </pre>
--   
--   Where <tt>f</tt> is a monad, <tt>(&lt;|&gt;)</tt> sequences the
--   conjoined streams stepwise. See the definition of <tt>paste</tt>
--   <a>here</a>, where the separate steps are bytestreams corresponding to
--   the lines of a file.
--   
--   Given, say,
--   
--   <pre>
--   data Branch r = Branch r r deriving Functor  -- add obvious applicative instance
--   </pre>
--   
--   then <tt>never :: Stream Branch Identity r</tt> is the pure infinite
--   binary tree with (inaccessible) <tt>r</tt>s in its leaves. Given two
--   binary trees, <tt>tree1 &lt;|&gt; tree2</tt> intersects them,
--   preserving the leaves that came first, so <tt>tree1 &lt;|&gt; never =
--   tree1</tt>
--   
--   <tt>Stream Identity m r</tt> is an action in <tt>m</tt> that is
--   indefinitely delayed. Such an action can be constructed with e.g.
--   <a>untilJust</a>.
--   
--   <pre>
--   untilJust :: (Monad m, Applicative f) =&gt; m (Maybe r) -&gt; Stream f m r
--   </pre>
--   
--   Given two such items, <tt>&lt;|&gt;</tt> instance races them. It is
--   thus the iterative monad transformer specially defined in
--   <a>Control.Monad.Trans.Iter</a>
--   
--   So, for example, we might write
--   
--   <pre>
--   &gt;&gt;&gt; let justFour str = if length str == 4 then Just str else Nothing
--   
--   &gt;&gt;&gt; let four = untilJust (fmap justFour getLine)
--   
--   &gt;&gt;&gt; run four
--   one&lt;Enter&gt;
--   two&lt;Enter&gt;
--   three&lt;Enter&gt;
--   four&lt;Enter&gt;
--   "four"
--   </pre>
--   
--   The <a>Alternative</a> instance in <a>Control.Monad.Trans.Free</a> is
--   avowedly wrong, though no explanation is given for this.
never :: (Monad m, Applicative f) => Stream f m r

-- | Repeat a
untilJust :: (Monad m, Applicative f) => m (Maybe r) -> Stream f m r

-- | Interpolate a layer at each segment. This specializes to e.g.
--   
--   <pre>
--   intercalates :: (Monad m, Functor f) =&gt; Stream f m () -&gt; Stream (Stream f m) m r -&gt; Stream f m r
--   </pre>
intercalates :: (Monad m, Monad (t m), MonadTrans t) => t m x -> Stream (t m) m r -> t m r

-- | Dissolves the segmentation into layers of <tt>Stream f m</tt> layers.
concats :: (Monad m, Functor f) => Stream (Stream f m) m r -> Stream f m r

-- | Specialized fold following the usage of
--   <tt>Control.Monad.Trans.Free</tt>
--   
--   <pre>
--   iterT alg = streamFold return join alg
--   iterT alg = runIdentityT . iterTM (IdentityT . alg . fmap runIdentityT)
--   </pre>
iterT :: (Functor f, Monad m) => (f (m a) -> m a) -> Stream f m a -> m a

-- | Specialized fold following the usage of
--   <tt>Control.Monad.Trans.Free</tt>
--   
--   <pre>
--   iterTM alg = streamFold return (join . lift)
--   iterTM alg = iterT alg . hoist lift
--   </pre>
iterTM :: (Functor f, Monad m, MonadTrans t, Monad (t m)) => (f (t m a) -> t m a) -> Stream f m a -> t m a

-- | Map a stream to its church encoding; compare <tt>Data.List.foldr</tt>.
--   <a>destroyExposed</a> may be more efficient in some cases when
--   applicable, but it is less safe.
--   
--   <pre>
--   destroy s construct eff done
--     = eff . iterT (return . construct . fmap eff) . fmap done $ s
--   
--   </pre>
destroy :: (Functor f, Monad m) => Stream f m r -> (f b -> b) -> (m b -> b) -> (r -> b) -> b

-- | <a>streamFold</a> reorders the arguments of <a>destroy</a> to be more
--   akin to <tt>foldr</tt> It is more convenient to query in ghci to
--   figure out what kind of 'algebra' you need to write.
--   
--   <pre>
--   &gt;&gt;&gt; :t streamFold return join
--   (Monad m, Functor f) =&gt;
--        (f (m a) -&gt; m a) -&gt; Stream f m a -&gt; m a        -- iterT
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t streamFold return (join . lift)
--   (Monad m, Monad (t m), Functor f, MonadTrans t) =&gt;
--        (f (t m a) -&gt; t m a) -&gt; Stream f m a -&gt; t m a  -- iterTM
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t streamFold return effect
--   (Monad m, Functor f, Functor g) =&gt;
--        (f (Stream g m r) -&gt; Stream g m r) -&gt; Stream f m r -&gt; Stream g m r
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t \f -&gt; streamFold return effect (wrap . f)
--   (Monad m, Functor f, Functor g) =&gt;
--        (f (Stream g m a) -&gt; g (Stream g m a))
--        -&gt; Stream f m a -&gt; Stream g m a                 -- maps
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t \f -&gt; streamFold return effect (effect . fmap wrap . f)
--   (Monad m, Functor f, Functor g) =&gt;
--        (f (Stream g m a) -&gt; m (g (Stream g m a)))
--        -&gt; Stream f m a -&gt; Stream g m a                 -- mapped
--   </pre>
--   
--   <pre>
--   streamFold done eff construct
--      = eff . iterT (return . construct . fmap eff) . fmap done
--   </pre>
streamFold :: (Functor f, Monad m) => (r -> b) -> (m b -> b) -> (f b -> b) -> Stream f m r -> b

-- | Inspect the first stage of a freely layered sequence. Compare
--   <tt>Pipes.next</tt> and the replica <tt>Streaming.Prelude.next</tt>.
--   This is the <tt>uncons</tt> for the general <a>unfold</a>.
--   
--   <pre>
--   unfold inspect = id
--   Streaming.Prelude.unfoldr StreamingPrelude.next = id
--   </pre>
inspect :: Monad m => Stream f m r -> m (Either r (f (Stream f m r)))

-- | Map layers of one functor to another with a transformation. Compare
--   hoist, which has a similar effect on the <tt>monadic</tt> parameter.
--   
--   <pre>
--   maps id = id
--   maps f . maps g = maps (f . g)
--   </pre>
maps :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation involving
--   the base monad. <a>maps</a> is more fundamental than <tt>mapsM</tt>,
--   which is best understood as a convenience for effecting this frequent
--   composition:
--   
--   <pre>
--   mapsM phi = decompose . maps (Compose . phi)
--   </pre>
--   
--   The streaming prelude exports the same function under the better name
--   <tt>mapped</tt>, which overlaps with the lens libraries.
mapsM :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation. Compare
--   hoist, which has a similar effect on the <tt>monadic</tt> parameter.
--   
--   <pre>
--   mapsPost id = id
--   mapsPost f . mapsPost g = mapsPost (f . g)
--   mapsPost f = maps f
--   </pre>
--   
--   <tt>mapsPost</tt> is essentially the same as <a>maps</a>, but it
--   imposes a <a>Functor</a> constraint on its target functor rather than
--   its source functor. It should be preferred if <a>fmap</a> is cheaper
--   for the target functor than for the source functor.
mapsPost :: forall m f g r. (Monad m, Functor g) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation involving
--   the base monad. <tt>mapsMPost</tt> is essentially the same as
--   <a>mapsM</a>, but it imposes a <a>Functor</a> constraint on its target
--   functor rather than its source functor. It should be preferred if
--   <a>fmap</a> is cheaper for the target functor than for the source
--   functor.
--   
--   <tt>mapsPost</tt> is more fundamental than <tt>mapsMPost</tt>, which
--   is best understood as a convenience for effecting this frequent
--   composition:
--   
--   <pre>
--   mapsMPost phi = decompose . mapsPost (Compose . phi)
--   </pre>
--   
--   The streaming prelude exports the same function under the better name
--   <tt>mappedPost</tt>, which overlaps with the lens libraries.
mapsMPost :: forall m f g r. (Monad m, Functor g) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | A less-efficient version of <a>hoist</a> that works properly even when
--   its argument is not a monad morphism.
--   
--   <pre>
--   hoistUnexposed = hoist . unexposed
--   </pre>
hoistUnexposed :: (Monad m, Functor f) => (forall a. m a -> n a) -> Stream f m r -> Stream f n r

-- | Rearrange a succession of layers of the form <tt>Compose m (f x)</tt>.
--   
--   we could as well define <tt>decompose</tt> by <tt>mapsM</tt>:
--   
--   <pre>
--   decompose = mapped getCompose
--   </pre>
--   
--   but <tt>mapped</tt> is best understood as:
--   
--   <pre>
--   mapped phi = decompose . maps (Compose . phi)
--   </pre>
--   
--   since <tt>maps</tt> and <tt>hoist</tt> are the really fundamental
--   operations that preserve the shape of the stream:
--   
--   <pre>
--   maps  :: (Monad m, Functor f) =&gt; (forall x. f x -&gt; g x) -&gt; Stream f m r -&gt; Stream g m r
--   hoist :: (Monad m, Functor f) =&gt; (forall a. m a -&gt; n a) -&gt; Stream f m r -&gt; Stream f n r
--   </pre>
decompose :: (Monad m, Functor f) => Stream (Compose m f) m r -> Stream f m r

-- | Map each layer to an effect, and run them all.
mapsM_ :: (Functor f, Monad m) => (forall x. f x -> m x) -> Stream f m r -> m r

-- | Run the effects in a stream that merely layers effects.
run :: Monad m => Stream m m r -> m r

-- | Make it possible to 'run' the underlying transformed monad.
distribute :: (Monad m, Functor f, MonadTrans t, MFunctor t, Monad (t (Stream f m))) => Stream f (t m) r -> t (Stream f m) r

-- | Group layers in an alternating stream into adjoining sub-streams of
--   one type or another.
groups :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream (Sum (Stream f m) (Stream g m)) m r

-- | Break a stream into substreams each with n functorial layers.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ mapped S.sum $ chunksOf 2 $ each [1,1,1,1,1]
--   2
--   2
--   1
--   </pre>
chunksOf :: (Monad m, Functor f) => Int -> Stream f m r -> Stream (Stream f m) m r

-- | Split a succession of layers after some number, returning a streaming
--   or effectful pair.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.print $ S.splitAt 1 $ each [1..3]
--   1
--   
--   &gt;&gt;&gt; S.print rest
--   2
--   3
--   </pre>
--   
--   <pre>
--   splitAt 0 = return
--   splitAt n &gt;=&gt; splitAt m = splitAt (m+n)
--   </pre>
--   
--   Thus, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.print $ splitsAt 2 &gt;=&gt; splitsAt 2 $ each [1..5]
--   1
--   2
--   3
--   4
--   
--   &gt;&gt;&gt; S.print rest
--   5
--   </pre>
splitsAt :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Stream f m r)
takes :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m ()
cutoff :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Maybe r)

-- | Zip two streams together. The <a>zipsWith'</a> function should
--   generally be preferred for efficiency.
zipsWith :: forall f g h m r. (Monad m, Functor h) => (forall x y. f x -> g y -> h (x, y)) -> Stream f m r -> Stream g m r -> Stream h m r

-- | Zip two streams together.
zipsWith' :: forall f g h m r. Monad m => (forall x y p. (x -> y -> p) -> f x -> g y -> h p) -> Stream f m r -> Stream g m r -> Stream h m r
zips :: (Monad m, Functor f, Functor g) => Stream f m r -> Stream g m r -> Stream (Compose f g) m r
unzips :: (Monad m, Functor f, Functor g) => Stream (Compose f g) m r -> Stream f (Stream g m) r

-- | Interleave functor layers, with the effects of the first preceding the
--   effects of the second. When the first stream runs out, any remaining
--   effects in the second are ignored.
--   
--   <pre>
--   interleaves = zipsWith (liftA2 (,))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let paste = \a b -&gt; interleaves (Q.lines a) (maps (Q.cons' '\t') (Q.lines b))
--   
--   &gt;&gt;&gt; Q.stdout $ Q.unlines $ paste "hello\nworld\n" "goodbye\nworld\n"
--   hello	goodbye
--   world	world
--   </pre>
interleaves :: (Monad m, Applicative h) => Stream h m r -> Stream h m r -> Stream h m r

-- | Given a stream on a sum of functors, make it a stream on the left
--   functor, with the streaming on the other functor as the governing
--   monad. This is useful for acting on one or the other functor with a
--   fold, leaving the other material for another treatment. It generalizes
--   <a>partitionEithers</a>, but actually streams properly.
--   
--   <pre>
--   &gt;&gt;&gt; let odd_even = S.maps (S.distinguish even) $ S.each [1..10::Int]
--   
--   &gt;&gt;&gt; :t separate odd_even
--   separate odd_even
--     :: Monad m =&gt; Stream (Of Int) (Stream (Of Int) m) ()
--   </pre>
--   
--   Now, for example, it is convenient to fold on the left and right
--   values separately:
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.toList $ separate odd_even
--   [2,4,6,8,10] :&gt; ([1,3,5,7,9] :&gt; ())
--   </pre>
--   
--   Or we can write them to separate files or whatever:
--   
--   <pre>
--   &gt;&gt;&gt; S.writeFile "even.txt" . S.show $ S.writeFile "odd.txt" . S.show $ S.separate odd_even
--   
--   &gt;&gt;&gt; :! cat even.txt
--   2
--   4
--   6
--   8
--   10
--   
--   &gt;&gt;&gt; :! cat odd.txt
--   1
--   3
--   5
--   7
--   9
--   </pre>
--   
--   Of course, in the special case of <tt>Stream (Of a) m r</tt>, we can
--   achieve the above effects more simply by using <a>copy</a>
--   
--   <pre>
--   &gt;&gt;&gt; S.toList . S.filter even $ S.toList . S.filter odd $ S.copy $ each [1..10::Int]
--   [2,4,6,8,10] :&gt; ([1,3,5,7,9] :&gt; ())
--   </pre>
--   
--   But <a>separate</a> and <a>unseparate</a> are functor-general.
separate :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream f (Stream g m) r
unseparate :: (Monad m, Functor f, Functor g) => Stream f (Stream g m) r -> Stream (Sum f g) m r

-- | If <tt>Of</tt> had a <tt>Comonad</tt> instance, then we'd have
--   
--   <pre>
--   copy = expand extend
--   </pre>
--   
--   See <a>expandPost</a> for a version that requires a <tt>Functor g</tt>
--   instance instead.
expand :: (Monad m, Functor f) => (forall a b. (g a -> b) -> f a -> h b) -> Stream f m r -> Stream g (Stream h m) r

-- | If <tt>Of</tt> had a <tt>Comonad</tt> instance, then we'd have
--   
--   <pre>
--   copy = expandPost extend
--   </pre>
--   
--   See <a>expand</a> for a version that requires a <tt>Functor f</tt>
--   instance instead.
expandPost :: (Monad m, Functor g) => (forall a b. (g a -> b) -> f a -> h b) -> Stream f m r -> Stream g (Stream h m) r

-- | Swap the order of functors in a sum of functors.
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.print $ separate $ maps S.switch $ maps (S.distinguish (=='a')) $ S.each "banana"
--   'a'
--   'a'
--   'a'
--   "bnn" :&gt; ()
--   
--   &gt;&gt;&gt; S.toList $ S.print $ separate $ maps (S.distinguish (=='a')) $ S.each "banana"
--   'b'
--   'n'
--   'n'
--   "aaa" :&gt; ()
--   </pre>
switch :: Sum f g r -> Sum g f r

-- | This is akin to the <tt>observe</tt> of <tt>Pipes.Internal</tt> . It
--   reeffects the layering in instances of <tt>Stream f m r</tt> so that
--   it replicates that of <tt>FreeT</tt>.
unexposed :: (Functor f, Monad m) => Stream f m r -> Stream f m r

-- | The same as <a>hoist</a>, but explicitly named to indicate that it is
--   not entirely safe. In particular, its argument must be a monad
--   morphism.
hoistExposed :: (Functor m, Functor f) => (forall b. m b -> n b) -> Stream f m a -> Stream f n a

-- | The same as <a>hoistExposed</a>, but with a <a>Functor</a> constraint
--   on the target rather than the source. This must be used only with a
--   monad morphism.
hoistExposedPost :: (Functor n, Functor f) => (forall b. m b -> n b) -> Stream f m a -> Stream f n a

-- | <i>Deprecated: Use maps instead.</i>
mapsExposed :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r

-- | <i>Deprecated: Use mapsM instead.</i>
mapsMExposed :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | Map a stream directly to its church encoding; compare
--   <tt>Data.List.foldr</tt> It permits distinctions that should be
--   hidden, as can be seen from e.g.
--   
--   <pre>
--   isPure stream = destroyExposed (const True) (const False) (const True)
--   </pre>
--   
--   and similar nonsense. The crucial constraint is that the <tt>m x -&gt;
--   x</tt> argument is an <i>Eilenberg-Moore algebra</i>. See Atkey,
--   "Reasoning about Stream Processing with Effects"
--   
--   When in doubt, use <a>destroy</a> instead.
destroyExposed :: (Functor f, Monad m) => Stream f m r -> (f b -> b) -> (m b -> b) -> (r -> b) -> b
instance (GHC.Base.Monad m, GHC.Show.Show r, GHC.Show.Show (m Streaming.Internal.ShowSWrapper), GHC.Show.Show (f (Streaming.Internal.Stream f m r))) => GHC.Show.Show (Streaming.Internal.Stream f m r)
instance (GHC.Base.Monad m, GHC.Base.Functor f, GHC.Show.Show (m Streaming.Internal.ShowSWrapper), GHC.Show.Show (f Streaming.Internal.ShowSWrapper)) => Data.Functor.Classes.Show1 (Streaming.Internal.Stream f m)
instance GHC.Show.Show Streaming.Internal.ShowSWrapper
instance (GHC.Base.Monad m, GHC.Classes.Eq (m (Data.Either.Either r (f (Streaming.Internal.Stream f m r))))) => GHC.Classes.Eq (Streaming.Internal.Stream f m r)
instance (GHC.Base.Monad m, GHC.Classes.Ord (m (Data.Either.Either r (f (Streaming.Internal.Stream f m r))))) => GHC.Classes.Ord (Streaming.Internal.Stream f m r)
instance (GHC.Base.Monad m, GHC.Base.Functor f, Data.Functor.Classes.Eq1 m, Data.Functor.Classes.Eq1 f) => Data.Functor.Classes.Eq1 (Streaming.Internal.Stream f m)
instance (GHC.Base.Monad m, GHC.Base.Functor f, Data.Functor.Classes.Ord1 m, Data.Functor.Classes.Ord1 f) => Data.Functor.Classes.Ord1 (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, GHC.Base.Monad m) => GHC.Base.Functor (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, GHC.Base.Monad m) => GHC.Base.Monad (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, Control.Monad.Fail.MonadFail m) => Control.Monad.Fail.MonadFail (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, GHC.Base.Monad m) => GHC.Base.Applicative (Streaming.Internal.Stream f m)
instance (GHC.Base.Applicative f, GHC.Base.Monad m) => GHC.Base.Alternative (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, GHC.Base.Monad m, GHC.Base.Semigroup w) => GHC.Base.Semigroup (Streaming.Internal.Stream f m w)
instance (GHC.Base.Functor f, GHC.Base.Monad m, GHC.Base.Monoid w) => GHC.Base.Monoid (Streaming.Internal.Stream f m w)
instance (GHC.Base.Applicative f, GHC.Base.Monad m) => GHC.Base.MonadPlus (Streaming.Internal.Stream f m)
instance GHC.Base.Functor f => Control.Monad.Trans.Class.MonadTrans (Streaming.Internal.Stream f)
instance GHC.Base.Functor f => Control.Monad.Morph.MFunctor (Streaming.Internal.Stream f)
instance GHC.Base.Functor f => Control.Monad.Morph.MMonad (Streaming.Internal.Stream f)
instance (Control.Monad.IO.Class.MonadIO m, GHC.Base.Functor f) => Control.Monad.IO.Class.MonadIO (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, Control.Monad.Reader.Class.MonadReader r m) => Control.Monad.Reader.Class.MonadReader r (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, Control.Monad.State.Class.MonadState s m) => Control.Monad.State.Class.MonadState s (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, Control.Monad.Error.Class.MonadError e m) => Control.Monad.Error.Class.MonadError e (Streaming.Internal.Stream f m)


-- | The names exported by this module are closely modeled on those in
--   <tt>Prelude</tt> and <tt>Data.List</tt>, but also on
--   <a>Pipes.Prelude</a>, <a>Pipes.Group</a> and <a>Pipes.Parse</a>. The
--   module may be said to give independent expression to the conception of
--   Producer / Source / Generator manipulation articulated in the latter
--   two modules. Because we dispense with piping and conduiting, the
--   distinction between all of these modules collapses. Some things are
--   lost but much is gained: on the one hand, everything comes much closer
--   to ordinary beginning Haskell programming and, on the other, acquires
--   the plasticity of programming directly with a general free monad type.
--   The leading type, <tt>Stream (Of a) m r</tt> is chosen to permit an
--   api that is as close as possible to that of <tt>Data.List</tt> and the
--   <tt>Prelude</tt>.
--   
--   Import qualified thus:
--   
--   <pre>
--   import Streaming
--   import qualified Streaming.Prelude as S
--   </pre>
--   
--   For the examples below, one sometimes needs
--   
--   <pre>
--   import Streaming.Prelude (each, yield, next, mapped, stdoutLn, stdinLn)
--   import Data.Function ((&amp;))
--   </pre>
--   
--   Other libraries that come up in passing are
--   
--   <pre>
--   import qualified Control.Foldl as L -- cabal install foldl
--   import qualified Pipes as P
--   import qualified Pipes.Prelude as P
--   import qualified System.IO as IO
--   </pre>
--   
--   Here are some correspondences between the types employed here and
--   elsewhere:
--   
--   <pre>
--                 streaming             |            pipes               |       conduit       |  io-streams
--   -------------------------------------------------------------------------------------------------------------------
--   Stream (Of a) m ()                  | Producer a m ()                | Source m a          | InputStream a
--                                       | ListT m a                      | ConduitM () o m ()  | Generator r ()
--   -------------------------------------------------------------------------------------------------------------------
--   Stream (Of a) m r                   | Producer a m r                 | ConduitM () o m r   | Generator a r
--   -------------------------------------------------------------------------------------------------------------------
--   Stream (Of a) m (Stream (Of a) m r) | Producer a m (Producer a m r)  |
--   --------------------------------------------------------------------------------------------------------------------
--   Stream (Stream (Of a) m) r          | FreeT (Producer a m) m r       |
--   --------------------------------------------------------------------------------------------------------------------
--   --------------------------------------------------------------------------------------------------------------------
--   ByteString m ()                     | Producer ByteString m ()       | Source m ByteString  | InputStream ByteString
--   --------------------------------------------------------------------------------------------------------------------
--   </pre>
module Streaming.Prelude

-- | A left-strict pair; the base functor for streams of individual
--   elements.
data Of a b
(:>) :: !a -> b -> Of a b
infixr 5 :>

-- | A singleton stream
--   
--   <pre>
--   &gt;&gt;&gt; stdoutLn $ yield "hello"
--   hello
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.sum $ do {yield 1; yield 2; yield 3}
--   6 :&gt; ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let number = lift (putStrLn "Enter a number:") &gt;&gt; lift readLn &gt;&gt;= yield :: Stream (Of Int) IO ()
--   
--   &gt;&gt;&gt; S.toList $ do {number; number; number}
--   Enter a number:
--   1&lt;Enter&gt;
--   Enter a number:
--   2&lt;Enter&gt;
--   Enter a number:
--   3&lt;Enter&gt;
--   [1,2,3] :&gt; ()
--   </pre>
yield :: Monad m => a -> Stream (Of a) m ()

-- | Stream the elements of a pure, foldable container.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ each [1..3]
--   1
--   2
--   3
--   </pre>
each :: (Monad m, Foldable f) => f a -> Stream (Of a) m ()

-- | View standard input as a <tt>Stream (Of String) m r</tt>. By contrast,
--   <a>stdoutLn</a> renders a <tt>Stream (Of String) m r</tt> to standard
--   output. The names follow <tt>Pipes.Prelude</tt>
--   
--   <pre>
--   &gt;&gt;&gt; stdoutLn stdinLn
--   hello&lt;Enter&gt;
--   hello
--   world&lt;Enter&gt;
--   world
--   ^CInterrupted.
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stdoutLn $ S.map reverse stdinLn
--   hello&lt;Enter&gt;
--   olleh
--   world&lt;Enter&gt;
--   dlrow
--   ^CInterrupted.
--   </pre>
stdinLn :: MonadIO m => Stream (Of String) m ()

-- | Read values from <a>stdin</a>, ignoring failed parses.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XTypeApplications
--   
--   &gt;&gt;&gt; S.sum $ S.take 2 (S.readLn @IO @Int)
--   10&lt;Enter&gt;
--   12&lt;Enter&gt;
--   22 :&gt; ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.take 2 (S.readLn @IO @Int)
--   10&lt;Enter&gt;
--   1@#$%^&amp;*\&lt;Enter&gt;
--   12&lt;Enter&gt;
--   [10,12] :&gt; ()
--   </pre>
readLn :: (MonadIO m, Read a) => Stream (Of a) m ()

-- | Read <a>String</a>s from a <a>Handle</a> using <a>hGetLine</a>
--   
--   Terminates on end of input
--   
--   <pre>
--   &gt;&gt;&gt; IO.withFile "/usr/share/dict/words" IO.ReadMode $ S.stdoutLn . S.take 3 . S.drop 50000 . S.fromHandle
--   deflagrator
--   deflate
--   deflation
--   </pre>
fromHandle :: MonadIO m => Handle -> Stream (Of String) m ()

-- | Read the lines of a file, using a function of the type:
--   '<tt><a>Stream</a> (<a>Of</a> <a>String</a>) <a>IO</a> () -&gt;
--   <a>IO</a> a</tt>' to turn the stream into a value of type '<a>IO</a>
--   a'.
--   
--   <pre>
--   &gt;&gt;&gt; S.writeFile "lines.txt" $ S.take 2 S.stdinLn
--   hello&lt;Enter&gt;
--   world&lt;Enter&gt;
--   
--   &gt;&gt;&gt; S.readFile "lines.txt" S.print
--   "hello"
--   "world"
--   </pre>
readFile :: FilePath -> (Stream (Of String) IO () -> IO a) -> IO a

-- | Iterate a pure function from a seed value, streaming the results
--   forever
iterate :: Monad m => (a -> a) -> a -> Stream (Of a) m r

-- | Iterate a monadic function from a seed value, streaming the results
--   forever
iterateM :: Monad m => (a -> m a) -> m a -> Stream (Of a) m r

-- | Repeat an element <i>ad inf.</i> .
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.take 3 $ S.repeat 1
--   1
--   1
--   1
--   </pre>
repeat :: Monad m => a -> Stream (Of a) m r

-- | Repeat a monadic action <i>ad inf.</i>, streaming its results.
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.take 2 $ repeatM getLine
--   one&lt;Enter&gt;
--   two&lt;Enter&gt;
--   ["one","two"]
--   </pre>
repeatM :: Monad m => m a -> Stream (Of a) m r

-- | Repeat an element several times.
replicate :: Monad m => Int -> a -> Stream (Of a) m ()
untilLeft :: Monad m => m (Either r a) -> Stream (Of a) m r
untilRight :: Monad m => m (Either a r) -> Stream (Of a) m r

-- | Cycle repeatedly through the layers of a stream, <i>ad inf.</i> This
--   function is functor-general
--   
--   <pre>
--   cycle = forever
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.print $ S.splitAt 3 $ S.cycle (yield True &gt;&gt; yield False)
--   True
--   False
--   True
--   
--   &gt;&gt;&gt; S.print $ S.take 3 rest
--   False
--   True
--   False
--   </pre>
cycle :: (Monad m, Functor f) => Stream f m r -> Stream f m s

-- | Repeat an action several times, streaming its results.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.replicateM 2 getCurrentTime
--   2015-08-18 00:57:36.124508 UTC
--   2015-08-18 00:57:36.124785 UTC
--   </pre>
replicateM :: Monad m => Int -> m a -> Stream (Of a) m ()

-- | An infinite stream of enumerable values, starting from a given value.
--   It is the same as <tt>S.iterate succ</tt>. Because their return type
--   is polymorphic, <tt>enumFrom</tt>, <tt>enumFromThen</tt> and
--   <tt>iterate</tt> are useful with functions like <tt>zip</tt> and
--   <tt>zipWith</tt>, which require the zipped streams to have the same
--   return type.
--   
--   For example, with <tt>each [1..]</tt> the following bit of
--   connect-and-resume would not compile:
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.print $ S.zip (S.enumFrom 1) $ S.splitAt 3 $ S.each ['a'..'z']
--   (1,'a')
--   (2,'b')
--   (3,'c')
--   
--   &gt;&gt;&gt; S.print $ S.take 3 rest
--   'd'
--   'e'
--   'f'
--   </pre>
enumFrom :: (Monad m, Enum n) => n -> Stream (Of n) m r

-- | An infinite sequence of enumerable values at a fixed distance,
--   determined by the first and second values. See the discussion of
--   <a>enumFrom</a>
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.take 3 $ S.enumFromThen 100 200
--   100
--   200
--   300
--   </pre>
enumFromThen :: (Monad m, Enum a) => a -> a -> Stream (Of a) m r

-- | Build a <tt>Stream</tt> by unfolding steps starting from a seed. In
--   particular note that <tt>S.unfoldr S.next = id</tt>.
--   
--   The seed can of course be anything, but this is one natural way to
--   consume a <tt>pipes</tt> <a>Producer</a>. Consider:
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.take 2 $ S.unfoldr Pipes.next Pipes.stdinLn
--   hello&lt;Enter&gt;
--   hello
--   goodbye&lt;Enter&gt;
--   goodbye
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.unfoldr Pipes.next (Pipes.stdinLn &gt;-&gt; Pipes.take 2)
--   hello&lt;Enter&gt;
--   hello
--   goodbye&lt;Enter&gt;
--   goodbye
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.effects $ S.unfoldr Pipes.next (Pipes.stdinLn &gt;-&gt; Pipes.take 2 &gt;-&gt; Pipes.stdoutLn)
--   hello&lt;Enter&gt;
--   hello
--   goodbye&lt;Enter&gt;
--   goodbye
--   </pre>
--   
--   <tt>Pipes.unfoldr S.next</tt> similarly unfolds a
--   <tt>Pipes.Producer</tt> from a stream.
unfoldr :: Monad m => (s -> m (Either r (a, s))) -> s -> Stream (Of a) m r

-- | Write <a>String</a>s to <a>stdout</a> using <a>putStrLn</a>;
--   terminates on a broken output pipe (The name and implementation are
--   modelled on the <tt>Pipes.Prelude</tt> <tt>stdoutLn</tt>).
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.take 3 $ S.each $ words "one two three four five"
--   one
--   two
--   three
--   </pre>
stdoutLn :: MonadIO m => Stream (Of String) m () -> m ()

-- | Write <a>String</a>s to <a>stdout</a> using <a>putStrLn</a>
--   
--   Unlike <tt>stdoutLn</tt>, <tt>stdoutLn'</tt> does not handle a broken
--   output pipe. Thus it can have a polymorphic return value, rather than
--   <tt>()</tt>, and this kind of "connect and resume" is possible:
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.stdoutLn' $ S.show $ S.splitAt 3 (each [1..5])
--   1
--   2
--   3
--   
--   &gt;&gt;&gt; S.toList rest
--   [4,5] :&gt; ()
--   </pre>
stdoutLn' :: MonadIO m => Stream (Of String) m r -> m r

-- | Reduce a stream to its return value with a monadic action.
--   
--   <pre>
--   &gt;&gt;&gt; S.mapM_ Prelude.print $ each [1..3]
--   1
--   2
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.mapM_ Prelude.print $ S.splitAt 3 $ each [1..10]
--   1
--   2
--   3
--   
--   &gt;&gt;&gt; S.sum rest
--   49 :&gt; ()
--   </pre>
mapM_ :: Monad m => (a -> m x) -> Stream (Of a) m r -> m r

-- | Print the elements of a stream as they arise.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.take 2 S.stdinLn
--   hello&lt;Enter&gt;
--   "hello"
--   world&lt;Enter&gt;
--   "world"
--   </pre>
print :: (MonadIO m, Show a) => Stream (Of a) m r -> m r

-- | Write a succession of strings to a handle as separate lines.
--   
--   <pre>
--   &gt;&gt;&gt; S.toHandle IO.stdout $ each (words "one two three")
--   one
--   two
--   three
--   </pre>
toHandle :: MonadIO m => Handle -> Stream (Of String) m r -> m r

-- | Write a series of <a>String</a>s as lines to a file.
--   
--   <pre>
--   &gt;&gt;&gt; S.writeFile "lines.txt" $ S.take 2 S.stdinLn
--   hello&lt;Enter&gt;
--   world&lt;Enter&gt;
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.readFile "lines.txt" S.stdoutLn
--   hello
--   world
--   </pre>
writeFile :: FilePath -> Stream (Of String) IO r -> IO r

-- | Reduce a stream, performing its actions but ignoring its elements.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.effects $ S.splitAt 2 $ each [1..5]
--   
--   &gt;&gt;&gt; S.print rest
--   3
--   4
--   5
--   </pre>
--   
--   <a>effects</a> should be understood together with <a>copy</a> and is
--   subject to the rules
--   
--   <pre>
--   S.effects . S.copy       = id
--   hoist S.effects . S.copy = id
--   </pre>
--   
--   The similar <tt>effects</tt> and <tt>copy</tt> operations in
--   <tt>Data.ByteString.Streaming</tt> obey the same rules.
effects :: Monad m => Stream (Of a) m r -> m r

-- | Remove the elements from a stream of values, retaining the structure
--   of layers.
erase :: Monad m => Stream (Of a) m r -> Stream Identity m r

-- | Where a transformer returns a stream, run the effects of the stream,
--   keeping the return value. This is usually used at the type
--   
--   <pre>
--   drained :: Monad m =&gt; Stream (Of a) m (Stream (Of b) m r) -&gt; Stream (Of a) m r
--   drained = join . fmap (lift . effects)
--   </pre>
--   
--   Here, for example, we split a stream in two places and throw out the
--   middle segment:
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.print $ S.drained $ S.splitAt 2 $ S.splitAt 5 $ each [1..7]
--   1
--   2
--   
--   &gt;&gt;&gt; S.print rest
--   6
--   7
--   </pre>
--   
--   In particular, we can define versions of <tt>take</tt> and
--   <tt>takeWhile</tt> which retrieve the return value of the rest of the
--   stream - and which can thus be used with <a>maps</a>:
--   
--   <pre>
--   take' n = S.drained . S.splitAt n
--   takeWhile' thus = S.drained . S.span thus
--   </pre>
drained :: (Monad m, Monad (t m), MonadTrans t) => t m (Stream (Of a) m r) -> t m r

-- | Standard map on the elements of a stream.
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.map reverse $ each (words "alpha beta")
--   ahpla
--   ateb
--   </pre>
map :: Monad m => (a -> b) -> Stream (Of a) m r -> Stream (Of b) m r

-- | Replace each element of a stream with the result of a monadic action
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.mapM readIORef $ S.chain (\ior -&gt; modifyIORef ior (*100)) $ S.mapM newIORef $ each [1..6]
--   100
--   200
--   300
--   400
--   500
--   600
--   </pre>
--   
--   See also <a>chain</a> for a variant of this which ignores the return
--   value of the function and just uses the side effects.
mapM :: Monad m => (a -> m b) -> Stream (Of a) m r -> Stream (Of b) m r

-- | Map layers of one functor to another with a transformation. Compare
--   hoist, which has a similar effect on the <tt>monadic</tt> parameter.
--   
--   <pre>
--   maps id = id
--   maps f . maps g = maps (f . g)
--   </pre>
maps :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation. Compare
--   hoist, which has a similar effect on the <tt>monadic</tt> parameter.
--   
--   <pre>
--   mapsPost id = id
--   mapsPost f . mapsPost g = mapsPost (f . g)
--   mapsPost f = maps f
--   </pre>
--   
--   <tt>mapsPost</tt> is essentially the same as <a>maps</a>, but it
--   imposes a <a>Functor</a> constraint on its target functor rather than
--   its source functor. It should be preferred if <a>fmap</a> is cheaper
--   for the target functor than for the source functor.
mapsPost :: forall m f g r. (Monad m, Functor g) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation involving
--   the base monad.
--   
--   This function is completely functor-general. It is often useful with
--   the more concrete type
--   
--   <pre>
--   mapped :: (forall x. Stream (Of a) IO x -&gt; IO (Of b x)) -&gt; Stream (Stream (Of a) IO) IO r -&gt; Stream (Of b) IO r
--   </pre>
--   
--   to process groups which have been demarcated in an effectful,
--   <tt>IO</tt>-based stream by grouping functions like <a>group</a>,
--   <a>split</a> or <a>breaks</a>. Summary functions like <a>fold</a>,
--   <a>foldM</a>, <a>mconcat</a> or <a>toList</a> are often used to define
--   the transformation argument. For example:
--   
--   <pre>
--   &gt;&gt;&gt; S.toList_ $ S.mapped S.toList $ S.split 'c' (S.each "abcde")
--   ["ab","de"]
--   </pre>
--   
--   <a>maps</a> and <a>mapped</a> obey these rules:
--   
--   <pre>
--   maps id              = id
--   mapped return        = id
--   maps f . maps g      = maps (f . g)
--   mapped f . mapped g  = mapped (f &lt;=&lt; g)
--   maps f . mapped g    = mapped (fmap f . g)
--   mapped f . maps g    = mapped (f &lt;=&lt; fmap g)
--   </pre>
--   
--   <a>maps</a> is more fundamental than <a>mapped</a>, which is best
--   understood as a convenience for effecting this frequent composition:
--   
--   <pre>
--   mapped phi = decompose . maps (Compose . phi)
--   </pre>
mapped :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | A version of <a>mapped</a> that imposes a <a>Functor</a> constraint on
--   the target functor rather than the source functor. This version should
--   be preferred if <a>fmap</a> on the target functor is cheaper.
mappedPost :: (Monad m, Functor g) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | <tt>for</tt> replaces each element of a stream with an associated
--   stream. Note that the associated stream may layer any functor.
for :: (Monad m, Functor f) => Stream (Of a) m r -> (a -> Stream f m x) -> Stream f m r

-- | Replace each element in a stream of individual Haskell values (a
--   <tt>Stream (Of a) m r</tt>) with an associated <tt>functorial</tt>
--   step.
--   
--   <pre>
--   for str f  = concats (with str f)
--   with str f = for str (yields . f)
--   with str f = maps (\(a:&gt;r) -&gt; r &lt;$ f a) str
--   with = flip subst
--   subst = flip with
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; with (each [1..3]) (yield . Prelude.show) &amp; intercalates (yield "--") &amp; S.stdoutLn
--   1
--   --
--   2
--   --
--   3
--   </pre>
with :: (Monad m, Functor f) => Stream (Of a) m r -> (a -> f x) -> Stream f m r

-- | Replace each element in a stream of individual values with a
--   functorial layer of any sort. <tt>subst = flip with</tt> and is more
--   convenient in a sequence of compositions that transform a stream.
--   
--   <pre>
--   with = flip subst
--   for str f = concats $ subst f str
--   subst f = maps (\(a:&gt;r) -&gt; r &lt;$ f a)
--   S.concat = concats . subst each
--   </pre>
subst :: (Monad m, Functor f) => (a -> f x) -> Stream (Of a) m r -> Stream f m r

-- | Duplicate the content of stream, so that it can be acted on twice in
--   different ways, but without breaking streaming. Thus, with <tt>each
--   [1,2]</tt> I might do:
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ each ["one","two"]
--   "one"
--   "two"
--   
--   &gt;&gt;&gt; S.stdoutLn $ each ["one","two"]
--   one
--   two
--   </pre>
--   
--   With copy, I can do these simultaneously:
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.stdoutLn $ S.copy $ each ["one","two"]
--   "one"
--   one
--   "two"
--   two
--   </pre>
--   
--   <a>copy</a> should be understood together with <a>effects</a> and is
--   subject to the rules
--   
--   <pre>
--   S.effects . S.copy       = id
--   hoist S.effects . S.copy = id
--   </pre>
--   
--   The similar operations in <a>Streaming</a> obey the same rules.
--   
--   Where the actions you are contemplating are each simple folds over the
--   elements, or a selection of elements, then the coupling of the folds
--   is often more straightforwardly effected with <a>Foldl</a>, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; L.purely S.fold (liftA2 (,) L.sum L.product) $ each [1..10]
--   (55,3628800) :&gt; ()
--   </pre>
--   
--   rather than
--   
--   <pre>
--   &gt;&gt;&gt; S.sum $ S.product . S.copy $ each [1..10]
--   55 :&gt; (3628800 :&gt; ())
--   </pre>
--   
--   A <tt>Control.Foldl</tt> fold can be altered to act on a selection of
--   elements by using <a>handles</a> on an appropriate lens. Some such
--   manipulations are simpler and more <a>List</a>-like, using
--   <a>copy</a>:
--   
--   <pre>
--   &gt;&gt;&gt; L.purely S.fold (liftA2 (,) (L.handles (L.filtered odd) L.sum) (L.handles (L.filtered even) L.product)) $ each [1..10]
--   (25,3840) :&gt; ()
--   </pre>
--   
--   becomes
--   
--   <pre>
--   &gt;&gt;&gt; S.sum $ S.filter odd $ S.product $ S.filter even $ S.copy $ each [1..10]
--   25 :&gt; (3840 :&gt; ())
--   </pre>
--   
--   or using <a>store</a>
--   
--   <pre>
--   &gt;&gt;&gt; S.sum $ S.filter odd $ S.store (S.product . S.filter even) $ each [1..10]
--   25 :&gt; (3840 :&gt; ())
--   </pre>
--   
--   But anything that fold of a <tt>Stream (Of a) m r</tt> into e.g. an
--   <tt>m (Of b r)</tt> that has a constraint on <tt>m</tt> that is
--   carried over into <tt>Stream f m</tt> - e.g. <tt>Monad</tt>,
--   <tt>MonadIO</tt>, <tt>MonadResource</tt>, etc. can be used on the
--   stream. Thus, I can fold over different groupings of the original
--   stream:
--   
--   <pre>
--   &gt;&gt;&gt; (S.toList . mapped S.toList . chunksOf 5) $  (S.toList . mapped S.toList . chunksOf 3) $ S.copy $ each [1..10]
--   [[1,2,3,4,5],[6,7,8,9,10]] :&gt; ([[1,2,3],[4,5,6],[7,8,9],[10]] :&gt; ())
--   </pre>
--   
--   The procedure can be iterated as one pleases, as one can see from this
--   (otherwise unadvisable!) example:
--   
--   <pre>
--   &gt;&gt;&gt; (S.toList . mapped S.toList . chunksOf 4) $ (S.toList . mapped S.toList . chunksOf 3) $ S.copy $ (S.toList . mapped S.toList . chunksOf 2) $ S.copy $ each [1..12]
--   [[1,2,3,4],[5,6,7,8],[9,10,11,12]] :&gt; ([[1,2,3],[4,5,6],[7,8,9],[10,11,12]] :&gt; ([[1,2],[3,4],[5,6],[7,8],[9,10],[11,12]] :&gt; ()))
--   </pre>
--   
--   <tt>copy</tt> can be considered a special case of <a>expand</a>:
--   
--   <pre>
--   copy = <a>expand</a> $ \p (a :&gt; as) -&gt; a :&gt; p (a :&gt; as)
--   </pre>
--   
--   If <a>Of</a> were an instance of <a>Comonad</a>, then one could write
--   
--   <pre>
--   copy = <a>expand</a> extend
--   </pre>
copy :: Monad m => Stream (Of a) m r -> Stream (Of a) (Stream (Of a) m) r

-- | An alias for <tt>copy</tt>.
duplicate :: Monad m => Stream (Of a) m r -> Stream (Of a) (Stream (Of a) m) r

-- | Store the result of any suitable fold over a stream, keeping the
--   stream for further manipulation. <tt>store f = f . copy</tt> :
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.store S.product $ each [1..4]
--   1
--   2
--   3
--   4
--   24 :&gt; ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.store S.sum $ S.store S.product $ each [1..4]
--   1
--   2
--   3
--   4
--   10 :&gt; (24 :&gt; ())
--   </pre>
--   
--   Here the sum (10) and the product (24) have been 'stored' for use when
--   finally we have traversed the stream with <a>print</a> . Needless to
--   say, a second <tt>pass</tt> is excluded conceptually, so the folds
--   that you apply successively with <tt>store</tt> are performed
--   simultaneously, and in constant memory -- as they would be if, say,
--   you linked them together with <tt>Control.Fold</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; L.impurely S.foldM (liftA3 (\a b c -&gt; (b, c)) (L.sink Prelude.print) (L.generalize L.sum) (L.generalize L.product)) $ each [1..4]
--   1
--   2
--   3
--   4
--   (10,24) :&gt; ()
--   </pre>
--   
--   Fusing folds after the fashion of <tt>Control.Foldl</tt> will
--   generally be a bit faster than the corresponding succession of uses of
--   <a>store</a>, but by constant factor that will be completely dwarfed
--   when any IO is at issue.
--   
--   But <a>store</a> / <a>copy</a> is <i>much</i> more powerful, as you
--   can see by reflecting on uses like this:
--   
--   <pre>
--   &gt;&gt;&gt; S.sum $ S.store (S.sum . mapped S.product . chunksOf 2) $ S.store (S.product . mapped S.sum . chunksOf 2) $ each [1..6]
--   21 :&gt; (44 :&gt; (231 :&gt; ()))
--   </pre>
--   
--   It will be clear that this cannot be reproduced with any combination
--   of lenses, <tt>Control.Fold</tt> folds, or the like. (See also the
--   discussion of <a>copy</a>.)
--   
--   It would conceivably be clearer to import a series of specializations
--   of <a>store</a>. It is intended to be used at types like these:
--   
--   <pre>
--   storeM ::  (forall s m . Monad m =&gt; Stream (Of a) m s -&gt; m (Of b s))
--           -&gt; (Monad n =&gt; Stream (Of a) n r -&gt; Stream (Of a) n (Of b r))
--   storeM = store
--   
--   storeMIO :: (forall s m . MonadIO m =&gt; Stream (Of a) m s -&gt; m (Of b s))
--            -&gt; (MonadIO n =&gt; Stream (Of a) n r -&gt; Stream (Of a) n (Of b r)
--   storeMIO = store
--   </pre>
--   
--   It is clear from these types that we are just using the general
--   instances:
--   
--   <pre>
--   instance (Functor f, Monad m)   =&gt; Monad (Stream f m)
--   instance (Functor f, MonadIO m) =&gt; MonadIO (Stream f m)
--   </pre>
--   
--   We thus can't be touching the elements of the stream, or the final
--   return value. It is the same with other constraints that <tt>Stream
--   (Of a)</tt> inherits from the underlying monad, like
--   <tt>MonadResource</tt>. Thus I can independently filter and write to
--   one file, but nub and write to another, or interact with a database
--   and a logfile and the like:
--   
--   <pre>
--   &gt;&gt;&gt; (S.writeFile "hello2.txt" . S.nubOrd) $ store (S.writeFile "hello.txt" . S.filter (/= "world")) $ each ["hello", "world", "goodbye", "world"]
--   
--   &gt;&gt;&gt; :! cat hello.txt
--   hello
--   goodbye
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   hello
--   world
--   goodbye
--   </pre>
store :: Monad m => (Stream (Of a) (Stream (Of a) m) r -> t) -> Stream (Of a) m r -> t

-- | Apply an action to all values, re-yielding each. The return value
--   (<tt>y</tt>) of the function is ignored.
--   
--   <pre>
--   &gt;&gt;&gt; S.product $ S.chain Prelude.print $ S.each [1..5]
--   1
--   2
--   3
--   4
--   5
--   120 :&gt; ()
--   </pre>
--   
--   See also <a>mapM</a> for a variant of this which uses the return value
--   of the function to transorm the values in the stream.
chain :: Monad m => (a -> m y) -> Stream (Of a) m r -> Stream (Of a) m r

-- | Like the <a>sequence</a> but streaming. The result type is a stream of
--   a's, <i>but is not accumulated</i>; the effects of the elements of the
--   original stream are interleaved in the resulting stream. Compare:
--   
--   <pre>
--   sequence :: Monad m =&gt;       [m a]           -&gt; m [a]
--   sequence :: Monad m =&gt; Stream (Of (m a)) m r -&gt; Stream (Of a) m r
--   </pre>
--   
--   This obeys the rule
sequence :: Monad m => Stream (Of (m a)) m r -> Stream (Of a) m r

-- | Remove repeated elements from a Stream. <a>nubOrd</a> of course
--   accumulates a <a>Set</a> of elements that have already been seen and
--   should thus be used with care.
--   
--   <pre>
--   &gt;&gt;&gt; S.toList_ $ S.nubOrd $ S.take 5 S.readLn :: IO [Int]
--   1&lt;Enter&gt;
--   2&lt;Enter&gt;
--   3&lt;Enter&gt;
--   1&lt;Enter&gt;
--   2&lt;Enter&gt;
--   [1,2,3]
--   </pre>
nubOrd :: (Monad m, Ord a) => Stream (Of a) m r -> Stream (Of a) m r

-- | Use <a>nubOrdOn</a> to have a custom ordering function for your
--   elements.
nubOrdOn :: (Monad m, Ord b) => (a -> b) -> Stream (Of a) m r -> Stream (Of a) m r

-- | More efficient versions of above when working with <a>Int</a>s that
--   use <a>IntSet</a>.
nubInt :: Monad m => Stream (Of Int) m r -> Stream (Of Int) m r
nubIntOn :: Monad m => (a -> Int) -> Stream (Of a) m r -> Stream (Of a) m r

-- | Skip elements of a stream that fail a predicate
filter :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m r

-- | Skip elements of a stream that fail a monadic test
filterM :: Monad m => (a -> m Bool) -> Stream (Of a) m r -> Stream (Of a) m r

-- | Map monadically over a stream, producing a new stream only containing
--   the <a>Just</a> values.
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> Stream (Of a) m r -> Stream (Of b) m r

-- | Interpolate a delay of n seconds between yields.
delay :: MonadIO m => Double -> Stream (Of a) m r -> Stream (Of a) m r

-- | Intersperse given value between each element of the stream.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.intersperse 0 $ each [1,2,3]
--   1
--   0
--   2
--   0
--   3
--   </pre>
intersperse :: Monad m => a -> Stream (Of a) m r -> Stream (Of a) m r

-- | End a stream after n elements; the original return value is thus lost.
--   <a>splitAt</a> preserves this information. Note that, like
--   <tt>splitAt</tt>, this function is functor-general, so that, for
--   example, you can <tt>take</tt> not just a number of items from a
--   stream of elements, but a number of substreams and the like.
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.take 3 $ each "with"
--   "wit" :&gt; ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.readFile "stream.hs" (S.stdoutLn . S.take 3)
--   import Streaming
--   import qualified Streaming.Prelude as S
--   import Streaming.Prelude (each, next, yield)
--   </pre>
take :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m ()

-- | End stream when an element fails a condition; the original return
--   value is lost. By contrast <a>span</a> preserves this information, and
--   is generally more desirable.
--   
--   <pre>
--   S.takeWhile thus = void . S.span thus
--   </pre>
--   
--   To preserve the information - but thus also force the rest of the
--   stream to be developed - write
--   
--   <pre>
--   S.drained . S.span thus
--   </pre>
--   
--   as <tt>dropWhile thus</tt> is
--   
--   <pre>
--   S.effects . S.span thus
--   </pre>
takeWhile :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m ()

-- | Like <a>takeWhile</a>, but takes a monadic predicate.
takeWhileM :: Monad m => (a -> m Bool) -> Stream (Of a) m r -> Stream (Of a) m ()

-- | Ignore the first n elements of a stream, but carry out the actions
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.drop 2 $ S.replicateM 5 getLine
--   a&lt;Enter&gt;
--   b&lt;Enter&gt;
--   c&lt;Enter&gt;
--   d&lt;Enter&gt;
--   e&lt;Enter&gt;
--   ["c","d","e"] :&gt; ()
--   </pre>
--   
--   Because it retains the final return value, <tt>drop n</tt> is a
--   suitable argument for <tt>maps</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ concats $ maps (S.drop 4) $ chunksOf 5 $ each [1..20]
--   [5,10,15,20] :&gt; ()
--   </pre>
drop :: Monad m => Int -> Stream (Of a) m r -> Stream (Of a) m r

-- | Ignore elements of a stream until a test succeeds, retaining the rest.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.dropWhile ((&lt; 5) . length) S.stdinLn
--   one&lt;Enter&gt;
--   two&lt;Enter&gt;
--   three&lt;Enter&gt;
--   "three"
--   four&lt;Enter&gt;
--   "four"
--   ^CInterrupted.
--   </pre>
dropWhile :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m r

-- | Make a stream of foldable containers into a stream of their separate
--   elements. This is just
--   
--   <pre>
--   concat str = for str each
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.concat (each ["xy","z"])
--   'x'
--   'y'
--   'z'
--   </pre>
--   
--   Note that it also has the effect of <a>catMaybes</a>, <a>rights</a>
--   <tt>map snd</tt> and such-like operations.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.concat $ S.each [Just 1, Nothing, Just 2]
--   1
--   2
--   
--   &gt;&gt;&gt; S.print $  S.concat $ S.each [Right 1, Left "Error!", Right 2]
--   1
--   2
--   
--   &gt;&gt;&gt; S.print $ S.concat $ S.each [('A',1), ('B',2)]
--   1
--   2
--   </pre>
concat :: (Monad m, Foldable f) => Stream (Of (f a)) m r -> Stream (Of a) m r

-- | Strict left scan, streaming, e.g. successive partial results. The seed
--   is yielded first, before any action of finding the next element is
--   performed.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.scan (++) "" id $ each (words "a b c d")
--   ""
--   "a"
--   "ab"
--   "abc"
--   "abcd"
--   </pre>
--   
--   <a>scan</a> is fitted for use with <tt>Control.Foldl</tt>, thus:
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ L.purely S.scan L.list $ each [3..5]
--   []
--   [3]
--   [3,4]
--   [3,4,5]
--   </pre>
scan :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Stream (Of a) m r -> Stream (Of b) m r

-- | Strict left scan, accepting a monadic function. It can be used with
--   <tt>FoldM</tt>s from <tt>Control.Foldl</tt> using <tt>impurely</tt>.
--   Here we yield a succession of vectors each recording
--   
--   <pre>
--   &gt;&gt;&gt; let v = L.impurely scanM L.vectorM $ each [1..4::Int] :: Stream (Of (Vector Int)) IO ()
--   
--   &gt;&gt;&gt; S.print v
--   []
--   [1]
--   [1,2]
--   [1,2,3]
--   [1,2,3,4]
--   </pre>
scanM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Stream (Of a) m r -> Stream (Of b) m r

-- | Label each element in a stream with a value accumulated according to a
--   fold.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.scanned (*) 1 id $ S.each [100,200,300]
--   (100,100)
--   (200,20000)
--   (300,6000000)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ L.purely S.scanned L.product $ S.each [100,200,300]
--   (100,100)
--   (200,20000)
--   (300,6000000)
--   </pre>
scanned :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Stream (Of a) m r -> Stream (Of (a, b)) m r

-- | Make a stream of strings into a stream of parsed values, skipping bad
--   cases
--   
--   <pre>
--   &gt;&gt;&gt; S.sum_ $ S.read $ S.takeWhile (/= "total") S.stdinLn :: IO Int
--   1000&lt;Enter&gt;
--   2000&lt;Enter&gt;
--   total&lt;Enter&gt;
--   3000
--   </pre>
read :: (Monad m, Read a) => Stream (Of String) m r -> Stream (Of a) m r
show :: (Monad m, Show a) => Stream (Of a) m r -> Stream (Of String) m r

-- | The natural <tt>cons</tt> for a <tt>Stream (Of a)</tt>.
--   
--   <pre>
--   cons a stream = yield a &gt;&gt; stream
--   </pre>
--   
--   Useful for interoperation:
--   
--   <pre>
--   Data.Text.foldr S.cons (return ()) :: Text -&gt; Stream (Of Char) m ()
--   Lazy.foldrChunks S.cons (return ()) :: Lazy.ByteString -&gt; Stream (Of Strict.ByteString) m ()
--   </pre>
--   
--   and so on.
cons :: Monad m => a -> Stream (Of a) m r -> Stream (Of a) m r

-- | <a>slidingWindow</a> accumulates the first <tt>n</tt> elements of a
--   stream, update thereafter to form a sliding window of length
--   <tt>n</tt>. It follows the behavior of the slidingWindow function in
--   <a>conduit-combinators</a>.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ S.slidingWindow 4 $ S.each "123456"
--   fromList "1234"
--   fromList "2345"
--   fromList "3456"
--   </pre>
slidingWindow :: Monad m => Int -> Stream (Of a) m b -> Stream (Of (Seq a)) m b

-- | <a>slidingWindowMin</a> finds the minimum in every sliding window of
--   <tt>n</tt> elements of a stream. If within a window there are multiple
--   elements that are the least, it prefers the first occurrence (if you
--   prefer to have the last occurrence, use the max version and flip your
--   comparator). It satisfies:
--   
--   <pre>
--   <a>slidingWindowMin</a> n s = <a>map</a> <a>minimum</a> (<a>slidingWindow</a> n s)
--   </pre>
--   
--   Except that it is far more efficient, especially when the window size
--   is large: it calls <a>compare</a> <i>O(m)</i> times overall where
--   <i>m</i> is the total number of elements in the stream.
slidingWindowMin :: (Monad m, Ord a) => Int -> Stream (Of a) m b -> Stream (Of a) m b

-- | <a>slidingWindowMinBy</a> finds the minimum in every sliding window of
--   <tt>n</tt> elements of a stream according to the given comparison
--   function (which should define a total ordering). See notes above about
--   elements that are equal. It satisfies:
--   
--   <pre>
--   <a>slidingWindowMinBy</a> f n s = <a>map</a> (<a>minimumBy</a> f) (<a>slidingWindow</a> n s)
--   </pre>
--   
--   Except that it is far more efficient, especially when the window size
--   is large: it calls the comparison function <i>O(m)</i> times overall
--   where <i>m</i> is the total number of elements in the stream.
slidingWindowMinBy :: Monad m => (a -> a -> Ordering) -> Int -> Stream (Of a) m b -> Stream (Of a) m b

-- | <a>slidingWindowMinOn</a> finds the minimum in every sliding window of
--   <tt>n</tt> elements of a stream according to the given projection
--   function. See notes above about elements that are equal. It satisfies:
--   
--   <pre>
--   <a>slidingWindowMinOn</a> f n s = <a>map</a> (<a>minimumOn</a> (<a>comparing</a> f)) (<a>slidingWindow</a> n s)
--   </pre>
--   
--   Except that it is far more efficient, especially when the window size
--   is large: it calls <a>compare</a> on the projected value <i>O(m)</i>
--   times overall where <i>m</i> is the total number of elements in the
--   stream, and it calls the projection function exactly <i>m</i> times.
slidingWindowMinOn :: (Monad m, Ord p) => (a -> p) -> Int -> Stream (Of a) m b -> Stream (Of a) m b

-- | <a>slidingWindowMax</a> finds the maximum in every sliding window of
--   <tt>n</tt> elements of a stream. If within a window there are multiple
--   elements that are the largest, it prefers the last occurrence (if you
--   prefer to have the first occurrence, use the min version and flip your
--   comparator). It satisfies:
--   
--   <pre>
--   <a>slidingWindowMax</a> n s = <a>map</a> <a>maximum</a> (<a>slidingWindow</a> n s)
--   </pre>
--   
--   Except that it is far more efficient, especially when the window size
--   is large: it calls <a>compare</a> <i>O(m)</i> times overall where
--   <i>m</i> is the total number of elements in the stream.
slidingWindowMax :: (Monad m, Ord a) => Int -> Stream (Of a) m b -> Stream (Of a) m b

-- | <a>slidingWindowMaxBy</a> finds the maximum in every sliding window of
--   <tt>n</tt> elements of a stream according to the given comparison
--   function (which should define a total ordering). See notes above about
--   elements that are equal. It satisfies:
--   
--   <pre>
--   <a>slidingWindowMaxBy</a> f n s = <a>map</a> (<a>maximumBy</a> f) (<a>slidingWindow</a> n s)
--   </pre>
--   
--   Except that it is far more efficient, especially when the window size
--   is large: it calls the comparison function <i>O(m)</i> times overall
--   where <i>m</i> is the total number of elements in the stream.
slidingWindowMaxBy :: Monad m => (a -> a -> Ordering) -> Int -> Stream (Of a) m b -> Stream (Of a) m b

-- | <a>slidingWindowMaxOn</a> finds the maximum in every sliding window of
--   <tt>n</tt> elements of a stream according to the given projection
--   function. See notes above about elements that are equal. It satisfies:
--   
--   <pre>
--   <a>slidingWindowMaxOn</a> f n s = <a>map</a> (<a>maximumOn</a> (<a>comparing</a> f)) (<a>slidingWindow</a> n s)
--   </pre>
--   
--   Except that it is far more efficient, especially when the window size
--   is large: it calls <a>compare</a> on the projected value <i>O(m)</i>
--   times overall where <i>m</i> is the total number of elements in the
--   stream, and it calls the projection function exactly <i>m</i> times.
slidingWindowMaxOn :: (Monad m, Ord p) => (a -> p) -> Int -> Stream (Of a) m b -> Stream (Of a) m b

-- | Before evaluating the monadic action returning the next step in the
--   <a>Stream</a>, <tt>wrapEffect</tt> extracts the value in a monadic
--   computation <tt>m a</tt> and passes it to a computation <tt>a -&gt; m
--   y</tt>.
wrapEffect :: (Monad m, Functor f) => m a -> (a -> m y) -> Stream f m r -> Stream f m r

-- | The standard way of inspecting the first item in a stream of elements,
--   if the stream is still 'running'. The <tt>Right</tt> case contains a
--   Haskell pair, where the more general <tt>inspect</tt> would return a
--   left-strict pair. There is no reason to prefer <tt>inspect</tt> since,
--   if the <tt>Right</tt> case is exposed, the first element in the pair
--   will have been evaluated to whnf.
--   
--   <pre>
--   next    :: Monad m =&gt; Stream (Of a) m r -&gt; m (Either r    (a, Stream (Of a) m r))
--   inspect :: Monad m =&gt; Stream (Of a) m r -&gt; m (Either r (Of a (Stream (Of a) m r)))
--   </pre>
--   
--   Interoperate with <tt>pipes</tt> producers thus:
--   
--   <pre>
--   Pipes.unfoldr Stream.next :: Stream (Of a) m r -&gt; Producer a m r
--   Stream.unfoldr Pipes.next :: Producer a m r -&gt; Stream (Of a) m r
--   </pre>
--   
--   Similarly:
--   
--   <pre>
--   IOStreams.unfoldM (fmap (either (const Nothing) Just) . next) :: Stream (Of a) IO b -&gt; IO (InputStream a)
--   Conduit.unfoldM   (fmap (either (const Nothing) Just) . next) :: Stream (Of a) m r -&gt; Source a m r
--   </pre>
--   
--   But see <a>uncons</a>, which is better fitted to these
--   <tt>unfoldM</tt>s
next :: Monad m => Stream (Of a) m r -> m (Either r (a, Stream (Of a) m r))

-- | Inspect the first item in a stream of elements, without a return
--   value. <tt>uncons</tt> provides convenient exit into another streaming
--   type:
--   
--   <pre>
--   IOStreams.unfoldM uncons :: Stream (Of a) IO b -&gt; IO (InputStream a)
--   Conduit.unfoldM uncons   :: Stream (Of a) m r -&gt; Conduit.Source m a
--   </pre>
uncons :: Monad m => Stream (Of a) m r -> m (Maybe (a, Stream (Of a) m r))

-- | Split a succession of layers after some number, returning a streaming
--   or effectful pair. This function is the same as the <a>splitsAt</a>
--   exported by the <tt>Streaming</tt> module, but since this module is
--   imported qualified, it can usurp a Prelude name. It specializes to:
--   
--   <pre>
--   splitAt :: (Monad m) =&gt; Int -&gt; Stream (Of a) m r -&gt; Stream (Of a) m (Stream (Of a) m r)
--   </pre>
splitAt :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Stream f m r)

-- | Split a stream of elements wherever a given element arises. The action
--   is like that of <a>words</a>.
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ mapped S.toList $ S.split ' ' $ each "hello world  "
--   hello
--   world
--   </pre>
split :: (Eq a, Monad m) => a -> Stream (Of a) m r -> Stream (Stream (Of a) m) m r

-- | Break during periods where the predicate is not satisfied, grouping
--   the periods when it is.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ mapped S.toList $ S.breaks not $ S.each [False,True,True,False,True,True,False]
--   [True,True]
--   [True,True]
--   
--   &gt;&gt;&gt; S.print $ mapped S.toList $ S.breaks id $ S.each [False,True,True,False,True,True,False]
--   [False]
--   [False]
--   [False]
--   </pre>
breaks :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Stream (Of a) m) m r

-- | Break a sequence upon meeting element falls under a predicate, keeping
--   it and the rest of the stream as the return value.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.print $ S.break even $ each [1,1,2,3]
--   1
--   1
--   
--   &gt;&gt;&gt; S.print rest
--   2
--   3
--   </pre>
break :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m (Stream (Of a) m r)

-- | Yield elements, using a fold to maintain state, until the accumulated
--   value satifies the supplied predicate. The fold will then be
--   short-circuited and the element that breaks it will be put after the
--   break. This function is easiest to use with <a>purely</a>
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- each [1..10] &amp; L.purely S.breakWhen L.sum (&gt;10) &amp; S.print
--   1
--   2
--   3
--   4
--   
--   &gt;&gt;&gt; S.print rest
--   5
--   6
--   7
--   8
--   9
--   10
--   </pre>
breakWhen :: Monad m => (x -> a -> x) -> x -> (x -> b) -> (b -> Bool) -> Stream (Of a) m r -> Stream (Of a) m (Stream (Of a) m r)

-- | Stream elements until one fails the condition, return the rest.
span :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m (Stream (Of a) m r)

-- | Group successive equal items together
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ mapped S.toList $ S.group $ each "baaaaad"
--   ["b","aaaaa","d"] :&gt; ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ concats $ maps (S.drained . S.splitAt 1) $ S.group $ each "baaaaaaad"
--   "bad" :&gt; ()
--   </pre>
group :: (Monad m, Eq a) => Stream (Of a) m r -> Stream (Stream (Of a) m) m r

-- | Group elements of a stream in accordance with the supplied comparison.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ mapped S.toList $ S.groupBy (&gt;=) $ each [1,2,3,1,2,3,4,3,2,4,5,6,7,6,5]
--   [1]
--   [2]
--   [3,1,2,3]
--   [4,3,2,4]
--   [5]
--   [6]
--   [7,6,5]
--   </pre>
groupBy :: Monad m => (a -> a -> Bool) -> Stream (Of a) m r -> Stream (Stream (Of a) m) m r
distinguish :: (a -> Bool) -> Of a r -> Sum (Of a) (Of a) r

-- | Swap the order of functors in a sum of functors.
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.print $ separate $ maps S.switch $ maps (S.distinguish (=='a')) $ S.each "banana"
--   'a'
--   'a'
--   'a'
--   "bnn" :&gt; ()
--   
--   &gt;&gt;&gt; S.toList $ S.print $ separate $ maps (S.distinguish (=='a')) $ S.each "banana"
--   'b'
--   'n'
--   'n'
--   "aaa" :&gt; ()
--   </pre>
switch :: Sum f g r -> Sum g f r

-- | Given a stream on a sum of functors, make it a stream on the left
--   functor, with the streaming on the other functor as the governing
--   monad. This is useful for acting on one or the other functor with a
--   fold, leaving the other material for another treatment. It generalizes
--   <a>partitionEithers</a>, but actually streams properly.
--   
--   <pre>
--   &gt;&gt;&gt; let odd_even = S.maps (S.distinguish even) $ S.each [1..10::Int]
--   
--   &gt;&gt;&gt; :t separate odd_even
--   separate odd_even
--     :: Monad m =&gt; Stream (Of Int) (Stream (Of Int) m) ()
--   </pre>
--   
--   Now, for example, it is convenient to fold on the left and right
--   values separately:
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.toList $ separate odd_even
--   [2,4,6,8,10] :&gt; ([1,3,5,7,9] :&gt; ())
--   </pre>
--   
--   Or we can write them to separate files or whatever:
--   
--   <pre>
--   &gt;&gt;&gt; S.writeFile "even.txt" . S.show $ S.writeFile "odd.txt" . S.show $ S.separate odd_even
--   
--   &gt;&gt;&gt; :! cat even.txt
--   2
--   4
--   6
--   8
--   10
--   
--   &gt;&gt;&gt; :! cat odd.txt
--   1
--   3
--   5
--   7
--   9
--   </pre>
--   
--   Of course, in the special case of <tt>Stream (Of a) m r</tt>, we can
--   achieve the above effects more simply by using <a>copy</a>
--   
--   <pre>
--   &gt;&gt;&gt; S.toList . S.filter even $ S.toList . S.filter odd $ S.copy $ each [1..10::Int]
--   [2,4,6,8,10] :&gt; ([1,3,5,7,9] :&gt; ())
--   </pre>
--   
--   But <a>separate</a> and <a>unseparate</a> are functor-general.
separate :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream f (Stream g m) r
unseparate :: (Monad m, Functor f, Functor g) => Stream f (Stream g m) r -> Stream (Sum f g) m r
eitherToSum :: Of (Either a b) r -> Sum (Of a) (Of b) r
sumToEither :: Sum (Of a) (Of b) r -> Of (Either a b) r
sumToCompose :: Sum f f r -> Compose (Of Bool) f r
composeToSum :: Compose (Of Bool) f r -> Sum f f r

-- | Strict fold of a <a>Stream</a> of elements that preserves the return
--   value. The third parameter will often be <a>id</a> where a fold is
--   written by hand:
--   
--   <pre>
--   &gt;&gt;&gt; S.fold (+) 0 id $ each [1..10]
--   55 :&gt; ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.fold (*) 1 id $ S.fold (+) 0 id $ S.copy $ each [1..10]
--   3628800 :&gt; (55 :&gt; ())
--   </pre>
--   
--   It can be used to replace a standard Haskell type with one more suited
--   to writing a strict accumulation function. It is also crucial to the
--   Applicative instance for <tt>Control.Foldl.Fold</tt> We can apply such
--   a fold <tt>purely</tt>
--   
--   <pre>
--   Control.Foldl.purely S.fold :: Monad m =&gt; Fold a b -&gt; Stream (Of a) m r -&gt; m (Of b r)
--   </pre>
--   
--   Thus, specializing a bit:
--   
--   <pre>
--   L.purely S.fold L.sum :: Stream (Of Int) Int r -&gt; m (Of Int r)
--   mapped (L.purely S.fold L.sum) :: Stream (Stream (Of Int)) IO r -&gt; Stream (Of Int) IO r
--   </pre>
--   
--   Here we use the Applicative instance for <tt>Control.Foldl.Fold</tt>
--   to stream three-item segments of a stream together with their sums and
--   products.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ mapped (L.purely S.fold (liftA3 (,,) L.list L.product L.sum)) $ chunksOf 3 $ each [1..10]
--   ([1,2,3],6,6)
--   ([4,5,6],120,15)
--   ([7,8,9],504,24)
--   ([10],10,10)
--   </pre>
fold :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Stream (Of a) m r -> m (Of b r)

-- | Strict fold of a <a>Stream</a> of elements, preserving only the result
--   of the fold, not the return value of the stream. The third parameter
--   will often be <a>id</a> where a fold is written by hand:
--   
--   <pre>
--   &gt;&gt;&gt; S.fold_ (+) 0 id $ each [1..10]
--   55
--   </pre>
--   
--   It can be used to replace a standard Haskell type with one more suited
--   to writing a strict accumulation function. It is also crucial to the
--   Applicative instance for <tt>Control.Foldl.Fold</tt>
--   
--   <pre>
--   Control.Foldl.purely fold :: Monad m =&gt; Fold a b -&gt; Stream (Of a) m () -&gt; m b
--   </pre>
fold_ :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Stream (Of a) m r -> m b

-- | Strict, monadic fold of the elements of a <tt>Stream (Of a)</tt>
--   
--   <pre>
--   Control.Foldl.impurely foldM' :: Monad m =&gt; FoldM a b -&gt; Stream (Of a) m r -&gt; m (b, r)
--   </pre>
--   
--   Thus to accumulate the elements of a stream as a vector, together with
--   a random element we might write:
--   
--   <pre>
--   &gt;&gt;&gt; L.impurely S.foldM (liftA2 (,) L.vectorM L.random) $ each [1..10::Int] :: IO (Of (Vector Int, Maybe Int) ())
--   ([1,2,3,4,5,6,7,8,9,10],Just 9) :&gt; ()
--   </pre>
foldM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Stream (Of a) m r -> m (Of b r)

-- | Strict, monadic fold of the elements of a <tt>Stream (Of a)</tt>
--   
--   <pre>
--   Control.Foldl.impurely foldM :: Monad m =&gt; FoldM a b -&gt; Stream (Of a) m () -&gt; m b
--   </pre>
foldM_ :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Stream (Of a) m r -> m b

-- | Map each element of the stream to a monoid, and take the monoidal sum
--   of the results.
--   
--   <pre>
--   &gt;&gt;&gt; S.foldMap Sum $ S.take 2 (S.stdinLn)
--   1&lt;Enter&gt;
--   2&lt;Enter&gt;
--   3&lt;Enter&gt;
--   Sum {getSum = 6} :&gt; ()
--   </pre>
foldMap :: (Monad m, Monoid w) => (a -> w) -> Stream (Of a) m r -> m (Of w r)
foldMap_ :: (Monad m, Monoid w) => (a -> w) -> Stream (Of a) m r -> m w
all :: Monad m => (a -> Bool) -> Stream (Of a) m r -> m (Of Bool r)
all_ :: Monad m => (a -> Bool) -> Stream (Of a) m r -> m Bool
any :: Monad m => (a -> Bool) -> Stream (Of a) m r -> m (Of Bool r)
any_ :: Monad m => (a -> Bool) -> Stream (Of a) m r -> m Bool

-- | Fold a <a>Stream</a> of numbers into their sum with the return value
--   
--   <pre>
--   mapped S.sum :: Stream (Stream (Of Int)) m r -&gt; Stream (Of Int) m r
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.sum $ each [1..10]
--   55 :&gt; ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; (n :&gt; rest)  &lt;- S.sum $ S.splitAt 3 $ each [1..10]
--   
--   &gt;&gt;&gt; System.IO.print n
--   6
--   
--   &gt;&gt;&gt; (m :&gt; rest') &lt;- S.sum $ S.splitAt 3 rest
--   
--   &gt;&gt;&gt; System.IO.print m
--   15
--   
--   &gt;&gt;&gt; S.print rest'
--   7
--   8
--   9
--   10
--   </pre>
sum :: (Monad m, Num a) => Stream (Of a) m r -> m (Of a r)

-- | Fold a <a>Stream</a> of numbers into their sum
sum_ :: (Monad m, Num a) => Stream (Of a) m () -> m a

-- | Fold a <a>Stream</a> of numbers into their product with the return
--   value
--   
--   <pre>
--   mapped product :: Stream (Stream (Of Int)) m r -&gt; Stream (Of Int) m r
--   </pre>
product :: (Monad m, Num a) => Stream (Of a) m r -> m (Of a r)

-- | Fold a <a>Stream</a> of numbers into their product
product_ :: (Monad m, Num a) => Stream (Of a) m () -> m a
head :: Monad m => Stream (Of a) m r -> m (Of (Maybe a) r)
head_ :: Monad m => Stream (Of a) m r -> m (Maybe a)
last :: Monad m => Stream (Of a) m r -> m (Of (Maybe a) r)
last_ :: Monad m => Stream (Of a) m r -> m (Maybe a)

-- | Exhaust a stream remembering only whether <tt>a</tt> was an element.
elem :: (Monad m, Eq a) => a -> Stream (Of a) m r -> m (Of Bool r)
elem_ :: (Monad m, Eq a) => a -> Stream (Of a) m r -> m Bool

-- | Exhaust a stream deciding whether <tt>a</tt> was an element.
notElem :: (Monad m, Eq a) => a -> Stream (Of a) m r -> m (Of Bool r)
notElem_ :: (Monad m, Eq a) => a -> Stream (Of a) m r -> m Bool

-- | Run a stream, keeping its length and its return value.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ mapped S.length $ chunksOf 3 $ S.each [1..10]
--   3
--   3
--   3
--   1
--   </pre>
length :: Monad m => Stream (Of a) m r -> m (Of Int r)

-- | Run a stream, remembering only its length:
--   
--   <pre>
--   &gt;&gt;&gt; runIdentity $ S.length_ (S.each [1..10] :: Stream (Of Int) Identity ())
--   10
--   </pre>
length_ :: Monad m => Stream (Of a) m r -> m Int

-- | Convert an effectful <a>Stream</a> into a list alongside the return
--   value
--   
--   <pre>
--   mapped toList :: Stream (Stream (Of a) m) m r -&gt; Stream (Of [a]) m r
--   </pre>
--   
--   Like <a>toList_</a>, <a>toList</a> breaks streaming; unlike
--   <a>toList_</a> it <i>preserves the return value</i> and thus is
--   frequently useful with e.g. <a>mapped</a>
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ mapped S.toList $ chunksOf 3 $ each [1..9]
--   [1,2,3]
--   [4,5,6]
--   [7,8,9]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ mapped S.toList $ chunksOf 2 $ S.replicateM 4 getLine
--   s&lt;Enter&gt;
--   t&lt;Enter&gt;
--   ["s","t"]
--   u&lt;Enter&gt;
--   v&lt;Enter&gt;
--   ["u","v"]
--   </pre>
toList :: Monad m => Stream (Of a) m r -> m (Of [a] r)

-- | Convert an effectful <tt>Stream (Of a)</tt> into a list of <tt>as</tt>
--   
--   Note: Needless to say, this function does not stream properly. It is
--   basically the same as Prelude <a>mapM</a> which, like
--   <a>replicateM</a>, <a>sequence</a> and similar operations on
--   traversable containers is a leading cause of space leaks.
toList_ :: Monad m => Stream (Of a) m r -> m [a]

-- | Fold streamed items into their monoidal sum
--   
--   <pre>
--   &gt;&gt;&gt; S.mconcat $ S.take 2 $ S.map (Data.Monoid.Last . Just) S.stdinLn
--   first&lt;Enter&gt;
--   last&lt;Enter&gt;
--   Last {getLast = Just "last"} :&gt; ()
--   </pre>
mconcat :: (Monad m, Monoid w) => Stream (Of w) m r -> m (Of w r)
mconcat_ :: (Monad m, Monoid w) => Stream (Of w) m r -> m w
minimum :: (Monad m, Ord a) => Stream (Of a) m r -> m (Of (Maybe a) r)
minimum_ :: (Monad m, Ord a) => Stream (Of a) m r -> m (Maybe a)
maximum :: (Monad m, Ord a) => Stream (Of a) m r -> m (Of (Maybe a) r)
maximum_ :: (Monad m, Ord a) => Stream (Of a) m r -> m (Maybe a)

-- | A natural right fold for consuming a stream of elements. See also the
--   more general <a>iterT</a> in the <tt>Streaming</tt> module and the
--   still more general <a>destroy</a>
foldrM :: Monad m => (a -> m r -> m r) -> Stream (Of a) m r -> m r

-- | A natural right fold for consuming a stream of elements. See also the
--   more general <a>iterTM</a> in the <tt>Streaming</tt> module and the
--   still more general <a>destroy</a>
--   
--   <pre>
--   foldrT (\a p -&gt; Streaming.yield a &gt;&gt; p) = id
--   foldrT (\a p -&gt; Pipes.yield a     &gt;&gt; p) :: Monad m =&gt; Stream (Of a) m r -&gt; Producer a m r
--   foldrT (\a p -&gt; Conduit.yield a   &gt;&gt; p) :: Monad m =&gt; Stream (Of a) m r -&gt; Conduit a m r
--   </pre>
foldrT :: (Monad m, MonadTrans t, Monad (t m)) => (a -> t m r -> t m r) -> Stream (Of a) m r -> t m r

-- | Zip two <a>Stream</a>s
zip :: Monad m => Stream (Of a) m r -> Stream (Of b) m r -> Stream (Of (a, b)) m r

-- | Zip two <a>Stream</a>s using the provided combining function
zipWith :: Monad m => (a -> b -> c) -> Stream (Of a) m r -> Stream (Of b) m r -> Stream (Of c) m r

-- | Zip three <a>Stream</a>s together
zip3 :: Monad m => Stream (Of a) m r -> Stream (Of b) m r -> Stream (Of c) m r -> Stream (Of (a, b, c)) m r

-- | Zip three <a>Stream</a>s with a combining function
zipWith3 :: Monad m => (a -> b -> c -> d) -> Stream (Of a) m r -> Stream (Of b) m r -> Stream (Of c) m r -> Stream (Of d) m r

-- | The type
--   
--   <pre>
--   Data.List.unzip     :: [(a,b)] -&gt; ([a],[b])
--   </pre>
--   
--   might lead us to expect
--   
--   <pre>
--   Streaming.unzip :: Stream (Of (a,b)) m r -&gt; Stream (Of a) m (Stream (Of b) m r)
--   </pre>
--   
--   which would not stream, since it would have to accumulate the second
--   stream (of <tt>b</tt>s). Of course, <tt>Data.List</tt> <a>unzip</a>
--   doesn't stream either.
--   
--   This <tt>unzip</tt> does stream, though of course you can spoil this
--   by using e.g. <a>toList</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let xs = Prelude.map (\x -&gt; (x, Prelude.show x)) [1..5 :: Int]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.toList $ S.unzip (S.each xs)
--   ["1","2","3","4","5"] :&gt; ([1,2,3,4,5] :&gt; ())
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Prelude.unzip xs
--   ([1,2,3,4,5],["1","2","3","4","5"])
--   </pre>
--   
--   Note the difference of order in the results. It may be of some use to
--   think why. The first application of <a>toList</a> was applied to a
--   stream of integers:
--   
--   <pre>
--   &gt;&gt;&gt; :t S.unzip $ S.each xs
--   S.unzip $ S.each xs :: Monad m =&gt; Stream (Of Int) (Stream (Of String) m) ()
--   </pre>
--   
--   Like any fold, <a>toList</a> takes no notice of the monad of effects.
--   
--   <pre>
--   toList :: Monad m =&gt; Stream (Of a) m r -&gt; m (Of [a] r)
--   </pre>
--   
--   In the case at hand (since I am in <tt>ghci</tt>) <tt>m = Stream (Of
--   String) IO</tt>. So when I apply <a>toList</a>, I exhaust that stream
--   of integers, folding it into a list:
--   
--   <pre>
--   &gt;&gt;&gt; :t S.toList $ S.unzip $ S.each xs
--   S.toList $ S.unzip $ S.each xs
--     :: Monad m =&gt; Stream (Of String) m (Of [Int] ())
--   </pre>
--   
--   When I apply <a>toList</a> to <i>this</i>, I reduce everything to an
--   ordinary action in <tt>IO</tt>, and return a list of strings:
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.toList $ S.unzip (S.each xs)
--   ["1","2","3","4","5"] :&gt; ([1,2,3,4,5] :&gt; ())
--   </pre>
--   
--   <a>unzip</a> can be considered a special case of either <a>unzips</a>
--   or <a>expand</a>:
--   
--   <pre>
--   unzip = <a>unzips</a> . <a>maps</a> (\((a,b) :&gt; x) -&gt; Compose (a :&gt; b :&gt; x))
--   unzip = <a>expand</a> $ \p ((a,b) :&gt; abs) -&gt; b :&gt; p (a :&gt; abs)
--   </pre>
unzip :: Monad m => Stream (Of (a, b)) m r -> Stream (Of a) (Stream (Of b) m) r

-- | Separate left and right values in distinct streams. (<a>separate</a>
--   is a more powerful, functor-general, equivalent using <a>Sum</a> in
--   place of <a>Either</a>). So, for example, to permit unlimited user
--   input of <tt>Int</tt>s on condition of only two errors, we might
--   write:
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.print $ S.take 2 $ partitionEithers $ S.map readEither $ S.stdinLn  :: IO (Of [Int] ())
--   1&lt;Enter&gt;
--   2&lt;Enter&gt;
--   qqqqqqqqqq&lt;Enter&gt;
--   "Prelude.read: no parse"
--   3&lt;Enter&gt;
--   rrrrrrrrrr&lt;Enter&gt;
--   "Prelude.read: no parse"
--   [1,2,3] :&gt; ()
--   </pre>
--   
--   <pre>
--   partitionEithers = separate . maps S.eitherToSum
--   lefts  = hoist S.effects . partitionEithers
--   rights = S.effects . partitionEithers
--   rights = S.concat
--   </pre>
partitionEithers :: Monad m => Stream (Of (Either a b)) m r -> Stream (Of a) (Stream (Of b) m) r

-- | <pre>
--   filter p = hoist effects (partition p)
--   </pre>
partition :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) (Stream (Of a) m) r

-- | Merge two streams of elements ordered with their <a>Ord</a> instance.
--   
--   The return values of both streams are returned.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ merge (each [1,3,5]) (each [2,4])
--   1
--   2
--   3
--   4
--   5
--   ((), ())
--   </pre>
merge :: (Monad m, Ord a) => Stream (Of a) m r -> Stream (Of a) m s -> Stream (Of a) m (r, s)

-- | Merge two streams, ordering them by applying the given function to
--   each element before comparing.
--   
--   The return values of both streams are returned.
mergeOn :: (Monad m, Ord b) => (a -> b) -> Stream (Of a) m r -> Stream (Of a) m s -> Stream (Of a) m (r, s)

-- | Merge two streams, ordering the elements using the given comparison
--   function.
--   
--   The return values of both streams are returned.
mergeBy :: Monad m => (a -> a -> Ordering) -> Stream (Of a) m r -> Stream (Of a) m s -> Stream (Of a) m (r, s)

-- | The <a>catMaybes</a> function takes a <a>Stream</a> of <a>Maybe</a>s
--   and returns a <a>Stream</a> of all of the <a>Just</a> values.
--   <a>concat</a> has the same behavior, but is more general; it works for
--   any foldable container type.
catMaybes :: Monad m => Stream (Of (Maybe a)) m r -> Stream (Of a) m r

-- | The <a>mapMaybe</a> function is a version of <a>map</a> which can
--   throw out elements. In particular, the functional argument returns
--   something of type <tt><a>Maybe</a> b</tt>. If this is <a>Nothing</a>,
--   no element is added on to the result <a>Stream</a>. If it is
--   <tt><a>Just</a> b</tt>, then <tt>b</tt> is included in the result
--   <a>Stream</a>.
mapMaybe :: Monad m => (a -> Maybe b) -> Stream (Of a) m r -> Stream (Of b) m r

-- | Note that <a>lazily</a>, <a>strictly</a>, <a>fst'</a>, and
--   <a>mapOf</a> are all so-called <i>natural transformations</i> on the
--   primitive <tt>Of a</tt> functor. If we write
--   
--   <pre>
--   type f ~~&gt; g = forall x . f x -&gt; g x
--   </pre>
--   
--   then we can restate some types as follows:
--   
--   <pre>
--   mapOf            :: (a -&gt; b) -&gt; Of a ~~&gt; Of b   -- Bifunctor first
--   lazily           ::             Of a ~~&gt; (,) a
--   Identity . fst'  ::             Of a ~~&gt; Identity a
--   </pre>
--   
--   Manipulation of a <tt>Stream f m r</tt> by mapping often turns on
--   recognizing natural transformations of <tt>f</tt>. Thus <tt>maps</tt>
--   is far more general the the <tt>map</tt> of the
--   <tt>Streaming.Prelude</tt>, which can be defined thus:
--   
--   <pre>
--   S.map :: (a -&gt; b) -&gt; Stream (Of a) m r -&gt; Stream (Of b) m r
--   S.map f = maps (mapOf f)
--   </pre>
--   
--   i.e.
--   
--   <pre>
--   S.map f = maps (\(a :&gt; x) -&gt; (f a :&gt; x))
--   </pre>
--   
--   This rests on recognizing that <tt>mapOf</tt> is a natural
--   transformation; note though that it results in such a transformation
--   as well:
--   
--   <pre>
--   S.map :: (a -&gt; b) -&gt; Stream (Of a) m ~~&gt; Stream (Of b) m
--   </pre>
--   
--   Thus we can <tt>maps</tt> it in turn.
lazily :: Of a b -> (a, b)

-- | Convert a standard Haskell pair into a left-strict pair
strictly :: (a, b) -> Of a b

-- | <tt>fst'</tt> and <tt>snd'</tt> extract the first and second element
--   of a pair
--   
--   <pre>
--   &gt;&gt;&gt; S.fst' (1:&gt;"hi")
--   1
--   
--   &gt;&gt;&gt; S.snd' (1:&gt;"hi")
--   "hi"
--   </pre>
--   
--   They are contained in the <tt>_first</tt> and <tt>_second</tt> lenses,
--   if any lens library is in scope
--   
--   <pre>
--   &gt;&gt;&gt; import Lens.Micro
--   
--   &gt;&gt;&gt; (1:&gt;"hi") ^. S._first
--   1
--   
--   &gt;&gt;&gt; (1:&gt;"hi") ^. S._second
--   "hi"
--   </pre>
fst' :: Of a b -> a
snd' :: Of a b -> b

-- | Map a function over the first element of an <tt>Of</tt> pair
--   
--   <pre>
--   &gt;&gt;&gt; S.mapOf even (1:&gt;"hi")
--   False :&gt; "hi"
--   </pre>
--   
--   <tt>mapOf</tt> is just <tt>first</tt> from the <tt>Bifunctor</tt>
--   instance
--   
--   <pre>
--   &gt;&gt;&gt; first even (1:&gt;"hi")
--   False :&gt; "hi"
--   </pre>
--   
--   and is contained in the <tt>_first</tt> lens
--   
--   <pre>
--   &gt;&gt;&gt; import Lens.Micro
--   
--   &gt;&gt;&gt; over S._first even (1:&gt;"hi")
--   False :&gt; "hi"
--   </pre>
mapOf :: (a -> b) -> Of a r -> Of b r

-- | A lens into the first element of a left-strict pair
_first :: Functor f => (a -> f a') -> Of a b -> f (Of a' b)

-- | A lens into the second element of a left-strict pair
_second :: Functor f => (b -> f b') -> Of a b -> f (Of a b')

-- | Read an <tt>IORef (Maybe a)</tt> or a similar device until it reads
--   <tt>Nothing</tt>. <tt>reread</tt> provides convenient exit from the
--   <tt>io-streams</tt> library
--   
--   <pre>
--   reread readIORef    :: IORef (Maybe a) -&gt; Stream (Of a) IO ()
--   reread Streams.read :: System.IO.Streams.InputStream a -&gt; Stream (Of a) IO ()
--   </pre>
reread :: Monad m => (s -> m (Maybe a)) -> s -> Stream (Of a) m ()
data Stream f m r

module Streaming
data Stream f m r

-- | <tt>yields</tt> is like <tt>lift</tt> for items in the streamed
--   functor. It makes a singleton or one-layer succession.
--   
--   <pre>
--   lift :: (Monad m, Functor f)    =&gt; m r -&gt; Stream f m r
--   yields ::  (Monad m, Functor f) =&gt; f r -&gt; Stream f m r
--   </pre>
--   
--   Viewed in another light, it is like a functor-general version of
--   <tt>yield</tt>:
--   
--   <pre>
--   S.yield a = yields (a :&gt; ())
--   </pre>
yields :: (Monad m, Functor f) => f r -> Stream f m r

-- | Wrap an effect that returns a stream
--   
--   <pre>
--   effect = join . lift
--   </pre>
effect :: (Monad m, Functor f) => m (Stream f m r) -> Stream f m r

-- | Wrap a new layer of a stream. So, e.g.
--   
--   <pre>
--   S.cons :: Monad m =&gt; a -&gt; Stream (Of a) m r -&gt; Stream (Of a) m r
--   S.cons a str = wrap (a :&gt; str)
--   </pre>
--   
--   and, recursively:
--   
--   <pre>
--   S.each :: (Monad m, Foldable t) =&gt; t a -&gt; Stream (Of a) m ()
--   S.each = foldr (\a b -&gt; wrap (a :&gt; b)) (return ())
--   </pre>
--   
--   The two operations
--   
--   <pre>
--   wrap :: (Monad m, Functor f )   =&gt; f (Stream f m r) -&gt; Stream f m r
--   effect :: (Monad m, Functor f ) =&gt; m (Stream f m r) -&gt; Stream f m r
--   </pre>
--   
--   are fundamental. We can define the parallel operations <tt>yields</tt>
--   and <tt>lift</tt> in terms of them
--   
--   <pre>
--   yields :: (Monad m, Functor f )  =&gt; f r -&gt; Stream f m r
--   yields = wrap . fmap return
--   lift ::  (Monad m, Functor f )   =&gt; m r -&gt; Stream f m r
--   lift = effect . fmap return
--   </pre>
wrap :: (Monad m, Functor f) => f (Stream f m r) -> Stream f m r

-- | Repeat a functorial layer, command or instruction a fixed number of
--   times.
--   
--   <pre>
--   replicates n = takes n . repeats
--   </pre>
replicates :: (Monad m, Functor f) => Int -> f () -> Stream f m ()

-- | Repeat a functorial layer (a "command" or "instruction") forever.
repeats :: (Monad m, Functor f) => f () -> Stream f m r

-- | Repeat an effect containing a functorial layer, command or instruction
--   forever.
repeatsM :: (Monad m, Functor f) => m (f ()) -> Stream f m r

-- | Build a <tt>Stream</tt> by unfolding steps starting from a seed. See
--   also the specialized <a>unfoldr</a> in the prelude.
--   
--   <pre>
--   unfold inspect = id -- modulo the quotient we work with
--   unfold Pipes.next :: Monad m =&gt; Producer a m r -&gt; Stream ((,) a) m r
--   unfold (curry (:&gt;) . Pipes.next) :: Monad m =&gt; Producer a m r -&gt; Stream (Of a) m r
--   </pre>
unfold :: (Monad m, Functor f) => (s -> m (Either r (f s))) -> s -> Stream f m r

-- | <a>never</a> interleaves the pure applicative action with the return
--   of the monad forever. It is the <a>empty</a> of the <a>Alternative</a>
--   instance, thus
--   
--   <pre>
--   never &lt;|&gt; a = a
--   a &lt;|&gt; never = a
--   </pre>
--   
--   and so on. If w is a monoid then <tt>never :: Stream (Of w) m r</tt>
--   is the infinite sequence of <a>mempty</a>, and <tt>str1 &lt;|&gt;
--   str2</tt> appends the elements monoidally until one of streams ends.
--   Thus we have, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.take 2 $ S.stdinLn &lt;|&gt; S.repeat " " &lt;|&gt; S.stdinLn  &lt;|&gt; S.repeat " " &lt;|&gt; S.stdinLn
--   1&lt;Enter&gt;
--   2&lt;Enter&gt;
--   3&lt;Enter&gt;
--   1 2 3
--   4&lt;Enter&gt;
--   5&lt;Enter&gt;
--   6&lt;Enter&gt;
--   4 5 6
--   </pre>
--   
--   This is equivalent to
--   
--   <pre>
--   &gt;&gt;&gt; S.stdoutLn $ S.take 2 $ foldr (&lt;|&gt;) never [S.stdinLn, S.repeat " ", S.stdinLn, S.repeat " ", S.stdinLn ]
--   </pre>
--   
--   Where <tt>f</tt> is a monad, <tt>(&lt;|&gt;)</tt> sequences the
--   conjoined streams stepwise. See the definition of <tt>paste</tt>
--   <a>here</a>, where the separate steps are bytestreams corresponding to
--   the lines of a file.
--   
--   Given, say,
--   
--   <pre>
--   data Branch r = Branch r r deriving Functor  -- add obvious applicative instance
--   </pre>
--   
--   then <tt>never :: Stream Branch Identity r</tt> is the pure infinite
--   binary tree with (inaccessible) <tt>r</tt>s in its leaves. Given two
--   binary trees, <tt>tree1 &lt;|&gt; tree2</tt> intersects them,
--   preserving the leaves that came first, so <tt>tree1 &lt;|&gt; never =
--   tree1</tt>
--   
--   <tt>Stream Identity m r</tt> is an action in <tt>m</tt> that is
--   indefinitely delayed. Such an action can be constructed with e.g.
--   <a>untilJust</a>.
--   
--   <pre>
--   untilJust :: (Monad m, Applicative f) =&gt; m (Maybe r) -&gt; Stream f m r
--   </pre>
--   
--   Given two such items, <tt>&lt;|&gt;</tt> instance races them. It is
--   thus the iterative monad transformer specially defined in
--   <a>Control.Monad.Trans.Iter</a>
--   
--   So, for example, we might write
--   
--   <pre>
--   &gt;&gt;&gt; let justFour str = if length str == 4 then Just str else Nothing
--   
--   &gt;&gt;&gt; let four = untilJust (fmap justFour getLine)
--   
--   &gt;&gt;&gt; run four
--   one&lt;Enter&gt;
--   two&lt;Enter&gt;
--   three&lt;Enter&gt;
--   four&lt;Enter&gt;
--   "four"
--   </pre>
--   
--   The <a>Alternative</a> instance in <a>Control.Monad.Trans.Free</a> is
--   avowedly wrong, though no explanation is given for this.
never :: (Monad m, Applicative f) => Stream f m r

-- | Repeat a
untilJust :: (Monad m, Applicative f) => m (Maybe r) -> Stream f m r

-- | Reflect a church-encoded stream; cp. <tt>GHC.Exts.build</tt>
--   
--   <pre>
--   streamFold return_ effect_ step_ (streamBuild psi) = psi return_ effect_ step_
--   </pre>
streamBuild :: (forall b. (r -> b) -> (m b -> b) -> (f b -> b) -> b) -> Stream f m r
delays :: (MonadIO m, Applicative f) => Double -> Stream f m r

-- | Map layers of one functor to another with a transformation. Compare
--   hoist, which has a similar effect on the <tt>monadic</tt> parameter.
--   
--   <pre>
--   maps id = id
--   maps f . maps g = maps (f . g)
--   </pre>
maps :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation. Compare
--   hoist, which has a similar effect on the <tt>monadic</tt> parameter.
--   
--   <pre>
--   mapsPost id = id
--   mapsPost f . mapsPost g = mapsPost (f . g)
--   mapsPost f = maps f
--   </pre>
--   
--   <tt>mapsPost</tt> is essentially the same as <a>maps</a>, but it
--   imposes a <a>Functor</a> constraint on its target functor rather than
--   its source functor. It should be preferred if <a>fmap</a> is cheaper
--   for the target functor than for the source functor.
mapsPost :: forall m f g r. (Monad m, Functor g) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation involving
--   the base monad. <a>maps</a> is more fundamental than <tt>mapsM</tt>,
--   which is best understood as a convenience for effecting this frequent
--   composition:
--   
--   <pre>
--   mapsM phi = decompose . maps (Compose . phi)
--   </pre>
--   
--   The streaming prelude exports the same function under the better name
--   <tt>mapped</tt>, which overlaps with the lens libraries.
mapsM :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation involving
--   the base monad. <tt>mapsMPost</tt> is essentially the same as
--   <a>mapsM</a>, but it imposes a <a>Functor</a> constraint on its target
--   functor rather than its source functor. It should be preferred if
--   <a>fmap</a> is cheaper for the target functor than for the source
--   functor.
--   
--   <tt>mapsPost</tt> is more fundamental than <tt>mapsMPost</tt>, which
--   is best understood as a convenience for effecting this frequent
--   composition:
--   
--   <pre>
--   mapsMPost phi = decompose . mapsPost (Compose . phi)
--   </pre>
--   
--   The streaming prelude exports the same function under the better name
--   <tt>mappedPost</tt>, which overlaps with the lens libraries.
mapsMPost :: forall m f g r. (Monad m, Functor g) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | Map layers of one functor to another with a transformation involving
--   the base monad.
--   
--   This function is completely functor-general. It is often useful with
--   the more concrete type
--   
--   <pre>
--   mapped :: (forall x. Stream (Of a) IO x -&gt; IO (Of b x)) -&gt; Stream (Stream (Of a) IO) IO r -&gt; Stream (Of b) IO r
--   </pre>
--   
--   to process groups which have been demarcated in an effectful,
--   <tt>IO</tt>-based stream by grouping functions like <a>group</a>,
--   <a>split</a> or <a>breaks</a>. Summary functions like <a>fold</a>,
--   <a>foldM</a>, <a>mconcat</a> or <a>toList</a> are often used to define
--   the transformation argument. For example:
--   
--   <pre>
--   &gt;&gt;&gt; S.toList_ $ S.mapped S.toList $ S.split 'c' (S.each "abcde")
--   ["ab","de"]
--   </pre>
--   
--   <a>maps</a> and <a>mapped</a> obey these rules:
--   
--   <pre>
--   maps id              = id
--   mapped return        = id
--   maps f . maps g      = maps (f . g)
--   mapped f . mapped g  = mapped (f &lt;=&lt; g)
--   maps f . mapped g    = mapped (fmap f . g)
--   mapped f . maps g    = mapped (f &lt;=&lt; fmap g)
--   </pre>
--   
--   <a>maps</a> is more fundamental than <a>mapped</a>, which is best
--   understood as a convenience for effecting this frequent composition:
--   
--   <pre>
--   mapped phi = decompose . maps (Compose . phi)
--   </pre>
mapped :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | A version of <a>mapped</a> that imposes a <a>Functor</a> constraint on
--   the target functor rather than the source functor. This version should
--   be preferred if <a>fmap</a> on the target functor is cheaper.
mappedPost :: (Monad m, Functor g) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r

-- | A less-efficient version of <a>hoist</a> that works properly even when
--   its argument is not a monad morphism.
--   
--   <pre>
--   hoistUnexposed = hoist . unexposed
--   </pre>
hoistUnexposed :: (Monad m, Functor f) => (forall a. m a -> n a) -> Stream f m r -> Stream f n r

-- | Make it possible to 'run' the underlying transformed monad.
distribute :: (Monad m, Functor f, MonadTrans t, MFunctor t, Monad (t (Stream f m))) => Stream f (t m) r -> t (Stream f m) r

-- | Group layers in an alternating stream into adjoining sub-streams of
--   one type or another.
groups :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream (Sum (Stream f m) (Stream g m)) m r

-- | Inspect the first stage of a freely layered sequence. Compare
--   <tt>Pipes.next</tt> and the replica <tt>Streaming.Prelude.next</tt>.
--   This is the <tt>uncons</tt> for the general <a>unfold</a>.
--   
--   <pre>
--   unfold inspect = id
--   Streaming.Prelude.unfoldr StreamingPrelude.next = id
--   </pre>
inspect :: Monad m => Stream f m r -> m (Either r (f (Stream f m r)))

-- | Split a succession of layers after some number, returning a streaming
--   or effectful pair.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.print $ S.splitAt 1 $ each [1..3]
--   1
--   
--   &gt;&gt;&gt; S.print rest
--   2
--   3
--   </pre>
--   
--   <pre>
--   splitAt 0 = return
--   splitAt n &gt;=&gt; splitAt m = splitAt (m+n)
--   </pre>
--   
--   Thus, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- S.print $ splitsAt 2 &gt;=&gt; splitsAt 2 $ each [1..5]
--   1
--   2
--   3
--   4
--   
--   &gt;&gt;&gt; S.print rest
--   5
--   </pre>
splitsAt :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Stream f m r)
takes :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m ()

-- | Break a stream into substreams each with n functorial layers.
--   
--   <pre>
--   &gt;&gt;&gt; S.print $ mapped S.sum $ chunksOf 2 $ each [1,1,1,1,1]
--   2
--   2
--   1
--   </pre>
chunksOf :: (Monad m, Functor f) => Int -> Stream f m r -> Stream (Stream f m) m r

-- | Dissolves the segmentation into layers of <tt>Stream f m</tt> layers.
concats :: (Monad m, Functor f) => Stream (Stream f m) m r -> Stream f m r

-- | Interpolate a layer at each segment. This specializes to e.g.
--   
--   <pre>
--   intercalates :: (Monad m, Functor f) =&gt; Stream f m () -&gt; Stream (Stream f m) m r -&gt; Stream f m r
--   </pre>
intercalates :: (Monad m, Monad (t m), MonadTrans t) => t m x -> Stream (t m) m r -> t m r
cutoff :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Maybe r)

-- | Zip two streams together. The <a>zipsWith'</a> function should
--   generally be preferred for efficiency.
zipsWith :: forall f g h m r. (Monad m, Functor h) => (forall x y. f x -> g y -> h (x, y)) -> Stream f m r -> Stream g m r -> Stream h m r

-- | Zip two streams together.
zipsWith' :: forall f g h m r. Monad m => (forall x y p. (x -> y -> p) -> f x -> g y -> h p) -> Stream f m r -> Stream g m r -> Stream h m r
zips :: (Monad m, Functor f, Functor g) => Stream f m r -> Stream g m r -> Stream (Compose f g) m r
unzips :: (Monad m, Functor f, Functor g) => Stream (Compose f g) m r -> Stream f (Stream g m) r

-- | Interleave functor layers, with the effects of the first preceding the
--   effects of the second. When the first stream runs out, any remaining
--   effects in the second are ignored.
--   
--   <pre>
--   interleaves = zipsWith (liftA2 (,))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let paste = \a b -&gt; interleaves (Q.lines a) (maps (Q.cons' '\t') (Q.lines b))
--   
--   &gt;&gt;&gt; Q.stdout $ Q.unlines $ paste "hello\nworld\n" "goodbye\nworld\n"
--   hello	goodbye
--   world	world
--   </pre>
interleaves :: (Monad m, Applicative h) => Stream h m r -> Stream h m r -> Stream h m r

-- | Given a stream on a sum of functors, make it a stream on the left
--   functor, with the streaming on the other functor as the governing
--   monad. This is useful for acting on one or the other functor with a
--   fold, leaving the other material for another treatment. It generalizes
--   <a>partitionEithers</a>, but actually streams properly.
--   
--   <pre>
--   &gt;&gt;&gt; let odd_even = S.maps (S.distinguish even) $ S.each [1..10::Int]
--   
--   &gt;&gt;&gt; :t separate odd_even
--   separate odd_even
--     :: Monad m =&gt; Stream (Of Int) (Stream (Of Int) m) ()
--   </pre>
--   
--   Now, for example, it is convenient to fold on the left and right
--   values separately:
--   
--   <pre>
--   &gt;&gt;&gt; S.toList $ S.toList $ separate odd_even
--   [2,4,6,8,10] :&gt; ([1,3,5,7,9] :&gt; ())
--   </pre>
--   
--   Or we can write them to separate files or whatever:
--   
--   <pre>
--   &gt;&gt;&gt; S.writeFile "even.txt" . S.show $ S.writeFile "odd.txt" . S.show $ S.separate odd_even
--   
--   &gt;&gt;&gt; :! cat even.txt
--   2
--   4
--   6
--   8
--   10
--   
--   &gt;&gt;&gt; :! cat odd.txt
--   1
--   3
--   5
--   7
--   9
--   </pre>
--   
--   Of course, in the special case of <tt>Stream (Of a) m r</tt>, we can
--   achieve the above effects more simply by using <a>copy</a>
--   
--   <pre>
--   &gt;&gt;&gt; S.toList . S.filter even $ S.toList . S.filter odd $ S.copy $ each [1..10::Int]
--   [2,4,6,8,10] :&gt; ([1,3,5,7,9] :&gt; ())
--   </pre>
--   
--   But <a>separate</a> and <a>unseparate</a> are functor-general.
separate :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream f (Stream g m) r
unseparate :: (Monad m, Functor f, Functor g) => Stream f (Stream g m) r -> Stream (Sum f g) m r

-- | Rearrange a succession of layers of the form <tt>Compose m (f x)</tt>.
--   
--   we could as well define <tt>decompose</tt> by <tt>mapsM</tt>:
--   
--   <pre>
--   decompose = mapped getCompose
--   </pre>
--   
--   but <tt>mapped</tt> is best understood as:
--   
--   <pre>
--   mapped phi = decompose . maps (Compose . phi)
--   </pre>
--   
--   since <tt>maps</tt> and <tt>hoist</tt> are the really fundamental
--   operations that preserve the shape of the stream:
--   
--   <pre>
--   maps  :: (Monad m, Functor f) =&gt; (forall x. f x -&gt; g x) -&gt; Stream f m r -&gt; Stream g m r
--   hoist :: (Monad m, Functor f) =&gt; (forall a. m a -&gt; n a) -&gt; Stream f m r -&gt; Stream f n r
--   </pre>
decompose :: (Monad m, Functor f) => Stream (Compose m f) m r -> Stream f m r

-- | If <tt>Of</tt> had a <tt>Comonad</tt> instance, then we'd have
--   
--   <pre>
--   copy = expand extend
--   </pre>
--   
--   See <a>expandPost</a> for a version that requires a <tt>Functor g</tt>
--   instance instead.
expand :: (Monad m, Functor f) => (forall a b. (g a -> b) -> f a -> h b) -> Stream f m r -> Stream g (Stream h m) r

-- | If <tt>Of</tt> had a <tt>Comonad</tt> instance, then we'd have
--   
--   <pre>
--   copy = expandPost extend
--   </pre>
--   
--   See <a>expand</a> for a version that requires a <tt>Functor f</tt>
--   instance instead.
expandPost :: (Monad m, Functor g) => (forall a b. (g a -> b) -> f a -> h b) -> Stream f m r -> Stream g (Stream h m) r

-- | Map each layer to an effect, and run them all.
mapsM_ :: (Functor f, Monad m) => (forall x. f x -> m x) -> Stream f m r -> m r

-- | Run the effects in a stream that merely layers effects.
run :: Monad m => Stream m m r -> m r

-- | <a>streamFold</a> reorders the arguments of <a>destroy</a> to be more
--   akin to <tt>foldr</tt> It is more convenient to query in ghci to
--   figure out what kind of 'algebra' you need to write.
--   
--   <pre>
--   &gt;&gt;&gt; :t streamFold return join
--   (Monad m, Functor f) =&gt;
--        (f (m a) -&gt; m a) -&gt; Stream f m a -&gt; m a        -- iterT
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t streamFold return (join . lift)
--   (Monad m, Monad (t m), Functor f, MonadTrans t) =&gt;
--        (f (t m a) -&gt; t m a) -&gt; Stream f m a -&gt; t m a  -- iterTM
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t streamFold return effect
--   (Monad m, Functor f, Functor g) =&gt;
--        (f (Stream g m r) -&gt; Stream g m r) -&gt; Stream f m r -&gt; Stream g m r
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t \f -&gt; streamFold return effect (wrap . f)
--   (Monad m, Functor f, Functor g) =&gt;
--        (f (Stream g m a) -&gt; g (Stream g m a))
--        -&gt; Stream f m a -&gt; Stream g m a                 -- maps
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t \f -&gt; streamFold return effect (effect . fmap wrap . f)
--   (Monad m, Functor f, Functor g) =&gt;
--        (f (Stream g m a) -&gt; m (g (Stream g m a)))
--        -&gt; Stream f m a -&gt; Stream g m a                 -- mapped
--   </pre>
--   
--   <pre>
--   streamFold done eff construct
--      = eff . iterT (return . construct . fmap eff) . fmap done
--   </pre>
streamFold :: (Functor f, Monad m) => (r -> b) -> (m b -> b) -> (f b -> b) -> Stream f m r -> b

-- | Specialized fold following the usage of
--   <tt>Control.Monad.Trans.Free</tt>
--   
--   <pre>
--   iterTM alg = streamFold return (join . lift)
--   iterTM alg = iterT alg . hoist lift
--   </pre>
iterTM :: (Functor f, Monad m, MonadTrans t, Monad (t m)) => (f (t m a) -> t m a) -> Stream f m a -> t m a

-- | Specialized fold following the usage of
--   <tt>Control.Monad.Trans.Free</tt>
--   
--   <pre>
--   iterT alg = streamFold return join alg
--   iterT alg = runIdentityT . iterTM (IdentityT . alg . fmap runIdentityT)
--   </pre>
iterT :: (Functor f, Monad m) => (f (m a) -> m a) -> Stream f m a -> m a

-- | Map a stream to its church encoding; compare <tt>Data.List.foldr</tt>.
--   <a>destroyExposed</a> may be more efficient in some cases when
--   applicable, but it is less safe.
--   
--   <pre>
--   destroy s construct eff done
--     = eff . iterT (return . construct . fmap eff) . fmap done $ s
--   
--   </pre>
destroy :: (Functor f, Monad m) => Stream f m r -> (f b -> b) -> (m b -> b) -> (r -> b) -> b

-- | A left-strict pair; the base functor for streams of individual
--   elements.
data Of a b
(:>) :: !a -> b -> Of a b
infixr 5 :>

-- | Note that <a>lazily</a>, <a>strictly</a>, <a>fst'</a>, and
--   <a>mapOf</a> are all so-called <i>natural transformations</i> on the
--   primitive <tt>Of a</tt> functor. If we write
--   
--   <pre>
--   type f ~~&gt; g = forall x . f x -&gt; g x
--   </pre>
--   
--   then we can restate some types as follows:
--   
--   <pre>
--   mapOf            :: (a -&gt; b) -&gt; Of a ~~&gt; Of b   -- Bifunctor first
--   lazily           ::             Of a ~~&gt; (,) a
--   Identity . fst'  ::             Of a ~~&gt; Identity a
--   </pre>
--   
--   Manipulation of a <tt>Stream f m r</tt> by mapping often turns on
--   recognizing natural transformations of <tt>f</tt>. Thus <tt>maps</tt>
--   is far more general the the <tt>map</tt> of the
--   <tt>Streaming.Prelude</tt>, which can be defined thus:
--   
--   <pre>
--   S.map :: (a -&gt; b) -&gt; Stream (Of a) m r -&gt; Stream (Of b) m r
--   S.map f = maps (mapOf f)
--   </pre>
--   
--   i.e.
--   
--   <pre>
--   S.map f = maps (\(a :&gt; x) -&gt; (f a :&gt; x))
--   </pre>
--   
--   This rests on recognizing that <tt>mapOf</tt> is a natural
--   transformation; note though that it results in such a transformation
--   as well:
--   
--   <pre>
--   S.map :: (a -&gt; b) -&gt; Stream (Of a) m ~~&gt; Stream (Of b) m
--   </pre>
--   
--   Thus we can <tt>maps</tt> it in turn.
lazily :: Of a b -> (a, b)

-- | Convert a standard Haskell pair into a left-strict pair
strictly :: (a, b) -> Of a b

-- | A functor in the category of monads, using <a>hoist</a> as the analog
--   of <a>fmap</a>:
--   
--   <pre>
--   hoist (f . g) = hoist f . hoist g
--   
--   hoist id = id
--   </pre>
class MFunctor (t :: Type -> Type -> k -> Type)

-- | Lift a monad morphism from <tt>m</tt> to <tt>n</tt> into a monad
--   morphism from <tt>(t m)</tt> to <tt>(t n)</tt>
--   
--   The first argument to <a>hoist</a> must be a monad morphism, even
--   though the type system does not enforce this
hoist :: forall m n (b :: k). (MFunctor t, Monad m) => (forall a. () => m a -> n a) -> t m b -> t n b

-- | A monad in the category of monads, using <a>lift</a> from
--   <a>MonadTrans</a> as the analog of <a>return</a> and <a>embed</a> as
--   the analog of (<a>=&lt;&lt;</a>):
--   
--   <pre>
--   embed lift = id
--   
--   embed f (lift m) = f m
--   
--   embed g (embed f t) = embed (\m -&gt; embed g (f m)) t
--   </pre>
class (MFunctor t, MonadTrans t) => MMonad (t :: Type -> Type -> Type -> Type)

-- | Embed a newly created <a>MMonad</a> layer within an existing layer
--   
--   <a>embed</a> is analogous to (<a>=&lt;&lt;</a>)
embed :: forall (n :: Type -> Type) m b. (MMonad t, Monad n) => (forall a. () => m a -> t n a) -> t m b -> t n b

-- | The class of monad transformers. Instances should satisfy the
--   following laws, which state that <a>lift</a> is a monad
--   transformation:
--   
--   <ul>
--   <li><pre><a>lift</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>lift</a> (m &gt;&gt;= f) = <a>lift</a> m &gt;&gt;=
--   (<a>lift</a> . f)</pre></li>
--   </ul>
class MonadTrans (t :: Type -> Type -> Type -> Type)

-- | Lift a computation from the argument monad to the constructed monad.
lift :: (MonadTrans t, Monad m) => m a -> t m a

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO (m :: Type -> Type)

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => IO a -> m a

-- | Right-to-left composition of functors. The composition of applicative
--   functors is always applicative, but the composition of monads is not
--   always a monad.
newtype Compose (f :: k -> Type) (g :: k1 -> k) (a :: k1)
Compose :: f (g a) -> Compose (f :: k -> Type) (g :: k1 -> k) (a :: k1)
[getCompose] :: Compose (f :: k -> Type) (g :: k1 -> k) (a :: k1) -> f (g a)
infixr 9 `Compose`
infixr 9 `Compose`

-- | Lifted sum of functors.
data Sum (f :: k -> Type) (g :: k -> Type) (a :: k)
InL :: f a -> Sum (f :: k -> Type) (g :: k -> Type) (a :: k)
InR :: g a -> Sum (f :: k -> Type) (g :: k -> Type) (a :: k)

-- | Identity functor and monad. (a non-strict monad)
newtype Identity a
Identity :: a -> Identity a
[runIdentity] :: Identity a -> a

-- | A monoid on applicative functors.
--   
--   If defined, <a>some</a> and <a>many</a> should be the least solutions
--   of the equations:
--   
--   <ul>
--   <li><pre><a>some</a> v = (:) <a>&lt;$&gt;</a> v <a>&lt;*&gt;</a>
--   <a>many</a> v</pre></li>
--   <li><pre><a>many</a> v = <a>some</a> v <a>&lt;|&gt;</a> <a>pure</a>
--   []</pre></li>
--   </ul>
class Applicative f => Alternative (f :: Type -> Type)

-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a
infixl 3 <|>

-- | A bifunctor is a type constructor that takes two type arguments and is
--   a functor in <i>both</i> arguments. That is, unlike with
--   <a>Functor</a>, a type constructor such as <a>Either</a> does not need
--   to be partially applied for a <a>Bifunctor</a> instance, and the
--   methods in this class permit mapping functions over the <a>Left</a>
--   value or the <a>Right</a> value, or both at the same time.
--   
--   Formally, the class <a>Bifunctor</a> represents a bifunctor from
--   <tt>Hask</tt> -&gt; <tt>Hask</tt>.
--   
--   Intuitively it is a bifunctor where both the first and second
--   arguments are covariant.
--   
--   You can define a <a>Bifunctor</a> by either defining <a>bimap</a> or
--   by defining both <a>first</a> and <a>second</a>.
--   
--   If you supply <a>bimap</a>, you should ensure that:
--   
--   <pre>
--   <a>bimap</a> <a>id</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply <a>first</a> and <a>second</a>, ensure:
--   
--   <pre>
--   <a>first</a> <a>id</a> ≡ <a>id</a>
--   <a>second</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply both, you should also ensure:
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>first</a> f <a>.</a> <a>second</a> g
--   </pre>
--   
--   These ensure by parametricity:
--   
--   <pre>
--   <a>bimap</a>  (f <a>.</a> g) (h <a>.</a> i) ≡ <a>bimap</a> f h <a>.</a> <a>bimap</a> g i
--   <a>first</a>  (f <a>.</a> g) ≡ <a>first</a>  f <a>.</a> <a>first</a>  g
--   <a>second</a> (f <a>.</a> g) ≡ <a>second</a> f <a>.</a> <a>second</a> g
--   </pre>
class Bifunctor (p :: Type -> Type -> Type)

-- | Map over both arguments at the same time.
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>first</a> f <a>.</a> <a>second</a> g
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) ('j', 3)
--   ('J',4)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) (Left 'j')
--   Left 'J'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) (Right 3)
--   Right 4
--   </pre>
bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d

-- | Map covariantly over the first argument.
--   
--   <pre>
--   <a>first</a> f ≡ <a>bimap</a> f <a>id</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; first toUpper ('j', 3)
--   ('J',3)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; first toUpper (Left 'j')
--   Left 'J'
--   </pre>
first :: Bifunctor p => (a -> b) -> p a c -> p b c

-- | Map covariantly over the second argument.
--   
--   <pre>
--   <a>second</a> ≡ <a>bimap</a> <a>id</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; second (+1) ('j', 3)
--   ('j',4)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; second (+1) (Right 3)
--   Right 4
--   </pre>
second :: Bifunctor p => (b -> c) -> p a b -> p a c

-- | The <a>join</a> function is the conventional monad join operator. It
--   is used to remove one level of monadic structure, projecting its bound
--   argument into the outer level.
--   
--   '<tt><a>join</a> bss</tt>' can be understood as the <tt>do</tt>
--   expression
--   
--   <pre>
--   do bs &lt;- bss
--      bs
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   A common use of <a>join</a> is to run an <a>IO</a> computation
--   returned from an <a>STM</a> transaction, since <a>STM</a> transactions
--   can't perform <a>IO</a> directly. Recall that
--   
--   <pre>
--   <a>atomically</a> :: STM a -&gt; IO a
--   </pre>
--   
--   is used to run <a>STM</a> transactions atomically. So, by specializing
--   the types of <a>atomically</a> and <a>join</a> to
--   
--   <pre>
--   <a>atomically</a> :: STM (IO b) -&gt; IO (IO b)
--   <a>join</a>       :: IO (IO b)  -&gt; IO b
--   </pre>
--   
--   we can compose them as
--   
--   <pre>
--   <a>join</a> . <a>atomically</a> :: STM (IO b) -&gt; IO b
--   </pre>
--   
--   to run an <a>STM</a> transaction and the <a>IO</a> action it returns.
join :: Monad m => m (m a) -> m a

-- | Promote a function to a monad.
liftM :: Monad m => (a1 -> r) -> m a1 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right. For example,
--   
--   <pre>
--   liftM2 (+) [0,1] [0,2] = [0,2,1,3]
--   liftM2 (+) (Just 1) Nothing = Nothing
--   </pre>
liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r

-- | Lift a binary function to actions.
--   
--   Some functors support an implementation of <a>liftA2</a> that is more
--   efficient than the default one. In particular, if <a>fmap</a> is an
--   expensive operation, it is likely better to use <a>liftA2</a> than to
--   <a>fmap</a> over the structure and then use <a>&lt;*&gt;</a>.
--   
--   This became a typeclass method in 4.10.0.0. Prior to that, it was a
--   function defined in terms of <a>&lt;*&gt;</a> and <a>fmap</a>.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt><a>liftA2</a> f as bs</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      b &lt;- bs
--      pure (f a b)
--   </pre>
liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c

-- | Lift a ternary function to actions.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt><a>liftA3</a> f as bs cs</tt>' can
--   be understood as the <tt>do</tt> expression
--   
--   <pre>
--   do a &lt;- as
--      b &lt;- bs
--      c &lt;- cs
--      pure (f a b c)
--   </pre>
liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d

-- | <tt><a>void</a> value</tt> discards or ignores the result of
--   evaluation, such as the return value of an <a>IO</a> action.
--   
--   Using <tt>ApplicativeDo</tt>: '<tt><a>void</a> as</tt>' can be
--   understood as the <tt>do</tt> expression
--   
--   <pre>
--   do as
--      pure ()
--   </pre>
--   
--   with an inferred <tt>Functor</tt> constraint.
--   
--   <h4><b>Examples</b></h4>
--   
--   Replace the contents of a <tt><a>Maybe</a> <a>Int</a></tt> with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void Nothing
--   Nothing
--   
--   &gt;&gt;&gt; void (Just 3)
--   Just ()
--   </pre>
--   
--   Replace the contents of an <tt><a>Either</a> <a>Int</a>
--   <a>Int</a></tt> with unit, resulting in an <tt><a>Either</a>
--   <a>Int</a> <tt>()</tt></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; void (Left 8675309)
--   Left 8675309
--   
--   &gt;&gt;&gt; void (Right 8675309)
--   Right ()
--   </pre>
--   
--   Replace every element of a list with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void [1,2,3]
--   [(),(),()]
--   </pre>
--   
--   Replace the second element of a pair with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void (1,2)
--   (1,())
--   </pre>
--   
--   Discard the result of an <a>IO</a> action:
--   
--   <pre>
--   &gt;&gt;&gt; mapM print [1,2]
--   1
--   2
--   [(),()]
--   
--   &gt;&gt;&gt; void $ mapM print [1,2]
--   1
--   2
--   </pre>
void :: Functor f => f a -> f ()

-- | An associative operation.
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &lt;&gt; [4,5,6]
--   [1,2,3,4,5,6]
--   </pre>
(<>) :: Semigroup a => a -> a -> a
infixr 6 <>
