A module defines a collection of values, datatypes, type synonyms, classes, etc. (see Section 4) in an environment created by a set of imports, resources brought into scope from other modules, and exports some of these resources, making them available to other modules. We use the term entity to refer to a value, type, or classes defined in, imported into, or perhaps exported from a module.

A Haskell program is a collection of modules, one of which, by convention, must be called Main and must export the value main. The value of the program is the value of the identifier main in module Main, and main must have type IO () (see Section 7).

Modules may reference other modules via explicit import declarations, each giving the name of a module to be imported and specifying its entities to be imported. Modules may be mutually recursive.

The name-space for modules is flat, with each module being associated with a unique module name (which are Haskell identifiers beginning with a capital letter; i.e. modid). There is one distinguished module, Prelude, which is imported into all programs by default (see Section 5.3), plus a set of standard library modules which may be imported as required (see the Haskell Library Report).

5.1 Module Structure

A module defines a mutually recursive scope containing declarations for value bindings, data types, type synonyms, classes, etc. (see Section 4).

module        -> module modid [exports] where body
              |  body
body          -> { [impdecls ;] [[fixdecls ;] topdecls [;]] }
              |  { impdecls [;] }

modid         -> conid
impdecls      -> impdecl1 ; ... ; impdecln                
topdecls      -> topdecl1 ; ... ; topdecln                

A module begins with a header: the keyword module, the module name, and a list of entities (enclosed in round parentheses) to be exported. The header is followed by an optional list of import declarations that specify modules to be imported, optionally restricting the imported bindings. This is followed by an optional list of fixity declarations and the module body. The module body is simply a list of top-level declarations (topdecls), as described in Section 4.

An abbreviated form of module is permitted which consists only of the module body. If this is used, the header is assumed to be `module Main(main) where'. If the first lexeme in the abbreviated module is not a {, then the layout rule applies for the top level of the module.

5.1.1 Export Lists

exports       -> ( export1 , ... , exportn [ , ] )        

export        -> qvar
              |  qtycon [(..) | ( qcname1 , ... , qcnamen )]     
              |  qtycls [(..) | ( qvar1 , ... , qvarn )]     
              |  module modid

qcname        -> qvar | qcon

An export list identifies the entities to be exported by a module declaration. A module implementation may only export an entity that it declares, or that it imports from some other module. If the export list is omitted, all values, types and classes defined in the module are exported, but not those that are imported.

Entities in an export list may be named as follows:

1. Ordinary values, whether declared in the module body or imported, may be named by giving the name of the value as a qvarid. Operators should be enclosed in parentheses to turn them into qvarid's.
2. An algebraic datatype T declared by a data or newtype declaration may be named in one of three ways:
   • The form T names the type but not the constructors or field names. The ability to export a type without its constructors allows the construction of abstract datatypes (see Section 5.5).
   • The form T(qcname1,...,qcname_n), where all and only the constructors and field names are listed without duplications, names the type and all its constructors and field names.
   • The abbreviated form T(..) names the type and all its constructors and field names.
   Data constructors and field names cannot be named in export lists in any other way.
3. A type synonym T declared by a type declaration may be named by the form T.
4. A class C with operations f1,...,f_n declared in a class declaration may be named in one of three ways:
   • The form C names the class but not the class methods.
   • The form C(f1,...,f_n), where all and only the class methods in that class are listed without duplications, names the class and all its methods.
   • The abbreviated form C(..) names the class and all its methods.
   Class methods may not be named in export lists in any other way.
5. The set of all entities brought into scope from a module m by one or more unqualified import declarations may be named by the form `module m', which is equivalent to listing all of the entities imported from the module. For example:

   
         module Queue( module Stack, enqueue, dequeue ) where
             import Stack
             ...
   

   Here the module Queue uses the module name Stack in its export list to abbreviate all the entities imported from Stack.

6. A module can name its own local definitions in its export list using its name in the `module m' syntax. For example:

   
          module Mod1(module Mod1, module Mod2) where
          import Mod2
          import Mod3
   

   Here module Mod1 exports all local definitions as well as those from imported from Mod2 but not those imported from Mod3.

module A ( B.f, C.f, g, B.g ) where   -- an invalid module
import qualified B(f,g)
import qualified C(f)
g = True

5.1.2 Import Declarations

impdecl       -> import [qualified] modid [as modid] [impspec]
impspec       -> ( import1 , ... , importn [ , ] )        
              |  hiding ( import1 , ... , importn [ , ] )     

import        -> var
              |  tycon [ (..) | ( cname1 , ... , cnamen )]     
              |  tycls [(..) | ( var1 , ... , varn )]     
cname         -> var | con

The entities exported by a module may be brought into scope in another module with an import declaration at the beginning of the module. The import declaration names the module to be imported and optionally specifies the entities to be imported. A single module may be imported by more than one import declaration. Imported names serve as top level declarations: they scope over the entire body of the module but may be shadowed by local non-top-level bindings. The effect of multiple import declarations is cumulative: an entity is in scope if it named by any of the import declarations in a module. The ordering of imports is irrelevant.

Exactly which entities are to be imported can be specified in one of three ways:

1. The imported entities can be specified explicitly by listing them in parentheses. Items in the list have the same form as those in export lists, except qualifiers are not permitted and the `module modid' entity is not permitted.

   The list must name only entities exported by the imported module. The list may be empty, in which case nothing except the instances are imported.

