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