package merlin-lib
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=67da3b34f2fea07678267309f61da4a2c6f08298de0dc59655b8d30fd8269af1
sha512=1fb3b5180d36aa82b82a319e15b743b802b6888f0dc67645baafdb4e18dfc23a7b90064ec9bc42f7424061cf8cde7f8839178d8a8537bf4596759f3ff4891873
doc/merlin-lib.ocaml_parsing/Ocaml_parsing/Location/index.html
Module Ocaml_parsing.Location
Source
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 = {
loc_start : Lexing.position;
loc_end : Lexing.position;
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.
Set the file name and line number of the lexbuf
to be the start of the named file.
Get the location of the current token from the lexbuf
.
rhs_loc n
returns the location of the symbol at position n
, starting at 1, in the current parser rule.
file, line, char
Input info
Toplevel-specific functions
Rewriting path
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
).
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:
None
, means either- BUILD_PATH_PREFIX_MAP is not set and
path
does not exists, or - no source prefixes of
path
in the mapping were found,
- BUILD_PATH_PREFIX_MAP is not set and
Some target
, meanstarget
exists and either- BUILD_PATH_PREFIX_MAP is not set and
target
=path
, or target
is the first file (in priority order) thatpath
mapped to that exists in the file system.
- BUILD_PATH_PREFIX_MAP is not set and
Not_found
raised, means some source prefixes in the map were found that matchedpath
, but none of them existed in the file system. The caller should catch this and issue an appropriate error message.
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:
[]
, means either- BUILD_PATH_PREFIX_MAP is not set and
dir
is not an existing directory, or - if set, then there were no matching prefixes of
dir
.
- BUILD_PATH_PREFIX_MAP is not set and
Some dirs
, means dirs are the directories found. Either- BUILD_PATH_PREFIX_MAP is not set and
dirs = [dir]
, or - it was set and
dirs
are the mapped existing directories.
- BUILD_PATH_PREFIX_MAP is not set and
- Not_found raised, means some source prefixes in the map were found that matched
dir
, but none of mapping results were existing directories (possibly due to misconfiguration). The caller should catch this and issue an appropriate error message.
See the BUILD_PATH_PREFIX_MAP spec
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
In -absname mode, return the absolute path for this filename. Otherwise, returns the filename unchanged.
Toplevel-specific location highlighting
Reporting errors and warnings
The type of reports and report printers
type report = {
kind : report_kind;
main : msg;
sub : msg list;
footnote : Merlin_utils.Format_doc.t option;
source : error_source;
}
type report_printer = {
pp : report_printer -> Format.formatter -> report -> unit;
pp_report_kind : report_printer -> report -> Format.formatter -> report_kind -> unit;
pp_main_loc : report_printer -> report -> Format.formatter -> t -> unit;
pp_main_txt : report_printer -> report -> Format.formatter -> Merlin_utils.Format_doc.t -> unit;
pp_submsgs : report_printer -> report -> Format.formatter -> msg list -> unit;
pp_submsg : report_printer -> report -> Format.formatter -> msg -> unit;
pp_submsg_loc : report_printer -> report -> Format.formatter -> t -> unit;
pp_submsg_txt : report_printer -> report -> Format.formatter -> Merlin_utils.Format_doc.t -> unit;
}
A printer for report
s, 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
Printing a report
Display an error or warning report.
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.
Original report printer for use in hooks.
Reporting warnings
Converting a Warnings.t
into a report
report_warning loc w
produces a report for the given warning w
, or None
if the warning is not to be printed.
Hook for intercepting warnings.
Original warning reporter for use in hooks.
Printing warnings
Prints a warning. This is simply the composition of report_warning
and print_report
.
Same as print_warning
, but uses !formatter_for_warnings
as output formatter.
Reporting alerts
Converting an Alert.t
into a report
report_alert loc w
produces a report for the given alert w
, or None
if the alert is not to be printed.
Hook for intercepting alerts.
Original alert reporter for use in hooks.
Printing alerts
Prints an alert. This is simply the composition of report_alert
and print_report
.
Same as print_alert
, but uses !formatter_for_warnings
as output formatter.
Prints an alert that -I +lib has been automatically added to the load path
deprecated_script_alert command
prints an alert that command foo
has been deprecated in favour of command ./foo
Reporting errors
val error :
?loc:t ->
?sub:msg list ->
?footnote:delayed_msg ->
?source:error_source ->
string ->
error
val errorf :
?loc:t ->
?sub:msg list ->
?footnote:delayed_msg ->
?source:error_source ->
('a, Merlin_utils.Format_doc.formatter, unit, error) format4 ->
'a
val error_of_printer :
?loc:t ->
?sub:msg list ->
?footnote:delayed_msg ->
?source:error_source ->
(Merlin_utils.Format_doc.formatter -> 'a -> unit) ->
'a ->
error
val error_of_printer_file :
?source:error_source ->
(Merlin_utils.Format_doc.formatter -> 'a -> unit) ->
'a ->
error
Automatically reporting errors for raised exceptions
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).
Raising Error e
signals an error e
; the exception will be caught and the error will be printed.
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 ->
?footnote:delayed_msg ->
?source:error_source ->
('a, Merlin_utils.Format_doc.formatter, unit, 'b) format4 ->
'a
Reraise the exception if it is unknown.