Fix reference to "Haskell 98"
[haskell-report.git] / report / modules.verb
index de6487d..46cd095 100644 (file)
@@ -1,5 +1,5 @@
 %
-% $Header: /home/cvs/root/haskell-report/report/modules.verb,v 1.15 2001/11/01 13:43:43 simonpj Exp $
+% $Header: /home/cvs/root/haskell-report/report/modules.verb,v 1.20 2003/01/13 13:08:56 simonpj Exp $
 %
 %**<title>The Haskell 98 Report: Modules</title>
 %*section 5
@@ -9,9 +9,9 @@
 \index{module}
 
 A module defines a collection of values, datatypes, type synonyms,
-classes, etc.~(see Section~\ref{declarations}) in an environment created
-by a set of {\em imports}, resources brought into scope from other modules, 
-and {\em exports} some of these resources, making them available to
+classes, etc.~(see Chapter~\ref{declarations}), in an environment created
+by a set of {\em imports} (resources brought into scope from other modules).
+It {\em exports} some of these resources, making them available to
 other modules.  
 We use the term {\em entity}\index{entity} to refer to
 a value, type, or class defined in, imported into, or perhaps
@@ -22,7 +22,7 @@ which, by convention, must be called @Main@\indexmodule{Main} and must
 export the value @main@\indextt{main}.  The {\em value} of the program
 is the value of the identifier @main@ in module @Main@,
 which must be a computation of type $@IO@~\tau$ for some type $\tau$
-(see Section~\ref{io}).  When the program is executed, the computation
+(see Chapter~\ref{io}).  When the program is executed, the computation
 @main@ is performed, and its result (of type $\tau$) is discarded.
 
 Modules may reference other modules via explicit
@@ -69,20 +69,36 @@ Because they are allowed to be mutually recursive,
 modules allow a program to be partitioned freely without regard to
 dependencies.
 
-The name-space for modules themselves is flat, with each module being associated
-with a unique module name (which are \Haskell{} identifiers
-beginning with a capital letter; i.e.~"modid").  
+\begin{haskellprime}
+A module name (lexeme "modid") is a sequence of one or more
+identifiers beginning with capital letters, separated by dots, with no
+intervening spaces.  For example, @Data.Bool@, @Main@ and
+@Foreign.Marshal.Alloc@ are all valid module names.
+
+@@@
+modid   ->  \hprime{\{conid @.@\}} conid       & (\tr{modules})
+@@@
+\indexsyn{modid}%
+
+Module names can be thought of as being arranged in a hierarchy in
+which appending a new component creates a child of the original module
+name.  For example, the module @Control.Monad.ST@ is a child of the
+@Control.Monad@ sub-hierarchy.  This is purely a convention, however,
+and not part of the language definition; in this report a "modid" is
+treated as a single identifier occupying a flat namespace.
+\end{haskellprime}
+
 There is one distinguished module, @Prelude@, which is imported into
 all modules by default (see Section~\ref{standard-prelude}), plus a
 set of standard library modules that may be imported as required
-(see the \Haskell{} Library Report\cite{libraries}).
+(see Part~\ref{libraries}).
 
 \subsection{Module Structure} 
 \label{module-implementations}
 
 A module defines a mutually
 recursive scope containing declarations for value bindings, data
-types, type synonyms, classes, etc. (see Section~\ref{declarations}).
+types, type synonyms, classes, etc. (see Chapter~\ref{declarations}).
 
 @@@
 module -> @module@ modid [exports] @where@ body
@@ -91,14 +107,12 @@ body   -> @{@ impdecls @;@ topdecls @}@
        | @{@ impdecls  @}@
        | @{@ topdecls @}@
 
-modid       -> conid
-impdecls     -> impdecl_1 @;@ ... @;@ impdecl_n        & \qquad (n>=1)
-topdecls     -> topdecl_1 @;@ ... @;@ topdecl_n        & \qquad (n>=1)
+impdecls     -> impdecl_1 @;@ ... @;@ impdecl_n        & (n>=1)
+topdecls     -> topdecl_1 @;@ ... @;@ topdecl_n        & (n>=1)
 @@@
 
 \indexsyn{module}%
 \indexsyn{body}%
