-- 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.3.0


-- | The module provides parser combinators defined for instances of
--   <a>Applicative</a> and <a>Alternative</a>. It also re-exports
--   functions that are commonly used in parsing from
--   <a>Control.Applicative</a> with additional parsing-related comments
--   added.
--   
--   Due to the nature of the <a>Applicative</a> and <a>Alternative</a>
--   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 <a>Applicative</a>
--   and <a>Alternative</a>, please prefer <a>Control.Monad.Combinators</a>
--   instead when possible.
--   
--   If you wish that the combinators that cannot return empty lists return
--   values of the <a>NonEmpty</a> data type, use the
--   <a>Control.Applicative.Combinators.NonEmpty</a> module.
--   
--   <h3>A note on backtracking</h3>
--   
--   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 <tt>try</tt>. Combinators in this module are defined
--   in terms <a>Applicative</a> and <a>Alternative</a> operations. Being
--   quite abstract, they cannot know anything about inner workings of any
--   concrete parsing library, and so they cannot use <tt>try</tt>.
--   
--   The essential feature of the <a>Alternative</a> type class is the
--   <tt>(<a>&lt;|&gt;</a>)</tt> 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 <tt>try</tt> 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.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; many (putStr "la")
--   lalalalalalalalala... * goes on forever *
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; many Nothing
--   Just []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take 5 &lt;$&gt; many (Just 1)
--   * hangs forever *
--   </pre>
--   
--   Note that this function can be used with Parsers based on
--   Applicatives. In that case <tt>many parser</tt> will attempt to parse
--   <tt>parser</tt> zero or more times until it fails.
many :: Alternative f => f a -> f [a]

-- | One or more.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; some (putStr "la")
--   lalalalalalalalala... * goes on forever *
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; some Nothing
--   nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take 5 &lt;$&gt; some (Just 1)
--   * hangs forever *
--   </pre>
--   
--   Note that this function can be used with Parsers based on
--   Applicatives. In that case <tt>some parser</tt> will attempt to parse
--   <tt>parser</tt> one or more times until it fails.
some :: Alternative f => f a -> f [a]

-- | One or none.
--   
--   It is useful for modelling any computation that is allowed to fail.
--   
--   <h4><b>Examples</b></h4>
--   
--   Using the <a>Alternative</a> instance of <a>Control.Monad.Except</a>,
--   the following functions:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad.Except
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; canFail = throwError "it failed" :: Except String Int
--   
--   &gt;&gt;&gt; final = return 42                :: Except String Int
--   </pre>
--   
--   Can be combined by allowing the first function to fail:
--   
--   <pre>
--   &gt;&gt;&gt; runExcept $ canFail *&gt; final
--   Left "it failed"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runExcept $ optional canFail *&gt; final
--   Right 42
--   </pre>
optional :: Alternative f => f a -> f (Maybe a)

-- | The identity of <a>&lt;|&gt;</a>
--   
--   <pre>
--   empty &lt;|&gt; a     == a
--   a     &lt;|&gt; empty == a
--   </pre>
empty :: Alternative f => f a

-- | <tt><a>between</a> open close p</tt> parses <tt>open</tt>, followed by
--   <tt>p</tt> and <tt>close</tt>. Returns the value returned by
--   <tt>p</tt>.
--   
--   <pre>
--   braces = between (symbol "{") (symbol "}")
--   </pre>
between :: Applicative m => m open -> m close -> m a -> m a

-- | <tt><a>choice</a> ps</tt> tries to apply the parsers in the list
--   <tt>ps</tt> in order, until one of them succeeds. Returns the value of
--   the succeeding parser.
--   
--   <pre>
--   choice = asum
--   </pre>
choice :: (Foldable f, Alternative m) => f (m a) -> m a

-- | <tt><a>count</a> n p</tt> parses <tt>n</tt> occurrences of <tt>p</tt>.
--   If <tt>n</tt> is smaller or equal to zero, the parser equals to
--   <tt><a>pure</a> []</tt>. Returns a list of <tt>n</tt> parsed values.
--   
--   <pre>
--   count = replicateM
--   </pre>
--   
--   See also: <a>skipCount</a>, <a>count'</a>.
count :: Applicative m => Int -> m a -> m [a]

