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


-- | Group streams into substreams
--   
--   <tt>pipes-group</tt> uses <tt>FreeT</tt> and lenses to group streams
--   into sub-streams. Notable features include:
--   
--   <ul>
--   <li><i>Perfect Streaming</i>: Group elements without collecting them
--   into memory</li>
--   <li><i>Lens Support</i>: Use lenses to simplify many common
--   operations</li>
--   </ul>
--   
--   <tt>Pipes.Group</tt> contains the full documentation for this library.
--   
--   Read <tt>Pipes.Group.Tutorial</tt> for an extensive tutorial.
@package pipes-group
@version 1.0.3


-- | Element-agnostic grouping utilities for <tt>pipes</tt>
--   
--   See <a>Pipes.Group.Tutorial</a> for an extended tutorial
module Pipes.Group

-- | <a>groupsBy</a> splits a <a>Producer</a> into a <a>FreeT</a> of
--   <a>Producer</a>s grouped using the given equality predicate
--   
--   <pre>
--   &gt;&gt;&gt; import Lens.Family (view)
--   
--   &gt;&gt;&gt; import Pipes (yield, each)
--   
--   &gt;&gt;&gt; import Pipes.Prelude (toList)
--   
--   &gt;&gt;&gt; (toList . intercalates (yield '|') . view (groupsBy (==))) (each "12233345")
--   "1|22|333|4|5"
--   </pre>
--   
--   You can think of this as:
--   
--   <pre>
--   groupsBy
--       :: Monad m
--       =&gt; (a -&gt; a -&gt; Bool) -&gt; Lens' (Producer a m x) (FreeT (Producer a m) m x)
--   </pre>
groupsBy :: Monad m => (a' -> a' -> Bool) -> Lens (Producer a' m x) (Producer a m x) (FreeT (Producer a' m) m x) (FreeT (Producer a m) m x)

