Module Ocaml_parsing.Location

Source code locations (ranges of positions), used in parsetree.

Warning: this module is unstable and part of compiler-libs.

type t = Ocaml_utils.Warnings.loc = {
  1. loc_start : Lexing.position;
  2. loc_end : Lexing.position;
  3. loc_ghost : bool;
}

Note on the use of Lexing.position in this module. If pos_fname = "", then use !input_name instead. If pos_lnum = -1, then pos_bol = 0. Use pos_cnum and re-parse the file to get the line and character numbers. Else all fields are correct.

val compare : t -> t -> int

Strict comparison: Compares all fields of the two locations, irrespective of whether or not they happen to refer to the same place. For fully-defined locations within the same file, is guaranteed to return them in source order; otherwise, or if given two locations that differ only in ghostiness, is just guaranteed to produce a consistent order, but which one is unspecified.

val none : t

An arbitrary value of type t; describes an empty ghost range.

val is_none : t -> bool

True for Location.none, false any other location

val in_file : string -> t

Return an empty ghost range located in a given file.

val init : Lexing.lexbuf -> string -> unit

Set the file name and line number of the lexbuf to be the start of the named file.

val curr : Lexing.lexbuf -> t

Get the location of the current token from the lexbuf.

val ghostify : t -> t

Return a version of the location with loc_ghost = true

val symbol_rloc : unit -> t
val symbol_gloc : unit -> t
val rhs_loc : int -> t

rhs_loc n returns the location of the symbol at position n, starting at 1, in the current parser rule.

val rhs_interval : int -> int -> t
val get_pos_info : Lexing.position -> string * int * int

file, line, char

val merge : ?ghost:bool -> t list -> t

merge locs returns the location covering all locations from locs. It raises if locs is empty, and the result only makes sense if all the locations are from the same file. If ~ghost:false is passed, the result location will only be ghost if one of the input locations was ghost. The default is ~ghost:true, which causes the result location to be ghost no matter what