-- | <tt><a>count'</a> m n p</tt> parses from <tt>m</tt> to <tt>n</tt>
--   occurrences of <tt>p</tt>. If <tt>n</tt> is not positive or <tt>m &gt;
--   n</tt>, the parser equals to <tt><a>pure</a> []</tt>. Returns a list
--   of parsed values.
--   
--   Please note that <tt>m</tt> <i>may</i> be negative, in this case
--   effect is the same as if it were equal to zero.
--   
--   See also: <a>skipCount</a>, <a>count</a>.
count' :: Alternative m => Int -> Int -> m a -> m [a]

-- | Combine two alternatives.
--   
--   <pre>
--   eitherP a b = (Left &lt;$&gt; a) &lt;|&gt; (Right &lt;$&gt; b)
--   </pre>
eitherP :: Alternative m => m a -> m b -> m (Either a b)

-- | <tt><a>endBy</a> p sep</tt> parses <i>zero</i> or more occurrences of
--   <tt>p</tt>, separated and ended by <tt>sep</tt>. Returns a list of
--   values returned by <tt>p</tt>.
--   
--   <pre>
--   cStatements = cStatement `endBy` semicolon
--   </pre>
endBy :: Alternative m => m a -> m sep -> m [a]

-- | <tt><a>endBy1</a> p sep</tt> parses <i>one</i> or more occurrences of
--   <tt>p</tt>, separated and ended by <tt>sep</tt>. Returns a list of
--   values returned by <tt>p</tt>.
endBy1 :: Alternative m => m a -> m sep -> m [a]

-- | <tt><a>manyTill</a> p end</tt> applies parser <tt>p</tt> <i>zero</i>
--   or more times until parser <tt>end</tt> succeeds. Returns the list of
--   values returned by <tt>p</tt>. <tt>end</tt> result is consumed and
--   lost. Use <a>manyTill_</a> if you wish to keep it.
--   
--   See also: <a>skipMany</a>, <a>skipManyTill</a>.
manyTill :: Alternative m => m a -> m end -> m [a]

-- | <tt><a>manyTill_</a> p end</tt> applies parser <tt>p</tt> <i>zero</i>
--   or more times until parser <tt>end</tt> succeeds. Returns the list of
--   values returned by <tt>p</tt> and the <tt>end</tt> result. Use
--   <a>manyTill</a> if you have no need in the result of the <tt>end</tt>.
--   
--   See also: <a>skipMany</a>, <a>skipManyTill</a>.
manyTill_ :: Alternative m => m a -> m end -> m ([a], end)

-- | <tt><a>someTill</a> p end</tt> works similarly to <tt><a>manyTill</a>
--   p end</tt>, but <tt>p</tt> should succeed at least once. <tt>end</tt>
--   result is consumed and lost. Use <a>someTill_</a> if you wish to keep
--   it.
--   
--   <pre>
--   someTill p end = liftA2 (:) p (manyTill p end)
--   </pre>
--   
--   See also: <a>skipSome</a>, <a>skipSomeTill</a>.
someTill :: Alternative m => m a -> m end -> m [a]

-- | <tt><a>someTill_</a> p end</tt> works similarly to
--   <tt><a>manyTill_</a> p end</tt>, but <tt>p</tt> should succeed at
--   least once. Use <a>someTill</a> if you have no need in the result of
--   the <tt>end</tt>.
--   
--   See also: <a>skipSome</a>, <a>skipSomeTill</a>.
someTill_ :: Alternative m => m a -> m end -> m ([a], end)

-- | <tt><a>option</a> x p</tt> tries to apply the parser <tt>p</tt>. If
--   <tt>p</tt> fails without consuming input, it returns the value
--   <tt>x</tt>, otherwise the value returned by <tt>p</tt>.
--   
--   <pre>
--   option x p = p &lt;|&gt; pure x
--   </pre>
--   
--   See also: <a>optional</a>.
option :: Alternative m => a -> m a -> m a

