Text.Megaparsec

This module includes everything you need to get started writing a parser. If you are new to Megaparsec and don't know where to begin, take a look at the tutorials https://markkarpov.com/learn-haskell.html#megaparsec-tutorials.

In addition to the Text.Megaparsec module, which exports and re-exports most everything that you may need, we advise to import Text.Megaparsec.Char if you plan to work with a stream of Char tokens or Text.Megaparsec.Byte if you intend to parse binary data.

It is common to start working with the library by defining a type synonym like this:

type Parser = Parsec Void Text
                     ^    ^
                     |    |
Custom error component    Type of input

Then you can write type signatures like Parser Int—for a parser that returns an Int for example.

Similarly (since it's known to cause confusion), you should use ParseError type parametrized like this:

ParseError Char Void
           ^    ^
           |    |
  Token type    Custom error component (the same you used in Parser)

Token type for String and Text (strict and lazy) is Char, for ByteStrings it's Word8.

Megaparsec uses some type-level machinery to provide flexibility without compromising on type safety. Thus type signatures are sometimes necessary to avoid ambiguous types. If you're seeing a error message that reads like “Type variable e0 is ambiguous …”, you need to give an explicit signature to your parser to resolve the ambiguity. It's a good idea to provide type signatures for all top-level definitions.

Megaparsec is capable of a lot. Apart from this standard functionality you can parse permutation phrases with Text.Megaparsec.Perm, expressions with Text.Megaparsec.Expr, do lexing with Text.Megaparsec.Char.Lexer and Text.Megaparsec.Byte.Lexer. These modules should be imported explicitly along with the modules mentioned above.

Re-exports

Also note that you can import Control.Applicative.Combinators.NonEmpty if you wish that combinators like some return NonEmpty lists. The module lives in the parser-combinators package (you need at least version 0.2.0).

This module is intended to be imported qualified:

import qualified Control.Applicative.Combinators.NonEmpty as NE

module Text.Megaparsec.Pos

module Text.Megaparsec.Error

module Text.Megaparsec.Stream

module Control.Applicative.Combinators

Data types

data State s

This is the Megaparsec's state parametrized over stream type s.

Constructors

State

Fields

• stateInput :: s

  The rest of input to process

• statePos :: NonEmpty SourcePos

  Current position (column + line number) with support for include files

• stateTokensProcessed :: !Int

  Number of processed tokens so far

  Since: 5.2.0

• stateTabWidth :: Pos

  Tab width to use

Instances

Eq s => Eq (State s)

Methods

(==) :: State s -> State s -> Bool

(/=) :: State s -> State s -> Bool

Data s => Data (State s)

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> State s -> c (State s)

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (State s)

toConstr :: State s -> Constr

dataTypeOf :: State s -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c (State s))

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (State s))

gmapT :: (forall b. Data b => b -> b) -> State s -> State s

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> State s -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> State s -> r

gmapQ :: (forall d. Data d => d -> u) -> State s -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> State s -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> State s -> m (State s)

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> State s -> m (State s)

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> State s -> m (State s)

Show s => Show (State s)

Methods

showsPrec :: Int -> State s -> ShowS

show :: State s -> String

showList :: [State s] -> ShowS

Generic (State s)

Associated Types

type Rep (State s) :: * -> *

Methods

from :: State s -> Rep (State s) x

to :: Rep (State s) x -> State s

NFData s => NFData (State s)

Methods

rnf :: State s -> ()

type Rep (State s)

type Rep (State s) = D1 (MetaData "State" "Text.Megaparsec" "megaparsec-6.1.1-CMqSyVo2ujBIkjeh07Majh" False) (C1 (MetaCons "State" PrefixI True) ((:*:) ((:*:) (S1 (MetaSel (Just Symbol "stateInput") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 s)) (S1 (MetaSel (Just Symbol "statePos") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (NonEmpty SourcePos)))) ((:*:) (S1 (MetaSel (Just Symbol "stateTokensProcessed") SourceUnpack SourceStrict DecidedUnpack) (Rec0 Int)) (S1 (MetaSel (Just Symbol "stateTabWidth") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Pos)))))

