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