Changes in Oct
[haskell-report.git] / report / modules.verb
1 %
2 % $Header: /home/cvs/root/haskell-report/report/modules.verb,v 1.15 2001/11/01 13:43:43 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 {\em unqualified} name, $e$, is in scope, and for which the {\em qualified} name
200 $M.e$ is also in scope and refers to the same entity as $e$.  This set
201 may be empty.
202 For example:
203 \bprog
204 @
205   module Queue( module Stack, enqueue, dequeue ) where
206       import Stack
207       ...
208 @
209 \eprog
210 Here the module @Queue@ uses the module name @Stack@ in its export
211 list to abbreviate all the entities imported from @Stack@.  
212
213 A module can name its own local definitions in its export
214 list using its own name in the ``@module M@'' syntax, because a local
215 declaration brings into scope both a qualified and unqualified name (Section~\ref{qualifiers}). 
216 For example:
217 \bprog
218 @
219   module Mod1( module Mod1, module Mod2 ) where
220   import Mod2
221   import Mod3
222 @
223 \eprog
224 Here module @Mod1@ exports all local definitions as well as those
225 imported from @Mod2@ but not those imported from @Mod3@.
226
227 It is an error to use @module M@ in an export list unless @M@ is 
228 the module bearing the export list, or @M@ is imported by at 
229 least one import declaration (qualified or unqualified).
230 \end{enumerate}
231 Exports lists are cumulative: the set of entities exported by an export
232 list is the union of the entities exported by the individual items of the list.
233
234 It makes no difference to an importing module how an entity was 
235 exported.  For example, a field name @f@ from data type @T@ may be exported individually
236 (@f@, item (1) above); or as an explicitly-named member of its data type (@T(f)@, item (2));
237 or as an implicitly-named member (@T(..)@, item(2)); or by exporting an entire
238 module (@module M@, item (5)).  
239
240 The {\em unqualified} names of the entities exported by a module must all be distinct
241 (within their respective namespace).  For example
242 \bprog
243 @
244   module A ( C.f, C.g, g, module B ) where   -- an invalid module
245   import B(f)
246   import qualified C(f,g)
247   g = f True
248 @
249 \eprog
250 There are name clashes in the export list 
251 between @C.g@ and @g@, 
252 and between @module B@ and @C.f@ (assuming @B.f@ and @C.f@ are different entities), 
253 even though there are no name clashes within module @A@ itself.  
254
255
256 \subsection{Import Declarations}
257 \label{import}
258 \index{import declaration}
259
260 @@@
261 impdecl   -> @import@ [@qualified@] modid [@as@ modid] [impspec]
262           |     & (empty declaration)
263 impspec   -> @(@ import_1 @,@ ... @,@ import_n [ @,@ ] @)@ & \qquad (n>=0)
264              |  @hiding@ @(@ import_1 @,@ ... @,@ import_n [ @,@ ] @)@ & \qquad (n>=0)
265
266 import    -> var
267           |  tycon [ @(..)@ | @(@ cname_1 @,@ ... @,@ cname_n @)@] & \qquad (n>=1)
268           |  tycls [@(..)@ | @(@ var_1 @,@ ... @,@ var_n @)@] & \qquad (n>=0)
269 cname     -> var | con
270 @@@
271 %             var
272 %          |  tycon
273 %          |  tycon @(..)@
274 %          |  tycon @(@ con_1 @,@ ... @,@ con_n@)@ & \qquad (n>=1)
275 %          |  tycls @(..)@
276 %          |  tycls @(@ var_1 @,@ ... @,@ var_n@)@ & \qquad (n>=0)
277 \indexsyn{impdecl}%
278 \indexsyn{impspec}%
279 \indexsyn{import}%
280 \indexsyn{cname}%
281
282 The entities exported by a module may be brought into scope in
283 another module with
284 an @import@
285 declaration at the beginning
286 of the module.  
287 The @import@ declaration names the module to be
288 imported
289 and optionally specifies the entities to be imported.
290 A single module may be imported by more than one @import@ declaration.  
291 Imported names serve as top level declarations: they scope over
292 the entire body of the module but may  be shadowed by local
293 non-top-level bindings.  
294
295 The effect of multiple @import@ declarations is strictly
296 cumulative: an entity is in scope if it is imported by any of the @import@
297 declarations in a module.  The ordering of import declarations is irrelevant.
298
299 Lexically speaking, the terminal symbols ``@as@'', ``@qualified@'' and
300 ``@hiding@'' are each a "varid" rather than a "reservedid".  They have
301 special significance only in the context of an @import@ declaration;
302 they may also be used as variables.
303
304 \subsubsection{What is imported}
305 \label{whatisimported}
306
307 Exactly which entities are to be imported can be specified in one
308 of the following three ways:\nopagebreak[4]
309 \begin{enumerate}
310 \item
311 The imported entities can be specified explicitly
312 by listing them in parentheses.
313 Items in the list have the same form as those in export lists, except
314 qualifiers are not permitted and
315 the `@module@ "modid"' entity is not permitted.  When the @(..)@ form
316 of import is used for a type or class, the @(..)@ refers to all of the
317 constructors, methods, or field names exported from the module.
318
319 The list must name only
320 entities exported by the imported module.
321 The list may be empty, in which case nothing except the instances is
322 imported.
323
324 \item
325 Entities can be excluded by 
326 using the form @hiding(@"import_1 @,@ ... @,@ import_n"
327 @)@,\index{hiding} which
328 specifies that all entities exported by the named module should
329 be imported except for those named in the list.  Data constructors may be
330 named directly in hiding lists without being prefixed by the
331 associated type.  Thus, in
332 \bprog
333 @
334   import M hiding (C)
335 @
336 \eprog
337 any constructor, class, or type named @C@ is excluded.  In contrast,
338 using @C@ in an import list names only a class or type.  
339
340 It is an error to hide an entity that is not, in fact, exported by
341 the imported module.
342
343 \item
344 Finally, if "impspec" is omitted then 
345 all the entities exported by the specified module are imported.
346 \end{enumerate}
347
348 \subsubsection{Qualified import}
349 \index{qualified name}
350
351 For each entity imported under the rules of Section~\ref{whatisimported},
352 the top-level environment is extended.  If the import declaration used
353 the @qualified@ keyword, only the {\em qualified name} of the entity is
354 brought into scope.  If the @qualified@ keyword is omitted, then {\em both} the
355 qualified {\em and} unqualified name of the entity is brought into scope.
356 Section~\ref{qualifiers} describes qualified names in more detail.
357
358 The qualifier on the imported name is either the name of the imported module,
359 or the local alias given in the @as@ clause (Section~\ref{as-clause}) 
360 on the @import@ statement.
361 Hence, {\em the qualifier is not necessarily the name of the module in which the
362 entity was originally declared}.
363
364 The ability to exclude the unqualified names allows full programmer control of
365 the unqualified namespace: a locally defined entity can share the same
366 name as a qualified import:
367 \bprog
368 @
369   module Ring where
370   import qualified Prelude  -- All Prelude names must be qualified
371   import List( nub )
372
373   l1 + l2 = l1 ++ l2        -- This + differs from the one in the Prelude
374   l1 * l2 = nub (l1 + l2)   -- This * differs from the one in the Prelude
375
376   succ = (Prelude.+ 1)
377 @
378 \eprog
379
380
381 \subsubsection{Local aliases}
382 \label{as-clause}
383
384 Imported modules may be assigned a local alias in the importing module
385 using the @as@ clause.
386 For example, in
387 \bprog
388 @
389   import qualified VeryLongModuleName as C
390 @
391 \eprog
392 entities must be referenced using `@C.@' as a qualifier instead of
393 `@VeryLongModuleName.@'.  This also allows a different module to be substituted
394 for @VeryLongModuleName@ without changing the qualifiers used for the imported module.
395 It is legal for more than one module in scope to 
396 use the same qualifier, provided that all names can still be resolved unambiguously.
397 For example:
398 \bprog
399 @
400   module M where
401     import qualified Foo as A
402     import qualified Baz as A
403     x = A.f
404 @
405 \eprog
406 This module is legal provided only that @Foo@ and @Baz@ do not both export @f@.
407
408 An @as@ clause may also be used on an un-@qualified@ @import@ statement:
409 \bprog
410 @
411   import Foo as A(f)
412 @
413 \eprog
414 This declaration brings into scope @f@ and @A.f@.
415
416
417 \subsubsection{Examples}
418
419 To clarify the above import rules, suppose the module @A@ exports @x@ and @y@.
420 Then this table shows what names are brought into scope by the specified import statement:
421 \begin{center}
422 \begin{tabular}{|ll|}
423 \hline
424 Import declaration & Names brought into scope \\
425 \hline
426   @import A@                    & @x@, @y@, @A.x@, @A.y@ \\
427   @import A()@                  & (nothing)     \\
428   @import A(x)@                 & @x@, @A.x@ \\
429   @import qualified A@          & @A.x@, @A.y@ \\
430   @import qualified A()@        & (nothing) \\
431   @import qualified A(x)@       & @A.x@ \\
432   @import A hiding ()@          & @x@, @y@, @A.x@, @A.y@ \\
433   @import A hiding (x)@         & @y@, @A.y@ \\
434   @import qualified A hiding ()@        & @A.x@, @A.y@ \\
435   @import qualified A hiding (x)@       & @A.y@ \\
436   @import A as B@               & @x@, @y@, @B.x@, @B.y@ \\
437   @import A as B(x)@            & @B.x@ \\
438   @import qualified A as B@     & @B.x@, @B.y@ \\
439 \hline
440 \end{tabular}
441 \end{center}
442 In all cases, all instance declarations in scope in module @A@ are imported
443 (Section~\ref{import-instances}).
444
445 \subsection{Importing and Exporting Instance Declarations}
446 \label{import-instances}
447 \index{instance declaration!importing and exporting}
448
449 Instance declarations cannot be explicitly named on import or export
450 lists.  All instances in scope within a module are {\em always}
451 exported and any import brings {\em all} instances in from the
452 imported module.  Thus, an
453 instance declaration is in scope if and only if a chain of @import@
454 declarations leads to the module containing the instance declaration.
455
456 For example, @import M()@ does not bring
457 any new names in scope from module @M@, but does bring in any instances
458 visible in @M@.  A module whose only purpose is to provide instance
459 declarations can have an empty export list.  For example
460 \bprog
461 @
462   module MyInstances() where
463     instance Show (a -> b) where
464         show fn = "<<function>>"
465     instance Show (IO a) where
466         show io = "<<IO action>>"
467 @
468 \eprog
469
470 \subsection{Name Clashes and Closure}
471
472 \subsubsection{Qualified names}\index{qualified name}
473 \label{qualifiers}
474
475 A {\em qualified name} is written as "modid"@.@"name" (Section~\ref{ids}).
476
477 A qualified name is brought into scope:
478 \begin{itemize}
479 \item {\em By a top level declaration.}
480 A top-level declaration brings into scope both the unqualified {\em and}
481 the qualified name of the entity being defined.  Thus:
482 \bprog
483 @
484   module M where
485     f x = ...
486     g x = M.f x x
487 @
488 \eprog
489 is legal.  The {\em defining} occurrence must mention the {\em unqualified} name; therefore, it is
490 illegal to write
491 \bprog
492 @
493   module M where
494     M.f x = ...                 -- ILLEGAL
495     g x = let M.y = x+1 in ...  -- ILLEGAL
496 @
497 \eprog
498 \item {\em By an @import@ declaration.}  An @import@ declaration, whether @qualified@ or not,
499 always brings into scope the qualified name of the imported entity (Section~\ref{import}).
500 \end{itemize}
501 Qualifiers may also be applied to
502 names imported by an unqualified import; this allows a qualified
503 import to be replaced with an unqualified one without forcing changes
504 in the references to the imported names.  
505
506
507 \subsubsection{Name clashes}
508
509 If a module contains a bound occurrence of a name, such as @f@ or @A.f@,
510 it must be possible unambiguously to resolve which entity is thereby referred to;
511 that is, there must be only one binding for @f@ or @A.f@ respectively.
512
513 It is {\em not} an error for there to exist names that cannot be so 
514 resolved, provided that the program does not mention those names.  For example:
515 \bprog
516 @
517   module A where
518     import B
519     import C
520     tup = (b, c, d, x)
521   
522   module B( d, b, x, y ) where
523     import D
524     x = ...
525     y = ...
526     b = ...
527   
528   module C( d, c, x, y ) where
529     import D
530     x = ...
531     y = ...
532     c = ...
533
534   module D( d ) where
535     d = ...
536 @
537 \eprog
538 Consider the definition of @tup@.  
539 \begin{itemize}
540 \item The references to @b@ and @c@
541 can be unambiguously resolved to @b@ declared in @B@, and @c@ declared in
542 @C@ respectively.  
543 \item The reference to @d@ is unambiguously resolved to
544 @d@ declared in @D@.  In this case the same entity is brought into scope by two routes
545 (the import of @B@ and the import of @C@), and can be referred to in @A@ by the names
546 @d@, @B.d@, and @C.d@.
547 \item The reference to @x@ is ambiguous: it could mean @x@ declared in @B@, or @x@ 
548 declared in @C@.  The ambiguity could be fixed by replacing the reference to @x@ by
549 @B.x@ or @C.x@.
550 \item There is no reference to @y@, so it is not erroneous that distinct entities called
551 @y@ are exported by both @B@ and @C@.  An error is only reported if @y@ is actually mentioned.
552 \end{itemize}
553
554 The name occurring in a type signature or fixity declarations is
555 always unqualified, and unambiguously refers to another declaration in
556 the same declaration list (except that the fixity declaration for a
557 class method can occur at top level --- Section~\ref{fixity}). For example,
558 the following module is legal:
559 \bprog
560 @
561   module F where
562
563     sin :: Float -> Float
564     sin x = (x::Float)
565
566     f x = Prelude.sin (F.sin x)
567 @
568 \eprog
569 The local declaration for @sin@ is
570 legal, even though the Prelude function @sin@ is implicitly in
571 scope. The references to @Prelude.sin@ and @F.sin@ must both be qualified
572 to make it unambigous which @sin@ is meant. However, the unqualified
573 name "@sin@" in the type signature in the first line of @F@ unambiguously
574 refers to the local declaration for @sin@.
575
576 \subsubsection{Closure}
577 \label{closure}
578 \index{closure}
579
580 Every module in a \Haskell{} program must be {\em closed}.  That is,
581 every name explicitly mentioned by the source code
582 must be either defined locally or imported from another module.
583 However, entities that the compiler requires for type checking or other
584 compile time analysis need not be imported if they are not mentioned
585 by name.  The \Haskell{} compilation system is responsible for finding
586 any information needed for compilation without the help of the
587 programmer.  That is, the import of a variable @x@ does not
588 require that the datatypes and classes in the signature of @x@ be
589 brought into the module along with @x@ unless these entities are
590 referenced by name in the user program.  The \Haskell{}
591 system silently imports any information that must accompany an
592 entity for type checking or any other purposes.  Such entities need
593 not even be explicitly exported: the following program is valid even though
594 @T@ does not escape @M1@:
595 \bprog
596 @
597   module M1(x) where
598     data T = T
599     x = T
600   
601   module M2 where
602     import M1(x)
603     y = x
604 @
605 \eprog
606 In this example, there is no way to supply an explicit type signature
607 for @y@ since @T@ is not in scope.
608 Whether or not @T@ is explicitly exported, module @M2@ knows
609 enough about @T@ to correctly type check the program.
610
611 The type of an exported entity is unaffected by non-exported type
612 synonyms.  For example, in
613 \bprog
614 @
615   module M(x) where
616     type T = Int
617     x :: T
618     x = 1
619 @
620 \eprog
621 the type of @x@ is both @T@ and @Int@; these are interchangeable even
622 when @T@ is not in scope.  That is, the definition of @T@ is available
623 to any module that encounters it whether or not the name @T@ is
624 in scope.  The only reason to export @T@ is to allow other modules to
625 refer it by name; the type checker finds the definition of @T@ if
626 needed whether or not it is exported.
627
628 \subsection{Standard Prelude}
629 \label{standard-prelude}
630 \index{standard prelude}
631 \index{libraries}
632 Many of the features of \Haskell{} are defined in \Haskell{}
633 itself as a library of standard datatypes, classes, and
634 functions, called the ``Standard Prelude.''  In
635 \Haskell{}, the Prelude is contained in the
636 module @Prelude@.\indexmodule{Prelude} There are also
637 many predefined library modules, which provide less frequently used
638 functions and types.  For example, arrays, 
639 tables, and most of the input/output are all part of the standard
640 libraries.    These are 
641 defined in the Haskell Library Report\cite{libraries},
642 a separate document.  Separating
643 libraries from the Prelude has the advantage of reducing the size and
644 complexity of the Prelude, allowing it to be more easily assimilated,
645 and increasing the space of useful names available to the programmer.
646
647 Prelude and library modules differ from other modules in that
648 their semantics (but not their implementation) are a fixed part of the
649 \Haskell{} language definition.
650 This means, for example, that a compiler may optimize calls to
651 functions in the Prelude without consulting the source code
652 of the Prelude.
653
654 \subsubsection{The @Prelude@ Module}
655 \indexmodule{Prelude}
656 \index{Prelude!implicit import of}
657
658 The @Prelude@ module is imported automatically into all modules as if
659 by the statement `@import Prelude@', if and only if it is not imported
660 with an explicit @import@ declaration. This provision for explicit
661 import allows entities defined in the Prelude to be selectively imported,
662 just like those from any other module.
663
664 The semantics of the entities in @Prelude@ is specified by a reference
665 implementation of @Prelude@ written in \Haskell{}, given in
666 Appendix~\ref{stdprelude}.  Some datatypes (such as @Int@) and
667 functions (such as @Int@ addition) cannot be specified directly in
668 \Haskell{}.  Since the treatment of such entities depends on the
669 implementation, they are not formally defined in the appendix.
670 The implementation of
671 @Prelude@ is also incomplete in its treatment of tuples: there should
672 be an infinite family of tuples and their instance declarations, but the
673 implementation only gives a scheme.
674
675 Appendix~\ref{stdprelude} defines the module @Prelude@ using
676 several other modules: @PreludeList@, @PreludeIO@, and so on.
677 These modules are {\em not} part of Haskell 98, and they cannot be imported
678 separately.  They are simply 
679 there to help explain the structure of the @Prelude@ module; they
680 should be considered part of its implementation, not part of the language
681 definition.
682  
683 \subsubsection{Shadowing Prelude Names}
684 \label{std-prel-shadowing}
685
686 The rules about the Prelude have been cast so that it is
687 possible to use Prelude names for nonstandard purposes; however,
688 every module that does so must have an @import@ declaration
689 that makes this nonstandard usage explicit.  For example:
690 \bprog
691 @
692   module A( null, nonNull ) where
693     import Prelude hiding( null ) 
694     null, nonNull :: Int -> Bool
695     null    x = x == 0
696     nonNull x = not (null x)
697 @
698 \eprog
699 Module @A@ redefines @null@, and contains an unqualified reference to @null@
700 on the right hand side of @nonNull@. The latter would be ambiguous
701 without the @hiding(null)@ on the @import Prelude@ statement. Every
702 module that imports @A@ unqualified, and then makes an unqualified
703 reference to @null@ must also resolve the ambiguous use of @null@ just as
704 @A@ does. Thus there is little danger of accidentally shadowing Prelude
705 names.
706
707 It is possible to construct and use a different module to serve in
708 place of the Prelude.  Other than the fact that it is implicitly
709 imported, the Prelude is an ordinary \Haskell{} module; it is special
710 only in that some objects in the Prelude are referenced by special
711 syntactic constructs.  Redefining names used by the Prelude does not
712 affect the meaning of these special constructs.  For example, in
713 \bprog
714 @
715   module B where
716     import qualified Prelude
717     import MyPrelude
718       ...
719 @
720 \eprog
721 @B@ imports nothing from @Prelude@, but the
722 explicit @import qualified Prelude@ declaration prevents the automatic
723 import of 
724 @Prelude@.  @import MyPrelude@ brings the
725 non-standard prelude into scope.  As before, the
726 standard prelude names are hidden explicitly.  Special
727 syntax, such as lists or tuples, always refers to prelude entities:
728 there is no way to redefine the meaning of @[x]@ in terms of a
729 different implementation of lists.
730
731 It is not possible, however, to hide @instance@ declarations in the
732 @Prelude@.  For example, one cannot define a new instance for @Show Char@.
733
734 \subsection{Separate Compilation}
735 \index{separate compilation}
736 Depending on the \Haskell{} implementation used, separate compilation
737 of mutually recursive modules may require that imported modules contain
738 additional information so that they may be referenced before they are
739 compiled.  Explicit type signatures for all exported values may be
740 necessary to deal with mutual recursion.  The
741 precise details of separate compilation are not defined by this
742 report. 
743
744 \subsection{Abstract Datatypes}
745 \label{abstract-types}
746
747 \index{abstract datatype}
748 The ability to export a datatype without its constructors
749 allows the construction of abstract datatypes (ADTs).  For example,
750 an ADT for stacks could be defined as:
751 \bprog
752 @
753   module Stack( StkType, push, pop, empty ) where
754     data StkType a = EmptyStk | Stk a (StkType a)
755     push x s = Stk x s
756     pop (Stk _ s) = s
757     empty = EmptyStk
758 @
759 \eprog
760 Modules importing @Stack@ cannot construct values of type @StkType@
761 because they do not have access to the constructors of the type.
762 Instead, they must use @push@, @pop@, and @empty@ to construct such values.
763
764 It is also possible to build an ADT on top of an existing type by
765 using a @newtype@ declaration.  For example, stacks can be defined
766 with lists: 
767 \bprog
768 @
769   module Stack( StkType, push, pop, empty ) where
770     newtype StkType a = Stk [a]
771     push x (Stk s) = Stk (x:s)
772     pop (Stk (_:s)) = Stk s
773     empty = Stk []
774 @
775 \eprogNoSkip
776
777
778 %**~footer
779
780 % Local Variables: 
781 % mode: latex
782 % End: