-- 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.2.0 -- | 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 Loh and -- Doaitse Swierstra. Published as a functional pearl at the Haskell -- Workshop 2001. -- -- 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')
--
-- -- Equivalently, this can also be describe using the convenience -- operators reminiscent of other parsing libraries: -- -- 
--   test = runPermutation $
--            (,,) <$?> ("", some (char 'a'))
--                 <||> char 'b'
--                 <|?> ('_', 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 ':') $
--            (,,) <$?> ("", some (char 'a'))
--                 <||> char 'b'
--                 <|?> ('_', 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: -- -- 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 -- | The expression f <$$> p creates a fresh permutation -- parser consisting of parser p. The the final result of the -- permutation parser is the function f applied to the return -- value of p. The parser p is not allowed to accept -- empty input—use the optional combinator (<$?>) instead. -- -- If the function f takes more than one parameter, the type -- variable b is instantiated to a functional type which -- combines nicely with the adds parser p to the -- (<||>) combinator. This results in stylized code where a -- permutation parser starts with a combining function f -- followed by the parsers. The function f gets its parameters -- in the order in which the parsers are specified, but actual input can -- be in any order. (<$$>) :: Alternative m => (a -> b) -> m a -> Permutation m b infixl 2 <$$> -- | The expression f <$?> (x, p) creates a fresh -- permutation parser consisting of parser p. The final result -- of the permutation parser is the function f applied to the -- return value of p. The parser p is optional—if it -- cannot be applied, the default value x will be used instead. (<$?>) :: Alternative m => (a -> b) -> (a, m a) -> Permutation m b infixl 2 <$?> -- | The expression perm <||> p adds parser p to -- the permutation parser perm. The parser p is not -- allowed to accept empty input—use the optional combinator -- (<|?>) instead. Returns a new permutation parser that -- includes p. (<||>) :: Alternative m => Permutation m (a -> b) -> m a -> Permutation m b infixl 1 <||> -- | The expression perm <||> (x, p) adds parser p -- to the permutation parser perm. The parser p is -- optional—if it cannot be applied, the default value x will be -- used instead. Returns a new permutation parser that includes the -- optional parser p. (<|?>) :: Alternative m => Permutation m (a -> b) -> (a, m a) -> Permutation m b infixl 1 <|?> 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 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 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 => 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 -- | This module provides NonEmpty list variants of some of the -- functions in Control.Applicative.Combinators. module Control.Applicative.Combinators.NonEmpty -- | some p applies the parser p one or -- more times and returns a list of the returned values of 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)