-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Parsing infrastructure for the pipes ecosystem -- -- pipes-parse builds upon the pipes library to provide -- shared parsing idioms and utilities: -- -- -- -- Pipes.Parse contains the full documentation for this library. @package pipes-parse @version 2.0.0 -- | Element-agnostic parsing utilities for pipes -- -- pipes-parse provides two ways to parse and transform streams -- in constant space: -- -- -- -- The top half of this module provides the list-like approach. The key -- idea is that: -- -- 
--   -- '~' means "is analogous to"
--   Producer a m ()            ~   [a]
--   
--   FreeT (Producer a m) m ()  ~  [[a]]
--
-- -- FreeT nests each subsequent Producer within the return -- value of the previous Producer so that you cannot access the -- next Producer until you completely drain the current -- Producer. However, you rarely need to work with FreeT -- directly. Instead, you structure everything using "splitters", -- "transformations" and "joiners": -- -- 
--   -- A "splitter"
--   Producer a m ()           -> FreeT (Producer a m) m ()  ~   [a]  -> [[a]]
--   
--   -- A "transformation"
--   FreeT (Producer a m) m () -> FreeT (Producer a m) m ()  ~  [[a]] -> [[a]]
--   
--   -- A "joiner"
--   FreeT (Producer a m) m () -> Producer a m ()            ~  [[a]] ->  [a]
--
-- -- For example, if you wanted to group standard input by equal lines and -- take the first three groups, you would write: -- -- 
--   import Pipes
--   import qualified Pipes.Parse as Parse
--   import qualified Pipes.Prelude as Prelude
--   
--   threeGroups :: (Monad m, Eq a) => Producer a m () -> Producer a m ()
--   threeGroups = Parse.concat . Parse.takeFree 3 . Parse.groupBy (==)
--   --            ^ Joiner       ^ Transformation   ^ Splitter
--
-- -- This then limits standard input to the first three consecutive groups -- of equal lines: -- -- 
--   >>> runEffect $ threeGroups Prelude.stdinLn >-> Prelude.stdoutLn
--   Group1<Enter>
--   Group1
--   Group1<Enter>
--   Group1
--   Group2<Enter>
--   Group2
--   Group3<Enter>
--   Group3
--   Group3<Enter>
--   Group3
--   Group4<Enter>
--   
--   >>> -- Done, because we began entering our fourth group
--
-- -- The advantage of this style or programming is that you never bring -- more than a single element into memory. This works because -- FreeT sub-divides the Producer without concatenating -- elements together, preserving the laziness of the underlying -- Producer. -- -- The bottom half of this module contains the lower-level monadic -- parsing primitives. These are more useful for pipes -- implementers, particularly for building splitters. I recommend that -- application developers use the list-like style whenever possible. module Pipes.Parse -- | Split a Producer into a FreeT-delimited stream of -- Producers grouped by the supplied equality predicate groupBy :: Monad m => (a -> a -> Bool) -> Producer a m r -> FreeT (Producer a m) m r -- | Split a Producer into a FreeT-delimited stream of -- Producers of the given chunk size chunksOf :: Monad m => Int -> Producer a m r -> FreeT (Producer a m) m r -- | Split a Producer into a FreeT-delimited stream of -- Producers separated by elements that satisfy the given -- predicate splitOn :: Monad m => (a -> Bool) -> Producer a m r -> FreeT (Producer a m) m r -- | (take n) only keeps the first n functor layers of a -- FreeT takeFree :: (Functor f, Monad m) => Int -> FreeT f m () -> FreeT f m () -- | Join a FreeT-delimited stream of Producers into a single -- Producer concat :: Monad m => FreeT (Producer a m) m r -> Producer a m r -- | Join a FreeT-delimited stream of Producers into a single -- Producer by intercalating a Producer in between them intercalate :: Monad m => Producer a m () -> FreeT (Producer a m) m r -> Producer a m r -- | Draw one element from the underlying Producer, returning -- Left if the Producer is empty draw :: Monad m => StateT (Producer a m r) m (Either r a) -- | Push back an element onto the underlying Producer unDraw :: Monad m => a -> StateT (Producer a m r) m () -- | peek checks the first element of the stream, but uses -- unDraw to push the element back so that it is available for the -- next draw command. -- -- 
--   peek = do
--       x <- draw
--       case x of
--           Left  _ -> return ()
--           Right a -> unDraw a
--       return x
--
peek :: Monad m => StateT (Producer a m r) m (Either r a) -- | Check if the underlying Producer is empty -- -- 
--   isEndOfInput = liftM isLeft peek
--
isEndOfInput :: Monad m => StateT (Producer a m r) m Bool -- | Stream from the underlying Producer -- -- input terminates if the Producer is empty, returning the -- final return value of the Producer. input :: Monad m => Producer' a (StateT (Producer a m r) m) r -- | A variation on takeWhile from Pipes.Prelude that -- unDraws the first element that does not match takeWhile :: Monad m => (a -> Bool) -> Pipe a a (StateT (Producer a m r) m) ()