Глава 12 Расширения языка

21 Предупреждения

• 21.1 Пометка компонента
• 21.2 Управление включенными предупреждениями
• 21.3 Сокращенный синтаксис для устаревания

(Добавлено в версии 4.08)

Начиная с OCaml 4.08, компоненты (например, объявления значений или типов) в сигнатурах можно помечать «предупреждениями», которые будут выдаваться при обращении к этим компонентам. Это обобщает понятие «устаревших» компонентов, о которых ранее сообщалось как о предупреждении 3. Такие предупреждения можно использовать, например, чтобы сообщать об использовании небезопасных возможностей или возможностей, доступных только на некоторых платформах и т. д.

Категории предупреждений задаются символьным идентификатором (идентификатором в нижнем регистре, соответствующим обычным лексическим правилам) и необязательным сообщением. Идентификатор используется для управления тем, какие предупреждения включены и какие из них превращаются в фатальные ошибки. Сообщение показывается пользователю при срабатывании предупреждения (то есть при обращении к помеченному компоненту).

Атрибут ocaml.alert или alert служит двум целям: (i) помечает компонент предупреждением, которое срабатывает при обращении к компоненту, и (ii) управляет тем, какие предупреждения включены.

21.1 Пометка компонента

При пометке компонента атрибут принимает идентификатор, за которым может следовать сообщение. Вот пример объявления значения, помеченного предупреждением:

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

Здесь unix — идентификатор предупреждения. Если эта категория предупреждений включена, любая ссылка на U.fork приведет к выводу сообщения во время компиляции, которое может быть или не быть преобразовано в фатальную ошибку.

Для других компонентов структур или сигнатур используется следующий синтаксис:

module type Sig = sig
  val v: int [@@alert name]
end

let v [@alert name] = 1
let `A (v [@alert name]) = `A 1

external e : int -> int = "c_function" [@@alert name]

type t1 = A | B [@@alert name]
(* N.B.: this only alerts on use of "t1", not uses of the constructors "A"
   and "B". So let x = A wouldn't alert, so long as you don't write down its
   type. *)

type t2 = A | B [@alert name]
(* Alerts on use of "B", but not "A" nor "t2". Note the single "@". *)

type t3 = { a : int; b : int [@alert name] }
(* Alerts on use of "b", but not "a" nor "t3". Note the single "@". *)

exception E of int [@alert name]
(* Alerts on use of "E". Note the single "@". *)

module M = struct end [@@alert name]
module type S = sig end [@@alert name]
class c1 = object end [@@alert name]
class type c2 = object end [@@alert name]

Когда система типов приводит сигнатуру с предупреждениями к сигнатуре с другими предупреждениями:

module M : sig
  val x : int
  val y : int [@@alert name]
end = struct
  let x [@alert name] = 0
  let y = 1
end

все предупреждения, которые не были переданы дальше, то есть предупреждение для x в этом примере, срабатывают.

Наконец, чтобы выдавать предупреждение при обращении к модулю, соответствующему файлу, плавающий атрибут можно указать в начале файла «.mli» (то есть до любых других элементов, не являющихся атрибутами) или в начале файла «.ml», если файла «.mli» нет:

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

21.2 Управление включенными предупреждениями

Управлять тем, какие предупреждения включены и превращаются ли они в фатальные ошибки, можно либо с помощью параметра командной строки компилятора -alert <spec>, либо локально в коде с помощью атрибута alert или ocaml.alert, принимающего единственную строку <spec>. В обоих случаях синтаксис <spec> представляет собой конкатенацию элементов следующего вида:

• +id включает предупреждение id.
• -id отключает предупреждение id.
• ++id превращает предупреждение id в фатальную ошибку.
• --id переводит предупреждение id в нефатальный режим.
• @id эквивалентно ++id+id (включает id и превращает его в фатальную ошибку)

В особом случае, если id — это all, он обозначает все предупреждения.

Вот несколько примеров:

(* 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

21.3 Сокращенный синтаксис для устаревания

До 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"]