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,
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
72 import {-# SOURCE #-} TypeRep( TyThing )
86 import Data.Word ( Word32 )
89 %************************************************************************
91 \subsection[Name-datatype]{The @Name@ datatype, and name construction}
93 %************************************************************************
96 -- | A unique, unambigious name for something, containing information about where
97 -- that thing originated.
99 n_sort :: NameSort, -- What sort of name it is
100 n_occ :: !OccName, -- Its occurrence name
101 n_uniq :: FastInt, -- UNPACK doesn't work, recursive type
102 --(note later when changing Int# -> FastInt: is that still true about UNPACK?)
103 n_loc :: !SrcSpan -- Definition site
106 -- NOTE: we make the n_loc field strict to eliminate some potential
107 -- (and real!) space leaks, due to the fact that we don't look at
108 -- the SrcLoc in a Name all that often.
113 | WiredIn Module TyThing BuiltInSyntax
114 -- A variant of External, for wired-in things
116 | Internal -- A user-defined Id or TyVar
117 -- defined in the module being compiled
119 | System -- A system-defined Id or TyVar. Typically the
120 -- OccName is very uninformative (like 's')
122 -- | BuiltInSyntax is for things like @(:)@, @[]@ and tuples,
123 -- which have special syntactic forms. They aren't in scope
125 data BuiltInSyntax = BuiltInSyntax | UserSyntax
128 Notes about the NameSorts:
130 1. Initially, top-level Ids (including locally-defined ones) get External names,
131 and all other local Ids get Internal names
133 2. Things with a External name are given C static labels, so they finally
134 appear in the .o file's symbol table. They appear in the symbol table
135 in the form M.n. If originally-local things have this property they
136 must be made @External@ first.
138 3. In the tidy-core phase, a External that is not visible to an importer
139 is changed to Internal, and a Internal that is visible is changed to External
141 4. A System Name differs in the following ways:
142 a) has unique attached when printing dumps
143 b) unifier eliminates sys tyvars in favour of user provs where possible
145 Before anything gets printed in interface files or output code, it's
146 fed through a 'tidy' processor, which zaps the OccNames to have
147 unique names; and converts all sys-locals to user locals
148 If any desugarer sys-locals have survived that far, they get changed to
151 Built-in syntax => It's a syntactic form, not "in scope" (e.g. [])
153 Wired-in thing => The thing (Id, TyCon) is fully known to the compiler,
154 not read from an interface file.
155 E.g. Bool, True, Int, Float, and many others
157 All built-in syntax is for wired-in things.
160 nameUnique :: Name -> Unique
161 nameOccName :: Name -> OccName
162 nameModule :: Name -> Module
163 nameSrcLoc :: Name -> SrcLoc
164 nameSrcSpan :: Name -> SrcSpan
166 nameUnique name = mkUniqueGrimily (iBox (n_uniq name))
167 nameOccName name = n_occ name
168 nameSrcLoc name = srcSpanStart (n_loc name)
169 nameSrcSpan name = n_loc name
172 %************************************************************************
174 \subsection{Predicates on names}
176 %************************************************************************
179 nameIsLocalOrFrom :: Module -> Name -> Bool
180 isInternalName :: Name -> Bool
181 isExternalName :: Name -> Bool
182 isSystemName :: Name -> Bool
183 isWiredInName :: Name -> Bool
185 isWiredInName (Name {n_sort = WiredIn _ _ _}) = True
186 isWiredInName _ = False
188 wiredInNameTyThing_maybe :: Name -> Maybe TyThing
189 wiredInNameTyThing_maybe (Name {n_sort = WiredIn _ thing _}) = Just thing
190 wiredInNameTyThing_maybe _ = Nothing
192 isBuiltInSyntax :: Name -> Bool
193 isBuiltInSyntax (Name {n_sort = WiredIn _ _ BuiltInSyntax}) = True
194 isBuiltInSyntax _ = False
196 isExternalName (Name {n_sort = External _}) = True
197 isExternalName (Name {n_sort = WiredIn _ _ _}) = True
198 isExternalName _ = False
200 isInternalName name = not (isExternalName name)
202 nameModule name = nameModule_maybe name `orElse` pprPanic "nameModule" (ppr name)
203 nameModule_maybe :: Name -> Maybe Module
204 nameModule_maybe (Name { n_sort = External mod}) = Just mod
205 nameModule_maybe (Name { n_sort = WiredIn mod _ _}) = Just mod
206 nameModule_maybe _ = Nothing
208 nameIsLocalOrFrom from name
209 | isExternalName name = from == nameModule name
212 isTyVarName :: Name -> Bool
213 isTyVarName name = isTvOcc (nameOccName name)
215 isTyConName :: Name -> Bool
216 isTyConName name = isTcOcc (nameOccName name)
218 isDataConName :: Name -> Bool
219 isDataConName name = isDataOcc (nameOccName name)
221 isValName :: Name -> Bool
222 isValName name = isValOcc (nameOccName name)
224 isVarName :: Name -> Bool
225 isVarName = isVarOcc . nameOccName
227 isSystemName (Name {n_sort = System}) = True
228 isSystemName _ = False
232 %************************************************************************
234 \subsection{Making names}
236 %************************************************************************
239 -- | Create a name which is (for now at least) local to the current module and hence
240 -- does not need a 'Module' to disambiguate it from other 'Name's
241 mkInternalName :: Unique -> OccName -> SrcSpan -> Name
242 mkInternalName uniq occ loc = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal, n_occ = occ, n_loc = loc }
243 -- NB: You might worry that after lots of huffing and
244 -- puffing we might end up with two local names with distinct
245 -- uniques, but the same OccName. Indeed we can, but that's ok
246 -- * the insides of the compiler don't care: they use the Unique
247 -- * when printing for -ddump-xxx you can switch on -dppr-debug to get the
248 -- uniques if you get confused
249 -- * for interface files we tidyCore first, which puts the uniques
250 -- into the print name (see setNameVisibility below)
252 -- | Create a name which definitely originates in the given module
253 mkExternalName :: Unique -> Module -> OccName -> SrcSpan -> Name
254 mkExternalName uniq mod occ loc
255 = Name { n_uniq = getKeyFastInt uniq, n_sort = External mod,
256 n_occ = occ, n_loc = loc }
258 -- | Create a name which is actually defined by the compiler itself
259 mkWiredInName :: Module -> OccName -> Unique -> TyThing -> BuiltInSyntax -> Name
260 mkWiredInName mod occ uniq thing built_in
261 = Name { n_uniq = getKeyFastInt uniq,
262 n_sort = WiredIn mod thing built_in,
263 n_occ = occ, n_loc = wiredInSrcSpan }
265 -- | Create a name brought into being by the compiler
266 mkSystemName :: Unique -> OccName -> Name
267 mkSystemName uniq occ = Name { n_uniq = getKeyFastInt uniq, n_sort = System,
268 n_occ = occ, n_loc = noSrcSpan }
270 mkSystemVarName :: Unique -> FastString -> Name
271 mkSystemVarName uniq fs = mkSystemName uniq (mkVarOccFS fs)
273 mkSysTvName :: Unique -> FastString -> Name
274 mkSysTvName uniq fs = mkSystemName uniq (mkOccNameFS tvName fs)
276 -- | Make a name for a foreign call
277 mkFCallName :: Unique -> String -> Name
278 -- The encoded string completely describes the ccall
279 mkFCallName uniq str = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal,
280 n_occ = mkVarOcc str, n_loc = noSrcSpan }
283 mkTickBoxOpName :: Unique -> String -> Name
284 mkTickBoxOpName uniq str
285 = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal,
286 n_occ = mkVarOcc str, n_loc = noSrcSpan }
288 -- | Make the name of an implicit parameter
289 mkIPName :: Unique -> OccName -> Name
291 = Name { n_uniq = getKeyFastInt uniq,
298 -- When we renumber/rename things, we need to be
299 -- able to change a Name's Unique to match the cached
300 -- one in the thing it's the name of. If you know what I mean.
301 setNameUnique :: Name -> Unique -> Name
302 setNameUnique name uniq = name {n_uniq = getKeyFastInt uniq}
304 tidyNameOcc :: Name -> OccName -> Name
305 -- We set the OccName of a Name when tidying
306 -- In doing so, we change System --> Internal, so that when we print
307 -- it we don't get the unique by default. It's tidy now!
308 tidyNameOcc name@(Name { n_sort = System }) occ = name { n_occ = occ, n_sort = Internal}
309 tidyNameOcc name occ = name { n_occ = occ }
311 -- | Make the 'Name' into an internal name, regardless of what it was to begin with
312 localiseName :: Name -> Name
313 localiseName n = n { n_sort = Internal }
316 %************************************************************************
318 \subsection{Hashing and comparison}
320 %************************************************************************
323 hashName :: Name -> Int -- ToDo: should really be Word
324 hashName name = getKey (nameUnique name) + 1
325 -- The +1 avoids keys with lots of zeros in the ls bits, which
326 -- interacts badly with the cheap and cheerful multiplication in
329 cmpName :: Name -> Name -> Ordering
330 cmpName n1 n2 = iBox (n_uniq n1) `compare` iBox (n_uniq n2)
333 %************************************************************************
335 \subsection[Name-instances]{Instance declarations}
337 %************************************************************************
340 instance Eq Name where
341 a == b = case (a `compare` b) of { EQ -> True; _ -> False }
342 a /= b = case (a `compare` b) of { EQ -> False; _ -> True }
344 instance Ord Name where
345 a <= b = case (a `compare` b) of { LT -> True; EQ -> True; GT -> False }
346 a < b = case (a `compare` b) of { LT -> True; EQ -> False; GT -> False }
347 a >= b = case (a `compare` b) of { LT -> False; EQ -> True; GT -> True }
348 a > b = case (a `compare` b) of { LT -> False; EQ -> False; GT -> True }
349 compare a b = cmpName a b
351 instance Uniquable Name where
352 getUnique = nameUnique
354 instance NamedThing Name where
358 %************************************************************************
362 %************************************************************************
365 instance Binary Name where
367 case getUserData bh of
368 UserData{ ud_put_name = put_name } -> put_name bh name
372 return $! (ud_symtab (getUserData bh) ! fromIntegral (i::Word32))
375 %************************************************************************
377 \subsection{Pretty printing}
379 %************************************************************************
382 instance Outputable Name where
383 ppr name = pprName name
385 instance OutputableBndr Name where
386 pprBndr _ name = pprName name
388 pprName :: Name -> SDoc
389 pprName (Name {n_sort = sort, n_uniq = u, n_occ = occ})
390 = getPprStyle $ \ sty ->
392 WiredIn mod _ builtin -> pprExternal sty uniq mod occ True builtin
393 External mod -> pprExternal sty uniq mod occ False UserSyntax
394 System -> pprSystem sty uniq occ
395 Internal -> pprInternal sty uniq occ
396 where uniq = mkUniqueGrimily (iBox u)
398 pprExternal :: PprStyle -> Unique -> Module -> OccName -> Bool -> BuiltInSyntax -> SDoc
399 pprExternal sty uniq mod occ is_wired is_builtin
400 | codeStyle sty = ppr mod <> char '_' <> ppr_z_occ_name occ
401 -- In code style, always qualify
402 -- ToDo: maybe we could print all wired-in things unqualified
403 -- in code style, to reduce symbol table bloat?
404 | debugStyle sty = ppr mod <> dot <> ppr_occ_name occ
405 <> braces (hsep [if is_wired then ptext (sLit "(w)") else empty,
406 pprNameSpaceBrief (occNameSpace occ),
408 | BuiltInSyntax <- is_builtin = ppr_occ_name occ -- Never qualify builtin syntax
409 | otherwise = pprModulePrefix sty mod occ <> ppr_occ_name occ
411 pprInternal :: PprStyle -> Unique -> OccName -> SDoc
412 pprInternal sty uniq occ
413 | codeStyle sty = pprUnique uniq
414 | debugStyle sty = ppr_occ_name occ <> braces (hsep [pprNameSpaceBrief (occNameSpace occ),
416 | dumpStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
417 -- For debug dumps, we're not necessarily dumping
418 -- tidied code, so we need to print the uniques.
419 | otherwise = ppr_occ_name occ -- User style
421 -- Like Internal, except that we only omit the unique in Iface style
422 pprSystem :: PprStyle -> Unique -> OccName -> SDoc
423 pprSystem sty uniq occ
424 | codeStyle sty = pprUnique uniq
425 | debugStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
426 <> braces (pprNameSpaceBrief (occNameSpace occ))
427 | otherwise = ppr_occ_name occ <> ppr_underscore_unique uniq
428 -- If the tidy phase hasn't run, the OccName
429 -- is unlikely to be informative (like 's'),
430 -- so print the unique
433 pprModulePrefix :: PprStyle -> Module -> OccName -> SDoc
434 -- Print the "M." part of a name, based on whether it's in scope or not
435 -- See Note [Printing original names] in HscTypes
436 pprModulePrefix sty mod occ
437 = case qualName sty mod occ of -- See Outputable.QualifyName:
438 NameQual modname -> ppr modname <> dot -- Name is in scope
439 NameNotInScope1 -> ppr mod <> dot -- Not in scope
440 NameNotInScope2 -> ppr (modulePackageId mod) <> colon -- Module not in
441 <> ppr (moduleName mod) <> dot -- scope eithber
444 ppr_underscore_unique :: Unique -> SDoc
445 -- Print an underscore separating the name from its unique
446 -- But suppress it if we aren't printing the uniques anyway
447 ppr_underscore_unique uniq
448 | opt_SuppressUniques = empty
449 | otherwise = char '_' <> pprUnique uniq
451 ppr_occ_name :: OccName -> SDoc
452 ppr_occ_name occ = ftext (occNameFS occ)
453 -- Don't use pprOccName; instead, just print the string of the OccName;
454 -- we print the namespace in the debug stuff above
456 -- In code style, we Z-encode the strings. The results of Z-encoding each FastString are
457 -- cached behind the scenes in the FastString implementation.
458 ppr_z_occ_name :: OccName -> SDoc
459 ppr_z_occ_name occ = ftext (zEncodeFS (occNameFS occ))
461 -- Prints (if mod information is available) "Defined at <loc>" or
462 -- "Defined in <mod>" information for a Name.
463 pprNameLoc :: Name -> SDoc
465 | isGoodSrcSpan loc = pprDefnLoc loc
466 | isInternalName name || isSystemName name
467 = ptext (sLit "<no location info>")
468 | otherwise = ptext (sLit "Defined in ") <> ppr (nameModule name)
469 where loc = nameSrcSpan name
472 %************************************************************************
474 \subsection{Overloaded functions related to Names}
476 %************************************************************************
479 -- | A class allowing convenient access to the 'Name' of various datatypes
480 class NamedThing a where
481 getOccName :: a -> OccName
484 getOccName n = nameOccName (getName n) -- Default method
488 getSrcLoc :: NamedThing a => a -> SrcLoc
489 getSrcSpan :: NamedThing a => a -> SrcSpan
490 getOccString :: NamedThing a => a -> String
492 getSrcLoc = nameSrcLoc . getName
493 getSrcSpan = nameSrcSpan . getName
494 getOccString = occNameString . getOccName
496 pprInfixName, pprPrefixName :: (Outputable a, NamedThing a) => a -> SDoc
497 -- See Outputable.pprPrefixVar, pprInfixVar;
498 -- add parens or back-quotes as appropriate
499 pprInfixName n = pprInfixVar (isSymOcc (getOccName n)) (ppr n)
500 pprPrefixName n = pprPrefixVar (isSymOcc (getOccName n)) (ppr n)