-- 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.12


-- | Element-agnostic grouping utilities for <tt>pipes</tt>
--   
--   See <a>Pipes.Group.Tutorial</a> for an extended tutorial
--   
--   Some type signatures below refer to the aliases below, which are not
--   used in this library, but are included to simplify the documentation.
--   
--   <pre>
--   type Groups         a m x = <a>FreeT</a> (<a>Producer</a> a m) m x
--   type Splitter       a m x = <a>Producer</a> a m x -&gt; Groups a m x
--   type Transformation a m x = Groups a m x -&gt; Groups a m x
--   type Joiner         a m x = Groups a m x -&gt; <a>Producer</a> a m x
--   </pre>
module Pipes.Group

-- | Like <a>groupsBy</a>, where the equality predicate is (<a>==</a>)
--   
--   <pre>
--        groups :: Monad m =&gt; Lens' (<a>Producer</a> a m x) (Groups a m x)
--   view groups :: Monad m =&gt; Splitter a m x
--   set  groups :: Monad m =&gt; Groups a m x -&gt; <a>Producer</a> a m x -&gt; <a>Producer</a> a m x
--   over groups :: Monad m =&gt; Transformation a m x -&gt; <a>Producer</a> a m x -&gt; <a>Producer</a> a m x
--   </pre>
--   
--   <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>
groups :: forall (m :: Type -> Type) a' x a. (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>groupsBy</a> splits a <a>Producer</a> into a <a>FreeT</a> of
--   <a>Producer</a>s grouped using the given equality predicate
--   
--   <pre>
--         groupsBy p  :: Monad m =&gt; Lens' (<a>Producer</a> a m x) (Groups a m x)
--   view (groupsBy p) :: Monad m =&gt; Splitter a m x
--   set  (groupsBy p) :: Monad m =&gt; Groups a m x -&gt; <a>Producer</a> a m x -&gt; <a>Producer</a> a m x
--   over (groupsBy p) :: Monad m =&gt; Transformation a m x -&gt; <a>Producer</a> a m x -&gt; <a>Producer</a> a m x
--   </pre>
--   
--   <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>
groupsBy :: forall (m :: Type -> Type) a' x a. 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>
--   
--   <pre>
--         groupsBy' p  :: Monad m =&gt; Lens' (<a>Producer</a> a m x) (Groups a m x)
--   view (groupsBy' p) :: Monad m =&gt; Splitter a m x
--   set  (groupsBy' p) :: Monad m =&gt; Groups a m x -&gt; <a>Producer</a> a m x -&gt; <a>Producer</a> a m x
--   over (groupsBy' p) :: Monad m =&gt; Transformation a m x -&gt; <a>Producer</a> a m x -&gt; <a>Producer</a> a m x
--   </pre>
groupsBy' :: forall (m :: Type -> Type) a' x a. 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>chunksOf</a> is an splits a <a>Producer</a> into a <a>FreeT</a> of
--   <a>Producer</a>s of fixed length
--   
--   <pre>
--         chunksOf n  :: Monad m =&gt; Lens' (<a>Producer</a> a m x) (Groups a m x)
--   view (chunksOf n) :: Monad m =&gt; Splitter a m x
--   set  (chunksOf n) :: Monad m =&gt; Groups a m x -&gt; <a>Producer</a> a m x -&gt; <a>Producer</a> a m x
--   over (chunksOf n) :: Monad m =&gt; Transformation a m x -&gt; <a>Producer</a> a m x -&gt; <a>Producer</a> a m x
--   </pre>
--   
--   <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>
chunksOf :: forall (m :: Type -> Type) a' x a. 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>
--   takes :: Monad m =&gt; Int -&gt; Groups a m () -&gt; Groups a m ()
--   </pre>
--   
--   <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>
takes :: forall (f :: Type -> Type) (m :: Type -> Type). (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>.
--   
--   <pre>
--   takes' :: Monad m =&gt; Int -&gt; Transformation a m x
--   </pre>
takes' :: forall (m :: Type -> Type) a x. 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>
--   drops :: Monad m =&gt; Int -&gt; Transformation a m x
--   </pre>
--   
--   <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 :: forall (m :: Type -> Type) a x. 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 :: forall (m :: Type -> Type) g f x. (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>.
--   (<tt>over <a>individually</a></tt>) is equivalent to <a>maps</a>, but
--   with a less general type.
--   
--   <pre>
--   type Group a m x = <a>Producer</a> a m (Groups a m x)
--   
--   set  individually :: Monad m =&gt; Group a m x -&gt; Transformation a m x
--   over individually :: Monad m =&gt; (Group a m x -&gt; Group a m x) -&gt; Transformation a m x
--   </pre>
individually :: forall (m :: Type -> Type) g f x. (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>
--   
--   <pre>
--   concats :: Monad m =&gt; Joiner a m x
--   </pre>
concats :: forall (m :: Type -> Type) a x. 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
--   
--   <pre>
--   intercalates :: Monad m =&gt; <a>Producer</a> a m () -&gt; Joiner a m x
--   </pre>
intercalates :: forall (m :: Type -> Type) a x. 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>
--   <a>purely</a> folds :: Monad m =&gt; <a>Fold</a> a b -&gt; Groups a m r -&gt; <a>Producer</a> b m r
--   </pre>
folds :: forall (m :: Type -> Type) x a b r. 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>
--   <a>impurely</a> foldsM :: Monad m =&gt; <a>FoldM</a> a b -&gt; Groups a m r -&gt; <a>Producer</a> 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

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

-- | The base functor for a free monad.
data FreeF (f :: Type -> Type) a b
Pure :: a -> FreeF (f :: Type -> Type) a b
Free :: f b -> FreeF (f :: Type -> Type) a b

-- | The "free monad transformer" for a functor <tt>f</tt>
newtype FreeT (f :: Type -> Type) (m :: Type -> Type) a
FreeT :: m (FreeF f a (FreeT f m a)) -> FreeT (f :: Type -> Type) (m :: Type -> Type) a
[runFreeT] :: FreeT (f :: Type -> Type) (m :: Type -> Type) a -> m (FreeF f a (FreeT f m a))

-- | Produce a value
--   
--   <pre>
--   <a>yield</a> :: <a>Monad</a> m =&gt; a -&gt; <a>Producer</a> a m ()
--   <a>yield</a> :: <a>Monad</a> m =&gt; a -&gt; <a>Pipe</a>   x a m ()
--   </pre>
yield :: forall (m :: Type -> Type) a x' x. Functor m => a -> Proxy x' x () a m ()

-- | <a>Producer</a>s can only <a>yield</a>
type Producer b = Proxy X () () b

-- | Consume the first value from a <a>Producer</a>
--   
--   <a>next</a> either fails with a <a>Left</a> if the <a>Producer</a>
--   terminates or succeeds with a <a>Right</a> providing the next value
--   and the remainder of the <a>Producer</a>.
next :: Monad m => Producer a m r -> m (Either r (a, Producer a 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
