doc/guide/localhost/MLBasisAnnotations

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta name="generator" content="AsciiDoc 8.6.9">
   6 <title>MLBasisAnnotations</title>
   7 <link rel="stylesheet" href="./asciidoc.css" type="text/css">
   8 <link rel="stylesheet" href="./pygments.css" type="text/css">
   9
  10
  11 <script type="text/javascript" src="./asciidoc.js"></script>
  12 <script type="text/javascript">
  13 /*<![CDATA[*/
  14 asciidoc.install();
  15 /*]]>*/
  16 </script>
  17 <link rel="stylesheet" href="./mlton.css" type="text/css">
  18 </head>
  19 <body class="article">
  20 <div id="banner">
  21 <div id="banner-home">
  22 <a href="./Home">MLton 20180207</a>
  23 </div>
  24 </div>
  25 <div id="header">
  26 <h1>MLBasisAnnotations</h1>
  27 </div>
  28 <div id="content">
  29 <div id="preamble">
  30 <div class="sectionbody">
  31 <div class="paragraph"><p><a href="MLBasis">ML Basis</a> annotations control options that affect the
  32 elaboration of SML source files.  Conceptually, a basis file is
  33 elaborated in a default annotation environment (just as it is
  34 elaborated in an empty basis).  The declaration
  35 <span class="monospaced">ann</span>&#160;<span class="monospaced">"</span><em>ann</em><span class="monospaced">"</span>&#160;<span class="monospaced">in</span>&#160;<em>basdec</em>&#160;<span class="monospaced">end</span>
  36 merges the annotation <em>ann</em> with the "current" annotation environment
  37 for the elaboration of <em>basdec</em>.  To allow for future expansion,
  38 <span class="monospaced">"</span><em>ann</em><span class="monospaced">"</span> is lexed as a single SML string constant.  To
  39 conveniently specify multiple annotations, the following derived form
  40 is provided:</p></div>
  41 <div class="sidebarblock">
  42 <div class="content">
  43 <div class="paragraph"><p><span class="monospaced">ann</span> <span class="monospaced">"</span><em>ann</em><span class="monospaced">"</span> (<span class="monospaced">"</span><em>ann</em><span class="monospaced">"</span> )<sup>+</sup> <span class="monospaced">in</span> <em>basdec</em> <span class="monospaced">end</span>
  44 &#8658;
  45 <span class="monospaced">ann</span> <span class="monospaced">"</span><em>ann</em><span class="monospaced">"</span> <span class="monospaced">in</span> <span class="monospaced">ann</span> (<span class="monospaced">"</span><em>ann</em><span class="monospaced">"</span>)<sup>+</sup> <span class="monospaced">in</span> <em>basdec</em> <span class="monospaced">end</span> <span class="monospaced">end</span></p></div>
  46 </div></div>
  47 <div class="paragraph"><p>Here are the available annotations.  In the explanation below, for
  48 annotations that take an argument, the first value listed is the
  49 default.</p></div>
  50 <div class="ulist"><ul>
  51 <li>
  52 <p>
  53 <span class="monospaced">allowFFI {false|true}</span>
  54 </p>
  55 <div class="paragraph"><p>If <span class="monospaced">true</span>, allow <span class="monospaced">_address</span>, <span class="monospaced">_export</span>, <span class="monospaced">_import</span>, and <span class="monospaced">_symbol</span>
  56 expressions to appear in source files.  See
  57 <a href="ForeignFunctionInterface">ForeignFunctionInterface</a>.</p></div>
  58 </li>
  59 <li>
  60 <p>
  61 <span class="monospaced">allowSuccessorML {false|true}</span>
  62 </p>
  63 <div class="openblock">
  64 <div class="content">
  65 <div class="paragraph"><p>Allow or disallow all of the <a href="SuccessorML">SuccessorML</a> features.  This is a
  66 proxy for all of the following annotations.</p></div>
  67 <div class="ulist"><ul>
  68 <li>
  69 <p>
  70 <span class="monospaced">allowDoDecls {false|true}</span>
  71 </p>
  72 <div class="paragraph"><p>If <span class="monospaced">true</span>, allow a <span class="monospaced">do <em>exp</em></span> declaration form.</p></div>
  73 </li>
  74 <li>
  75 <p>
  76 <span class="monospaced">allowExtendedConsts {false|true}</span>
  77 </p>
  78 <div class="openblock">
  79 <div class="content">
  80 <div class="paragraph"><p>Allow or disallow all of the extended constants features.  This is a
  81 proxy for all of the following annotations.</p></div>
  82 <div class="ulist"><ul>
  83 <li>
  84 <p>
  85 <span class="monospaced">allowExtendedNumConsts {false|true}</span>
  86 </p>
  87 <div class="paragraph"><p>If <span class="monospaced">true</span>, allow extended numeric constants.</p></div>
  88 </li>
  89 <li>
  90 <p>
  91 <span class="monospaced">allowExtendedTextConsts {false|true}</span>
  92 </p>
  93 <div class="paragraph"><p>If <span class="monospaced">true</span>, allow extended text constants.</p></div>
  94 </li>
  95 </ul></div>
  96 </div></div>
  97 </li>
  98 <li>
  99 <p>
 100 <span class="monospaced">allowLineComments {false|true}</span>
 101 </p>
 102 <div class="paragraph"><p>If <span class="monospaced">true</span>, allow line comments beginning with the token <span class="monospaced">(*)</span>.</p></div>
 103 </li>
 104 <li>
 105 <p>
 106 <span class="monospaced">allowOptBar {false|true}</span>
 107 </p>
 108 <div class="paragraph"><p>If <span class="monospaced">true</span>, allow a bar to appear before the first match rule of a
 109 <span class="monospaced">case</span>, <span class="monospaced">fn</span>, or <span class="monospaced">handle</span> expression, allow a bar to appear before the
 110 first function-value binding of a <span class="monospaced">fun</span> declaration, and allow a bar
 111 to appear before the first constructor binding or description of a
 112 <span class="monospaced">datatype</span> declaration or specification.</p></div>
 113 </li>
 114 <li>
 115 <p>
 116 <span class="monospaced">allowOptSemicolon {false|true}</span>
 117 </p>
 118 <div class="paragraph"><p>If <span class="monospaced">true</span>, allows a semicolon to appear after the last expression in a
 119 sequence expression or <span class="monospaced">let</span> body.</p></div>
 120 </li>
 121 <li>
 122 <p>
 123 <span class="monospaced">allowOrPats {false|true}</span>
 124 </p>
 125 <div class="paragraph"><p>If <span class="monospaced">true</span>, allows disjunctive (a.k.a., "or") patterns of the form
 126 <span class="monospaced"><em>pat</em> | <em>pat</em></span>.</p></div>
 127 </li>
 128 <li>
 129 <p>
 130 <span class="monospaced">allowRecordPunExps {false|true}</span>
 131 </p>
 132 <div class="paragraph"><p>If <span class="monospaced">true</span>, allows record punning expressions.</p></div>
 133 </li>
 134 <li>
 135 <p>
 136 <span class="monospaced">allowSigWithtype {false|true}</span>
 137 </p>
 138 <div class="paragraph"><p>If <span class="monospaced">true</span>, allows <span class="monospaced">withtype</span> to modify a <span class="monospaced">datatype</span> specification in a
 139 signature.</p></div>
 140 </li>
 141 <li>
 142 <p>
 143 <span class="monospaced">allowVectorExpsAndPats {false|true}</span>
 144 </p>
 145 <div class="openblock">
 146 <div class="content">
 147 <div class="paragraph"><p>Allow or disallow vector expressions and vector patterns.  This is a
 148 proxy for all of the following annotations.</p></div>
 149 <div class="ulist"><ul>
 150 <li>
 151 <p>
 152 <span class="monospaced">allowVectorExps {false|true}</span>
 153 </p>
 154 <div class="paragraph"><p>If <span class="monospaced">true</span>, allow vector expressions.</p></div>
 155 </li>
 156 <li>
 157 <p>
 158 <span class="monospaced">allowVectorPats {false|true}</span>
 159 </p>
 160 <div class="paragraph"><p>If <span class="monospaced">true</span>, allow vector patterns.</p></div>
 161 </li>
 162 </ul></div>
 163 </div></div>
 164 </li>
 165 </ul></div>
 166 </div></div>
 167 </li>
 168 <li>
 169 <p>
 170 <span class="monospaced">forceUsed</span>
 171 </p>
 172 <div class="paragraph"><p>Force all identifiers in the basis denoted by the body of the <span class="monospaced">ann</span> to
 173 be considered used; use in conjunction with <span class="monospaced">warnUnused true</span>.</p></div>
 174 </li>
 175 <li>
 176 <p>
 177 <span class="monospaced">nonexhaustiveBind {warn|error|ignore}</span>
 178 </p>
 179 <div class="paragraph"><p>If <span class="monospaced">error</span> or <span class="monospaced">warn</span>, report nonexhaustive patterns in <span class="monospaced">val</span>
 180 declarations (i.e., pattern-match failures that raise the <span class="monospaced">Bind</span>
 181 exception).  An error will abort a compile, while a warning will not.</p></div>
 182 </li>
 183 <li>
 184 <p>
 185 <span class="monospaced">nonexhaustiveExnBind {default|ignore}</span>
 186 </p>
 187 <div class="paragraph"><p>If <span class="monospaced">ignore</span>, suppress errors and warnings about nonexhaustive matches
 188 in <span class="monospaced">val</span> declarations that arise solely from unmatched exceptions.
 189 If <span class="monospaced">default</span>, follow the behavior of <span class="monospaced">nonexhaustiveBind</span>.</p></div>
 190 </li>
 191 <li>
 192 <p>
 193 <span class="monospaced">nonexhaustiveExnMatch {default|ignore}</span>
 194 </p>
 195 <div class="paragraph"><p>If <span class="monospaced">ignore</span>, suppress errors and warnings about nonexhaustive matches
 196 in <span class="monospaced">fn</span> expressions, <span class="monospaced">case</span> expressions, and <span class="monospaced">fun</span> declarations that
 197 arise solely from unmatched exceptions.  If <span class="monospaced">default</span>, follow the
 198 behavior of <span class="monospaced">nonexhaustiveMatch</span>.</p></div>
 199 </li>
 200 <li>
 201 <p>
 202 <span class="monospaced">nonexhaustiveExnRaise {ignore|default}</span>
 203 </p>
 204 <div class="paragraph"><p>If <span class="monospaced">ignore</span>, suppress errors and warnings about nonexhaustive matches
 205 in <span class="monospaced">handle</span> expressions that arise solely from unmatched exceptions.
 206 If <span class="monospaced">default</span>, follow the behavior of <span class="monospaced">nonexhaustiveRaise</span>.</p></div>
 207 </li>
 208 <li>
 209 <p>
 210 <span class="monospaced">nonexhaustiveMatch {warn|error|ignore}</span>
 211 </p>
 212 <div class="paragraph"><p>If <span class="monospaced">error</span> or <span class="monospaced">warn</span>, report nonexhaustive patterns in <span class="monospaced">fn</span>
 213 expressions, <span class="monospaced">case</span> expressions, and <span class="monospaced">fun</span> declarations (i.e.,
 214 pattern-match failures that raise the <span class="monospaced">Match</span> exception).  An error
 215 will abort a compile, while a warning will not.</p></div>
 216 </li>
 217 <li>
 218 <p>
 219 <span class="monospaced">nonexhaustiveRaise {ignore|warn|error}</span>
 220 </p>
 221 <div class="paragraph"><p>If <span class="monospaced">error</span> or <span class="monospaced">warn</span>, report nonexhaustive patterns in <span class="monospaced">handle</span>
 222 expressions (i.e., pattern-match failures that implicitly (re)raise
 223 the unmatched exception).  An error will abort a compile, while a
 224 warning will not.</p></div>
 225 </li>
 226 <li>
 227 <p>
 228 <span class="monospaced">redundantBind {warn|error|ignore}</span>
 229 </p>
 230 <div class="paragraph"><p>If <span class="monospaced">error</span> or <span class="monospaced">warn</span>, report redundant patterns in <span class="monospaced">val</span> declarations.
 231 An error will abort a compile, while a warning will not.</p></div>
 232 </li>
 233 <li>
 234 <p>
 235 <span class="monospaced">redundantMatch {warn|error|ignore}</span>
 236 </p>
 237 <div class="paragraph"><p>If <span class="monospaced">error</span> or <span class="monospaced">warn</span>, report redundant patterns in <span class="monospaced">fn</span> expressions,
 238 <span class="monospaced">case</span> expressions, and <span class="monospaced">fun</span> declarations.  An error will abort a
 239 compile, while a warning will not.</p></div>
 240 </li>
 241 <li>
 242 <p>
 243 <span class="monospaced">redundantRaise {warn|error|ignore}</span>
 244 </p>
 245 <div class="paragraph"><p>If <span class="monospaced">error</span> or <span class="monospaced">warn</span>, report redundant patterns in <span class="monospaced">handle</span>
 246 expressions.  An error will abort a compile, while a warning will not.</p></div>
 247 </li>
 248 <li>
 249 <p>
 250 <span class="monospaced">resolveScope {strdec|dec|topdec|program}</span>
 251 </p>
 252 <div class="paragraph"><p>Used to control the scope at which overload constraints are resolved
 253 to default types (if not otherwise resolved by type inference) and the
 254 scope at which unresolved flexible record constraints are reported.</p></div>
 255 <div class="paragraph"><p>The syntactic-class argument means to perform resolution checks at the
 256 smallest enclosing syntactic form of the given class.  The default
 257 behavior is to resolve at the smallest enclosing <em>strdec</em> (which is
 258 equivalent to the largest enclosing <em>dec</em>).  Other useful behaviors
 259 are to resolve at the smallest enclosing <em>topdec</em> (which is equivalent
 260 to the largest enclosing <em>strdec</em>) and at the smallest enclosing
 261 <em>program</em> (which corresponds to a single <span class="monospaced">.sml</span> file and does not
 262 correspond to the whole <span class="monospaced">.mlb</span> program).</p></div>
 263 </li>
 264 <li>
 265 <p>
 266 <span class="monospaced">sequenceNonUnit {ignore|error|warn}</span>
 267 </p>
 268 <div class="paragraph"><p>If <span class="monospaced">error</span> or <span class="monospaced">warn</span>, report when <span class="monospaced">e1</span> is not of type <span class="monospaced">unit</span> in the
 269 sequence expression <span class="monospaced">(e1; e2)</span>.  This can be helpful in detecting
 270 curried applications that are mistakenly not fully applied.  To
 271 silence spurious messages, you can use <span class="monospaced">ignore e1</span>.</p></div>
 272 </li>
 273 <li>
 274 <p>
 275 <span class="monospaced">valrecConstr {warn|error|ignore}</span>
 276 </p>
 277 <div class="paragraph"><p>If <span class="monospaced">error</span> or <span class="monospaced">warn</span>, report when a <span class="monospaced">val rec</span> (or <span class="monospaced">fun</span>) declaration
 278 redefines an identifier that previously had constructor status.  An
 279 error will abort a compile, while a warning will not.</p></div>
 280 </li>
 281 <li>
 282 <p>
 283 <span class="monospaced">warnUnused {false|true}</span>
 284 </p>
 285 <div class="paragraph"><p>Report unused identifiers.</p></div>
 286 </li>
 287 </ul></div>
 288 </div>
 289 </div>
 290 <div class="sect1">
 291 <h2 id="_next_steps">Next Steps</h2>
 292 <div class="sectionbody">
 293 <div class="ulist"><ul>
 294 <li>
 295 <p>
 296 <a href="MLBasisAnnotationExamples">MLBasisAnnotationExamples</a>
 297 </p>
 298 </li>
 299 <li>
 300 <p>
 301 <a href="WarnUnusedAnomalies">WarnUnusedAnomalies</a>
 302 </p>
 303 </li>
 304 </ul></div>
 305 </div>
 306 </div>
 307 </div>
 308 <div id="footnotes"><hr></div>
 309 <div id="footer">
 310 <div id="footer-text">
 311 </div>
 312 <div id="footer-badges">
 313 </div>
 314 </div>
 315 </body>
 316 </html>