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