2 % (c) The University of Glasgow 2006
3 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
5 \section{@Vars@: Variables}
10 -- GHC uses several kinds of name internally:
12 -- * 'OccName.OccName': see "OccName#name_types"
14 -- * 'RdrName.RdrName': see "RdrName#name_types"
16 -- * 'Name.Name': see "Name#name_types"
18 -- * 'Id.Id': see "Id#name_types"
20 -- * 'Var.Var' is a synonym for the 'Id.Id' type but it may additionally potentially contain type variables,
21 -- which have a 'TypeRep.Kind' rather than a 'TypeRep.Type' and only contain some extra details during typechecking.
22 -- These 'Var.Var' names may either be global or local, see "Var#globalvslocal"
25 -- Global 'Id's and 'Var's are those that are imported or correspond to a data constructor, primitive operation, or record selectors.
26 -- Local 'Id's and 'Var's are those bound within an expression (e.g. by a lambda) or at the top level of the module being compiled.
28 -- * The main data type
31 -- ** Constructing 'Var's
32 mkLocalIdVar, mkExportedLocalIdVar, mkGlobalIdVar,
34 -- ** Taking 'Var's apart
35 varName, varUnique, varType, varIdInfo, globalIdVarDetails,
37 -- ** Modifying 'Var's
38 setVarName, setVarUnique, setVarType,
39 setIdVarExported, setIdVarNotExported,
40 globaliseIdVar, lazySetVarIdInfo,
43 isCoVar, isIdVar, isTyVar, isTcTyVar,
44 isLocalVar, isLocalIdVar,
45 isGlobalIdVar, isExportedIdVar,
48 -- * Type variable data type
51 -- ** Constructing 'TyVar's
52 mkTyVar, mkTcTyVar, mkWildCoVar,
54 -- ** Taking 'TyVar's apart
55 tyVarName, tyVarKind, tcTyVarDetails,
57 -- ** Modifying 'TyVar's
58 setTyVarName, setTyVarUnique, setTyVarKind,
60 -- * Coercion variable data type
63 -- ** Constructing 'CoVar's
66 -- ** Taking 'CoVar's apart
69 -- ** Modifying 'CoVar's
70 setCoVarUnique, setCoVarName,
72 -- * 'Var' type synonyms
76 #include "HsVersions.h"
78 import {-# SOURCE #-} TypeRep( Type, Kind )
79 import {-# SOURCE #-} TcType( TcTyVarDetails, pprTcTyVarDetails )
80 import {-# SOURCE #-} IdInfo( GlobalIdDetails, notGlobalId,
82 import {-# SOURCE #-} TypeRep( isCoercionKind )
84 import Name hiding (varName)
92 %************************************************************************
94 \subsection{The main data type declarations}
96 %************************************************************************
99 Every @Var@ has a @Unique@, to uniquify it and for fast comparison, a
100 @Type@, and an @IdInfo@ (non-essential info about it, e.g.,
101 strictness). The essential info about different kinds of @Vars@ is
105 -- | Essentially a typed 'Name', that may also contain some additional information
106 -- about the 'Var' and it's use sites.
110 realUnique :: FastInt, -- Key for fast comparison
111 -- Identical to the Unique in the name,
112 -- cached here for speed
113 varType :: Kind, -- ^ The type or kind of the 'Var' in question
114 isCoercionVar :: Bool
117 | TcTyVar { -- Used only during type inference
118 -- Used for kind variables during
119 -- inference, as well
121 realUnique :: FastInt,
123 tcTyVarDetails :: TcTyVarDetails }
125 | GlobalId { -- Used for imported Ids, dict selectors etc
126 -- See Note [GlobalId/LocalId] below
127 varName :: !Name, -- Always an External or WiredIn Name
128 realUnique :: FastInt,
131 gblDetails :: GlobalIdDetails }
133 | LocalId { -- Used for locally-defined Ids
134 -- See Note [GlobalId/LocalId] below
136 realUnique :: FastInt,
139 lclDetails :: LocalIdDetails }
142 = NotExported -- ^ Not exported: may be discarded as dead code.
143 | Exported -- ^ Exported: kept alive
146 Note [GlobalId/LocalId]
147 ~~~~~~~~~~~~~~~~~~~~~~~
149 * always a constant (top-level)
150 * imported, or data constructor, or primop, or record selector
151 * has a Unique that is globally unique across the whole
152 GHC invocation (a single invocation may compile multiple modules)
153 * never treated as a candidate by the free-variable finder;
157 * bound within an expression (lambda, case, local let(rec))
158 * or defined at top level in the module being compiled
159 * always treated as a candidate by the free-variable finder
161 After CoreTidy, top-level LocalIds are turned into GlobalIds
164 instance Outputable Var where
165 ppr var = ppr (varName var) <+> ifPprDebug (brackets extra)
168 GlobalId {} -> ptext (sLit "gid")
169 LocalId {} -> ptext (sLit "lid")
170 TyVar {} -> ptext (sLit "tv")
171 TcTyVar {tcTyVarDetails = details} -> pprTcTyVarDetails details
173 instance Show Var where
174 showsPrec p var = showsPrecSDoc p (ppr var)
176 instance NamedThing Var where
179 instance Uniquable Var where
180 getUnique = varUnique
182 instance Eq Var where
183 a == b = realUnique a ==# realUnique b
185 instance Ord Var where
186 a <= b = realUnique a <=# realUnique b
187 a < b = realUnique a <# realUnique b
188 a >= b = realUnique a >=# realUnique b
189 a > b = realUnique a ># realUnique b
190 a `compare` b = varUnique a `compare` varUnique b
195 varUnique :: Var -> Unique
196 varUnique var = mkUniqueGrimily (iBox (realUnique var))
198 setVarUnique :: Var -> Unique -> Var
199 setVarUnique var uniq
200 = var { realUnique = getKeyFastInt uniq,
201 varName = setNameUnique (varName var) uniq }
203 setVarName :: Var -> Name -> Var
204 setVarName var new_name
205 = var { realUnique = getKeyFastInt (getUnique new_name),
208 setVarType :: Id -> Type -> Id
209 setVarType id ty = id { varType = ty }
211 setIdVarExported :: Var -> Var
212 -- ^ Exports the given local 'Id'. Can also be called on global 'Id's, such as data constructors
213 -- and class operations, which are born as global 'Id's and automatically exported
214 setIdVarExported id@(LocalId {}) = id { lclDetails = Exported }
215 setIdVarExported other_id = ASSERT( isIdVar other_id ) other_id
217 setIdVarNotExported :: Id -> Id
218 -- ^ We can only do this to LocalIds
219 setIdVarNotExported id = ASSERT( isLocalIdVar id ) id { lclDetails = NotExported }
221 globaliseIdVar :: GlobalIdDetails -> Var -> Var
222 -- ^ If it's a local, make it global
223 globaliseIdVar details id = GlobalId { varName = varName id,
224 realUnique = realUnique id,
225 varType = varType id,
226 idInfo_ = varIdInfo id,
227 gblDetails = details }
229 -- | Extract 'Id' information from the 'Var' if it represents a global or local 'Id', otherwise panic
230 varIdInfo :: Var -> IdInfo
231 varIdInfo (GlobalId {idInfo_ = info}) = info
232 varIdInfo (LocalId {idInfo_ = info}) = info
233 varIdInfo other_var = pprPanic "idInfo" (ppr other_var)
235 lazySetVarIdInfo :: Var -> IdInfo -> Var
236 lazySetVarIdInfo id info = id { idInfo_ = info }
240 %************************************************************************
242 \subsection{Type variables}
244 %************************************************************************
249 tyVarName :: TyVar -> Name
252 tyVarKind :: TyVar -> Kind
255 setTyVarUnique :: TyVar -> Unique -> TyVar
256 setTyVarUnique = setVarUnique
258 setTyVarName :: TyVar -> Name -> TyVar
259 setTyVarName = setVarName
261 setTyVarKind :: TyVar -> Kind -> TyVar
262 setTyVarKind tv k = tv {varType = k}
266 mkTyVar :: Name -> Kind -> TyVar
267 mkTyVar name kind = ASSERT( not (isCoercionKind kind ) )
268 TyVar { varName = name
269 , realUnique = getKeyFastInt (nameUnique name)
271 , isCoercionVar = False
274 mkTcTyVar :: Name -> Kind -> TcTyVarDetails -> TyVar
275 mkTcTyVar name kind details
276 = -- TOM: no longer valid assertion?
277 -- ASSERT( not (isCoercionKind kind) )
278 TcTyVar { varName = name,
279 realUnique = getKeyFastInt (nameUnique name),
281 tcTyVarDetails = details
285 %************************************************************************
287 \subsection{Coercion variables}
289 %************************************************************************
292 type CoVar = Var -- ^ A coercion variable is simply a type
293 -- variable of kind @ty1 :=: ty2@. Hence its
294 -- 'varType' is always @PredTy (EqPred t1 t2)@
296 coVarName :: CoVar -> Name
299 setCoVarUnique :: CoVar -> Unique -> CoVar
300 setCoVarUnique = setVarUnique
302 setCoVarName :: CoVar -> Name -> CoVar
303 setCoVarName = setVarName
305 mkCoVar :: Name -> Kind -> CoVar
306 mkCoVar name kind = ASSERT( isCoercionKind kind )
307 TyVar { varName = name
308 , realUnique = getKeyFastInt (nameUnique name)
310 , isCoercionVar = True
313 mkWildCoVar :: Kind -> TyVar
314 -- ^ Create a type variable that is never referred to, so its unique doesn't matter
316 = ASSERT( isCoercionKind kind )
317 TyVar { varName = mkSysTvName wild_uniq (fsLit "co_wild"),
318 realUnique = _ILIT(1),
320 isCoercionVar = True }
322 wild_uniq = mkBuiltinUnique 1
326 %************************************************************************
330 %************************************************************************
334 -- These synonyms are here and not in Id because otherwise we need a very
335 -- large number of SOURCE imports of Id.hs :-(
341 %************************************************************************
343 \subsection{Predicates over variables}
345 %************************************************************************
348 -- | For an explanation of global vs. local 'Var's, see "Var#globalvslocal"
349 mkGlobalIdVar :: GlobalIdDetails -> Name -> Type -> IdInfo -> Var
350 mkGlobalIdVar details name ty info
351 = GlobalId { varName = name,
352 realUnique = getKeyFastInt (nameUnique name), -- Cache the unique
354 gblDetails = details,
357 mkLocalIdVar' :: Name -> Type -> LocalIdDetails -> IdInfo -> Var
358 mkLocalIdVar' name ty details info
359 = LocalId { varName = name,
360 realUnique = getKeyFastInt (nameUnique name), -- Cache the unique
362 lclDetails = details,
365 -- | For an explanation of global vs. local 'Var's, see "Var#globalvslocal"
366 mkLocalIdVar :: Name -> Type -> IdInfo -> Var
367 mkLocalIdVar name ty info = mkLocalIdVar' name ty NotExported info
369 -- | Exported 'Var's will not be removed as dead code
370 mkExportedLocalIdVar :: Name -> Type -> IdInfo -> Var
371 mkExportedLocalIdVar name ty info = mkLocalIdVar' name ty Exported info
375 isTyVar :: Var -> Bool
376 isTyVar (TyVar {}) = True
377 isTyVar (TcTyVar {}) = True
380 isTcTyVar :: Var -> Bool
381 isTcTyVar (TcTyVar {}) = True
384 isIdVar :: Var -> Bool
385 isIdVar (LocalId {}) = True
386 isIdVar (GlobalId {}) = True
389 isLocalIdVar :: Var -> Bool
390 isLocalIdVar (LocalId {}) = True
391 isLocalIdVar _ = False
393 isCoVar :: Var -> Bool
394 isCoVar (v@(TyVar {})) = isCoercionVar v
397 -- | 'isLocalVar' returns @True@ for type variables as well as local 'Id's
398 -- These are the variables that we need to pay attention to when finding free
399 -- variables, or doing dependency analysis.
400 isLocalVar :: Var -> Bool
401 isLocalVar (GlobalId {}) = False
404 -- | 'mustHaveLocalBinding' returns @True@ of 'Id's and 'TyVar's
405 -- that must have a binding in this module. The converse
406 -- is not quite right: there are some global 'Id's that must have
407 -- bindings, such as record selectors. But that doesn't matter,
408 -- because it's only used for assertions
409 mustHaveLocalBinding :: Var -> Bool
410 mustHaveLocalBinding var = isLocalVar var
412 isGlobalIdVar :: Var -> Bool
413 isGlobalIdVar (GlobalId {}) = True
414 isGlobalIdVar _ = False
416 -- | 'isExportedIdVar' means \"don't throw this away\"
417 isExportedIdVar :: Var -> Bool
418 isExportedIdVar (GlobalId {}) = True
419 isExportedIdVar (LocalId {lclDetails = details})
423 isExportedIdVar _ = False
427 globalIdVarDetails :: Var -> GlobalIdDetails
428 -- ^ Find the global 'Id' information if the 'Var' is a global 'Id', otherwise returns 'notGlobalId'
429 globalIdVarDetails (GlobalId {gblDetails = details}) = details
430 globalIdVarDetails _ = notGlobalId