-- 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:
--   
--   
--   
- Leftovers: Save unused input for later consumption
--   
- Leftover propagation: Leftovers are propagated backwards
--   perfectly
--   
- Connect and Resume: Use StateT to save unused
--   input for later
--   
- Termination Safety: Detect and recover from end of
--   input
--   
--   
--   Pipes.Parse contains the full documentation for this library.
--   
--   Read Pipes.Parse.Tutorial for an extensive tutorial.
@package pipes-parse
@version 3.0.9

-- | Element-agnostic parsing utilities for pipes
--   
--   See Pipes.Parse.Tutorial for an extended tutorial
module Pipes.Parse

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

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

-- | Skip one element from the underlying Producer, returning
--   True if successful or False if the Producer is
--   empty
--   
--   
--   skip = fmap isJust draw
--   
skip :: forall (m :: Type -> Type) a. Monad m => Parser a m Bool

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

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

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

-- | Check if the underlying Producer is empty
--   
--   
--   isEndOfInput = fmap isNothing peek
--   
isEndOfInput :: forall (m :: Type -> Type) a. Monad m => Parser a m Bool

-- | Fold all input values
--   
--   
--   Control.Foldl.purely foldAll :: Monad m => Fold a b -> Parser a m b
--   
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
--   
--   
--   Control.Foldl.impurely foldAllM :: Monad m => FoldM a m b -> Parser a m b
--   
foldAllM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Parser a m b

-- | span is an improper lens that splits the Producer into
--   two Producers, where the outer Producer 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))

-- | splitAt is an improper lens that splits a Producer into
--   two Producers 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))

-- | groupBy splits a Producer into two Producers
--   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 groupBy, where the equality predicate is (==)
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 Consumer to a Parser
--   
--   Nothing 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 Consumer to a Parser
toParser_ :: forall (m :: Type -> Type) a. Monad m => Consumer a m X -> Parser a m ()

-- | Run a Parser repeatedly on a Producer, yielding
--   each `Right result
--   
--   Returns the remainder of the Producer when the Parser
--   returns Left
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 Parser repeatedly on a Producer, yielding
--   each Just result
--   
--   Returns the remainder of the Producer when the Parser
--   returns Nothing
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 Parser to a Pipe by running it repeatedly on
--   the input

-- | Deprecated: Use parsed instead
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 parseForever for parsers which return a Maybe
--   instead of an Either

-- | Deprecated: Use parsed_ instead
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:
--   
--   
--   
- s - The state.
--   
- m - The inner monad.
--   
--   
--   The return function leaves the state unchanged, while
--   >>= 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.
--   
--   
--   
- 
evalStateT m s = liftM fst
--   (runStateT m s)

--   
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.
--   
--   
--   
- 
execStateT m s = liftM snd
--   (runStateT m s)

--   
execStateT :: Monad m => StateT s m a -> s -> m s

-- | Produce a value
--   
--   
--   yield :: Monad m => a -> Producer a m ()
--   yield :: Monad m => a -> Pipe   x a m ()
--   
yield :: forall (m :: Type -> Type) a x' x. Functor m => a -> Proxy x' x () a m ()

-- | Producers can only yield
type Producer b = Proxy X () () b

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

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