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