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

ParsecT s m a is a parser with stream type s, underlying monad m and return type a.

runParser 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 either a ParseError (Left) or a value of type a (Right).

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

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

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

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). show or print 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 -> print err
         Right xs -> print (sum xs)

numbers = commaSep integer

parseMaybe p input runs parser p on input and returns 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 single number according to specification of its format is desired.

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

parseFromFile p filename runs parser p on the input read from filename. Returns either a ParseError (Left) or a value of type a (Right).

main = do
  result <- parseFromFile numbers "digits.txt"
  case result of
    Left err -> print err
    Right xs -> print $ sum xs

An associative binary operation

Zero or more.

One or more.

One or none.

The parser unexpected msg always fails with an unexpected error message msg without consuming any input.

The parsers fail, label and unexpected are the three parsers used to generate error messages. Of these, only label is commonly used.

The most general way to stop parsing and report ParseError.

unexpected is defined in terms of the function:

unexpected = failure . pure . Unexpected

Since: 4.2.0

A synonym for label in form of an operator.

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 p behaves just like parser p, but it doesn't show any “expected” tokens in error message when p fails.

The parser try p behaves like parser p, except that it pretends that it hasn't consumed any input when an error occurs.

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 when the first parser failed while consuming input.

For example, here is a parser that will try (sorry for the pun) to parse word “let” or “lexical”:

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

What happens here? 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.

lookAhead p parses p without consuming any input.

If p fails and consumes some input, so does lookAhead. Combine with try if this is undesirable.

notFollowedBy p only succeeds when parser p fails. This parser does not consume any input and can be used to implement the “longest match” rule.

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

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

This parser only succeeds at the end of the input.

The parser token nextPos testTok accepts a token t with result x when the function testTok t returns Right x. The position of the next token should be returned when nextPos is called with the tab width, current source position, and the current token.

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

char c = token updatePosChar testChar
  where testChar x = if x == c
                     then Right x
                     else Left . pure . Unexpected . showToken $ x

The parser tokens posFromTok test parses list of tokens and returns it. posFromTok is called with three arguments: tab width, initial position, and collection of tokens to parse. The resulting parser will use showToken to pretty-print the collection of tokens in error messages. Supplied predicate test is used to check equality of given and parsed tokens.

This can be used for example to write string:

string = tokens updatePosString (==)

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 new feature does not affect performance in any way.

between open close p parses open, followed by p and close. Returns the value returned by p.

braces = between (symbol "{") (symbol "}")

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.

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.

count' m n p parses from m to n occurrences of p. If n is not positive or m > n, the parser equals to return []. Returns a list of parsed values.

Please note that m may be negative, in this case effect is the same as if it were equal to zero.

Combine two alternatives.

Since: 4.4.0

endBy p sep parses zero or more occurrences of p, separated and ended by sep. Returns a list of values returned by p.

cStatements = cStatement `endBy` semicolon

endBy1 p sep parses one or more occurrences of p, separated and ended by sep. Returns a list of values returned by p.

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 (string "-->")

someTill p end works similarly to manyTill p end, but p should succeed at least once.

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 <$> digitChar)

sepBy p sep parses zero or more occurrences of p, separated by sep. Returns a list of values returned by p.

commaSep p = p `sepBy` comma

sepBy1 p sep parses one or more occurrences of p, separated by sep. Returns a list of values returned by p.

sepEndBy p sep parses zero or more occurrences of p, separated and optionally ended by sep. Returns a list of values returned by p.

sepEndBy1 p sep parses one or more occurrences of p, separated and optionally ended by sep. Returns a list of values returned by p.

skipMany p applies the parser p zero or more times, skipping its result.

space = skipMany spaceChar

skipSome p applies the parser p one or more times, skipping its result.

Parses a newline character.

Parses a carriage return character followed by a newline character. Returns sequence of characters parsed.

Parses a CRLF (see crlf) or LF (see newline) end of line. Returns the sequence of characters parsed.

eol = (pure <$> newline) <|> crlf

Parses a tab character.

Skips zero or more white space characters.

See also: skipMany and spaceChar.

Parses control characters, which are the non-printing characters of the Latin-1 subset of Unicode.

