Location(3) OCaml library Location(3)

# [NAME](#NAME)

Location - Source code locations (ranges of positions), used in parsetree.

# [Module](#Module)

Module Location

# [Documentation](#Documentation)

Module **Location**  
: **sig end**

Source code locations (ranges of positions), used in parsetree.

Warning: this module is unstable and part of **Compiler\_libs** .

*type t* = **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.

*val none* : **t**

An arbitrary value of type **t** ; describes an empty ghost range.

*val is\_none* : **t -> bool**

True for **Location.none** , false any other location

*val in\_file* : **string -> t**

Return an empty ghost range located in a given file.

*val init* : **Lexing.lexbuf -> string -> unit**

Set the file name and line number of the **lexbuf** to be the start of the named file.

*val curr* : **Lexing.lexbuf -> t**

Get the location of the current token from the **lexbuf** .

*val symbol\_rloc* : **unit -> t**

*val symbol\_gloc* : **unit -> t**

*val rhs\_loc* : **int -> t**

**rhs\_loc n** returns the location of the symbol at position **n** , starting at 1, in the current parser rule.

*val rhs\_interval* : **int -> int -> t**

*val get\_pos\_info* : **Lexing.position -> string * int * int**

file, line, char

*type* **'a** *loc* = {  
txt : **'a** ;  
loc : **t** ;  
}

*val mknoloc* : **'a -> 'a loc**

*val mkloc* : **'a -> t -> 'a loc**

## [Input info](#Input_info)

*val input\_name* : **string ref**

*val input\_lexbuf* : **Lexing.lexbuf option ref**

*val input\_phrase\_buffer* : **Buffer.t option ref**

## [Toplevel-specific functions](#Toplevel-specific_functions)

*val echo\_eof* : **unit -> unit**

*val reset* : **unit -> unit**

## [Printing locations](#Printing_locations)

*val rewrite\_absolute\_path* : **string -> string**

rewrite absolute path to honor the BUILD\_PATH\_PREFIX\_MAP variable (https://reproducible-builds.org/specs/build-path-prefix-map/) if it is set.

*val absolute\_path* : **string -> string**

*val show\_filename* : **string -> string**

In -absname mode, return the absolute path for this filename. Otherwise, returns the filename unchanged.

*val print\_filename* : **Format.formatter -> string -> unit**

*val print\_loc* : **Format.formatter -> t -> unit**

*val print\_locs* : **Format.formatter -> t list -> unit**

## [Toplevel-specific location highlighting](#Toplevel-specific_location_highlighting)

*val highlight\_terminfo* : **Lexing.lexbuf -> Format.formatter -> t list -> unit**

## [Reporting errors and warnings](#Reporting_errors_and_warnings)

## [The type of reports and report printers](#The_type_of_reports_and_report_printers)

*type msg* = **(Format.formatter -> unit) loc**

*val msg* : **?loc:t ->** **('a, Format.formatter, unit, msg) format4 -> 'a**

*type report\_kind* =  
| Report\_error  
| Report\_warning **of** **string**  
| Report\_warning\_as\_error **of** **string**  
| Report\_alert **of** **string**  
| Report\_alert\_as\_error **of** **string**

*type report* = {  
kind : **report\_kind** ;  
main : **msg** ;  
sub : **msg list** ;  
}

*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 -> (Format.formatter -> unit) -> 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 -> (Format.formatter -> unit) -> 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](#Report_printers_used_in_the_compiler)

*val batch\_mode\_printer* : **report\_printer**

*val terminfo\_toplevel\_printer* : **Lexing.lexbuf -> report\_printer**

*val best\_toplevel\_printer* : **unit -> report\_printer**

Detects the terminal capabilities and selects an adequate printer

## [Printing a report](#Printing_a_report)

*val print\_report* : **Format.formatter -> report -> unit**

Display an error or warning report.

*val report\_printer* : **(unit -> report\_printer) ref**

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.

*val default\_report\_printer* : **unit -> report\_printer**

Original report printer for use in hooks.

## [Reporting warnings](#Reporting_warnings)

## [Converting a Warnings.t into a report](#Converting_a_Warnings.t_into_a_report)

*val report\_warning* : **t -> Warnings.t -> report option**

**report\_warning loc w** produces a report for the given warning **w** , or **None** if the warning is not to be printed.

*val warning\_reporter* : **(t -> Warnings.t -> report option) ref**

Hook for intercepting warnings.

*val default\_warning\_reporter* : **t -> Warnings.t -> report option**

Original warning reporter for use in hooks.

## [Printing warnings](#Printing_warnings)

*val formatter\_for\_warnings* : **Format.formatter ref**

*val print\_warning* : **t -> Format.formatter -> Warnings.t -> unit**

Prints a warning. This is simply the composition of **report\_warning** and **print\_report** .

*val prerr\_warning* : **t -> Warnings.t -> unit**

Same as **print\_warning** , but uses **!formatter\_for\_warnings** as output formatter.

## [Reporting alerts](#Reporting_alerts)

## [Converting an Alert.t into a report](#Converting_an_Alert.t_into_a_report)

*val report\_alert* : **t -> Warnings.alert -> report option**

**report\_alert loc w** produces a report for the given alert **w** , or **None** if the alert is not to be printed.

*val alert\_reporter* : **(t -> Warnings.alert -> report option) ref**

Hook for intercepting alerts.

*val default\_alert\_reporter* : **t -> Warnings.alert -> report option**

Original alert reporter for use in hooks.

## [Printing alerts](#Printing_alerts)

*val print\_alert* : **t -> Format.formatter -> Warnings.alert -> unit**

Prints an alert. This is simply the composition of **report\_alert** and **print\_report** .

*val prerr\_alert* : **t -> Warnings.alert -> unit**

Same as **print\_alert** , but uses **!formatter\_for\_warnings** as output formatter.

*val deprecated* : **?def:t -> ?use:t -> t -> string -> unit**

Prints a deprecation alert.

*val alert* : **?def:t ->** **?use:t -> kind:string -> t -> string -> unit**

Prints an arbitrary alert.

## [Reporting errors](#Reporting_errors)

*type error* = **report**

An **error** is a **report** which **report\_kind** must be **Report\_error** .

*val error* : **?loc:t -> ?sub:msg list -> string -> error**

*val errorf* : **?loc:t ->** **?sub:msg list ->** **('a, Format.formatter, unit, error) format4 -> 'a**

*val error\_of\_printer* : **?loc:t ->** **?sub:msg list ->** **(Format.formatter -> 'a -> unit) -> 'a -> error**

*val error\_of\_printer\_file* : **(Format.formatter -> 'a -> unit) -> 'a -> error**

## [Automatically reporting errors for raised exceptions](#Automatically_reporting_errors_for_raised_exceptions)

*val register\_error\_of\_exn* : **(exn -> error option) -> unit**

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).

*val error\_of\_exn* : **exn -> \[ \`Already\_displayed | \`Ok of error ] option**

*exception Error* **of** **error**

Raising **Error e** signals an error **e** ; the exception will be caught and the error will be printed.

*exception Already\_displayed\_error*

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 ->** **('a, Format.formatter, unit, 'b) format4 -> 'a**

*val report\_exception* : **Format.formatter -> exn -> unit**

Reraise the exception if it is unknown.

2026-09-15 OCamldoc

---

Document: Location(3o) from ocaml-4 4.14.4-r3 (Chainguard OS)
Source: https://github.com/ocaml/ocaml