man-pages/man3/Location.3o.html
2021-03-31 01:06:50 +01:00

1040 lines
13 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of Location</TITLE>
</HEAD><BODY>
<H1>Location</H1>
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
Location - Source code locations (ranges of positions), used in parsetree
<A NAME="lbAC">&nbsp;</A>
<H2>Module</H2>
Module Location
<A NAME="lbAD">&nbsp;</A>
<H2>Documentation</H2>
<P>
Module
<B>Location</B>
<BR>&nbsp;:&nbsp;
<B>sig end</B>
<P>
<P>
<A NAME="lbAE">&nbsp;</A>
<H3>Source code locations (ranges of positions), used in parsetree</H3>
<P>
Warning: this module is unstable and part of
<B>Compiler_libs</B>
.
<P>
<P>
<P>
<P>
<P>
<I>type t </I>
=
<B>Warnings.loc</B>
= {
<BR>&nbsp;loc_start&nbsp;:&nbsp;
<B>Lexing.position</B>
;
<BR>&nbsp;loc_end&nbsp;:&nbsp;
<B>Lexing.position</B>
;
<BR>&nbsp;loc_ghost&nbsp;:&nbsp;
<B>bool</B>
;
<BR>&nbsp;}
<P>
<P>
<P>
<P>
<P>
<P>
Note on the use of Lexing.position in this module.
If
<B>pos_fname = </B>
, then use
<B>!input_name</B>
instead.
If
<B>pos_lnum = -1</B>
, then
<B>pos_bol = 0</B>
. Use
<B>pos_cnum</B>
and
re-parse the file to get the line and character numbers.
Else all fields are correct.
<P>
<P>
<I>val none </I>
:
<B>t</B>
<P>
An arbitrary value of type
<B>t</B>
; describes an empty ghost range.
<P>
<P>
<P>
<I>val in_file </I>
:
<B>string -&gt; t</B>
<P>
Return an empty ghost range located in a given file.
<P>
<P>
<P>
<I>val init </I>
:
<B>Lexing.lexbuf -&gt; string -&gt; unit</B>
<P>
Set the file name and line number of the
<B>lexbuf</B>
to be the start
of the named file.
<P>
<P>
<P>
<I>val curr </I>
:
<B>Lexing.lexbuf -&gt; t</B>
<P>
Get the location of the current token from the
<B>lexbuf</B>
.
<P>
<P>
<P>
<I>val symbol_rloc </I>
:
<B>unit -&gt; t</B>
<P>
<P>
<P>
<P>
<I>val symbol_gloc </I>
:
<B>unit -&gt; t</B>
<P>
<P>
<P>
<P>
<I>val rhs_loc </I>
:
<B>int -&gt; t</B>
<P>
<P>
<B>rhs_loc n</B>
returns the location of the symbol at position
<B>n</B>
, starting
at 1, in the current parser rule.
<P>
<P>
<P>
<I>val rhs_interval </I>
:
<B>int -&gt; int -&gt; t</B>
<P>
<P>
<P>
<P>
<I>val get_pos_info </I>
:
<B>Lexing.position -&gt; string * int * int</B>
<P>
file, line, char
<P>
<P>
<I>type </I>
<B>'a</B>
<I>loc </I>
= {
<BR>&nbsp;txt&nbsp;:&nbsp;
<B>'a</B>
;
<BR>&nbsp;loc&nbsp;:&nbsp;
<B>t</B>
;
<BR>&nbsp;}
<P>
<P>
<P>
<P>
<P>
<I>val mknoloc </I>
:
<B>'a -&gt; 'a loc</B>
<P>
<P>
<P>
<P>
<I>val mkloc </I>
:
<B>'a -&gt; t -&gt; 'a loc</B>
<P>
<P>
<P>
<P>
<P>
<A NAME="lbAF">&nbsp;</A>
<H3>Input info</H3>
<P>
<P>
<P>
<I>val input_name </I>
:
<B>string ref</B>
<P>
<P>
<P>
<P>
<I>val input_lexbuf </I>
:
<B>Lexing.lexbuf option ref</B>
<P>
<P>
<P>
<P>
<P>
<A NAME="lbAG">&nbsp;</A>
<H3>Toplevel-specific functions</H3>
<P>
<P>
<P>
<I>val echo_eof </I>
:
<B>unit -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val reset </I>
:
<B>unit -&gt; unit</B>
<P>
<P>
<P>
<P>
<P>
<A NAME="lbAH">&nbsp;</A>
<H3>Printing locations</H3>
<P>
<P>
<P>
<I>val rewrite_absolute_path </I>
:
<B>string -&gt; string</B>
<P>
rewrite absolute path to honor the BUILD_PATH_PREFIX_MAP
variable (<A HREF="https://reproducible-builds.org/specs/build-path-prefix-map/)">https://reproducible-builds.org/specs/build-path-prefix-map/)</A>
if it is set.
<P>
<P>
<P>
<I>val absolute_path </I>
:
<B>string -&gt; string</B>
<P>
<P>
<P>
<P>
<I>val show_filename </I>
:
<B>string -&gt; string</B>
<P>
In -absname mode, return the absolute path for this filename.
Otherwise, returns the filename unchanged.
<P>
<P>
<P>
<I>val print_filename </I>
:
<B>Format.formatter -&gt; string -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val print_loc </I>
:
<B>Format.formatter -&gt; t -&gt; unit</B>
<P>
<P>
<P>
<P>
<I>val print_locs </I>
:
<B>Format.formatter -&gt; t list -&gt; unit</B>
<P>
<P>
<P>
<P>
<P>
<A NAME="lbAI">&nbsp;</A>
<H3>Toplevel-specific location highlighting</H3>
<P>
<P>
<P>
<I>val highlight_terminfo </I>
:
<B>Lexing.lexbuf -&gt; Format.formatter -&gt; t list -&gt; unit</B>
<P>
<P>
<P>
<P>
<P>
<A NAME="lbAJ">&nbsp;</A>
<H3>Reporting errors and warnings</H3>
<P>
<P>
<P>
<P>
<A NAME="lbAK">&nbsp;</A>
<H3>The type of reports and report printers</H3>
<P>
<P>
<I>type msg </I>
=
<B>(Format.formatter -&gt; unit) loc</B>
<P>
<P>
<P>
<P>
<P>
<I>val msg </I>
:
<B>?loc:t -&gt;</B>
<B>('a, Format.formatter, unit, msg) format4 -&gt; 'a</B>
<P>
<P>
<P>
<I>type report_kind </I>
=
<BR>&nbsp;|&nbsp;Report_error
<BR>&nbsp;|&nbsp;Report_warning
<B>of </B>
<B>string</B>
<BR>&nbsp;|&nbsp;Report_warning_as_error
<B>of </B>
<B>string</B>
<BR>&nbsp;|&nbsp;Report_alert
<B>of </B>
<B>string</B>
<BR>&nbsp;|&nbsp;Report_alert_as_error
<B>of </B>
<B>string</B>
<BR>&nbsp;
<P>
<P>
<P>
<I>type report </I>
= {
<BR>&nbsp;kind&nbsp;:&nbsp;
<B>report_kind</B>
;
<BR>&nbsp;main&nbsp;:&nbsp;
<B>msg</B>
;
<BR>&nbsp;sub&nbsp;:&nbsp;
<B>msg list</B>
;
<BR>&nbsp;}
<P>
<P>
<P>
<P>
<I>type report_printer </I>
= {
<BR>&nbsp;pp&nbsp;:&nbsp;
<B>report_printer -&gt; Format.formatter -&gt; report -&gt; unit</B>
;
<BR>&nbsp;pp_report_kind&nbsp;:&nbsp;
<B>report_printer -&gt;</B>
<B>report -&gt; Format.formatter -&gt; report_kind -&gt; unit</B>
;
<BR>&nbsp;pp_main_loc&nbsp;:&nbsp;
<B>report_printer -&gt;</B>
<B>report -&gt; Format.formatter -&gt; t -&gt; unit</B>
;
<BR>&nbsp;pp_main_txt&nbsp;:&nbsp;
<B>report_printer -&gt;</B>
<B>report -&gt;</B>
<B>Format.formatter -&gt; (Format.formatter -&gt; unit) -&gt; unit</B>
;
<BR>&nbsp;pp_submsgs&nbsp;:&nbsp;
<B>report_printer -&gt;</B>
<B>report -&gt; Format.formatter -&gt; msg list -&gt; unit</B>
;
<BR>&nbsp;pp_submsg&nbsp;:&nbsp;
<B>report_printer -&gt;</B>
<B>report -&gt; Format.formatter -&gt; msg -&gt; unit</B>
;
<BR>&nbsp;pp_submsg_loc&nbsp;:&nbsp;
<B>report_printer -&gt;</B>
<B>report -&gt; Format.formatter -&gt; t -&gt; unit</B>
;
<BR>&nbsp;pp_submsg_txt&nbsp;:&nbsp;
<B>report_printer -&gt;</B>
<B>report -&gt;</B>
<B>Format.formatter -&gt; (Format.formatter -&gt; unit) -&gt; unit</B>
;
<BR>&nbsp;}
<P>
<P>
A printer for
<B>report</B>
s, defined using open-recursion.
The goal is to make it easy to define new printers by re-using code from
existing ones.
<P>
<P>
<P>
<P>
<A NAME="lbAL">&nbsp;</A>
<H3>Report printers used in the compiler</H3>
<P>
<P>
<P>
<I>val batch_mode_printer </I>
:
<B>report_printer</B>
<P>
<P>
<P>
<P>
<I>val terminfo_toplevel_printer </I>
:
<B>Lexing.lexbuf -&gt; report_printer</B>
<P>
<P>
<P>
<P>
<I>val best_toplevel_printer </I>
:
<B>unit -&gt; report_printer</B>
<P>
Detects the terminal capabilities and selects an adequate printer
<P>
<P>
<P>
<P>
<A NAME="lbAM">&nbsp;</A>
<H3>Printing a report</H3>
<P>
<P>
<P>
<I>val print_report </I>
:
<B>Format.formatter -&gt; report -&gt; unit</B>
<P>
Display an error or warning report.
<P>
<P>
<P>
<I>val report_printer </I>
:
<B>(unit -&gt; report_printer) ref</B>
<P>
Hook for redefining the printer of reports.
<P>
The hook is a
<B>unit -&gt; report_printer</B>
and not simply a
<B>report_printer</B>
:
this is useful so that it can detect the type of the output (a file, a
terminal, ...) and select a printer accordingly.
<P>
<P>
<P>
<I>val default_report_printer </I>
:
<B>unit -&gt; report_printer</B>
<P>
Original report printer for use in hooks.
<P>
<P>
<P>
<P>
<A NAME="lbAN">&nbsp;</A>
<H3>Reporting warnings</H3>
<P>
<P>
<P>
<P>
<A NAME="lbAO">&nbsp;</A>
<H3>Converting a Warnings.t into a report</H3>
<P>
<P>
<P>
<I>val report_warning </I>
:
<B>t -&gt; Warnings.t -&gt; report option</B>
<P>
<P>
<B>report_warning loc w</B>
produces a report for the given warning
<B>w</B>
, or
<B>None</B>
if the warning is not to be printed.
<P>
<P>
<P>
<I>val warning_reporter </I>
:
<B>(t -&gt; Warnings.t -&gt; report option) ref</B>
<P>
Hook for intercepting warnings.
<P>
<P>
<P>
<I>val default_warning_reporter </I>
:
<B>t -&gt; Warnings.t -&gt; report option</B>
<P>
Original warning reporter for use in hooks.
<P>
<P>
<P>
<P>
<A NAME="lbAP">&nbsp;</A>
<H3>Printing warnings</H3>
<P>
<P>
<P>
<I>val formatter_for_warnings </I>
:
<B>Format.formatter ref</B>
<P>
<P>
<P>
<P>
<I>val print_warning </I>
:
<B>t -&gt; Format.formatter -&gt; Warnings.t -&gt; unit</B>
<P>
Prints a warning. This is simply the composition of
<B>report_warning</B>
and
<B>print_report</B>
.
<P>
<P>
<P>
<I>val prerr_warning </I>
:
<B>t -&gt; Warnings.t -&gt; unit</B>
<P>
Same as
<B>print_warning</B>
, but uses
<B>!formatter_for_warnings</B>
as output
formatter.
<P>
<P>
<P>
<P>
<A NAME="lbAQ">&nbsp;</A>
<H3>Reporting alerts</H3>
<P>
<P>
<P>
<P>
<A NAME="lbAR">&nbsp;</A>
<H3>Converting an Alert.t into a report</H3>
<P>
<P>
<P>
<I>val report_alert </I>
:
<B>t -&gt; Warnings.alert -&gt; report option</B>
<P>
<P>
<B>report_alert loc w</B>
produces a report for the given alert
<B>w</B>
, or
<B>None</B>
if the alert is not to be printed.
<P>
<P>
<P>
<I>val alert_reporter </I>
:
<B>(t -&gt; Warnings.alert -&gt; report option) ref</B>
<P>
Hook for intercepting alerts.
<P>
<P>
<P>
<I>val default_alert_reporter </I>
:
<B>t -&gt; Warnings.alert -&gt; report option</B>
<P>
Original alert reporter for use in hooks.
<P>
<P>
<P>
<P>
<A NAME="lbAS">&nbsp;</A>
<H3>Printing alerts</H3>
<P>
<P>
<P>
<I>val print_alert </I>
:
<B>t -&gt; Format.formatter -&gt; Warnings.alert -&gt; unit</B>
<P>
Prints an alert. This is simply the composition of
<B>report_alert</B>
and
<B>print_report</B>
.
<P>
<P>
<P>
<I>val prerr_alert </I>
:
<B>t -&gt; Warnings.alert -&gt; unit</B>
<P>
Same as
<B>print_alert</B>
, but uses
<B>!formatter_for_warnings</B>
as output
formatter.
<P>
<P>
<P>
<I>val deprecated </I>
:
<B>?def:t -&gt; ?use:t -&gt; t -&gt; string -&gt; unit</B>
<P>
Prints a deprecation alert.
<P>
<P>
<P>
<I>val alert </I>
:
<B>?def:t -&gt;</B>
<B>?use:t -&gt; kind:string -&gt; t -&gt; string -&gt; unit</B>
<P>
Prints an arbitrary alert.
<P>
<P>
<P>
<P>
<A NAME="lbAT">&nbsp;</A>
<H3>Reporting errors</H3>
<P>
<P>
<I>type error </I>
=
<B>report</B>
<P>
<P>
An
<B>error</B>
is a
<B>report</B>
which
<B>report_kind</B>
must be
<B>Report_error</B>
.
<P>
<P>
<P>
<I>val error </I>
:
<B>?loc:t -&gt; ?sub:msg list -&gt; string -&gt; error</B>
<P>
<P>
<P>
<P>
<I>val errorf </I>
:
<B>?loc:t -&gt;</B>
<B>?sub:msg list -&gt;</B>
<B>('a, Format.formatter, unit, error) format4 -&gt; 'a</B>
<P>
<P>
<P>
<P>
<I>val error_of_printer </I>
:
<B>?loc:t -&gt;</B>
<B>?sub:msg list -&gt;</B>
<B>(Format.formatter -&gt; 'a -&gt; unit) -&gt; 'a -&gt; error</B>
<P>
<P>
<P>
<P>
<I>val error_of_printer_file </I>
:
<B>(Format.formatter -&gt; 'a -&gt; unit) -&gt; 'a -&gt; error</B>
<P>
<P>
<P>
<P>
<P>
<A NAME="lbAU">&nbsp;</A>
<H3>Automatically reporting errors for raised exceptions</H3>
<P>
<P>
<P>
<I>val register_error_of_exn </I>
:
<B>(exn -&gt; error option) -&gt; unit</B>
<P>
Each compiler module which defines a custom type of exception
which can surface as a user-visible error should register
a &quot;printer&quot; for this exception using
<B>register_error_of_exn</B>
.
The result of the printer is an
<B>error</B>
value containing
a location, a message, and optionally sub-messages (each of them
being located as well).
<P>
<P>
<P>
<I>val error_of_exn </I>
:
<B>exn -&gt; [ `Already_displayed | `Ok of error ] option</B>
<P>
<P>
<P>
<P>
<I>exception Error </I>
<B>of </B>
<B>error</B>
<P>
<P>
Raising
<B>Error e</B>
signals an error
<B>e</B>
; the exception will be caught and the
error will be printed.
<P>
<P>
<P>
<I>exception Already_displayed_error </I>
<P>
<P>
Raising
<B>Already_displayed_error</B>
signals an error which has already been
printed. The exception will be caught, but nothing will be printed
<P>
<P>
<P>
<I>val raise_errorf </I>
:
<B>?loc:t -&gt;</B>
<B>?sub:msg list -&gt;</B>
<B>('a, Format.formatter, unit, 'b) format4 -&gt; 'a</B>
<P>
<P>
<P>
<P>
<I>val report_exception </I>
:
<B>Format.formatter -&gt; exn -&gt; unit</B>
<P>
Reraise the exception if it is unknown.
<P>
<P>
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
<DT id="2"><A HREF="#lbAC">Module</A><DD>
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
<DL>
<DT id="4"><A HREF="#lbAE">Source code locations (ranges of positions), used in parsetree</A><DD>
<DT id="5"><A HREF="#lbAF">Input info</A><DD>
<DT id="6"><A HREF="#lbAG">Toplevel-specific functions</A><DD>
<DT id="7"><A HREF="#lbAH">Printing locations</A><DD>
<DT id="8"><A HREF="#lbAI">Toplevel-specific location highlighting</A><DD>
<DT id="9"><A HREF="#lbAJ">Reporting errors and warnings</A><DD>
<DT id="10"><A HREF="#lbAK">The type of reports and report printers</A><DD>
<DT id="11"><A HREF="#lbAL">Report printers used in the compiler</A><DD>
<DT id="12"><A HREF="#lbAM">Printing a report</A><DD>
<DT id="13"><A HREF="#lbAN">Reporting warnings</A><DD>
<DT id="14"><A HREF="#lbAO">Converting a Warnings.t into a report</A><DD>
<DT id="15"><A HREF="#lbAP">Printing warnings</A><DD>
<DT id="16"><A HREF="#lbAQ">Reporting alerts</A><DD>
<DT id="17"><A HREF="#lbAR">Converting an Alert.t into a report</A><DD>
<DT id="18"><A HREF="#lbAS">Printing alerts</A><DD>
<DT id="19"><A HREF="#lbAT">Reporting errors</A><DD>
<DT id="20"><A HREF="#lbAU">Automatically reporting errors for raised exceptions</A><DD>
</DL>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:05:47 GMT, March 31, 2021
</BODY>
</HTML>