2 % (c) The University of Glasgow 2006
3 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
5 \section[Name]{@Name@: to transmit name info from renamer to typechecker}
10 -- GHC uses several kinds of name internally:
12 -- * 'OccName.OccName': see "OccName#name_types"
14 -- * 'RdrName.RdrName': see "RdrName#name_types"
16 -- * 'Name.Name' is the type of names that have had their scoping and binding resolved. They
17 -- have an 'OccName.OccName' but also a 'Unique.Unique' that disambiguates Names that have
18 -- the same 'OccName.OccName' and indeed is used for all 'Name.Name' comparison. Names
19 -- also contain information about where they originated from, see "Name#name_sorts"
21 -- * 'Id.Id': see "Id#name_types"
23 -- * 'Var.Var': see "Var#name_types"
28 -- * External, if they name things declared in other modules. Some external
29 -- Names are wired in, i.e. they name primitives defined in the compiler itself
31 -- * Internal, if they name things in the module being compiled. Some internal
32 -- Names are system names, if they are names manufactured by the compiler
39 -- ** Creating 'Name's
40 mkInternalName, mkSystemName, mkDerivedInternalName,
41 mkSystemVarName, mkSysTvName,
42 mkFCallName, mkIPName,
44 mkExternalName, mkWiredInName,
46 -- ** Manipulating and deconstructing 'Name's
47 nameUnique, setNameUnique,
48 nameOccName, nameModule, nameModule_maybe,
50 hashName, localiseName,
52 nameSrcLoc, nameSrcSpan, pprNameLoc,
54 -- ** Predicates on 'Name's
55 isSystemName, isInternalName, isExternalName,
56 isTyVarName, isTyConName, isDataConName,
58 isWiredInName, isBuiltInSyntax,
59 wiredInNameTyThing_maybe,
62 -- * Class 'NamedThing' and overloaded friends
64 getSrcLoc, getSrcSpan, getOccString,
66 pprInfixName, pprPrefixName, pprModulePrefix,
67 getNameDepth, setNameDepth,
69 -- Re-export the OccName stuff
75 import {-# SOURCE #-} TypeRep( TyThing )
91 import Data.Word ( Word32 )
94 %************************************************************************
96 \subsection[Name-datatype]{The @Name@ datatype, and name construction}
98 %************************************************************************
101 -- | A unique, unambigious name for something, containing information about where
102 -- that thing originated.
104 n_sort :: NameSort, -- What sort of name it is
105 n_occ :: !OccName, -- Its occurrence name
106 n_uniq :: FastInt, -- UNPACK doesn't work, recursive type
107 --(note later when changing Int# -> FastInt: is that still true about UNPACK?)
108 n_loc :: !SrcSpan -- Definition site
111 -- NOTE: we make the n_loc field strict to eliminate some potential
112 -- (and real!) space leaks, due to the fact that we don't look at
113 -- the SrcLoc in a Name all that often.
115 setNameDepth :: Int -> Name -> Name
116 setNameDepth depth name = name { n_occ = setOccNameDepth depth (n_occ name) }
118 getNameDepth :: Name -> Int
119 getNameDepth name = getOccNameDepth $ n_occ name
124 | WiredIn Module TyThing BuiltInSyntax
125 -- A variant of External, for wired-in things
127 | Internal -- A user-defined Id or TyVar
128 -- defined in the module being compiled
130 | System -- A system-defined Id or TyVar. Typically the
131 -- OccName is very uninformative (like 's')
133 -- | BuiltInSyntax is for things like @(:)@, @[]@ and tuples,
134 -- which have special syntactic forms. They aren't in scope
136 data BuiltInSyntax = BuiltInSyntax | UserSyntax
139 Notes about the NameSorts:
141 1. Initially, top-level Ids (including locally-defined ones) get External names,
142 and all other local Ids get Internal names
144 2. Things with a External name are given C static labels, so they finally
145 appear in the .o file's symbol table. They appear in the symbol table
146 in the form M.n. If originally-local things have this property they
147 must be made @External@ first.
149 3. In the tidy-core phase, a External that is not visible to an importer
150 is changed to Internal, and a Internal that is visible is changed to External
152 4. A System Name differs in the following ways:
153 a) has unique attached when printing dumps
154 b) unifier eliminates sys tyvars in favour of user provs where possible
156 Before anything gets printed in interface files or output code, it's
157 fed through a 'tidy' processor, which zaps the OccNames to have
158 unique names; and converts all sys-locals to user locals
159 If any desugarer sys-locals have survived that far, they get changed to
162 Built-in syntax => It's a syntactic form, not "in scope" (e.g. [])
164 Wired-in thing => The thing (Id, TyCon) is fully known to the compiler,
165 not read from an interface file.
166 E.g. Bool, True, Int, Float, and many others
168 All built-in syntax is for wired-in things.
171 nameUnique :: Name -> Unique
172 nameOccName :: Name -> OccName
173 nameModule :: Name -> Module
174 nameSrcLoc :: Name -> SrcLoc
175 nameSrcSpan :: Name -> SrcSpan
177 nameUnique name = mkUniqueGrimily (iBox (n_uniq name))
178 nameOccName name = n_occ name
179 nameSrcLoc name = srcSpanStart (n_loc name)
180 nameSrcSpan name = n_loc name
183 %************************************************************************
185 \subsection{Predicates on names}
187 %************************************************************************
190 nameIsLocalOrFrom :: Module -> Name -> Bool
191 isInternalName :: Name -> Bool
192 isExternalName :: Name -> Bool
193 isSystemName :: Name -> Bool
194 isWiredInName :: Name -> Bool
196 isWiredInName (Name {n_sort = WiredIn _ _ _}) = True
197 isWiredInName _ = False
199 wiredInNameTyThing_maybe :: Name -> Maybe TyThing
200 wiredInNameTyThing_maybe (Name {n_sort = WiredIn _ thing _}) = Just thing
201 wiredInNameTyThing_maybe _ = Nothing
203 isBuiltInSyntax :: Name -> Bool
204 isBuiltInSyntax (Name {n_sort = WiredIn _ _ BuiltInSyntax}) = True
205 isBuiltInSyntax _ = False
207 isExternalName (Name {n_sort = External _}) = True
208 isExternalName (Name {n_sort = WiredIn _ _ _}) = True
209 isExternalName _ = False
211 isInternalName name = not (isExternalName name)
213 nameModule name = nameModule_maybe name `orElse` pprPanic "nameModule" (ppr name)
214 nameModule_maybe :: Name -> Maybe Module
215 nameModule_maybe (Name { n_sort = External mod}) = Just mod
216 nameModule_maybe (Name { n_sort = WiredIn mod _ _}) = Just mod
217 nameModule_maybe _ = Nothing
219 nameIsLocalOrFrom from name
220 | isExternalName name = from == nameModule name
223 isTyVarName :: Name -> Bool
224 isTyVarName name = isTvOcc (nameOccName name)
226 isTyConName :: Name -> Bool
227 isTyConName name = isTcOcc (nameOccName name)
229 isDataConName :: Name -> Bool
230 isDataConName name = isDataOcc (nameOccName name)
232 isValName :: Name -> Bool
233 isValName name = isValOcc (nameOccName name)
235 isVarName :: Name -> Bool
236 isVarName = isVarOcc . nameOccName
238 isSystemName (Name {n_sort = System}) = True
239 isSystemName _ = False
243 %************************************************************************
245 \subsection{Making names}
247 %************************************************************************
250 -- | Create a name which is (for now at least) local to the current module and hence
251 -- does not need a 'Module' to disambiguate it from other 'Name's
252 mkInternalName :: Unique -> OccName -> SrcSpan -> Name
253 mkInternalName uniq occ loc = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal, n_occ = occ, n_loc = loc }
254 -- NB: You might worry that after lots of huffing and
255 -- puffing we might end up with two local names with distinct
256 -- uniques, but the same OccName. Indeed we can, but that's ok
257 -- * the insides of the compiler don't care: they use the Unique
258 -- * when printing for -ddump-xxx you can switch on -dppr-debug to get the
259 -- uniques if you get confused
260 -- * for interface files we tidyCore first, which puts the uniques
261 -- into the print name (see setNameVisibility below)
263 mkDerivedInternalName :: (OccName -> OccName) -> Unique -> Name -> Name
264 mkDerivedInternalName derive_occ uniq (Name { n_occ = occ, n_loc = loc })
265 = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal
266 , n_occ = derive_occ occ, n_loc = loc }
268 -- | Create a name which definitely originates in the given module
269 mkExternalName :: Unique -> Module -> OccName -> SrcSpan -> Name
270 mkExternalName uniq mod occ loc
271 = Name { n_uniq = getKeyFastInt uniq, n_sort = External mod,
272 n_occ = occ, n_loc = loc }
274 -- | Create a name which is actually defined by the compiler itself
275 mkWiredInName :: Module -> OccName -> Unique -> TyThing -> BuiltInSyntax -> Name
276 mkWiredInName mod occ uniq thing built_in
277 = Name { n_uniq = getKeyFastInt uniq,
278 n_sort = WiredIn mod thing built_in,
279 n_occ = occ, n_loc = wiredInSrcSpan }
281 -- | Create a name brought into being by the compiler
282 mkSystemName :: Unique -> OccName -> Name
283 mkSystemName uniq occ = Name { n_uniq = getKeyFastInt uniq, n_sort = System,
284 n_occ = occ, n_loc = noSrcSpan }
286 mkSystemVarName :: Unique -> FastString -> Name
287 mkSystemVarName uniq fs = mkSystemName uniq (mkVarOccFS fs)
289 mkSysTvName :: Unique -> FastString -> Name
290 mkSysTvName uniq fs = mkSystemName uniq (mkOccNameFS tvName fs)
292 -- | Make a name for a foreign call
293 mkFCallName :: Unique -> String -> Name
294 -- The encoded string completely describes the ccall
295 mkFCallName uniq str = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal,
296 n_occ = mkVarOcc str, n_loc = noSrcSpan }
299 mkTickBoxOpName :: Unique -> String -> Name
300 mkTickBoxOpName uniq str
301 = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal,
302 n_occ = mkVarOcc str, n_loc = noSrcSpan }
304 -- | Make the name of an implicit parameter
305 mkIPName :: Unique -> OccName -> Name
307 = Name { n_uniq = getKeyFastInt uniq,
314 -- When we renumber/rename things, we need to be
315 -- able to change a Name's Unique to match the cached
316 -- one in the thing it's the name of. If you know what I mean.
317 setNameUnique :: Name -> Unique -> Name
318 setNameUnique name uniq = name {n_uniq = getKeyFastInt uniq}
320 tidyNameOcc :: Name -> OccName -> Name
321 -- We set the OccName of a Name when tidying
322 -- In doing so, we change System --> Internal, so that when we print
323 -- it we don't get the unique by default. It's tidy now!
324 tidyNameOcc name@(Name { n_sort = System }) occ = name { n_occ = occ, n_sort = Internal}
325 tidyNameOcc name occ = name { n_occ = occ }
327 -- | Make the 'Name' into an internal name, regardless of what it was to begin with
328 localiseName :: Name -> Name
329 localiseName n = n { n_sort = Internal }
332 %************************************************************************
334 \subsection{Hashing and comparison}
336 %************************************************************************
339 hashName :: Name -> Int -- ToDo: should really be Word
340 hashName name = getKey (nameUnique name) + 1
341 -- The +1 avoids keys with lots of zeros in the ls bits, which
342 -- interacts badly with the cheap and cheerful multiplication in
345 cmpName :: Name -> Name -> Ordering
346 cmpName n1 n2 = iBox (n_uniq n1) `compare` iBox (n_uniq n2)
349 %************************************************************************
351 \subsection[Name-instances]{Instance declarations}
353 %************************************************************************
356 instance Eq Name where
357 a == b = case (a `compare` b) of { EQ -> True; _ -> False }
358 a /= b = case (a `compare` b) of { EQ -> False; _ -> True }
360 instance Ord Name where
361 a <= b = case (a `compare` b) of { LT -> True; EQ -> True; GT -> False }
362 a < b = case (a `compare` b) of { LT -> True; EQ -> False; GT -> False }
363 a >= b = case (a `compare` b) of { LT -> False; EQ -> True; GT -> True }
364 a > b = case (a `compare` b) of { LT -> False; EQ -> False; GT -> True }
365 compare a b = cmpName a b
367 instance Uniquable Name where
368 getUnique = nameUnique
370 instance NamedThing Name where
373 INSTANCE_TYPEABLE0(Name,nameTc,"Name")
375 instance Data Name where
377 toConstr _ = abstractConstr "Name"
378 gunfold _ _ = error "gunfold"
379 dataTypeOf _ = mkNoRepType "Name"
382 %************************************************************************
386 %************************************************************************
389 instance Binary Name where
391 case getUserData bh of
392 UserData{ ud_put_name = put_name } -> put_name bh name
396 return $! (ud_symtab (getUserData bh) ! fromIntegral (i::Word32))
399 %************************************************************************
401 \subsection{Pretty printing}
403 %************************************************************************
406 instance Outputable Name where
407 ppr name = pprName name
409 instance OutputableBndr Name where
410 pprBndr _ name = pprName name
412 pprName :: Name -> SDoc
413 pprName (Name {n_sort = sort, n_uniq = u, n_occ = occ})
414 = getPprStyle $ \ sty ->
416 WiredIn mod _ builtin -> pprExternal sty uniq mod occ True builtin
417 External mod -> pprExternal sty uniq mod occ False UserSyntax
418 System -> pprSystem sty uniq occ
419 Internal -> pprInternal sty uniq occ
420 where uniq = mkUniqueGrimily (iBox u)
422 pprExternal :: PprStyle -> Unique -> Module -> OccName -> Bool -> BuiltInSyntax -> SDoc
423 pprExternal sty uniq mod occ is_wired is_builtin
424 | codeStyle sty = ppr mod <> char '_' <> ppr_z_occ_name occ
425 -- In code style, always qualify
426 -- ToDo: maybe we could print all wired-in things unqualified
427 -- in code style, to reduce symbol table bloat?
428 | debugStyle sty = ppr mod <> dot <> ppr_occ_name occ
429 <> braces (hsep [if is_wired then ptext (sLit "(w)") else empty,
430 pprNameSpaceBrief (occNameSpace occ),
432 | BuiltInSyntax <- is_builtin = ppr_occ_name occ -- Never qualify builtin syntax
433 | otherwise = pprModulePrefix sty mod occ <> ppr_occ_name occ
435 pprInternal :: PprStyle -> Unique -> OccName -> SDoc
436 pprInternal sty uniq occ
437 | codeStyle sty = pprUnique uniq
438 | debugStyle sty = ppr_occ_name occ <> braces (hsep [pprNameSpaceBrief (occNameSpace occ),
440 | dumpStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
441 -- For debug dumps, we're not necessarily dumping
442 -- tidied code, so we need to print the uniques.
443 | otherwise = ppr_occ_name occ -- User style
445 -- Like Internal, except that we only omit the unique in Iface style
446 pprSystem :: PprStyle -> Unique -> OccName -> SDoc
447 pprSystem sty uniq occ
448 | codeStyle sty = pprUnique uniq
449 | debugStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
450 <> braces (pprNameSpaceBrief (occNameSpace occ))
451 | otherwise = ppr_occ_name occ <> ppr_underscore_unique uniq
452 -- If the tidy phase hasn't run, the OccName
453 -- is unlikely to be informative (like 's'),
454 -- so print the unique
457 pprModulePrefix :: PprStyle -> Module -> OccName -> SDoc
458 -- Print the "M." part of a name, based on whether it's in scope or not
459 -- See Note [Printing original names] in HscTypes
460 pprModulePrefix sty mod occ
461 | opt_SuppressModulePrefixes = empty
464 = case qualName sty mod occ of -- See Outputable.QualifyName:
465 NameQual modname -> ppr modname <> dot -- Name is in scope
466 NameNotInScope1 -> ppr mod <> dot -- Not in scope
467 NameNotInScope2 -> ppr (modulePackageId mod) <> colon -- Module not in
468 <> ppr (moduleName mod) <> dot -- scope eithber
471 ppr_underscore_unique :: Unique -> SDoc
472 -- Print an underscore separating the name from its unique
473 -- But suppress it if we aren't printing the uniques anyway
474 ppr_underscore_unique uniq
475 | opt_SuppressUniques = empty
476 | otherwise = char '_' <> pprUnique uniq
478 ppr_occ_name :: OccName -> SDoc
479 ppr_occ_name occ = ftext (occNameFS occ)
480 -- Don't use pprOccName; instead, just print the string of the OccName;
481 -- we print the namespace in the debug stuff above
483 -- In code style, we Z-encode the strings. The results of Z-encoding each FastString are
484 -- cached behind the scenes in the FastString implementation.
485 ppr_z_occ_name :: OccName -> SDoc
486 ppr_z_occ_name occ = ftext (zEncodeFS (occNameFS occ))
488 -- Prints (if mod information is available) "Defined at <loc>" or
489 -- "Defined in <mod>" information for a Name.
490 pprNameLoc :: Name -> SDoc
492 | isGoodSrcSpan loc = pprDefnLoc loc
493 | isInternalName name || isSystemName name
494 = ptext (sLit "<no location info>")
495 | otherwise = ptext (sLit "Defined in ") <> ppr (nameModule name)
496 where loc = nameSrcSpan name
499 %************************************************************************
501 \subsection{Overloaded functions related to Names}
503 %************************************************************************
506 -- | A class allowing convenient access to the 'Name' of various datatypes
507 class NamedThing a where
508 getOccName :: a -> OccName
511 getOccName n = nameOccName (getName n) -- Default method
515 getSrcLoc :: NamedThing a => a -> SrcLoc
516 getSrcSpan :: NamedThing a => a -> SrcSpan
517 getOccString :: NamedThing a => a -> String
519 getSrcLoc = nameSrcLoc . getName
520 getSrcSpan = nameSrcSpan . getName
521 getOccString = occNameString . getOccName
523 pprInfixName, pprPrefixName :: (Outputable a, NamedThing a) => a -> SDoc
524 -- See Outputable.pprPrefixVar, pprInfixVar;
525 -- add parens or back-quotes as appropriate
526 pprInfixName n = pprInfixVar (isSymOcc (getOccName n)) (ppr n)
527 pprPrefixName n = pprPrefixVar (isSymOcc (getOccName n)) (ppr n)