-- | <tt><a>sepBy</a> p sep</tt> parses <i>zero</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of values
--   returned by <tt>p</tt>.
--   
--   <pre>
--   commaSep p = p `sepBy` comma
--   </pre>
sepBy :: Alternative m => m a -> m sep -> m [a]

-- | <tt><a>sepBy1</a> p sep</tt> parses <i>one</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of values
--   returned by <tt>p</tt>.
sepBy1 :: Alternative m => m a -> m sep -> m [a]

-- | <tt><a>sepEndBy</a> p sep</tt> parses <i>zero</i> or more occurrences
--   of <tt>p</tt>, separated and optionally ended by <tt>sep</tt>. Returns
--   a list of values returned by <tt>p</tt>.
sepEndBy :: Alternative m => m a -> m sep -> m [a]

-- | <tt><a>sepEndBy1</a> p sep</tt> parses <i>one</i> or more occurrences
--   of <tt>p</tt>, separated and optionally ended by <tt>sep</tt>. Returns
--   a list of values returned by <tt>p</tt>.
sepEndBy1 :: Alternative m => m a -> m sep -> m [a]

-- | <tt><a>skipMany</a> p</tt> applies the parser <tt>p</tt> <i>zero</i>
--   or more times, skipping its result.
--   
--   See also: <a>manyTill</a>, <a>skipManyTill</a>.
skipMany :: Alternative m => m a -> m ()

-- | <tt><a>skipSome</a> p</tt> applies the parser <tt>p</tt> <i>one</i> or
--   more times, skipping its result.
--   
--   See also: <a>someTill</a>, <a>skipSomeTill</a>.
skipSome :: Alternative m => m a -> m ()

-- | <tt><a>skipCount</a> n p</tt> parses <tt>n</tt> occurrences of
--   <tt>p</tt>, skipping its result. If <tt>n</tt> is not positive, the
--   parser equals to <tt><a>pure</a> ()</tt>.
--   
--   <pre>
--   skipCount = replicateM_
--   </pre>
--   
--   See also: <a>count</a>, <a>count'</a>.
skipCount :: Applicative m => Int -> m a -> m ()

-- | <tt><a>skipManyTill</a> p end</tt> applies the parser <tt>p</tt>
--   <i>zero</i> or more times skipping results until parser <tt>end</tt>
--   succeeds. Result parsed by <tt>end</tt> is then returned.
--   
--   See also: <a>manyTill</a>, <a>skipMany</a>.
skipManyTill :: Alternative m => m a -> m end -> m end

-- | <tt><a>skipSomeTill</a> p end</tt> applies the parser <tt>p</tt>
--   <i>one</i> or more times skipping results until parser <tt>end</tt>
--   succeeds. Result parsed by <tt>end</tt> is then returned.
--   
--   See also: <a>someTill</a>, <a>skipSome</a>.
skipSomeTill :: Alternative m => m a -> m end -> m end


-- | The module provides <a>NonEmpty</a> list variants of some of the
--   functions from <a>Control.Applicative.Combinators</a>.
module Control.Applicative.Combinators.NonEmpty

-- | <tt><a>some</a> p</tt> applies the parser <tt>p</tt> <i>one</i> or
--   more times and returns a list of the values returned by <tt>p</tt>.
--   
--   <pre>
--   word = some letter
--   </pre>
some :: Alternative m => m a -> m (NonEmpty a)

-- | <tt><a>endBy1</a> p sep</tt> parses <i>one</i> or more occurrences of
--   <tt>p</tt>, separated and ended by <tt>sep</tt>. Returns a non-empty
--   list of values returned by <tt>p</tt>.
endBy1 :: Alternative m => m a -> m sep -> m (NonEmpty a)

-- | <tt><a>someTill</a> p end</tt> works similarly to <tt><a>manyTill</a>
--   p end</tt>, but <tt>p</tt> should succeed at least once.
--   
--   See also: <a>skipSome</a>, <a>skipSomeTill</a>.
someTill :: Alternative m => m a -> m end -> m (NonEmpty a)

