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
112 -- NOTE: we make the n_loc field strict to eliminate some potential
113 -- (and real!) space leaks, due to the fact that we don't look at
114 -- the SrcLoc in a Name all that often.
116 setNameDepth :: Int -> Name -> Name
117 setNameDepth depth name = name { n_occ = setOccNameDepth depth (n_occ name) }
119 getNameDepth :: Name -> Int
120 getNameDepth name = getOccNameDepth $ n_occ name
125 | WiredIn Module TyThing BuiltInSyntax
126 -- A variant of External, for wired-in things
128 | Internal -- A user-defined Id or TyVar
129 -- defined in the module being compiled
131 | System -- A system-defined Id or TyVar. Typically the
132 -- OccName is very uninformative (like 's')
134 -- | BuiltInSyntax is for things like @(:)@, @[]@ and tuples,
135 -- which have special syntactic forms. They aren't in scope
137 data BuiltInSyntax = BuiltInSyntax | UserSyntax
140 Notes about the NameSorts:
142 1. Initially, top-level Ids (including locally-defined ones) get External names,
143 and all other local Ids get Internal names
145 2. Things with a External name are given C static labels, so they finally
146 appear in the .o file's symbol table. They appear in the symbol table
147 in the form M.n. If originally-local things have this property they
148 must be made @External@ first.
150 3. In the tidy-core phase, a External that is not visible to an importer
151 is changed to Internal, and a Internal that is visible is changed to External
153 4. A System Name differs in the following ways:
154 a) has unique attached when printing dumps
155 b) unifier eliminates sys tyvars in favour of user provs where possible
157 Before anything gets printed in interface files or output code, it's
158 fed through a 'tidy' processor, which zaps the OccNames to have
159 unique names; and converts all sys-locals to user locals
160 If any desugarer sys-locals have survived that far, they get changed to
163 Built-in syntax => It's a syntactic form, not "in scope" (e.g. [])
165 Wired-in thing => The thing (Id, TyCon) is fully known to the compiler,
166 not read from an interface file.
167 E.g. Bool, True, Int, Float, and many others
169 All built-in syntax is for wired-in things.
172 nameUnique :: Name -> Unique
173 nameOccName :: Name -> OccName
174 nameModule :: Name -> Module
175 nameSrcLoc :: Name -> SrcLoc
176 nameSrcSpan :: Name -> SrcSpan
178 nameUnique name = mkUniqueGrimily (iBox (n_uniq name))
179 nameOccName name = n_occ name
180 nameSrcLoc name = srcSpanStart (n_loc name)
181 nameSrcSpan name = n_loc name
184 %************************************************************************
186 \subsection{Predicates on names}
188 %************************************************************************
191 nameIsLocalOrFrom :: Module -> Name -> Bool
192 isInternalName :: Name -> Bool
193 isExternalName :: Name -> Bool
194 isSystemName :: Name -> Bool
195 isWiredInName :: Name -> Bool
197 isWiredInName (Name {n_sort = WiredIn _ _ _}) = True
198 isWiredInName _ = False
200 wiredInNameTyThing_maybe :: Name -> Maybe TyThing
201 wiredInNameTyThing_maybe (Name {n_sort = WiredIn _ thing _}) = Just thing
202 wiredInNameTyThing_maybe _ = Nothing
204 isBuiltInSyntax :: Name -> Bool
205 isBuiltInSyntax (Name {n_sort = WiredIn _ _ BuiltInSyntax}) = True
206 isBuiltInSyntax _ = False
208 isExternalName (Name {n_sort = External _}) = True
209 isExternalName (Name {n_sort = WiredIn _ _ _}) = True
210 isExternalName _ = False
212 isInternalName name = not (isExternalName name)
214 nameModule name = nameModule_maybe name `orElse` pprPanic "nameModule" (ppr name)
215 nameModule_maybe :: Name -> Maybe Module
216 nameModule_maybe (Name { n_sort = External mod}) = Just mod
217 nameModule_maybe (Name { n_sort = WiredIn mod _ _}) = Just mod
218 nameModule_maybe _ = Nothing
220 nameIsLocalOrFrom from name
221 | isExternalName name = from == nameModule name
224 isTyVarName :: Name -> Bool
225 isTyVarName name = isTvOcc (nameOccName name)
227 isTyConName :: Name -> Bool
228 isTyConName name = isTcOcc (nameOccName name)
230 isDataConName :: Name -> Bool
231 isDataConName name = isDataOcc (nameOccName name)
233 isValName :: Name -> Bool
234 isValName name = isValOcc (nameOccName name)
236 isVarName :: Name -> Bool
237 isVarName = isVarOcc . nameOccName
239 isSystemName (Name {n_sort = System}) = True
240 isSystemName _ = False
244 %************************************************************************
246 \subsection{Making names}
248 %************************************************************************
251 -- | Create a name which is (for now at least) local to the current module and hence
252 -- does not need a 'Module' to disambiguate it from other 'Name's
253 mkInternalName :: Unique -> OccName -> SrcSpan -> Name
254 mkInternalName uniq occ loc = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal, n_occ = occ, n_loc = loc }
255 -- NB: You might worry that after lots of huffing and
256 -- puffing we might end up with two local names with distinct
257 -- uniques, but the same OccName. Indeed we can, but that's ok
258 -- * the insides of the compiler don't care: they use the Unique
259 -- * when printing for -ddump-xxx you can switch on -dppr-debug to get the
260 -- uniques if you get confused
261 -- * for interface files we tidyCore first, which puts the uniques
262 -- into the print name (see setNameVisibility below)
264 mkDerivedInternalName :: (OccName -> OccName) -> Unique -> Name -> Name
265 mkDerivedInternalName derive_occ uniq (Name { n_occ = occ, n_loc = loc })
266 = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal
267 , n_occ = derive_occ occ, n_loc = loc }
269 -- | Create a name which definitely originates in the given module
270 mkExternalName :: Unique -> Module -> OccName -> SrcSpan -> Name
271 mkExternalName uniq mod occ loc
272 = Name { n_uniq = getKeyFastInt uniq, n_sort = External mod,
273 n_occ = occ, n_loc = loc }
275 -- | Create a name which is actually defined by the compiler itself
276 mkWiredInName :: Module -> OccName -> Unique -> TyThing -> BuiltInSyntax -> Name
277 mkWiredInName mod occ uniq thing built_in
278 = Name { n_uniq = getKeyFastInt uniq,
279 n_sort = WiredIn mod thing built_in,
280 n_occ = occ, n_loc = wiredInSrcSpan }
282 -- | Create a name brought into being by the compiler
283 mkSystemName :: Unique -> OccName -> Name
284 mkSystemName uniq occ = Name { n_uniq = getKeyFastInt uniq, n_sort = System,
285 n_occ = occ, n_loc = noSrcSpan }
287 mkSystemVarName :: Unique -> FastString -> Name
288 mkSystemVarName uniq fs = mkSystemName uniq (mkVarOccFS fs)
290 mkSysTvName :: Unique -> FastString -> Name
291 mkSysTvName uniq fs = mkSystemName uniq (mkOccNameFS tvName fs)
293 -- | Make a name for a foreign call
294 mkFCallName :: Unique -> String -> Name
295 -- The encoded string completely describes the ccall
296 mkFCallName uniq str = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal,
297 n_occ = mkVarOcc str, n_loc = noSrcSpan }
300 mkTickBoxOpName :: Unique -> String -> Name
301 mkTickBoxOpName uniq str
302 = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal,
303 n_occ = mkVarOcc str, n_loc = noSrcSpan }
305 -- | Make the name of an implicit parameter
306 mkIPName :: Unique -> OccName -> Name
308 = Name { n_uniq = getKeyFastInt uniq,
315 -- When we renumber/rename things, we need to be
316 -- able to change a Name's Unique to match the cached
317 -- one in the thing it's the name of. If you know what I mean.
318 setNameUnique :: Name -> Unique -> Name
319 setNameUnique name uniq = name {n_uniq = getKeyFastInt uniq}
321 tidyNameOcc :: Name -> OccName -> Name
322 -- We set the OccName of a Name when tidying
323 -- In doing so, we change System --> Internal, so that when we print
324 -- it we don't get the unique by default. It's tidy now!
325 tidyNameOcc name@(Name { n_sort = System }) occ = name { n_occ = occ, n_sort = Internal}
326 tidyNameOcc name occ = name { n_occ = occ }
328 -- | Make the 'Name' into an internal name, regardless of what it was to begin with
329 localiseName :: Name -> Name
330 localiseName n = n { n_sort = Internal }
333 %************************************************************************
335 \subsection{Hashing and comparison}
337 %************************************************************************
340 hashName :: Name -> Int -- ToDo: should really be Word
341 hashName name = getKey (nameUnique name) + 1
342 -- The +1 avoids keys with lots of zeros in the ls bits, which
343 -- interacts badly with the cheap and cheerful multiplication in
346 cmpName :: Name -> Name -> Ordering
347 cmpName n1 n2 = iBox (n_uniq n1) `compare` iBox (n_uniq n2)
350 %************************************************************************
352 \subsection[Name-instances]{Instance declarations}
354 %************************************************************************
357 instance Eq Name where
358 a == b = case (a `compare` b) of { EQ -> True; _ -> False }
359 a /= b = case (a `compare` b) of { EQ -> False; _ -> True }
361 instance Ord Name where
362 a <= b = case (a `compare` b) of { LT -> True; EQ -> True; GT -> False }
363 a < b = case (a `compare` b) of { LT -> True; EQ -> False; GT -> False }
364 a >= b = case (a `compare` b) of { LT -> False; EQ -> True; GT -> True }
365 a > b = case (a `compare` b) of { LT -> False; EQ -> False; GT -> True }
366 compare a b = cmpName a b
368 instance Uniquable Name where
369 getUnique = nameUnique
371 instance NamedThing Name where
374 instance Data Name where
376 toConstr _ = abstractConstr "Name"
377 gunfold _ _ = error "gunfold"
378 dataTypeOf _ = mkNoRepType "Name"
381 %************************************************************************
385 %************************************************************************
388 instance Binary Name where
390 case getUserData bh of
391 UserData{ ud_put_name = put_name } -> put_name bh name
395 return $! (ud_symtab (getUserData bh) ! fromIntegral (i::Word32))
398 %************************************************************************
400 \subsection{Pretty printing}
402 %************************************************************************
405 instance Outputable Name where
406 ppr name = pprName name
408 instance OutputableBndr Name where
409 pprBndr _ name = pprName name
411 pprName :: Name -> SDoc
412 pprName (Name {n_sort = sort, n_uniq = u, n_occ = occ})
413 = getPprStyle $ \ sty ->
415 WiredIn mod _ builtin -> pprExternal sty uniq mod occ True builtin
416 External mod -> pprExternal sty uniq mod occ False UserSyntax
417 System -> pprSystem sty uniq occ
418 Internal -> pprInternal sty uniq occ
419 where uniq = mkUniqueGrimily (iBox u)
421 pprExternal :: PprStyle -> Unique -> Module -> OccName -> Bool -> BuiltInSyntax -> SDoc
422 pprExternal sty uniq mod occ is_wired is_builtin
423 | codeStyle sty = ppr mod <> char '_' <> ppr_z_occ_name occ
424 -- In code style, always qualify
425 -- ToDo: maybe we could print all wired-in things unqualified
426 -- in code style, to reduce symbol table bloat?
427 | debugStyle sty = ppr mod <> dot <> ppr_occ_name occ
428 <> braces (hsep [if is_wired then ptext (sLit "(w)") else empty,
429 pprNameSpaceBrief (occNameSpace occ),
431 | BuiltInSyntax <- is_builtin = ppr_occ_name occ -- Never qualify builtin syntax
432 | otherwise = pprModulePrefix sty mod occ <> ppr_occ_name occ
434 pprInternal :: PprStyle -> Unique -> OccName -> SDoc
435 pprInternal sty uniq occ
436 | codeStyle sty = pprUnique uniq
437 | debugStyle sty = ppr_occ_name occ <> braces (hsep [pprNameSpaceBrief (occNameSpace occ),
439 | dumpStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
440 -- For debug dumps, we're not necessarily dumping
441 -- tidied code, so we need to print the uniques.
442 | otherwise = ppr_occ_name occ -- User style
444 -- Like Internal, except that we only omit the unique in Iface style
445 pprSystem :: PprStyle -> Unique -> OccName -> SDoc
446 pprSystem sty uniq occ
447 | codeStyle sty = pprUnique uniq
448 | debugStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
449 <> braces (pprNameSpaceBrief (occNameSpace occ))
450 | otherwise = ppr_occ_name occ <> ppr_underscore_unique uniq
451 -- If the tidy phase hasn't run, the OccName
452 -- is unlikely to be informative (like 's'),
453 -- so print the unique
456 pprModulePrefix :: PprStyle -> Module -> OccName -> SDoc
457 -- Print the "M." part of a name, based on whether it's in scope or not
458 -- See Note [Printing original names] in HscTypes
459 pprModulePrefix sty mod occ
460 | opt_SuppressModulePrefixes = empty
463 = case qualName sty mod occ of -- See Outputable.QualifyName:
464 NameQual modname -> ppr modname <> dot -- Name is in scope
465 NameNotInScope1 -> ppr mod <> dot -- Not in scope
466 NameNotInScope2 -> ppr (modulePackageId mod) <> colon -- Module not in
467 <> ppr (moduleName mod) <> dot -- scope eithber
470 ppr_underscore_unique :: Unique -> SDoc
471 -- Print an underscore separating the name from its unique
472 -- But suppress it if we aren't printing the uniques anyway
473 ppr_underscore_unique uniq
474 | opt_SuppressUniques = empty
475 | otherwise = char '_' <> pprUnique uniq
477 ppr_occ_name :: OccName -> SDoc
478 ppr_occ_name occ = ftext (occNameFS occ)
479 -- Don't use pprOccName; instead, just print the string of the OccName;
480 -- we print the namespace in the debug stuff above
482 -- In code style, we Z-encode the strings. The results of Z-encoding each FastString are
483 -- cached behind the scenes in the FastString implementation.
484 ppr_z_occ_name :: OccName -> SDoc
485 ppr_z_occ_name occ = ftext (zEncodeFS (occNameFS occ))
487 -- Prints (if mod information is available) "Defined at <loc>" or
488 -- "Defined in <mod>" information for a Name.
489 pprNameLoc :: Name -> SDoc
490 pprNameLoc name = case nameSrcSpan name of
494 | isInternalName name || isSystemName name ->
495 ptext (sLit "<no location info>")
497 ptext (sLit "Defined in ") <> ppr (nameModule name)
500 %************************************************************************
502 \subsection{Overloaded functions related to Names}
504 %************************************************************************
507 -- | A class allowing convenient access to the 'Name' of various datatypes
508 class NamedThing a where
509 getOccName :: a -> OccName
512 getOccName n = nameOccName (getName n) -- Default method
516 getSrcLoc :: NamedThing a => a -> SrcLoc
517 getSrcSpan :: NamedThing a => a -> SrcSpan
518 getOccString :: NamedThing a => a -> String
520 getSrcLoc = nameSrcLoc . getName
521 getSrcSpan = nameSrcSpan . getName
522 getOccString = occNameString . getOccName
524 pprInfixName, pprPrefixName :: (Outputable a, NamedThing a) => a -> SDoc
525 -- See Outputable.pprPrefixVar, pprInfixVar;
526 -- add parens or back-quotes as appropriate
527 pprInfixName n = pprInfixVar (isSymOcc (getOccName n)) (ppr n)
528 pprPrefixName n = pprPrefixVar (isSymOcc (getOccName n)) (ppr n)