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,
68 -- Re-export the OccName stuff
74 import {-# SOURCE #-} TypeRep( TyThing )
90 import Data.Word ( Word32 )
93 %************************************************************************
95 \subsection[Name-datatype]{The @Name@ datatype, and name construction}
97 %************************************************************************
100 -- | A unique, unambigious name for something, containing information about where
101 -- that thing originated.
103 n_sort :: NameSort, -- What sort of name it is
104 n_occ :: !OccName, -- Its occurrence name
105 n_uniq :: FastInt, -- UNPACK doesn't work, recursive type
106 --(note later when changing Int# -> FastInt: is that still true about UNPACK?)
107 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.
118 | WiredIn Module TyThing BuiltInSyntax
119 -- A variant of External, for wired-in things
121 | Internal -- A user-defined Id or TyVar
122 -- defined in the module being compiled
124 | System -- A system-defined Id or TyVar. Typically the
125 -- OccName is very uninformative (like 's')
127 -- | BuiltInSyntax is for things like @(:)@, @[]@ and tuples,
128 -- which have special syntactic forms. They aren't in scope
130 data BuiltInSyntax = BuiltInSyntax | UserSyntax
133 Notes about the NameSorts:
135 1. Initially, top-level Ids (including locally-defined ones) get External names,
136 and all other local Ids get Internal names
138 2. Things with a External name are given C static labels, so they finally
139 appear in the .o file's symbol table. They appear in the symbol table
140 in the form M.n. If originally-local things have this property they
141 must be made @External@ first.
143 3. In the tidy-core phase, a External that is not visible to an importer
144 is changed to Internal, and a Internal that is visible is changed to External
146 4. A System Name differs in the following ways:
147 a) has unique attached when printing dumps
148 b) unifier eliminates sys tyvars in favour of user provs where possible
150 Before anything gets printed in interface files or output code, it's
151 fed through a 'tidy' processor, which zaps the OccNames to have
152 unique names; and converts all sys-locals to user locals
153 If any desugarer sys-locals have survived that far, they get changed to
156 Built-in syntax => It's a syntactic form, not "in scope" (e.g. [])
158 Wired-in thing => The thing (Id, TyCon) is fully known to the compiler,
159 not read from an interface file.
160 E.g. Bool, True, Int, Float, and many others
162 All built-in syntax is for wired-in things.
165 nameUnique :: Name -> Unique
166 nameOccName :: Name -> OccName
167 nameModule :: Name -> Module
168 nameSrcLoc :: Name -> SrcLoc
169 nameSrcSpan :: Name -> SrcSpan
171 nameUnique name = mkUniqueGrimily (iBox (n_uniq name))
172 nameOccName name = n_occ name
173 nameSrcLoc name = srcSpanStart (n_loc name)
174 nameSrcSpan name = n_loc name
177 %************************************************************************
179 \subsection{Predicates on names}
181 %************************************************************************
184 nameIsLocalOrFrom :: Module -> Name -> Bool
185 isInternalName :: Name -> Bool
186 isExternalName :: Name -> Bool
187 isSystemName :: Name -> Bool
188 isWiredInName :: Name -> Bool
190 isWiredInName (Name {n_sort = WiredIn _ _ _}) = True
191 isWiredInName _ = False
193 wiredInNameTyThing_maybe :: Name -> Maybe TyThing
194 wiredInNameTyThing_maybe (Name {n_sort = WiredIn _ thing _}) = Just thing
195 wiredInNameTyThing_maybe _ = Nothing
197 isBuiltInSyntax :: Name -> Bool
198 isBuiltInSyntax (Name {n_sort = WiredIn _ _ BuiltInSyntax}) = True
199 isBuiltInSyntax _ = False
201 isExternalName (Name {n_sort = External _}) = True
202 isExternalName (Name {n_sort = WiredIn _ _ _}) = True
203 isExternalName _ = False
205 isInternalName name = not (isExternalName name)
207 nameModule name = nameModule_maybe name `orElse` pprPanic "nameModule" (ppr name)
208 nameModule_maybe :: Name -> Maybe Module
209 nameModule_maybe (Name { n_sort = External mod}) = Just mod
210 nameModule_maybe (Name { n_sort = WiredIn mod _ _}) = Just mod
211 nameModule_maybe _ = Nothing
213 nameIsLocalOrFrom from name
214 | isExternalName name = from == nameModule name
217 isTyVarName :: Name -> Bool
218 isTyVarName name = isTvOcc (nameOccName name)
220 isTyConName :: Name -> Bool
221 isTyConName name = isTcOcc (nameOccName name)
223 isDataConName :: Name -> Bool
224 isDataConName name = isDataOcc (nameOccName name)
226 isValName :: Name -> Bool
227 isValName name = isValOcc (nameOccName name)
229 isVarName :: Name -> Bool
230 isVarName = isVarOcc . nameOccName
232 isSystemName (Name {n_sort = System}) = True
233 isSystemName _ = False
237 %************************************************************************
239 \subsection{Making names}
241 %************************************************************************
244 -- | Create a name which is (for now at least) local to the current module and hence
245 -- does not need a 'Module' to disambiguate it from other 'Name's
246 mkInternalName :: Unique -> OccName -> SrcSpan -> Name
247 mkInternalName uniq occ loc = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal, n_occ = occ, n_loc = loc }
248 -- NB: You might worry that after lots of huffing and
249 -- puffing we might end up with two local names with distinct
250 -- uniques, but the same OccName. Indeed we can, but that's ok
251 -- * the insides of the compiler don't care: they use the Unique
252 -- * when printing for -ddump-xxx you can switch on -dppr-debug to get the
253 -- uniques if you get confused
254 -- * for interface files we tidyCore first, which puts the uniques
255 -- into the print name (see setNameVisibility below)
257 mkDerivedInternalName :: (OccName -> OccName) -> Unique -> Name -> Name
258 mkDerivedInternalName derive_occ uniq (Name { n_occ = occ, n_loc = loc })
259 = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal
260 , n_occ = derive_occ occ, n_loc = loc }
262 -- | Create a name which definitely originates in the given module
263 mkExternalName :: Unique -> Module -> OccName -> SrcSpan -> Name
264 mkExternalName uniq mod occ loc
265 = Name { n_uniq = getKeyFastInt uniq, n_sort = External mod,
266 n_occ = occ, n_loc = loc }
268 -- | Create a name which is actually defined by the compiler itself
269 mkWiredInName :: Module -> OccName -> Unique -> TyThing -> BuiltInSyntax -> Name
270 mkWiredInName mod occ uniq thing built_in
271 = Name { n_uniq = getKeyFastInt uniq,
272 n_sort = WiredIn mod thing built_in,
273 n_occ = occ, n_loc = wiredInSrcSpan }
275 -- | Create a name brought into being by the compiler
276 mkSystemName :: Unique -> OccName -> Name
277 mkSystemName uniq occ = Name { n_uniq = getKeyFastInt uniq, n_sort = System,
278 n_occ = occ, n_loc = noSrcSpan }
280 mkSystemVarName :: Unique -> FastString -> Name
281 mkSystemVarName uniq fs = mkSystemName uniq (mkVarOccFS fs)
283 mkSysTvName :: Unique -> FastString -> Name
284 mkSysTvName uniq fs = mkSystemName uniq (mkOccNameFS tvName fs)
286 -- | Make a name for a foreign call
287 mkFCallName :: Unique -> String -> Name
288 -- The encoded string completely describes the ccall
289 mkFCallName uniq str = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal,
290 n_occ = mkVarOcc str, n_loc = noSrcSpan }
293 mkTickBoxOpName :: Unique -> String -> Name
294 mkTickBoxOpName uniq str
295 = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal,
296 n_occ = mkVarOcc str, n_loc = noSrcSpan }
298 -- | Make the name of an implicit parameter
299 mkIPName :: Unique -> OccName -> Name
301 = Name { n_uniq = getKeyFastInt uniq,
308 -- When we renumber/rename things, we need to be
309 -- able to change a Name's Unique to match the cached
310 -- one in the thing it's the name of. If you know what I mean.
311 setNameUnique :: Name -> Unique -> Name
312 setNameUnique name uniq = name {n_uniq = getKeyFastInt uniq}
314 tidyNameOcc :: Name -> OccName -> Name
315 -- We set the OccName of a Name when tidying
316 -- In doing so, we change System --> Internal, so that when we print
317 -- it we don't get the unique by default. It's tidy now!
318 tidyNameOcc name@(Name { n_sort = System }) occ = name { n_occ = occ, n_sort = Internal}
319 tidyNameOcc name occ = name { n_occ = occ }
321 -- | Make the 'Name' into an internal name, regardless of what it was to begin with
322 localiseName :: Name -> Name
323 localiseName n = n { n_sort = Internal }
326 %************************************************************************
328 \subsection{Hashing and comparison}
330 %************************************************************************
333 hashName :: Name -> Int -- ToDo: should really be Word
334 hashName name = getKey (nameUnique name) + 1
335 -- The +1 avoids keys with lots of zeros in the ls bits, which
336 -- interacts badly with the cheap and cheerful multiplication in
339 cmpName :: Name -> Name -> Ordering
340 cmpName n1 n2 = iBox (n_uniq n1) `compare` iBox (n_uniq n2)
343 %************************************************************************
345 \subsection[Name-instances]{Instance declarations}
347 %************************************************************************
350 instance Eq Name where
351 a == b = case (a `compare` b) of { EQ -> True; _ -> False }
352 a /= b = case (a `compare` b) of { EQ -> False; _ -> True }
354 instance Ord Name where
355 a <= b = case (a `compare` b) of { LT -> True; EQ -> True; GT -> False }
356 a < b = case (a `compare` b) of { LT -> True; EQ -> False; GT -> False }
357 a >= b = case (a `compare` b) of { LT -> False; EQ -> True; GT -> True }
358 a > b = case (a `compare` b) of { LT -> False; EQ -> False; GT -> True }
359 compare a b = cmpName a b
361 instance Uniquable Name where
362 getUnique = nameUnique
364 instance NamedThing Name where
367 instance Data Name where
369 toConstr _ = abstractConstr "Name"
370 gunfold _ _ = error "gunfold"
371 dataTypeOf _ = mkNoRepType "Name"
374 %************************************************************************
378 %************************************************************************
381 instance Binary Name where
383 case getUserData bh of
384 UserData{ ud_put_name = put_name } -> put_name bh name
388 return $! (ud_symtab (getUserData bh) ! fromIntegral (i::Word32))
391 %************************************************************************
393 \subsection{Pretty printing}
395 %************************************************************************
398 instance Outputable Name where
399 ppr name = pprName name
401 instance OutputableBndr Name where
402 pprBndr _ name = pprName name
404 pprName :: Name -> SDoc
405 pprName (Name {n_sort = sort, n_uniq = u, n_occ = occ})
406 = getPprStyle $ \ sty ->
408 WiredIn mod _ builtin -> pprExternal sty uniq mod occ True builtin
409 External mod -> pprExternal sty uniq mod occ False UserSyntax
410 System -> pprSystem sty uniq occ
411 Internal -> pprInternal sty uniq occ
412 where uniq = mkUniqueGrimily (iBox u)
414 pprExternal :: PprStyle -> Unique -> Module -> OccName -> Bool -> BuiltInSyntax -> SDoc
415 pprExternal sty uniq mod occ is_wired is_builtin
416 | codeStyle sty = ppr mod <> char '_' <> ppr_z_occ_name occ
417 -- In code style, always qualify
418 -- ToDo: maybe we could print all wired-in things unqualified
419 -- in code style, to reduce symbol table bloat?
420 | debugStyle sty = ppr mod <> dot <> ppr_occ_name occ
421 <> braces (hsep [if is_wired then ptext (sLit "(w)") else empty,
422 pprNameSpaceBrief (occNameSpace occ),
424 | BuiltInSyntax <- is_builtin = ppr_occ_name occ -- Never qualify builtin syntax
425 | otherwise = pprModulePrefix sty mod occ <> ppr_occ_name occ
427 pprInternal :: PprStyle -> Unique -> OccName -> SDoc
428 pprInternal sty uniq occ
429 | codeStyle sty = pprUnique uniq
430 | debugStyle sty = ppr_occ_name occ <> braces (hsep [pprNameSpaceBrief (occNameSpace occ),
432 | dumpStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
433 -- For debug dumps, we're not necessarily dumping
434 -- tidied code, so we need to print the uniques.
435 | otherwise = ppr_occ_name occ -- User style
437 -- Like Internal, except that we only omit the unique in Iface style
438 pprSystem :: PprStyle -> Unique -> OccName -> SDoc
439 pprSystem sty uniq occ
440 | codeStyle sty = pprUnique uniq
441 | debugStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
442 <> braces (pprNameSpaceBrief (occNameSpace occ))
443 | otherwise = ppr_occ_name occ <> ppr_underscore_unique uniq
444 -- If the tidy phase hasn't run, the OccName
445 -- is unlikely to be informative (like 's'),
446 -- so print the unique
449 pprModulePrefix :: PprStyle -> Module -> OccName -> SDoc
450 -- Print the "M." part of a name, based on whether it's in scope or not
451 -- See Note [Printing original names] in HscTypes
452 pprModulePrefix sty mod occ
453 | opt_SuppressModulePrefixes = empty
456 = case qualName sty mod occ of -- See Outputable.QualifyName:
457 NameQual modname -> ppr modname <> dot -- Name is in scope
458 NameNotInScope1 -> ppr mod <> dot -- Not in scope
459 NameNotInScope2 -> ppr (modulePackageId mod) <> colon -- Module not in
460 <> ppr (moduleName mod) <> dot -- scope eithber
463 ppr_underscore_unique :: Unique -> SDoc
464 -- Print an underscore separating the name from its unique
465 -- But suppress it if we aren't printing the uniques anyway
466 ppr_underscore_unique uniq
467 | opt_SuppressUniques = empty
468 | otherwise = char '_' <> pprUnique uniq
470 ppr_occ_name :: OccName -> SDoc
471 ppr_occ_name occ = ftext (occNameFS occ)
472 -- Don't use pprOccName; instead, just print the string of the OccName;
473 -- we print the namespace in the debug stuff above
475 -- In code style, we Z-encode the strings. The results of Z-encoding each FastString are
476 -- cached behind the scenes in the FastString implementation.
477 ppr_z_occ_name :: OccName -> SDoc
478 ppr_z_occ_name occ = ftext (zEncodeFS (occNameFS occ))
480 -- Prints (if mod information is available) "Defined at <loc>" or
481 -- "Defined in <mod>" information for a Name.
482 pprNameLoc :: Name -> SDoc
484 | isGoodSrcSpan loc = pprDefnLoc loc
485 | isInternalName name || isSystemName name
486 = ptext (sLit "<no location info>")
487 | otherwise = ptext (sLit "Defined in ") <> ppr (nameModule name)
488 where loc = nameSrcSpan name
491 %************************************************************************
493 \subsection{Overloaded functions related to Names}
495 %************************************************************************
498 -- | A class allowing convenient access to the 'Name' of various datatypes
499 class NamedThing a where
500 getOccName :: a -> OccName
503 getOccName n = nameOccName (getName n) -- Default method
507 getSrcLoc :: NamedThing a => a -> SrcLoc
508 getSrcSpan :: NamedThing a => a -> SrcSpan
509 getOccString :: NamedThing a => a -> String
511 getSrcLoc = nameSrcLoc . getName
512 getSrcSpan = nameSrcSpan . getName
513 getOccString = occNameString . getOccName
515 pprInfixName, pprPrefixName :: (Outputable a, NamedThing a) => a -> SDoc
516 -- See Outputable.pprPrefixVar, pprInfixVar;
517 -- add parens or back-quotes as appropriate
518 pprInfixName n = pprInfixVar (isSymOcc (getOccName n)) (ppr n)
519 pprPrefixName n = pprPrefixVar (isSymOcc (getOccName n)) (ppr n)