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