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