10.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"]