-- | <a>groupsBy'</a> splits a <a>Producer</a> into a <a>FreeT</a> of
--   <a>Producer</a>s grouped using the given equality predicate
--   
--   This differs from <a>groupsBy</a> by comparing successive elements for
--   equality instead of comparing each element to the first member of the
--   group
--   
--   <pre>
--   &gt;&gt;&gt; import Lens.Family (view)
--   
--   &gt;&gt;&gt; import Pipes (yield, each)
--   
--   &gt;&gt;&gt; import Pipes.Prelude (toList)
--   
--   &gt;&gt;&gt; let cmp c1 c2 = succ c1 == c2
--   
--   &gt;&gt;&gt; (toList . intercalates (yield '|') . view (groupsBy' cmp)) (each "12233345")
--   "12|23|3|345"
--   
--   &gt;&gt;&gt; (toList . intercalates (yield '|') . view (groupsBy  cmp)) (each "12233345")
--   "122|3|3|34|5"
--   </pre>
--   
--   You can think of this as:
--   
--   <pre>
--   groupsBy'
--       :: Monad m
--       =&gt; (a -&gt; a -&gt; Bool)
--       -&gt; Lens' (Producer a m x) (FreeT (Producer a m) m x)
--   </pre>
groupsBy' :: Monad m => (a' -> a' -> Bool) -> Lens (Producer a' m x) (Producer a m x) (FreeT (Producer a' m) m x) (FreeT (Producer a m) m x)

-- | Like <a>groupsBy</a>, where the equality predicate is (<a>==</a>)
--   
--   <pre>
--   &gt;&gt;&gt; import Lens.Family (view)
--   
--   &gt;&gt;&gt; import Pipes (yield, each)
--   
--   &gt;&gt;&gt; import Pipes.Prelude (toList)
--   
--   &gt;&gt;&gt; (toList . intercalates (yield '|') . view groups) (each "12233345")
--   "1|22|333|4|5"
--   </pre>
--   
--   You can think of this as:
--   
--   <pre>
--   groups
--       :: (Monad m, Eq a) =&gt; Lens' (Producer a m x) (FreeT (Producer a m) m x)
--   </pre>
groups :: (Monad m, Eq a') => Lens (Producer a' m x) (Producer a m x) (FreeT (Producer a' m) m x) (FreeT (Producer a m) m x)

-- | <a>chunksOf</a> is an splits a <a>Producer</a> into a <a>FreeT</a> of
--   <a>Producer</a>s of fixed length
--   
--   <pre>
--   &gt;&gt;&gt; import Lens.Family (view)
--   
--   &gt;&gt;&gt; import Pipes (yield, each)
--   
--   &gt;&gt;&gt; import Pipes.Prelude (toList)
--   
--   &gt;&gt;&gt; (toList . intercalates (yield '|') . view (chunksOf 3)) (each "12233345")
--   "122|333|45"
--   </pre>
--   
--   You can think of this as:
--   
--   <pre>
--   chunksOf
--       :: Monad m =&gt; Int -&gt; Lens' (Producer a m x) (FreeT (Producer a m) m x)
--   </pre>
chunksOf :: Monad m => Int -> Lens (Producer a' m x) (Producer a m x) (FreeT (Producer a' m) m x) (FreeT (Producer a m) m x)

-- | <tt>(takes n)</tt> only keeps the first <tt>n</tt> functor layers of a
--   <a>FreeT</a>
--   
--   <pre>
--   &gt;&gt;&gt; import Lens.Family (view)
--   
--   &gt;&gt;&gt; import Pipes (yield, each)
--   
--   &gt;&gt;&gt; import Pipes.Prelude (toList)
--   
--   &gt;&gt;&gt; (toList . intercalates (yield '|') . takes 3 . view groups) (each "12233345")
--   "1|22|333"
--   </pre>
--   
--   You can think of this as:
--   
--   <pre>
--   takes
--       :: (Functor f, Monad m)
--       =&gt; Int -&gt; FreeT (Producer a m) m () -&gt; FreeT (Producer a m) m ()
--   </pre>
takes :: (Functor f, Monad m) => Int -> FreeT f m () -> FreeT f m ()

-- | <tt>(takes' n)</tt> only keeps the first <tt>n</tt> <a>Producer</a>s
--   of a <a>FreeT</a>
--   
--   <a>takes'</a> differs from <a>takes</a> by draining unused
--   <a>Producer</a>s in order to preserve the return value. This makes it
--   a suitable argument for <a>maps</a>.
takes' :: Monad m => Int -> FreeT (Producer a m) m x -> FreeT (Producer a m) m x

-- | <tt>(drops n)</tt> peels off the first <tt>n</tt> <a>Producer</a>
--   layers of a <a>FreeT</a>
--   
--   <pre>
--   &gt;&gt;&gt; import Lens.Family (view)
--   
--   &gt;&gt;&gt; import Pipes (yield, each)
--   
--   &gt;&gt;&gt; import Pipes.Prelude (toList)
--   
--   &gt;&gt;&gt; (toList . intercalates (yield '|') . drops 3 . view groups) (each "12233345")
--   "4|5"
--   </pre>
--   
--   <b>Use carefully</b>: the peeling off is not free. This runs the first
--   <tt>n</tt> layers, just discarding everything they produce.
drops :: Monad m => Int -> FreeT (Producer a m) m x -> FreeT (Producer a m) m x

-- | Transform each individual functor layer of a <a>FreeT</a>
--   
--   You can think of this as:
--   
--   <pre>
--   maps
--       :: (forall r . Producer a m r -&gt; Producer b m r)
--       -&gt; FreeT (Producer a m) m x -&gt; FreeT (Producer b m) m x
--   </pre>
--   
--   This is just a synonym for <a>transFreeT</a>
maps :: (Monad m, Functor g) => (forall r. f r -> g r) -> FreeT f m x -> FreeT g m x

-- | Lens to transform each individual functor layer of a <a>FreeT</a>
--   
--   <pre>
--   over individually = maps  -- ... with a less general type
--   </pre>
individually :: (Monad m, Functor g) => Setter (FreeT f m x) (FreeT g m x) (f (FreeT f m x)) (g (FreeT f m x))

-- | Join a <a>FreeT</a>-delimited stream of <a>Producer</a>s into a single
--   <a>Producer</a>
concats :: Monad m => FreeT (Producer a m) m x -> Producer a m x

-- | Join a <a>FreeT</a>-delimited stream of <a>Producer</a>s into a single
--   <a>Producer</a> by intercalating a <a>Producer</a> in between them
intercalates :: Monad m => Producer a m () -> FreeT (Producer a m) m x -> Producer a m x

-- | Fold each <a>Producer</a> of a <a>FreeT</a>
--   
--   <pre>
--   purely folds
--       :: Monad m =&gt; Fold a b -&gt; FreeT (Producer a m) m r -&gt; Producer b m r
--   </pre>
folds :: Monad m => (x -> a -> x) -> x -> (x -> b) -> FreeT (Producer a m) m r -> Producer b m r

-- | Fold each <a>Producer</a> of a <a>FreeT</a>, monadically
--   
--   <pre>
--   impurely foldsM
--       :: Monad m =&gt; FoldM a b -&gt; FreeT (Producer a m) m r -&gt; Producer b m r
--   </pre>
foldsM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> FreeT (Producer a m) m r -> Producer b m r


-- | <tt>pipes-group</tt> builds upon <tt>pipes</tt> to establish idioms
--   for grouping streams into sub-streams without collecting elements into
--   memory. This tutorial assumes familiarity with <tt>pipes</tt> and
--   <tt>pipes-parse</tt>.
module Pipes.Group.Tutorial
