Module `Loc`Source

A library to manipulate code locations, typically to decorate AST nodes built by parser so as to allow located error messages.

Sourcetype t

An immutable value representing a range of characters in a file.

Dumping locations

Sourceval sexp_of_t : t -> Sexplib0.Sexp.t

By default, locations are hidden and rendered as the Atom "_". Locations are typically brittle, and not always interesting when inspecting the nodes of an AST. You may however set include_sexp_of_locs to true - then sexp_of_t will show actual locations.

Sourceval include_sexp_of_locs : bool ref

By default set to false, this may be temporarily turned to true to inspect locations in the dump of an AST.

Comparing locations

Sourceval equal : t -> t -> bool

equal t1 t2 returns true if t1 and t2 identify the same location. Beware, it is possible to deactivate comparison of locs by setting equal_ignores_locs to true, in which case equal will always return true.

Sourceval equal_ignores_locs : bool ref

By default set to false, this may be temporarily turned to true to operates some comparison that ignores all locations. When this is true, equal returns true for any locs.

Creating locations

Sourceval create : (Lexing.position * Lexing.position) -> t

To be called in the right hand side of a Menhir rule, using the $loc special keyword provided by Menhir. For example:

 ident:
  | ident=IDENT { Loc.create $loc }
 ;

Sourceval of_position : Lexing.position -> t

To be used with a Lexing.position, including for example:

  Loc.of_position [%here]

Sourceval of_pos : (string * int * int * int) -> t

To be used with the __POS__ special construct. For example:

  Loc.of_pos __POS__

Sourceval of_lexbuf : Lexing.lexbuf -> t

Build a location from the current internal state of the lexbuf.

Sourceval in_file : path:Fpath.t -> t

Build a location identifying the file as a whole. This is a practical location to use when it is not possible to build a more precise location rather than the entire file.

Sourceval none : t

none is a special value to be used when no location information is available.

Sourcemodule File_cache : sig ... end

When locations are created manually, such as from a given line number, to compute all the actual positions and offsets we need to access the original contents of the file and locate new lines characters in it. This cache serves this purpose.

Sourceval in_file_line : file_cache:File_cache.t -> line:int -> t

Create a location that covers the entire line line of the file. Lines start at 1. Raises Invalid_argument if the line overflows.

Getters

Sourceval is_none : t -> bool

is_none loc is true when loc is none, and false otherwise.

Sourceval to_string : t -> string

Build the first line of error messages to produce to stderr using the same syntax as used by the OCaml compiler. If your editor has logic to recognize it, it will allow to jump to the source file.

Sourceval to_file_colon_line : t -> string

This builds a short string representation for use in tests or quick debug.

Sourceval path : t -> Fpath.t

Retrieves the name of the file that contains the location.

Sourceval start_line : t -> int

Retrieve the line number from the start position of the given location. Line numbers start at line 1.

Lexbuf locations

Sourcemodule Lexbuf_loc : sig ... end

Convert between Lexbuf_loc and t.

Sourceval to_lexbuf_loc : t -> Lexbuf_loc.t

Sourceval of_lexbuf_loc : Lexbuf_loc.t -> t

Access the start (included) and stop (excluded) positions of a location, expressed as lexing positions.

Sourceval start : t -> Lexing.position

Sourceval stop : t -> Lexing.position

Utils on offsets and ranges

Sourcemodule Offset : sig ... end

Sourceval start_offset : t -> Offset.t

Sourceval stop_offset : t -> Offset.t

Sourcemodule Range : sig ... end

Sourceval range : t -> Range.t

Sourcemodule Txt : sig ... end

When the symbol you want to decorate is not already an argument in a record, it may be convenient to use this type as a standard way to decorate a symbol with a position.

package loc

Module LocSource