loc 0.2.2 (latest) · OCaml Package

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

type t

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

Dumping locations

val 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.

val 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

val 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.

val 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

val 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 }
     ;

val of_position : Lexing.position -> t

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

Loc.of_position [%here]

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

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

Loc.of_pos __POS__

val of_lexbuf : Lexing.lexbuf -> t

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

val of_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.

val none : t

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

module 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.

val of_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

val is_none : t -> bool

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

val 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.

val to_file_colon_line : t -> string

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

val path : t -> Fpath.t

Retrieves the name of the file that contains the location.

val start_line : t -> int

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

Lexbuf locations

module Lexbuf_loc : sig ... end

Convert between Lexbuf_loc and t.

val to_lexbuf_loc : t -> Lexbuf_loc.t

val of_lexbuf_loc : Lexbuf_loc.t -> t

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

val start : t -> Lexing.position

val stop : t -> Lexing.position

Utils on offsets and ranges

module Offset : sig ... end

val start_offset : t -> Offset.t

val stop_offset : t -> Offset.t

val of_file_offset : file_cache:File_cache.t -> offset:Offset.t -> t

A convenient wrapper to build a loc from the position at a given offset. See Offset.to_position.

module Range : sig ... end

val range : t -> Range.t

val of_file_range : file_cache:File_cache.t -> range:Range.t -> t

A convenient wrapper to build a loc from a file range. Raises Invalid_argument if the range is not valid for that file. See Offset.to_position.

module 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.

Deprecated aliases

This part of the API will be deprecated in a future version.

val in_file : path:Fpath.t -> t

This was renamed of_file.

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

This was renamed of_file_line.

Private

module Private : sig ... end

Exported for testing only.

package loc