<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="AsciiDoc 8.6.8">
<title>MLBasisAnnotationExamples</title>
<link rel="stylesheet" href="./asciidoc.css" type="text/css">
<link rel="stylesheet" href="./pygments.css" type="text/css">


<script type="text/javascript" src="./asciidoc.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install();
/*]]>*/
</script>
<link rel="stylesheet" href="./mlton.css" type="text/css"/>
</head>
<body class="article">
<div id="banner">
<div id="banner-home">
<a href="./Home">MLton 20130715</a>
</div>
</div>
<div id="header">
<h1>MLBasisAnnotationExamples</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>Here are some example uses of <a href="MLBasisAnnotations">MLBasisAnnotations</a>.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_eliminate_spurious_warnings_in_automatically_generated_code">Eliminate spurious warnings in automatically generated code</h2>
<div class="sectionbody">
<div class="paragraph"><p>Programs that automatically generate source code can often produce
nonexhaustive matches, relying on invariants of the generated code to
ensure that the matches never fail.  A programmer may wish to elide
the nonexhaustive match warnings from this code, in order that
legitimate warnings are not missed in a flurry of false positives.  To
do so, the programmer simply annotates the generated code with the
<span class="monospaced">nonexhaustiveMatch ignore</span> annotation:</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>local
  $(GEN_ROOT)/gen-lib.mlb

  ann "nonexhaustiveMatch ignore" in
    foo.gen.sml
  end
in
  signature FOO
  structure Foo
end</pre>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_deliver_a_library">Deliver a library</h2>
<div class="sectionbody">
<div class="paragraph"><p>Standard ML libraries can be delivered via <span class="monospaced">.mlb</span> files.  Authors of
such libraries should strive to be mindful of the ways in which
programmers may choose to compile their programs.  For example,
although the defaults for <span class="monospaced">sequenceNonUnit</span> and <span class="monospaced">warnUnused</span> are
<span class="monospaced">ignore</span> and <span class="monospaced">false</span>, periodically compiling with these annotations
defaulted to <span class="monospaced">warn</span> and <span class="monospaced">true</span> can help uncover likely bugs.  However,
a programmer is unlikely to be interested in unused modules from an
imported library, and the behavior of <span class="monospaced">sequenceNonUnit error</span> may be
incompatible with some libraries.  Hence, a library author may choose
to deliver a library as follows:</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>ann
  "nonexhaustiveMatch warn" "redundantMatch warn"
  "sequenceNonUnit warn"
  "warnUnused true" "forceUsed"
in
  local
    file1.sml
    ...
    filen.sml
  in
    functor F1
    ...
    signature S1
    ...
    structure SN
    ...
  end
end</pre>
</div></div>
<div class="paragraph"><p>The annotations <span class="monospaced">nonexhaustiveMatch warn</span>, <span class="monospaced">redundantMatch warn</span>, and
<span class="monospaced">sequenceNonUnit warn</span> have the obvious effect on elaboration.  The
annotations <span class="monospaced">warnUnused true</span> and <span class="monospaced">forceUsed</span> work in conjunction&#8201;&#8212;&#8201;warning on any identifiers that do not contribute to the exported
modules, and preventing warnings on exported modules that are not used
in the remainder of the program.  Many of the
<a href="MLBasisAvailableLibraries">available libraries</a> are delivered with
these annotations.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr></div>
<div id="footer">
<div id="footer-text">
</div>
<div id="footer-badges">
</div>
</div>
</body>
</html>
