asai 0.1.1 · OCaml Package

Locations and spans.

Types

type position = {

file_path : string;
(*
The absolute file path of the file that contains the position.
*)
offset : int;
(*
The 0-indexed byte offset of the position relative to the beginning of the file.
*)
start_of_line : int;
(*
The 0-indexed byte offset pointing to the start of the line that contains the position.
*)
line_num : int;
(*
The 1-indexed line number of the line that contains the position.
*)

}

The type of positions; this is isomorphic to Lexing.position, but with arguably better field names.

type t

The abstract type of spans.

type 'a located = {

loc : t option;
value : 'a;

}

An auxiliary type to package data with an optional span.

Spans

val make : (position * position) -> t

make (beginning, ending) builds the span [begining, ending) (not including the byte at the ending position) from a pair of positions beginning and ending.

raises Invalid_argument
if the positions do not share the same file path or if end_ comes before begin_. (It is okay if end_ equals to begin_, which means the span is empty.) The comparison of file paths is done by String.equal without any path normalization.

val split : t -> position * position

split span returning the pair of the beginning and ending positions of span. It is the right inverse of make.

val file_path : t -> string

file_path span returns the file path associated with span.

val begin_line_num : t -> int

begin_line_num span returns the 1-indexed line number of the beginning position.

val end_line_num : t -> int

end_line_num span returns the 1-indexed line number of the ending position.

val begin_offset : t -> int

begin_offset span returns the 0-indexed offset of the (inclusive) beginning position.

val end_offset : t -> int

end_offset span returns the 0-indexed offset of the (exclusive) ending position.

val locate_opt : t option -> 'a -> 'a located

locate_opt sp v is {loc = sp; value = v}.

val locate : t -> 'a -> 'a located

locate sp v is {loc = Some sp; value = v}.

Support of Lexing

val of_lex_position : Stdlib.Lexing.position -> position

of_lex_position pos converts an OCaml lexer position pos of type Lexing.position into a position. The input pos must be byte-indexed. (Therefore, the OCaml tool ocamllex is compatible, but the OCaml library sedlex is not because it uses Unicode code points.)

val of_lex_span : (Stdlib.Lexing.position * Stdlib.Lexing.position) -> t

of_lex_span (begining, ending) takes a pair of OCaml lexer positions and creates a span. It is make (of_lex_position begining, of_lex_position ending).

val of_lexbuf : Stdlib.Lexing.lexbuf -> t

of_lexbuf lexbuf constructs a span from the current lexeme that lexbuf points to. It is of_lex_span (Lexing.lexeme_start_p lexbuf, Lexing.lexeme_end_p lexbuf).

val locate_lex : 
  (Stdlib.Lexing.position * Stdlib.Lexing.position) ->
  'a ->
  'a located

locate_lex ps v is a helper function to create a value annotated with a span. It is locate (Some (of_lex_span ps)) v and is designed to work with the OCaml parser generator Menhir. You can add the following code to your Menhir grammar to generate annotated data:

%inline
locate(X):
  | e = X
    { Asai.Span.locate_lex $loc e }

package asai

Types

Spans

Support of Lexing