doc/guide/localhost/MLBasisExamples

   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>MLBasisExamples</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>MLBasisExamples</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="MLBasis">ML Basis</a> files.</p></div>
  32 </div>
  33 </div>
  34 <div class="sect1">
  35 <h2 id="_complete_program">Complete program</h2>
  36 <div class="sectionbody">
  37 <div class="paragraph"><p>Suppose your complete program consists of the files <span class="monospaced">file1.sml</span>, &#8230;,
  38 <span class="monospaced">filen.sml</span>, which depend upon libraries <span class="monospaced">lib1.mlb</span>, &#8230;, <span class="monospaced">libm.mlb</span>.</p></div>
  39 <div class="listingblock">
  40 <div class="content monospaced">
  41 <pre>(* import libraries *)
  42 lib1.mlb
  43 ...
  44 libm.mlb
  45
  46 (* program files *)
  47 file1.sml
  48 ...
  49 filen.sml</pre>
  50 </div></div>
  51 <div class="paragraph"><p>The bases denoted by <span class="monospaced">lib1.mlb</span>, &#8230;, <span class="monospaced">libm.mlb</span> are merged (bindings
  52 of names in later bases take precedence over bindings of the same name
  53 in earlier bases), producing a basis in which <span class="monospaced">file1.sml</span>, &#8230;,
  54 <span class="monospaced">filen.sml</span> are elaborated, adding additional bindings to the basis.</p></div>
  55 </div>
  56 </div>
  57 <div class="sect1">
  58 <h2 id="_export_filter">Export filter</h2>
  59 <div class="sectionbody">
  60 <div class="paragraph"><p>Suppose you only want to export certain structures, signatures, and
  61 functors from a collection of files.</p></div>
  62 <div class="listingblock">
  63 <div class="content monospaced">
  64 <pre>local
  65   file1.sml
  66   ...
  67   filen.sml
  68 in
  69   (* export filter here *)
  70   functor F
  71   structure S
  72 end</pre>
  73 </div></div>
  74 <div class="paragraph"><p>While <span class="monospaced">file1.sml</span>, &#8230;, <span class="monospaced">filen.sml</span> may declare top-level identifiers
  75 in addition to <span class="monospaced">F</span> and <span class="monospaced">S</span>, such names are not accessible to programs
  76 and libraries that import this <span class="monospaced">.mlb</span>.</p></div>
  77 </div>
  78 </div>
  79 <div class="sect1">
  80 <h2 id="_export_filter_with_renaming">Export filter with renaming</h2>
  81 <div class="sectionbody">
  82 <div class="paragraph"><p>Suppose you want an export filter, but want to rename one of the
  83 modules.</p></div>
  84 <div class="listingblock">
  85 <div class="content monospaced">
  86 <pre>local
  87   file1.sml
  88   ...
  89   filen.sml
  90 in
  91   (* export filter, with renaming, here *)
  92   functor F
  93   structure S' = S
  94 end</pre>
  95 </div></div>
  96 <div class="paragraph"><p>Note that <span class="monospaced">functor F</span> is an abbreviation for <span class="monospaced">functor F = F</span>, which
  97 simply exports an identifier under the same name.</p></div>
  98 </div>
  99 </div>
 100 <div class="sect1">
 101 <h2 id="_import_filter">Import filter</h2>
 102 <div class="sectionbody">
 103 <div class="paragraph"><p>Suppose you only want to import a functor <span class="monospaced">F</span> from one library and a
 104 structure <span class="monospaced">S</span> from another library.</p></div>
 105 <div class="listingblock">
 106 <div class="content monospaced">
 107 <pre>local
 108   lib1.mlb
 109 in
 110   (* import filter here *)
 111   functor F
 112 end
 113 local
 114   lib2.mlb
 115 in
 116   (* import filter here *)
 117   structure S
 118 end
 119 file1.sml
 120 ...
 121 filen.sml</pre>
 122 </div></div>
 123 </div>
 124 </div>
 125 <div class="sect1">
 126 <h2 id="_import_filter_with_renaming">Import filter with renaming</h2>
 127 <div class="sectionbody">
 128 <div class="paragraph"><p>Suppose you want to import a structure <span class="monospaced">S</span> from one library and
 129 another structure <span class="monospaced">S</span> from another library.</p></div>
 130 <div class="listingblock">
 131 <div class="content monospaced">
 132 <pre>local
 133   lib1.mlb
 134 in
 135   (* import filter, with renaming, here *)
 136   structure S1 = S
 137 end
 138 local
 139   lib2.mlb
 140 in
 141   (* import filter, with renaming, here *)
 142   structure S2 = S
 143 end
 144 file1.sml
 145 ...
 146 filen.sml</pre>
 147 </div></div>
 148 </div>
 149 </div>
 150 <div class="sect1">
 151 <h2 id="_full_basis">Full Basis</h2>
 152 <div class="sectionbody">
 153 <div class="paragraph"><p>Since the Modules level of SML is the natural means for organizing
 154 program and library components, MLB files provide convenient syntax
 155 for renaming Modules level identifiers (in fact, renaming of functor
 156 identifiers provides a mechanism that is not available in SML).
 157 However, please note that <span class="monospaced">.mlb</span> files elaborate to full bases
 158 including top-level types and values (including infix status), in
 159 addition to structures, signatures, and functors.  For example,
 160 suppose you wished to extend the <a href="BasisLibrary">Basis Library</a> with an
 161 <span class="monospaced">('a, 'b) either</span> datatype corresponding to a disjoint sum; the type
 162 and some operations should be available at the top-level;
 163 additionally, a signature and structure provide the complete
 164 interface.</p></div>
 165 <div class="paragraph"><p>We could use the following files.</p></div>
 166 <div class="paragraph"><p><span class="monospaced">either-sigs.sml</span></p></div>
 167 <div class="listingblock">
 168 <div class="content"><div class="highlight"><pre><span class="k">signature</span><span class="w"> </span><span class="n">EITHER_GLOBAL</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
 169 <span class="w">  </span><span class="k">sig</span><span class="w"></span>
 170 <span class="w">    </span><span class="k">datatype</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;a</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;b</span><span class="p">)</span><span class="w"> </span><span class="n">either</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Left</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">&#39;a</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="n">Right</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">&#39;b</span><span class="w"></span>
 171 <span class="w">    </span><span class="k">val</span><span class="w"> </span><span class="n">&amp;</span><span class="w">  </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;a</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">&#39;c</span><span class="p">)</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;b</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">&#39;c</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;a</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;b</span><span class="p">)</span><span class="w"> </span><span class="n">either</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">&#39;c</span><span class="w"></span>
 172 <span class="w">    </span><span class="k">val</span><span class="w"> </span><span class="n">&amp;&amp;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;a</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">&#39;c</span><span class="p">)</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;b</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">&#39;d</span><span class="p">)</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;a</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;b</span><span class="p">)</span><span class="w"> </span><span class="n">either</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;c</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;d</span><span class="p">)</span><span class="w"> </span><span class="n">either</span><span class="w"></span>
 173 <span class="w">  </span><span class="k">end</span><span class="w"></span>
 174
 175 <span class="k">signature</span><span class="w"> </span><span class="n">EITHER</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
 176 <span class="w">  </span><span class="k">sig</span><span class="w"></span>
 177 <span class="w">    </span><span class="k">include</span><span class="w"> </span><span class="n">EITHER_GLOBAL</span><span class="w"></span>
 178 <span class="w">    </span><span class="k">val</span><span class="w"> </span><span class="n">isLeft</span><span class="w">  </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;a</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;b</span><span class="p">)</span><span class="w"> </span><span class="n">either</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">bool</span><span class="w"></span>
 179 <span class="w">    </span><span class="k">val</span><span class="w"> </span><span class="n">isRight</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;a</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;b</span><span class="p">)</span><span class="w"> </span><span class="n">either</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">bool</span><span class="w"></span>
 180 <span class="w">    </span><span class="p">...</span><span class="w"></span>
 181 <span class="w">  </span><span class="k">end</span><span class="w"></span>
 182 </pre></div></div></div>
 183 <div class="paragraph"><p><span class="monospaced">either-strs.sml</span></p></div>
 184 <div class="listingblock">
 185 <div class="content"><div class="highlight"><pre><span class="k">structure</span><span class="w"> </span><span class="n">Either</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">EITHER</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
 186 <span class="w">  </span><span class="k">struct</span><span class="w"></span>
 187 <span class="w">    </span><span class="k">datatype</span><span class="w"> </span><span class="p">(</span><span class="n">&#39;a</span><span class="p">,</span><span class="w"> </span><span class="n">&#39;b</span><span class="p">)</span><span class="w"> </span><span class="n">either</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Left</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">&#39;a</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="n">Right</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">&#39;b</span><span class="w"></span>
 188 <span class="w">    </span><span class="k">fun</span><span class="w"> </span><span class="n">f</span><span class="w"> </span><span class="n">&amp;</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="k">fn</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"></span>
 189 <span class="w">      </span><span class="k">case</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">Left</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="n">f</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="n">Right</span><span class="w"> </span><span class="n">z</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="n">z</span><span class="w"></span>
 190 <span class="w">    </span><span class="k">fun</span><span class="w"> </span><span class="n">f</span><span class="w"> </span><span class="n">&amp;&amp;</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">(</span><span class="n">Left</span><span class="w"> </span><span class="n">o</span><span class="w"> </span><span class="n">f</span><span class="p">)</span><span class="w"> </span><span class="n">&amp;</span><span class="w"> </span><span class="p">(</span><span class="n">Right</span><span class="w"> </span><span class="n">o</span><span class="w"> </span><span class="n">g</span><span class="p">)</span><span class="w"></span>
 191 <span class="w">    </span><span class="k">fun</span><span class="w"> </span><span class="n">isLeft</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">((</span><span class="k">fn</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="n">true</span><span class="p">)</span><span class="w"> </span><span class="n">&amp;</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="n">false</span><span class="p">))</span><span class="w"> </span><span class="n">x</span><span class="w"></span>
 192 <span class="w">    </span><span class="k">fun</span><span class="w"> </span><span class="n">isRight</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">(</span><span class="n">not</span><span class="w"> </span><span class="n">o</span><span class="w"> </span><span class="n">isLeft</span><span class="p">)</span><span class="w"> </span><span class="n">x</span><span class="w"></span>
 193 <span class="w">    </span><span class="p">...</span><span class="w"></span>
 194 <span class="w">  </span><span class="k">end</span><span class="w"></span>
 195 <span class="k">structure</span><span class="w"> </span><span class="n">EitherGlobal</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="n">EITHER_GLOBAL</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Either</span><span class="w"></span>
 196 </pre></div></div></div>
 197 <div class="paragraph"><p><span class="monospaced">either-infixes.sml</span></p></div>
 198 <div class="listingblock">
 199 <div class="content"><div class="highlight"><pre><span class="k">infixr</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="n">&amp;</span><span class="w"> </span><span class="n">&amp;&amp;</span><span class="w"></span>
 200 </pre></div></div></div>
 201 <div class="paragraph"><p><span class="monospaced">either-open.sml</span></p></div>
 202 <div class="listingblock">
 203 <div class="content"><div class="highlight"><pre><span class="k">open</span><span class="w"> </span><span class="n">EitherGlobal</span><span class="w"></span>
 204 </pre></div></div></div>
 205 <div class="paragraph"><p><span class="monospaced">either.mlb</span></p></div>
 206 <div class="listingblock">
 207 <div class="content monospaced">
 208 <pre>either-infixes.sml
 209 local
 210   (* import Basis Library *)
 211   $(SML_LIB)/basis/basis.mlb
 212   either-sigs.sml
 213   either-strs.sml
 214 in
 215   signature EITHER
 216   structure Either
 217   either-open.sml
 218 end</pre>
 219 </div></div>
 220 <div class="paragraph"><p>A client that imports <span class="monospaced">either.mlb</span> will have access to neither
 221 <span class="monospaced">EITHER_GLOBAL</span> nor <span class="monospaced">EitherGlobal</span>, but will have access to the type
 222 <span class="monospaced">either</span> and the values <span class="monospaced">&amp;</span> and <span class="monospaced">&amp;&amp;</span> (with infix status) in the
 223 top-level environment.  Note that <span class="monospaced">either-infixes.sml</span> is outside the
 224 scope of the local, because we want the infixes available in the
 225 implementation of the library and to clients of the library.</p></div>
 226 </div>
 227 </div>
 228 </div>
 229 <div id="footnotes"><hr></div>
 230 <div id="footer">
 231 <div id="footer-text">
 232 </div>
 233 <div id="footer-badges">
 234 </div>
 235 </div>
 236 </body>
 237 </html>