fmlib 0.2.0 · OCaml Package

State: User state.
Final: Final result type of the parser.
Semantic: Semantic error message (triggered by fail error)

Parameters

module State : Fmlib_std.Interfaces.ANY

module Final : Fmlib_std.Interfaces.ANY

module Semantic : Fmlib_std.Interfaces.ANY

Signature

Final Parser

module Parser : sig ... end

Generic Combinators

include Interfaces.COMBINATOR
  with type state = State.t
   and type expect = string
   and type semantic = Semantic.t

type state = State.t

type expect = string

type semantic = Semantic.t

Basic Combinators

type _ t

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

val (>>=) : 'a t -> ('a -> 'b t) -> 'b 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.

val let* : 'a t -> ('a -> 'b t) -> 'b t

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.

val map : ('a -> 'b) -> 'a t -> 'b t

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.

val unexpected : expect -> 'a t

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.

val fail : semantic -> 'a t

fail error triggers a semantic error.

val (</>) : 'a t -> 'a t -> 'a t

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.

val choices : 'a t -> 'a t list -> 'a t

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

val (<?>) : 'a t -> expect -> 'a 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.

State Combinators

val get : state t

Get the current user state.

val update : (state -> state) -> unit t

update f Update the user state using f.

val get_and_update : (state -> state) -> state t

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

Convenience Combinators

val optional : 'a t -> 'a option t

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.

val zero_or_more : 'r -> ('item -> 'r -> 'r) -> 'item t -> 'r t

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.

val one_or_more : ('item -> 'r) -> ('item -> 'r -> 'r) -> 'item t -> 'r t

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

val list_zero_or_more : 'a t -> 'a list t

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

val list_one_or_more : 'a t -> ('a * 'a list) t

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.

val skip_zero_or_more : 'a t -> int t

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

val skip_one_or_more : 'a t -> int t

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.

Backtracking

val backtrack : 'a t -> expect -> 'a t

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.

val followed_by : 'a t -> expect -> 'a t

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.

val not_followed_by : 'a t -> expect -> unit t

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.

Location Combinator

val located : 'a t -> 'a Located.t t

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.

Indentation Combinators

val indent : int -> 'a t -> 'a t

indent i p Indent p by i columns relative to its parent.

Precondition: 0 <= i

val align : 'a t -> 'a t

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.

val left_align : 'a t -> 'a t

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.

val detach : 'a t -> 'a t

detach p Parse p without any indentation and alignment restrictions.

val zero_or_more_aligned : 'r -> ('a -> 'r -> 'r) -> 'a t -> 'r t

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

val one_or_more_aligned : ('a -> 'r) -> ('a -> 'r -> 'r) -> 'a t -> 'r t

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

Character Combinators

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.

val one_of_chars : string -> expect -> char t

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 the Final Parser

val make : State.t -> Final.t t -> Parser.t

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.

package fmlib