Location(3) OCaml library Location(3) NAME Location - Source code locations (ranges of positions), used in parsetree. Module Module Location 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 val input_name : string ref val input_lexbuf : Lexing.lexbuf option ref val input_phrase_buffer : Buffer.t option ref Toplevel-specific functions val echo_eof : unit -> unit val separate_new_message : Format.formatter -> unit val reset : unit -> unit Rewriting path val rewrite_absolute_path : string -> string rewrite_absolute_path path rewrites path to honor the BUILD_PATH_PREFIX_MAP variable if it is set. It does not check whether path is absolute or not. The result is as follows: -If BUILD_PATH_PREFIX_MAP is not set, just return path . -otherwise, rewrite using the mapping (and if there are no matching prefixes that will just return path ). See the BUILD_PATH_PREFIX_MAP spec val rewrite_find_first_existing : string -> string option rewrite_find_first_existing path uses a BUILD_PATH_PREFIX_MAP mapping and tries to find a source in mapping that maps to a result that exists in the file system. There are the following return values: - None , means either -BUILD_PATH_PREFIX_MAP is not set and path does not exists, or -no source prefixes of path in the mapping were found, - Some target , means target exists and either -BUILD_PATH_PREFIX_MAP is not set and target = path , or - target is the first file (in priority order) that path mapped to that exists in the file system. - Not_found raised, means some source prefixes in the map were found that matched path , but none of them existed in the file system. The caller should catch this and issue an appropriate error message. See the BUILD_PATH_PREFIX_MAP spec val rewrite_find_all_existing_dirs : string -> string list rewrite_find_all_existing_dirs dir accumulates a list of existing directories, dirs , that are the result of mapping a potentially abstract directory, dir , over all the mapping pairs in the BUILD_PATH_PREFIX_MAP environment variable, if any. The list dirs will be in priority order (head as highest priority). The possible results are: - [] , means either -BUILD_PATH_PREFIX_MAP is not set and dir is not an existing directory, or -if set, then there were no matching prefixes of dir . - Some dirs , means dirs are the directories found. Either -BUILD_PATH_PREFIX_MAP is not set and dirs = [dir] , or -it was set and dirs are the mapped existing directories. -Not_found raised, means some source prefixes in the map were found that matched dir , but none of mapping results were existing directories (possibly due to misconfiguration). The caller should catch this and issue an appropriate error message. See the BUILD_PATH_PREFIX_MAP spec val absolute_path : string -> string absolute_path path first makes an absolute path, s from path , prepending the current working directory if path was relative. Then s is rewritten using rewrite_absolute_path . Finally the result is normalized by eliminating instances of '.' or '..' . Printing locations 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 val highlight_terminfo : Lexing.lexbuf -> Format.formatter -> t list -> unit Reporting errors and warnings 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 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 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 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 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 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 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. val auto_include_alert : string -> unit Prints an alert that -I +lib has been automatically added to the load path val deprecated_script_alert : string -> unit deprecated_script_alert command prints an alert that command foo has been deprecated in favour of command ./foo 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 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. OCamldoc 2024-02-29 Location(3)