-- 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 1.2.1
-- | 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.
--
-- Due to the nature of the Applicative and Alternative
-- abstractions, they are prone to memory leaks and not as efficient as
-- their monadic counterparts. Although all the combinators we provide in
-- this module are perfectly expressible in terms of Applicative
-- and Alternative, please prefer Control.Monad.Combinators
-- instead when possible.
--
-- If you wish that the combinators that cannot return empty lists return
-- values of the NonEmpty data type, use the
-- Control.Applicative.Combinators.NonEmpty module.
--
-- 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.
--
-- The 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
-- on the left hand side to backtrack in order for the alternative branch
-- of parsing 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 => f a -> f a -> f a
infixl 3 <|>
-- | Zero or more.
many :: Alternative f => f a -> f [a]
-- | One or more.
some :: Alternative f => f a -> f [a]
-- | One or none.
optional :: Alternative f => f a -> f (Maybe a)
-- | The identity of <|>
empty :: Alternative f => f 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 = asum
--
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 parsed values.
--
--
-- count = replicateM
--
--
-- See also: skipCount, 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: skipCount, count.
count' :: Alternative m => Int -> Int -> m a -> m [a]
-- | Combine two alternatives.
--
--
-- eitherP a b = (Left <$> a) <|> (Right <$> b)
--
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. end result is consumed and
-- lost. Use manyTill_ if you wish to keep it.
--
-- See also: skipMany, skipManyTill.
manyTill :: Alternative m => m a -> m end -> m [a]
-- | manyTill_ p end applies parser p zero
-- or more times until parser end succeeds. Returns the list of
-- values returned by p and the end result. Use
-- manyTill if you have no need in the result of the end.
--
-- See also: skipMany, skipManyTill.
manyTill_ :: Alternative m => m a -> m end -> m ([a], end)
-- | someTill p end works similarly to manyTill
-- p end, but p should succeed at least once. end
-- result is consumed and lost. Use someTill_ if you wish to keep
-- it.
--
--
-- someTill p end = liftA2 (:) p (manyTill p end)
--
--
-- See also: skipSome, skipSomeTill.
someTill :: Alternative m => m a -> m end -> m [a]
-- | someTill_ p end works similarly to
-- manyTill_ p end, but p should succeed at
-- least once. Use someTill if you have no need in the result of
-- the end.
--
-- See also: skipSome, skipSomeTill.
someTill_ :: Alternative m => m a -> m end -> m ([a], end)
-- | 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.
--
--
-- option x p = p <|> pure x
--
--
-- 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 ()
-- | skipCount n p parses n occurrences of
-- p, skipping its result. If n is not positive, the
-- parser equals to pure []. Returns a list of n
-- values.
--
--
-- skipCount = replicateM_
--
--
-- See also: count, count'.
skipCount :: Applicative m => Int -> 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
-- | The module provides NonEmpty list variants of some of the
-- functions from Control.Applicative.Combinators.
module Control.Applicative.Combinators.NonEmpty
-- | some p applies the parser p one or
-- more times and returns a list of the values returned by p.
--
--
-- word = some letter
--
some :: Alternative m => m a -> m (NonEmpty a)
-- | endBy1 p sep parses one or more occurrences of
-- p, separated and ended by sep. Returns a non-empty
-- list of values returned by p.
endBy1 :: Alternative m => m a -> m sep -> m (NonEmpty 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 (NonEmpty a)
-- | sepBy1 p sep parses one or more occurrences of
-- p, separated by sep. Returns a non-empty list of
-- values returned by p.
sepBy1 :: Alternative m => m a -> m sep -> m (NonEmpty a)
-- | sepEndBy1 p sep parses one or more occurrences
-- of p, separated and optionally ended by sep. Returns
-- a non-empty list of values returned by p.
sepEndBy1 :: Alternative m => m a -> m sep -> m (NonEmpty a)
-- | This module is a generalization of the package
-- parsec-permutation authored by Samuel Hoffstaetter:
--
-- https://hackage.haskell.org/package/parsec-permutation
--
-- This module also takes inspiration from the algorithm is described in:
-- Parsing Permutation Phrases, by Arthur Baars, Andres Löh and
-- Doaitse Swierstra. Published as a functional pearl at the Haskell
-- Workshop 2001:
--
--
-- https://www.cs.ox.ac.uk/jeremy.gibbons/wg21/meeting56/loeh-paper.pdf
--
-- From these two works we derive a flexible and general method for
-- parsing permutations over an Applicative structure. Quite
-- useful in conjunction with "Free" constructions of
-- Applicatives, Monads, etc.
--
-- Other permutation parsing libraries tend towards using special "almost
-- applicative" combinators for construction which denies the library
-- user the ability to lift and unlift permutation parsing into any
-- Applicative computational context. We redefine these
-- combinators as convenience operators here alongside the equivalent
-- Applicative instance.
--
-- For example, suppose we want to parse a permutation of: an optional
-- string of a's, the character b and an optional
-- c. Using a standard parsing library combinator char,
-- this can be described using the Applicative instance by:
--
--
-- test = runPermutation $
-- (,,) <$> toPermutationWithDefault "" (some (char 'a'))
-- <*> toPermutation (char 'b')
-- <*> toPermutationWithDefault '_' (char 'c')
--
module Control.Applicative.Permutations
-- | An Applicative wrapper-type for constructing permutation
-- parsers.
data Permutation m a
-- | "Unlifts" a permutation parser into a parser to be evaluated.
runPermutation :: (Alternative m, Monad m) => Permutation m a -> m a
-- | "Unlifts" a permutation parser into a parser to be evaluated with an
-- intercalated effect. Useful for separators between permutation
-- elements.
--
-- For example, suppose that similar to above we want to parse a
-- permutation of: an optional string of a's, the character
-- b and an optional c. However, we also want
-- each element of the permutation to be separated by a colon. Using a
-- standard parsing library combinator char, this can be
-- described using the Applicative instance by:
--
--
-- test = intercalateEffect (char ':') $
-- (,,) <$> toPermutationWithDefault "" (some (char 'a'))
-- <*> toPermutation (char 'b')
-- <*> toPermutationWithDefault '_' (char 'c')
--
--
-- This will accept strings such as: "a:b:c", "b:c:a", "b:aa", "b", etc.
--
-- Note that the effect is intercalated between permutation
-- components and that:
--
--
-- - There is never an effect parsed preceeding the first component of
-- the permutation.
-- - There is never an effect parsed following the last component of
-- the permutation.
-- - No effects are intercalated between missing components with a
-- default value.
--
intercalateEffect :: (Alternative m, Monad m) => m b -> Permutation m a -> m a
-- | "Lifts" a parser to a permutation parser.
toPermutation :: Alternative m => m a -> Permutation m a
-- | "Lifts" a parser with a default value to a permutation parser.
--
-- If no permutation containing the supplied parser can be parsed from
-- the input, then the supplied default value is returned in lieu of a
-- parse result.
toPermutationWithDefault :: Alternative m => a -> m a -> Permutation m a
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Applicative.Permutations.Permutation m)
instance GHC.Base.Alternative m => GHC.Base.Applicative (Control.Applicative.Permutations.Permutation m)
-- | The module provides more efficient versions of the combinators from
-- Control.Applicative.Combinators defined in terms of
-- Monad and MonadPlus instead of Applicative and
-- Alternative. When there is no difference in performance we just
-- re-export the combinators from Control.Applicative.Combinators.
module Control.Monad.Combinators
-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a
infixl 3 <|>
-- | One or none.
optional :: Alternative f => f a -> f (Maybe a)
-- | The identity of <|>
empty :: Alternative f => f 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 = asum
--
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
-- return []. Returns a list of n values.
--
-- See also: skipCount, count'.
count :: Monad 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 return []. 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: skipCount, count.
count' :: MonadPlus m => Int -> Int -> m a -> m [a]
-- | Combine two alternatives.
--
--
-- eitherP a b = (Left <$> a) <|> (Right <$> b)
--
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 :: MonadPlus 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 :: MonadPlus m => m a -> m sep -> m [a]
-- | many p applies the parser p zero or
-- more times and returns a list of the values returned by p.
--
--
-- identifier = (:) <$> letter <*> many (alphaNumChar <|> char '_')
--
many :: MonadPlus m => m a -> m [a]
-- | manyTill p end applies parser p zero
-- or more times until parser end succeeds. Returns the list of
-- values returned by p. Note that end result is
-- consumed and lost. Use manyTill_ if you wish to keep it.
--
-- See also: skipMany, skipManyTill.
manyTill :: MonadPlus m => m a -> m end -> m [a]
-- | manyTill_ p end applies parser p zero
-- or more times until parser end succeeds. Returns the list of
-- values returned by p and the end result. Use
-- manyTill if you have no need in the result of the end.
--
-- See also: skipMany, skipManyTill.
manyTill_ :: MonadPlus m => m a -> m end -> m ([a], end)
-- | some p applies the parser p one or
-- more times and returns a list of the values returned by p.
--
--
-- word = some letter
--
some :: MonadPlus m => m a -> m [a]
-- | someTill p end works similarly to manyTill
-- p end, but p should succeed at least once. Note
-- that end result is consumed and lost. Use someTill_ if
-- you wish to keep it.
--
--
-- someTill p end = liftM2 (:) p (manyTill p end)
--
--
-- See also: skipSome, skipSomeTill.
someTill :: MonadPlus m => m a -> m end -> m [a]
-- | someTill_ p end works similarly to
-- manyTill_ p end, but p should succeed at
-- least once. Use someTill if you have no need in the result of
-- the end.
--
-- See also: skipSome, skipSomeTill.
someTill_ :: MonadPlus m => m a -> m end -> m ([a], end)
-- | 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.
--
--
-- option x p = p <|> pure x
--
--
-- 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 :: MonadPlus 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 :: MonadPlus 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 :: MonadPlus 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 :: MonadPlus 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 :: MonadPlus m => m a -> m ()
-- | skipSome p applies the parser p one or
-- more times, skipping its result.
--
-- See also: someTill, skipSomeTill.
skipSome :: MonadPlus m => m a -> m ()
-- | skipCount n p parses n occurrences of
-- p, skipping its result. If n is smaller or equal to
-- zero, the parser equals to return []. Returns a list
-- of n values.
--
-- See also: count, count'.
skipCount :: Monad m => Int -> 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 :: MonadPlus 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 :: MonadPlus m => m a -> m end -> m end
-- | A helper module to parse expressions. It can build a parser given a
-- table of operators.
module Control.Monad.Combinators.Expr
-- | This data type specifies operators that work on values of type
-- a. An operator is either binary infix or unary prefix or
-- postfix. A binary operator has also an associated associativity.
data Operator m a
-- | Non-associative infix
InfixN :: m (a -> a -> a) -> Operator m a
-- | Left-associative infix
InfixL :: m (a -> a -> a) -> Operator m a
-- | Right-associative infix
InfixR :: m (a -> a -> a) -> Operator m a
-- | Prefix
Prefix :: m (a -> a) -> Operator m a
-- | Postfix
Postfix :: m (a -> a) -> Operator m a
-- | Right-associative ternary. Right-associative means that a ? b : d
-- ? e : f parsed as a ? b : (d ? e : f) and not as (a
-- ? b : d) ? e : f.
--
-- The outer monadic action parses the first separator (e.g. ?)
-- and returns an action (of type m (a -> a -> a -> a))
-- that parses the second separator (e.g. :).
--
-- Example usage:
--
--
-- >>> TernR ((If <$ char ':') <$ char '?')
--
TernR :: m (m (a -> a -> a -> a)) -> Operator m a
-- | makeExprParser term table builds an expression parser
-- for terms term with operators from table, taking the
-- associativity and precedence specified in the table into
-- account.
--
-- table is a list of [Operator m a] lists. The list is
-- ordered in descending precedence. All operators in one list have the
-- same precedence (but may have different associativity).
--
-- Prefix and postfix operators of the same precedence associate to the
-- left (i.e. if ++ is postfix increment, than -2++
-- equals -1, not -3).
--
-- Unary operators of the same precedence can only occur once (i.e.
-- --2 is not allowed if - is prefix negate). If you
-- need to parse several prefix or postfix operators in a row, (like C
-- pointers—**i) you can use this approach:
--
--
-- manyUnaryOp = foldr1 (.) <$> some singleUnaryOp
--
--
-- This is not done by default because in some cases allowing repeating
-- prefix or postfix operators is not desirable.
--
-- If you want to have an operator that is a prefix of another operator
-- in the table, use the following (or similar) wrapper (Megaparsec
-- example):
--
--
-- op n = (lexeme . try) (string n <* notFollowedBy punctuationChar)
--
--
-- makeExprParser takes care of all the complexity involved in
-- building an expression parser. Here is an example of an expression
-- parser that handles prefix signs, postfix increment and basic
-- arithmetic:
--
--
-- expr = makeExprParser term table <?> "expression"
--
-- term = parens expr <|> integer <?> "term"
--
-- table = [ [ prefix "-" negate
-- , prefix "+" id ]
-- , [ postfix "++" (+1) ]
-- , [ binary "*" (*)
-- , binary "/" div ]
-- , [ binary "+" (+)
-- , binary "-" (-) ] ]
--
-- binary name f = InfixL (f <$ symbol name)
-- prefix name f = Prefix (f <$ symbol name)
-- postfix name f = Postfix (f <$ symbol name)
--
makeExprParser :: MonadPlus m => m a -> [[Operator m a]] -> m a
-- | The module provides NonEmpty list variants of some of the
-- functions from Control.Monad.Combinators.
module Control.Monad.Combinators.NonEmpty
-- | some p applies the parser p one or
-- more times and returns a list of the values returned by p.
--
--
-- word = some letter
--
some :: MonadPlus m => m a -> m (NonEmpty a)
-- | endBy1 p sep parses one or more occurrences of
-- p, separated and ended by sep. Returns a non-empty
-- list of values returned by p.
endBy1 :: MonadPlus m => m a -> m sep -> m (NonEmpty a)
-- | someTill p end works similarly to manyTill
-- p end, but p should succeed at least once.
--
-- See also: skipSome, skipSomeTill.
someTill :: MonadPlus m => m a -> m end -> m (NonEmpty a)
-- | sepBy1 p sep parses one or more occurrences of
-- p, separated by sep. Returns a non-empty list of
-- values returned by p.
sepBy1 :: MonadPlus m => m a -> m sep -> m (NonEmpty a)
-- | sepEndBy1 p sep parses one or more occurrences
-- of p, separated and optionally ended by sep. Returns
-- a non-empty list of values returned by p.
sepEndBy1 :: MonadPlus m => m a -> m sep -> m (NonEmpty a)