-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Lightweight package providing commonly useful parser combinators
--
-- Lightweight package providing commonly useful parser combinators.
@package parser-combinators
@version 0.1.0
-- | The module provides parser combinators defined for instances of
-- Applicative and Alternative. It also re-exports
-- functions that are commonly used in parsing from
-- Control.Applicative with additional parsing-related comments
-- added.
--
-- A note on backtracking
--
-- Certain parsing libraries, such as Megaparsec, do not backtrack every
-- branch of parsing automatically for the sake of performance and better
-- error messages. They typically backtrack only “atomic” parsers, e.g.
-- those that match a token or several tokens in a row. To backtrack an
-- arbitrary complex parser/branch, a special combinator should be used,
-- typically called try. Combinators in this module are defined
-- in terms Applicative and Alternative operations. Being
-- quite abstract, they cannot know anything about inner workings of any
-- concrete parsing library, and so they cannot use try.
--
-- An essential feature of the Alternative type class is the
-- (<|>) operator that allows to express choice. In
-- libraries that do not backtrack everything automatically, the choice
-- operator and everything that is build on top of it require the parser
-- of the left hand side to backtrack in order for the other alternative
-- branch of paring to be tried. Thus it is the responsibility of the
-- programmer to wrap more complex, composite parsers in try to
-- achieve correct behavior.
module Control.Applicative.Combinators
-- | An associative binary operation
(<|>) :: Alternative f => forall a. f a -> f a -> f a
-- | Zero or more.
many :: Alternative f => forall a. f a -> f [a]
-- | One or more.
some :: Alternative f => forall a. f a -> f [a]
-- | One or none.
optional :: Alternative f => f a -> f (Maybe a)
-- | between open close p parses open, followed by
-- p and close. Returns the value returned by
-- p.
--
--
-- braces = between (symbol "{") (symbol "}")
--
between :: Applicative m => m open -> m close -> m a -> m a
-- | choice ps tries to apply the parsers in the list
-- ps in order, until one of them succeeds. Returns the value of
-- the succeeding parser.
choice :: (Foldable f, Alternative m) => f (m a) -> m a
-- | count n p parses n occurrences of p.
-- If n is smaller or equal to zero, the parser equals to
-- pure []. Returns a list of n values.
--
-- See also: count'.
count :: Applicative m => Int -> m a -> m [a]
-- | count' m n p parses from m to n
-- occurrences of p. If n is not positive or m >
-- n, the parser equals to pure []. Returns a list
-- of parsed values.
--
-- Please note that m may be negative, in this case
-- effect is the same as if it were equal to zero.
--
-- See also: count.
count' :: Alternative m => Int -> Int -> m a -> m [a]
-- | Combine two alternatives.
eitherP :: Alternative m => m a -> m b -> m (Either a b)
-- | endBy p sep parses zero or more occurrences of
-- p, separated and ended by sep. Returns a list of
-- values returned by p.
--
--
-- cStatements = cStatement `endBy` semicolon
--
endBy :: Alternative m => m a -> m sep -> m [a]
-- | endBy1 p sep parses one or more occurrences of
-- p, separated and ended by sep. Returns a list of
-- values returned by p.
endBy1 :: Alternative m => m a -> m sep -> m [a]
-- | manyTill p end applies parser p zero
-- or more times until parser end succeeds. Returns the list of
-- values returned by p.
--
-- See also: skipMany, skipManyTill.
manyTill :: Alternative m => m a -> m end -> m [a]
-- | someTill p end works similarly to manyTill
-- p end, but p should succeed at least once.
--
-- See also: skipSome, skipSomeTill.
someTill :: Alternative m => m a -> m end -> m [a]
-- | option x p tries to apply the parser p. If
-- p fails without consuming input, it returns the value
-- x, otherwise the value returned by p.
--
--
-- priority = option 0 (digitToInt <$> digitChar)
--
--
-- See also: optional.
option :: Alternative m => a -> m a -> m a
-- | sepBy p sep parses zero or more occurrences of
-- p, separated by sep. Returns a list of values
-- returned by p.
--
--
-- commaSep p = p `sepBy` comma
--
sepBy :: Alternative m => m a -> m sep -> m [a]
-- | sepBy1 p sep parses one or more occurrences of
-- p, separated by sep. Returns a list of values
-- returned by p.
sepBy1 :: Alternative m => m a -> m sep -> m [a]
-- | sepEndBy p sep parses zero or more occurrences
-- of p, separated and optionally ended by sep. Returns
-- a list of values returned by p.
sepEndBy :: Alternative m => m a -> m sep -> m [a]
-- | sepEndBy1 p sep parses one or more occurrences
-- of p, separated and optionally ended by sep. Returns
-- a list of values returned by p.
sepEndBy1 :: Alternative m => m a -> m sep -> m [a]
-- | skipMany p applies the parser p zero
-- or more times, skipping its result.
--
-- See also: manyTill, skipManyTill.
skipMany :: Alternative m => m a -> m ()
-- | skipSome p applies the parser p one or
-- more times, skipping its result.
--
-- See also: someTill, skipSomeTill.
skipSome :: Alternative m => m a -> m ()
-- | skipManyTill p end applies the parser p
-- zero or more times skipping results until parser end
-- succeeds. Result parsed by end is then returned.
--
-- See also: manyTill, skipMany.
skipManyTill :: Alternative m => m a -> m end -> m end
-- | skipSomeTill p end applies the parser p
-- one or more times skipping results until parser end
-- succeeds. Result parsed by end is then returned.
--
-- See also: someTill, skipSome.
skipSomeTill :: Alternative m => m a -> m end -> m end