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

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

(Введено в версии 4.08)

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

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

Атрибут ocaml.alert или alert служит двум целям: (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>, либо локально в коде с помощью атрибута 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

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