-- | <tt><a>sepBy1</a> p sep</tt> parses <i>one</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a non-empty list of
--   values returned by <tt>p</tt>.
sepBy1 :: Alternative m => m a -> m sep -> m (NonEmpty a)

-- | <tt><a>sepEndBy1</a> p sep</tt> parses <i>one</i> or more occurrences
--   of <tt>p</tt>, separated and optionally ended by <tt>sep</tt>. Returns
--   a non-empty list of values returned by <tt>p</tt>.
sepEndBy1 :: Alternative m => m a -> m sep -> m (NonEmpty a)


-- | This module is a generalization of the package
--   <tt>parsec-permutation</tt> authored by Samuel Hoffstaetter:
--   
--   <a>https://hackage.haskell.org/package/parsec-permutation</a>
--   
--   This module also takes inspiration from the algorithm is described in:
--   <i>Parsing Permutation Phrases</i>, by Arthur Baars, Andres Löh and
--   Doaitse Swierstra. Published as a functional pearl at the Haskell
--   Workshop 2001:
--   
--   
--   <a>https://www.cs.ox.ac.uk/jeremy.gibbons/wg21/meeting56/loeh-paper.pdf</a>
--   
--   From these two works we derive a flexible and general method for
--   parsing permutations over an <a>Applicative</a> structure. Quite
--   useful in conjunction with "Free" constructions of
--   <a>Applicative</a>s, <a>Monad</a>s, 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
--   <a>Applicative</a> computational context. We redefine these
--   combinators as convenience operators here alongside the equivalent
--   <a>Applicative</a> instance.
--   
--   For example, suppose we want to parse a permutation of: an optional
--   string of <tt>a</tt>'s, the character <tt>b</tt> and an optional
--   <tt>c</tt>. Using a standard parsing library combinator <tt>char</tt>
--   (e.g. <a>ReadP</a>) this can be described using the <a>Applicative</a>
--   instance by:
--   
--   <pre>
--   test = runPermutation $
--            (,,) &lt;$&gt; toPermutationWithDefault ""  (some (char 'a'))
--                 &lt;*&gt; toPermutation (char 'b')
--                 &lt;*&gt; toPermutationWithDefault '_' (char 'c')
--   </pre>
module Control.Applicative.Permutations

-- | An <a>Applicative</a> wrapper-type for constructing permutation
--   parsers.
data Permutation (m :: Type -> Type) a

-- | "Unlifts" a permutation parser into a parser to be evaluated.
runPermutation :: Alternative 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 <tt>a</tt>'s, the character
--   <tt>b</tt> and an optional <tt>c</tt>. <i>However</i>, we also want
--   each element of the permutation to be separated by a colon. Using a
--   standard parsing library combinator <tt>char</tt>, this can be
--   described using the <a>Applicative</a> instance by:
--   
--   <pre>
--   test = intercalateEffect (char ':') $
--            (,,) &lt;$&gt; toPermutationWithDefault "" (some (char 'a'))
--                 &lt;*&gt; toPermutation (char 'b')
--                 &lt;*&gt; toPermutationWithDefault '_' (char 'c')
--   </pre>
--   
--   This will accept strings such as: "a:b:c", "b:c:a", "b:aa", "b", etc.
--   
--   Note that the effect is intercalated <i>between</i> permutation
--   components and that:
--   
--   <ul>
--   <li>There is never an effect parsed preceeding the first component of
--   the permutation.</li>
--   <li>There is never an effect parsed following the last component of
--   the permutation.</li>
--   <li>No effects are intercalated between missing components with a
--   default value.</li>
--   <li>If an effect is encountered after a component, another component
--   must immediately follow the effect.</li>
--   </ul>
intercalateEffect :: Alternative 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.Internal.Base.Functor m => GHC.Internal.Base.Applicative (Control.Applicative.Permutations.Permutation m)
instance GHC.Internal.Base.Functor p => GHC.Internal.Base.Functor (Control.Applicative.Permutations.Branch p)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Functor (Control.Applicative.Permutations.Permutation m)


