Parser (beluga.Beluga_parser.Common

type token = Located_token.t

type location = Beluga_syntax.Location.t

type state

type 'a t = state -> state * ('a, exn) Stdlib.result

type 'a parser = 'a t

exception Parser_error of exn

exception Labelled_exception of {

label : string;
cause : exn;

}

exception No_more_choices of exn list

exception Expected_end_of_input

include Support.Monad.MONAD with type 'a t := 'a t

val return : 'a -> 'a t

return a injects a into the monadic type.

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

bind f a is the sequential composition of two actions, passing any value produced by a as argument to f.

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

Operator alias of bind.

val compose : ('b -> 'c t) -> ('a -> 'b t) -> 'a -> 'c t

compose g f is the Kleisli composition of f and g, passing the input to f, then binding the output to g.

val (>=>) : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

Operator alias of compose.

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

( let* ) ma f is bind f ma. This is a binding operator, and it is used as let* a = ma in f a.

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

( and* ) ma mb is let* a = ma in let* b = mb in return (a, b). This is a binding operator, and it is used as let* a = ma and* b = mb in ....

include Support.Functor.FUNCTOR with type 'a t := 'a t

Combinators

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

map f is the function that maps values of t by f. The order of arguments is for use in function pipelines as fb = fa |> map (fun a -> (* ... *)).

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

( $> ) is an infix synonym for map.

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

( let+ ) ma f is map f a. This is a binding operator, and is used as let+ a = ma in f a

val (and+) : 'a t -> 'b t -> ('a * 'b) t

( and+ ) ma mb is let+ a = ma in let+ b = mb in return (a, b). This is a binding operator, and it is used as let+ a = ma and+ b = mb in ....

include Support.Apply.APPLY with type 'a t := 'a t

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

ap fa fab applies argument fa to fab under the abstract datatype t.

val (<&>) : ('a -> 'b) t -> 'a t -> 'b t

( <&> ) is an infix synonym of ap.

Combinators

val ap_first : 'b t -> 'a t -> 'a t

ap_first second first combines actions first and second but keeps only first. That is, ap_first second first = first. The order of arguments is for use in function pipelines as first = first |> ap_first second.

val (<&) : 'a t -> 'b t -> 'a t

( <& ) is an infix synonym for ap_first.

val ap_second : 'b t -> 'a t -> 'b t

ap_second second first combines actions first and second but keeps only second. That is, ap_second second first = second. The order of arguments is for use in function pipelines as second = first |> ap_second second.

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

( &> ) is an infix synonym for ap_second.

val seq2 : 'a1 t -> 'a2 t -> ('a1 * 'a2) t

seq2 fa1 fa2 sequentially executes actions fa1 and fa2, and keeps their outputs under the abstract datatype t.

val seq3 : 'a1 t -> 'a2 t -> 'a3 t -> ('a1 * 'a2 * 'a3) t

seq3 fa1 fa2 fa3 sequentially executes actions fa1, fa2 and fa3, and keeps their outputs under the abstract datatype t.

val seq4 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> ('a1 * 'a2 * 'a3 * 'a4) t

seq4 fa1 fa2 fa3 fa4 sequentially executes actions fa1, fa2, fa3 and fa4, and keeps their outputs under the abstract datatype t.

