第 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"]