haddock fixes
[ghc.git] / compiler / basicTypes / Module.lhs
1 %
2 % (c) The University of Glasgow, 2004-2006
3 %
4
5 Module
6 ~~~~~~~~~~
7 Simply the name of a module, represented as a FastString.
8 These are Uniquable, hence we can build FiniteMaps with Modules as
9 the keys.
10
11 \begin{code}
12 module Module 
13     (
14         -- * The ModuleName type
15         ModuleName,
16         pprModuleName,
17         moduleNameFS,
18         moduleNameString,
19         moduleNameSlashes,
20         mkModuleName,
21         mkModuleNameFS,
22         stableModuleNameCmp,
23
24         -- * The PackageId type
25         PackageId,
26         fsToPackageId,
27         packageIdFS,
28         stringToPackageId,
29         packageIdString,
30         stablePackageIdCmp,
31
32         -- * Wired-in PackageIds
33         -- $wired_in_packages
34         primPackageId,
35         integerPackageId,
36         basePackageId,
37         rtsPackageId,
38         haskell98PackageId,
39         thPackageId,
40         ndpPackageId,
41         dphSeqPackageId,
42         dphParPackageId,
43         mainPackageId,
44
45         -- * The Module type
46         Module,
47         modulePackageId, moduleName,
48         pprModule,
49         mkModule,
50         stableModuleCmp,
51
52         -- * The ModuleLocation type
53         ModLocation(..),
54         addBootSuffix, addBootSuffix_maybe, addBootSuffixLocn,
55
56         -- * Module mappings
57         ModuleEnv,
58         elemModuleEnv, extendModuleEnv, extendModuleEnvList, 
59         extendModuleEnvList_C, plusModuleEnv_C,
60         delModuleEnvList, delModuleEnv, plusModuleEnv, lookupModuleEnv,
61         lookupWithDefaultModuleEnv, mapModuleEnv, mkModuleEnv, emptyModuleEnv,
62         moduleEnvKeys, moduleEnvElts, unitModuleEnv, isEmptyModuleEnv,
63         foldModuleEnv, extendModuleEnv_C, filterModuleEnv,
64
65         -- * ModuleName mappings
66         ModuleNameEnv,
67
68         -- * Sets of Modules
69         ModuleSet, 
70         emptyModuleSet, mkModuleSet, moduleSetElts, extendModuleSet, elemModuleSet
71     ) where
72
73 import Outputable
74 import qualified Pretty
75 import Unique
76 import FiniteMap
77 import LazyUniqFM
78 import FastString
79 import Binary
80 import Util
81
82 import System.FilePath
83 \end{code}
84
85 %************************************************************************
86 %*                                                                      *
87 \subsection{Module locations}
88 %*                                                                      *
89 %************************************************************************
90
91 \begin{code}
92 -- | Where a module lives on the file system: the actual locations
93 -- of the .hs, .hi and .o files, if we have them
94 data ModLocation
95    = ModLocation {
96         ml_hs_file   :: Maybe FilePath,
97                 -- The source file, if we have one.  Package modules
98                 -- probably don't have source files.
99
100         ml_hi_file   :: FilePath,
101                 -- Where the .hi file is, whether or not it exists
102                 -- yet.  Always of form foo.hi, even if there is an
103                 -- hi-boot file (we add the -boot suffix later)
104
105         ml_obj_file  :: FilePath
106                 -- Where the .o file is, whether or not it exists yet.
107                 -- (might not exist either because the module hasn't
108                 -- been compiled yet, or because it is part of a
109                 -- package with a .a file)
110   } deriving Show
111
112 instance Outputable ModLocation where
113    ppr = text . show
114 \end{code}
115
116 For a module in another package, the hs_file and obj_file
117 components of ModLocation are undefined.  
118
119 The locations specified by a ModLocation may or may not
120 correspond to actual files yet: for example, even if the object
121 file doesn't exist, the ModLocation still contains the path to
122 where the object file will reside if/when it is created.
123
124 \begin{code}
125 addBootSuffix :: FilePath -> FilePath
126 -- ^ Add the @-boot@ suffix to .hs, .hi and .o files
127 addBootSuffix path = path ++ "-boot"
128
129 addBootSuffix_maybe :: Bool -> FilePath -> FilePath
130 -- ^ Add the @-boot@ suffix if the @Bool@ argument is @True@
131 addBootSuffix_maybe is_boot path
132  | is_boot   = addBootSuffix path
133  | otherwise = path
134
135 addBootSuffixLocn :: ModLocation -> ModLocation
136 -- ^ Add the @-boot@ suffix to all file paths associated with the module
137 addBootSuffixLocn locn
138   = locn { ml_hs_file  = fmap addBootSuffix (ml_hs_file locn)
139          , ml_hi_file  = addBootSuffix (ml_hi_file locn)
140          , ml_obj_file = addBootSuffix (ml_obj_file locn) }
141 \end{code}
142
143
144 %************************************************************************
145 %*                                                                      *
146 \subsection{The name of a module}
147 %*                                                                      *
148 %************************************************************************
149
150 \begin{code}
151 -- | A ModuleName is essentially a simple string, e.g. @Data.List@.
152 newtype ModuleName = ModuleName FastString
153
154 instance Uniquable ModuleName where
155   getUnique (ModuleName nm) = getUnique nm
156
157 instance Eq ModuleName where
158   nm1 == nm2 = getUnique nm1 == getUnique nm2
159
160 -- Warning: gives an ordering relation based on the uniques of the
161 -- FastStrings which are the (encoded) module names.  This is _not_
162 -- a lexicographical ordering.
163 instance Ord ModuleName where
164   nm1 `compare` nm2 = getUnique nm1 `compare` getUnique nm2
165
166 instance Outputable ModuleName where
167   ppr = pprModuleName
168
169 instance Binary ModuleName where
170   put_ bh (ModuleName fs) = put_ bh fs
171   get bh = do fs <- get bh; return (ModuleName fs)
172
173 stableModuleNameCmp :: ModuleName -> ModuleName -> Ordering
174 -- ^ Compares module names lexically, rather than by their 'Unique's
175 stableModuleNameCmp n1 n2 = moduleNameFS n1 `compare` moduleNameFS n2
176
177 pprModuleName :: ModuleName -> SDoc
178 pprModuleName (ModuleName nm) = 
179     getPprStyle $ \ sty ->
180     if codeStyle sty 
181         then ftext (zEncodeFS nm)
182         else ftext nm
183
184 moduleNameFS :: ModuleName -> FastString
185 moduleNameFS (ModuleName mod) = mod
186
187 moduleNameString :: ModuleName -> String
188 moduleNameString (ModuleName mod) = unpackFS mod
189
190 mkModuleName :: String -> ModuleName
191 mkModuleName s = ModuleName (mkFastString s)
192
193 mkModuleNameFS :: FastString -> ModuleName
194 mkModuleNameFS s = ModuleName s
195
196 -- | Returns the string version of the module name, with dots replaced by slashes
197 moduleNameSlashes :: ModuleName -> String
198 moduleNameSlashes = dots_to_slashes . moduleNameString
199   where dots_to_slashes = map (\c -> if c == '.' then pathSeparator else c)
200 \end{code}
201
202 %************************************************************************
203 %*                                                                      *
204 \subsection{A fully qualified module}
205 %*                                                                      *
206 %************************************************************************
207
208 \begin{code}
209 -- | A Module is a pair of a 'PackageId' and a 'ModuleName'.
210 data Module = Module {
211    modulePackageId :: !PackageId,  -- pkg-1.0
212    moduleName      :: !ModuleName  -- A.B.C
213   }
214   deriving (Eq, Ord)
215
216 instance Outputable Module where
217   ppr = pprModule
218
219 instance Binary Module where
220   put_ bh (Module p n) = put_ bh p >> put_ bh n
221   get bh = do p <- get bh; n <- get bh; return (Module p n)
222
223 -- | This gives a stable ordering, as opposed to the Ord instance which
224 -- gives an ordering based on the 'Unique's of the components, which may
225 -- not be stable from run to run of the compiler.
226 stableModuleCmp :: Module -> Module -> Ordering
227 stableModuleCmp (Module p1 n1) (Module p2 n2) 
228    = (p1 `stablePackageIdCmp`  p2) `thenCmp`
229      (n1 `stableModuleNameCmp` n2)
230
231 mkModule :: PackageId -> ModuleName -> Module
232 mkModule = Module
233
234 pprModule :: Module -> SDoc
235 pprModule mod@(Module p n)  = pprPackagePrefix p mod <> pprModuleName n
236
237 pprPackagePrefix :: PackageId -> Module -> PprStyle -> Pretty.Doc
238 pprPackagePrefix p mod = getPprStyle doc
239  where
240    doc sty
241        | codeStyle sty = 
242           if p == mainPackageId 
243                 then empty -- never qualify the main package in code
244                 else ftext (zEncodeFS (packageIdFS p)) <> char '_'
245        | qualModule sty mod = ftext (packageIdFS (modulePackageId mod)) <> char ':'
246                 -- the PrintUnqualified tells us which modules have to
247                 -- be qualified with package names
248        | otherwise = empty
249 \end{code}
250
251 %************************************************************************
252 %*                                                                      *
253 \subsection{PackageId}
254 %*                                                                      *
255 %************************************************************************
256
257 \begin{code}
258 -- | Essentially just a string identifying a package, including the version: e.g. parsec-1.0
259 newtype PackageId = PId FastString deriving( Eq )
260     -- here to avoid module loops with PackageConfig
261
262 instance Uniquable PackageId where
263  getUnique pid = getUnique (packageIdFS pid)
264
265 -- Note: *not* a stable lexicographic ordering, a faster unique-based
266 -- ordering.
267 instance Ord PackageId where
268   nm1 `compare` nm2 = getUnique nm1 `compare` getUnique nm2
269
270 stablePackageIdCmp :: PackageId -> PackageId -> Ordering
271 -- ^ Compares package ids lexically, rather than by their 'Unique's
272 stablePackageIdCmp p1 p2 = packageIdFS p1 `compare` packageIdFS p2
273
274 instance Outputable PackageId where
275    ppr pid = text (packageIdString pid)
276
277 instance Binary PackageId where
278   put_ bh pid = put_ bh (packageIdFS pid)
279   get bh = do { fs <- get bh; return (fsToPackageId fs) }
280
281 fsToPackageId :: FastString -> PackageId
282 fsToPackageId = PId
283
284 packageIdFS :: PackageId -> FastString
285 packageIdFS (PId fs) = fs
286
287 stringToPackageId :: String -> PackageId
288 stringToPackageId = fsToPackageId . mkFastString
289
290 packageIdString :: PackageId -> String
291 packageIdString = unpackFS . packageIdFS
292
293
294 -- -----------------------------------------------------------------------------
295 -- $wired_in_packages
296 -- Certain packages are known to the compiler, in that we know about certain
297 -- entities that reside in these packages, and the compiler needs to 
298 -- declare static Modules and Names that refer to these packages.  Hence
299 -- the wired-in packages can't include version numbers, since we don't want
300 -- to bake the version numbers of these packages into GHC.
301 --
302 -- So here's the plan.  Wired-in packages are still versioned as
303 -- normal in the packages database, and you can still have multiple
304 -- versions of them installed.  However, for each invocation of GHC,
305 -- only a single instance of each wired-in package will be recognised
306 -- (the desired one is selected via @-package@\/@-hide-package@), and GHC
307 -- will use the unversioned 'PackageId' below when referring to it,
308 -- including in .hi files and object file symbols.  Unselected
309 -- versions of wired-in packages will be ignored, as will any other
310 -- package that depends directly or indirectly on it (much as if you
311 -- had used @-ignore-package@).
312
313 -- Make sure you change 'Packages.findWiredInPackages' if you add an entry here
314
315 integerPackageId, primPackageId,
316   basePackageId, rtsPackageId, haskell98PackageId,
317   thPackageId, ndpPackageId, dphSeqPackageId, dphParPackageId,
318   mainPackageId  :: PackageId
319 primPackageId      = fsToPackageId (fsLit "ghc-prim")
320 integerPackageId   = fsToPackageId (fsLit "integer")
321 basePackageId      = fsToPackageId (fsLit "base")
322 rtsPackageId       = fsToPackageId (fsLit "rts")
323 haskell98PackageId = fsToPackageId (fsLit "haskell98")
324 thPackageId        = fsToPackageId (fsLit "template-haskell")
325 ndpPackageId       = fsToPackageId (fsLit "ndp")
326 dphSeqPackageId    = fsToPackageId (fsLit "dph-seq")
327 dphParPackageId    = fsToPackageId (fsLit "dph-par")
328
329 -- | This is the package Id for the current program.  It is the default
330 -- package Id if you don't specify a package name.  We don't add this prefix
331 -- to symbol names, since there can be only one main package per program.
332 mainPackageId      = fsToPackageId (fsLit "main")
333 \end{code}
334
335 %************************************************************************
336 %*                                                                      *
337 \subsection{@ModuleEnv@s}
338 %*                                                                      *
339 %************************************************************************
340
341 \begin{code}
342 -- | A map keyed off of 'Module's
343 type ModuleEnv elt = FiniteMap Module elt
344
345 emptyModuleEnv       :: ModuleEnv a
346 mkModuleEnv          :: [(Module, a)] -> ModuleEnv a
347 unitModuleEnv        :: Module -> a -> ModuleEnv a
348 extendModuleEnv      :: ModuleEnv a -> Module -> a -> ModuleEnv a
349 extendModuleEnv_C    :: (a->a->a) -> ModuleEnv a -> Module -> a -> ModuleEnv a
350 plusModuleEnv        :: ModuleEnv a -> ModuleEnv a -> ModuleEnv a
351 extendModuleEnvList  :: ModuleEnv a -> [(Module, a)] -> ModuleEnv a
352 extendModuleEnvList_C  :: (a->a->a) -> ModuleEnv a -> [(Module, a)] -> ModuleEnv a
353                   
354 delModuleEnvList     :: ModuleEnv a -> [Module] -> ModuleEnv a
355 delModuleEnv         :: ModuleEnv a -> Module -> ModuleEnv a
356 plusModuleEnv_C      :: (a -> a -> a) -> ModuleEnv a -> ModuleEnv a -> ModuleEnv a
357 mapModuleEnv         :: (a -> b) -> ModuleEnv a -> ModuleEnv b
358 moduleEnvKeys        :: ModuleEnv a -> [Module]
359 moduleEnvElts        :: ModuleEnv a -> [a]
360                   
361 isEmptyModuleEnv     :: ModuleEnv a -> Bool
362 lookupModuleEnv      :: ModuleEnv a -> Module     -> Maybe a
363 lookupWithDefaultModuleEnv :: ModuleEnv a -> a -> Module -> a
364 elemModuleEnv        :: Module -> ModuleEnv a -> Bool
365 foldModuleEnv        :: (a -> b -> b) -> b -> ModuleEnv a -> b
366 filterModuleEnv      :: (a -> Bool) -> ModuleEnv a -> ModuleEnv a
367
368 filterModuleEnv f   = filterFM (\_ v -> f v)
369 elemModuleEnv       = elemFM
370 extendModuleEnv     = addToFM
371 extendModuleEnv_C   = addToFM_C
372 extendModuleEnvList = addListToFM
373 extendModuleEnvList_C = addListToFM_C
374 plusModuleEnv_C     = plusFM_C
375 delModuleEnvList    = delListFromFM
376 delModuleEnv        = delFromFM
377 plusModuleEnv       = plusFM
378 lookupModuleEnv     = lookupFM
379 lookupWithDefaultModuleEnv = lookupWithDefaultFM
380 mapModuleEnv f      = mapFM (\_ v -> f v)
381 mkModuleEnv         = listToFM
382 emptyModuleEnv      = emptyFM
383 moduleEnvKeys       = keysFM
384 moduleEnvElts       = eltsFM
385 unitModuleEnv       = unitFM
386 isEmptyModuleEnv    = isEmptyFM
387 foldModuleEnv f     = foldFM (\_ v -> f v)
388 \end{code}
389
390 \begin{code}
391 -- | A set of 'Module's
392 type ModuleSet = FiniteMap Module ()
393
394 mkModuleSet     :: [Module] -> ModuleSet
395 extendModuleSet :: ModuleSet -> Module -> ModuleSet
396 emptyModuleSet  :: ModuleSet
397 moduleSetElts   :: ModuleSet -> [Module]
398 elemModuleSet   :: Module -> ModuleSet -> Bool
399
400 emptyModuleSet    = emptyFM
401 mkModuleSet ms    = listToFM [(m,()) | m <- ms ]
402 extendModuleSet s m = addToFM s m ()
403 moduleSetElts     = keysFM
404 elemModuleSet     = elemFM
405 \end{code}
406
407 A ModuleName has a Unique, so we can build mappings of these using
408 UniqFM.
409
410 \begin{code}
411 -- | A map keyed off of 'ModuleName's (actually, their 'Unique's)
412 type ModuleNameEnv elt = UniqFM elt
413 \end{code}