val seq5 : 
  'a1 t ->
  'a2 t ->
  'a3 t ->
  'a4 t ->
  'a5 t ->
  ('a1 * 'a2 * 'a3 * 'a4 * 'a5) t

seq5 fa1 fa2 fa3 fa4 fa5 sequentially executes actions fa1, fa2, fa3, fa4 and fa5, and keeps their outputs under the abstract datatype t.

val lift2 : ('a1 -> 'a2 -> 'r) -> 'a1 t -> 'a2 t -> 'r t

lift2 f ma1 ma2 sequentially executes actions ma1, ma2 and passes their outputs to f.

val lift3 : ('a1 -> 'a2 -> 'a3 -> 'r) -> 'a1 t -> 'a2 t -> 'a3 t -> 'r t

lift3 f ma1 ma2 ma3 sequentially executes actions ma1, ma2, ma3 and passes their outputs to f.

val lift4 : 
  ('a1 -> 'a2 -> 'a3 -> 'a4 -> 'r) ->
  'a1 t ->
  'a2 t ->
  'a3 t ->
  'a4 t ->
  'r t

lift4 f ma1 ma2 ma3 ma4 sequentially executes actions ma1, ma2, ma3, ma4 and passes their outputs to f.

val lift5 : 
  ('a1 -> 'a2 -> 'a3 -> 'a4 -> 'a5 -> 'r) ->
  'a1 t ->
  'a2 t ->
  'a3 t ->
  'a4 t ->
  'a5 t ->
  'r t

lift5 f ma1 ma2 ma3 ma4 ma5 sequentially executes actions ma1, ma2, ma3, ma4, ma5 and passes their outputs to f.

val replicate : int -> 'a t -> 'a list t

replicate n a sequentially runs n times a.

raises Invalid_argument
If n < 0.

val run : 'a t -> state -> state * ('a, exn) Stdlib.result

run p state is (state', result) where result is the output of parsing p using state.

This is only meant to be used internally, or when defining new parser combinators, since it does not prune the parser exception when result = Result.Error exn.

The end user of a parser should use run_exn.

val run_exn : 'a t -> state -> state * 'a

run_exn p state is (state', parsed) where parsed is the object parsed from state using p. A pruned exception is raised if p fails.

val eval_exn : 'a t -> state -> 'a

eval_exn p state runs p on state like run_exn, and discards the output parser state. This is used whenever we do not resume parsing from the final parser state, particularly when using the only combinator since we expect the end of the input stream to be reached.

val catch : 
  'a t ->
  ((state * ('a, exn) Stdlib.result) -> state * ('b, exn) Stdlib.result) ->
  'b t

catch p runs p and invokes the given handler to modify the outcome. Despite being called "catch", this parser is actually a kind of map, and is used to implement "low-level" parser transformations.

val fail : exn -> 'a t

fail exn is the parser that always fails with exn.

val fail_at_location : Beluga_syntax.Location.t -> exn -> 'a t

fail_at_location location exn is the parser that always fails with exn annotated with location.

val fail_at_next_location : exn -> 'a t

fail_at_next_location exn is the parser that always fails with exn annotated with the next location in the input stream.

val fail_at_previous_location : exn -> 'a t

fail_at_previous_location exn is the parser that always fails with exn annotated with the previous location in the input stream.

val labelled : string -> 'a t -> 'a t

labelled label p is p' such that when p fails, p' annotates the exception with a label for error-reporting.

val span : 'a t -> (location * 'a) t

span p is the parser p' that additionally returns the source file location that spans the tokens consumed by p.

val only : 'a t -> 'a t

only p is the parser p' that expects p to succeed, then the end of input to be reached immediately after.

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

maybe p is the parser p' that may fail, in which case it returns Option.none.

val void : 'a t -> unit t

void p is the parser p' that discards the result of p.

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

many p is the parser p' that parses tokens following the EBNF grammar p*, meaning that it parses 0 or more occurrences of p.

val some : 'a t -> 'a Support.List1.t t

some p is the parser p' that parses tokens following the EBNF grammar p+, meaning that it parses 1 or more occurrences of p.

val sep_by0 : sep:unit t -> 'a t -> 'a list t

sep_by0 ~sep p is the parser p' that parses tokens following the EBNF grammar [p (sep p)*], meaning that it parses 0 or more occurrences of p separated by sep.

val sep_by1 : sep:unit t -> 'a t -> 'a Support.List1.t t

sep_by1 ~sep p is the parser p' that parses tokens following the EBNF grammar p (sep p)+, meaning that it parses 1 or more occurrences of p separated by sep.

val trying : 'a t -> 'a t

trying p is the parser p' that enables backtracking in the parser state if p fails, which signals that the erroneous state can be backtracked out of irrespective of the number of consumed tokens.

val choice : 'a t Support.List.t -> 'a t

choice ps is the parser p that sequentially tries the parsers in p.

For instance, choice [p1; p2] first runs p1. If it fails, p2 is run if one of the following is true.

p1 failed without consuming any input.
p1 failed with backtracking enabled. Backtracking is enabled by the trying combinator.

val alt : 'a t -> 'a t -> 'a t

alt p1 p2 is choice [p1; p2].

val satisfy : (token option -> ('a, exn) Stdlib.result) -> 'a t

satisfy f is the basic parser p that performs an action based on whether the next token in the stream satisfies the predicate f. The parser is advanced only if the next token satisfies f. If the next token does not satisfy the predicate, then the error is annotated with the next token's location.

val eoi : unit t

eoi is the parser that expects the end of input to be reached. This is either the end of the input string, token stream, or file input channel.

val insert_token : token -> unit t

insert_token token is the parser that inserts token as the next token to be read from the input stream.