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


-- | Parser Effect for the Control.Effects Library
--   
--   Control.Effects.Parser is a parsing effect for the Control.Effects
--   library. Control.Effects is a library for programming with effects,
--   like in the the Eff language by Andrej Bauer and Matija Pretnar.
--   Effects can be used instead of monad transformers.
--   
--   See the home page for some example code.
@package effects-parser
@version 0.1

module Control.Effects.Parser

-- | Generates a Handler to parse input from the given list of items.
parse :: Monad m => [c] -> Handler (Parser c m a) (Maybe a) m a

-- | Tries each action from the given list in turn, stopping with the first
--   one which successfully parses the input. A parse failure in the action
--   or the continuation results in backtracking to the original location
--   in the input, and reverts the state of any more deeply nested effects.
oneOf :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> [n b] -> n b

-- | Returns and consumes the next item from the input. Fails if there is
--   no more input to be consumed.
item :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n c

-- | Returns and consumes the next item from the input, provided it
--   satisfies a predicate. Fails if there is no more input, or if the
--   predicate function evaluates to False.
itemIf :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> (c -> Bool) -> n c

-- | Zero-width positive lookahead assertion. Runs the given action against
--   the current input without consuming it. A parse failure in the action
--   causes the lookahead to fail; otherwise, the result of the action is
--   returned.
lookahead :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n b

-- | Zero-width negative lookahead assertion. Runs the given action against
--   the current input without consuming it. A parse failure in the action
--   causes the lookahead to succeed; otherwise, the lookahead fails.
noMatch :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n ()

-- | Prevents backtracking into the middle of the given action. This can be
--   used to create actions which always consume as much or as little of
--   the input as possible, even if that would cause a later match to fail.
--   Note that backtracking is still possible within the action, or across
--   the entire noBacktrack action.
--   
--   Examples:
--   
--   <pre>
--   noBacktrack p $ oneOf [return (), item p &gt;&gt; return ()]  -- never consumes any input
--   noBacktrack p $ parseMany p $ itemIf p (=='a')          -- always consumes all the 'a's
--   </pre>
noBacktrack :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n b

-- | A parser which always fails.
parseFail :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b

-- | A parser which succeeds only when there is no more input.
parseEnd :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n ()

-- | Try the given parser; returns Just the result on success, or Nothing
--   otherwise.
parseOpt :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n (Maybe b)

-- | Apply the given parser zero or more times, and return a list of the
--   results.
parseMany :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n [b]

-- | Like parseMany, but fails if there isn't at least one match.
parseMany1 :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n [b]

-- | A non-greedy version of parseOpt which prefers to match Nothing.
parseOpt' :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n (Maybe b)

-- | A non-greedy version of parseMany which matches as few times as
--   possible.
parseMany' :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n [b]

-- | A non-greedy version of parseMany1 which matches as few times as
--   possible (but at least once).
parseMany1' :: AutoLift (Parser c m a) m n => Effect (Parser c m a) m -> n b -> n [b]