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


-- | 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 :: Type -> Type) 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 :: forall (m :: Type -> Type) a. 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 :: forall (m :: Type -> Type) a. 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 :: forall (m :: Type -> Type) a. Monad m => Parser a m [a]

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

-- | Push back an element onto the underlying <a>Producer</a>
unDraw :: forall (m :: Type -> Type) a. 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 :: forall (m :: Type -> Type) a. Monad m => Parser a m (Maybe a)

-- | Check if the underlying <a>Producer</a> is empty
--   
--   <pre>
--   isEndOfInput = fmap isNothing peek
--   </pre>
isEndOfInput :: forall (m :: Type -> Type) a. 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 :: forall (m :: Type -> Type) x a b. 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 :: forall (m :: Type -> Type) a x. 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 :: forall (m :: Type -> Type) a x. 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 :: forall (m :: Type -> Type) a x. 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 :: forall (m :: Type -> Type) a x. (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 :: forall (m :: Type -> Type) a r. Monad m => Consumer (Maybe a) m r -> Parser a m r

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

-- | Run a <a>Parser</a> repeatedly on a <a>Producer</a>, <a>yield</a>ing
--   each `Right result
--   
--   Returns the remainder of the <a>Producer</a> when the <a>Parser</a>
--   returns <a>Left</a>
parsed :: forall (m :: Type -> Type) a e b r. Monad m => Parser a m (Either e b) -> Producer a m r -> Producer b m (e, Producer a m r)

-- | Run a <a>Parser</a> repeatedly on a <a>Producer</a>, <a>yield</a>ing
--   each <a>Just</a> result
--   
--   Returns the remainder of the <a>Producer</a> when the <a>Parser</a>
--   returns <a>Nothing</a>
parsed_ :: forall (m :: Type -> Type) a b r. Monad m => Parser a m (Maybe b) -> Producer a m r -> Producer b m (Producer a m r)

-- | Convert a <a>Parser</a> to a <a>Pipe</a> by running it repeatedly on
--   the input

-- | <i>Deprecated: Use <a>parsed</a> instead</i>
parseForever :: forall (m :: Type -> Type) a r b. Monad m => (forall (n :: Type -> Type). Monad n => Parser a n (Either r b)) -> Pipe a b m r

-- | Variant of <a>parseForever</a> for parsers which return a Maybe
--   instead of an Either

-- | <i>Deprecated: Use <a>parsed_</a> instead</i>
parseForever_ :: forall (m :: Type -> Type) a b. Monad m => (forall (n :: Type -> Type). Monad n => Parser a n (Maybe b)) -> Pipe a b m ()

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

-- | A state transformer monad parameterized by:
--   
--   <ul>
--   <li><tt>s</tt> - The state.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
newtype StateT s (m :: Type -> Type) a
StateT :: (s -> m (a, s)) -> StateT s (m :: Type -> Type) a
[runStateT] :: StateT s (m :: Type -> Type) a -> s -> m (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalStateT</a> m s = <a>liftM</a> <a>fst</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
evalStateT :: Monad m => StateT s m a -> s -> m a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execStateT</a> m s = <a>liftM</a> <a>snd</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
execStateT :: Monad m => StateT s m a -> s -> m s

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