Common (mra_bi_assembler.Lang.Common)

Basic definitions

Parseable structures

type parseable =

| Bind of bind
(*
A subparser, binding its result into the associated name. See bind.
*)
| Or of parseable list
(*
A choice between a given list of alternatives. Backtracking occurs within a single Or pattern.
*)
| Seq of parseable list
(*
A sequential composition of the given parseables.
*)
| Lit of string
(*
A literal string.
*)
| Space
(*
Zero or more within-line space characters (space or tab).
*)
| Return of string
(*
A parser that always succeeds, returning the given string. Consumes no input.
*)
| Digits
(*
One or more decimal digits (without sign characters).
*)
| Eof
(*
A parser that succeeds only at the end of the text.
*)

A parseable structure.

The syntax allowed is intentionally very restrictive, to allow for tractable analysis and manipulation. Grammars definable by this structure will have no unbounded repetition and no context-sensitivity. This makes it less powerful, even, than the regular languages.

and bind = {

name : string;
syntax : parseable;

}

A parseable and a name.

When parsed, associates the parse result of syntax with name. This is used to extract interesting information from the parseable, particularly in the case of Or parsers.

module StringSet : sig ... end

module StringMap : sig ... end

val quote : string -> string

Places double quotes around the given string.

Output type

type output = {

output : string list;

}

Currently, all parseables will produce string list when parsed. This explicit type helps avoid confusion with other lists, especially in the case of an output list.

Functions on output objects.

include sig ... end

val get_output : output -> string list

val equal_output : output -> output -> bool

val show_output : output -> string

val compare_output : output -> output -> int

val output : string list -> output

val output_str : string -> output

val output_append : string list -> string list -> output

val output_concat : output list -> output

Bindings type

type bindings = output list StringMap.t

Bindings are the results of subtrees named by bind values.

These are returned as a map alongside the main result. A binding name may be bound multiple times if its bind name appears and is matched more than once. Within an output list, outputs are ordered in the order they appear in the parseable.

Functions on bindings objects. These must be used instead of the normal map functions to maintain the semantics of bindings as a list of parse outputs.

include sig ... end

val binding : StringMap.key -> output -> bindings

val bindings_add : string -> output -> bindings -> bindings

Adds a new output to the given binding name. The new output is added to the front of the output list.

val bindings_merge : bindings -> bindings -> bindings

Merges two binding maps, with the interpretation that the left bindings were parsed before the right bindings - not commutative!

val bindings_pop : string -> bindings -> output * bindings

Pops one output associated to given name from the bindings. Returns the output and the modified bindings map.

raises Stdlib.Not_found
if the name is not bound or has no outputs remaining.

val bindings_compare : bindings -> bindings -> int

Partial order on bindings, comparing two bindings by the number of outputs they contain.

A bindings map b1 is less than or equal to b2 if: for every entry (k,v1) in b1, b2 has a mapping for k and v1 is a suffix of f2(k). For the purpose of this comparison, a mapping to the empty list is treated as if no mapping was present.

raises Stdlib.Failure
if the two bindings are incomparable (neither is less than or equal to the other)

val bindings_equal : bindings -> bindings -> bool

val bindings_empty : bindings

val bindings_is_empty : bindings -> bool

Derived functions

Automatically-generated functions for parseable and bind.

include sig ... end

val pp_parseable : Stdlib.Format.formatter -> Lang__.Types.parseable -> unit

val show_parseable : Lang__.Types.parseable -> string

val pp_bind : Stdlib.Format.formatter -> Lang__.Types.bind -> unit

val show_bind : Lang__.Types.bind -> string

val equal_parseable : Lang__.Types.parseable -> Lang__.Types.parseable -> bool

val equal_bind : Lang__.Types.bind -> Lang__.Types.bind -> bool

val compare_parseable : Lang__.Types.parseable -> Lang__.Types.parseable -> int

val compare_bind : Lang__.Types.bind -> Lang__.Types.bind -> int

val parseable_to_yojson : Lang__.Types.parseable -> Yojson.Safe.t

val parseable_of_yojson : 
  Yojson.Safe.t ->
  Lang__.Types.parseable Ppx_deriving_yojson_runtime.error_or

val bind_to_yojson : Lang__.Types.bind -> Yojson.Safe.t

val bind_of_yojson : 
  Yojson.Safe.t ->
  Lang__.Types.bind Ppx_deriving_yojson_runtime.error_or

Combinators

val literals : string list -> parseable

Creates a parseable which accepts any of the given strings.

Note: the parser will re-order literals to be longest first, to avoid problems when one alternative is a prefix of another.

val eof : parseable

val just : parseable -> parseable

val empty : parseable

A parser that always succeeds, consumes no input (abbreviation for Seq []).

val fail : parseable

A parser that always fails (abbreviation for Or []).

val optional : parseable -> parseable

A parser that accepts the given parser or the empty string.

val bind : string -> parseable -> parseable

The constructor for Bind in function form.

val bracketed : ?l:parseable -> ?r:parseable -> parseable -> parseable

Parses the given parser in between the given l and r delimiters. Delimeters default to open- and close- square brackets.

val parseable_append : parseable -> parseable -> parseable

Returns a parser which sequences the two parsers. Performs minor optimisation when one or both of its arguments is Seq, fusing them together if possible.

val repeat : min:int -> max:int -> parseable -> parseable

Repetition combinator, accepting repetitions of p at least min and at most max times (both inclusive). Requires both bounds be non-negative.

Printing functions

val describe_parseable : parseable -> string

Produces a human-readable description of the given parseable.

For example,

describe_parseable @@ optional (Or [Lit "a"; Lit "b"])

produces ("a" | "b")?.

val show : (Stdlib.Format.formatter -> 'a -> unit) -> 'a -> string

Given a Format-style pp function, converts it to a simple function returning a string.

val show_string_list : string list -> string

Shows a list of strings.

val show_list : ('a -> string) -> 'a list -> string

Shows a list of arbitrary objects.

val show_stringmap : ('a -> string) -> 'a StringMap.t -> string

Shows a string map.

val show_bindings : output list StringMap.t -> string

Shows a map of binding values.

val show_parse_output : (output * output list StringMap.t) -> string

Shows a pair of output and bindings, as produced by the parser.

val show_parse_result : 
  (output * output list StringMap.t, string) result ->
  string

Shows the result of running a parseable through Angstrom.

val show_result : ('a -> string) -> ('a, string) result -> string