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