Module Parsing0.Location

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

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

type t = 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.

let none: t;

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

let is_none: t => bool;

True for Location.none, false any other location

let in_file: string => t;

Return an empty ghost range located in a given file.

let init: Lexing.lexbuf => string => unit;

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

let curr: Lexing.lexbuf => t;

Get the location of the current token from the lexbuf.

let symbol_rloc: unit => t;
let symbol_gloc: unit => t;
let rhs_loc: int => t;

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

let rhs_interval: int => int => t;
let set_input_name: string => unit;
let get_pos_info: Lexing.position => (string, int, int);

file, line, char

type loc('a) = Melange_wrapper.Location.loc('a) = {
  1. txt: 'a,
  2. loc: t,
};
let mknoloc: 'a => loc('a);
let mkloc: 'a => t => loc('a);

Input info

let input_name: ref(string);
let input_lexbuf: ref(option(Lexing.lexbuf));
let input_phrase_buffer: ref(option(Buffer.t));

Toplevel-specific functions

let echo_eof: unit => unit;
let reset: unit => unit;

Printing locations

let rewrite_absolute_path: string => string;

rewrite absolute path to honor the BUILD_PATH_PREFIX_MAP variable (https://reproducible-builds.org/specs/build-path-prefix-map/) if it is set.

let absolute_path: string => string;
let show_filename: string => string;

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

let print_filename: Format.formatter => string => unit;
let print_loc: Format.formatter => t => unit;
let print_locs: Format.formatter => list(t) => unit;

Toplevel-specific location highlighting

let highlight_terminfo: Lexing.lexbuf => Format.formatter => list(t) => unit;

Reporting errors and warnings

The type of reports and report printers

type msg = loc((Format.formatter => unit));
let msg: ?loc:t => format4('a, Format.formatter, unit, msg) => 'a;
type report_kind = Melange_wrapper.Location.report_kind =
  1. | Report_error
  2. | Report_warning(string)
  3. | Report_warning_as_error(string)
  4. | Report_alert(string)
  5. | Report_alert_as_error(string)
;
type report = Melange_wrapper.Location.report = {
  1. kind: report_kind,
  2. main: msg,
  3. sub: list(msg),
};
type report_printer = Melange_wrapper.Location.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 => list(msg) => 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

let batch_mode_printer: report_printer;
let terminfo_toplevel_printer: Lexing.lexbuf => report_printer;
let best_toplevel_printer: unit => report_printer;

Detects the terminal capabilities and selects an adequate printer

Printing a report

let print_report: Format.formatter => report => unit;

Display an error or warning report.

let report_printer: ref((unit => report_printer));

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.

let default_report_printer: unit => report_printer;

Original report printer for use in hooks.

Reporting warnings

Converting a Warnings.t into a report

let report_warning: t => Warnings.t => option(report);

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

let warning_reporter: ref((t => Warnings.t => option(report)));

Hook for intercepting warnings.

let default_warning_reporter: t => Warnings.t => option(report);

Original warning reporter for use in hooks.

Printing warnings

let formatter_for_warnings: ref(Format.formatter);
let print_warning: t => Format.formatter => Warnings.t => unit;

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

let prerr_warning: t => Warnings.t => unit;

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

Reporting alerts

Converting an Alert.t into a report

let report_alert: t => Warnings.alert => option(report);

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

let alert_reporter: ref((t => Warnings.alert => option(report)));

Hook for intercepting alerts.

let default_alert_reporter: t => Warnings.alert => option(report);

Original alert reporter for use in hooks.

Printing alerts

let print_alert: t => Format.formatter => Warnings.alert => unit;

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

let prerr_alert: t => Warnings.alert => unit;

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

let deprecated: ?def:t => ?use:t => t => string => unit;

Prints a deprecation alert.

let alert: ?def:t => ?use:t => kind:string => t => string => unit;

Prints an arbitrary alert.

Reporting errors

type error = report;

An error is a report which report_kind must be Report_error.

let error: ?loc:t => ?sub:list(msg) => string => error;
let errorf: ?loc:t => ?sub:list(msg) => format4('a, Format.formatter, unit, error) => 'a;
let error_of_printer: ?loc:t => ?sub:list(msg) => (Format.formatter => 'a => unit) => 'a => error;
let error_of_printer_file: (Format.formatter => 'a => unit) => 'a => error;

Automatically reporting errors for raised exceptions

let register_error_of_exn: (exn => option(error)) => 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).

let error_of_exn: exn => option([ `Ok(error) | `Already_displayed ]);
exception Error(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

let raise_errorf: ?loc:t => ?sub:list(msg) => format4('a, Format.formatter, unit, 'b) => 'a;
let report_exception: Format.formatter => exn => unit;

Reraise the exception if it is unknown.