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