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