模組 Location

module Location: sig .. end

原始碼位置（位置範圍），用於 parsetree 中。

警告：此模組不穩定，是 compiler-libs 的一部分。

type t = Warnings.loc = {
   loc_start : Lexing.position;
   loc_end : Lexing.position;
   loc_ghost : bool;
}

關於在此模組中使用 Lexing.position 的注意事項。如果 pos_fname = ""，則改用 !input_name。如果 pos_lnum = -1，則 pos_bol = 0。使用 pos_cnum 並重新剖析檔案以取得行號和字元號。否則所有欄位都是正確的。

val none : t

類型為 t 的任意值；描述一個空的虛擬範圍。

val is_none : t -> bool

對於 Location.none 為 true，對於任何其他位置為 false

val in_file : string -> t

傳回位於指定檔案中的空虛擬範圍。

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

將 lexbuf 的檔案名稱和行號設定為指定檔案的開頭。

val curr : Lexing.lexbuf -> t

從 lexbuf 取得目前語法的標記位置。

val symbol_rloc : unit -> t
val symbol_gloc : unit -> t
val rhs_loc : int -> t

rhs_loc n 會傳回目前剖析器規則中位置 n（從 1 開始）的符號位置。

val rhs_interval : int -> int -> t
val get_pos_info : Lexing.position -> string * int * int

檔案、行、字元

type 'a loc = {
   txt : 'a;
   loc : t;
} 
val mknoloc : 'a -> 'a loc
val mkloc : 'a -> t -> 'a loc

輸入資訊

val input_name : string ref
val input_lexbuf : Lexing.lexbuf option ref
val input_phrase_buffer : Buffer.t option ref

頂層專用函式

val echo_eof : unit -> unit
val separate_new_message : Format.formatter -> unit
val reset : unit -> unit

重寫路徑

val rewrite_absolute_path : string -> string

rewrite_absolute_path path 會重寫 path 以符合 BUILD_PATH_PREFIX_MAP 變數（如果已設定）。它不會檢查 path 是否為絕對路徑。結果如下

  • 如果未設定 BUILD_PATH_PREFIX_MAP，則只傳回 path。
  • 否則，使用對應關係進行重寫（如果沒有符合的前置詞，則只會傳回 path）。

請參閱 BUILD_PATH_PREFIX_MAP 規格

val rewrite_find_first_existing : string -> string option

rewrite_find_first_existing path 使用 BUILD_PATH_PREFIX_MAP 對應關係，並嘗試在對應關係中尋找對應到檔案系統中存在之結果的來源。傳回值如下

  • None，表示
    • 未設定 BUILD_PATH_PREFIX_MAP 且 path 不存在，或
    • 在對應關係中找不到 path 的來源前置詞，
  • Some target，表示 target 存在，且
    • 未設定 BUILD_PATH_PREFIX_MAP 且 target = path，或
    • target 是 path 對應到的檔案系統中存在的（依優先順序）第一個檔案。
  • 引發 Not_found，表示找到對應關係中與 path 符合的某些來源前置詞，但它們在檔案系統中都不存在。呼叫者應捕捉此情況並發出適當的錯誤訊息。

請參閱 BUILD_PATH_PREFIX_MAP 規格

val rewrite_find_all_existing_dirs : string -> string list

rewrite_find_all_existing_dirs dir 會累積現有目錄的清單 dirs，這些目錄是將潛在的抽象目錄 dir，套用到 BUILD_PATH_PREFIX_MAP 環境變數（如果有的話）中的所有對應配對的結果。清單 dirs 將會依優先順序排列（head 為最高優先順序）。

可能的結果如下

  • []，表示
    • 未設定 BUILD_PATH_PREFIX_MAP 且 dir 不是現有目錄，或
    • 如果已設定，則沒有與 dir 符合的前置詞。
  • Some dirs，表示 dirs 是找到的目錄。表示
    • 未設定 BUILD_PATH_PREFIX_MAP 且 dirs = [dir]，或
    • 已設定，且 dirs 是對應到的現有目錄。
  • 引發 Not_found，表示找到對應關係中與 dir 符合的某些來源前置詞，但沒有任何對應結果是現有目錄（可能是由於組態錯誤）。呼叫者應捕捉此情況並發出適當的錯誤訊息。

請參閱 BUILD_PATH_PREFIX_MAP 規格

val absolute_path : string -> string

