c82a06c2f38bec95cea6eee37e3f1cec93e0af73
[ghc.git] / compiler / basicTypes / Name.lhs
1 %
2 % (c) The University of Glasgow 2006
3 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
4 %
5 \section[Name]{@Name@: to transmit name info from renamer to typechecker}
6
7 \begin{code}
8 -- |
9 -- #name_types#
10 -- GHC uses several kinds of name internally:
11 --
12 -- * 'OccName.OccName': see "OccName#name_types"
13 --
14 -- * 'RdrName.RdrName': see "RdrName#name_types"
15 --
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"
20 --
21 -- * 'Id.Id': see "Id#name_types"
22 --
23 -- * 'Var.Var': see "Var#name_types"
24 --
25 -- #name_sorts#
26 -- Names are one of:
27 --
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
30 --
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
33
34 module Name (
35         -- * The main types
36         Name,                                   -- Abstract
37         BuiltInSyntax(..),
38
39         -- ** Creating 'Name's
40         mkInternalName, mkSystemName, mkDerivedInternalName, 
41         mkSystemVarName, mkSysTvName, 
42         mkFCallName, mkIPName,
43         mkTickBoxOpName,
44         mkExternalName, mkWiredInName,
45
46         -- ** Manipulating and deconstructing 'Name's
47         nameUnique, setNameUnique,
48         nameOccName, nameModule, nameModule_maybe,
49         tidyNameOcc, 
50         hashName, localiseName,
51   mkLocalisedOccName,
52
53         nameSrcLoc, nameSrcSpan, pprNameLoc,
54
55         -- ** Predicates on 'Name's
56         isSystemName, isInternalName, isExternalName,
57         isTyVarName, isTyConName, isDataConName, 
58         isValName, isVarName,
59         isWiredInName, isBuiltInSyntax,
60         wiredInNameTyThing_maybe, 
61         nameIsLocalOrFrom, stableNameCmp,
62
63         -- * Class 'NamedThing' and overloaded friends
64         NamedThing(..),
65         getSrcLoc, getSrcSpan, getOccString,
66
67         pprInfixName, pprPrefixName, pprModulePrefix,
68
69         -- Re-export the OccName stuff
70         module OccName
71     ) where
72
73 #include "Typeable.h"
74
75 import {-# SOURCE #-} TypeRep( TyThing )
76
77 import OccName
78 import Module
79 import SrcLoc
80 import Unique
81 import Util
82 import Maybes
83 import Binary
84 import StaticFlags
85 import FastTypes
86 import FastString
87 import Outputable
88
89 import Data.Array
90 import Data.Data
91 import Data.Word        ( Word32 )
92 \end{code}
93
94 %************************************************************************
95 %*                                                                      *
96 \subsection[Name-datatype]{The @Name@ datatype, and name construction}
97 %*                                                                      *
98 %************************************************************************
99  
100 \begin{code}
101 -- | A unique, unambigious name for something, containing information about where
102 -- that thing originated.
103 data Name = Name {
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
109             }
110     deriving Typeable
111
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.
115
116 data NameSort
117   = External Module
118  
119   | WiredIn Module TyThing BuiltInSyntax
120         -- A variant of External, for wired-in things
121
122   | Internal            -- A user-defined Id or TyVar
123                         -- defined in the module being compiled
124
125   | System              -- A system-defined Id or TyVar.  Typically the
126                         -- OccName is very uninformative (like 's')
127
128 -- | BuiltInSyntax is for things like @(:)@, @[]@ and tuples, 
129 -- which have special syntactic forms.  They aren't in scope
130 -- as such.
131 data BuiltInSyntax = BuiltInSyntax | UserSyntax
132 \end{code}
133
134 Notes about the NameSorts:
135
136 1.  Initially, top-level Ids (including locally-defined ones) get External names, 
137     and all other local Ids get Internal names
138
139 2.  Things with a External name are given C static labels, so they finally
140     appear in the .o file's symbol table.  They appear in the symbol table
141     in the form M.n.  If originally-local things have this property they
142     must be made @External@ first.
143
144 3.  In the tidy-core phase, a External that is not visible to an importer
145     is changed to Internal, and a Internal that is visible is changed to External
146
147 4.  A System Name differs in the following ways:
148         a) has unique attached when printing dumps
149         b) unifier eliminates sys tyvars in favour of user provs where possible
150
151     Before anything gets printed in interface files or output code, it's
152     fed through a 'tidy' processor, which zaps the OccNames to have
153     unique names; and converts all sys-locals to user locals
154     If any desugarer sys-locals have survived that far, they get changed to
155     "ds1", "ds2", etc.
156
157 Built-in syntax => It's a syntactic form, not "in scope" (e.g. [])
158
159 Wired-in thing  => The thing (Id, TyCon) is fully known to the compiler, 
160                    not read from an interface file. 
161                    E.g. Bool, True, Int, Float, and many others
162
163 All built-in syntax is for wired-in things.
164
165 \begin{code}
166 nameUnique              :: Name -> Unique
167 nameOccName             :: Name -> OccName 
168 nameModule              :: Name -> Module
169 nameSrcLoc              :: Name -> SrcLoc
170 nameSrcSpan             :: Name -> SrcSpan
171
172 nameUnique  name = mkUniqueGrimily (iBox (n_uniq name))
173 nameOccName name = n_occ  name
174 nameSrcLoc  name = srcSpanStart (n_loc name)
175 nameSrcSpan name = n_loc  name
176 \end{code}
177
178 %************************************************************************
179 %*                                                                      *
180 \subsection{Predicates on names}
181 %*                                                                      *
182 %************************************************************************
183
184 \begin{code}
185 nameIsLocalOrFrom :: Module -> Name -> Bool
186 isInternalName    :: Name -> Bool
187 isExternalName    :: Name -> Bool
188 isSystemName      :: Name -> Bool
189 isWiredInName     :: Name -> Bool
190
191 isWiredInName (Name {n_sort = WiredIn _ _ _}) = True
192 isWiredInName _                               = False
193
194 wiredInNameTyThing_maybe :: Name -> Maybe TyThing
195 wiredInNameTyThing_maybe (Name {n_sort = WiredIn _ thing _}) = Just thing
196 wiredInNameTyThing_maybe _                                   = Nothing
197
198 isBuiltInSyntax :: Name -> Bool
199 isBuiltInSyntax (Name {n_sort = WiredIn _ _ BuiltInSyntax}) = True
200 isBuiltInSyntax _                                           = False
201
202 isExternalName (Name {n_sort = External _})    = True
203 isExternalName (Name {n_sort = WiredIn _ _ _}) = True
204 isExternalName _                               = False
205
206 isInternalName name = not (isExternalName name)
207
208 nameModule name = nameModule_maybe name `orElse` pprPanic "nameModule" (ppr name)
209 nameModule_maybe :: Name -> Maybe Module
210 nameModule_maybe (Name { n_sort = External mod})    = Just mod
211 nameModule_maybe (Name { n_sort = WiredIn mod _ _}) = Just mod
212 nameModule_maybe _                                  = Nothing
213
214 nameIsLocalOrFrom from name
215   | isExternalName name = from == nameModule name
216   | otherwise           = True
217
218 isTyVarName :: Name -> Bool
219 isTyVarName name = isTvOcc (nameOccName name)
220
221 isTyConName :: Name -> Bool
222 isTyConName name = isTcOcc (nameOccName name)
223
224 isDataConName :: Name -> Bool
225 isDataConName name = isDataOcc (nameOccName name)
226
227 isValName :: Name -> Bool
228 isValName name = isValOcc (nameOccName name)
229
230 isVarName :: Name -> Bool
231 isVarName = isVarOcc . nameOccName
232
233 isSystemName (Name {n_sort = System}) = True
234 isSystemName _                        = False
235 \end{code}
236
237
238 %************************************************************************
239 %*                                                                      *
240 \subsection{Making names}
241 %*                                                                      *
242 %************************************************************************
243
244 \begin{code}
245 -- | Create a name which is (for now at least) local to the current module and hence
246 -- does not need a 'Module' to disambiguate it from other 'Name's
247 mkInternalName :: Unique -> OccName -> SrcSpan -> Name
248 mkInternalName uniq occ loc = Name { n_uniq = getKeyFastInt uniq
249                                    , n_sort = Internal
250                                    , n_occ = occ
251                                    , n_loc = loc }
252         -- NB: You might worry that after lots of huffing and
253         -- puffing we might end up with two local names with distinct
254         -- uniques, but the same OccName.  Indeed we can, but that's ok
255         --      * the insides of the compiler don't care: they use the Unique
256         --      * when printing for -ddump-xxx you can switch on -dppr-debug to get the
257         --        uniques if you get confused
258         --      * for interface files we tidyCore first, which puts the uniques
259         --        into the print name (see setNameVisibility below)
260
261 mkDerivedInternalName :: (OccName -> OccName) -> Unique -> Name -> Name
262 mkDerivedInternalName derive_occ uniq (Name { n_occ = occ, n_loc = loc })
263   = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal
264          , n_occ = derive_occ occ, n_loc = loc }
265
266 -- | Create a name which definitely originates in the given module
267 mkExternalName :: Unique -> Module -> OccName -> SrcSpan -> Name
268 mkExternalName uniq mod occ loc 
269   = Name { n_uniq = getKeyFastInt uniq, n_sort = External mod,
270            n_occ = occ, n_loc = loc }
271
272 -- | Create a name which is actually defined by the compiler itself
273 mkWiredInName :: Module -> OccName -> Unique -> TyThing -> BuiltInSyntax -> Name
274 mkWiredInName mod occ uniq thing built_in
275   = Name { n_uniq = getKeyFastInt uniq,
276            n_sort = WiredIn mod thing built_in,
277            n_occ = occ, n_loc = wiredInSrcSpan }
278
279 -- | Create a name brought into being by the compiler
280 mkSystemName :: Unique -> OccName -> Name
281 mkSystemName uniq occ = Name { n_uniq = getKeyFastInt uniq, n_sort = System, 
282                                n_occ = occ, n_loc = noSrcSpan }
283
284 mkSystemVarName :: Unique -> FastString -> Name
285 mkSystemVarName uniq fs = mkSystemName uniq (mkVarOccFS fs)
286
287 mkSysTvName :: Unique -> FastString -> Name
288 mkSysTvName uniq fs = mkSystemName uniq (mkOccNameFS tvName fs)
289
290 -- | Make a name for a foreign call
291 mkFCallName :: Unique -> String -> Name
292         -- The encoded string completely describes the ccall
293 mkFCallName uniq str =  Name { n_uniq = getKeyFastInt uniq, n_sort = Internal, 
294                                n_occ = mkVarOcc str, n_loc = noSrcSpan }
295
296
297 mkTickBoxOpName :: Unique -> String -> Name
298 mkTickBoxOpName uniq str 
299    = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal, 
300             n_occ = mkVarOcc str, n_loc = noSrcSpan }
301
302 -- | Make the name of an implicit parameter
303 mkIPName :: Unique -> OccName -> Name
304 mkIPName uniq occ
305   = Name { n_uniq = getKeyFastInt uniq,
306            n_sort = Internal,
307            n_occ  = occ,
308            n_loc = noSrcSpan }
309 \end{code}
310
311 \begin{code}
312 -- When we renumber/rename things, we need to be
313 -- able to change a Name's Unique to match the cached
314 -- one in the thing it's the name of.  If you know what I mean.
315 setNameUnique :: Name -> Unique -> Name
316 setNameUnique name uniq = name {n_uniq = getKeyFastInt uniq}
317
318 tidyNameOcc :: Name -> OccName -> Name
319 -- We set the OccName of a Name when tidying
320 -- In doing so, we change System --> Internal, so that when we print
321 -- it we don't get the unique by default.  It's tidy now!
322 tidyNameOcc name@(Name { n_sort = System }) occ = name { n_occ = occ, n_sort = Internal}
323 tidyNameOcc name                            occ = name { n_occ = occ }
324
325 -- | Make the 'Name' into an internal name, regardless of what it was to begin with
326 localiseName :: Name -> Name
327 localiseName n = n { n_sort = Internal }
328 \end{code}
329
330 \begin{code}
331 -- |Create a localised variant of a name.  
332 --
333 -- If the name is external, encode the original's module name to disambiguate.
334 --
335 mkLocalisedOccName :: Module -> (Maybe String -> OccName -> OccName) -> Name -> OccName
336 mkLocalisedOccName this_mod mk_occ name = mk_occ origin (nameOccName name)
337   where
338     origin 
339       | nameIsLocalOrFrom this_mod name = Nothing
340       | otherwise                       = Just (moduleNameColons . moduleName . nameModule $ name)
341 \end{code}
342
343 %************************************************************************
344 %*                                                                      *
345 \subsection{Hashing and comparison}
346 %*                                                                      *
347 %************************************************************************
348
349 \begin{code}
350 hashName :: Name -> Int         -- ToDo: should really be Word
351 hashName name = getKey (nameUnique name) + 1
352         -- The +1 avoids keys with lots of zeros in the ls bits, which 
353         -- interacts badly with the cheap and cheerful multiplication in
354         -- hashExpr
355
356 cmpName :: Name -> Name -> Ordering
357 cmpName n1 n2 = iBox (n_uniq n1) `compare` iBox (n_uniq n2)
358
359 stableNameCmp :: Name -> Name -> Ordering
360 -- Compare lexicographically
361 stableNameCmp (Name { n_sort = s1, n_occ = occ1 })
362               (Name { n_sort = s2, n_occ = occ2 })
363   = (s1 `sort_cmp` s2) `thenCmp` (occ1 `compare` occ2)
364     -- The ordinary compare on OccNames is lexicogrpahic
365   where
366     -- Later constructors are bigger
367     sort_cmp (External m1) (External m2)       = m1 `stableModuleCmp` m2
368     sort_cmp (External {}) _                   = LT
369     sort_cmp (WiredIn {}) (External {})        = GT
370     sort_cmp (WiredIn m1 _ _) (WiredIn m2 _ _) = m1 `stableModuleCmp` m2
371     sort_cmp (WiredIn {})     _                = LT
372     sort_cmp Internal         (External {})    = GT
373     sort_cmp Internal         (WiredIn {})     = GT
374     sort_cmp Internal         Internal         = EQ
375     sort_cmp Internal         System           = LT
376     sort_cmp System           System           = EQ
377     sort_cmp System           _                = GT
378 \end{code}
379
380 %************************************************************************
381 %*                                                                      *
382 \subsection[Name-instances]{Instance declarations}
383 %*                                                                      *
384 %************************************************************************
385
386 \begin{code}
387 instance Eq Name where
388     a == b = case (a `compare` b) of { EQ -> True;  _ -> False }
389     a /= b = case (a `compare` b) of { EQ -> False; _ -> True }
390
391 instance Ord Name where
392     a <= b = case (a `compare` b) of { LT -> True;  EQ -> True;  GT -> False }
393     a <  b = case (a `compare` b) of { LT -> True;  EQ -> False; GT -> False }
394     a >= b = case (a `compare` b) of { LT -> False; EQ -> True;  GT -> True  }
395     a >  b = case (a `compare` b) of { LT -> False; EQ -> False; GT -> True  }
396     compare a b = cmpName a b
397
398 instance Uniquable Name where
399     getUnique = nameUnique
400
401 instance NamedThing Name where
402     getName n = n
403
404 instance Data Name where
405   -- don't traverse?
406   toConstr _   = abstractConstr "Name"
407   gunfold _ _  = error "gunfold"
408   dataTypeOf _ = mkNoRepType "Name"
409 \end{code}
410
411 %************************************************************************
412 %*                                                                      *
413 \subsection{Binary}
414 %*                                                                      *
415 %************************************************************************
416
417 \begin{code}
418 instance Binary Name where
419    put_ bh name =
420       case getUserData bh of 
421         UserData{ ud_put_name = put_name } -> put_name bh name
422
423    get bh = do
424         i <- get bh
425         return $! (ud_symtab (getUserData bh) ! fromIntegral (i::Word32))
426 \end{code}
427
428 %************************************************************************
429 %*                                                                      *
430 \subsection{Pretty printing}
431 %*                                                                      *
432 %************************************************************************
433
434 \begin{code}
435 instance Outputable Name where
436     ppr name = pprName name
437
438 instance OutputableBndr Name where
439     pprBndr _ name = pprName name
440
441 pprName :: Name -> SDoc
442 pprName (Name {n_sort = sort, n_uniq = u, n_occ = occ})
443   = getPprStyle $ \ sty ->
444     case sort of
445       WiredIn mod _ builtin   -> pprExternal sty uniq mod occ True  builtin
446       External mod            -> pprExternal sty uniq mod occ False UserSyntax
447       System                  -> pprSystem sty uniq occ
448       Internal                -> pprInternal sty uniq occ
449   where uniq = mkUniqueGrimily (iBox u)
450
451 pprExternal :: PprStyle -> Unique -> Module -> OccName -> Bool -> BuiltInSyntax -> SDoc
452 pprExternal sty uniq mod occ is_wired is_builtin
453   | codeStyle sty = ppr mod <> char '_' <> ppr_z_occ_name occ
454         -- In code style, always qualify
455         -- ToDo: maybe we could print all wired-in things unqualified
456         --       in code style, to reduce symbol table bloat?
457   | debugStyle sty = pp_mod <> ppr_occ_name occ
458                      <> braces (hsep [if is_wired then ptext (sLit "(w)") else empty,
459                                       pprNameSpaceBrief (occNameSpace occ), 
460                                       pprUnique uniq])
461   | BuiltInSyntax <- is_builtin = ppr_occ_name occ  -- Never qualify builtin syntax
462   | otherwise                   = pprModulePrefix sty mod occ <> ppr_occ_name occ
463   where
464     pp_mod | opt_SuppressModulePrefixes = empty
465            | otherwise                  = ppr mod <> dot 
466
467 pprInternal :: PprStyle -> Unique -> OccName -> SDoc
468 pprInternal sty uniq occ
469   | codeStyle sty  = pprUnique uniq
470   | debugStyle sty = ppr_occ_name occ <> braces (hsep [pprNameSpaceBrief (occNameSpace occ), 
471                                                        pprUnique uniq])
472   | dumpStyle sty  = ppr_occ_name occ <> ppr_underscore_unique uniq
473                         -- For debug dumps, we're not necessarily dumping
474                         -- tidied code, so we need to print the uniques.
475   | otherwise      = ppr_occ_name occ   -- User style
476
477 -- Like Internal, except that we only omit the unique in Iface style
478 pprSystem :: PprStyle -> Unique -> OccName -> SDoc
479 pprSystem sty uniq occ
480   | codeStyle sty  = pprUnique uniq
481   | debugStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
482                      <> braces (pprNameSpaceBrief (occNameSpace occ))
483   | otherwise      = ppr_occ_name occ <> ppr_underscore_unique uniq
484                                 -- If the tidy phase hasn't run, the OccName
485                                 -- is unlikely to be informative (like 's'),
486                                 -- so print the unique
487
488
489 pprModulePrefix :: PprStyle -> Module -> OccName -> SDoc
490 -- Print the "M." part of a name, based on whether it's in scope or not
491 -- See Note [Printing original names] in HscTypes
492 pprModulePrefix sty mod occ
493   | opt_SuppressModulePrefixes = empty
494   
495   | otherwise
496   = case qualName sty mod occ of                   -- See Outputable.QualifyName:
497       NameQual modname -> ppr modname <> dot       -- Name is in scope       
498       NameNotInScope1  -> ppr mod <> dot           -- Not in scope
499       NameNotInScope2  -> ppr (modulePackageId mod) <> colon     -- Module not in
500                           <> ppr (moduleName mod) <> dot         -- scope eithber
501       _otherwise       -> empty
502
503 ppr_underscore_unique :: Unique -> SDoc
504 -- Print an underscore separating the name from its unique
505 -- But suppress it if we aren't printing the uniques anyway
506 ppr_underscore_unique uniq
507   | opt_SuppressUniques = empty
508   | otherwise           = char '_' <> pprUnique uniq
509
510 ppr_occ_name :: OccName -> SDoc
511 ppr_occ_name occ = ftext (occNameFS occ)
512         -- Don't use pprOccName; instead, just print the string of the OccName; 
513         -- we print the namespace in the debug stuff above
514
515 -- In code style, we Z-encode the strings.  The results of Z-encoding each FastString are
516 -- cached behind the scenes in the FastString implementation.
517 ppr_z_occ_name :: OccName -> SDoc
518 ppr_z_occ_name occ = ftext (zEncodeFS (occNameFS occ))
519
520 -- Prints (if mod information is available) "Defined at <loc>" or 
521 --  "Defined in <mod>" information for a Name.
522 pprNameLoc :: Name -> SDoc
523 pprNameLoc name = case nameSrcSpan name of
524                   RealSrcSpan s ->
525                       pprDefnLoc s
526                   UnhelpfulSpan _
527                    | isInternalName name || isSystemName name ->
528                       ptext (sLit "<no location info>")
529                    | otherwise ->
530                       ptext (sLit "Defined in ") <> ppr (nameModule name)
531 \end{code}
532
533 %************************************************************************
534 %*                                                                      *
535 \subsection{Overloaded functions related to Names}
536 %*                                                                      *
537 %************************************************************************
538
539 \begin{code}
540 -- | A class allowing convenient access to the 'Name' of various datatypes
541 class NamedThing a where
542     getOccName :: a -> OccName
543     getName    :: a -> Name
544
545     getOccName n = nameOccName (getName n)      -- Default method
546 \end{code}
547
548 \begin{code}
549 getSrcLoc           :: NamedThing a => a -> SrcLoc
550 getSrcSpan          :: NamedThing a => a -> SrcSpan
551 getOccString        :: NamedThing a => a -> String
552
553 getSrcLoc           = nameSrcLoc           . getName
554 getSrcSpan          = nameSrcSpan          . getName
555 getOccString        = occNameString        . getOccName
556
557 pprInfixName, pprPrefixName :: (Outputable a, NamedThing a) => a -> SDoc
558 -- See Outputable.pprPrefixVar, pprInfixVar; 
559 -- add parens or back-quotes as appropriate
560 pprInfixName  n = pprInfixVar  (isSymOcc (getOccName n)) (ppr n)
561 pprPrefixName n = pprPrefixVar (isSymOcc (getOccName n)) (ppr n)
562 \end{code}
563