Merge branch 'master' of http://darcs.haskell.org/ghc
[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
52         nameSrcLoc, nameSrcSpan, pprNameLoc,
53
54         -- ** Predicates on 'Name's
55         isSystemName, isInternalName, isExternalName,
56         isTyVarName, isTyConName, isDataConName, 
57         isValName, isVarName,
58         isWiredInName, isBuiltInSyntax,
59         wiredInNameTyThing_maybe, 
60         nameIsLocalOrFrom, stableNameCmp,
61
62         -- * Class 'NamedThing' and overloaded friends
63         NamedThing(..),
64         getSrcLoc, getSrcSpan, getOccString,
65
66         pprInfixName, pprPrefixName, pprModulePrefix,
67
68         -- Re-export the OccName stuff
69         module OccName
70     ) where
71
72 #include "Typeable.h"
73
74 import {-# SOURCE #-} TypeRep( TyThing )
75
76 import OccName
77 import Module
78 import SrcLoc
79 import Unique
80 import Util
81 import Maybes
82 import Binary
83 import StaticFlags
84 import FastTypes
85 import FastString
86 import Outputable
87
88 import Data.Array
89 import Data.Data
90 import Data.Word        ( Word32 )
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 nameUnique              :: Name -> Unique
166 nameOccName             :: Name -> OccName 
167 nameModule              :: Name -> Module
168 nameSrcLoc              :: Name -> SrcLoc
169 nameSrcSpan             :: Name -> SrcSpan
170
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
175 \end{code}
176
177 %************************************************************************
178 %*                                                                      *
179 \subsection{Predicates on names}
180 %*                                                                      *
181 %************************************************************************
182
183 \begin{code}
184 nameIsLocalOrFrom :: Module -> Name -> Bool
185 isInternalName    :: Name -> Bool
186 isExternalName    :: Name -> Bool
187 isSystemName      :: Name -> Bool
188 isWiredInName     :: Name -> Bool
189
190 isWiredInName (Name {n_sort = WiredIn _ _ _}) = True
191 isWiredInName _                               = False
192
193 wiredInNameTyThing_maybe :: Name -> Maybe TyThing
194 wiredInNameTyThing_maybe (Name {n_sort = WiredIn _ thing _}) = Just thing
195 wiredInNameTyThing_maybe _                                   = Nothing
196
197 isBuiltInSyntax :: Name -> Bool
198 isBuiltInSyntax (Name {n_sort = WiredIn _ _ BuiltInSyntax}) = True
199 isBuiltInSyntax _                                           = False
200
201 isExternalName (Name {n_sort = External _})    = True
202 isExternalName (Name {n_sort = WiredIn _ _ _}) = True
203 isExternalName _                               = False
204
205 isInternalName name = not (isExternalName name)
206
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
212
213 nameIsLocalOrFrom from name
214   | isExternalName name = from == nameModule name
215   | otherwise           = True
216
217 isTyVarName :: Name -> Bool
218 isTyVarName name = isTvOcc (nameOccName name)
219
220 isTyConName :: Name -> Bool
221 isTyConName name = isTcOcc (nameOccName name)
222
223 isDataConName :: Name -> Bool
224 isDataConName name = isDataOcc (nameOccName name)
225
226 isValName :: Name -> Bool
227 isValName name = isValOcc (nameOccName name)
228
229 isVarName :: Name -> Bool
230 isVarName = isVarOcc . nameOccName
231
232 isSystemName (Name {n_sort = System}) = True
233 isSystemName _                        = False
234 \end{code}
235
236
237 %************************************************************************
238 %*                                                                      *
239 \subsection{Making names}
240 %*                                                                      *
241 %************************************************************************
242
243 \begin{code}
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
248                                    , n_sort = Internal
249                                    , n_occ = occ
250                                    , n_loc = loc }
251         -- NB: You might worry that after lots of huffing and
252         -- puffing we might end up with two local names with distinct
253         -- uniques, but the same OccName.  Indeed we can, but that's ok
254         --      * the insides of the compiler don't care: they use the Unique
255         --      * when printing for -ddump-xxx you can switch on -dppr-debug to get the
256         --        uniques if you get confused
257         --      * for interface files we tidyCore first, which puts the uniques
258         --        into the print name (see setNameVisibility below)
259
260 mkDerivedInternalName :: (OccName -> OccName) -> Unique -> Name -> Name
261 mkDerivedInternalName derive_occ uniq (Name { n_occ = occ, n_loc = loc })
262   = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal
263          , n_occ = derive_occ occ, n_loc = loc }
264
265 -- | Create a name which definitely originates in the given module
266 mkExternalName :: Unique -> Module -> OccName -> SrcSpan -> Name
267 mkExternalName uniq mod occ loc 
268   = Name { n_uniq = getKeyFastInt uniq, n_sort = External mod,
269            n_occ = occ, n_loc = loc }
270
271 -- | Create a name which is actually defined by the compiler itself
272 mkWiredInName :: Module -> OccName -> Unique -> TyThing -> BuiltInSyntax -> Name
273 mkWiredInName mod occ uniq thing built_in
274   = Name { n_uniq = getKeyFastInt uniq,
275            n_sort = WiredIn mod thing built_in,
276            n_occ = occ, n_loc = wiredInSrcSpan }
277
278 -- | Create a name brought into being by the compiler
279 mkSystemName :: Unique -> OccName -> Name
280 mkSystemName uniq occ = Name { n_uniq = getKeyFastInt uniq, n_sort = System, 
281                                n_occ = occ, n_loc = noSrcSpan }
282
283 mkSystemVarName :: Unique -> FastString -> Name
284 mkSystemVarName uniq fs = mkSystemName uniq (mkVarOccFS fs)
285
286 mkSysTvName :: Unique -> FastString -> Name
287 mkSysTvName uniq fs = mkSystemName uniq (mkOccNameFS tvName fs)
288
289 -- | Make a name for a foreign call
290 mkFCallName :: Unique -> String -> Name
291         -- The encoded string completely describes the ccall
292 mkFCallName uniq str =  Name { n_uniq = getKeyFastInt uniq, n_sort = Internal, 
293                                n_occ = mkVarOcc str, n_loc = noSrcSpan }
294
295
296 mkTickBoxOpName :: Unique -> String -> Name
297 mkTickBoxOpName uniq str 
298    = Name { n_uniq = getKeyFastInt uniq, n_sort = Internal, 
299             n_occ = mkVarOcc str, n_loc = noSrcSpan }
300
301 -- | Make the name of an implicit parameter
302 mkIPName :: Unique -> OccName -> Name
303 mkIPName uniq occ
304   = Name { n_uniq = getKeyFastInt uniq,
305            n_sort = Internal,
306            n_occ  = occ,
307            n_loc = noSrcSpan }
308 \end{code}
309
310 \begin{code}
311 -- When we renumber/rename things, we need to be
312 -- able to change a Name's Unique to match the cached
313 -- one in the thing it's the name of.  If you know what I mean.
314 setNameUnique :: Name -> Unique -> Name
315 setNameUnique name uniq = name {n_uniq = getKeyFastInt uniq}
316
317 tidyNameOcc :: Name -> OccName -> Name
318 -- We set the OccName of a Name when tidying
319 -- In doing so, we change System --> Internal, so that when we print
320 -- it we don't get the unique by default.  It's tidy now!
321 tidyNameOcc name@(Name { n_sort = System }) occ = name { n_occ = occ, n_sort = Internal}
322 tidyNameOcc name                            occ = name { n_occ = occ }
323
324 -- | Make the 'Name' into an internal name, regardless of what it was to begin with
325 localiseName :: Name -> Name
326 localiseName n = n { n_sort = Internal }
327 \end{code}
328
329 %************************************************************************
330 %*                                                                      *
331 \subsection{Hashing and comparison}
332 %*                                                                      *
333 %************************************************************************
334
335 \begin{code}
336 hashName :: Name -> Int         -- ToDo: should really be Word
337 hashName name = getKey (nameUnique name) + 1
338         -- The +1 avoids keys with lots of zeros in the ls bits, which 
339         -- interacts badly with the cheap and cheerful multiplication in
340         -- hashExpr
341
342 cmpName :: Name -> Name -> Ordering
343 cmpName n1 n2 = iBox (n_uniq n1) `compare` iBox (n_uniq n2)
344
345 stableNameCmp :: Name -> Name -> Ordering
346 -- Compare lexicographically
347 stableNameCmp (Name { n_sort = s1, n_occ = occ1 })
348               (Name { n_sort = s2, n_occ = occ2 })
349   = (s1 `sort_cmp` s2) `thenCmp` (occ1 `compare` occ2)
350     -- The ordinary compare on OccNames is lexicogrpahic
351   where
352     -- Later constructors are bigger
353     sort_cmp (External m1) (External m2)       = m1 `stableModuleCmp` m2
354     sort_cmp (External {}) _                   = LT
355     sort_cmp (WiredIn {}) (External {})        = GT
356     sort_cmp (WiredIn m1 _ _) (WiredIn m2 _ _) = m1 `stableModuleCmp` m2
357     sort_cmp (WiredIn {})     _                = LT
358     sort_cmp Internal         (External {})    = GT
359     sort_cmp Internal         (WiredIn {})     = GT
360     sort_cmp Internal         Internal         = EQ
361     sort_cmp Internal         System           = LT
362     sort_cmp System           System           = EQ
363     sort_cmp System           _                = GT
364 \end{code}
365
366 %************************************************************************
367 %*                                                                      *
368 \subsection[Name-instances]{Instance declarations}
369 %*                                                                      *
370 %************************************************************************
371
372 \begin{code}
373 instance Eq Name where
374     a == b = case (a `compare` b) of { EQ -> True;  _ -> False }
375     a /= b = case (a `compare` b) of { EQ -> False; _ -> True }
376
377 instance Ord Name where
378     a <= b = case (a `compare` b) of { LT -> True;  EQ -> True;  GT -> False }
379     a <  b = case (a `compare` b) of { LT -> True;  EQ -> False; GT -> False }
380     a >= b = case (a `compare` b) of { LT -> False; EQ -> True;  GT -> True  }
381     a >  b = case (a `compare` b) of { LT -> False; EQ -> False; GT -> True  }
382     compare a b = cmpName a b
383
384 instance Uniquable Name where
385     getUnique = nameUnique
386
387 instance NamedThing Name where
388     getName n = n
389
390 instance Data Name where
391   -- don't traverse?
392   toConstr _   = abstractConstr "Name"
393   gunfold _ _  = error "gunfold"
394   dataTypeOf _ = mkNoRepType "Name"
395 \end{code}
396
397 %************************************************************************
398 %*                                                                      *
399 \subsection{Binary}
400 %*                                                                      *
401 %************************************************************************
402
403 \begin{code}
404 instance Binary Name where
405    put_ bh name =
406       case getUserData bh of 
407         UserData{ ud_put_name = put_name } -> put_name bh name
408
409    get bh = do
410         i <- get bh
411         return $! (ud_symtab (getUserData bh) ! fromIntegral (i::Word32))
412 \end{code}
413
414 %************************************************************************
415 %*                                                                      *
416 \subsection{Pretty printing}
417 %*                                                                      *
418 %************************************************************************
419
420 \begin{code}
421 instance Outputable Name where
422     ppr name = pprName name
423
424 instance OutputableBndr Name where
425     pprBndr _ name = pprName name
426
427 pprName :: Name -> SDoc
428 pprName (Name {n_sort = sort, n_uniq = u, n_occ = occ})
429   = getPprStyle $ \ sty ->
430     case sort of
431       WiredIn mod _ builtin   -> pprExternal sty uniq mod occ True  builtin
432       External mod            -> pprExternal sty uniq mod occ False UserSyntax
433       System                  -> pprSystem sty uniq occ
434       Internal                -> pprInternal sty uniq occ
435   where uniq = mkUniqueGrimily (iBox u)
436
437 pprExternal :: PprStyle -> Unique -> Module -> OccName -> Bool -> BuiltInSyntax -> SDoc
438 pprExternal sty uniq mod occ is_wired is_builtin
439   | codeStyle sty = ppr mod <> char '_' <> ppr_z_occ_name occ
440         -- In code style, always qualify
441         -- ToDo: maybe we could print all wired-in things unqualified
442         --       in code style, to reduce symbol table bloat?
443   | debugStyle sty = ppr mod <> dot <> ppr_occ_name occ
444                      <> braces (hsep [if is_wired then ptext (sLit "(w)") else empty,
445                                       pprNameSpaceBrief (occNameSpace occ), 
446                                       pprUnique uniq])
447   | BuiltInSyntax <- is_builtin = ppr_occ_name occ  -- Never qualify builtin syntax
448   | otherwise                   = pprModulePrefix sty mod occ <> ppr_occ_name occ
449
450 pprInternal :: PprStyle -> Unique -> OccName -> SDoc
451 pprInternal sty uniq occ
452   | codeStyle sty  = pprUnique uniq
453   | debugStyle sty = ppr_occ_name occ <> braces (hsep [pprNameSpaceBrief (occNameSpace occ), 
454                                                        pprUnique uniq])
455   | dumpStyle sty  = ppr_occ_name occ <> ppr_underscore_unique uniq
456                         -- For debug dumps, we're not necessarily dumping
457                         -- tidied code, so we need to print the uniques.
458   | otherwise      = ppr_occ_name occ   -- User style
459
460 -- Like Internal, except that we only omit the unique in Iface style
461 pprSystem :: PprStyle -> Unique -> OccName -> SDoc
462 pprSystem sty uniq occ
463   | codeStyle sty  = pprUnique uniq
464   | debugStyle sty = ppr_occ_name occ <> ppr_underscore_unique uniq
465                      <> braces (pprNameSpaceBrief (occNameSpace occ))
466   | otherwise      = ppr_occ_name occ <> ppr_underscore_unique uniq
467                                 -- If the tidy phase hasn't run, the OccName
468                                 -- is unlikely to be informative (like 's'),
469                                 -- so print the unique
470
471
472 pprModulePrefix :: PprStyle -> Module -> OccName -> SDoc
473 -- Print the "M." part of a name, based on whether it's in scope or not
474 -- See Note [Printing original names] in HscTypes
475 pprModulePrefix sty mod occ
476   | opt_SuppressModulePrefixes = empty
477   
478   | otherwise
479   = case qualName sty mod occ of                   -- See Outputable.QualifyName:
480       NameQual modname -> ppr modname <> dot       -- Name is in scope       
481       NameNotInScope1  -> ppr mod <> dot           -- Not in scope
482       NameNotInScope2  -> ppr (modulePackageId mod) <> colon     -- Module not in
483                           <> ppr (moduleName mod) <> dot         -- scope eithber
484       _otherwise       -> empty
485
486 ppr_underscore_unique :: Unique -> SDoc
487 -- Print an underscore separating the name from its unique
488 -- But suppress it if we aren't printing the uniques anyway
489 ppr_underscore_unique uniq
490   | opt_SuppressUniques = empty
491   | otherwise           = char '_' <> pprUnique uniq
492
493 ppr_occ_name :: OccName -> SDoc
494 ppr_occ_name occ = ftext (occNameFS occ)
495         -- Don't use pprOccName; instead, just print the string of the OccName; 
496         -- we print the namespace in the debug stuff above
497
498 -- In code style, we Z-encode the strings.  The results of Z-encoding each FastString are
499 -- cached behind the scenes in the FastString implementation.
500 ppr_z_occ_name :: OccName -> SDoc
501 ppr_z_occ_name occ = ftext (zEncodeFS (occNameFS occ))
502
503 -- Prints (if mod information is available) "Defined at <loc>" or 
504 --  "Defined in <mod>" information for a Name.
505 pprNameLoc :: Name -> SDoc
506 pprNameLoc name = case nameSrcSpan name of
507                   RealSrcSpan s ->
508                       pprDefnLoc s
509                   UnhelpfulSpan _
510                    | isInternalName name || isSystemName name ->
511                       ptext (sLit "<no location info>")
512                    | otherwise ->
513                       ptext (sLit "Defined in ") <> ppr (nameModule name)
514 \end{code}
515
516 %************************************************************************
517 %*                                                                      *
518 \subsection{Overloaded functions related to Names}
519 %*                                                                      *
520 %************************************************************************
521
522 \begin{code}
523 -- | A class allowing convenient access to the 'Name' of various datatypes
524 class NamedThing a where
525     getOccName :: a -> OccName
526     getName    :: a -> Name
527
528     getOccName n = nameOccName (getName n)      -- Default method
529 \end{code}
530
531 \begin{code}
532 getSrcLoc           :: NamedThing a => a -> SrcLoc
533 getSrcSpan          :: NamedThing a => a -> SrcSpan
534 getOccString        :: NamedThing a => a -> String
535
536 getSrcLoc           = nameSrcLoc           . getName
537 getSrcSpan          = nameSrcSpan          . getName
538 getOccString        = occNameString        . getOccName
539
540 pprInfixName, pprPrefixName :: (Outputable a, NamedThing a) => a -> SDoc
541 -- See Outputable.pprPrefixVar, pprInfixVar; 
542 -- add parens or back-quotes as appropriate
543 pprInfixName  n = pprInfixVar  (isSymOcc (getOccName n)) (ppr n)
544 pprPrefixName n = pprPrefixVar (isSymOcc (getOccName n)) (ppr n)
545 \end{code}
546