doc/guide/localhost/MLBasisAnnotationExamples

   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>MLBasisAnnotationExamples</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>MLBasisAnnotationExamples</h1>
  27 </div>
  28 <div id="content">
  29 <div id="preamble">
  30 <div class="sectionbody">
  31 <div class="paragraph"><p>Here are some example uses of <a href="MLBasisAnnotations">MLBasisAnnotations</a>.</p></div>
  32 </div>
  33 </div>
  34 <div class="sect1">
  35 <h2 id="_eliminate_spurious_warnings_in_automatically_generated_code">Eliminate spurious warnings in automatically generated code</h2>
  36 <div class="sectionbody">
  37 <div class="paragraph"><p>Programs that automatically generate source code can often produce
  38 nonexhaustive patterns, relying on invariants of the generated code to
  39 ensure that the pattern matchings never fail.  A programmer may wish
  40 to elide the nonexhaustive warnings from this code, in order that
  41 legitimate warnings are not missed in a flurry of false positives.  To
  42 do so, the programmer simply annotates the generated code with the
  43 <span class="monospaced">nonexhaustiveBind ignore</span> and <span class="monospaced">nonexhaustiveMatch ignore</span>
  44 annotations:</p></div>
  45 <div class="listingblock">
  46 <div class="content monospaced">
  47 <pre>local
  48   $(GEN_ROOT)/gen-lib.mlb
  49
  50   ann
  51     "nonexhaustiveBind ignore"
  52     "nonexhaustiveMatch ignore"
  53   in
  54     foo.gen.sml
  55   end
  56 in
  57   signature FOO
  58   structure Foo
  59 end</pre>
  60 </div></div>
  61 </div>
  62 </div>
  63 <div class="sect1">
  64 <h2 id="_deliver_a_library">Deliver a library</h2>
  65 <div class="sectionbody">
  66 <div class="paragraph"><p>Standard ML libraries can be delivered via <span class="monospaced">.mlb</span> files.  Authors of
  67 such libraries should strive to be mindful of the ways in which
  68 programmers may choose to compile their programs.  For example,
  69 although the defaults for <span class="monospaced">sequenceNonUnit</span> and <span class="monospaced">warnUnused</span> are
  70 <span class="monospaced">ignore</span> and <span class="monospaced">false</span>, periodically compiling with these annotations
  71 defaulted to <span class="monospaced">warn</span> and <span class="monospaced">true</span> can help uncover likely bugs.  However,
  72 a programmer is unlikely to be interested in unused modules from an
  73 imported library, and the behavior of <span class="monospaced">sequenceNonUnit error</span> may be
  74 incompatible with some libraries.  Hence, a library author may choose
  75 to deliver a library as follows:</p></div>
  76 <div class="listingblock">
  77 <div class="content monospaced">
  78 <pre>ann
  79   "nonexhaustiveBind warn" "nonexhaustiveMatch warn"
  80   "redundantBind warn" "redundantMatch warn"
  81   "sequenceNonUnit warn"
  82   "warnUnused true" "forceUsed"
  83 in
  84   local
  85     file1.sml
  86     ...
  87     filen.sml
  88   in
  89     functor F1
  90     ...
  91     signature S1
  92     ...
  93     structure SN
  94     ...
  95   end
  96 end</pre>
  97 </div></div>
  98 <div class="paragraph"><p>The annotations <span class="monospaced">nonexhaustiveBind warn</span>, <span class="monospaced">redundantBind warn</span>,
  99 <span class="monospaced">nonexhaustiveMatch warn</span>, <span class="monospaced">redundantMatch warn</span>, and <span class="monospaced">sequenceNonUnit
 100 warn</span> have the obvious effect on elaboration.  The annotations
 101 <span class="monospaced">warnUnused true</span> and <span class="monospaced">forceUsed</span> work in conjunction&#8201;&#8212;&#8201;warning on
 102 any identifiers that do not contribute to the exported modules, and
 103 preventing warnings on exported modules that are not used in the
 104 remainder of the program.  Many of the
 105 <a href="MLBasisAvailableLibraries">available libraries</a> are delivered with
 106 these annotations.</p></div>
 107 </div>
 108 </div>
 109 </div>
 110 <div id="footnotes"><hr></div>
 111 <div id="footer">
 112 <div id="footer-text">
 113 </div>
 114 <div id="footer-badges">
 115 </div>
 116 </div>
 117 </body>
 118 </html>