FlatParse.Basic.Base

Basic parser building blocks.

Bytewise

eof :: ParserT st e ()

Succeed if the input is empty.

take :: Int -> ParserT st e ByteString

Read the given number of bytes as a ByteString.

Throws a runtime error if given a negative integer.

take# :: Int# -> ParserT st e ByteString

Read n# bytes as a ByteString. Fails if fewer than n# bytes are available.

Throws a runtime error if given a negative integer.

takeUnsafe# :: Int# -> ParserT st e ByteString

Read n# bytes as a ByteString. Fails if fewer than n# bytes are available.

Undefined behaviour if given a negative integer.

takeRest :: ParserT st e ByteString

Consume the rest of the input. May return the empty bytestring.

skip :: Int -> ParserT st e ()

Skip forward n bytes. Fails if fewer than n bytes are available.

Throws a runtime error if given a negative integer.

skip# :: Int# -> ParserT st e ()

Skip forward n# bytes. Fails if fewer than n# bytes are available.

Throws a runtime error if given a negative integer.

skipBack :: Int -> ParserT st e ()

Go back i bytes in the input. Takes a positive integer.

Extremely unsafe. Makes no checks. Almost certainly a Bad Idea.

skipBack# :: Int# -> ParserT st e ()

Go back n# bytes. Takes a positive integer.

Extremely unsafe. Makes no checks. Almost certainly a Bad Idea.

atSkip# :: Int# -> ParserT st e a -> ParserT st e a

Skip forward n# bytes and run the given parser. Fails if fewer than n# bytes are available.

Throws a runtime error if given a negative integer.

atSkipUnsafe# :: Int# -> ParserT st e r -> ParserT st e r

Skip forward n bytes and run the given parser. Fails if fewer than n bytes are available.

Undefined behaviour if given a negative integer.

Combinators

branch :: ParserT st e a -> ParserT st e b -> ParserT st e b -> ParserT st e b

Branch on a parser: if the first argument succeeds, continue with the second, else with the third. This can produce slightly more efficient code than (<|>). Moreover, branch does not backtrack from the true/false cases.

notFollowedBy :: ParserT st e a -> ParserT st e b -> ParserT st e a

Succeed if the first parser succeeds and the second one fails.

chainl :: (b -> a -> b) -> ParserT st e b -> ParserT st e a -> ParserT st e b

An analogue of the list foldl function: first parse a b, then parse zero or more a-s, and combine the results in a left-nested way by the b -> a -> b function. Note: this is not the usual chainl function from the parsec libraries!

chainr :: (a -> b -> b) -> ParserT st e a -> ParserT st e b -> ParserT st e b

An analogue of the list foldr function: parse zero or more a-s, terminated by a b, and combine the results in a right-nested way using the a -> b -> b function. Note: this is not the usual chainr function from the parsec libraries!

lookahead :: ParserT st e a -> ParserT st e a

Save the parsing state, then run a parser, then restore the state.

ensure :: Int -> ParserT st e ()

Assert that there are at least n bytes remaining.

Undefined behaviour if given a negative integer.

ensure# :: Int# -> ParserT st e ()

Assert that there are at least n# bytes remaining.

Undefined behaviour if given a negative integer.

withEnsure :: Int -> ParserT st e r -> ParserT st e r

Assert that there are at least n# bytes remaining (CPS).

Undefined behaviour if given a negative integer.

withEnsure1 :: ParserT st e r -> ParserT st e r

Assert that there is at least 1 byte remaining (CPS).

Undefined behaviour if given a negative integer.

withEnsure# :: Int# -> ParserT st e r -> ParserT st e r

Assert that there are at least n# bytes remaining (CPS).

Undefined behaviour if given a negative integer.

isolate :: Int -> ParserT st e a -> ParserT st e a

isolate n p runs the parser p isolated to the next n bytes. All isolated bytes must be consumed.

Throws a runtime error if given a negative integer.

isolate# :: Int# -> ParserT st e a -> ParserT st e a

isolate# n# p runs the parser p isolated to the next n# bytes. All isolated bytes must be consumed.

Throws a runtime error if given a negative integer.

isolateUnsafe# :: Int# -> ParserT st e a -> ParserT st e a

isolateUnsafe# n# p runs the parser p isolated to the next n# bytes. All isolated bytes must be consumed.

Undefined behaviour if given a negative integer.

Non-specific (TODO)

skipMany :: ParserT st e a -> ParserT st e ()

Skip a parser zero or more times.

skipSome :: ParserT st e a -> ParserT st e ()

Skip a parser one or more times.

Errors and failures

failed :: ParserT st e a

The failing parser. By default, parser choice (<|>) arbitrarily backtracks on parser failure.

try :: ParserT st e a -> ParserT st e a

Convert a parsing error into failure.

err :: e -> ParserT st e a

Throw a parsing error. By default, parser choice (<|>) can't backtrack on parser error. Use try to convert an error to a recoverable failure.

fails :: ParserT st e a -> ParserT st e ()

Convert a parsing failure to a success.

cut :: ParserT st e a -> e -> ParserT st e a

Convert a parsing failure to an error.

cutting :: ParserT st e a -> e -> (e -> e -> e) -> ParserT st e a

Run the parser, if we get a failure, throw the given error, but if we get an error, merge the inner and the newly given errors using the e -> e -> e function. This can be useful for implementing parsing errors which may propagate hints or accummulate contextual information.

optional :: ParserT st e a -> ParserT st e (Maybe a)

Convert a parsing failure to a Maybe. If possible, use withOption instead.

optional_ :: ParserT st e a -> ParserT st e ()

Convert a parsing failure to a ().

withOption :: ParserT st e a -> (a -> ParserT st e r) -> ParserT st e r -> ParserT st e r

CPS'd version of optional. This is usually more efficient, since it gets rid of the extra Maybe allocation.