Export lists cumulative
[haskell-report.git] / report / modules.verb
1 %
2 % $Header: /home/cvs/root/haskell-report/report/modules.verb,v 1.11 2001/09/13 13:29:08 simonpj Exp $
3 %
4 %**<title>The Haskell 98 Report: Modules</title>
5 %*section 5
6 %**~header
7 \section{Modules} 
8 \label{modules} 
9 \index{module}
10
11 A module defines a collection of values, datatypes, type synonyms,
12 classes, etc.~(see Section~\ref{declarations}) in an environment created
13 by a set of {\em imports}, resources brought into scope from other modules, 
14 and {\em exports} some of these resources, making them available to
15 other modules.  
16 We use the term {\em entity}\index{entity} to refer to
17 a value, type, or class defined in, imported into, or perhaps
18 exported from a module.
19
20 A \Haskell{} {\em program} is a collection of modules, one of
21 which, by convention, must be called @Main@\indexmodule{Main} and must
22 export the value @main@\indextt{main}.  The {\em value} of the program
23 is the value of the identifier @main@ in module @Main@,
24 which must be a computation of type $@IO@~\tau$ for some type $\tau$
25 (see Section~\ref{io}).  When the program is executed, the computation
26 @main@ is performed, and its result (of type $\tau$) is discarded.
27
28 Modules may reference other modules via explicit
29 @import@ declarations, each giving the name of a module to be
30 imported and specifying its entities to be imported.
31 Modules may be mutually recursive.
32
33 Modules are used for name-space control, and are not first class values.
34 A multi-module Haskell program can be converted into a single-module
35 program by giving each entity a unique name, changing all occurrences
36 to refer to the appropriate unique name, and then concatenating all the module
37 bodies\footnote{There are two minor exceptions to this statement.
38 First, @default@ declarations scope over a single module (Section~\ref{default-decls}).
39 Second, Rule 2 of the monomorphism restriction (Section~\ref{sect:monomorphism-restriction})
40 is affected by module boundaries.
41 }.  
42 For example, here is a three-module program:
43 \bprog
44 @
45   module Main where
46     import A
47     import B
48     main = A.f >> B.f
49
50   module A where
51     f = ...
52
53   module B where
54     f = ...
55 @
56 \eprog
57 It is equivalent to the following single-module program:
58 \bprog
59 @
60   module Main where
61     main = af >> bf
62
63     af = ...
64
65     bf = ...
66 @
67 \eprog
68 Because they are allowed to be mutually recursive,
69 modules allow a program to be partitioned freely without regard to
70 dependencies.
71
72 The name-space for modules themselves is flat, with each module being associated
73 with a unique module name (which are \Haskell{} identifiers
74 beginning with a capital letter; i.e.~"modid").  
75 There is one distinguished module, @Prelude@, which is imported into
76 all modules by default (see Section~\ref{standard-prelude}), plus a
77 set of standard library modules that may be imported as required
78 (see the \Haskell{} Library Report\cite{libraries}).
79
80 \subsection{Module Structure} 
81 \label{module-implementations}
82
83 A module defines a mutually
84 recursive scope containing declarations for value bindings, data
85 types, type synonyms, classes, etc. (see Section~\ref{declarations}).
86
87 @@@
88 module -> @module@ modid [exports] @where@ body
89        |  body
90 body   -> @{@ impdecls @;@ topdecls @}@
91         | @{@ impdecls  @}@
92         | @{@ topdecls @}@
93
94 modid        -> conid
95 impdecls     -> impdecl_1 @;@ ... @;@ impdecl_n         & \qquad (n>=1)
96 topdecls     -> topdecl_1 @;@ ... @;@ topdecl_n         & \qquad (n>=1)
97 @@@
98
99 \indexsyn{module}%
100 \indexsyn{body}%
101 \indexsyn{modid}%
102 \indexsyn{impdecls}%
103 \indexsyn{topdecls}%
104
105 A module 
106 begins with a header: the keyword
107 @module@, the module name, and a list of entities (enclosed in round
108 parentheses) to be exported.  The header is followed by a possibly-empty
109 list of @import@ declarations ("impdecls", Section~\ref{import}) that specify modules to be imported,
110 optionally restricting the imported bindings.  
111 This is followed by a possibly-empty list of top-level declarations ("topdecls", Section~\ref{declarations}).  
112
113 An abbreviated form of module, consisting only 
114 of\index{abbreviated module}
115 the module body, is permitted.  If this is used, the header is assumed to be
116 `@module Main(main) where@'.
117 If the first lexeme in the
118 abbreviated module is not a @{@, then the layout rule applies
119 for the top level of the module.
120
121 \subsection{Export Lists}
122 \label{export}
123 \index{export list}
124
125 @@@
126 exports  -> @(@ export_1 @,@ ... @,@ export_n [ @,@ ] @)@ & \qquad (n>=0)
127
128 export   -> qvar
129          |  qtycon [@(..)@ | @(@ qcname_1 @,@ ... @,@ qcname_n @)@] & \qquad (n>=0)
130          |  qtycls [@(..)@ | @(@ qvar_1 @,@ ... @,@ qvar_n @)@] & \qquad (n>=0)
131          |  @module@ modid
132
133 qcname   -> qvar | qcon
134 @@@
135 \indexsyn{exports}%
136 \indexsyn{export}%
137 \indexsyn{qcname}%
138
139 An {\em export list} identifies the entities to be exported by a
140 module declaration.  A module implementation may only export an entity
141 that it declares, or that it imports from some other module.  If the
142 export list is omitted, all values, types and classes defined in the
143 module are exported, {\em but not those that are imported}.
144
145 Entities in an export list may be named as follows:
146 \begin{enumerate}
147 \item
148 A value, field name, or class method, whether declared in
149 the module body or imported,
150 may be named by giving the name of the value as a "qvarid".
151 Operators should be enclosed in parentheses to turn them into
152 "qvarid"'s.  
153
154 \item
155 An algebraic datatype "T"
156 \index{algebraic datatype}
157 declared by a @data@ or @newtype@ declaration may be named in one of
158 three ways: 
159 \begin{itemize}
160 \item
161 The form "T" names the type {\em but not the constructors or field names}.
162 The ability to export a type without its constructors allows the
163 construction of abstract datatypes (see Section~\ref{abstract-types}).
164 \item
165 The form $T@(@qcname_1@,@\ldots@,@qcname_n@)@$, where the $qcname_i$
166 name only constructors and field names in $T$, 
167 names the type and some or all of its constructors and field names.  
168 The $qcname_i$ must not contain duplications.  
169 \item
170 The abbreviated form "T@(..)@" names the type 
171 and all its constructors and field names that are currently in scope
172 (whether qualified or not).
173 \end{itemize}
174 Data constructors cannot be named in export lists in any other way.
175
176 \item
177 A type synonym "T" declared by a
178 @type@ declaration may be named by the form "T".
179 \index{type synonym}
180
181 \item
182 \index{class declaration}
183 A class $C$ with operations $f_1,\ldots,f_n$
184 declared in a @class@ declaration may be named in one of three ways:
185 \begin{itemize}
186 \item
187 The form "C" names the class {\em but not the class methods}.
188 \item
189 The form $C@(@f_1@,@\ldots@,@f_n@)@$, where
190 the $f_i$ must be class methods of $C$, names the class and some or all
191 of its methods.  The $f_i$ must not contain duplications.
192 \item
193 The abbreviated form $C@(..)@$ names the class and all its methods
194 that are in scope (whether qualified or not).
195 \end{itemize}
196
197 \item
198 The form `"@module@ M"' abbreviates the set of all entities whose
199 names are brought into scope by one or more {\em unqualified} @import@ declarations
200 of the form `"@import@~M~[impspec]"' or `"@import@~A~@as@~M~[impspec]"'.  This set may be empty.
201 For example:
202 \bprog
203 @
204       module Queue( module Stack, enqueue, dequeue ) where
205           import Stack
206           ...
207 @
208 \eprog
209 Here the module @Queue@ uses the module name @Stack@ in its export
210 list to abbreviate all the entities imported from @Stack@.  
211 \item
212 Additionally, a module can name its own local definitions in its export
213 list using its name in the `"@module@" m' syntax.  For example:
214 \bprog
215 @
216  module Mod1(module Mod1, module Mod2) where
217  import Mod2
218  import Mod3
219 @
220 \eprog
221 Here module @Mod1@ exports all local definitions as well as those
222 imported from @Mod2@ but not those imported from @Mod3@.  Note that
223 @module M where@ is the same as using @module M(module M) where@.
224 \end{enumerate}
225 It is an error to use "@module@~M" in an export list unless $M$ is the
226 module bearing the export list, or $M$ is imported
227 by at least one @import@ declaration (qualified or unqualified).
228
229 Exports lists are cumulative: the set of entities exported by an export
230 list is the union of the entities exported by the individual items of the list.
231
232 It makes no difference to an importing module how an entity was 
233 exported.  For example, a field name @f@ from data type @T@ may be exported individually
234 (@f@, item (1) above); or as an explicitly-named member of its data type (@T(f)@, item (2));
235 or as an implicitly-named member (@T(..)@, item(2)); or by exporting an entire
236 module (@module M@, item (5) or (6)).  
237
238 The {\em unqualified} names of the entities exported by a module must all be distinct
239 (within their respective namespace).  For example
240 \bprog
241 @
242   module A ( B.f, C.f, g ) where   -- an invalid module
243   import qualified B(f,g)
244   import qualified C(f)
245   g = True
246 @
247 \eprog
248 There are name clashes in the export list between @B.f@ and @C.f@ and
249 between @g@ and @B.g@ even though there are no name clashes within
250 module @A@.  
251
252
253 \subsection{Import Declarations}
254 \label{import}
255 \index{import declaration}
256
257 @@@
258 impdecl   -> @import@ [@qualified@] modid [@as@ modid] [impspec]
259           |     & (empty declaration)
260 impspec   -> @(@ import_1 @,@ ... @,@ import_n [ @,@ ] @)@ & \qquad (n>=0)
261              |  @hiding@ @(@ import_1 @,@ ... @,@ import_n [ @,@ ] @)@ & \qquad (n>=0)
262
263 import    -> var
264           |  tycon [ @(..)@ | @(@ cname_1 @,@ ... @,@ cname_n @)@] & \qquad (n>=1)
265           |  tycls [@(..)@ | @(@ var_1 @,@ ... @,@ var_n @)@] & \qquad (n>=0)
266 cname     -> var | con
267 @@@
268 %             var
269 %          |  tycon
270 %          |  tycon @(..)@
271 %          |  tycon @(@ con_1 @,@ ... @,@ con_n@)@ & \qquad (n>=1)
272 %          |  tycls @(..)@
273 %          |  tycls @(@ var_1 @,@ ... @,@ var_n@)@ & \qquad (n>=0)
274 \indexsyn{impdecl}%
275 \indexsyn{impspec}%
276 \indexsyn{import}%
277 \indexsyn{cname}%
278
279 The entities exported by a module may be brought into scope in
280 another module with
281 an @import@
282 declaration at the beginning
283 of the module.  
284 The @import@ declaration names the module to be
285 imported
286 and optionally specifies the entities to be imported.
287 A single module may be imported by more than one @import@ declaration.  
288 Imported names serve as top level declarations: they scope over
289 the entire body of the module but may  be shadowed by local
290 non-top-level bindings.  
291
292 The effect of multiple @import@ declarations is strictly
293 cumulative: an entity is in scope if it is imported by any of the @import@
294 declarations in a module.  The ordering of import declarations is irrelevant.
295
296 \subsubsection{What is imported}
297 \label{whatisimported}
298
299 Exactly which entities are to be imported can be specified in one
300 of the following three ways:\nopagebreak[4]
301 \begin{enumerate}
302 \item
303 The imported entities can be specified explicitly
304 by listing them in parentheses.
305 Items in the list have the same form as those in export lists, except
306 qualifiers are not permitted and
307 the `@module@ "modid"' entity is not permitted.  When the @(..)@ form
308 of import is used for a type or class, the @(..)@ refers to all of the
309 constructors, methods, or field names exported from the module.
310
311 The list must name only
312 entities exported by the imported module.
313 The list may be empty, in which case nothing except the instances is
314 imported.
315
316 \item
317 Entities can be excluded by 
318 using the form @hiding(@"import_1 @,@ ... @,@ import_n"
319 @)@,\index{hiding} which
320 specifies that all entities exported by the named module should
321 be imported except for those named in the list.  Data constructors may be
322 named directly in hiding lists without being prefixed by the
323 associated type.  Thus, in
324 \bprog
325 @
326   import M hiding (C)
327 @
328 \eprog
329 any constructor, class, or type named @C@ is excluded.  In contrast,
330 using @C@ in an import list names only a class or type.  
331
332 It is not an error to hide an entity that is not, in fact, exported by
333 the imported module, although compilers are encouraged to flag a warning in this case.
334
335 \item
336 Finally, if "impspec" is omitted then 
337 all the entities exported by the specified module are imported.
338 \end{enumerate}
339
340 \subsubsection{Qualified import}
341 \index{qualified name}
342
343 For each entity imported under the rules of Section~\ref{whatisimported},
344 the top-level environment is extended.  If the import declaration used
345 the @qualified@ keyword, only the {\em qualified name} of the entity is
346 brought into scope.  If the @qualified@ keyword is omitted, then {\em both} the
347 qualified {\em and} unqualified name of the entity is brought into scope.
348 Section~\ref{qualifiers} describes qualified names in more detail.
349
350 The qualifier on the imported name is either the name of the imported module,
351 or the local alias given in the @as@ clause (Section~\ref{as-clause}) 
352 on the @import@ statement.
353 Hence, {\em the qualifier is not necessarily the name of the module in which the
354 entity was originally declared}.
355
356 The ability to exclude the unqualified names allows full programmer control of
357 the unqualified namespace: a locally defined entity can share the same
358 name as a qualified import:
359 \bprog
360 @
361   module Ring where
362   import qualified Prelude  -- All Prelude names must be qualified
363   import List( nub )
364
365   l1 + l2 = l1 ++ l2        -- This + differs from the one in the Prelude
366   l1 * l2 = nub (l1 + l2)   -- This * differs from the one in the Prelude
367
368   succ = (Prelude.+ 1)
369 @
370 \eprog
371
372
373 \subsubsection{Local aliases}
374 \label{as-clause}
375
376 Imported modules may be assigned a local alias in the importing module
377 using the @as@ clause.
378 For example, in
379 \bprog
380 @
381   import qualified VeryLongModuleName as C
382 @
383 \eprog
384 entities must be referenced using `@C.@' as a qualifier instead of
385 `@VeryLongModuleName.@'.  This also allows a different module to be substituted
386 for @VeryLongModuleName@ without changing the qualifiers used for the imported module.
387 It is legal for more than one module in scope to 
388 use the same qualifier, provided that all names can still be resolved unambiguously.
389 For example:
390 \bprog
391 @
392   module M where
393     import qualified Foo as A
394     import qualified Baz as A
395     x = A.f
396 @
397 \eprog
398 This module is legal provided only that @Foo@ and @Baz@ do not both export @f@.
399
400 An @as@ clause may also be used on an un-@qualified@ @import@ statement:
401 \bprog
402 @
403   import Foo as A(f)
404 @
405 \eprog
406 This declaration brings into scope @f@ and @A.f@.
407
408
409 \subsubsection{Examples}
410
411 To clarify the above import rules, suppose the module @A@ exports @x@ and @y@.
412 Then this table shows what names are brought into scope by the specified import statement:
413 \begin{center}
414 \begin{tabular}{|ll|}
415 \hline
416 Import declaration & Names brought into scope \\
417 \hline
418   @import A@                    & @x@, @y@, @A.x@, @A.y@ \\
419   @import A()@                  & (nothing)     \\
420   @import A(x)@                 & @x@, @A.x@ \\
421   @import qualified A@          & @A.x@, @A.y@ \\
422   @import qualified A()@        & (nothing) \\
423   @import qualified A(x)@       & @A.x@ \\
424   @import A hiding ()@          & @x@, @y@, @A.x@, @A.y@ \\
425   @import A hiding (x)@         & @y@, @A.y@ \\
426   @import qualified A hiding ()@        & @A.x@, @A.y@ \\
427   @import qualified A hiding (x)@       & @A.y@ \\
428   @import A as B@               & @x@, @y@, @B.x@, @B.y@ \\
429   @import A as B(x)@            & @B.x@ \\
430   @import qualified A as B@     & @B.x@, @B.y@ \\
431 \hline
432 \end{tabular}
433 \end{center}
434 In all cases, all instance declarations in scope in module @A@ are imported
435 (Section~\ref{import-instances}).
436
437 \subsection{Importing and Exporting Instance Declarations}
438 \label{import-instances}
439 \index{instance declaration!importing and exporting}
440
441 Instance declarations cannot be explicitly named on import or export
442 lists.  All instances in scope within a module are {\em always}
443 exported and any import brings {\em all} instances in from the
444 imported module.  Thus, an
445 instance declaration is in scope if and only if a chain of @import@
446 declarations leads to the module containing the instance declaration.
447
448 For example, @import M()@ does not bring
449 any new names in scope from module @M@, but does bring in any instances
450 visible in @M@.  A module whose only purpose is to provide instance
451 declarations can have an empty export list.  For example
452 \bprog
453 @
454   module MyInstances() where
455     instance Show (a -> b) where
456         show fn = "<<function>>"
457     instance Show (IO a) where
458         show io = "<<IO action>>"
459 @
460 \eprog
461
462 \subsection{Name Clashes and Closure}
463
464 \subsubsection{Qualified names}\index{qualified name}
465 \label{qualifiers}
466
467 A {\em qualified name} is written as "modid"@.@"name" (Section~\ref{ids}).
468
469 A qualified name is brought into scope:
470 \begin{itemize}
471 \item {\em By a top level declaration.}
472 A top-level declaration brings into scope both the unqualified {\em and}
473 the qualified name of the entity being defined.  Thus:
474 \bprog
475 @
476   module M where
477     f x = ...
478     g x = M.f x x
479 @
480 \eprog
481 is legal.  The {\em defining} occurrence must mention the {\em unqualified} name; therefore, it is
482 illegal to write
483 \bprog
484 @
485   module M where
486     M.f x = ...                 -- ILLEGAL
487     g x = let M.y = x+1 in ...  -- ILLEGAL
488 @
489 \eprog
490 \item {\em By an @import@ declaration.}  An @import@ declaration, whether @qualified@ or not,
491 always brings into scope the qualified name of the imported entity (Section~\ref{import}).
492 \end{itemize}
493 Qualifiers may also be applied to
494 names imported by an unqualified import; this allows a qualified
495 import to be replaced with an unqualified one without forcing changes
496 in the references to the imported names.  
497
498
499 \subsubsection{Name clashes}
500
501 If a module contains a bound occurrence of a name, such as @f@ or @A.f@,
502 it must be possible unambiguously to resolve which entity is thereby referred to;
503 that is, there must be only one binding for @f@ or @A.f@ respectively.
504
505 It is {\em not} an error for there to exist names that cannot be so 
506 resolved, provided that the program does not mention those names.  For example:
507 \bprog
508 @
509   module A where
510     import B
511     import C
512     tup = (b, c, d, x)
513   
514   module B( d, b, x, y ) where
515     import D
516     x = ...
517     y = ...
518     b = ...
519   
520   module C( d, c, x, y ) where
521     import D
522     x = ...
523     y = ...
524     c = ...
525
526   module D( d ) where
527     d = ...
528 @
529 \eprog
530 Consider the definition of @tup@.  
531 \begin{itemize}
532 \item The references to @b@ and @c@
533 can be unambiguously resolved to @b@ declared in @B@, and @c@ declared in
534 @C@ respectively.  
535 \item The reference to @d@ is unambiguously resolved to
536 @d@ declared in @D@.  In this case the same entity is brought into scope by two routes
537 (the import of @B@ and the import of @C@), and can be referred to in @A@ by the names
538 @d@, @B.d@, and @C.d@.
539 \item The reference to @x@ is ambiguous: it could mean @x@ declared in @B@, or @x@ 
540 declared in @C@.  The ambiguity could be fixed by replacing the reference to @x@ by
541 @B.x@ or @C.x@.
542 \item There is no reference to @y@, so it is not erroneous that distinct entities called
543 @y@ are exported by both @B@ and @C@.  An error is only reported if @y@ is actually mentioned.
544 \end{itemize}
545
546 The name occurring in a type signature or fixity declarations is
547 always unqualified, and unambiguously refers to another declaration in
548 the same declaration list (except that the fixity declaration for a
549 class method can occur at top level --- Section~\ref{fixity}). For example,
550 the following module is legal:
551 \bprog
552 @
553   module F where
554
555     sin :: Float -> Float
556     sin x = (x::Float)
557
558     f x = Prelude.sin (F.sin x)
559 @
560 \eprog
561 The local declaration for @sin@ is
562 legal, even though the Prelude function @sin@ is implicitly in
563 scope. The references to @Prelude.sin@ and @F.sin@ must both be qualified
564 to make it unambigous which @sin@ is meant. However, the unqualified
565 name "@sin@" in the type signature in the first line of @F@ unambiguously
566 refers to the local declaration for @sin@.
567
568 \subsubsection{Closure}
569 \label{closure}
570 \index{closure}
571
572 Every module in a \Haskell{} program must be {\em closed}.  That is,
573 every name explicitly mentioned by the source code
574 must be either defined locally or imported from another module.
575 However, entities that the compiler requires for type checking or other
576 compile time analysis need not be imported if they are not mentioned
577 by name.  The \Haskell{} compilation system is responsible for finding
578 any information needed for compilation without the help of the
579 programmer.  That is, the import of a variable @x@ does not
580 require that the datatypes and classes in the signature of @x@ be
581 brought into the module along with @x@ unless these entities are
582 referenced by name in the user program.  The \Haskell{}
583 system silently imports any information that must accompany an
584 entity for type checking or any other purposes.  Such entities need
585 not even be explicitly exported: the following program is valid even though
586 @T@ does not escape @M1@:
587 \bprog
588 @
589   module M1(x) where
590     data T = T
591     x = T
592   
593   module M2 where
594     import M1(x)
595     y = x
596 @
597 \eprog
598 In this example, there is no way to supply an explicit type signature
599 for @y@ since @T@ is not in scope.
600 Whether or not @T@ is explicitly exported, module @M2@ knows
601 enough about @T@ to correctly type check the program.
602
603 The type of an exported entity is unaffected by non-exported type
604 synonyms.  For example, in
605 \bprog
606 @
607   module M(x) where
608     type T = Int
609     x :: T
610     x = 1
611 @
612 \eprog
613 the type of @x@ is both @T@ and @Int@; these are interchangeable even
614 when @T@ is not in scope.  That is, the definition of @T@ is available
615 to any module that encounters it whether or not the name @T@ is
616 in scope.  The only reason to export @T@ is to allow other modules to
617 refer it by name; the type checker finds the definition of @T@ if
618 needed whether or not it is exported.
619
620 \subsection{Standard Prelude}
621 \label{standard-prelude}
622 \index{standard prelude}
623 \index{libraries}
624 Many of the features of \Haskell{} are defined in \Haskell{}
625 itself as a library of standard datatypes, classes, and
626 functions, called the ``Standard Prelude.''  In
627 \Haskell{}, the Prelude is contained in the
628 module @Prelude@.\indexmodule{Prelude} There are also
629 many predefined library modules, which provide less frequently used
630 functions and types.  For example, arrays, 
631 tables, and most of the input/output are all part of the standard
632 libraries.    These are 
633 defined in the Haskell Library Report\cite{libraries},
634 a separate document.  Separating
635 libraries from the Prelude has the advantage of reducing the size and
636 complexity of the Prelude, allowing it to be more easily assimilated,
637 and increasing the space of useful names available to the programmer.
638
639 Prelude and library modules differ from other modules in that
640 their semantics (but not their implementation) are a fixed part of the
641 \Haskell{} language definition.
642 This means, for example, that a compiler may optimize calls to
643 functions in the Prelude without consulting the source code
644 of the Prelude.
645
646 \subsubsection{The @Prelude@ Module}
647 \indexmodule{Prelude}
648 \index{Prelude!implicit import of}
649
650 The @Prelude@ module is imported automatically into 
651 all modules as if by the statement `@import Prelude@', if and
652 only if it is not imported with an explicit @import@ declaration.
653 This provision for explicit import allows values defined in the
654 Prelude to be hidden from the unqualified name space.  The
655 @Prelude@ module is always available as a qualified import: an
656 implicit `@import qualified Prelude@' is part of every module and 
657 names prefixed by `@Prelude.@' can always be used to refer to entities in the
658 Prelude.
659
660 The semantics of the entities in @Prelude@ is specified by a reference
661 implementation of @Prelude@ written in \Haskell{}, given in
662 Appendix~\ref{stdprelude}.  Some datatypes (such as @Int@) and
663 functions (such as @Int@ addition) cannot be specified directly in
664 \Haskell{}.  Since the treatment of such entities depends on the
665 implementation, they are not formally defined in the appendix.
666 The implementation of
667 @Prelude@ is also incomplete in its treatment of tuples: there should
668 be an infinite family of tuples and their instance declarations, but the
669 implementation only gives a scheme.
670
671 Appendix~\ref{stdprelude} defines the module @Prelude@ using
672 several other modules: @PreludeList@, @PreludeIO@, and so on.
673 These modules are {\em not} part of Haskell 98, and they cannot be imported
674 separately.  They are simply 
675 there to help explain the structure of the @Prelude@ module; they
676 should be considered part of its implementation, not part of the language
677 definition.
678  
679 \subsubsection{Shadowing Prelude Names}
680 \label{std-prel-shadowing}
681
682 The rules about the Prelude have been cast so that it is
683 possible to use Prelude names for nonstandard purposes; however,
684 every module that does so must have an @import@ declaration
685 that makes this nonstandard usage explicit.  For example:
686 \bprog
687 @
688   module A( null, nonNull ) where
689     import Prelude hiding( null ) 
690     null, nonNull :: Int -> Bool
691     null    x = x == 0
692     nonNull x = not (null x)
693 @
694 \eprog
695 Module @A@ redefines @null@, and contains an unqualified reference to @null@
696 on the right hand side of @nonNull@. The latter would be ambiguous
697 without the @hiding(null)@ on the @import Prelude@ statement. Every
698 module that imports @A@ unqualified, and then makes an unqualified
699 reference to @null@ must also resolve the ambiguous use of @null@ just as
700 @A@ does. Thus there is little danger of accidentally shadowing Prelude
701 names.
702
703 It is possible to construct and use a different module to serve in
704 place of the Prelude.  Other than the fact that it is implicitly
705 imported, the Prelude is an ordinary \Haskell{} module; it is special
706 only in that some objects in the Prelude are referenced by special
707 syntactic constructs.  Redefining names used by the Prelude does not
708 affect the meaning of these special constructs.  For example, in
709 \bprog
710 @
711   module B where
712     import qualified Prelude
713     import MyPrelude
714       ...
715 @
716 \eprog
717 @B@ imports nothing from @Prelude@, but the
718 explicit @import qualified Prelude@ declaration prevents the automatic
719 import of 
720 @Prelude@.  @import MyPrelude@ brings the
721 non-standard prelude into scope.  As before, the
722 standard prelude names are hidden explicitly.  Special
723 syntax, such as lists or tuples, always refers to prelude entities:
724 there is no way to redefine the meaning of @[x]@ in terms of a
725 different implementation of lists.
726
727 It is not possible, however, to hide @instance@ declarations in the
728 @Prelude@.  For example, one cannot define a new instance for @Show Char@.
729
730 \subsection{Separate Compilation}
731 \index{separate compilation}
732 Depending on the \Haskell{} implementation used, separate compilation
733 of mutually recursive modules may require that imported modules contain
734 additional information so that they may be referenced before they are
735 compiled.  Explicit type signatures for all exported values may be
736 necessary to deal with mutual recursion.  The
737 precise details of separate compilation are not defined by this
738 report. 
739
740 \subsection{Abstract Datatypes}
741 \label{abstract-types}
742
743 \index{abstract datatype}
744 The ability to export a datatype without its constructors
745 allows the construction of abstract datatypes (ADTs).  For example,
746 an ADT for stacks could be defined as:
747 \bprog
748 @
749   module Stack( StkType, push, pop, empty ) where
750     data StkType a = EmptyStk | Stk a (StkType a)
751     push x s = Stk x s
752     pop (Stk _ s) = s
753     empty = EmptyStk
754 @
755 \eprog
756 Modules importing @Stack@ cannot construct values of type @StkType@
757 because they do not have access to the constructors of the type.
758 Instead, they must use @push@, @pop@, and @empty@ to construct such values.
759
760 It is also possible to build an ADT on top of an existing type by
761 using a @newtype@ declaration.  For example, stacks can be defined
762 with lists: 
763 \bprog
764 @
765   module Stack( StkType, push, pop, empty ) where
766     newtype StkType a = Stk [a]
767     push x (Stk s) = Stk (x:s)
768     pop (Stk (_:s)) = Stk s
769     empty = Stk []
770 @
771 \eprogNoSkip
772
773
774 %**~footer
775
776 % Local Variables: 
777 % mode: latex
778 % End: