e11262568e9dc04dbe3a0c9970db0d653072403a
[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         mkSystemName, mkSystemNameAt,
41         mkInternalName, mkClonedInternalName, mkDerivedInternalName,
42         mkSystemVarName, mkSysTvName,
43         mkFCallName,
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, pprNameDefnLoc, pprDefinedAt,
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 import {-# SOURCE #-} PrelNames( liftedTypeKindTyConKey )
77
78 import OccName
79 import Module
80 import SrcLoc
81 import Unique
82 import Util
83 import Maybes
84 import Binary
85 import DynFlags
86 import FastTypes
87 import FastString
88 import Outputable
89
90 import Data.Data
91 \end{code}
92
93 %************************************************************************
94 %*                                                                      *
95 \subsection[Name-datatype]{The @Name@ datatype, and name construction}
96 %*                                                                      *
97 %************************************************************************
98
99 \begin{code}
100 -- | A unique, unambigious name for something, containing information about where
101 -- that thing originated.
102 data Name = Name {
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
108             }
109     deriving Typeable
110
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.
114
115 data NameSort
116   = External Module
117
118   | WiredIn Module TyThing BuiltInSyntax
119         -- A variant of External, for wired-in things
120
121   | Internal            -- A user-defined Id or TyVar
122                         -- defined in the module being compiled
123
124   | System              -- A system-defined Id or TyVar.  Typically the
125                         -- OccName is very uninformative (like 's')
126
127 -- | BuiltInSyntax is for things like @(:)@, @[]@ and tuples,
128 -- which have special syntactic forms.  They aren't in scope
129 -- as such.
130 data BuiltInSyntax = BuiltInSyntax | UserSyntax
131 \end{code}
132
133 Notes about the NameSorts:
134
135 1.  Initially, top-level Ids (including locally-defined ones) get External names,
136     and all other local Ids get Internal names
137
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.
142
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
145
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
149
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
154     "ds1", "ds2", etc.
155
156 Built-in syntax => It's a syntactic form, not "in scope" (e.g. [])
157
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
161
162 All built-in syntax is for wired-in things.
163
164 \begin{code}
165 instance HasOccName Name where
166   occName = nameOccName
167
168 nameUnique              :: Name -> Unique
169 nameOccName             :: Name -> OccName
170 nameModule              :: Name -> Module
171 nameSrcLoc              :: Name -> SrcLoc
172 nameSrcSpan             :: Name -> SrcSpan
173
174 nameUnique  name = mkUniqueGrimily (iBox (n_uniq name))
175 nameOccName name = n_occ  name
176 nameSrcLoc  name = srcSpanStart (n_loc name)
177 nameSrcSpan name = n_loc  name
178 \end{code}
179
180 %************************************************************************
181 %*                                                                      *
182 \subsection{Predicates on names}
183 %*                                                                      *
184 %************************************************************************
185
186 \begin{code}
187 nameIsLocalOrFrom :: Module -> Name -> Bool
188 isInternalName    :: Name -> Bool
189 isExternalName    :: Name -> Bool
190 isSystemName      :: Name -> Bool
191 isWiredInName     :: Name -> Bool
192
193 isWiredInName (Name {n_sort = WiredIn _ _ _}) = True
194 isWiredInName _                               = False
195
196 wiredInNameTyThing_maybe :: Name -> Maybe TyThing
197 wiredInNameTyThing_maybe (Name {n_sort = WiredIn _ thing _}) = Just thing
198 wiredInNameTyThing_maybe _                                   = Nothing
199
200 isBuiltInSyntax :: Name -> Bool
201 isBuiltInSyntax (Name {n_sort = WiredIn _ _ BuiltInSyntax}) = True
202 isBuiltInSyntax _                                           = False
203
204 isExternalName (Name {n_sort = External _})    = True
205 isExternalName (Name {n_sort = WiredIn _ _ _}) = True
206 isExternalName _                               = False
207
208 isInternalName name = not (isExternalName name)
209
210 nameModule name = nameModule_maybe name `orElse` pprPanic "nameModule" (ppr name)
211 nameModule_maybe :: Name -> Maybe Module
212 nameModule_maybe (Name { n_sort = External mod})    = Just mod
213 nameModule_maybe (Name { n_sort = WiredIn mod _ _}) = Just mod
214 nameModule_maybe _                                  = Nothing
215
216 nameIsLocalOrFrom from name
217   | isExternalName name = from == nameModule name
218   | otherwise           = True
219
220 isTyVarName :: Name -> Bool
221 isTyVarName name = isTvOcc (nameOccName name)
222
223 isTyConName :: Name -> Bool
224 isTyConName name = isTcOcc (nameOccName name)
225
226 isDataConName :: Name -> Bool
227 isDataConName name = isDataOcc (nameOccName name)
228
229 isValName :: Name -> Bool
230 isValName name = isValOcc (nameOccName name)
231
232 isVarName :: Name -> Bool
233 isVarName = isVarOcc . nameOccName
234
235 isSystemName (Name {n_sort = System}) = True
236 isSystemName _                        = False
237 \end{code}
238
239
240 %************************************************************************
241 %*                                                                      *
242 \subsection{Making names}
243 %*                                                                      *
244 %************************************************************************
245
246 \begin{code}
247 -- | Create a name which is (for now at least) local to the current module and hence
248 -- does not need a 'Module' to disambiguate it from other 'Name's
249 mkInternalName :: Unique -> OccName -> SrcSpan -> Name
250 mkInternalName uniq occ loc = Name { n_uniq = getKeyFastInt uniq
251                                    , n_sort = Internal
252                                    , n_occ = occ
253                                    , 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 makes
261         --        the OccNames distinct when they need to be
262
263 mkClonedInternalName :: Unique -> Name -> Name
264 mkClonedInternalName uniq (Name { n_occ = occ, n_loc = loc })
265   = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal
266          , n_occ = occ, n_loc = loc }
267
268 mkDerivedInternalName :: (OccName -> OccName) -> Unique -> Name -> Name
269 mkDerivedInternalName derive_occ uniq (Name { n_occ = occ, n_loc = loc })
270   = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal
271          , n_occ = derive_occ occ, n_loc = loc }
272
273 -- | Create a name which definitely originates in the given module
274 mkExternalName :: Unique -> Module -> OccName -> SrcSpan -> Name
275 mkExternalName uniq mod occ loc
276   = Name { n_uniq = getKeyFastInt uniq, n_sort = External mod,
277            n_occ = occ, n_loc = loc }
278
279 -- | Create a name which is actually defined by the compiler itself
280 mkWiredInName :: Module -> OccName -> Unique -> TyThing -> BuiltInSyntax -> Name
281 mkWiredInName mod occ uniq thing built_in
282   = Name { n_uniq = getKeyFastInt uniq,
283            n_sort = WiredIn mod thing built_in,
284            n_occ = occ, n_loc = wiredInSrcSpan }
285
286 -- | Create a name brought into being by the compiler
287 mkSystemName :: Unique -> OccName -> Name
288 mkSystemName uniq occ = mkSystemNameAt uniq occ noSrcSpan
289
290 mkSystemNameAt :: Unique -> OccName -> SrcSpan -> Name
291 mkSystemNameAt uniq occ loc = Name { n_uniq = getKeyFastInt uniq, n_sort = System
292                                    , n_occ = occ, n_loc = loc }
293
294 mkSystemVarName :: Unique -> FastString -> Name
295 mkSystemVarName uniq fs = mkSystemName uniq (mkVarOccFS fs)
296
297 mkSysTvName :: Unique -> FastString -> Name
298 mkSysTvName uniq fs = mkSystemName uniq (mkOccNameFS tvName fs)
299
300 -- | Make a name for a foreign call
301 mkFCallName :: Unique -> String -> Name
302 mkFCallName uniq str = mkInternalName uniq (mkVarOcc str) noSrcSpan
303    -- The encoded string completely describes the ccall
304 \end{code}
305
306 \begin{code}
307 -- When we renumber/rename things, we need to be
308 -- able to change a Name's Unique to match the cached
309 -- one in the thing it's the name of.  If you know what I mean.
310 setNameUnique :: Name -> Unique -> Name
311 setNameUnique name uniq = name {n_uniq = getKeyFastInt uniq}
312
313 tidyNameOcc :: Name -> OccName -> Name
314 -- We set the OccName of a Name when tidying
315 -- In doing so, we change System --> Internal, so that when we print
316 -- it we don't get the unique by default.  It's tidy now!
317 tidyNameOcc name@(Name { n_sort = System }) occ = name { n_occ = occ, n_sort = Internal}
318 tidyNameOcc name                            occ = name { n_occ = occ }
319
320 -- | Make the 'Name' into an internal name, regardless of what it was to begin with
321 localiseName :: Name -> Name
322 localiseName n = n { n_sort = Internal }
323 \end{code}
324
325 \begin{code}
326 -- |Create a localised variant of a name.
327 --
328 -- If the name is external, encode the original's module name to disambiguate.
329 --
330 mkLocalisedOccName :: Module -> (Maybe String -> OccName -> OccName) -> Name -> OccName
331 mkLocalisedOccName this_mod mk_occ name = mk_occ origin (nameOccName name)
332   where
333     origin
334       | nameIsLocalOrFrom this_mod name = Nothing
335       | otherwise                       = Just (moduleNameColons . moduleName . nameModule $ name)
336 \end{code}
337
338 %************************************************************************
339 %*                                                                      *
340 \subsection{Hashing and comparison}
341 %*                                                                      *
342 %************************************************************************
343
344 \begin{code}
345 hashName :: Name -> Int         -- ToDo: should really be Word
346 hashName name = getKey (nameUnique name) + 1
347         -- The +1 avoids keys with lots of zeros in the ls bits, which
348         -- interacts badly with the cheap and cheerful multiplication in
349         -- hashExpr
350
351 cmpName :: Name -> Name -> Ordering
352 cmpName n1 n2 = iBox (n_uniq n1) `compare` iBox (n_uniq n2)
353
354 stableNameCmp :: Name -> Name -> Ordering
355 -- Compare lexicographically
356 stableNameCmp (Name { n_sort = s1, n_occ = occ1 })
357               (Name { n_sort = s2, n_occ = occ2 })
358   = (s1 `sort_cmp` s2) `thenCmp` (occ1 `compare` occ2)
359     -- The ordinary compare on OccNames is lexicogrpahic
360   where
361     -- Later constructors are bigger
362     sort_cmp (External m1) (External m2)       = m1 `stableModuleCmp` m2
363     sort_cmp (External {}) _                   = LT
364     sort_cmp (WiredIn {}) (External {})        = GT
365     sort_cmp (WiredIn m1 _ _) (WiredIn m2 _ _) = m1 `stableModuleCmp` m2
366     sort_cmp (WiredIn {})     _                = LT
367     sort_cmp Internal         (External {})    = GT
368     sort_cmp Internal         (WiredIn {})     = GT
369     sort_cmp Internal         Internal         = EQ
370     sort_cmp Internal         System           = LT
371     sort_cmp System           System           = EQ
372     sort_cmp System           _                = GT
373 \end{code}
374
375 %************************************************************************
376 %*                                                                      *
377 \subsection[Name-instances]{Instance declarations}
378 %*                                                                      *
379 %************************************************************************
380
381 \begin{code}
382 instance Eq Name where
383     a == b = case (a `compare` b) of { EQ -> True;  _ -> False }
384     a /= b = case (a `compare` b) of { EQ -> False; _ -> True }
385
386 instance Ord Name where
387     a <= b = case (a `compare` b) of { LT -> True;  EQ -> True;  GT -> False }
388     a <  b = case (a `compare` b) of { LT -> True;  EQ -> False; GT -> False }
389     a >= b = case (a `compare` b) of { LT -> False; EQ -> True;  GT -> True  }
390     a >  b = case (a `compare` b) of { LT -> False; EQ -> False; GT -> True  }
391     compare a b = cmpName a b
392
393 instance Uniquable Name where
394     getUnique = nameUnique
395
396 instance NamedThing Name where
397     getName n = n
398
399 instance Data Name where
400   -- don't traverse?
401   toConstr _   = abstractConstr "Name"
402   gunfold _ _  = error "gunfold"
403   dataTypeOf _ = mkNoRepType "Name"
404 \end{code}
405
406 %************************************************************************
407 %*                                                                      *
408 \subsection{Binary}
409 %*                                                                      *
410 %************************************************************************
411
412 \begin{code}
413 instance Binary Name where
414    put_ bh name =
415       case getUserData bh of
416         UserData{ ud_put_name = put_name } -> put_name bh name
417
418    get bh =
419       case getUserData bh of
420         UserData { ud_get_name = get_name } -> get_name bh
421 \end{code}
422
423 %************************************************************************
424 %*                                                                      *
425 \subsection{Pretty printing}
426 %*                                                                      *
427 %************************************************************************
428
429 \begin{code}
430 instance Outputable Name where
431     ppr name = pprName name
432
433 instance OutputableBndr Name where
434     pprBndr _ name = pprName name
435     pprInfixOcc  = pprInfixName
436     pprPrefixOcc = pprPrefixName
437
438
439 pprName :: Name -> SDoc
440 pprName n@(Name {n_sort = sort, n_uniq = u, n_occ = occ})
441   = getPprStyle $ \ sty ->
442     case sort of
443       WiredIn mod _ builtin   -> pprExternal sty uniq mod occ n True  builtin
444       External mod            -> pprExternal sty uniq mod occ n False UserSyntax
445       System                  -> pprSystem sty uniq occ
446       Internal                -> pprInternal sty uniq occ
447   where uniq = mkUniqueGrimily (iBox u)
448
449 pprExternal :: PprStyle -> Unique -> Module -> OccName -> Name -> Bool -> BuiltInSyntax -> SDoc
450 pprExternal sty uniq mod occ name is_wired is_builtin
451   | codeStyle sty = ppr mod <> char '_' <> ppr_z_occ_name occ
452         -- In code style, always qualify
453         -- ToDo: maybe we could print all wired-in things unqualified
454         --       in code style, to reduce symbol table bloat?
455   | debugStyle sty = pp_mod <> ppr_occ_name occ
456                      <> braces (hsep [if is_wired then ptext (sLit "(w)") else empty,
457                                       pprNameSpaceBrief (occNameSpace occ),
458                                       pprUnique uniq])
459   | BuiltInSyntax <- is_builtin = ppr_occ_name occ  -- Never qualify builtin syntax
460   | otherwise                   = pprModulePrefix sty mod name <> ppr_occ_name occ
461   where
462     pp_mod = sdocWithDynFlags $ \dflags ->
463              if gopt Opt_SuppressModulePrefixes dflags
464              then empty
465              else 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 -> Name -> 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 name = sdocWithDynFlags $ \dflags ->
493   if gopt Opt_SuppressModulePrefixes dflags
494   then empty
495   else
496     case qualName sty name 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   = sdocWithDynFlags $ \dflags ->
508     if gopt Opt_SuppressUniques dflags
509     then empty
510     else char '_' <> pprUnique uniq
511
512 ppr_occ_name :: OccName -> SDoc
513 ppr_occ_name occ = ftext (occNameFS occ)
514         -- Don't use pprOccName; instead, just print the string of the OccName;
515         -- we print the namespace in the debug stuff above
516
517 -- In code style, we Z-encode the strings.  The results of Z-encoding each FastString are
518 -- cached behind the scenes in the FastString implementation.
519 ppr_z_occ_name :: OccName -> SDoc
520 ppr_z_occ_name occ = ztext (zEncodeFS (occNameFS occ))
521
522 -- Prints (if mod information is available) "Defined at <loc>" or
523 --  "Defined in <mod>" information for a Name.
524 pprDefinedAt :: Name -> SDoc
525 pprDefinedAt name = ptext (sLit "Defined") <+> pprNameDefnLoc name
526
527 pprNameDefnLoc :: Name -> SDoc
528 -- Prints "at <loc>" or
529 --     or "in <mod>" depending on what info is available
530 pprNameDefnLoc name
531   = case nameSrcLoc name of
532          -- nameSrcLoc rather than nameSrcSpan
533          -- It seems less cluttered to show a location
534          -- rather than a span for the definition point
535        RealSrcLoc s -> ptext (sLit "at") <+> ppr s
536        UnhelpfulLoc s
537          | isInternalName name || isSystemName name
538          -> ptext (sLit "at") <+> ftext s
539          | otherwise
540          -> ptext (sLit "in") <+> quotes (ppr (nameModule name))
541 \end{code}
542
543 %************************************************************************
544 %*                                                                      *
545 \subsection{Overloaded functions related to Names}
546 %*                                                                      *
547 %************************************************************************
548
549 \begin{code}
550 -- | A class allowing convenient access to the 'Name' of various datatypes
551 class NamedThing a where
552     getOccName :: a -> OccName
553     getName    :: a -> Name
554
555     getOccName n = nameOccName (getName n)      -- Default method
556 \end{code}
557
558 \begin{code}
559 getSrcLoc           :: NamedThing a => a -> SrcLoc
560 getSrcSpan          :: NamedThing a => a -> SrcSpan
561 getOccString        :: NamedThing a => a -> String
562
563 getSrcLoc           = nameSrcLoc           . getName
564 getSrcSpan          = nameSrcSpan          . getName
565 getOccString        = occNameString        . getOccName
566
567 pprInfixName, pprPrefixName :: (Outputable a, NamedThing a) => a -> SDoc
568 -- See Outputable.pprPrefixVar, pprInfixVar;
569 -- add parens or back-quotes as appropriate
570 pprInfixName  n = pprInfixVar (isSymOcc (getOccName n)) (ppr n)
571
572 pprPrefixName thing 
573  |  name `hasKey` liftedTypeKindTyConKey 
574  = ppr name   -- See Note [Special treatment for kind *]
575  | otherwise
576  = pprPrefixVar (isSymOcc (nameOccName name)) (ppr name)
577  where
578    name = getName thing
579 \end{code}
580
581 Note [Special treatment for kind *]
582 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
583 Do not put parens around the kind '*'.  Even though it looks like
584 an operator, it is really a special case.
585
586 This pprPrefixName stuff is really only used when printing HsSyn,
587 which has to be polymorphic in the name type, and hence has to go via
588 the overloaded function pprPrefixOcc.  It's easier where we know the
589 type being pretty printed; eg the pretty-printing code in TypeRep.
590
591 See Trac #7645, which led to this.
592