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