-\indexsyn{modid}%
 \indexsyn{impdecls}%
 \indexsyn{topdecls}%
 
@@ -108,7 +122,7 @@ begins with a header: the keyword
 parentheses) to be exported.  The header is followed by a possibly-empty
 list of @import@ declarations ("impdecls", Section~\ref{import}) that specify modules to be imported,
 optionally restricting the imported bindings.  
-This is followed by a possibly-empty list of top-level declarations ("topdecls", Section~\ref{declarations}).  
+This is followed by a possibly-empty list of top-level declarations ("topdecls", Chapter~\ref{declarations}).
 
 An abbreviated form of module, consisting only 
 of\index{abbreviated module}
@@ -123,18 +137,17 @@ for the top level of the module.
 \index{export list}
 
 @@@
-exports         -> @(@ export_1 @,@ ... @,@ export_n [ @,@ ] @)@ & \qquad (n>=0)
+exports         -> @(@ export_1 @,@ ... @,@ export_n [ @,@ ] @)@ & (n>=0)
 
 export   -> qvar
-        |  qtycon [@(..)@ | @(@ qcname_1 @,@ ... @,@ qcname_n @)@] & \qquad (n>=0)
-        |  qtycls [@(..)@ | @(@ qvar_1 @,@ ... @,@ qvar_n @)@] & \qquad (n>=0)
+        |  qtycon [@(..)@ | @(@ cname_1 @,@ ... @,@ cname_n @)@] &  (n>=0)
+        |  qtycls [@(..)@ | @(@ var_1 @,@ ... @,@ var_n @)@] &  (n>=0)
          |  @module@ modid
 
-qcname   -> qvar | qcon
+cname   -> var | con
 @@@
 \indexsyn{exports}%
 \indexsyn{export}%
-\indexsyn{qcname}%
 
 An {\em export list} identifies the entities to be exported by a
 module declaration.  A module implementation may only export an entity
@@ -147,9 +160,9 @@ Entities in an export list may be named as follows:
 \item
 A value, field name, or class method, whether declared in
 the module body or imported,
-may be named by giving the name of the value as a "qvarid".
+may be named by giving the name of the value as a "qvarid", which must be in scope.
 Operators should be enclosed in parentheses to turn them into
-"qvarid"'s.  
+"qvarid"s.  
 
 \item
 An algebraic datatype "T"
@@ -162,20 +175,34 @@ The form "T" names the type {\em but not the constructors or field names}.
 The ability to export a type without its constructors allows the
 construction of abstract datatypes (see Section~\ref{abstract-types}).
 \item
-The form $T@(@qcname_1@,@\ldots@,@qcname_n@)@$, where the $qcname_i$
-name only constructors and field names in $T$, 
+The form $T@(@c_1@,@\ldots@,@c_n@)@$, 
 names the type and some or all of its constructors and field names.  
-The $qcname_i$ must not contain duplications.  
+% Restriction removed March 02:
+% The subordinate names $c_i$ must not contain duplicates.  
 \item
 The abbreviated form "T@(..)@" names the type 
 and all its constructors and field names that are currently in scope
 (whether qualified or not).
 \end{itemize}
-Data constructors cannot be named in export lists in any other way.
+In all cases, the (possibly-qualified) type constructor "T" must be in scope. 
+The constructor and field names $c_i$ in the second form are unqualified;
+one of these subordinate names is legal if and only if (a) it names a constructor
+or field of "T", and (b) the constructor or field
+is in scope in the module body {\em regardless of whether it is in scope
+under a qualified or unqualified name}. For example, the following is 
+legal
+\bprog
+@
+  module A( Mb.Maybe( Nothing, Just ) ) where
+    import qualified Data.Maybe as Mb
+@
+\eprog
+Data constructors cannot be named in export lists except as subordinate names, because
+they cannot otherwise be distinguished from type constructors.
 
 \item
 A type synonym "T" declared by a
