Module Ocamlformat_ocaml_common.LocationSource

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

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

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

t represents a range of characters in the source code.

loc_ghost=false whenever the AST described by the location can be parsed from the location. In all other cases, loc_ghost must be true. Most locations produced by the parser have loc_ghost=false. When loc_ghost=true, the location is usually a best effort approximation.

This info is used by tools like merlin that want to relate source code with parsetrees or later asts. ocamlprof skips instrumentation of ghost nodes.

Example: in `let f x = x`, we have:

  • a structure item at location "let f x = x"
  • a pattern "f" at location "f"
  • an expression "fun x -> x" at location "x = x" with loc_ghost=true
  • a pattern "x" at location "x"
  • an expression "x" at location "x" In this case, every node has loc_ghost=false, except the node "fun x -> x", since Parser.expression (Lexing.from_string "x = x") would fail to parse. By contrast, in `let f = fun x -> x`, every node has loc_ghost=false.

Line directives can modify the filenames and line numbers arbitrarily, which is orthogonal to loc_ghost, which describes the range of characters from loc_start.pos_cnum to loc_end.pos_cnum in the parsed string.

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.

Sourceval none : t

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

Sourceval is_none : t -> bool

True for Location.none, false any other location

Sourceval in_file : string -> t

Return an empty ghost range located in a given file.

Sourceval init_info : Stdlib.Lexing.lexbuf -> string -> unit

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

Sourceval curr : Stdlib.Lexing.lexbuf -> t

Get the location of the current token from the lexbuf.

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

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

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

file, line, char

Sourcetype 'a loc = {
  1. txt : 'a;
  2. loc : t;
}
Sourceval mknoloc : 'a -> 'a loc
Sourceval mkloc : 'a -> t -> 'a loc
Sourceval map : ('a -> 'b) -> 'a loc -> 'b loc

Input info

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

Toplevel-specific functions

Sourceval echo_eof : unit -> unit
Sourceval reset : unit -> unit

Rewriting path

Printing locations

Sourceval show_filename : string -> string

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

Sourceval print_filename : Stdlib.Format.formatter -> string -> unit
Sourceval print_loc : Stdlib.Format.formatter -> t -> unit
Sourceval print_locs : Stdlib.Format.formatter -> t list -> unit
Sourceval separate_new_message : Stdlib.Format.formatter -> unit
Sourcemodule Doc : sig ... end

Toplevel-specific location highlighting

Sourceval highlight_terminfo : Stdlib.Lexing.lexbuf -> Stdlib.Format.formatter -> t list -> unit

Reporting errors and warnings

The type of reports and report printers

Sourceval msg : ?loc:t -> ('a, Ocamlformat_parser_shims.Format_doc.formatter, unit, msg) Stdlib.format4 -> 'a
Sourcetype 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
Sourcetype report = {
  1. kind : report_kind;
  2. main : msg;
  3. sub : msg list;
  4. footnote : Ocamlformat_parser_shims.Format_doc.t option;
}
Sourcetype report_printer = {
  1. pp : report_printer -> Stdlib.Format.formatter -> report -> unit;
  2. pp_report_kind : report_printer -> report -> Stdlib.Format.formatter -> report_kind -> unit;
  3. pp_main_loc : report_printer -> report -> Stdlib.Format.formatter -> t -> unit;
  4. pp_main_txt : report_printer -> report -> Stdlib.Format.formatter -> Ocamlformat_parser_shims.Format_doc.t -> unit;
  5. pp_submsgs : report_printer -> report -> Stdlib.Format.formatter -> msg list -> unit;
  6. pp_submsg : report_printer -> report -> Stdlib.Format.formatter -> msg -> unit;
  7. pp_submsg_loc : report_printer -> report -> Stdlib.Format.formatter -> t -> unit;
  8. pp_submsg_txt : report_printer -> report -> Stdlib.Format.formatter -> Ocamlformat_parser_shims.Format_doc.t -> unit;
}

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

Report printers used in the compiler

Sourceval batch_mode_printer : report_printer
Sourceval terminfo_toplevel_printer : Stdlib.Lexing.lexbuf -> report_printer
Sourceval best_toplevel_printer : unit -> report_printer

Detects the terminal capabilities and selects an adequate printer

Printing a report

Sourceval print_report : Stdlib.Format.formatter -> report -> unit

Display an error or warning report.

Sourceval report_printer : (unit -> report_printer) Stdlib.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.

Sourceval default_report_printer : unit -> report_printer

Original report printer for use in hooks.

Reporting warnings

Converting a Warnings.t into a report

Sourceval report_warning : t -> 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.

Sourceval warning_reporter : (t -> Warnings.t -> report option) Stdlib.ref

Hook for intercepting warnings.

Sourceval default_warning_reporter : t -> Warnings.t -> report option

Original warning reporter for use in hooks.

Printing warnings

Sourceval formatter_for_warnings : Stdlib.Format.formatter Stdlib.ref
Sourceval print_warning : t -> Stdlib.Format.formatter -> Warnings.t -> unit

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

Sourceval 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

Sourceval report_alert : t -> 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.

Sourceval alert_reporter : (t -> Warnings.alert -> report option) Stdlib.ref

Hook for intercepting alerts.

Sourceval default_alert_reporter : t -> Warnings.alert -> report option

Original alert reporter for use in hooks.

Printing alerts

Sourceval print_alert : t -> Stdlib.Format.formatter -> Warnings.alert -> unit

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

Sourceval prerr_alert : t -> Warnings.alert -> unit

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

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

Prints a deprecation alert.

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

Prints an arbitrary alert.

Sourceval auto_include_alert : string -> unit

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

Sourceval 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

Sourcetype error = report

An error is a report which report_kind must be Report_error.

Sourcetype delayed_msg = unit -> Ocamlformat_parser_shims.Format_doc.t option
Sourceval error : ?loc:t -> ?sub:msg list -> ?footnote:delayed_msg -> string -> error
Sourceval errorf : ?loc:t -> ?sub:msg list -> ?footnote:delayed_msg -> ('a, Ocamlformat_parser_shims.Format_doc.formatter, unit, error) Stdlib.format4 -> 'a
Sourceval error_of_printer : ?loc:t -> ?sub:msg list -> ?footnote:delayed_msg -> (Ocamlformat_parser_shims.Format_doc.formatter -> 'a -> unit) -> 'a -> error
Sourceval error_of_printer_file : (Ocamlformat_parser_shims.Format_doc.formatter -> 'a -> unit) -> 'a -> error

Automatically reporting errors for raised exceptions

Sourceval 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).

Sourceval error_of_exn : exn -> [ `Ok of error | `Already_displayed ] option
Sourceexception Error of error

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

Sourceexception 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

Sourceval raise_errorf : ?loc:t -> ?sub:msg list -> ?footnote:delayed_msg -> ('a, Ocamlformat_parser_shims.Format_doc.formatter, unit, 'b) Stdlib.format4 -> 'a
Sourceval report_exception : Stdlib.Format.formatter -> exn -> unit

Reraise the exception if it is unknown.