-- | The module provides more efficient versions of the combinators from
--   <a>Control.Applicative.Combinators</a> defined in terms of
--   <a>Monad</a> and <a>MonadPlus</a> instead of <a>Applicative</a> and
--   <a>Alternative</a>. When there is no difference in performance we just
--   re-export the combinators from <a>Control.Applicative.Combinators</a>.
module Control.Monad.Combinators

-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a
infixl 3 <|>

-- | One or none.
--   
--   It is useful for modelling any computation that is allowed to fail.
--   
--   <h4><b>Examples</b></h4>
--   
--   Using the <a>Alternative</a> instance of <a>Control.Monad.Except</a>,
--   the following functions:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad.Except
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; canFail = throwError "it failed" :: Except String Int
--   
--   &gt;&gt;&gt; final = return 42                :: Except String Int
--   </pre>
--   
--   Can be combined by allowing the first function to fail:
--   
--   <pre>
--   &gt;&gt;&gt; runExcept $ canFail *&gt; final
--   Left "it failed"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runExcept $ optional canFail *&gt; final
--   Right 42
--   </pre>
optional :: Alternative f => f a -> f (Maybe a)

-- | The identity of <a>&lt;|&gt;</a>
--   
--   <pre>
--   empty &lt;|&gt; a     == a
--   a     &lt;|&gt; empty == a
--   </pre>
empty :: Alternative f => f a

-- | <tt><a>between</a> open close p</tt> parses <tt>open</tt>, followed by
--   <tt>p</tt> and <tt>close</tt>. Returns the value returned by
--   <tt>p</tt>.
--   
--   <pre>
--   braces = between (symbol "{") (symbol "}")
--   </pre>
between :: Applicative m => m open -> m close -> m a -> m a

-- | <tt><a>choice</a> ps</tt> tries to apply the parsers in the list
--   <tt>ps</tt> in order, until one of them succeeds. Returns the value of
--   the succeeding parser.
--   
--   <pre>
--   choice = asum
--   </pre>
choice :: (Foldable f, Alternative m) => f (m a) -> m a

-- | <tt><a>count</a> n p</tt> parses <tt>n</tt> occurrences of <tt>p</tt>.
--   If <tt>n</tt> is smaller or equal to zero, the parser equals to
--   <tt><a>return</a> []</tt>. Returns a list of <tt>n</tt> values.
--   
--   See also: <a>skipCount</a>, <a>count'</a>.
count :: Monad m => Int -> m a -> m [a]

-- | <tt><a>count'</a> m n p</tt> parses from <tt>m</tt> to <tt>n</tt>
--   occurrences of <tt>p</tt>. If <tt>n</tt> is not positive or <tt>m &gt;
--   n</tt>, the parser equals to <tt><a>return</a> []</tt>. Returns a list
--   of parsed values.
--   
--   Please note that <tt>m</tt> <i>may</i> be negative, in this case
--   effect is the same as if it were equal to zero.
--   
--   See also: <a>skipCount</a>, <a>count</a>.
count' :: MonadPlus m => Int -> Int -> m a -> m [a]

-- | Combine two alternatives.
--   
--   <pre>
--   eitherP a b = (Left &lt;$&gt; a) &lt;|&gt; (Right &lt;$&gt; b)
--   </pre>
eitherP :: Alternative m => m a -> m b -> m (Either a b)

-- | <tt><a>endBy</a> p sep</tt> parses <i>zero</i> or more occurrences of
--   <tt>p</tt>, separated and ended by <tt>sep</tt>. Returns a list of
--   values returned by <tt>p</tt>.
--   
--   <pre>
--   cStatements = cStatement `endBy` semicolon
--   </pre>
endBy :: MonadPlus m => m a -> m sep -> m [a]