-@type@ declaration may be named by the form "T".
+@type@ declaration may be named by the form "T", where "T" is in scope.
 \index{type synonym}
 
 \item
@@ -186,19 +213,25 @@ declared in a @class@ declaration may be named in one of three ways:
 \item
 The form "C" names the class {\em but not the class methods}.
 \item
-The form $C@(@f_1@,@\ldots@,@f_n@)@$, where
-the $f_i$ must be class methods of $C$, names the class and some or all
-of its methods.  The $f_i$ must not contain duplications.
+The form $C@(@f_1@,@\ldots@,@f_n@)@$, names the class and some or all
+of its methods.  
+% Restriction removed March 02:
+% The subordinate names $f_i$ must not contain duplicates.
 \item
 The abbreviated form $C@(..)@$ names the class and all its methods
 that are in scope (whether qualified or not).
 \end{itemize}
+In all cases, "C" must be in scope.  In the second form,
+one of the (unqualified) subordinate names $f_i$ is legal if and only if (a) it names a
+class method of "C", and (b) the class method 
+is in scope in the module body regardless of whether it is in scope
+under a qualified or unqualified name.
 
 \item
-The form ``@module M@'' abbreviates the set of all entities whose
-{\em unqualified} name, $e$, is in scope, and for which the {\em qualified} name
-$M.e$ is also in scope and refers to the same entity as $e$.  This set
-may be empty.
+The form ``@module M@'' names the set of all entities that are in
+scope with both an unqualified name ``@e@'' and a qualified name
+``@M.e@''.
+This set may be empty.
 For example:
 \bprog
 @
@@ -247,11 +280,11 @@ The {\em unqualified} names of the entities exported by a module must all be dis
   g = f True
 @
 \eprog
-There are name clashes in the export list 
-between @C.g@ and @g@, 
-and between @module B@ and @C.f@ (assuming @B.f@ and @C.f@ are different entities), 
-even though there are no name clashes within module @A@ itself.  
-
+There are no name clashes within module @A@ itself, 
+but there are name clashes in the export list between @C.g@ and @g@
+(assuming @C.g@ and @g@ are different entities -- remember, modules
+can import each other recursively), and between @module B@ and @C.f@
+(assuming @B.f@ and @C.f@ are different entities).
 
 \subsection{Import Declarations}
 \label{import}
@@ -260,20 +293,20 @@ even though there are no name clashes within module @A@ itself.
 @@@
 impdecl   -> @import@ [@qualified@] modid [@as@ modid] [impspec]
          |     & (empty declaration)
-impspec   -> @(@ import_1 @,@ ... @,@ import_n [ @,@ ] @)@ & \qquad (n>=0)
-             |  @hiding@ @(@ import_1 @,@ ... @,@ import_n [ @,@ ] @)@ & \qquad (n>=0)
+impspec   -> @(@ import_1 @,@ ... @,@ import_n [ @,@ ] @)@ & (n>=0)
+             |  @hiding@ @(@ import_1 @,@ ... @,@ import_n [ @,@ ] @)@ & (n>=0)
 
 import    -> var
-         |  tycon [ @(..)@ | @(@ cname_1 @,@ ... @,@ cname_n @)@] & \qquad (n>=1)
-         |  tycls [@(..)@ | @(@ var_1 @,@ ... @,@ var_n @)@] & \qquad (n>=0)
+         |  tycon [ @(..)@ | @(@ cname_1 @,@ ... @,@ cname_n @)@] &  (n>=0)
+         |  tycls [@(..)@ | @(@ var_1 @,@ ... @,@ var_n @)@] & (n>=0)
 cname     -> var | con
 @@@
 %             var
 %          |  tycon
 %          |  tycon @(..)@
-%          |  tycon @(@ con_1 @,@ ... @,@ con_n@)@ & \qquad (n>=1)
+%          |  tycon @(@ con_1 @,@ ... @,@ con_n@)@ & (n>=1)
 %          |  tycls @(..)@
