{- |
Module      :  Text.ParserCombinators.Parsec.Combinator
Copyright   :  (c) Daan Leijen 1999-2001
License     :  BSD-style (see the file LICENSE)

Maintainer  :  Christian Maeder <chr.maeder@web.de>
Stability   :  provisional
Portability :  portable

Commonly used generic combinators
-}

module Text.ParserCombinators.Parsec.Combinator
  ( between
  , chainl
  , chainl1
  , chainr
  , chainr1
  , choice
  , count
  , endBy
  , endBy1
  , eof
  , many1
  , notFollowedBy
  , option
  , optionMaybe
  , optional
  , sepBy
  , sepBy1
  , sepEndBy
  , sepEndBy1
  , skipMany1
    -- tricky combinators
  , anyToken
  , lookAhead
  , manyTill
  ) where

import Control.Monad
import Text.ParserCombinators.Parsec.Prim


{- | @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 :: [GenParser tok st a] -> GenParser tok st a
choice :: [GenParser tok st a] -> GenParser tok st a
choice = (GenParser tok st a -> GenParser tok st a -> GenParser tok st a)
-> GenParser tok st a -> [GenParser tok st a] -> GenParser tok st a
forall (t :: * -> *) a b.
Foldable t =>
(a -> b -> b) -> b -> t a -> b
foldr GenParser tok st a -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
(<|>) GenParser tok st a
forall (m :: * -> *) a. MonadPlus m => m a
mzero

{- | @option x p@ tries to apply parser @p@. If @p@ fails without
consuming input, it returns the value @x@, otherwise the value
returned by @p@.

>  priority  = option 0 (digitToInt <$> digit) -}
option :: a -> GenParser tok st a -> GenParser tok st a
option :: a -> GenParser tok st a -> GenParser tok st a
option a
x GenParser tok st a
p = GenParser tok st a
p GenParser tok st a -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> a -> GenParser tok st a
forall (m :: * -> *) a. Monad m => a -> m a
return a
x

{- | @optionMaybe p@ tries to apply parser @p@.  If @p@ fails without
consuming input, it return 'Nothing', otherwise it returns
'Just' the value returned by @p@. -}
optionMaybe :: GenParser tok st a -> GenParser tok st (Maybe a)
optionMaybe :: GenParser tok st a -> GenParser tok st (Maybe a)
optionMaybe GenParser tok st a
p = Maybe a -> GenParser tok st (Maybe a) -> GenParser tok st (Maybe a)
forall a tok st. a -> GenParser tok st a -> GenParser tok st a
option Maybe a
forall a. Maybe a
Nothing ((a -> Maybe a) -> GenParser tok st a -> GenParser tok st (Maybe a)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap a -> Maybe a
forall a. a -> Maybe a
Just GenParser tok st a
p)

{- | @optional p@ tries to apply parser @p@.  It will parse @p@ or nothing.
It only fails if @p@ fails after consuming input. It discards the result
of @p@. -}
optional :: GenParser tok st a -> GenParser tok st ()
optional :: GenParser tok st a -> GenParser tok st ()
optional GenParser tok st a
p = () () -> GenParser tok st a -> GenParser tok st ()
forall (f :: * -> *) a b. Functor f => a -> f b -> f a
<$ GenParser tok st a
p GenParser tok st () -> GenParser tok st () -> GenParser tok st ()
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> () -> GenParser tok st ()
forall (m :: * -> *) a. Monad m => a -> m a
return ()

{- | @between open close p@ parses @open@, followed by @p@ and @close@.
Returns the value returned by @p@.

>  braces  = between (symbol "{") (symbol "}") -}
between :: GenParser tok st open -> GenParser tok st close
            -> GenParser tok st a -> GenParser tok st a
between :: GenParser tok st open
-> GenParser tok st close
-> GenParser tok st a
-> GenParser tok st a
between GenParser tok st open
open GenParser tok st close
close GenParser tok st a
p = GenParser tok st open
open GenParser tok st open -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a b. Applicative f => f a -> f b -> f b
*> GenParser tok st a
p GenParser tok st a -> GenParser tok st close -> GenParser tok st a
forall (f :: * -> *) a b. Applicative f => f a -> f b -> f a
<* GenParser tok st close
close

{- | @skipMany1 p@ applies the parser @p@ /one/ or more times, skipping
its result. -}
skipMany1 :: GenParser tok st a -> GenParser tok st ()
skipMany1 :: GenParser tok st a -> GenParser tok st ()
skipMany1 GenParser tok st a
p = GenParser tok st a
p GenParser tok st a -> GenParser tok st () -> GenParser tok st ()
forall (f :: * -> *) a b. Applicative f => f a -> f b -> f b
*> GenParser tok st a -> GenParser tok st ()
forall tok st a. GenParser tok st a -> GenParser tok st ()
skipMany GenParser tok st a
p

{- | @many1 p@ applies the parser @p@ /one/ or more times. Returns a
list of the returned values of @p@.

>  word  = many1 letter -}
many1 :: GenParser tok st a -> GenParser tok st [a]
many1 :: GenParser tok st a -> GenParser tok st [a]
many1 GenParser tok st a
p = do
  a
x <- GenParser tok st a
p
  [a]
xs <- GenParser tok st a -> GenParser tok st [a]
forall (f :: * -> *) a. Alternative f => f a -> f [a]
many GenParser tok st a
p
  [a] -> GenParser tok st [a]
forall (m :: * -> *) a. Monad m => a -> m a
return (a
x a -> [a] -> [a]
forall a. a -> [a] -> [a]
: [a]
xs)

{- | @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` (symbol ",") -}
sepBy :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepBy :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepBy GenParser tok st a
p GenParser tok st sep
sep = GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
forall tok st a sep.
GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepBy1 GenParser tok st a
p GenParser tok st sep
sep GenParser tok st [a]
-> GenParser tok st [a] -> GenParser tok st [a]
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> [a] -> GenParser tok st [a]
forall (m :: * -> *) a. Monad m => a -> m a
return []

{- | @sepBy1 p sep@ parses /one/ or more occurrences of @p@, separated
by @sep@. Returns a list of values returned by @p@. -}
sepBy1 :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepBy1 :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepBy1 GenParser tok st a
p GenParser tok st sep
sep = do
  a
x <- GenParser tok st a
p
  [a]
xs <- GenParser tok st a -> GenParser tok st [a]
forall (f :: * -> *) a. Alternative f => f a -> f [a]
many (GenParser tok st sep
sep GenParser tok st sep -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a b. Applicative f => f a -> f b -> f b
*> GenParser tok st a
p)
  [a] -> GenParser tok st [a]
forall (m :: * -> *) a. Monad m => a -> m a
return (a
x a -> [a] -> [a]
forall a. a -> [a] -> [a]
: [a]
xs)

{- | @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 :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepEndBy1 :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepEndBy1 GenParser tok st a
p GenParser tok st sep
sep = do
  a
x <- GenParser tok st a
p
  do
      [a]
xs <- GenParser tok st sep
sep GenParser tok st sep
-> GenParser tok st [a] -> GenParser tok st [a]
forall (f :: * -> *) a b. Applicative f => f a -> f b -> f b
*> GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
forall tok st a sep.
GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepEndBy GenParser tok st a
p GenParser tok st sep
sep
      [a] -> GenParser tok st [a]
forall (m :: * -> *) a. Monad m => a -> m a
return (a
x a -> [a] -> [a]
forall a. a -> [a] -> [a]
: [a]
xs)
    GenParser tok st [a]
-> GenParser tok st [a] -> GenParser tok st [a]
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> [a] -> GenParser tok st [a]
forall (m :: * -> *) a. Monad m => a -> m a
return [a
x]

{- | @sepEndBy p sep@ parses /zero/ or more occurrences of @p@,
separated and optionally ended by @sep@, ie. haskell style
statements. Returns a list of values returned by @p@.

>  haskellStatements  = haskellStatement `sepEndBy` semi -}
sepEndBy :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepEndBy :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepEndBy GenParser tok st a
p GenParser tok st sep
sep = GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
forall tok st a sep.
GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
sepEndBy1 GenParser tok st a
p GenParser tok st sep
sep GenParser tok st [a]
-> GenParser tok st [a] -> GenParser tok st [a]
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> [a] -> GenParser tok st [a]
forall (m :: * -> *) a. Monad m => a -> m a
return []


{- | @endBy1 p sep@ parses /one/ or more occurrences of @p@, seperated
and ended by @sep@. Returns a list of values returned by @p@. -}
endBy1 :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
endBy1 :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
endBy1 GenParser tok st a
p GenParser tok st sep
sep = GenParser tok st a -> GenParser tok st [a]
forall tok st a. GenParser tok st a -> GenParser tok st [a]
many1 (GenParser tok st a
p GenParser tok st a -> GenParser tok st sep -> GenParser tok st a
forall (f :: * -> *) a b. Applicative f => f a -> f b -> f a
<* GenParser tok st sep
sep)

{- | @endBy p sep@ parses /zero/ or more occurrences of @p@, seperated
and ended by @sep@. Returns a list of values returned by @p@.

>   cStatements  = cStatement `endBy` semi -}
endBy :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
endBy :: GenParser tok st a -> GenParser tok st sep -> GenParser tok st [a]
endBy GenParser tok st a
p GenParser tok st sep
sep = GenParser tok st a -> GenParser tok st [a]
forall (f :: * -> *) a. Alternative f => f a -> f [a]
many (GenParser tok st a
p GenParser tok st a -> GenParser tok st sep -> GenParser tok st a
forall (f :: * -> *) a b. Applicative f => f a -> f b -> f a
<* GenParser tok st sep
sep)

{- | @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 returned by @p@. -}
count :: Int -> GenParser tok st a -> GenParser tok st [a]
count :: Int -> GenParser tok st a -> GenParser tok st [a]
count Int
n GenParser tok st a
p | Int
n Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
<= Int
0 = [a] -> GenParser tok st [a]
forall (m :: * -> *) a. Monad m => a -> m a
return []
                    | Bool
otherwise = Int -> GenParser tok st a -> GenParser tok st [a]
forall (m :: * -> *) a. Applicative m => Int -> m a -> m [a]
replicateM Int
n GenParser tok st a
p


{- | @chainr p op x@ parser /zero/ or more occurrences of @p@,
separated by @op@ Returns a value obtained by a /right/ associative
application of all functions returned by @op@ to the values returned
by @p@. If there are no occurrences of @p@, the value @x@ is
returned. -}
chainr :: GenParser tok st a -> GenParser tok st (a -> a -> a) -> a
  -> GenParser tok st a
chainr :: GenParser tok st a
-> GenParser tok st (a -> a -> a) -> a -> GenParser tok st a
chainr GenParser tok st a
p GenParser tok st (a -> a -> a)
op a
x = GenParser tok st a
-> GenParser tok st (a -> a -> a) -> GenParser tok st a
forall tok st a.
GenParser tok st a
-> GenParser tok st (a -> a -> a) -> GenParser tok st a
chainr1 GenParser tok st a
p GenParser tok st (a -> a -> a)
op GenParser tok st a -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> a -> GenParser tok st a
forall (m :: * -> *) a. Monad m => a -> m a
return a
x

{- | @chainl p op x@ parser /zero/ or more occurrences of @p@,
separated by @op@. Returns a value obtained by a /left/ associative
application of all functions returned by @op@ to the values returned
by @p@. If there are zero occurrences of @p@, the value @x@ is
returned. -}
chainl :: GenParser tok st a -> GenParser tok st (a -> a -> a) -> a
  -> GenParser tok st a
chainl :: GenParser tok st a
-> GenParser tok st (a -> a -> a) -> a -> GenParser tok st a
chainl GenParser tok st a
p GenParser tok st (a -> a -> a)
op a
x = GenParser tok st a
-> GenParser tok st (a -> a -> a) -> GenParser tok st a
forall tok st a.
GenParser tok st a
-> GenParser tok st (a -> a -> a) -> GenParser tok st a
chainl1 GenParser tok st a
p GenParser tok st (a -> a -> a)
op GenParser tok st a -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> a -> GenParser tok st a
forall (m :: * -> *) a. Monad m => a -> m a
return a
x

{- | @chainl1 p op x@ parser /one/ or more occurrences of @p@,
separated by @op@ Returns a value obtained by a /left/ associative
application of all functions returned by @op@ to the values returned
by @p@. This parser can for example be used to eliminate left
recursion which typically occurs in expression grammars.

>  expr    = term   `chainl1` addop
>  term    = factor `chainl1` mulop
>  factor  = parens expr <|> integer
>
>  mulop   =   symbol "*" *> return (*)
>          <|> symbol "/" *> return (div)
>
>  addop   =   symbol "+" *> return (+)
>          <|> symbol "-" *> return (-) -}
chainl1 :: GenParser tok st a -> GenParser tok st (a -> a -> a)
  -> GenParser tok st a
chainl1 :: GenParser tok st a
-> GenParser tok st (a -> a -> a) -> GenParser tok st a
chainl1 GenParser tok st a
p GenParser tok st (a -> a -> a)
op = do
  a
x <- GenParser tok st a
p
  a -> GenParser tok st a
rest a
x
    where
      rest :: a -> GenParser tok st a
rest a
x = do
          a -> a -> a
f <- GenParser tok st (a -> a -> a)
op
          a
y <- GenParser tok st a
p
          a -> GenParser tok st a
rest (a -> a -> a
f a
x a
y)
        GenParser tok st a -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> a -> GenParser tok st a
forall (m :: * -> *) a. Monad m => a -> m a
return a
x

{- | @chainr1 p op x@ parser /one/ or more occurrences of |p|,
separated by @op@ Returns a value obtained by a /right/ associative
application of all functions returned by @op@ to the values returned
by @p@. -}
chainr1 :: GenParser tok st a -> GenParser tok st (a -> a -> a)
  -> GenParser tok st a
chainr1 :: GenParser tok st a
-> GenParser tok st (a -> a -> a) -> GenParser tok st a
chainr1 GenParser tok st a
p GenParser tok st (a -> a -> a)
op = GenParser tok st a
scan
                    where
                      scan :: GenParser tok st a
scan = do
                        a
x <- GenParser tok st a
p
                        a -> GenParser tok st a
rest a
x

                      rest :: a -> GenParser tok st a
rest a
x = do
                          a -> a -> a
f <- GenParser tok st (a -> a -> a)
op
                          a -> a -> a
f a
x (a -> a) -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> GenParser tok st a
scan
                        GenParser tok st a -> GenParser tok st a -> GenParser tok st a
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> a -> GenParser tok st a
forall (m :: * -> *) a. Monad m => a -> m a
return a
x

{- ---------------------------------------------------------
Tricky combinators
--------------------------------------------------------- -}

{- | The parser @anyToken@ accepts any kind of token. It is for example
used to implement 'eof'. Returns the accepted token. -}
anyToken :: Show tok => GenParser tok st tok
anyToken :: GenParser tok st tok
anyToken = (tok -> String)
-> (SourcePos -> tok -> [tok] -> SourcePos)
-> (tok -> Maybe tok)
-> GenParser tok st tok
forall tok a st.
(tok -> String)
-> (SourcePos -> tok -> [tok] -> SourcePos)
-> (tok -> Maybe a)
-> GenParser tok st a
tokenPrim tok -> String
forall a. Show a => a -> String
show (\ SourcePos
pos tok
_tok [tok]
_toks -> SourcePos
pos) tok -> Maybe tok
forall a. a -> Maybe a
Just

{- | This parser only succeeds at the end of the input. This is not a
primitive parser but it is defined using 'notFollowedBy'.

>  eof  = notFollowedBy anyToken <?> "end of input" -}
eof :: Show tok => GenParser tok st ()
eof :: GenParser tok st ()
eof = GenParser tok st tok -> GenParser tok st ()
forall a tok st.
Show a =>
GenParser tok st a -> GenParser tok st ()
notFollowedBy GenParser tok st tok
forall tok st. Show tok => GenParser tok st tok
anyToken GenParser tok st () -> String -> GenParser tok st ()
forall tok st a. GenParser tok st a -> String -> GenParser tok st a
<?> String
"end of input"

{- | @notFollowedBy p@ only succeeds when parser @p@ fails. This parser
does not consume any input. This parser can be used to implement the
\'longest match\' rule. For example, when recognizing keywords (for
example @let@), we want to make sure that a keyword is not followed
by a legal identifier character, in which case the keyword is
actually an identifier (for example @lets@). We can program this
behaviour as follows:

>  keywordLet  = try (string "let" <* notFollowedBy alphaNum) -}
notFollowedBy :: Show a => GenParser tok st a -> GenParser tok st ()
notFollowedBy :: GenParser tok st a -> GenParser tok st ()
notFollowedBy GenParser tok st a
p = GenParser tok st () -> GenParser tok st ()
forall tok st a. GenParser tok st a -> GenParser tok st a
try (GenParser tok st () -> GenParser tok st ())
-> GenParser tok st () -> GenParser tok st ()
forall a b. (a -> b) -> a -> b
$ do
    a
c <- GenParser tok st a
p
    String -> GenParser tok st ()
forall tok st a. String -> GenParser tok st a
unexpected (a -> String
forall a. Show a => a -> String
show a
c)
  GenParser tok st () -> GenParser tok st () -> GenParser tok st ()
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> () -> GenParser tok st ()
forall (m :: * -> *) a. Monad m => a -> m a
return ()

{- | @manyTill p end@ applies parser @p@ /zero/ or more times until
parser @end@ succeeds. Returns the list of values returned by @p@.
This parser can be used to scan comments:

>  simpleComment   = string "<!--" *> manyTill anyChar (try (string "-->"))

Note the overlapping parsers @anyChar@ and @string \"-->\"@, and
therefore the use of the 'try' combinator. -}
manyTill :: GenParser tok st a -> GenParser tok st end -> GenParser tok st [a]
manyTill :: GenParser tok st a -> GenParser tok st end -> GenParser tok st [a]
manyTill GenParser tok st a
p GenParser tok st end
end = GenParser tok st [a]
scan where
  scan :: GenParser tok st [a]
scan = [] [a] -> GenParser tok st end -> GenParser tok st [a]
forall (f :: * -> *) a b. Functor f => a -> f b -> f a
<$ GenParser tok st end
end GenParser tok st [a]
-> GenParser tok st [a] -> GenParser tok st [a]
forall (f :: * -> *) a. Alternative f => f a -> f a -> f a
<|> do
    a
x <- GenParser tok st a
p
    [a]
xs <- GenParser tok st [a]
scan
    [a] -> GenParser tok st [a]
forall (m :: * -> *) a. Monad m => a -> m a
return (a
x a -> [a] -> [a]
forall a. a -> [a] -> [a]
: [a]
xs)