-- | <tt><a>endBy1</a> p sep</tt> parses <i>one</i> or more occurrences of
--   <tt>p</tt>, separated and ended by <tt>sep</tt>. Returns a list of
--   values returned by <tt>p</tt>.
endBy1 :: MonadPlus m => m a -> m sep -> m [a]

-- | <tt><a>many</a> p</tt> applies the parser <tt>p</tt> <i>zero</i> or
--   more times and returns a list of the values returned by <tt>p</tt>.
--   
--   <pre>
--   identifier = (:) &lt;$&gt; letter &lt;*&gt; many (alphaNumChar &lt;|&gt; char '_')
--   </pre>
many :: MonadPlus m => m a -> m [a]

-- | <tt><a>manyTill</a> p end</tt> applies parser <tt>p</tt> <i>zero</i>
--   or more times until parser <tt>end</tt> succeeds. Returns the list of
--   values returned by <tt>p</tt>. <b>Note</b> that <tt>end</tt> result is
--   consumed and lost. Use <a>manyTill_</a> if you wish to keep it.
--   
--   See also: <a>skipMany</a>, <a>skipManyTill</a>.
manyTill :: MonadPlus m => m a -> m end -> m [a]

-- | <tt><a>manyTill_</a> p end</tt> applies parser <tt>p</tt> <i>zero</i>
--   or more times until parser <tt>end</tt> succeeds. Returns the list of
--   values returned by <tt>p</tt> and the <tt>end</tt> result. Use
--   <a>manyTill</a> if you have no need in the result of the <tt>end</tt>.
--   
--   See also: <a>skipMany</a>, <a>skipManyTill</a>.
manyTill_ :: MonadPlus m => m a -> m end -> m ([a], end)

-- | <tt><a>some</a> p</tt> applies the parser <tt>p</tt> <i>one</i> or
--   more times and returns a list of the values returned by <tt>p</tt>.
--   
--   <pre>
--   word = some letter
--   </pre>
some :: MonadPlus m => m a -> m [a]

-- | <tt><a>someTill</a> p end</tt> works similarly to <tt><a>manyTill</a>
--   p end</tt>, but <tt>p</tt> should succeed at least once. <b>Note</b>
--   that <tt>end</tt> result is consumed and lost. Use <a>someTill_</a> if
--   you wish to keep it.
--   
--   <pre>
--   someTill p end = liftM2 (:) p (manyTill p end)
--   </pre>
--   
--   See also: <a>skipSome</a>, <a>skipSomeTill</a>.
someTill :: MonadPlus m => m a -> m end -> m [a]

-- | <tt><a>someTill_</a> p end</tt> works similarly to
--   <tt><a>manyTill_</a> p end</tt>, but <tt>p</tt> should succeed at
--   least once. Use <a>someTill</a> if you have no need in the result of
--   the <tt>end</tt>.
--   
--   See also: <a>skipSome</a>, <a>skipSomeTill</a>.
someTill_ :: MonadPlus m => m a -> m end -> m ([a], end)

-- | <tt><a>option</a> x p</tt> tries to apply the parser <tt>p</tt>. If
--   <tt>p</tt> fails without consuming input, it returns the value
--   <tt>x</tt>, otherwise the value returned by <tt>p</tt>.
--   
--   <pre>
--   option x p = p &lt;|&gt; pure x
--   </pre>
--   
--   See also: <a>optional</a>.
option :: Alternative m => a -> m a -> m a

-- | <tt><a>sepBy</a> p sep</tt> parses <i>zero</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of values
--   returned by <tt>p</tt>.
--   
--   <pre>
--   commaSep p = p `sepBy` comma
--   </pre>
sepBy :: MonadPlus m => m a -> m sep -> m [a]

-- | <tt><a>sepBy1</a> p sep</tt> parses <i>one</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a list of values
--   returned by <tt>p</tt>.
sepBy1 :: MonadPlus m => m a -> m sep -> m [a]

-- | <tt><a>sepEndBy</a> p sep</tt> parses <i>zero</i> or more occurrences
--   of <tt>p</tt>, separated and optionally ended by <tt>sep</tt>. Returns
--   a list of values returned by <tt>p</tt>.
sepEndBy :: MonadPlus m => m a -> m sep -> m [a]