-%          |  tycls @(@ var_1 @,@ ... @,@ var_n@)@ & \qquad (n>=0)
+%          |  tycls @(@ var_1 @,@ ... @,@ var_n@)@ & (n>=0)
 \indexsyn{impdecl}%
 \indexsyn{impspec}%
 \indexsyn{import}%
@@ -296,7 +329,7 @@ The effect of multiple @import@ declarations is strictly
 cumulative: an entity is in scope if it is imported by any of the @import@
 declarations in a module.  The ordering of import declarations is irrelevant.
 
-Lexically speaking, the terminal symbols ``@as@'', ``@qualified@'' and
+Lexically, the terminal symbols ``@as@'', ``@qualified@'' and
 ``@hiding@'' are each a "varid" rather than a "reservedid".  They have
 special significance only in the context of an @import@ declaration;
 they may also be used as variables.
@@ -364,19 +397,21 @@ entity was originally declared}.
 The ability to exclude the unqualified names allows full programmer control of
 the unqualified namespace: a locally defined entity can share the same
 name as a qualified import:
+\par
+{\small
 \bprog
 @
   module Ring where
-  import qualified Prelude  -- All Prelude names must be qualified
-  import List( nub )
+  import qualified Prelude    -- All Prelude names must be qualified
+  import Data.List( nub )
 
-  l1 + l2 = l1 ++ l2        -- This + differs from the one in the Prelude
-  l1 * l2 = nub (l1 + l2)   -- This * differs from the one in the Prelude
+  l1 + l2 = l1 Prelude.++ l2  -- This + differs from the one in the Prelude
+  l1 * l2 = nub (l1 + l2)     -- This * differs from the one in the Prelude
 
   succ = (Prelude.+ 1)
 @
 \eprog
-
+}
 
 \subsubsection{Local aliases}
 \label{as-clause}
@@ -434,7 +469,7 @@ Import declaration & Names brought into scope \\
   @import qualified A hiding ()@       & @A.x@, @A.y@ \\
   @import qualified A hiding (x)@      & @A.y@ \\
   @import A as B@              & @x@, @y@, @B.x@, @B.y@ \\
-  @import A as B(x)@           & @B.x@ \\
+  @import A as B(x)@           & @x@, @B.x@ \\
   @import qualified A as B@    & @B.x@, @B.y@ \\
 \hline
 \end{tabular}
@@ -461,9 +496,9 @@ declarations can have an empty export list.  For example
 @
   module MyInstances() where
     instance Show (a -> b) where
-       show fn = "<<function>>"
+      show fn = "<<function>>"
     instance Show (IO a) where
-       show io = "<<IO action>>"
+      show io = "<<IO action>>"
 @
 \eprog
 
@@ -473,7 +508,6 @@ declarations can have an empty export list.  For example
 \label{qualifiers}
 
 A {\em qualified name} is written as "modid"@.@"name" (Section~\ref{ids}).
-
 A qualified name is brought into scope:
 \begin{itemize}
 \item {\em By a top level declaration.}
@@ -497,11 +531,10 @@ illegal to write
 \eprog
 \item {\em By an @import@ declaration.}  An @import@ declaration, whether @qualified@ or not,
 always brings into scope the qualified name of the imported entity (Section~\ref{import}).
-\end{itemize}
-Qualifiers may also be applied to
-names imported by an unqualified import; this allows a qualified
+This allows a qualified
 import to be replaced with an unqualified one without forcing changes
 in the references to the imported names.  
+\end{itemize}
 
 
 \subsubsection{Name clashes}
@@ -569,7 +602,7 @@ the following module is legal:
 The local declaration for @sin@ is
 legal, even though the Prelude function @sin@ is implicitly in
 scope. The references to @Prelude.sin@ and @F.sin@ must both be qualified