type Parsec e s = ParsecT e s Identity

Parsec is a non-transformer variant of the more general ParsecT monad transformer.

data ParsecT e s m a

ParsecT e s m a is a parser with custom data component of error e, stream type s, underlying monad m and return type a.

Instances

(Ord e, Stream s) => MonadParsec e s (ParsecT e s m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> ParsecT e s m a

fancyFailure :: Set (ErrorFancy e) -> ParsecT e s m a

label :: String -> ParsecT e s m a -> ParsecT e s m a

hidden :: ParsecT e s m a -> ParsecT e s m a

try :: ParsecT e s m a -> ParsecT e s m a

lookAhead :: ParsecT e s m a -> ParsecT e s m a

notFollowedBy :: ParsecT e s m a -> ParsecT e s m ()

withRecovery :: (ParseError (Token s) e -> ParsecT e s m a) -> ParsecT e s m a -> ParsecT e s m a

observing :: ParsecT e s m a -> ParsecT e s m (Either (ParseError (Token s) e) a)

eof :: ParsecT e s m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> ParsecT e s m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> ParsecT e s m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> ParsecT e s m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> ParsecT e s m (Tokens s)

takeP :: Maybe String -> Int -> ParsecT e s m (Tokens s)

getParserState :: ParsecT e s m (State s)

updateParserState :: (State s -> State s) -> ParsecT e s m ()

(Stream s, MonadError e' m) => MonadError e' (ParsecT e s m)

Methods

throwError :: e' -> ParsecT e s m a

catchError :: ParsecT e s m a -> (e' -> ParsecT e s m a) -> ParsecT e s m a

(Stream s, MonadReader r m) => MonadReader r (ParsecT e s m)

Methods

ask :: ParsecT e s m r

local :: (r -> r) -> ParsecT e s m a -> ParsecT e s m a

reader :: (r -> a) -> ParsecT e s m a

(Stream s, MonadState st m) => MonadState st (ParsecT e s m)

Methods

get :: ParsecT e s m st

put :: st -> ParsecT e s m ()

state :: (st -> (a, st)) -> ParsecT e s m a

MonadTrans (ParsecT e s)

Methods

lift :: Monad m => m a -> ParsecT e s m a

Stream s => Monad (ParsecT e s m)

return returns a parser that succeeds without consuming input.

Methods

(>>=) :: ParsecT e s m a -> (a -> ParsecT e s m b) -> ParsecT e s m b

(>>) :: ParsecT e s m a -> ParsecT e s m b -> ParsecT e s m b

return :: a -> ParsecT e s m a

fail :: String -> ParsecT e s m a

Functor (ParsecT e s m)

Methods

fmap :: (a -> b) -> ParsecT e s m a -> ParsecT e s m b

(<$) :: a -> ParsecT e s m b -> ParsecT e s m a

(Stream s, MonadFix m) => MonadFix (ParsecT e s m)

Methods

mfix :: (a -> ParsecT e s m a) -> ParsecT e s m a

Stream s => MonadFail (ParsecT e s m)

Methods

fail :: String -> ParsecT e s m a

Stream s => Applicative (ParsecT e s m)

pure returns a parser that succeeds without consuming input.

Methods

pure :: a -> ParsecT e s m a

(<*>) :: ParsecT e s m (a -> b) -> ParsecT e s m a -> ParsecT e s m b

(*>) :: ParsecT e s m a -> ParsecT e s m b -> ParsecT e s m b

(<*) :: ParsecT e s m a -> ParsecT e s m b -> ParsecT e s m a

(Stream s, MonadIO m) => MonadIO (ParsecT e s m)

Methods

liftIO :: IO a -> ParsecT e s m a

(Ord e, Stream s) => Alternative (ParsecT e s m)

empty is a parser that fails without consuming input.

Methods

empty :: ParsecT e s m a

(<|>) :: ParsecT e s m a -> ParsecT e s m a -> ParsecT e s m a

some :: ParsecT e s m a -> ParsecT e s m [a]

many :: ParsecT e s m a -> ParsecT e s m [a]

(Ord e, Stream s) => MonadPlus (ParsecT e s m)

mzero is a parser that fails without consuming input.

Methods

mzero :: ParsecT e s m a

mplus :: ParsecT e s m a -> ParsecT e s m a -> ParsecT e s m a

(Stream s, MonadCont m) => MonadCont (ParsecT e s m)

Methods

callCC :: ((a -> ParsecT e s m b) -> ParsecT e s m a) -> ParsecT e s m a

(Stream s, Semigroup a) => Semigroup (ParsecT e s m a)

Methods

(<>) :: ParsecT e s m a -> ParsecT e s m a -> ParsecT e s m a

sconcat :: NonEmpty (ParsecT e s m a) -> ParsecT e s m a

stimes :: Integral b => b -> ParsecT e s m a -> ParsecT e s m a

(Stream s, Monoid a) => Monoid (ParsecT e s m a)

Methods

mempty :: ParsecT e s m a

mappend :: ParsecT e s m a -> ParsecT e s m a -> ParsecT e s m a

mconcat :: [ParsecT e s m a] -> ParsecT e s m a

Running parser

parse

Arguments

:: Parsec e s a

Parser to run

-> String

Name of source file

-> s

Input for parser

-> Either (ParseError (Token s) e) a

parse p file input runs parser p over Identity (see runParserT if you're using the ParsecT monad transformer; parse itself is just a synonym for runParser). It returns either a ParseError (Left) or a value of type a (Right). parseErrorPretty can be used to turn ParseError into the string representation of the error message. See Text.Megaparsec.Error if you need to do more advanced error analysis.

main = case (parse numbers "" "11,2,43") of
         Left err -> putStr (parseErrorPretty err)
         Right xs -> print (sum xs)

numbers = integer `sepBy` char ','

parseMaybe :: (Ord e, Stream s) => Parsec e s a -> s -> Maybe a

parseMaybe p input runs the parser p on input and returns the result inside Just on success and Nothing on failure. This function also parses eof, so if the parser doesn't consume all of its input, it will fail.

The function is supposed to be useful for lightweight parsing, where error messages (and thus file name) are not important and entire input should be parsed. For example, it can be used when parsing of a single number according to a specification of its format is desired.

parseTest

Arguments

:: (ShowErrorComponent e, Ord (Token s), ShowToken (Token s), Show a)

=> Parsec e s a

Parser to run

-> s

Input for parser

-> IO ()

The expression parseTest p input applies the parser p against input input and prints the result to stdout. Useful for testing.

parseTest'

Arguments

:: (ShowErrorComponent e, ShowToken (Token s), LineToken (Token s), Show a, Stream s)

=> Parsec e s a

Parser to run

-> s

Input for parser

-> IO ()

A version of parseTest that also prints offending line in parse errors.

Since: 6.0.0

runParser

Arguments

:: Parsec e s a

Parser to run

-> String

Name of source file

-> s

Input for parser

-> Either (ParseError (Token s) e) a

runParser p file input runs parser p on the input stream of tokens input, obtained from source file. The file is only used in error messages and may be the empty string. Returns either a ParseError (Left) or a value of type a (Right).

parseFromFile p file = runParser p file <$> readFile file

runParser'

Arguments

:: Parsec e s a

Parser to run

-> State s

Initial state

-> (State s, Either (ParseError (Token s) e) a)

The function is similar to runParser with the difference that it accepts and returns parser state. This allows to specify arbitrary textual position at the beginning of parsing, for example. This is the most general way to run a parser over the Identity monad.

Since: 4.2.0

runParserT

Arguments

:: Monad m

=> ParsecT e s m a

Parser to run

-> String

Name of source file

-> s

Input for parser

-> m (Either (ParseError (Token s) e) a)

runParserT p file input runs parser p on the input list of tokens input, obtained from source file. The file is only used in error messages and may be the empty string. Returns a computation in the underlying monad m that returns either a ParseError (Left) or a value of type a (Right).

runParserT'

Arguments

:: Monad m

=> ParsecT e s m a

Parser to run

-> State s

Initial state

-> m (State s, Either (ParseError (Token s) e) a)

This function is similar to runParserT, but like runParser' it accepts and returns parser state. This is thus the most general way to run a parser.

Since: 4.2.0

Primitive combinators

class (Stream s, Alternative m, MonadPlus m) => MonadParsec e s m | m -> e s where

Type class describing monads that implement the full set of primitive parsers.

Note carefully that the following primitives are “fast” and should be taken advantage of as much as possible if your aim is a fast parser: tokens, takeWhileP, takeWhile1P, and takeP.

Minimal complete definition

failure, fancyFailure, label, try, lookAhead, notFollowedBy, withRecovery, observing, eof, token, tokens, takeWhileP, takeWhile1P, takeP, getParserState, updateParserState

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> m a

The most general way to stop parsing and report a trivial ParseError.

Since: 6.0.0

fancyFailure :: Set (ErrorFancy e) -> m a

The most general way to stop parsing and report a fancy ParseError.

Since: 6.0.0

label :: String -> m a -> m a

The parser label name p behaves as parser p, but whenever the parser p fails without consuming any input, it replaces names of “expected” tokens with the name name.

hidden :: m a -> m a

hidden p behaves just like parser p, but it doesn't show any “expected” tokens in error message when p fails.

Please use hidden instead of the old label "" idiom.

try :: m a -> m a

The parser try p behaves like parser p, except that it backtracks the parser state when p fails (either consuming input or not).

This combinator is used whenever arbitrary look ahead is needed. Since it pretends that it hasn't consumed any input when p fails, the (<|>) combinator will try its second alternative even if the first parser failed while consuming input.

For example, here is a parser that is supposed to parse the word “let” or the word “lexical”:

>>> parseTest (string "let" <|> string "lexical") "lexical"
1:1:
unexpected "lex"
expecting "let"

What happens here? The first parser consumes “le” and fails (because it doesn't see a “t”). The second parser, however, isn't tried, since the first parser has already consumed some input! try fixes this behavior and allows backtracking to work:

>>> parseTest (try (string "let") <|> string "lexical") "lexical"
"lexical"

try also improves error messages in case of overlapping alternatives, because Megaparsec's hint system can be used:

>>> parseTest (try (string "let") <|> string "lexical") "le"
1:1:
unexpected "le"
expecting "let" or "lexical"

Please note that as of Megaparsec 4.4.0, string backtracks automatically (see tokens), so it does not need try. However, the examples above demonstrate the idea behind try so well that it was decided to keep them. You still need to use try when your alternatives are complex, composite parsers.

lookAhead :: m a -> m a

If p in lookAhead p succeeds (either consuming input or not) the whole parser behaves like p succeeded without consuming anything (parser state is not updated as well). If p fails, lookAhead has no effect, i.e. it will fail consuming input if p fails consuming input. Combine with try if this is undesirable.

notFollowedBy :: m a -> m ()

notFollowedBy p only succeeds when the parser p fails. This parser never consumes any input and never modifies parser state. It can be used to implement the “longest match” rule.

withRecovery :: (ParseError (Token s) e -> m a) -> m a -> m a

withRecovery r p allows continue parsing even if parser p fails. In this case r is called with the actual ParseError as its argument. Typical usage is to return a value signifying failure to parse this particular object and to consume some part of the input up to the point where the next object starts.

Note that if r fails, original error message is reported as if without withRecovery. In no way recovering parser r can influence error messages.

Since: 4.4.0

observing :: m a -> m (Either (ParseError (Token s) e) a)

observing p allows to “observe” failure of the p parser, should it happen, without actually ending parsing, but instead getting the ParseError in Left. On success parsed value is returned in Right as usual. Note that this primitive just allows you to observe parse errors as they happen, it does not backtrack or change how the p parser works in any way.

Since: 5.1.0

eof :: m ()

This parser only succeeds at the end of the input.

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> m a

The parser token test mrep accepts a token t with result x when the function test t returns Right x. mrep may provide representation of the token to report in error messages when input stream in empty.

This is the most primitive combinator for accepting tokens. For example, the satisfy parser is implemented as:

satisfy f = token testChar Nothing
  where
    testChar x =
      if f x
        then Right x
        else Left (pure (Tokens (x:|[])), Set.empty)

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> m (Tokens s)

The parser tokens test parses a chunk of input and returns it. Supplied predicate test is used to check equality of given and parsed chunks after a candidate chunk of correct length is fetched from the stream.

This can be used for example to write string:

string = tokens (==)

Note that beginning from Megaparsec 4.4.0, this is an auto-backtracking primitive, which means that if it fails, it never consumes any input. This is done to make its consumption model match how error messages for this primitive are reported (which becomes an important thing as user gets more control with primitives like withRecovery):

>>> parseTest (string "abc") "abd"
1:1:
unexpected "abd"
expecting "abc"

This means, in particular, that it's no longer necessary to use try with tokens-based parsers, such as string and string'. This feature does not affect performance in any way.

takeWhileP :: Maybe String -> (Token s -> Bool) -> m (Tokens s)

Parse zero or more tokens for which the supplied predicate holds. Try to use this as much as possible because for many streams the combinator is much faster than parsers built with many and satisfy.

The following equations should clarify the behavior:

takeWhileP (Just "foo") f = many (satisfy f <?> "foo")
takeWhileP Nothing      f = many (satisfy f)

The combinator never fails, although it may parse an empty chunk.

Since: 6.0.0

takeWhile1P :: Maybe String -> (Token s -> Bool) -> m (Tokens s)

Similar to takeWhileP, but fails if it can't parse at least one token. Note that the combinator either succeeds or fails without consuming any input, so try is not necessary with it.

Since: 6.0.0

takeP :: Maybe String -> Int -> m (Tokens s)

Extract the specified number of tokens from the input stream and return them packed as a chunk of stream. If there is not enough tokens in the stream, a parse error will be signaled. It's guaranteed that if the parser succeeds, the requested number of tokens will be returned.

The parser is roughly equivalent to:

takeP (Just "foo") n = count n (anyChar <?> "foo")
takeP Nothing      n = count n anyChar

Note that if the combinator fails due to insufficient number of tokens in the input stream, it backtracks automatically. No try is necessary with takeP.

Since: 6.0.0

getParserState :: m (State s)

Return the full parser state as a State record.

updateParserState :: (State s -> State s) -> m ()

updateParserState f applies the function f to the parser state.

Instances

MonadParsec e s m => MonadParsec e s (IdentityT * m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> IdentityT * m a

fancyFailure :: Set (ErrorFancy e) -> IdentityT * m a

label :: String -> IdentityT * m a -> IdentityT * m a

hidden :: IdentityT * m a -> IdentityT * m a

try :: IdentityT * m a -> IdentityT * m a

lookAhead :: IdentityT * m a -> IdentityT * m a

notFollowedBy :: IdentityT * m a -> IdentityT * m ()

withRecovery :: (ParseError (Token s) e -> IdentityT * m a) -> IdentityT * m a -> IdentityT * m a

observing :: IdentityT * m a -> IdentityT * m (Either (ParseError (Token s) e) a)

eof :: IdentityT * m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> IdentityT * m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> IdentityT * m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> IdentityT * m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> IdentityT * m (Tokens s)

takeP :: Maybe String -> Int -> IdentityT * m (Tokens s)

getParserState :: IdentityT * m (State s)

updateParserState :: (State s -> State s) -> IdentityT * m ()

(Monoid w, MonadParsec e s m) => MonadParsec e s (WriterT w m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> WriterT w m a

fancyFailure :: Set (ErrorFancy e) -> WriterT w m a

label :: String -> WriterT w m a -> WriterT w m a

hidden :: WriterT w m a -> WriterT w m a

try :: WriterT w m a -> WriterT w m a

lookAhead :: WriterT w m a -> WriterT w m a

notFollowedBy :: WriterT w m a -> WriterT w m ()

withRecovery :: (ParseError (Token s) e -> WriterT w m a) -> WriterT w m a -> WriterT w m a

observing :: WriterT w m a -> WriterT w m (Either (ParseError (Token s) e) a)

eof :: WriterT w m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> WriterT w m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> WriterT w m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> WriterT w m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> WriterT w m (Tokens s)

takeP :: Maybe String -> Int -> WriterT w m (Tokens s)

getParserState :: WriterT w m (State s)

updateParserState :: (State s -> State s) -> WriterT w m ()

(Monoid w, MonadParsec e s m) => MonadParsec e s (WriterT w m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> WriterT w m a

fancyFailure :: Set (ErrorFancy e) -> WriterT w m a

label :: String -> WriterT w m a -> WriterT w m a

hidden :: WriterT w m a -> WriterT w m a

try :: WriterT w m a -> WriterT w m a

lookAhead :: WriterT w m a -> WriterT w m a

notFollowedBy :: WriterT w m a -> WriterT w m ()

withRecovery :: (ParseError (Token s) e -> WriterT w m a) -> WriterT w m a -> WriterT w m a

observing :: WriterT w m a -> WriterT w m (Either (ParseError (Token s) e) a)

eof :: WriterT w m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> WriterT w m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> WriterT w m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> WriterT w m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> WriterT w m (Tokens s)

takeP :: Maybe String -> Int -> WriterT w m (Tokens s)

getParserState :: WriterT w m (State s)

updateParserState :: (State s -> State s) -> WriterT w m ()

MonadParsec e s m => MonadParsec e s (StateT st m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> StateT st m a

fancyFailure :: Set (ErrorFancy e) -> StateT st m a

label :: String -> StateT st m a -> StateT st m a

hidden :: StateT st m a -> StateT st m a

try :: StateT st m a -> StateT st m a

lookAhead :: StateT st m a -> StateT st m a

notFollowedBy :: StateT st m a -> StateT st m ()

withRecovery :: (ParseError (Token s) e -> StateT st m a) -> StateT st m a -> StateT st m a

observing :: StateT st m a -> StateT st m (Either (ParseError (Token s) e) a)

eof :: StateT st m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> StateT st m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> StateT st m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> StateT st m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> StateT st m (Tokens s)

takeP :: Maybe String -> Int -> StateT st m (Tokens s)

getParserState :: StateT st m (State s)

updateParserState :: (State s -> State s) -> StateT st m ()

MonadParsec e s m => MonadParsec e s (StateT st m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> StateT st m a

fancyFailure :: Set (ErrorFancy e) -> StateT st m a

label :: String -> StateT st m a -> StateT st m a

hidden :: StateT st m a -> StateT st m a

try :: StateT st m a -> StateT st m a

lookAhead :: StateT st m a -> StateT st m a

notFollowedBy :: StateT st m a -> StateT st m ()

withRecovery :: (ParseError (Token s) e -> StateT st m a) -> StateT st m a -> StateT st m a

observing :: StateT st m a -> StateT st m (Either (ParseError (Token s) e) a)

eof :: StateT st m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> StateT st m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> StateT st m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> StateT st m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> StateT st m (Tokens s)

takeP :: Maybe String -> Int -> StateT st m (Tokens s)

getParserState :: StateT st m (State s)

updateParserState :: (State s -> State s) -> StateT st m ()

MonadParsec e s m => MonadParsec e s (ReaderT * r m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> ReaderT * r m a

fancyFailure :: Set (ErrorFancy e) -> ReaderT * r m a

label :: String -> ReaderT * r m a -> ReaderT * r m a

hidden :: ReaderT * r m a -> ReaderT * r m a

try :: ReaderT * r m a -> ReaderT * r m a

lookAhead :: ReaderT * r m a -> ReaderT * r m a

notFollowedBy :: ReaderT * r m a -> ReaderT * r m ()

withRecovery :: (ParseError (Token s) e -> ReaderT * r m a) -> ReaderT * r m a -> ReaderT * r m a

observing :: ReaderT * r m a -> ReaderT * r m (Either (ParseError (Token s) e) a)

eof :: ReaderT * r m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> ReaderT * r m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> ReaderT * r m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> ReaderT * r m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> ReaderT * r m (Tokens s)

takeP :: Maybe String -> Int -> ReaderT * r m (Tokens s)

getParserState :: ReaderT * r m (State s)

updateParserState :: (State s -> State s) -> ReaderT * r m ()

(Ord e, Stream s) => MonadParsec e s (ParsecT e s m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> ParsecT e s m a

fancyFailure :: Set (ErrorFancy e) -> ParsecT e s m a

label :: String -> ParsecT e s m a -> ParsecT e s m a

hidden :: ParsecT e s m a -> ParsecT e s m a

try :: ParsecT e s m a -> ParsecT e s m a

lookAhead :: ParsecT e s m a -> ParsecT e s m a

notFollowedBy :: ParsecT e s m a -> ParsecT e s m ()

withRecovery :: (ParseError (Token s) e -> ParsecT e s m a) -> ParsecT e s m a -> ParsecT e s m a

observing :: ParsecT e s m a -> ParsecT e s m (Either (ParseError (Token s) e) a)

eof :: ParsecT e s m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> ParsecT e s m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> ParsecT e s m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> ParsecT e s m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> ParsecT e s m (Tokens s)

takeP :: Maybe String -> Int -> ParsecT e s m (Tokens s)

getParserState :: ParsecT e s m (State s)

updateParserState :: (State s -> State s) -> ParsecT e s m ()

(Monoid w, MonadParsec e s m) => MonadParsec e s (RWST r w st m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> RWST r w st m a

fancyFailure :: Set (ErrorFancy e) -> RWST r w st m a

label :: String -> RWST r w st m a -> RWST r w st m a

hidden :: RWST r w st m a -> RWST r w st m a

try :: RWST r w st m a -> RWST r w st m a

lookAhead :: RWST r w st m a -> RWST r w st m a

notFollowedBy :: RWST r w st m a -> RWST r w st m ()

withRecovery :: (ParseError (Token s) e -> RWST r w st m a) -> RWST r w st m a -> RWST r w st m a

observing :: RWST r w st m a -> RWST r w st m (Either (ParseError (Token s) e) a)

eof :: RWST r w st m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> RWST r w st m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> RWST r w st m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> RWST r w st m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> RWST r w st m (Tokens s)

takeP :: Maybe String -> Int -> RWST r w st m (Tokens s)

getParserState :: RWST r w st m (State s)

updateParserState :: (State s -> State s) -> RWST r w st m ()

(Monoid w, MonadParsec e s m) => MonadParsec e s (RWST r w st m)

Methods

failure :: Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> RWST r w st m a

fancyFailure :: Set (ErrorFancy e) -> RWST r w st m a

label :: String -> RWST r w st m a -> RWST r w st m a

hidden :: RWST r w st m a -> RWST r w st m a

try :: RWST r w st m a -> RWST r w st m a

lookAhead :: RWST r w st m a -> RWST r w st m a

notFollowedBy :: RWST r w st m a -> RWST r w st m ()

withRecovery :: (ParseError (Token s) e -> RWST r w st m a) -> RWST r w st m a -> RWST r w st m a

observing :: RWST r w st m a -> RWST r w st m (Either (ParseError (Token s) e) a)

eof :: RWST r w st m ()

token :: (Token s -> Either (Maybe (ErrorItem (Token s)), Set (ErrorItem (Token s))) a) -> Maybe (Token s) -> RWST r w st m a

tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> RWST r w st m (Tokens s)

takeWhileP :: Maybe String -> (Token s -> Bool) -> RWST r w st m (Tokens s)

takeWhile1P :: Maybe String -> (Token s -> Bool) -> RWST r w st m (Tokens s)

takeP :: Maybe String -> Int -> RWST r w st m (Tokens s)

getParserState :: RWST r w st m (State s)

updateParserState :: (State s -> State s) -> RWST r w st m ()

Derivatives of primitive combinators

(<?>) :: MonadParsec e s m => m a -> String -> m a infix 0

A synonym for label in the form of an operator.

unexpected :: MonadParsec e s m => ErrorItem (Token s) -> m a

The parser unexpected item fails with an error message telling about unexpected item item without consuming any input.

unexpected item = failure (pure item) Set.empty

match :: MonadParsec e s m => m a -> m (Tokens s, a)

Return both the result of a parse and a chunk of input that was consumed during parsing. This relies on the change of the stateTokensProcessed value to evaluate how many tokens were consumed. If you mess with it manually in the argument parser, prepare for troubles.

Since: 5.3.0

region

Arguments

:: MonadParsec e s m

=> (ParseError (Token s) e -> ParseError (Token s) e)

How to process ParseErrors

-> m a

The “region” that the processing applies to

-> m a

Specify how to process ParseErrors that happen inside of this wrapper. As a side effect of the current implementation changing errorPos with this combinator will also change the final statePos in the parser state (try to avoid that because statePos will go out of sync with factual position in the input stream, which is probably OK if you finish parsing right after that, but be warned).

Since: 5.3.0

takeRest :: MonadParsec e s m => m (Tokens s)

Consume the rest of the input and return it as a chunk. This parser never fails, but may return an empty chunk.

takeRest = takeWhileP Nothing (const True)

Since: 6.0.0

atEnd :: MonadParsec e s m => m Bool

Return True when end of input has been reached.

Since: 6.0.0

Parser state combinators

getInput :: MonadParsec e s m => m s

Return the current input.

setInput :: MonadParsec e s m => s -> m ()

setInput input continues parsing with input. The getInput and setInput functions can for example be used to deal with include files.

getPosition :: MonadParsec e s m => m SourcePos

Return the current source position.

See also: setPosition, pushPosition, popPosition, and SourcePos.

getNextTokenPosition :: forall e s m. MonadParsec e s m => m (Maybe SourcePos)

Get the position where the next token in the stream begins. If the stream is empty, return Nothing.

Since: 5.3.0

setPosition :: MonadParsec e s m => SourcePos -> m ()

setPosition pos sets the current source position to pos.

See also: getPosition, pushPosition, popPosition, and SourcePos.

pushPosition :: MonadParsec e s m => SourcePos -> m ()

Push a position into stack of positions and continue parsing working with this position. Useful for working with include files and the like.

See also: getPosition, setPosition, popPosition, and SourcePos.

Since: 5.0.0

popPosition :: MonadParsec e s m => m ()

Pop a position from the stack of positions unless it only contains one element (in that case the stack of positions remains the same). This is how to return to previous source file after pushPosition.

See also: getPosition, setPosition, pushPosition, and SourcePos.

Since: 5.0.0

getTokensProcessed :: MonadParsec e s m => m Int

Get the number of tokens processed so far.

Since: 6.0.0

setTokensProcessed :: MonadParsec e s m => Int -> m ()

Set the number of tokens processed so far.

Since: 6.0.0

getTabWidth :: MonadParsec e s m => m Pos

Return the tab width. The default tab width is equal to defaultTabWidth. You can set a different tab width with the help of setTabWidth.

setTabWidth :: MonadParsec e s m => Pos -> m ()

Set tab width. If the argument of the function is not a positive number, defaultTabWidth will be used.

setParserState :: MonadParsec e s m => State s -> m ()

setParserState st sets the parser state to st.

Debugging

dbg

Arguments

:: (Stream s, ShowToken (Token s), ShowErrorComponent e, Show a)

=> String

Debugging label

-> ParsecT e s m a

Parser to debug

-> ParsecT e s m a

Parser that prints debugging messages

dbg label p parser works exactly like p, but when it's evaluated it also prints information useful for debugging. The label is only used to refer to this parser in the debugging output. This combinator uses the trace function from Debug.Trace under the hood.

Typical usage is to wrap every sub-parser in misbehaving parser with dbg assigning meaningful labels. Then give it a shot and go through the print-out. As of current version, this combinator prints all available information except for hints, which are probably only interesting to the maintainer of Megaparsec itself and may be quite verbose to output in general. Let me know if you would like to be able to see hints in the debugging output.

The output itself is pretty self-explanatory, although the following abbreviations should be clarified (they are derived from the low-level source code):

• COK—“consumed OK”. The parser consumed input and succeeded.
• CERR—“consumed error”. The parser consumed input and failed.
• EOK—“empty OK”. The parser succeeded without consuming input.
• EERR—“empty error”. The parser failed without consuming input.

Finally, it's not possible to lift this function into some monad transformers without introducing surprising behavior (e.g. unexpected state backtracking) or adding otherwise redundant constraints (e.g. Show instance for state), so this helper is only available for ParsecT monad, not MonadParsec in general.

Since: 5.1.0