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