-- | <tt><a>sepEndBy1</a> p sep</tt> parses <i>one</i> or more occurrences
--   of <tt>p</tt>, separated and optionally ended by <tt>sep</tt>. Returns
--   a list of values returned by <tt>p</tt>.
sepEndBy1 :: MonadPlus m => m a -> m sep -> m [a]

-- | <tt><a>skipMany</a> p</tt> applies the parser <tt>p</tt> <i>zero</i>
--   or more times, skipping its result.
--   
--   See also: <a>manyTill</a>, <a>skipManyTill</a>.
skipMany :: MonadPlus m => m a -> m ()

-- | <tt><a>skipSome</a> p</tt> applies the parser <tt>p</tt> <i>one</i> or
--   more times, skipping its result.
--   
--   See also: <a>someTill</a>, <a>skipSomeTill</a>.
skipSome :: MonadPlus m => m a -> m ()

-- | <tt><a>skipCount</a> n p</tt> parses <tt>n</tt> occurrences of
--   <tt>p</tt>, skipping its result. If <tt>n</tt> is smaller or equal to
--   zero, the parser equals to <tt><a>return</a> ()</tt>.
--   
--   See also: <a>count</a>, <a>count'</a>.
skipCount :: Monad m => Int -> m a -> m ()

-- | <tt><a>skipManyTill</a> p end</tt> applies the parser <tt>p</tt>
--   <i>zero</i> or more times skipping results until parser <tt>end</tt>
--   succeeds. Result parsed by <tt>end</tt> is then returned.
--   
--   See also: <a>manyTill</a>, <a>skipMany</a>.
skipManyTill :: MonadPlus m => m a -> m end -> m end

-- | <tt><a>skipSomeTill</a> p end</tt> applies the parser <tt>p</tt>
--   <i>one</i> or more times skipping results until parser <tt>end</tt>
--   succeeds. Result parsed by <tt>end</tt> is then returned.
--   
--   See also: <a>someTill</a>, <a>skipSome</a>.
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
--   <tt>a</tt>. An operator is either binary infix or unary prefix or
--   postfix. A binary operator has also an associated associativity.
data Operator (m :: Type -> Type) a

-- | Non-associative infix
InfixN :: m (a -> a -> a) -> Operator (m :: Type -> Type) a

-- | Left-associative infix
InfixL :: m (a -> a -> a) -> Operator (m :: Type -> Type) a

-- | Right-associative infix
InfixR :: m (a -> a -> a) -> Operator (m :: Type -> Type) a

-- | Prefix
Prefix :: m (a -> a) -> Operator (m :: Type -> Type) a

-- | Postfix
Postfix :: m (a -> a) -> Operator (m :: Type -> Type) a

-- | Right-associative ternary. Right-associative means that <tt>a ? b : d
--   ? e : f</tt> parsed as <tt>a ? b : (d ? e : f)</tt> and not as <tt>(a
--   ? b : d) ? e : f</tt>.
--   
--   The outer monadic action parses the first separator (e.g. <tt>?</tt>)
--   and returns an action (of type <tt>m (a -&gt; a -&gt; a -&gt; a)</tt>)
--   that parses the second separator (e.g. <tt>:</tt>).
--   
--   Example usage:
--   
--   <pre>
--   &gt;&gt;&gt; TernR ((If &lt;$ char ':') &lt;$ char '?')
--   </pre>
TernR :: m (m (a -> a -> a -> a)) -> Operator (m :: Type -> Type) a

