package fmlib

'a t Type of a parse combinator returning an 'a.

p >>= f

Parse first the input according to the combinator p. In case of success, feed the returned value of p into the function f to get the combinator to parse next.

let* x = p in f x is equivalent to p >>= f

The let* combinator let us express parsing sequences conveniently. Example:

let* x = p in       (* parse [p], result [x] in case of success. *)
let* y = q x in     (* parse [q x], result [y] ... *)
let* z = r x y in   (* ... *)
...
return f x y z ...

The wildcard let* _ = ... can be used to ignore results of intermediate parsing steps.

map f p

Try combinator p. In case of success, map the returned value x to f x. In case of failure, do nothing.

map f p is equivalent to let* x = p in return (f x).

succeed a

Succeed immediately without consuming token. Return object a as result.

return a is equivalent to succeed a.

unexpected expect triggers a syntax error signalling the expectation expect.

clear_last_expectation p Clear last failed expectation.

This is useful e.g. after stripping whitespace. Since stripping whitespace means skip_one_or_more ws or skip_zero_or_more ws, after skipping whitespace the parser can still expect more whitespace. Therefore there is a failed expectation *whitespace* on the stack. However you rarely want this expectation to be reported.

fail error triggers a semantic error.

p </> q

Try first combinator p. In case of success or failure with consumed token, p </> q is equivalent to p.

If p fails without consuming token, then p </> q is equivalent to q.

choices p [q r t ...] is equivalent to p </> q </> r </> t </> ....

p <?> expect

Try combinator p. In case of success or failure with consumed token, p <?> expect is equivalent to p.

If p fails without consuming token, then the failed expectations are replaced with the failed expectation expect.

Usually p is a combinator implementing a choice between various alternatives of a grammar construct. The <?> combinator allows to replace the set of failed grammar alternatives with a higher abstraction of the failed expectation. E.g. instead of getting the failed expectations identifier, '(', -, ... we can get the failed expectation expression.

Get the current user state.

update f Update the user state using f.

get_and_update f Get the current user state and then update the user state. The returned value is the old state.

optional p

Try combinator p.

• Success: Return Some a where a is the returned value.
• Failure without consuming token: Return None
• Failure with consuming token: Remain in the error state.

zero_or_more start f p

Try the combinator p as often as possible. Return start if p fails without consuming token. As long as p succeeds use f to accumulate the results.

The first time p fails without consuming token, return the accumulated result.

If p fails by consuming token, then zero_or_more f p fails with the same error.

one_or_more first next p

one_or_more first next p is equivalent to

let* x = p in
zero_or_more (first x) next p

list_zero_or_more p Parse zero or more occurrences of p and returned the collected result in a list.

list_zero_or_more p Parse one or more occurrences of p and returned the collected results as a pair of the first value and a list of the remaining values.

skip_zero_or_more p Parse zero or more occurrences of p, ignore the result and return the number of occurrences.

skip_one_or_more p Parse one or more occurrences of p, ignore the result and return the number of occurrences.

one_or_more_separated first next p sep

Parse one or more occurrences of p separated by sep. Use first to convert the first occurrence of p into the result and use next to accumulate the results.

backtrack p expect

Try the combinator p. In case of failure with consuming token, push the consumed token back to the lookahead and let it fail without consuming token. Use expect to record the failed expectation.

Backtracking reduces the performance, because the token pushed back to the lookahead have to be parsed again. Try to avoid backtracking whenever possible.

followed_by p expect

Parses p and backtracks (i.e. all tokens of p will be pushed back to the lookahead). In case p succeeds, the followed_by parser succeeds without consuming token. Otherwise it fails without consuming tokens.

not_followed_by p expect

Parses p and backtracks (i.e. all tokens of p will be pushed back to the lookahead). In case p succeeds, the not_followed_by parser fails without consuming token. Otherwise it succeeds without consuming tokens.