-to make it unambigous which @sin@ is meant. However, the unqualified
+to make it unambiguous which @sin@ is meant. However, the unqualified
 name "@sin@" in the type signature in the first line of @F@ unambiguously
 refers to the local declaration for @sin@.
 
@@ -635,11 +668,11 @@ functions, called the ``Standard Prelude.''  In
 \Haskell{}, the Prelude is contained in the
 module @Prelude@.\indexmodule{Prelude} There are also
 many predefined library modules, which provide less frequently used
-functions and types.  For example, arrays, 
-tables, and most of the input/output are all part of the standard
+functions and types.  For example, complex numbers, arrays, 
+and most of the input/output are all part of the standard
 libraries.    These are 
-defined in the Haskell Library Report\cite{libraries},
-a separate document.  Separating
+defined in Part~\ref{libraries}.
+Separating
 libraries from the Prelude has the advantage of reducing the size and
 complexity of the Prelude, allowing it to be more easily assimilated,
 and increasing the space of useful names available to the programmer.
@@ -651,7 +684,7 @@ This means, for example, that a compiler may optimize calls to
 functions in the Prelude without consulting the source code
 of the Prelude.
 
-\subsubsection{The @Prelude@ Module}
+\subsubsection{The \texorpdfstring{@Prelude@}{Prelude} Module}
 \indexmodule{Prelude}
 \index{Prelude!implicit import of}
 
@@ -663,18 +696,18 @@ just like those from any other module.
 
 The semantics of the entities in @Prelude@ is specified by a reference
 implementation of @Prelude@ written in \Haskell{}, given in
-Appendix~\ref{stdprelude}.  Some datatypes (such as @Int@) and
+Chapter~\ref{stdprelude}.  Some datatypes (such as @Int@) and
 functions (such as @Int@ addition) cannot be specified directly in
 \Haskell{}.  Since the treatment of such entities depends on the
-implementation, they are not formally defined in the appendix.
+implementation, they are not formally defined in Chapter~\ref{stdprelude}.
 The implementation of
 @Prelude@ is also incomplete in its treatment of tuples: there should
 be an infinite family of tuples and their instance declarations, but the
 implementation only gives a scheme.
 
-Appendix~\ref{stdprelude} defines the module @Prelude@ using
+Chapter~\ref{stdprelude} defines the module @Prelude@ using
 several other modules: @PreludeList@, @PreludeIO@, and so on.
-These modules are {\em not} part of Haskell 98, and they cannot be imported
+These modules are {\em not} part of Haskell, and they cannot be imported
 separately.  They are simply 
 there to help explain the structure of the @Prelude@ module; they
 should be considered part of its implementation, not part of the language
@@ -713,20 +746,23 @@ affect the meaning of these special constructs.  For example, in
 \bprog
 @
   module B where
-    import qualified Prelude
+    import Prelude()
     import MyPrelude
-      ...
+    f x = (x,x)
+    g x = (,) x x
+    h x = [x] ++ []
 @
 \eprog
-@B@ imports nothing from @Prelude@, but the
-explicit @import qualified Prelude@ declaration prevents the automatic
-import of 
-@Prelude@.  @import MyPrelude@ brings the
-non-standard prelude into scope.  As before, the
-standard prelude names are hidden explicitly.  Special
-syntax, such as lists or tuples, always refers to prelude entities:
-there is no way to redefine the meaning of @[x]@ in terms of a
+the explicit @import Prelude()@ declaration prevents the automatic
+import of @Prelude@, while the declaration @import MyPrelude@ brings the
+non-standard prelude into scope.  
+The special syntax for tuples (such as @(x,x)@ and @(,)@) and lists
+(such as @[x]@ and @[]@) continues to refer to the tuples and lists
+defined by the standard @Prelude@;
+there is no way to redefine the meaning of @[x]@, for example, in terms of a
 different implementation of lists.
+On the other hand, the use of @++@ is not special syntax, so it refers
+to @++@ imported from @MyPrelude@.
 
 It is not possible, however, to hide @instance@ declarations in the
 @Prelude@.  For example, one cannot define a new instance for @Show Char@.