1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="hevea 2.32">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
<link rel="stylesheet" type="text/css" href="manual.css">
<title>8.21 Alerts</title>
</head>
<body>
<a href="emptyvariants.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="extn.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="generalizedopens.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h2 class="section" id="s:alerts"><a class="section-anchor" href="#s:alerts" aria-hidden="true"></a>8.21 Alerts</h2>
<p>
(Introduced in 4.08)</p><p>Since OCaml 4.08, it is possible to mark components (such as value or
type declarations) in signatures with “alerts” that will be reported
when those components are referenced. This generalizes the notion of
“deprecated” components which were previously reported as warning 3.
Those alerts can be used for instance to report usage of unsafe
features, or of features which are only available on some platforms,
etc.</p><p>Alert categories are identified by a symbolic identifier (a lowercase
identifier, following the usual lexical rules) and an optional
message. The identifier is used to control which alerts are enabled,
and which ones are turned into fatal errors. The message is reported
to the user when the alert is triggered (i.e. when the marked
component is referenced).</p><p>The <span class="c003">ocaml.alert</span> or <span class="c003">alert</span> attribute serves two purposes: (i) to
mark component with an alert to be triggered when the component is
referenced, and (ii) to control which alert names are enabled. In the
first form, the attribute takes an identifier possibly
followed by a message. Here is an example of a value declaration marked
with an alert:</p><pre>module U: sig
val fork: unit -> bool
[@@alert unix "This function is only available under Unix."]
end
</pre><p>
Here <span class="c003">unix</span> is the identifier for the alert. If this alert category
is enabled, any reference to <span class="c003">U.fork</span> will produce a message at
compile time, which can be turned or not into a fatal error.</p><p>And here is another example as a floating attribute on top
of an “.mli” file (i.e. before any other non-attribute item)
or on top of an “.ml” file without a corresponding interface file,
so that any reference to that unit will trigger the alert:</p><pre>[@@@alert unsafe "This module is unsafe!"]
</pre><p>Controlling which alerts are enabled and whether they are turned into
fatal errors is done either through the compiler’s command-line option
<span class="c003">-alert <spec></span> or locally in the code through the <span class="c003">alert</span> or
<span class="c003">ocaml.alert</span> attribute taking a single string payload <span class="c003"><spec></span>. In
both cases, the syntax for <span class="c003"><spec></span> is a concatenation of items of the
form:</p><ul class="itemize"><li class="li-itemize">
<span class="c003">+id</span> enables alert <span class="c003">id</span>.
</li><li class="li-itemize"><span class="c003">-id</span> disables alert <span class="c003">id</span>.
</li><li class="li-itemize"><span class="c003">++id</span> turns alert <span class="c003">id</span> into a fatal error.
</li><li class="li-itemize"><span class="c003">--id</span> turns alert <span class="c003">id</span> into non-fatal mode.
</li><li class="li-itemize"><span class="c003">@id</span> equivalent to <span class="c003">++id+id</span> (enables <span class="c003">id</span> and turns it into a fatal-error)
</li></ul><p>As a special case, if <span class="c003">id</span> is <span class="c003">all</span>, it stands for all alerts.</p><p>Here are some examples:</p><pre>
(* 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
</pre><p>
Before OCaml 4.08, there was support for a single kind of deprecation
alert. It is now known as the <span class="c003">deprecated</span> alert, but legacy
attributes to trigger it and the legacy ways to control it as warning
3 are still supported. For instance, passing <span class="c003">-w +3</span> on the
command-line is equivant to <span class="c003">-alert +deprecated</span>, and:</p><pre>val x: int
[@@@ocaml.deprecated "Please do something else"]
</pre><p>
is equivalent to:</p><pre>val x: int
[@@@ocaml.alert deprecated "Please do something else"]
</pre>
<hr>
<a href="emptyvariants.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="extn.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="generalizedopens.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>
|
