Text.Megaparsec

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> finalLeft "it failed"

>>> runExcept $ optional canFail *> finalRight 42

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.

choice = asum

Combine two alternatives.

eitherP a b = (Left <$> a) <|> (Right <$> b)

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

option x p = p <|> pure x

See also: optional.

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.

See also: skipCount, count'.

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.

See also: skipCount, count.

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.

many p applies the parser p zero or more times and returns a list of the values returned by p.

identifier = (:) <$> letter <*> many (alphaNumChar <|> char '_')

manyTill p end applies parser p zero or more times until parser end succeeds. Returns the list of values returned by p. Note that end result is consumed and lost. Use manyTill_ if you wish to keep it.

See also: skipMany, skipManyTill.

manyTill_ p end applies parser p zero or more times until parser end succeeds. Returns the list of values returned by p and the end result. Use manyTill if you have no need in the result of the end.

See also: skipMany, skipManyTill.

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.

skipCount n p parses n occurrences of p, skipping its result. If n is smaller or equal to zero, the parser equals to return ().

See also: count, count'.

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

See also: manyTill, skipManyTill.

skipManyTill p end applies the parser p zero or more times skipping results until parser end succeeds. Result parsed by end is then returned.

See also: manyTill, skipMany.

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

See also: someTill, skipSomeTill.

skipSomeTill p end applies the parser p one or more times skipping results until parser end succeeds. Result parsed by end is then returned.

See also: someTill, skipSome.

some p applies the parser p one or more times and returns a list of the values returned by p.

word = some letter

someTill p end works similarly to manyTill p end, but p should succeed at least once. Note that end result is consumed and lost. Use someTill_ if you wish to keep it.

someTill p end = liftM2 (:) p (manyTill p end)

See also: skipSome, skipSomeTill.

someTill_ p end works similarly to manyTill_ p end, but p should succeed at least once. Use someTill if you have no need in the result of the end.

See also: skipSome, skipSomeTill.

An associative binary operation

The identity of <|>

empty <|> a     == a
a     <|> empty == a

This is Megaparsec's state, parametrized over the stream type s and the custom error component type e.

A special kind of state that is used to calculate line/column positions on demand.

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

ParsecT e s m a is a parser with custom error data component e, stream type s, underlying monad m, and return type 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 ParseErrorBundle (Left) or a value of type a (Right). errorBundlePretty can be used to turn ParseErrorBundle 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 bundle -> putStr (errorBundlePretty bundle)
         Right xs -> print (sum xs)

numbers = decimal `sepBy` char ','

parse is the same as runParser.

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 names) are not important and the entire input should be consumed. For example, it can be used for parsing a single number according to a specification of its format.

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

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

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

runParser is the same as parse.

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

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 ParseErrorBundle (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.

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

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

Stop parsing and report a trivial ParseError.

Stop parsing and report a fancy ParseError. To report a single custom parse error, see customFailure.

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

unexpected item = failure (Just item) Set.empty

Report a custom parse error. For a more general version, see fancyFailure.

customFailure = fancyFailure . Set.singleton . ErrorCustom

Specify how to process ParseErrors that happen inside of this wrapper. This applies to both normal and delayed ParseErrors.

As a side effect of the implementation, the inner computation will start with an empty collection of delayed errors, and they will be updated and “restored” on the way out of region.

Register a ParseError for later reporting. This action does not end parsing and has no effect except for adding the given ParseError to the collection of “delayed” ParseErrors which will be taken into consideration at the end of parsing. Only if this collection is empty will the parser succeed. This is the main way to report several parse errors at once.

Like failure, but for delayed ParseErrors.

Like fancyFailure, but for delayed ParseErrors.

single t only matches the single token t.

semicolon = single ';'

See also: token, anySingle, char, char.

The parser satisfy f succeeds for any token for which the supplied function f returns True.

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

Performance note: when you need to parse a single token, it is often a good idea to use satisfy with the right predicate function instead of creating a complex parser using the combinators.

See also: anySingle, anySingleBut, oneOf, noneOf.

Parse and return a single token. It's a good idea to attach a label to this parser.

anySingle = satisfy (const True)

See also: satisfy, anySingleBut.

Match any token but the given one. It's a good idea to attach a label to this parser.

anySingleBut t = satisfy (/= t)

See also: single, anySingle, satisfy.

oneOf ts succeeds if the current token is in the supplied collection of tokens ts. Returns the parsed token. Note that this parser cannot automatically generate the “expected” component of error message, so usually you should label it manually with label or (<?>).

oneOf cs = satisfy (`elem` cs)

See also: satisfy.

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

Performance note: prefer satisfy when you can because it's faster when you have only a couple of tokens to compare to:

quoteFast = satisfy (\x -> x == '\'' || x == '\"')
quoteSlow = oneOf "'\""

As the dual of oneOf, noneOf ts succeeds if the current token is not in the supplied list of tokens ts. Returns the parsed character. Note that this parser cannot automatically generate the “expected” component of error message, so usually you should label it manually with label or (<?>).

noneOf cs = satisfy (`notElem` cs)

See also: satisfy.

Performance note: prefer satisfy and anySingleBut when you can because it's faster.

chunk chk only matches the chunk chk.

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

See also: tokens, string, Text.Megaparsec.Byte.string.

A synonym for label in the form of an operator.

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

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

takeRest = takeWhileP Nothing (const True)

Return True when end of input has been reached.

atEnd = option False (True <$ hidden eof)

Return the current input.

setInput input continues parsing with input.

Return the current source position. This function is not cheap, so do not call it, e.g., on matching of every token—that's a bad idea. Still, you can use it to get a SourcePos to attach to things that you parse.

The function works under the assumption that we move in the input stream only forwards and never backwards, which is always true unless the user abuses the library.

Get the number of tokens processed so far.

See also: setOffset.

Set the number of tokens processed so far.

See also: getOffset.

setParserState st sets the parser state to st.

See also: getParserState, updateParserState.