2. Entities can be excluded by using the form hiding(import1 , ... , import_n ), which specifies that all entities exported by the named module should be imported except for those named in the list. The effect of multiple import declarations is strictly cumulative: hiding an entity on one import declaration does not prevent the same entity from being imported by another import from the same module.

3. Finally, if impspec is omitted then all the entities exported by the specified module are imported.

When an import declaration uses the qualified keyword, the names brought into scope must be prefixed by the name of the imported module (or a local alias, if an as clause is present). A qualified name is written as modid.name. This allows full programmer control of the unqualified namespace: a locally defined entity can share the same name as a qualified import:

module Ring where
import qualified Prelude  -- All Prelude names must be qualified

l1 + l2 = l1 ++ l2        -- This + differs from the one in the Prelude
l1 * l2 = nub (l1 + l2)

succ = (Prelude.+ 1)

Imported modules may be assigned a local alias in the importing module using the as clause. For example, in

import qualified Complex as C

Since qualifier names are part of the lexical syntax, no spaces are allowed between the qualifier and the name. Sample parses are shown below.

It may be that a particular entity is imported into a module by more than one route --- for example, because it is exported by two modules, both of which are imported by a third module. Benign name clashes of this form are allowed, but it is a static error for two different entities to have the same name. When two entities have the same name, they are considered to be the same object if and only if they are defined by the same module. Two different qualified names may refer to the same entity; the name of the importing module does not affect the identity of an entity.

It is an error for two different entities to have the same name. This is valid:

module A
import B(f)
import qualified C(f)

5.1.3 Importing and Exporting Instance Declarations

5.2 Closure

module M1(x) where
data T = T
x = T

module M2 where
import M1(x)
y = x

The type of an exported entity is unaffected by non-exported type synonyms. For example, in

module M(x) where
type T = Int
x :: T
x = 1

5.3 Standard Prelude

Prelude and library modules differ from other modules in that their semantics (but not their implementation) are a fixed part of the Haskell language definition. This means, for example, that a compiler may optimize calls to functions in the Prelude without being concerned that a future change to the program will alter the semantics of the Prelude function.

5.3.1 The Prelude Module

The semantics of the entities in Prelude is specified by an implementation of Prelude written in Haskell, given in Appendix A. 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. 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.

5.3.2 Shadowing Prelude Names

The rules about the Prelude have been cast so that it is possible to use Prelude names for nonstandard purposes; however, every module that does so must have an import declaration that makes this nonstandard usage explicit. For example:

     module A where
     import Prelude hiding (null)
     null x = []

It is possible to construct and use a different module to serve in place of the Prelude. Other than the fact that it is implicitly imported, the Prelude is an ordinary Haskell module; it is special only in that some objects in the Prelude are referenced by special syntactic constructs. Redefining names used by the Prelude does not affect the meaning of these special constructs. For example, in

module B where
import qualified Prelude
import MyPrelude
      ...

5.4 Separate Compilation

5.5 Abstract Datatypes

The ability to export a datatype without its constructors allows the construction of abstract datatypes (ADTs). For example, an ADT for stacks could be defined as:

module Stack( StkType, push, pop, empty ) where
	data StkType a = EmptyStk | Stk a (StkType a)
	push x s = Stk x s
	pop (Stk _ s) = s
	empty = EmptyStk

It is also possible to build an ADT on top of an existing type by using a newtype declaration. For example, stacks can be defined with lists:

module Stack( StkType, push, pop, empty ) where
	newtype StkType a = Stk [a]
	push x (Stk s) = Stk (x:s)
	pop (Stk (x:s)) = Stk s
	empty = Stk []

5.6 Fixity Declarations

fixdecls      -> fix1 ; ... ; fixn                        
fix           -> infixl [digit] ops 
              |  infixr [digit] ops
              |  infix  [digit] ops 
ops           -> op1 , ... , opn                          
op            -> varop | conop 

There are three kinds of fixity, non-, left- and right-associativity (infix, infixl, and infixr, respectively), and ten precedence levels, 0 to 9 inclusive (level 0 binds least tightly, and level 9 binds most tightly). If the digit is omitted, level 9 is assumed. Any operator lacking a fixity declaration is assumed to be infixl 9 (See Section 3 for more on the use of fixities). Table 2 lists the fixities and precedences of the operators defined in the Prelude.

Fixity is a property of the name of an identifier or operator: the same fixity attaches to every occurrence of an operator name in a module, whether at the top level or rebound at an inner level. For example:

module Foo
import Bar
infix 3 `op`

f x = ... where p `op` q = ...

Next section: Basic Types
The Haskell 1.3 Report