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 Uniquable Module where
 217   getUnique (Module p n) = getUnique (packageIdFS p `appendFS` moduleNameFS n)
 218
 219 instance Outputable Module where
 220   ppr = pprModule
 221
 222 instance Binary Module where
 223   put_ bh (Module p n) = put_ bh p >> put_ bh n
 224   get bh = do p <- get bh; n <- get bh; return (Module p n)
 225
 226 -- | This gives a stable ordering, as opposed to the Ord instance which
 227 -- gives an ordering based on the 'Unique's of the components, which may
 228 -- not be stable from run to run of the compiler.
 229 stableModuleCmp :: Module -> Module -> Ordering
 230 stableModuleCmp (Module p1 n1) (Module p2 n2)
 231    = (p1 `stablePackageIdCmp`  p2) `thenCmp`
 232      (n1 `stableModuleNameCmp` n2)
 233
 234 mkModule :: PackageId -> ModuleName -> Module
 235 mkModule = Module
 236
 237 pprModule :: Module -> SDoc
 238 pprModule mod@(Module p n)  = pprPackagePrefix p mod <> pprModuleName n
 239
 240 pprPackagePrefix :: PackageId -> Module -> PprStyle -> Pretty.Doc
 241 pprPackagePrefix p mod = getPprStyle doc
 242  where
 243    doc sty
 244        | codeStyle sty =
 245           if p == mainPackageId
 246                 then empty -- never qualify the main package in code
 247                 else ftext (zEncodeFS (packageIdFS p)) <> char '_'
 248        | qualModule sty mod = ftext (packageIdFS (modulePackageId mod)) <> char ':'
 249                 -- the PrintUnqualified tells us which modules have to
 250                 -- be qualified with package names
 251        | otherwise = empty
 252 \end{code}
 253
 254 %************************************************************************
 255 %*                                                                      *
 256 \subsection{PackageId}
 257 %*                                                                      *
 258 %************************************************************************
 259
 260 \begin{code}
 261 -- | Essentially just a string identifying a package, including the version: e.g. parsec-1.0
 262 newtype PackageId = PId FastString deriving( Eq )
 263     -- here to avoid module loops with PackageConfig
 264
 265 instance Uniquable PackageId where
 266  getUnique pid = getUnique (packageIdFS pid)
 267
 268 -- Note: *not* a stable lexicographic ordering, a faster unique-based
 269 -- ordering.
 270 instance Ord PackageId where
 271   nm1 `compare` nm2 = getUnique nm1 `compare` getUnique nm2
 272
 273 stablePackageIdCmp :: PackageId -> PackageId -> Ordering
 274 -- ^ Compares package ids lexically, rather than by their 'Unique's
 275 stablePackageIdCmp p1 p2 = packageIdFS p1 `compare` packageIdFS p2
 276
 277 instance Outputable PackageId where
 278    ppr pid = text (packageIdString pid)
 279
 280 instance Binary PackageId where
 281   put_ bh pid = put_ bh (packageIdFS pid)
 282   get bh = do { fs <- get bh; return (fsToPackageId fs) }
 283
 284 fsToPackageId :: FastString -> PackageId
 285 fsToPackageId = PId
 286
 287 packageIdFS :: PackageId -> FastString
 288 packageIdFS (PId fs) = fs
 289
 290 stringToPackageId :: String -> PackageId
 291 stringToPackageId = fsToPackageId . mkFastString
 292
 293 packageIdString :: PackageId -> String
 294 packageIdString = unpackFS . packageIdFS
 295
 296
 297 -- -----------------------------------------------------------------------------
 298 -- $wired_in_packages
 299 -- Certain packages are known to the compiler, in that we know about certain
 300 -- entities that reside in these packages, and the compiler needs to
 301 -- declare static Modules and Names that refer to these packages.  Hence
 302 -- the wired-in packages can't include version numbers, since we don't want
 303 -- to bake the version numbers of these packages into GHC.
 304 --
 305 -- So here's the plan.  Wired-in packages are still versioned as
 306 -- normal in the packages database, and you can still have multiple
 307 -- versions of them installed.  However, for each invocation of GHC,
 308 -- only a single instance of each wired-in package will be recognised
 309 -- (the desired one is selected via @-package@\/@-hide-package@), and GHC
 310 -- will use the unversioned 'PackageId' below when referring to it,
 311 -- including in .hi files and object file symbols.  Unselected
 312 -- versions of wired-in packages will be ignored, as will any other
 313 -- package that depends directly or indirectly on it (much as if you
 314 -- had used @-ignore-package@).
 315
 316 -- Make sure you change 'Packages.findWiredInPackages' if you add an entry here
 317
 318 integerPackageId, primPackageId,
 319   basePackageId, rtsPackageId, haskell98PackageId,
 320   thPackageId, ndpPackageId, dphSeqPackageId, dphParPackageId,
 321   mainPackageId  :: PackageId
 322 primPackageId      = fsToPackageId (fsLit "ghc-prim")
 323 integerPackageId   = fsToPackageId (fsLit "integer")
 324 basePackageId      = fsToPackageId (fsLit "base")
 325 rtsPackageId       = fsToPackageId (fsLit "rts")
 326 haskell98PackageId = fsToPackageId (fsLit "haskell98")
 327 thPackageId        = fsToPackageId (fsLit "template-haskell")
 328 ndpPackageId       = fsToPackageId (fsLit "ndp")
 329 dphSeqPackageId    = fsToPackageId (fsLit "dph-seq")
 330 dphParPackageId    = fsToPackageId (fsLit "dph-par")
 331
 332 -- | This is the package Id for the current program.  It is the default
 333 -- package Id if you don't specify a package name.  We don't add this prefix
 334 -- to symbol names, since there can be only one main package per program.
 335 mainPackageId      = fsToPackageId (fsLit "main")
 336 \end{code}
 337
 338 %************************************************************************
 339 %*                                                                      *
 340 \subsection{@ModuleEnv@s}
 341 %*                                                                      *
 342 %************************************************************************
 343
 344 \begin{code}
 345 -- | A map keyed off of 'Module's
 346 type ModuleEnv elt = FiniteMap Module elt
 347
 348 emptyModuleEnv       :: ModuleEnv a
 349 mkModuleEnv          :: [(Module, a)] -> ModuleEnv a
 350 unitModuleEnv        :: Module -> a -> ModuleEnv a
 351 extendModuleEnv      :: ModuleEnv a -> Module -> a -> ModuleEnv a
 352 extendModuleEnv_C    :: (a->a->a) -> ModuleEnv a -> Module -> a -> ModuleEnv a
 353 plusModuleEnv        :: ModuleEnv a -> ModuleEnv a -> ModuleEnv a
 354 extendModuleEnvList  :: ModuleEnv a -> [(Module, a)] -> ModuleEnv a
 355 extendModuleEnvList_C  :: (a->a->a) -> ModuleEnv a -> [(Module, a)] -> ModuleEnv a
 356
 357 delModuleEnvList     :: ModuleEnv a -> [Module] -> ModuleEnv a
 358 delModuleEnv         :: ModuleEnv a -> Module -> ModuleEnv a
 359 plusModuleEnv_C      :: (a -> a -> a) -> ModuleEnv a -> ModuleEnv a -> ModuleEnv a
 360 mapModuleEnv         :: (a -> b) -> ModuleEnv a -> ModuleEnv b
 361 moduleEnvKeys        :: ModuleEnv a -> [Module]
 362 moduleEnvElts        :: ModuleEnv a -> [a]
 363
 364 isEmptyModuleEnv     :: ModuleEnv a -> Bool
 365 lookupModuleEnv      :: ModuleEnv a -> Module     -> Maybe a
 366 lookupWithDefaultModuleEnv :: ModuleEnv a -> a -> Module -> a
 367 elemModuleEnv        :: Module -> ModuleEnv a -> Bool
 368 foldModuleEnv        :: (a -> b -> b) -> b -> ModuleEnv a -> b
 369 filterModuleEnv      :: (a -> Bool) -> ModuleEnv a -> ModuleEnv a
 370
 371 filterModuleEnv f   = filterFM (\_ v -> f v)
 372 elemModuleEnv       = elemFM
 373 extendModuleEnv     = addToFM
 374 extendModuleEnv_C   = addToFM_C
 375 extendModuleEnvList = addListToFM
 376 extendModuleEnvList_C = addListToFM_C
 377 plusModuleEnv_C     = plusFM_C
 378 delModuleEnvList    = delListFromFM
 379 delModuleEnv        = delFromFM
 380 plusModuleEnv       = plusFM
 381 lookupModuleEnv     = lookupFM
 382 lookupWithDefaultModuleEnv = lookupWithDefaultFM
 383 mapModuleEnv f      = mapFM (\_ v -> f v)
 384 mkModuleEnv         = listToFM
 385 emptyModuleEnv      = emptyFM
 386 moduleEnvKeys       = keysFM
 387 moduleEnvElts       = eltsFM
 388 unitModuleEnv       = unitFM
 389 isEmptyModuleEnv    = isEmptyFM
 390 foldModuleEnv f     = foldFM (\_ v -> f v)
 391 \end{code}
 392
 393 \begin{code}
 394 -- | A set of 'Module's
 395 type ModuleSet = FiniteMap Module ()
 396
 397 mkModuleSet     :: [Module] -> ModuleSet
 398 extendModuleSet :: ModuleSet -> Module -> ModuleSet
 399 emptyModuleSet  :: ModuleSet
 400 moduleSetElts   :: ModuleSet -> [Module]
 401 elemModuleSet   :: Module -> ModuleSet -> Bool
 402
 403 emptyModuleSet    = emptyFM
 404 mkModuleSet ms    = listToFM [(m,()) | m <- ms ]
 405 extendModuleSet s m = addToFM s m ()
 406 moduleSetElts     = keysFM
 407 elemModuleSet     = elemFM
 408 \end{code}
 409
 410 A ModuleName has a Unique, so we can build mappings of these using
 411 UniqFM.
 412
 413 \begin{code}
 414 -- | A map keyed off of 'ModuleName's (actually, their 'Unique's)
 415 type ModuleNameEnv elt = UniqFM elt
 416 \end{code}