-- | <tt><a>makeExprParser</a> term table</tt> builds an expression parser
--   for terms <tt>term</tt> with operators from <tt>table</tt>, taking the
--   associativity and precedence specified in the <tt>table</tt> into
--   account.
--   
--   <tt>table</tt> is a list of <tt>[Operator m a]</tt> 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 <tt>++</tt> is postfix increment, than <tt>-2++</tt>
--   equals <tt>-1</tt>, not <tt>-3</tt>).
--   
--   Unary operators of the same precedence can only occur once (i.e.
--   <tt>--2</tt> is not allowed if <tt>-</tt> is prefix negate). If you
--   need to parse several prefix or postfix operators in a row, (like C
--   pointers—<tt>**i</tt>) you can use this approach:
--   
--   <pre>
--   manyUnaryOp = foldr1 (.) &lt;$&gt; some singleUnaryOp
--   </pre>
--   
--   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):
--   
--   <pre>
--   op n = (lexeme . try) (string n &lt;* notFollowedBy punctuationChar)
--   </pre>
--   
--   <a>makeExprParser</a> 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:
--   
--   <pre>
--   expr = makeExprParser term table &lt;?&gt; "expression"
--   
--   term = parens expr &lt;|&gt; integer &lt;?&gt; "term"
--   
--   table = [ [ prefix  "-"  negate
--             , prefix  "+"  id ]
--           , [ postfix "++" (+1) ]
--           , [ binary  "*"  (*)
--             , binary  "/"  div  ]
--           , [ binary  "+"  (+)
--             , binary  "-"  (-)  ] ]
--   
--   binary  name f = InfixL  (f &lt;$ symbol name)
--   prefix  name f = Prefix  (f &lt;$ symbol name)
--   postfix name f = Postfix (f &lt;$ symbol name)
--   </pre>
makeExprParser :: MonadPlus m => m a -> [[Operator m a]] -> m a


-- | The module provides <a>NonEmpty</a> list variants of some of the
--   functions from <a>Control.Monad.Combinators</a>.
module Control.Monad.Combinators.NonEmpty

-- | <tt><a>some</a> p</tt> applies the parser <tt>p</tt> <i>one</i> or
--   more times and returns a list of the values returned by <tt>p</tt>.
--   
--   <pre>
--   word = some letter
--   </pre>
some :: MonadPlus m => m a -> m (NonEmpty a)

-- | <tt><a>endBy1</a> p sep</tt> parses <i>one</i> or more occurrences of
--   <tt>p</tt>, separated and ended by <tt>sep</tt>. Returns a non-empty
--   list of values returned by <tt>p</tt>.
endBy1 :: MonadPlus m => m a -> m sep -> m (NonEmpty a)

-- | <tt><a>someTill</a> p end</tt> works similarly to <tt><a>manyTill</a>
--   p end</tt>, but <tt>p</tt> should succeed at least once.
--   
--   See also: <a>skipSome</a>, <a>skipSomeTill</a>.
someTill :: MonadPlus m => m a -> m end -> m (NonEmpty a)

-- | <tt><a>sepBy1</a> p sep</tt> parses <i>one</i> or more occurrences of
--   <tt>p</tt>, separated by <tt>sep</tt>. Returns a non-empty list of
--   values returned by <tt>p</tt>.
sepBy1 :: MonadPlus m => m a -> m sep -> m (NonEmpty a)

-- | <tt><a>sepEndBy1</a> p sep</tt> parses <i>one</i> or more occurrences
--   of <tt>p</tt>, separated and optionally ended by <tt>sep</tt>. Returns
--   a non-empty list of values returned by <tt>p</tt>.
sepEndBy1 :: MonadPlus m => m a -> m sep -> m (NonEmpty a)


-- | This module specialized the interface to <a>Monad</a> for potential
--   efficiency considerations, depending on the monad the permutations are
--   run over.
--   
--   For a more general interface requiring only <a>Applicative</a>, and
--   for more complete documentation, see the <a>Permutations</a> module.
module Control.Monad.Permutations

-- | An <a>Applicative</a> wrapper-type for constructing permutation
--   parsers.
data Permutation (m :: Type -> Type) 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.
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.Internal.Base.Alternative m => GHC.Internal.Base.Applicative (Control.Monad.Permutations.Permutation m)
instance GHC.Internal.Base.Functor m => GHC.Internal.Base.Functor (Control.Monad.Permutations.Permutation m)
