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