87658b542ebc53b71fe6b78d58d5ea7f8898a6fb
[ghc.git] / compiler / basicTypes / Var.hs
1 {-
2 (c) The University of Glasgow 2006
3 (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
4
5 \section{@Vars@: Variables}
6 -}
7
8 {-# LANGUAGE CPP, DeriveDataTypeable #-}
9 -- |
10 -- #name_types#
11 -- GHC uses several kinds of name internally:
12 --
13 -- * 'OccName.OccName': see "OccName#name_types"
14 --
15 -- * 'RdrName.RdrName': see "RdrName#name_types"
16 --
17 -- * 'Name.Name': see "Name#name_types"
18 --
19 -- * 'Id.Id': see "Id#name_types"
20 --
21 -- * 'Var.Var' is a synonym for the 'Id.Id' type but it may additionally
22 -- potentially contain type variables, which have a 'TypeRep.Kind'
23 -- rather than a 'TypeRep.Type' and only contain some extra
24 -- details during typechecking.
25 --
26 -- These 'Var.Var' names may either be global or local, see "Var#globalvslocal"
27 --
28 -- #globalvslocal#
29 -- Global 'Id's and 'Var's are those that are imported or correspond
30 -- to a data constructor, primitive operation, or record selectors.
31 -- Local 'Id's and 'Var's are those bound within an expression
32 -- (e.g. by a lambda) or at the top level of the module being compiled.
33
34 module Var (
35 -- * The main data type and synonyms
36 Var, CoVar, Id, DictId, DFunId, EvVar, EqVar, EvId, IpId,
37 TyVar, TypeVar, KindVar, TKVar,
38
39 -- ** Taking 'Var's apart
40 varName, varUnique, varType,
41
42 -- ** Modifying 'Var's
43 setVarName, setVarUnique, setVarType,
44
45 -- ** Constructing, taking apart, modifying 'Id's
46 mkGlobalVar, mkLocalVar, mkExportedLocalVar, mkCoVar,
47 idInfo, idDetails,
48 lazySetIdInfo, setIdDetails, globaliseId,
49 setIdExported, setIdNotExported,
50
51 -- ** Predicates
52 isId, isTKVar, isTyVar, isTcTyVar,
53 isLocalVar, isLocalId,
54 isGlobalId, isExportedId,
55 mustHaveLocalBinding,
56
57 -- ** Constructing 'TyVar's
58 mkTyVar, mkTcTyVar, mkKindVar,
59
60 -- ** Taking 'TyVar's apart
61 tyVarName, tyVarKind, tcTyVarDetails, setTcTyVarDetails,
62
63 -- ** Modifying 'TyVar's
64 setTyVarName, setTyVarUnique, setTyVarKind, updateTyVarKind,
65 updateTyVarKindM
66
67 ) where
68
69 #include "HsVersions.h"
70
71 import {-# SOURCE #-} TypeRep( Type, Kind, SuperKind )
72 import {-# SOURCE #-} TcType( TcTyVarDetails, pprTcTyVarDetails )
73 import {-# SOURCE #-} IdInfo( IdDetails, IdInfo, coVarDetails, vanillaIdInfo, pprIdDetails )
74
75 import Name hiding (varName)
76 import Unique
77 import Util
78 import FastString
79 import Outputable
80
81 import Data.Data
82
83 {-
84 ************************************************************************
85 * *
86 Synonyms
87 * *
88 ************************************************************************
89 -- These synonyms are here and not in Id because otherwise we need a very
90 -- large number of SOURCE imports of Id.hs :-(
91 -}
92
93 type Id = Var -- A term-level identifier
94
95 type TyVar = Var -- Type *or* kind variable (historical)
96
97 type TKVar = Var -- Type *or* kind variable (historical)
98 type TypeVar = Var -- Definitely a type variable
99 type KindVar = Var -- Definitely a kind variable
100 -- See Note [Kind and type variables]
101
102 -- See Note [Evidence: EvIds and CoVars]
103 type EvId = Id -- Term-level evidence: DictId, IpId, or EqVar
104 type EvVar = EvId -- ...historical name for EvId
105 type DFunId = Id -- A dictionary function
106 type DictId = EvId -- A dictionary variable
107 type IpId = EvId -- A term-level implicit parameter
108 type EqVar = EvId -- Boxed equality evidence
109
110 type CoVar = Id -- See Note [Evidence: EvIds and CoVars]
111
112 {-
113 Note [Evidence: EvIds and CoVars]
114 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115 * An EvId (evidence Id) is a *boxed*, term-level evidence variable
116 (dictionary, implicit parameter, or equality).
117
118 * A CoVar (coercion variable) is an *unboxed* term-level evidence variable
119 of type (t1 ~# t2). So it's the unboxed version of an EqVar.
120
121 * Only CoVars can occur in Coercions, EqVars appear in TcCoercions.
122
123 * DictId, IpId, and EqVar are synonyms when we know what kind of
124 evidence we are talking about. For example, an EqVar has type (t1 ~ t2).
125
126 Note [Kind and type variables]
127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128 Before kind polymorphism, TyVar were used to mean type variables. Now
129 they are use to mean kind *or* type variables. KindVar is used when we
130 know for sure that it is a kind variable. In future, we might want to
131 go over the whole compiler code to use:
132 - TKVar to mean kind or type variables
133 - TypeVar to mean type variables only
134 - KindVar to mean kind variables
135
136
137 ************************************************************************
138 * *
139 \subsection{The main data type declarations}
140 * *
141 ************************************************************************
142
143
144 Every @Var@ has a @Unique@, to uniquify it and for fast comparison, a
145 @Type@, and an @IdInfo@ (non-essential info about it, e.g.,
146 strictness). The essential info about different kinds of @Vars@ is
147 in its @VarDetails@.
148 -}
149
150 -- | Essentially a typed 'Name', that may also contain some additional information
151 -- about the 'Var' and it's use sites.
152 data Var
153 = TyVar { -- Type and kind variables
154 -- see Note [Kind and type variables]
155 varName :: !Name,
156 realUnique :: {-# UNPACK #-} !Int,
157 -- ^ Key for fast comparison
158 -- Identical to the Unique in the name,
159 -- cached here for speed
160 varType :: Kind -- ^ The type or kind of the 'Var' in question
161 }
162
163 | TcTyVar { -- Used only during type inference
164 -- Used for kind variables during
165 -- inference, as well
166 varName :: !Name,
167 realUnique :: {-# UNPACK #-} !Int,
168 varType :: Kind,
169 tc_tv_details :: TcTyVarDetails }
170
171 | Id {
172 varName :: !Name,
173 realUnique :: {-# UNPACK #-} !Int,
174 varType :: Type,
175 idScope :: IdScope,
176 id_details :: IdDetails, -- Stable, doesn't change
177 id_info :: IdInfo } -- Unstable, updated by simplifier
178 deriving Typeable
179
180 data IdScope -- See Note [GlobalId/LocalId]
181 = GlobalId
182 | LocalId ExportFlag
183
184 data ExportFlag -- See Note [ExportFlag on binders]
185 = NotExported -- ^ Not exported: may be discarded as dead code.
186 | Exported -- ^ Exported: kept alive
187
188 {- Note [ExportFlag on binders]
189 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190 An ExportFlag of "Exported" on a top-level binder says "keep this
191 binding alive; do not drop it as dead code". This transitively
192 keeps alive all the other top-level bindings that this binding refers
193 to. This property is persisted all the way down the pipeline, so that
194 the binding will be compiled all the way to object code, and its
195 symbols will appear in the linker symbol table.
196
197 However, note that this use of "exported" is quite different to the
198 export list on a Haskell module. Setting the ExportFlag on an Id does
199 /not/ mean that if you import the module (in Haskell source code) you
200 will see this Id. Of course, things that appear in the export list
201 of the source Haskell module do indeed have their ExportFlag set.
202 But many other things, such as dictionary functions, are kept alive
203 by having their ExportFlag set, even though they are not exported
204 in the source-code sense.
205
206 We should probably use a different term for ExportFlag, like
207 KeepAlive.
208
209 Note [GlobalId/LocalId]
210 ~~~~~~~~~~~~~~~~~~~~~~~
211 A GlobalId is
212 * always a constant (top-level)
213 * imported, or data constructor, or primop, or record selector
214 * has a Unique that is globally unique across the whole
215 GHC invocation (a single invocation may compile multiple modules)
216 * never treated as a candidate by the free-variable finder;
217 it's a constant!
218
219 A LocalId is
220 * bound within an expression (lambda, case, local let(rec))
221 * or defined at top level in the module being compiled
222 * always treated as a candidate by the free-variable finder
223
224 After CoreTidy, top-level LocalIds are turned into GlobalIds
225 -}
226
227 instance Outputable Var where
228 ppr var = ppr (varName var) <> getPprStyle (ppr_debug var)
229
230 ppr_debug :: Var -> PprStyle -> SDoc
231 ppr_debug (TyVar {}) sty
232 | debugStyle sty = brackets (ptext (sLit "tv"))
233 ppr_debug (TcTyVar {tc_tv_details = d}) sty
234 | dumpStyle sty || debugStyle sty = brackets (pprTcTyVarDetails d)
235 ppr_debug (Id { idScope = s, id_details = d }) sty
236 | debugStyle sty = brackets (ppr_id_scope s <> pprIdDetails d)
237 ppr_debug _ _ = empty
238
239 ppr_id_scope :: IdScope -> SDoc
240 ppr_id_scope GlobalId = ptext (sLit "gid")
241 ppr_id_scope (LocalId Exported) = ptext (sLit "lidx")
242 ppr_id_scope (LocalId NotExported) = ptext (sLit "lid")
243
244 instance NamedThing Var where
245 getName = varName
246
247 instance Uniquable Var where
248 getUnique = varUnique
249
250 instance Eq Var where
251 a == b = realUnique a == realUnique b
252
253 instance Ord Var where
254 a <= b = realUnique a <= realUnique b
255 a < b = realUnique a < realUnique b
256 a >= b = realUnique a >= realUnique b
257 a > b = realUnique a > realUnique b
258 a `compare` b = varUnique a `compare` varUnique b
259
260 instance Data Var where
261 -- don't traverse?
262 toConstr _ = abstractConstr "Var"
263 gunfold _ _ = error "gunfold"
264 dataTypeOf _ = mkNoRepType "Var"
265
266 varUnique :: Var -> Unique
267 varUnique var = mkUniqueGrimily (realUnique var)
268
269 setVarUnique :: Var -> Unique -> Var
270 setVarUnique var uniq
271 = var { realUnique = getKey uniq,
272 varName = setNameUnique (varName var) uniq }
273
274 setVarName :: Var -> Name -> Var
275 setVarName var new_name
276 = var { realUnique = getKey (getUnique new_name),
277 varName = new_name }
278
279 setVarType :: Id -> Type -> Id
280 setVarType id ty = id { varType = ty }
281
282 {-
283 ************************************************************************
284 * *
285 \subsection{Type and kind variables}
286 * *
287 ************************************************************************
288 -}
289
290 tyVarName :: TyVar -> Name
291 tyVarName = varName
292
293 tyVarKind :: TyVar -> Kind
294 tyVarKind = varType
295
296 setTyVarUnique :: TyVar -> Unique -> TyVar
297 setTyVarUnique = setVarUnique
298
299 setTyVarName :: TyVar -> Name -> TyVar
300 setTyVarName = setVarName
301
302 setTyVarKind :: TyVar -> Kind -> TyVar
303 setTyVarKind tv k = tv {varType = k}
304
305 updateTyVarKind :: (Kind -> Kind) -> TyVar -> TyVar
306 updateTyVarKind update tv = tv {varType = update (tyVarKind tv)}
307
308 updateTyVarKindM :: (Monad m) => (Kind -> m Kind) -> TyVar -> m TyVar
309 updateTyVarKindM update tv
310 = do { k' <- update (tyVarKind tv)
311 ; return $ tv {varType = k'} }
312
313 mkTyVar :: Name -> Kind -> TyVar
314 mkTyVar name kind = TyVar { varName = name
315 , realUnique = getKey (nameUnique name)
316 , varType = kind
317 }
318
319 mkTcTyVar :: Name -> Kind -> TcTyVarDetails -> TyVar
320 mkTcTyVar name kind details
321 = -- NB: 'kind' may be a coercion kind; cf, 'TcMType.newMetaCoVar'
322 TcTyVar { varName = name,
323 realUnique = getKey (nameUnique name),
324 varType = kind,
325 tc_tv_details = details
326 }
327
328 tcTyVarDetails :: TyVar -> TcTyVarDetails
329 tcTyVarDetails (TcTyVar { tc_tv_details = details }) = details
330 tcTyVarDetails var = pprPanic "tcTyVarDetails" (ppr var)
331
332 setTcTyVarDetails :: TyVar -> TcTyVarDetails -> TyVar
333 setTcTyVarDetails tv details = tv { tc_tv_details = details }
334
335 mkKindVar :: Name -> SuperKind -> KindVar
336 -- mkKindVar take a SuperKind as argument because we don't have access
337 -- to superKind here.
338 mkKindVar name kind = TyVar
339 { varName = name
340 , realUnique = getKey (nameUnique name)
341 , varType = kind }
342
343 {-
344 ************************************************************************
345 * *
346 \subsection{Ids}
347 * *
348 ************************************************************************
349 -}
350
351 idInfo :: Id -> IdInfo
352 idInfo (Id { id_info = info }) = info
353 idInfo other = pprPanic "idInfo" (ppr other)
354
355 idDetails :: Id -> IdDetails
356 idDetails (Id { id_details = details }) = details
357 idDetails other = pprPanic "idDetails" (ppr other)
358
359 -- The next three have a 'Var' suffix even though they always build
360 -- Ids, because Id.hs uses 'mkGlobalId' etc with different types
361 mkGlobalVar :: IdDetails -> Name -> Type -> IdInfo -> Id
362 mkGlobalVar details name ty info
363 = mk_id name ty GlobalId details info
364
365 mkLocalVar :: IdDetails -> Name -> Type -> IdInfo -> Id
366 mkLocalVar details name ty info
367 = mk_id name ty (LocalId NotExported) details info
368
369 mkCoVar :: Name -> Type -> CoVar
370 -- Coercion variables have no IdInfo
371 mkCoVar name ty = mk_id name ty (LocalId NotExported) coVarDetails vanillaIdInfo
372
373 -- | Exported 'Var's will not be removed as dead code
374 mkExportedLocalVar :: IdDetails -> Name -> Type -> IdInfo -> Id
375 mkExportedLocalVar details name ty info
376 = mk_id name ty (LocalId Exported) details info
377
378 mk_id :: Name -> Type -> IdScope -> IdDetails -> IdInfo -> Id
379 mk_id name ty scope details info
380 = Id { varName = name,
381 realUnique = getKey (nameUnique name),
382 varType = ty,
383 idScope = scope,
384 id_details = details,
385 id_info = info }
386
387 -------------------
388 lazySetIdInfo :: Id -> IdInfo -> Var
389 lazySetIdInfo id info = id { id_info = info }
390
391 setIdDetails :: Id -> IdDetails -> Id
392 setIdDetails id details = id { id_details = details }
393
394 globaliseId :: Id -> Id
395 -- ^ If it's a local, make it global
396 globaliseId id = id { idScope = GlobalId }
397
398 setIdExported :: Id -> Id
399 -- ^ Exports the given local 'Id'. Can also be called on global 'Id's, such as data constructors
400 -- and class operations, which are born as global 'Id's and automatically exported
401 setIdExported id@(Id { idScope = LocalId {} }) = id { idScope = LocalId Exported }
402 setIdExported id@(Id { idScope = GlobalId }) = id
403 setIdExported tv = pprPanic "setIdExported" (ppr tv)
404
405 setIdNotExported :: Id -> Id
406 -- ^ We can only do this to LocalIds
407 setIdNotExported id = ASSERT( isLocalId id )
408 id { idScope = LocalId NotExported }
409
410 {-
411 ************************************************************************
412 * *
413 \subsection{Predicates over variables}
414 * *
415 ************************************************************************
416 -}
417
418 isTyVar :: Var -> Bool
419 isTyVar = isTKVar -- Historical
420
421 isTKVar :: Var -> Bool -- True of both type and kind variables
422 isTKVar (TyVar {}) = True
423 isTKVar (TcTyVar {}) = True
424 isTKVar _ = False
425
426 isTcTyVar :: Var -> Bool
427 isTcTyVar (TcTyVar {}) = True
428 isTcTyVar _ = False
429
430 isId :: Var -> Bool
431 isId (Id {}) = True
432 isId _ = False
433
434 isLocalId :: Var -> Bool
435 isLocalId (Id { idScope = LocalId _ }) = True
436 isLocalId _ = False
437
438 -- | 'isLocalVar' returns @True@ for type variables as well as local 'Id's
439 -- These are the variables that we need to pay attention to when finding free
440 -- variables, or doing dependency analysis.
441 isLocalVar :: Var -> Bool
442 isLocalVar v = not (isGlobalId v)
443
444 isGlobalId :: Var -> Bool
445 isGlobalId (Id { idScope = GlobalId }) = True
446 isGlobalId _ = False
447
448 -- | 'mustHaveLocalBinding' returns @True@ of 'Id's and 'TyVar's
449 -- that must have a binding in this module. The converse
450 -- is not quite right: there are some global 'Id's that must have
451 -- bindings, such as record selectors. But that doesn't matter,
452 -- because it's only used for assertions
453 mustHaveLocalBinding :: Var -> Bool
454 mustHaveLocalBinding var = isLocalVar var
455
456 -- | 'isExportedIdVar' means \"don't throw this away\"
457 isExportedId :: Var -> Bool
458 isExportedId (Id { idScope = GlobalId }) = True
459 isExportedId (Id { idScope = LocalId Exported}) = True
460 isExportedId _ = False