absolute_path path 會先從 path 建立絕對路徑 s，如果 path 是相對路徑，則會加上目前的工作目錄。然後使用 rewrite_absolute_path 重寫 s。最後，結果會經過正規化，以消除 '.' 或 '..' 的執行個體。

列印位置

val show_filename : string -> string

在 -absname 模式中，傳回此檔案名稱的絕對路徑。否則，傳回未變更的檔案名稱。

val print_filename : Format.formatter -> string -> unit
val print_loc : Format.formatter -> t -> unit
val print_locs : Format.formatter -> t list -> unit

頂層專用位置醒目提示

val highlight_terminfo : Lexing.lexbuf -> Format.formatter -> t list -> unit

回報錯誤和警告

報告類型和報告印表機

type msg = (Format.formatter -> unit) loc 
val msg : ?loc:t ->
       ('a, Format.formatter, unit, msg) format4 -> 'a
type report_kind =
| 回報錯誤
| 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;
}

用於 report 的印表機，使用開放式遞迴定義。目標是透過重複使用現有印表機的程式碼，輕鬆定義新的印表機。

編譯器中使用的報告印表機

val batch_mode_printer : report_printer
val terminfo_toplevel_printer : Lexing.lexbuf -> report_printer
val best_toplevel_printer : unit -> report_printer

偵測終端機功能並選取適當的印表機

列印 report

val print_report : Format.formatter -> report -> unit

顯示錯誤或警告報告。

val report_printer : (unit -> report_printer) ref

重新定義報告印表機的 Hook。

Hook 是一個 unit -> report_printer，而不單單是一個 report_printer：這很有用，因為它可以偵測輸出類型（檔案、終端機...）並據此選取印表機。

val default_report_printer : unit -> report_printer

用於 Hook 的原始報告印表機。

回報警告

將 Warnings.t 轉換為 report

val report_warning : t -> Warnings.t -> report option

report_warning loc w 會針對指定的警告 w 產生報告，如果警告不應列印，則產生 None。

val warning_reporter : (t -> Warnings.t -> report option) ref

攔截警告的 Hook。

val default_warning_reporter : t -> Warnings.t -> report option

用於 Hook 的原始警告回報器。

列印警告

val formatter_for_warnings : Format.formatter ref
val print_warning : t -> Format.formatter -> Warnings.t -> unit

列印警告。這只是 report_warning 和 print_report 的組合。

val prerr_warning : t -> Warnings.t -> unit

與 print_warning 相同，但使用 !formatter_for_warnings 作為輸出格式器。

回報提示

將 Alert.t 轉換為 report

val report_alert : t -> Warnings.alert -> report option

report_alert loc w 會針對指定的提示 w 產生報告，如果提示不應列印，則產生 None。

val alert_reporter : (t -> Warnings.alert -> report option) ref

攔截提示的 Hook。

val default_alert_reporter : t -> Warnings.alert -> report option

用於 Hook 的原始提示回報器。

列印提示

val print_alert : t -> Format.formatter -> Warnings.alert -> unit

列印提示。這只是 report_alert 和 print_report 的組合。

val prerr_alert : t -> Warnings.alert -> unit

與 print_alert 相同，但使用 !formatter_for_warnings 作為輸出格式器。

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

列印淘汰提示。

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

列印任意提示。

val auto_include_alert : string -> unit

列印已自動將 -I +lib 新增至載入路徑的提示

val deprecated_script_alert : string -> unit

deprecated_script_alert command 會列印一則提示，指出 command foo 已淘汰，改用 command ./foo

回報錯誤

type error = report

error 是一個 report，其 report_kind 必須是 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

自動回報引發例外狀況的錯誤

val register_error_of_exn : (exn -> error option) -> unit

每個定義可做為使用者可見錯誤的自訂例外狀況類型的編譯器模組都應該使用 register_error_of_exn 註冊此例外狀況的「印表機」。印表機的結果是一個 error 值，其中包含位置、訊息，以及選擇性的子訊息（每個子訊息也都有位置）。

val error_of_exn : exn -> [ `Already_displayed | `Ok of error ] option
exception Error of error

引發 Error e 表示錯誤 e；例外狀況會被捕捉，並且會列印錯誤。

exception Already_displayed_error

引發 Already_displayed_error 表示已列印的錯誤。例外狀況會被捕捉，但不會列印任何內容

val raise_errorf : ?loc:t ->
       ?sub:msg list ->
       ('a, Format.formatter, unit, 'b) format4 -> 'a
val report_exception : Format.formatter -> exn -> unit

如果例外狀況不明，則重新引發例外狀況。