Parses a Unicode space character, and the control characters: tab, newline, carriage return, form feed, and vertical tab.

Parses an upper-case or title-case alphabetic Unicode character. Title case is used by a small number of letter ligatures like the single-character form of Lj.

Parses a lower-case alphabetic Unicode character.

Parses alphabetic Unicode characters: lower-case, upper-case and title-case letters, plus letters of case-less scripts and modifiers letters.

Parses alphabetic or numeric digit Unicode characters.

Note that numeric digits outside the ASCII range are parsed by this parser but not by digitChar. Such digits may be part of identifiers but are not used by the printer and reader to represent numbers.

Parses printable Unicode characters: letters, numbers, marks, punctuation, symbols and spaces.

Parses an ASCII digit, i.e between “0” and “9”.

Parses an octal digit, i.e. between “0” and “7”.

Parses a hexadecimal digit, i.e. between “0” and “9”, or “a” and “f”, or “A” and “F”.

Parses Unicode mark characters, for example accents and the like, which combine with preceding characters.

Parses Unicode numeric characters, including digits from various scripts, Roman numerals, et cetera.

Parses Unicode punctuation characters, including various kinds of connectors, brackets and quotes.

Parses Unicode symbol characters, including mathematical and currency symbols.

Parses Unicode space and separator characters.

Parses a character from the first 128 characters of the Unicode character set, corresponding to the ASCII character set.

Parses a character from the first 256 characters of the Unicode character set, corresponding to the ISO 8859-1 (Latin-1) character set.

charCategory cat Parses character in Unicode General Category cat, see GeneralCategory.

char c parses a single character c.

semicolon = char ';'

The same as char but case-insensitive. This parser returns actually parsed character preserving its case.

>>> parseTest (char' 'e') "E"
'E'
>>> parseTest (char' 'e') "G"
1:1:
unexpected 'G'
expecting 'E' or 'e'

This parser succeeds for any character. Returns the parsed character.

oneOf cs succeeds if the current character is in the supplied list of characters cs. Returns the parsed character. Note that this parser doesn't automatically generate “expected” component of error message, so usually you should label it manually with label or (<?>).

See also: satisfy.

digit = oneOf ['0'..'9'] <?> "digit"

The same as oneOf, but case-insensitive. Returns the parsed character preserving its case.

vowel = oneOf' "aeiou" <?> "vowel"

As the dual of oneOf, noneOf cs succeeds if the current character not in the supplied list of characters cs. Returns the parsed character.

The same as noneOf, but case-insensitive.

consonant = noneOf' "aeiou" <?> "consonant"

The parser satisfy f succeeds for any character for which the supplied function f returns True. Returns the character that is actually parsed.

digitChar = satisfy isDigit <?> "digit"
oneOf cs  = satisfy (`elem` cs)

string s parses a sequence of characters given by s. Returns the parsed string (i.e. s).

divOrMod = string "div" <|> string "mod"

The same as string, but case-insensitive. On success returns string cased as actually parsed input.

>>> parseTest (string' "foobar") "foObAr"
"foObAr"

This data type represents parse error messages.

Extract the message string from an error message.

Test if message string is empty.

The data type ParseError represents parse errors. It provides the source position (SourcePos) of the error and a list of error messages (Message).

Extract the source position from ParseError.

Extract the list of error messages from ParseError.

Test whether given ParseError has associated collection of error messages. Return True if it has none and False otherwise.

The abstract data type SourcePos represents source positions. It contains the name of the source (i.e. file name), a line number and a column number. SourcePos is an instance of the Show, Eq and Ord class.

Extract the name of the source from a source position.

Extract the line number from a source position.

Extract the column number from a source position.

An instance of Stream s t has stream type s, and token type t determined by the stream.

StorableStream abstracts ability of some streams to be stored in a file. This is used by the polymorphic function parseFromFile.

This is Megaparsec state, it's parametrized over stream type s.

Returns the current input.

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

Returns the current source position.

See also: SourcePos.

setPosition pos sets the current source position to pos.

Returns tab width. Default tab width is equal to defaultTabWidth. You can set different tab width with help of setTabWidth.

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

Returns the full parser state as a State record.

setParserState st set the full parser state to st.

updateParserState f applies function f to the parser state.