    {-----------------------------------------------------------------------------

                     A LIBRARY OF MONADIC PARSER COMBINATORS

                                  29th July 1996

                     Graham Hutton               Erik Meijer
                University of Nottingham    University of Utrecht

    This Haskell 1.3 script defines a library of parser combinators, and is taken
    from sections 1-6 of our article "Monadic Parser Combinators".  Some changes
    to the library have been made in the move from Gofer to Haskell:

       * Do notation is used in place of monad comprehension notation;

       * The parser datatype is defined using "newtype", to avoid the overhead
         of tagging and untagging parsers with the P constructor.

    ------------------------------------------------------------------------------
    ** Extended to allow a symbol table/state to be threaded through the monad.
    ** Extended to allow a parameterised token type, rather than just strings.
    ** Extended to allow error-reporting.

    (Extensions: 1998-2000 Malcolm.Wallace@cs.york.ac.uk)
    (More extensions: 2004 gk-haskell@ninebynine.org)

    ------------------------------------------------------------------------------}

    -- | This library of monadic parser combinators is based on the ones
    --   defined by Graham Hutton and Erik Meijer.  It has been extended by
    --   Malcolm Wallace to use an abstract token type (no longer just a
    --   string) as input, and to incorporate state in the monad, useful
    --   for symbol tables, macros, and so on.  Basic facilities for error
    --   reporting have also been added, and later extended by Graham Klyne
    --   to return the errors through an @Either@ type, rather than just
    --   calling @error@.

    module Text.ParserCombinators.HuttonMeijerWallace
      (
      -- * The parser monad
        Parser(..)
      -- * Primitive parser combinators
      , item, eof, papply, papply'
      -- * Derived combinators
      , (+++), {-sat,-} tok, nottok, many, many1
      , sepby, sepby1, chainl, chainl1, chainr, chainr1, ops, bracket
      , toEOF
      -- * Error handling
      , elserror
      -- * State handling
      , stupd, stquery, stget
      -- * Re-parsing
      , reparse
      ) where

    import Data.Char
    import Control.Applicative ( Applicative(pure,(<*>)), Alternative(empty,(<|>)) )
    import Control.Monad
    import qualified Control.Monad.Fail as Fail

    infixr 5 +++

    --- The parser monad ---------------------------------------------------------

    type ParseResult s t e a = Either e [(a,s,[Either e t])]

    newtype Parser s t e a   = P ( s -> [Either e t] -> ParseResult s t e a )
        -- ^ The parser type is parametrised on the types of the state @s@,
        --   the input tokens @t@, error-type @e@, and the result value @a@.
        --   The state and remaining input are threaded through the monad.

    instance Functor (Parser s t e) where
       -- fmap        :: (a -> b) -> (Parser s t e a -> Parser s t e b)
       fmap :: forall a b. (a -> b) -> Parser s t e a -> Parser s t e b
    fmap a -> b
    f (P s -> [Either e t] -> ParseResult s t e a
    p)    = (s -> [Either e t] -> ParseResult s t e b) -> Parser s t e b
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp -> case s -> [Either e t] -> ParseResult s t e a
    p s
    st [Either e t]
    inp of
                            Right [(a, s, [Either e t])]
    res -> [(b, s, [Either e t])] -> ParseResult s t e b
    forall a b. b -> Either a b
    Right [(a -> b
    f a
    v, s
    s, [Either e t]
    out) | (a
    v,s
    s,[Either e t]
    out) <- [(a, s, [Either e t])]
    res]
                            Left e
    err  -> e -> ParseResult s t e b
    forall a b. a -> Either a b
    Left e
    err
                           )

    instance Applicative (Parser s t e) where
       pure :: forall a. a -> Parser s t e a
    pure a
    v = (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp -> [(a, s, [Either e t])] -> ParseResult s t e a
    forall a b. b -> Either a b
    Right [(a
    v,s
    st,[Either e t]
    inp)])
       <*> :: forall a b.
    Parser s t e (a -> b) -> Parser s t e a -> Parser s t e b
    (<*>) = Parser s t e (a -> b) -> Parser s t e a -> Parser s t e b
    forall (m :: * -> *) a b. Monad m => m (a -> b) -> m a -> m b
    ap

    instance Monad (Parser s t e) where
       -- return      :: a -> Parser s t e a
       return :: forall a. a -> Parser s t e a
    return          = a -> Parser s t e a
    forall a. a -> Parser s t e a
    forall (f :: * -> *) a. Applicative f => a -> f a
    pure
       -- >>=         :: Parser s t e a -> (a -> Parser s t e b) -> Parser s t e b
       (P s -> [Either e t] -> ParseResult s t e a
    p) >>= :: forall a b.
    Parser s t e a -> (a -> Parser s t e b) -> Parser s t e b
    >>= a -> Parser s t e b
    f     = (s -> [Either e t] -> ParseResult s t e b) -> Parser s t e b
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp -> case s -> [Either e t] -> ParseResult s t e a
    p s
    st [Either e t]
    inp of
                            Right [(a, s, [Either e t])]
    res -> (ParseResult s t e b -> ParseResult s t e b -> ParseResult s t e b)
    -> ParseResult s t e b
    -> [ParseResult s t e b]
    -> ParseResult s t e b
    forall a b. (a -> b -> b) -> b -> [a] -> b
    forall (t :: * -> *) a b.
    Foldable t =>
    (a -> b -> b) -> b -> t a -> b
    foldr ParseResult s t e b -> ParseResult s t e b -> ParseResult s t e b
    forall s t e a.
    ParseResult s t e a -> ParseResult s t e a -> ParseResult s t e a
    joinresults ([(b, s, [Either e t])] -> ParseResult s t e b
    forall a b. b -> Either a b
    Right [])
                                [ Parser s t e b -> s -> [Either e t] -> ParseResult s t e b
    forall s t e a.
    Parser s t e a
    -> s -> [Either e t] -> Either e [(a, s, [Either e t])]
    papply' (a -> Parser s t e b
    f a
    v) s
    s [Either e t]
    out | (a
    v,s
    s,[Either e t]
    out) <- [(a, s, [Either e t])]
    res ]
                            Left e
    err  -> e -> ParseResult s t e b
    forall a b. a -> Either a b
    Left e
    err
                           )

    #if !MIN_VERSION_base(4,13,0)
       fail            = Fail.fail
    #endif

    instance Fail.MonadFail (Parser s t e) where
       -- fail        :: String -> Parser s t e a
       fail :: forall a. String -> Parser s t e a
    fail String
    err        = (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp -> [(a, s, [Either e t])] -> ParseResult s t e a
    forall a b. b -> Either a b
    Right [])
      -- I know it's counterintuitive, but we want no-parse, not an error.

    instance Alternative (Parser s t e) where
       empty :: forall a. Parser s t e a
    empty = Parser s t e a
    forall a. Parser s t e a
    forall (m :: * -> *) a. MonadPlus m => m a
    mzero
       <|> :: forall a. Parser s t e a -> Parser s t e a -> Parser s t e a
    (<|>) = Parser s t e a -> Parser s t e a -> Parser s t e a
    forall a. Parser s t e a -> Parser s t e a -> Parser s t e a
    forall (m :: * -> *) a. MonadPlus m => m a -> m a -> m a
    mplus

    instance MonadPlus (Parser s t e) where
       -- mzero       :: Parser s t e a
       mzero :: forall a. Parser s t e a
    mzero           = (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp -> [(a, s, [Either e t])] -> ParseResult s t e a
    forall a b. b -> Either a b
    Right [])
       -- mplus       :: Parser s t e a -> Parser s t e a -> Parser s t e a
       (P s -> [Either e t] -> ParseResult s t e a
    p) mplus :: forall a. Parser s t e a -> Parser s t e a -> Parser s t e a
    `mplus` (P s -> [Either e t] -> ParseResult s t e a
    q) = (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp -> ParseResult s t e a -> ParseResult s t e a -> ParseResult s t e a
    forall s t e a.
    ParseResult s t e a -> ParseResult s t e a -> ParseResult s t e a
    joinresults (s -> [Either e t] -> ParseResult s t e a
    p s
    st [Either e t]
    inp) (s -> [Either e t] -> ParseResult s t e a
    q s
    st [Either e t]
    inp))

    -- joinresults ensures that explicitly raised errors are dominant,
    -- provided no parse has yet been found.  The commented out code is
    -- a slightly stricter specification of the real code.
    joinresults :: ParseResult s t e a -> ParseResult s t e a -> ParseResult s t e a
    {-
    joinresults (Left  p)  (Left  q)  = Left  p
    joinresults (Left  p)  (Right _)  = Left  p
    joinresults (Right []) (Left  q)  = Left  q
    joinresults (Right p)  (Left  q)  = Right p
    joinresults (Right p)  (Right q)  = Right (p++q)
    -}
    joinresults :: forall s t e a.
    ParseResult s t e a -> ParseResult s t e a -> ParseResult s t e a
    joinresults (Left  e
    p)  Either e [(a, s, [Either e t])]
    q  = e -> Either e [(a, s, [Either e t])]
    forall a b. a -> Either a b
    Left e
    p
    joinresults (Right []) Either e [(a, s, [Either e t])]
    q  = Either e [(a, s, [Either e t])]
    q
    joinresults (Right [(a, s, [Either e t])]
    p)  Either e [(a, s, [Either e t])]
    q  = [(a, s, [Either e t])] -> Either e [(a, s, [Either e t])]
    forall a b. b -> Either a b
    Right ([(a, s, [Either e t])]
    p[(a, s, [Either e t])]
    -> [(a, s, [Either e t])] -> [(a, s, [Either e t])]
    forall a. [a] -> [a] -> [a]
    ++ case Either e [(a, s, [Either e t])]
    q of Left e
    _  -> []
                                                     Right [(a, s, [Either e t])]
    r -> [(a, s, [Either e t])]
    r)

    --- Primitive parser combinators ---------------------------------------------

    -- | Deliver the first remaining token.
    item              :: Parser s t e t
    item :: forall s t e. Parser s t e t
    item               = (s -> [Either e t] -> ParseResult s t e t) -> Parser s t e t
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp -> case [Either e t]
    inp of
                            []            -> [(t, s, [Either e t])] -> ParseResult s t e t
    forall a b. b -> Either a b
    Right []
                            (Left e
    e: [Either e t]
    _)   -> e -> ParseResult s t e t
    forall a b. a -> Either a b
    Left e
    e
                            (Right t
    x: [Either e t]
    xs) -> [(t, s, [Either e t])] -> ParseResult s t e t
    forall a b. b -> Either a b
    Right [(t
    x,s
    st,[Either e t]
    xs)]
                           )

    -- | Fail if end of input is not reached
    eof               :: Show p => Parser s (p,t) String ()
    eof :: forall p s t. Show p => Parser s (p, t) String ()
    eof                = (s -> [Either String (p, t)] -> ParseResult s (p, t) String ())
    -> Parser s (p, t) String ()
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either String (p, t)]
    inp -> case [Either String (p, t)]
    inp of
                            []         -> [((), s, [Either String (p, t)])] -> ParseResult s (p, t) String ()
    forall a b. b -> Either a b
    Right [((),s
    st,[])]
                            (Left String
    e:[Either String (p, t)]
    _) -> String -> ParseResult s (p, t) String ()
    forall a b. a -> Either a b
    Left String
    e
                            (Right (p
    p,t
    _):[Either String (p, t)]
    _) -> String -> ParseResult s (p, t) String ()
    forall a b. a -> Either a b
    Left (String
    "End of input expected at "
                                                     String -> String -> String
    forall a. [a] -> [a] -> [a]
    ++p -> String
    forall a. Show a => a -> String
    show p
    pString -> String -> String
    forall a. [a] -> [a] -> [a]
    ++String
    "\n  but found text")
                           )

    {-
    -- | Ensure the value delivered by the parser is evaluated to WHNF.
    force             :: Parser s t e a -> Parser s t e a
    force (P p)        = P (\st inp -> let Right xs = p st inp
                                           h = head xs in
                                       h `seq` Right (h: tail xs)
                           )
    --  [[[GK]]]  ^^^^^^
    --  WHNF = Weak Head Normal Form, meaning that it has no top-level redex.
    --  In this case, I think that means that the first element of the list
    --  is fully evaluated.
    --
    --  NOTE:  the original form of this function fails if there is no parse
    --  result for p st inp (head xs fails if xs is null), so the modified
    --  form can assume a Right value only.
    --
    --  Why is this needed?
    --  It's not exported, and the only use of this I see is commented out.
    ---------------------------------------
    -}

    -- | Deliver the first parse result only, eliminating any backtracking.
    first             :: Parser s t e a -> Parser s t e a
    first :: forall s t e a. Parser s t e a -> Parser s t e a
    first (P s -> [Either e t] -> ParseResult s t e a
    p)        = (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp -> case s -> [Either e t] -> ParseResult s t e a
    p s
    st [Either e t]
    inp of
                                       Right ((a, s, [Either e t])
    x:[(a, s, [Either e t])]
    xs) -> [(a, s, [Either e t])] -> ParseResult s t e a
    forall a b. b -> Either a b
    Right [(a, s, [Either e t])
    x]
                                       ParseResult s t e a
    otherwise    -> ParseResult s t e a
    otherwise
                           )

    -- | Apply the parser to some real input, given an initial state value.
    --   If the parser fails, raise 'error' to halt the program.
    --   (This is the original exported behaviour - to allow the caller to
    --   deal with the error differently, see @papply'@.)
    papply            :: Parser s t String a -> s -> [Either String t]
                                                  -> [(a,s,[Either String t])]
    papply :: forall s t a.
    Parser s t String a
    -> s -> [Either String t] -> [(a, s, [Either String t])]
    papply (P s -> [Either String t] -> ParseResult s t String a
    p) s
    st [Either String t]
    inp = (String -> [(a, s, [Either String t])])
    -> ([(a, s, [Either String t])] -> [(a, s, [Either String t])])
    -> ParseResult s t String a
    -> [(a, s, [Either String t])]
    forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
    either String -> [(a, s, [Either String t])]
    forall a. HasCallStack => String -> a
    error [(a, s, [Either String t])] -> [(a, s, [Either String t])]
    forall a. a -> a
    id (s -> [Either String t] -> ParseResult s t String a
    p s
    st [Either String t]
    inp)

    -- | Apply the parser to some real input, given an initial state value.
    --   If the parser fails, return a diagnostic message to the caller.
    papply'           :: Parser s t e a -> s -> [Either e t]
                                             -> Either e [(a,s,[Either e t])]
    papply' :: forall s t e a.
    Parser s t e a
    -> s -> [Either e t] -> Either e [(a, s, [Either e t])]
    papply' (P s -> [Either e t] -> ParseResult s t e a
    p) s
    st [Either e t]
    inp = s -> [Either e t] -> ParseResult s t e a
    p s
    st [Either e t]
    inp

    --- Derived combinators ------------------------------------------------------

    -- | A choice between parsers.  Keep only the first success.
    (+++)             :: Parser s t e a -> Parser s t e a -> Parser s t e a
    Parser s t e a
    p +++ :: forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    +++ Parser s t e a
    q            = Parser s t e a -> Parser s t e a
    forall s t e a. Parser s t e a -> Parser s t e a
    first (Parser s t e a
    p Parser s t e a -> Parser s t e a -> Parser s t e a
    forall a. Parser s t e a -> Parser s t e a -> Parser s t e a
    forall (m :: * -> *) a. MonadPlus m => m a -> m a -> m a
    `mplus` Parser s t e a
    q)

    -- | Deliver the first token if it satisfies a predicate.
    sat               :: (t -> Bool) -> Parser s (p,t) e t
    sat :: forall t s p e. (t -> Bool) -> Parser s (p, t) e t
    sat t -> Bool
    p              = do {(_,x) <- Parser s (p, t) e (p, t)
    forall s t e. Parser s t e t
    item; if p x then return x else mzero}

    -- | Deliver the first token if it equals the argument.
    tok               :: Eq t => t -> Parser s (p,t) e t
    tok :: forall t s p e. Eq t => t -> Parser s (p, t) e t
    tok t
    t              = do {(_,x) <- Parser s (p, t) e (p, t)
    forall s t e. Parser s t e t
    item; if x==t then return t else mzero}

    -- | Deliver the first token if it does not equal the argument.
    nottok            :: Eq t => [t] -> Parser s (p,t) e t
    nottok :: forall t s p e. Eq t => [t] -> Parser s (p, t) e t
    nottok [t]
    ts          = do {(_,x) <- Parser s (p, t) e (p, t)
    forall s t e. Parser s t e t
    item; if x `notElem` ts then return x
                                            else mzero}

    -- | Deliver zero or more values of @a@.
    many              :: Parser s t e a -> Parser s t e [a]
    many :: forall s t e a. Parser s t e a -> Parser s t e [a]
    many Parser s t e a
    p             = Parser s t e a -> Parser s t e [a]
    forall s t e a. Parser s t e a -> Parser s t e [a]
    many1 Parser s t e a
    p Parser s t e [a] -> Parser s t e [a] -> Parser s t e [a]
    forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    +++ [a] -> Parser s t e [a]
    forall a. a -> Parser s t e a
    forall (m :: * -> *) a. Monad m => a -> m a
    return []
    --many p           = force (many1 p +++ return [])

    -- | Deliver one or more values of @a@.
    many1             :: Parser s t e a -> Parser s t e [a]
    many1 :: forall s t e a. Parser s t e a -> Parser s t e [a]
    many1 Parser s t e a
    p            = do {x <- Parser s t e a
    p; xs <- many p; return (x:xs)}

    -- | Deliver zero or more values of @a@ separated by @b@'s.
    sepby             :: Parser s t e a -> Parser s t e b -> Parser s t e [a]
    Parser s t e a
    p sepby :: forall s t e a b.
    Parser s t e a -> Parser s t e b -> Parser s t e [a]
    `sepby` Parser s t e b
    sep      = (Parser s t e a
    p Parser s t e a -> Parser s t e b -> Parser s t e [a]
    forall s t e a b.
    Parser s t e a -> Parser s t e b -> Parser s t e [a]
    `sepby1` Parser s t e b
    sep) Parser s t e [a] -> Parser s t e [a] -> Parser s t e [a]
    forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    +++ [a] -> Parser s t e [a]
    forall a. a -> Parser s t e a
    forall (m :: * -> *) a. Monad m => a -> m a
    return []

    -- | Deliver one or more values of @a@ separated by @b@'s.
    sepby1            :: Parser s t e a -> Parser s t e b -> Parser s t e [a]
    Parser s t e a
    p sepby1 :: forall s t e a b.
    Parser s t e a -> Parser s t e b -> Parser s t e [a]
    `sepby1` Parser s t e b
    sep     = do {x <- Parser s t e a
    p; xs <- many (do {sep; p}); return (x:xs)}

    chainl            :: Parser s t e a -> Parser s t e (a->a->a) -> a
                                                                  -> Parser s t e a
    chainl :: forall s t e a.
    Parser s t e a -> Parser s t e (a -> a -> a) -> a -> Parser s t e a
    chainl Parser s t e a
    p Parser s t e (a -> a -> a)
    op a
    v      = (Parser s t e a
    p Parser s t e a -> Parser s t e (a -> a -> a) -> Parser s t e a
    forall s t e a.
    Parser s t e a -> Parser s t e (a -> a -> a) -> Parser s t e a
    `chainl1` Parser s t e (a -> a -> a)
    op) Parser s t e a -> Parser s t e a -> Parser s t e a
    forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    +++ a -> Parser s t e a
    forall a. a -> Parser s t e a
    forall (m :: * -> *) a. Monad m => a -> m a
    return a
    v

    chainl1           :: Parser s t e a -> Parser s t e (a->a->a) -> Parser s t e a
    Parser s t e a
    p chainl1 :: forall s t e a.
    Parser s t e a -> Parser s t e (a -> a -> a) -> Parser s t e a
    `chainl1` Parser s t e (a -> a -> a)
    op     = do {x <- Parser s t e a
    p; rest x}
                         where
                            rest :: a -> Parser s t e a
    rest a
    x = do {f <- Parser s t e (a -> a -> a)
    op; y <- p; rest (f x y)}
                                     Parser s t e a -> Parser s t e a -> Parser s t e a
    forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    +++ a -> Parser s t e a
    forall a. a -> Parser s t e a
    forall (m :: * -> *) a. Monad m => a -> m a
    return a
    x

    chainr            :: Parser s t e a -> Parser s t e (a->a->a) -> a
                                                                  -> Parser s t e a
    chainr :: forall s t e a.
    Parser s t e a -> Parser s t e (a -> a -> a) -> a -> Parser s t e a
    chainr Parser s t e a
    p Parser s t e (a -> a -> a)
    op a
    v      = (Parser s t e a
    p Parser s t e a -> Parser s t e (a -> a -> a) -> Parser s t e a
    forall s t e a.
    Parser s t e a -> Parser s t e (a -> a -> a) -> Parser s t e a
    `chainr1` Parser s t e (a -> a -> a)
    op) Parser s t e a -> Parser s t e a -> Parser s t e a
    forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    +++ a -> Parser s t e a
    forall a. a -> Parser s t e a
    forall (m :: * -> *) a. Monad m => a -> m a
    return a
    v

    chainr1           :: Parser s t e a -> Parser s t e (a->a->a) -> Parser s t e a
    Parser s t e a
    p chainr1 :: forall s t e a.
    Parser s t e a -> Parser s t e (a -> a -> a) -> Parser s t e a
    `chainr1` Parser s t e (a -> a -> a)
    op     = do {x <- Parser s t e a
    p; rest x}
                         where
                            rest :: a -> Parser s t e a
    rest a
    x = do { f <- Parser s t e (a -> a -> a)
    op
                                        ; y <- p `chainr1` op
                                        ; return (f x y)
                                        }
                                     Parser s t e a -> Parser s t e a -> Parser s t e a
    forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    +++ a -> Parser s t e a
    forall a. a -> Parser s t e a
    forall (m :: * -> *) a. Monad m => a -> m a
    return a
    x

    ops               :: [(Parser s t e a, b)] -> Parser s t e b
    ops :: forall s t e a b. [(Parser s t e a, b)] -> Parser s t e b
    ops [(Parser s t e a, b)]
    xs             = (Parser s t e b -> Parser s t e b -> Parser s t e b)
    -> [Parser s t e b] -> Parser s t e b
    forall a. (a -> a -> a) -> [a] -> a
    forall (t :: * -> *) a. Foldable t => (a -> a -> a) -> t a -> a
    foldr1 Parser s t e b -> Parser s t e b -> Parser s t e b
    forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    (+++) [do {Parser s t e a
    p; b -> Parser s t e b
    forall a. a -> Parser s t e a
    forall (m :: * -> *) a. Monad m => a -> m a
    return b
    op} | (Parser s t e a
    p,b
    op) <- [(Parser s t e a, b)]
    xs]

    bracket           :: (Show p,Show t) =>
                         Parser s (p,t) e a -> Parser s (p,t) e b ->
                                   Parser s (p,t) e c -> Parser s (p,t) e b
    bracket :: forall p t s e a b c.
    (Show p, Show t) =>
    Parser s (p, t) e a
    -> Parser s (p, t) e b
    -> Parser s (p, t) e c
    -> Parser s (p, t) e b
    bracket Parser s (p, t) e a
    open Parser s (p, t) e b
    p Parser s (p, t) e c
    close = do { Parser s (p, t) e a
    open
                              ; x <- Parser s (p, t) e b
    p
                              ; close -- `elserror` "improperly matched construct";
                              ; return x
                              }

    -- | Accept a complete parse of the input only, no partial parses.
    toEOF             :: Show p =>
                         Parser s (p,t) String a -> Parser s (p,t) String a
    toEOF :: forall p s t a.
    Show p =>
    Parser s (p, t) String a -> Parser s (p, t) String a
    toEOF Parser s (p, t) String a
    p            = do { x <- Parser s (p, t) String a
    p; eof; return x }

    --- Error handling -----------------------------------------------------------

    -- | Return an error using the supplied diagnostic string, and a token type
    --   which includes position information.
    parseerror :: (Show p,Show t) => String -> Parser s (p,t) String a
    parseerror :: forall p t s a.
    (Show p, Show t) =>
    String -> Parser s (p, t) String a
    parseerror String
    err = (s -> [Either String (p, t)] -> ParseResult s (p, t) String a)
    -> Parser s (p, t) String a
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either String (p, t)]
    inp ->
                             case [Either String (p, t)]
    inp of
                               [] -> String -> ParseResult s (p, t) String a
    forall a b. a -> Either a b
    Left String
    "Parse error: unexpected EOF\n"
                               (Left String
    e:[Either String (p, t)]
    _) -> String -> ParseResult s (p, t) String a
    forall a b. a -> Either a b
    Left (String
    "Lexical error:  "String -> String -> String
    forall a. [a] -> [a] -> [a]
    ++String
    e)
                               (Right (p
    p,t
    t):[Either String (p, t)]
    _)  ->
                                     String -> ParseResult s (p, t) String a
    forall a b. a -> Either a b
    Left (String
    "Parse error: in  "String -> String -> String
    forall a. [a] -> [a] -> [a]
    ++p -> String
    forall a. Show a => a -> String
    show p
    pString -> String -> String
    forall a. [a] -> [a] -> [a]
    ++String
    "\n    "
                                           String -> String -> String
    forall a. [a] -> [a] -> [a]
    ++String
    errString -> String -> String
    forall a. [a] -> [a] -> [a]
    ++String
    "\n  "String -> String -> String
    forall a. [a] -> [a] -> [a]
    ++String
    "Found "String -> String -> String
    forall a. [a] -> [a] -> [a]
    ++t -> String
    forall a. Show a => a -> String
    show t
    t)
                       )

    -- | If the parser fails, generate an error message.
    elserror          :: (Show p,Show t) => Parser s (p,t) String a -> String
                                            -> Parser s (p,t) String a
    Parser s (p, t) String a
    p elserror :: forall p t s a.
    (Show p, Show t) =>
    Parser s (p, t) String a -> String -> Parser s (p, t) String a
    `elserror` String
    s     = Parser s (p, t) String a
    p Parser s (p, t) String a
    -> Parser s (p, t) String a -> Parser s (p, t) String a
    forall s t e a. Parser s t e a -> Parser s t e a -> Parser s t e a
    +++ String -> Parser s (p, t) String a
    forall p t s a.
    (Show p, Show t) =>
    String -> Parser s (p, t) String a
    parseerror String
    s

    --- State handling -----------------------------------------------------------

    -- | Update the internal state.
    stupd      :: (s->s) -> Parser s t e ()
    stupd :: forall s t e. (s -> s) -> Parser s t e ()
    stupd s -> s
    f     = (s -> [Either e t] -> ParseResult s t e ()) -> Parser s t e ()
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp-> {-let newst = f st in newst `seq`-}
                               [((), s, [Either e t])] -> ParseResult s t e ()
    forall a b. b -> Either a b
    Right [((), s -> s
    f s
    st, [Either e t]
    inp)])

    -- | Query the internal state.
    stquery    :: (s->a) -> Parser s t e a
    stquery :: forall s a t e. (s -> a) -> Parser s t e a
    stquery s -> a
    f   = (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp-> [(a, s, [Either e t])] -> ParseResult s t e a
    forall a b. b -> Either a b
    Right [(s -> a
    f s
    st, s
    st, [Either e t]
    inp)])

    -- | Deliver the entire internal state.
    stget      :: Parser s t e s
    stget :: forall s t e. Parser s t e s
    stget       = (s -> [Either e t] -> ParseResult s t e s) -> Parser s t e s
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp-> [(s, s, [Either e t])] -> ParseResult s t e s
    forall a b. b -> Either a b
    Right [(s
    st, s
    st, [Either e t]
    inp)])

    --- Push some tokens back onto the input stream and reparse ------------------

    -- | This is useful for recursively expanding macros.  When the
    --   user-parser recognises a macro use, it can lookup the macro
    --   expansion from the parse state, lex it, and then stuff the
    --   lexed expansion back down into the parser.
    reparse    :: [Either e t] -> Parser s t e ()
    reparse :: forall e t s. [Either e t] -> Parser s t e ()
    reparse [Either e t]
    ts  = (s -> [Either e t] -> ParseResult s t e ()) -> Parser s t e ()
    forall s t e a.
    (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a
    P (\s
    st [Either e t]
    inp-> [((), s, [Either e t])] -> ParseResult s t e ()
    forall a b. b -> Either a b
    Right [((), s
    st, [Either e t]
    ts[Either e t] -> [Either e t] -> [Either e t]
    forall a. [a] -> [a] -> [a]
    ++[Either e t]
    inp)])

    ------------------------------------------------------------------------------