type 'a loc = {
  1. txt : 'a;
  2. loc : t;
}
val mknoloc : 'a -> 'a loc
val mkloc : 'a -> t -> 'a loc
val get_txt : 'a loc -> 'a
val get_loc : 'a loc -> t
val map : ('a -> 'b) -> 'a loc -> 'b loc
val compare_txt : ('a -> 'b -> 'c) -> 'a loc -> 'b loc -> 'c

Input info

val input_name : string ref
val input_lexbuf : Lexing.lexbuf option ref
val input_phrase_buffer : Buffer.t option ref

Toplevel-specific functions

val echo_eof : unit -> unit
val separate_new_message : Format.formatter -> unit
val reset : unit -> unit

Rewriting path

val rewrite_absolute_path : string -> string

rewrite_absolute_path path rewrites path to honor the BUILD_PATH_PREFIX_MAP variable if it is set. It does not check whether path is absolute or not. The result is as follows:

  • If BUILD_PATH_PREFIX_MAP is not set, just return path.
  • otherwise, rewrite using the mapping (and if there are no matching prefixes that will just return path).

See the BUILD_PATH_PREFIX_MAP spec

rewrite_find_first_existing path uses a BUILD_PATH_PREFIX_MAP mapping and tries to find a source in mapping that maps to a result that exists in the file system. There are the following return values:

See the BUILD_PATH_PREFIX_MAP spec

rewrite_find_all_existing_dirs dir accumulates a list of existing directories, dirs, that are the result of mapping a potentially abstract directory, dir, over all the mapping pairs in the BUILD_PATH_PREFIX_MAP environment variable, if any. The list dirs will be in priority order (head as highest priority).

The possible results are:

See the BUILD_PATH_PREFIX_MAP spec

val absolute_path : string -> string

absolute_path path first makes an absolute path, s from path, prepending the current working directory if path was relative. Then s is rewritten using rewrite_absolute_path. Finally the result is normalized by eliminating instances of '.' or '..'.

Printing locations

val show_filename : string -> string

In -absname mode, return the absolute path for this filename. Otherwise, returns the filename unchanged.

val print_filename : Format.formatter -> string -> unit
val print_loc : Format.formatter -> t -> unit
val print_loc_in_lowercase : Format.formatter -> t -> unit
val print_locs : Format.formatter -> t list -> unit

Toplevel-specific location highlighting

Reporting errors and warnings

The type of reports and report printers

type msg = (Format.formatter -> unit) loc
val msg : ?loc:t -> ('a, Format.formatter, unit, msg) format4 -> 'a
type report_kind =
  1. | Report_error
  2. | Report_warning of string
  3. | Report_warning_as_error of string
  4. | Report_alert of string
  5. | Report_alert_as_error of string
type error_source =
  1. | Lexer
  2. | Parser
  3. | Typer
  4. | Warning
  5. | Unknown
  6. | Env
  7. | Config
type report = {
  1. kind : report_kind;
  2. main : msg;
  3. sub : msg list;
  4. source : error_source;
}
val loc_of_report : report -> t
val print_main : Format.formatter -> report -> unit
val print_sub_msg : Format.formatter -> msg -> unit
type report_printer = {
  1. pp : report_printer -> Format.formatter -> report -> unit;
  2. pp_report_kind : report_printer -> report -> Format.formatter -> report_kind -> unit;
  3. pp_main_loc : report_printer -> report -> Format.formatter -> t -> unit;
  4. pp_main_txt : report_printer -> report -> Format.formatter -> (Format.formatter -> unit) -> unit;
  5. pp_submsgs : report_printer -> report -> Format.formatter -> msg list -> unit;
  6. pp_submsg : report_printer -> report -> Format.formatter -> msg -> unit;
  7. pp_submsg_loc : report_printer -> report -> Format.formatter -> t -> unit;
  8. pp_submsg_txt : report_printer -> report -> Format.formatter -> (Format.formatter -> unit) -> unit;
}

A printer for reports, defined using open-recursion. The goal is to make it easy to define new printers by re-using code from existing ones.

Report printers used in the compiler

val batch_mode_printer : report_printer

Printing a report

val print_report : Format.formatter -> report -> unit

Display an error or warning report.

val report_printer : (unit -> report_printer) ref

Hook for redefining the printer of reports.

The hook is a unit -> report_printer and not simply a report_printer: this is useful so that it can detect the type of the output (a file, a terminal, ...) and select a printer accordingly.

val default_report_printer : unit -> report_printer

Original report printer for use in hooks.

Reporting warnings

Converting a Warnings.t into a report

val report_warning : t -> Ocaml_utils.Warnings.t -> report option

report_warning loc w produces a report for the given warning w, or None if the warning is not to be printed.

val warning_reporter : (t -> Ocaml_utils.Warnings.t -> report option) ref

Hook for intercepting warnings.

val default_warning_reporter : t -> Ocaml_utils.Warnings.t -> report option

Original warning reporter for use in hooks.

Printing warnings

val formatter_for_warnings : Format.formatter ref
val print_warning : t -> Format.formatter -> Ocaml_utils.Warnings.t -> unit

Prints a warning. This is simply the composition of report_warning and print_report.

val prerr_warning_ref : (t -> Ocaml_utils.Warnings.t -> unit) ref
val prerr_warning : t -> Ocaml_utils.Warnings.t -> unit

Same as print_warning, but uses !formatter_for_warnings as output formatter.

Reporting alerts

Converting an Alert.t into a report

val report_alert : t -> Ocaml_utils.Warnings.alert -> report option

report_alert loc w produces a report for the given alert w, or None if the alert is not to be printed.

val alert_reporter : (t -> Ocaml_utils.Warnings.alert -> report option) ref

Hook for intercepting alerts.

val default_alert_reporter : t -> Ocaml_utils.Warnings.alert -> report option

Original alert reporter for use in hooks.

Printing alerts

val print_alert : t -> Format.formatter -> Ocaml_utils.Warnings.alert -> unit

Prints an alert. This is simply the composition of report_alert and print_report.

val prerr_alert_ref : (t -> Ocaml_utils.Warnings.alert -> unit) ref
val prerr_alert : t -> Ocaml_utils.Warnings.alert -> unit

Same as print_alert, but uses !formatter_for_warnings as output formatter.

val deprecated : ?def:t -> ?use:t -> t -> string -> unit

Prints a deprecation alert.

val alert : ?def:t -> ?use:t -> kind:string -> t -> string -> unit

Prints an arbitrary alert.

val auto_include_alert : string -> unit

Prints an alert that -I +lib has been automatically added to the load path

val deprecated_script_alert : string -> unit

deprecated_script_alert command prints an alert that command foo has been deprecated in favour of command ./foo

Reporting errors

type error = report

An error is a report which report_kind must be Report_error.

val error : ?loc:t -> ?sub:msg list -> ?source:error_source -> string -> error
val errorf : ?loc:t -> ?sub:msg list -> ?source:error_source -> ('a, Format.formatter, unit, error) format4 -> 'a
val error_of_printer : ?loc:t -> ?sub:msg list -> ?source:error_source -> (Format.formatter -> 'a -> unit) -> 'a -> error
val error_of_printer_file : ?source:error_source -> (Format.formatter -> 'a -> unit) -> 'a -> error

Automatically reporting errors for raised exceptions

val register_error_of_exn : (exn -> error option) -> unit

Each compiler module which defines a custom type of exception which can surface as a user-visible error should register a "printer" for this exception using register_error_of_exn. The result of the printer is an error value containing a location, a message, and optionally sub-messages (each of them being located as well).

val error_of_exn : exn -> [ `Ok of error | `Already_displayed ] option
exception Error of error

Raising Error e signals an error e; the exception will be caught and the error will be printed.

exception Already_displayed_error

Raising Already_displayed_error signals an error which has already been printed. The exception will be caught, but nothing will be printed

val raise_errorf : ?loc:t -> ?sub:msg list -> ?source:error_source -> ('a, Format.formatter, unit, 'b) format4 -> 'a
val report_exception : Format.formatter -> exn -> unit

Reraise the exception if it is unknown.

val todo_overwrite_not_implemented : ?kind:string -> t -> 'a

CR uniqueness: remove this once overwriting is fully implemented