libghc-pipes-parse-doc 3.0.1-1 / usr / share / doc / libghc-pipes-parse-doc / html / pipes-parse.txt

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


-- | Parsing infrastructure for the pipes ecosystem
--   
--   <tt>pipes-parse</tt> builds upon the <tt>pipes</tt> library to provide
--   shared parsing idioms and utilities:
--   
--   <ul>
--   <li><i>Leftovers</i>: Save unused input for later consumption</li>
--   <li><i>Leftover propagation</i>: Leftovers are propagated backwards
--   perfectly</li>
--   <li><i>Connect and Resume</i>: Use <tt>StateT</tt> to save unused
--   input for later</li>
--   <li><i>Termination Safety</i>: Detect and recover from end of
--   input</li>
--   </ul>
--   
--   <tt>Pipes.Parse</tt> contains the full documentation for this library.
--   
--   Read <tt>Pipes.Parse.Tutorial</tt> for an extensive tutorial.
@package pipes-parse
@version 3.0.1


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

-- | A <a>Parser</a> is an action that reads from and writes to a stored
--   <a>Producer</a>
type Parser a m r = forall x. StateT (Producer a m x) m r

-- | Draw one element from the underlying <a>Producer</a>, returning
--   <a>Nothing</a> if the <a>Producer</a> is empty
draw :: Monad m => Parser a m (Maybe a)

-- | Skip one element from the underlying <a>Producer</a>, returning
--   <a>True</a> if successful or <a>False</a> if the <a>Producer</a> is
--   empty
--   
--   <pre>
--   skip = fmap isJust draw
--   </pre>
skip :: Monad m => Parser a m Bool

-- | Draw all elements from the underlying <a>Producer</a>
--   
--   Note that <a>drawAll</a> is not an idiomatic use of
--   <tt>pipes-parse</tt>, but I provide it for simple testing purposes.
--   Idiomatic <tt>pipes-parse</tt> style consumes the elements immediately
--   as they are generated instead of loading all elements into memory. For
--   example, you can use <a>foldAll</a> or <a>foldAllM</a> for this
--   purpose.
drawAll :: Monad m => Parser a m [a]

-- | Drain all elements from the underlying <a>Producer</a>
skipAll :: Monad m => Parser a m ()

-- | Push back an element onto the underlying <a>Producer</a>
unDraw :: Monad m => a -> Parser a m ()

-- | <a>peek</a> checks the first element of the stream, but uses
--   <a>unDraw</a> to push the element back so that it is available for the
--   next <a>draw</a> command.
--   
--   <pre>
--   peek = do
--       x &lt;- draw
--       case x of
--           Nothing -&gt; return ()
--           Just a  -&gt; unDraw a
--       return x
--   </pre>
peek :: Monad m => Parser a m (Maybe a)

-- | Check if the underlying <a>Producer</a> is empty
--   
--   <pre>
--   isEndOfInput = fmap isNothing peek
--   </pre>
isEndOfInput :: Monad m => Parser a m Bool

-- | Fold all input values
--   
--   <pre>
--   Control.Foldl.purely foldAll :: Monad m =&gt; Fold a b -&gt; Parser a m b
--   </pre>
foldAll :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Parser a m b

-- | Fold all input values monadically
--   
--   <pre>
--   Control.Foldl.impurely foldAllM :: Monad m =&gt; FoldM a m b -&gt; Parser a m b
--   </pre>
foldAllM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Parser a m b

-- | <a>span</a> is an improper lens that splits the <a>Producer</a> into
--   two <a>Producer</a>s, where the outer <a>Producer</a> is the longest
--   consecutive group of elements that satisfy the predicate
span :: Monad m => (a -> Bool) -> Lens' (Producer a m x) (Producer a m (Producer a m x))

-- | <a>splitAt</a> is an improper lens that splits a <a>Producer</a> into
--   two <a>Producer</a>s after a fixed number of elements
splitAt :: Monad m => Int -> Lens' (Producer a m x) (Producer a m (Producer a m x))

-- | <a>groupBy</a> splits a <a>Producer</a> into two <a>Producer</a>s
--   after the first group of elements that are equal according to the
--   equality predicate
groupBy :: Monad m => (a -> a -> Bool) -> Lens' (Producer a m x) (Producer a m (Producer a m x))

-- | Like <a>groupBy</a>, where the equality predicate is (<a>==</a>)
group :: (Monad m, Eq a) => Lens' (Producer a m x) (Producer a m (Producer a m x))

-- | Convert a <a>Consumer</a> to a <a>Parser</a>
--   
--   <a>Nothing</a> signifies end of input
toParser :: Monad m => Consumer (Maybe a) m r -> Parser a m r

-- | Convert a never-ending <a>Consumer</a> to a <a>Parser</a>
toParser_ :: Monad m => Consumer a m X -> Parser a m ()


-- | <tt>pipes-parse</tt> builds upon <tt>pipes</tt> to add several missing
--   features necessary to implement <a>Parser</a>s:
--   
--   <ul>
--   <li>End-of-input detection, so that <a>Parser</a>s can react to an
--   exhausted input stream</li>
--   <li>Leftovers support, which simplifies several parsing problems</li>
--   <li>Connect-and-resume, to connect a <a>Producer</a> to a
--   <a>Parser</a> and retrieve unused input</li>
--   </ul>
module Pipes.Parse.Tutorial