1Location(3)                      OCaml library                     Location(3)
2
3
4

NAME

6       Location  - Source code locations (ranges of positions), used in parse‐
7       tree.
8

Module

10       Module   Location
11

Documentation

13       Module Location
14        : sig end
15
16
17       Source code locations (ranges of positions), used in parsetree.
18
19       Warning: this module is unstable and part of Compiler_libs .
20
21
22
23
24
25       type t = Warnings.loc = {
26        loc_start : Lexing.position ;
27        loc_end : Lexing.position ;
28        loc_ghost : bool ;
29        }
30
31
32
33
34
35
36       Note on the use of Lexing.position in this module.  If pos_fname = "" ,
37       then  use  !input_name  instead.  If pos_lnum = -1 , then pos_bol = 0 .
38       Use pos_cnum and re-parse the file to get the line and  character  num‐
39       bers.  Else all fields are correct.
40
41       val none : t
42
43       An arbitrary value of type t ; describes an empty ghost range.
44
45
46
47       val is_none : t -> bool
48
49       True for Location.none , false any other location
50
51
52
53       val in_file : string -> t
54
55       Return an empty ghost range located in a given file.
56
57
58
59       val init : Lexing.lexbuf -> string -> unit
60
61       Set  the file name and line number of the lexbuf to be the start of the
62       named file.
63
64
65
66       val curr : Lexing.lexbuf -> t
67
68       Get the location of the current token from the lexbuf .
69
70
71
72       val symbol_rloc : unit -> t
73
74
75
76
77       val symbol_gloc : unit -> t
78
79
80
81
82       val rhs_loc : int -> t
83
84
85       rhs_loc n returns the location of the symbol at position n  ,  starting
86       at 1, in the current parser rule.
87
88
89
90       val rhs_interval : int -> int -> t
91
92
93
94
95       val get_pos_info : Lexing.position -> string * int * int
96
97       file, line, char
98
99
100       type 'a loc = {
101        txt : 'a ;
102        loc : t ;
103        }
104
105
106
107
108
109       val mknoloc : 'a -> 'a loc
110
111
112
113
114       val mkloc : 'a -> t -> 'a loc
115
116
117
118
119
120   Input info
121       val input_name : string ref
122
123
124
125
126       val input_lexbuf : Lexing.lexbuf option ref
127
128
129
130
131       val input_phrase_buffer : Buffer.t option ref
132
133
134
135
136
137   Toplevel-specific functions
138       val echo_eof : unit -> unit
139
140
141
142
143       val reset : unit -> unit
144
145
146
147
148
149   Printing locations
150       val rewrite_absolute_path : string -> string
151
152       rewrite  absolute  path  to  honor  the  BUILD_PATH_PREFIX_MAP variable
153       (https://reproducible-builds.org/specs/build-path-prefix-map/) if it is
154       set.
155
156
157
158       val absolute_path : string -> string
159
160
161
162
163       val show_filename : string -> string
164
165       In  -absname  mode, return the absolute path for this filename.  Other‐
166       wise, returns the filename unchanged.
167
168
169
170       val print_filename : Format.formatter -> string -> unit
171
172
173
174
175       val print_loc : Format.formatter -> t -> unit
176
177
178
179
180       val print_locs : Format.formatter -> t list -> unit
181
182
183
184
185
186   Toplevel-specific location highlighting
187       val highlight_terminfo : Lexing.lexbuf -> Format.formatter -> t list ->
188       unit
189
190
191
192
193
194   Reporting errors and warnings
195   The type of reports and report printers
196       type msg = (Format.formatter -> unit) loc
197
198
199
200
201
202       val msg : ?loc:t -> ('a, Format.formatter, unit, msg) format4 -> 'a
203
204
205
206       type report_kind =
207        | Report_error
208        | Report_warning of string
209        | Report_warning_as_error of string
210        | Report_alert of string
211        | Report_alert_as_error of string
212
213
214
215
216       type report = {
217        kind : report_kind ;
218        main : msg ;
219        sub : msg list ;
220        }
221
222
223
224
225       type report_printer = {
226        pp : report_printer -> Format.formatter -> report -> unit ;
227        pp_report_kind  :  report_printer -> report -> Format.formatter -> re‐
228       port_kind -> unit ;
229        pp_main_loc : report_printer -> report ->  Format.formatter  ->  t  ->
230       unit ;
231        pp_main_txt  :  report_printer  -> report -> Format.formatter -> (For‐
232       mat.formatter -> unit) -> unit ;
233        pp_submsgs : report_printer -> report -> Format.formatter -> msg  list
234       -> unit ;
235        pp_submsg  :  report_printer  ->  report -> Format.formatter -> msg ->
236       unit ;
237        pp_submsg_loc : report_printer -> report -> Format.formatter ->  t  ->
238       unit ;
239        pp_submsg_txt  : report_printer -> report -> Format.formatter -> (For‐
240       mat.formatter -> unit) -> unit ;
241        }
242
243
244       A printer for report s, defined using open-recursion.  The goal  is  to
245       make  it  easy  to  define  new printers by re-using code from existing
246       ones.
247
248
249
250
251   Report printers used in the compiler
252       val batch_mode_printer : report_printer
253
254
255
256
257       val terminfo_toplevel_printer : Lexing.lexbuf -> report_printer
258
259
260
261
262       val best_toplevel_printer : unit -> report_printer
263
264       Detects the terminal capabilities and selects an adequate printer
265
266
267
268
269   Printing a report
270       val print_report : Format.formatter -> report -> unit
271
272       Display an error or warning report.
273
274
275
276       val report_printer : (unit -> report_printer) ref
277
278       Hook for redefining the printer of reports.
279
280       The hook is a unit -> report_printer and not simply a report_printer  :
281       this  is useful so that it can detect the type of the output (a file, a
282       terminal, ...) and select a printer accordingly.
283
284
285
286       val default_report_printer : unit -> report_printer
287
288       Original report printer for use in hooks.
289
290
291
292
293   Reporting warnings
294   Converting a Warnings.t into a report
295       val report_warning : t -> Warnings.t -> report option
296
297
298       report_warning loc w produces a report for the given  warning  w  ,  or
299       None if the warning is not to be printed.
300
301
302
303       val warning_reporter : (t -> Warnings.t -> report option) ref
304
305       Hook for intercepting warnings.
306
307
308
309       val default_warning_reporter : t -> Warnings.t -> report option
310
311       Original warning reporter for use in hooks.
312
313
314
315
316   Printing warnings
317       val formatter_for_warnings : Format.formatter ref
318
319
320
321
322       val print_warning : t -> Format.formatter -> Warnings.t -> unit
323
324       Prints  a warning. This is simply the composition of report_warning and
325       print_report .
326
327
328
329       val prerr_warning : t -> Warnings.t -> unit
330
331       Same as print_warning , but uses !formatter_for_warnings as output for‐
332       matter.
333
334
335
336
337   Reporting alerts
338   Converting an Alert.t into a report
339       val report_alert : t -> Warnings.alert -> report option
340
341
342       report_alert loc w produces a report for the given alert w , or None if
343       the alert is not to be printed.
344
345
346
347       val alert_reporter : (t -> Warnings.alert -> report option) ref
348
349       Hook for intercepting alerts.
350
351
352
353       val default_alert_reporter : t -> Warnings.alert -> report option
354
355       Original alert reporter for use in hooks.
356
357
358
359
360   Printing alerts
361       val print_alert : t -> Format.formatter -> Warnings.alert -> unit
362
363       Prints an alert. This is simply the  composition  of  report_alert  and
364       print_report .
365
366
367
368       val prerr_alert : t -> Warnings.alert -> unit
369
370       Same  as  print_alert , but uses !formatter_for_warnings as output for‐
371       matter.
372
373
374
375       val deprecated : ?def:t -> ?use:t -> t -> string -> unit
376
377       Prints a deprecation alert.
378
379
380
381       val alert : ?def:t -> ?use:t -> kind:string -> t -> string -> unit
382
383       Prints an arbitrary alert.
384
385
386
387       val auto_include_alert : string -> unit
388
389       Prints an alert that -I +lib has been automatically added to  the  load
390       path
391
392
393
394       val deprecated_script_alert : string -> unit
395
396
397       deprecated_script_alert  command  prints  an alert that command foo has
398       been deprecated in favour of command ./foo
399
400
401
402
403
404   Reporting errors
405       type error = report
406
407
408       An error is a report which report_kind must be Report_error .
409
410
411
412       val error : ?loc:t -> ?sub:msg list -> string -> error
413
414
415
416
417       val errorf : ?loc:t -> ?sub:msg list ->  ('a,  Format.formatter,  unit,
418       error) format4 -> 'a
419
420
421
422
423       val  error_of_printer : ?loc:t -> ?sub:msg list -> (Format.formatter ->
424       'a -> unit) -> 'a -> error
425
426
427
428
429       val error_of_printer_file : (Format.formatter -> 'a -> unit) ->  'a  ->
430       error
431
432
433
434
435
436   Automatically reporting errors for raised exceptions
437       val register_error_of_exn : (exn -> error option) -> unit
438
439       Each compiler module which defines a custom type of exception which can
440       surface as a user-visible error should register a  "printer"  for  this
441       exception  using  register_error_of_exn .  The result of the printer is
442       an error  value  containing  a  location,  a  message,  and  optionally
443       sub-messages (each of them being located as well).
444
445
446
447       val error_of_exn : exn -> [ `Already_displayed | `Ok of error ] option
448
449
450
451
452       exception Error of error
453
454
455       Raising  Error  e signals an error e ; the exception will be caught and
456       the error will be printed.
457
458
459
460       exception Already_displayed_error
461
462
463       Raising Already_displayed_error signals an error which has already been
464       printed. The exception will be caught, but nothing will be printed
465
466
467
468       val  raise_errorf  :  ?loc:t -> ?sub:msg list -> ('a, Format.formatter,
469       unit, 'b) format4 -> 'a
470
471
472
473
474       val report_exception : Format.formatter -> exn -> unit
475
476       Reraise the exception if it is unknown.
477
478
479
480
481
482OCamldoc                          2023-07-20                       Location(3)