Commit | Line | Data |
---|---|---|
7f918cf1 CE |
1 | MLBasisExamples |
2 | =============== | |
3 | ||
4 | Here are some example uses of <:MLBasis:ML Basis> files. | |
5 | ||
6 | ||
7 | == Complete program == | |
8 | ||
9 | Suppose your complete program consists of the files `file1.sml`, ..., | |
10 | `filen.sml`, which depend upon libraries `lib1.mlb`, ..., `libm.mlb`. | |
11 | ||
12 | ---- | |
13 | (* import libraries *) | |
14 | lib1.mlb | |
15 | ... | |
16 | libm.mlb | |
17 | ||
18 | (* program files *) | |
19 | file1.sml | |
20 | ... | |
21 | filen.sml | |
22 | ---- | |
23 | ||
24 | The bases denoted by `lib1.mlb`, ..., `libm.mlb` are merged (bindings | |
25 | of names in later bases take precedence over bindings of the same name | |
26 | in earlier bases), producing a basis in which `file1.sml`, ..., | |
27 | `filen.sml` are elaborated, adding additional bindings to the basis. | |
28 | ||
29 | ||
30 | == Export filter == | |
31 | ||
32 | Suppose you only want to export certain structures, signatures, and | |
33 | functors from a collection of files. | |
34 | ||
35 | ---- | |
36 | local | |
37 | file1.sml | |
38 | ... | |
39 | filen.sml | |
40 | in | |
41 | (* export filter here *) | |
42 | functor F | |
43 | structure S | |
44 | end | |
45 | ---- | |
46 | ||
47 | While `file1.sml`, ..., `filen.sml` may declare top-level identifiers | |
48 | in addition to `F` and `S`, such names are not accessible to programs | |
49 | and libraries that import this `.mlb`. | |
50 | ||
51 | ||
52 | == Export filter with renaming == | |
53 | ||
54 | Suppose you want an export filter, but want to rename one of the | |
55 | modules. | |
56 | ||
57 | ---- | |
58 | local | |
59 | file1.sml | |
60 | ... | |
61 | filen.sml | |
62 | in | |
63 | (* export filter, with renaming, here *) | |
64 | functor F | |
65 | structure S' = S | |
66 | end | |
67 | ---- | |
68 | ||
69 | Note that `functor F` is an abbreviation for `functor F = F`, which | |
70 | simply exports an identifier under the same name. | |
71 | ||
72 | ||
73 | == Import filter == | |
74 | ||
75 | Suppose you only want to import a functor `F` from one library and a | |
76 | structure `S` from another library. | |
77 | ||
78 | ---- | |
79 | local | |
80 | lib1.mlb | |
81 | in | |
82 | (* import filter here *) | |
83 | functor F | |
84 | end | |
85 | local | |
86 | lib2.mlb | |
87 | in | |
88 | (* import filter here *) | |
89 | structure S | |
90 | end | |
91 | file1.sml | |
92 | ... | |
93 | filen.sml | |
94 | ---- | |
95 | ||
96 | ||
97 | == Import filter with renaming == | |
98 | ||
99 | Suppose you want to import a structure `S` from one library and | |
100 | another structure `S` from another library. | |
101 | ||
102 | ---- | |
103 | local | |
104 | lib1.mlb | |
105 | in | |
106 | (* import filter, with renaming, here *) | |
107 | structure S1 = S | |
108 | end | |
109 | local | |
110 | lib2.mlb | |
111 | in | |
112 | (* import filter, with renaming, here *) | |
113 | structure S2 = S | |
114 | end | |
115 | file1.sml | |
116 | ... | |
117 | filen.sml | |
118 | ---- | |
119 | ||
120 | ||
121 | == Full Basis == | |
122 | ||
123 | Since the Modules level of SML is the natural means for organizing | |
124 | program and library components, MLB files provide convenient syntax | |
125 | for renaming Modules level identifiers (in fact, renaming of functor | |
126 | identifiers provides a mechanism that is not available in SML). | |
127 | However, please note that `.mlb` files elaborate to full bases | |
128 | including top-level types and values (including infix status), in | |
129 | addition to structures, signatures, and functors. For example, | |
130 | suppose you wished to extend the <:BasisLibrary:Basis Library> with an | |
131 | `('a, 'b) either` datatype corresponding to a disjoint sum; the type | |
132 | and some operations should be available at the top-level; | |
133 | additionally, a signature and structure provide the complete | |
134 | interface. | |
135 | ||
136 | We could use the following files. | |
137 | ||
138 | `either-sigs.sml` | |
139 | [source,sml] | |
140 | ---- | |
141 | signature EITHER_GLOBAL = | |
142 | sig | |
143 | datatype ('a, 'b) either = Left of 'a | Right of 'b | |
144 | val & : ('a -> 'c) * ('b -> 'c) -> ('a, 'b) either -> 'c | |
145 | val && : ('a -> 'c) * ('b -> 'd) -> ('a, 'b) either -> ('c, 'd) either | |
146 | end | |
147 | ||
148 | signature EITHER = | |
149 | sig | |
150 | include EITHER_GLOBAL | |
151 | val isLeft : ('a, 'b) either -> bool | |
152 | val isRight : ('a, 'b) either -> bool | |
153 | ... | |
154 | end | |
155 | ---- | |
156 | ||
157 | `either-strs.sml` | |
158 | [source,sml] | |
159 | ---- | |
160 | structure Either : EITHER = | |
161 | struct | |
162 | datatype ('a, 'b) either = Left of 'a | Right of 'b | |
163 | fun f & g = fn x => | |
164 | case x of Left z => f z | Right z => g z | |
165 | fun f && g = (Left o f) & (Right o g) | |
166 | fun isLeft x = ((fn _ => true) & (fn _ => false)) x | |
167 | fun isRight x = (not o isLeft) x | |
168 | ... | |
169 | end | |
170 | structure EitherGlobal : EITHER_GLOBAL = Either | |
171 | ---- | |
172 | ||
173 | `either-infixes.sml` | |
174 | [source,sml] | |
175 | ---- | |
176 | infixr 3 & && | |
177 | ---- | |
178 | ||
179 | `either-open.sml` | |
180 | [source,sml] | |
181 | ---- | |
182 | open EitherGlobal | |
183 | ---- | |
184 | ||
185 | `either.mlb` | |
186 | ---- | |
187 | either-infixes.sml | |
188 | local | |
189 | (* import Basis Library *) | |
190 | $(SML_LIB)/basis/basis.mlb | |
191 | either-sigs.sml | |
192 | either-strs.sml | |
193 | in | |
194 | signature EITHER | |
195 | structure Either | |
196 | either-open.sml | |
197 | end | |
198 | ---- | |
199 | ||
200 | A client that imports `either.mlb` will have access to neither | |
201 | `EITHER_GLOBAL` nor `EitherGlobal`, but will have access to the type | |
202 | `either` and the values `&` and `&&` (with infix status) in the | |
203 | top-level environment. Note that `either-infixes.sml` is outside the | |
204 | scope of the local, because we want the infixes available in the | |
205 | implementation of the library and to clients of the library. |