Library
Module
Module type
Parameter
Class
Class type
State
: User state.Final
: Final result type of the parser.Semantic
: Semantic error message (triggered by fail error
)module State : Fmlib_std.Interfaces.ANY
module Final : Fmlib_std.Interfaces.ANY
module Semantic : Fmlib_std.Interfaces.ANY
module Parser : sig ... end
include Interfaces.COMBINATOR
with type state = State.t
and type expect = string
and type semantic = Semantic.t
type state = State.t
type semantic = Semantic.t
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)
.
val succeed : 'a -> 'a t
succeed a
Succeed immediately without consuming token. Return object a
as result.
val return : 'a -> 'a t
return a
is equivalent to succeed a
.
unexpected expect
triggers a syntax error signalling the expectation expect
.
val clear_last_expectation : 'a -> 'a t
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.
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_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
.
Some a
where a
is the returned value.None
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.
val one_or_more_separated :
('item -> 'r) ->
('r -> 'sep -> 'item -> 'r) ->
'item t ->
'sep t ->
'r t
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.
followed_by
and not_followed_by
can be used to peek into the token stream without consuming token.
located p
Parse p
and return its result with its start and end position.
Note: If p
parses strips whitespace at the end, the returned end position is at the end of the whitespace. This is not what you usually want. Therefore first parse the essential part located and then strip the whitespace.
indent i p
Indent p
by i
columns relative to its parent.
Precondition: 0 <= i
align p
Set the indentation set of p
to {col}
where col
is the column position of its first character. Fail, if col
is not in the indentation set.
left_align p
Set the indentation set of p
to {col}
where col
is the column position of its first character. Fail, if col
is not the lower bound of the indentation set. I.e. p
is left aligned in its indentation set.
zero_or_more_aligned start next p
Parse an indented block of zero or more aligned constructs p
.
Equivalent to
zero_or_more start next (align p) |> align |> indent 1
zero_or_more_aligned first next p
Parse an indented block of one or more aligned constructs p
.
Equivalent to
one_or_more first next (align p) |> align |> indent 1
val charp : (char -> bool) -> string -> char t
charp p expect
Parse a character which satisfies the predicate p
.
In case of failure, report the failed expectation expect
.
val range : char -> char -> char t
range c1 c2
Parses a charager in the range between c1
and c2
, i.e. a character c
which satisfies c1 <= c && c <= c2
.
val char : char -> char t
char c
Parse the character c
.
one_of_chars str expect
Parse one of the characters in the string str
. In case of failure, report the failed expectation expect
.
val string : string -> string t
string str
Parse the string str
.
val uppercase_letter : char t
Parse an uppercase letter.
val lowercase_letter : char t
Parse a lowercase letter.
val letter : char t
Parse a letter.
val digit : int t
Parse a digit.
val hex_uppercase : int t
Equivalent to range 'A' 'F'
and then converted to the corresponding number between 10
and 15
.
val hex_lowercase : int t
Equivalent to range 'a' 'f'
and then converted to the corresponding number between 10
and 15
.
val hex_digit : int t
Parse a hexadecimal digit and return the corresponding number between 0
and 15
.
val base64 : (string -> 'r) -> (string -> 'r -> 'r) -> 'r t
base64 start next
Parse a base64 encoding into an object of type 'r
.
A base64 encoding is a sequence of zero or more base64 characters (A-Za-z0-9+/) grouped into sequences of 4 characters and optionally padded with the character =
. Each group of 2-4 base64 characters are decoded into a string of 1-3 bytes.
start
gets the first 1-3 bytes and next
gets all subsequent 1-3 bytes until the end of the encoding is reached.
val string_of_base64 : string t
Parse a base64 encoding and decode it into a string.
make state p
Make a parser which starts in state state
and parses a construct defined by the combinator p
. The token stream must be ended by put_end
, otherwise the parse won't succeed.
val make_parser : Position.t -> State.t -> Final.t t -> Parser.t
make_parser pos state p
Make a parser which starts at position pos
and state state
and parses a construct defined by the combinator p
. The parser can succeed even if no end token is pushed into the parser.