第 12 章 語言擴展

21 警示

(於 4.08 版本引入)

自 OCaml 4.08 版本起,可以在簽名中標記元件(例如值或類型宣告)為「警示」,當這些元件被引用時會回報。這概括了先前作為警告 3 回報的「已棄用」元件的概念。這些警示可用於回報不安全功能的使用,或僅在某些平台上可用的功能等。

警示類別由符號識別符號(小寫識別符號,遵循一般的詞彙規則)和可選的訊息來識別。識別符號用於控制啟用哪些警示,以及將哪些警示轉換為致命錯誤。當觸發警示時(即引用標記的元件時),訊息會回報給使用者。

ocaml.alertalert 屬性有兩個用途:(i) 標記元件,當元件被引用時會觸發警示,以及 (ii) 控制啟用哪些警示名稱。在第一種形式中,屬性會採用一個識別符號,後面可能跟著一個訊息。以下是一個以警示標記的值宣告範例

module U: sig
  val fork: unit -> bool
    [@@alert unix "This function is only available under Unix."]
end

這裡 unix 是警示的識別符號。如果啟用此警示類別,則任何對 U.fork 的引用都會在編譯時產生訊息,該訊息可以轉換為致命錯誤或不轉換。

以下是另一個範例,作為位於 ".mli" 檔案頂部(即在任何其他非屬性項目之前)或沒有對應介面檔案的 ".ml" 檔案頂部的浮動屬性,以便任何對該單元的引用都會觸發警示

[@@@alert unsafe "This module is unsafe!"]

控制啟用哪些警示以及是否將它們轉換為致命錯誤,可以透過編譯器的命令列選項 -alert <spec> 或透過程式碼中的 alertocaml.alert 屬性(採用單一字串負載 <spec>)來完成。在這兩種情況下,<spec> 的語法是以下形式的項目串聯

在特殊情況下,如果 idall,則代表所有警示。

以下是一些範例

(* Disable all alerts, reenables just unix (as a soft alert) and window
   (as a fatal-error), for the rest of the current structure *)

[@@@alert "-all--all+unix@window"]
 ...

let x =
  (* Locally disable the window alert *)
  begin[@alert "-window"]
      ...
  end

在 OCaml 4.08 之前,只支援單一種類的棄用警示。它現在稱為 deprecated 警示,但觸發它的傳統屬性和將其控制為警告 3 的傳統方式仍然支援。例如,在命令列上傳遞 -w +3 等同於 -alert +deprecated,而

val x: int
  [@@ocaml.deprecated "Please do something else"]

等同於

val x: int
  [@@ocaml.alert deprecated "Please do something else"]