ghc-7.7.20130829: The GHC API

Safe HaskellNone

Type

Contents

Description

Main functions for manipulating types and type-related things

Synopsis

Main data types representing Types

Types are one of:

Unboxed
Iff its representation is other than a pointer Unboxed types are also unlifted.
Lifted
Iff it has bottom as an element. Closures always have lifted types: i.e. any let-bound identifier in Core must have a lifted type. Operationally, a lifted object is one that can be entered. Only lifted types may be unified with a type variable.
Algebraic
Iff it is a type with one or more constructors, whether declared with data or newtype. An algebraic type is one that can be deconstructed with a case expression. This is not the same as lifted types, because we also include unboxed tuples in this classification.
Data
Iff it is a type declared with data, or a boxed tuple.
Primitive
Iff it is a built-in type that can't be expressed in Haskell.

Currently, all primitive types are unlifted, but that's not necessarily the case: for example, Int could be primitive.

Some primitive types are unboxed, such as Int#, whereas some are boxed but unlifted (such as ByteArray#). The only primitive types that we classify as algebraic are the unboxed tuples.

Some examples of type classifications that may make this a bit clearer are:

 Type         primitive       boxed           lifted          algebraic
 -----------------------------------------------------------------------------
 Int#         Yes             No              No              No
 ByteArray#   Yes             Yes             No              No
 (# a, b #)   Yes             No              No              Yes
 (  a, b  )   No              Yes             Yes             Yes
 [a]          No              Yes             Yes             Yes

A source type is a type that is a separate type as far as the type checker is concerned, but which has a more low-level representation as far as Core-to-Core passes and the rest of the back end is concerned.

You don't normally have to worry about this, as the utility functions in this module will automatically convert a source into a representation type if they are spotted, to the best of it's abilities. If you don't want this to happen, use the equivalent functions from the TcType module.

data TyThing Source

A typecheckable-thing, essentially anything that has a name

data Type Source

The key representation of types within the compiler

type PredType = TypeSource

A type of the form p of kind Constraint represents a value whose type is the Haskell predicate p, where a predicate is what occurs before the => in a Haskell type.

We use PredType as documentation to mark those types that we guarantee to have this kind.

It can be expanded into its representation, but:

  • The type checker must treat it as opaque
  • The rest of the compiler treats it as transparent

Consider these examples:

 f :: (Eq a) => a -> Int
 g :: (?x :: Int -> Int) => a -> Int
 h :: (r\l) => {r} => {l::Int | r}

Here the Eq a and ?x :: Int -> Int and rl are all called "predicates"

type ThetaType = [PredType]Source

A collection of PredTypes

data Var Source

Essentially a typed Name, that may also contain some additional information about the Var and it's use sites.

Constructing and deconstructing types

getTyVar :: String -> Type -> TyVarSource

Attempts to obtain the type variable underlying a Type, and panics with the given message if this is not a type variable type. See also getTyVar_maybe

getTyVar_maybe :: Type -> Maybe TyVarSource

Attempts to obtain the type variable underlying a Type

mkAppTy :: Type -> Type -> TypeSource

Applies a type to another, as in e.g. k a

splitAppTy :: Type -> (Type, Type)Source

Attempts to take a type application apart, as in splitAppTy_maybe, and panics if this is not possible

splitAppTys :: Type -> (Type, [Type])Source

Recursively splits a type as far as is possible, leaving a residual type being applied to and the type arguments applied to it. Never fails, even if that means returning an empty list of type applications.

splitAppTy_maybe :: Type -> Maybe (Type, Type)Source

Attempt to take a type application apart, whether it is a function, type constructor, or plain type application. Note that type family applications are NEVER unsaturated by this!

repSplitAppTy_maybe :: Type -> Maybe (Type, Type)Source

Does the AppTy split as in splitAppTy_maybe, but assumes that any Core view stuff is already done

mkFunTy :: Type -> Type -> TypeSource

Creates a function type from the given argument and result type

splitFunTy :: Type -> (Type, Type)Source

Attempts to extract the argument and result types from a type, and panics if that is not possible. See also splitFunTy_maybe

splitFunTy_maybe :: Type -> Maybe (Type, Type)Source

Attempts to extract the argument and result types from a type

splitFunTysN :: Int -> Type -> ([Type], Type)Source

Split off exactly the given number argument types, and panics if that is not possible

funResultTy :: Type -> TypeSource

Extract the function result type and panic if that is not possible

funArgTy :: Type -> TypeSource

Extract the function argument type and panic if that is not possible

zipFunTys :: Outputable a => [a] -> Type -> ([(a, Type)], Type)Source

Splits off argument types from the given type and associating them with the things in the input list from left to right. The final result type is returned, along with the resulting pairs of objects and types, albeit with the list of pairs in reverse order. Panics if there are not enough argument types for the input list.

mkTyConApp :: TyCon -> [Type] -> TypeSource

A key function: builds a TyConApp or FunTy as apppropriate to its arguments. Applies its arguments to the constructor from left to right.

mkTyConTy :: TyCon -> TypeSource

Create the plain type constructor type which has been applied to no type arguments at all.

tyConAppTyCon_maybe :: Type -> Maybe TyConSource

The same as fst . splitTyConApp

tyConAppArgs_maybe :: Type -> Maybe [Type]Source

The same as snd . splitTyConApp

splitTyConApp_maybe :: Type -> Maybe (TyCon, [Type])Source

Attempts to tease a type apart into a type constructor and the application of a number of arguments to that constructor

splitTyConApp :: Type -> (TyCon, [Type])Source

Attempts to tease a type apart into a type constructor and the application of a number of arguments to that constructor. Panics if that is not possible. See also splitTyConApp_maybe

mkForAllTys :: [TyVar] -> Type -> TypeSource

Wraps foralls over the type using the provided TyVars from left to right

splitForAllTy_maybe :: Type -> Maybe (TyVar, Type)Source

Attempts to take a forall type apart, returning the bound type variable and the remainder of the type

splitForAllTys :: Type -> ([TyVar], Type)Source

Attempts to take a forall type apart, returning all the immediate such bound type variables and the remainder of the type. Always suceeds, even if that means returning an empty list of TyVars

mkPiType :: Var -> Type -> TypeSource

Makes a (->) type or a forall type, depending on whether it is given a type variable or a term variable.

mkPiTypes :: [Var] -> Type -> TypeSource

mkPiType for multiple type or value arguments

applyTy :: Type -> KindOrType -> TypeSource

Instantiate a forall type with one or more type arguments. Used when we have a polymorphic function applied to type args:

 f t1 t2

We use applyTys type-of-f [t1,t2] to compute the type of the expression. Panics if no application is possible.

applyTys :: Type -> [KindOrType] -> TypeSource

This function is interesting because:

  1. The function may have more for-alls than there are args
  2. Less obviously, it may have fewer for-alls

For case 2. think of:

 applyTys (forall a.a) [forall b.b, Int]

This really can happen, but only (I think) in situations involving undefined. For example: undefined :: forall a. a Term: undefined (forall b. b->b) Int This term should have type (Int -> Int), but notice that there are more type args than foralls in undefineds type.

dropForAlls :: Type -> TypeSource

Equivalent to snd . splitForAllTys

isNumLitTy :: Type -> Maybe IntegerSource

Is this a numeric literal. We also look through type synonyms.

isStrLitTy :: Type -> Maybe FastStringSource

Is this a symbol literal. We also look through type synonyms.

coAxNthLHS :: CoAxiom br -> Int -> TypeSource

Get the type on the LHS of a coercion induced by a type/data family instance.

newTyConInstRhs :: TyCon -> [Type] -> TypeSource

Unwrap one layer of newtype on a type constructor and its arguments, using an eta-reduced version of the newtype if possible

mkFamilyTyConApp :: TyCon -> [Type] -> TypeSource

Given a family instance TyCon and its arg types, return the corresponding family type. E.g:

 data family T a
 data instance T (Maybe b) = MkT b

Where the instance tycon is :RTL, so:

 mkFamilyTyConApp :RTL Int  =  T (Maybe Int)

mkEqPred :: Type -> Type -> PredTypeSource

Creates a type equality predicate

Common type constructors

Predicates on types

isUnLiftedType :: Type -> BoolSource

See Type for what an unlifted type is

isAlgType :: Type -> BoolSource

See Type for what an algebraic type is. Should only be applied to types, as opposed to e.g. partially saturated type constructors

isClosedAlgType :: Type -> BoolSource

See Type for what an algebraic type is. Should only be applied to types, as opposed to e.g. partially saturated type constructors. Closed type constructors are those with a fixed right hand side, as opposed to e.g. associated types

isPrimitiveType :: Type -> BoolSource

Returns true of types that are opaque to Haskell. Most of these are unlifted, but now that we interact with .NET, we may have primtive (foreign-imported) types that are lifted

isStrictType :: Type -> BoolSource

Computes whether an argument (or let right hand side) should be computed strictly or lazily, based only on its type. Works just like isUnLiftedType, except that it has a special case for dictionaries (i.e. does not work purely on representation types)

Main data types representing Kinds

type Kind = TypeSource

The key type representing kinds in the compiler. Invariant: a kind is always in one of these forms:

 FunTy k1 k2
 TyConApp PrimTyCon [...]
 TyVar kv   -- (during inference only)
 ForAll ... -- (for top-level coercions)

Finding the kind of a type

Common Kinds and SuperKinds

anyKind :: KindSource

See Type for details of the distinction between these Kinds

liftedTypeKind :: KindSource

See Type for details of the distinction between these Kinds

unliftedTypeKind :: KindSource

See Type for details of the distinction between these Kinds

openTypeKind :: KindSource

See Type for details of the distinction between these Kinds

constraintKind :: KindSource

See Type for details of the distinction between these Kinds

superKind :: KindSource

See Type for details of the distinction between these Kinds

Common Kind type constructors

liftedTypeKindTyCon :: TyConSource

See Type for details of the distinction between the Kind TyCons

openTypeKindTyCon :: TyConSource

See Type for details of the distinction between the Kind TyCons

unliftedTypeKindTyCon :: TyConSource

See Type for details of the distinction between the Kind TyCons

constraintKindTyCon :: TyConSource

See Type for details of the distinction between the Kind TyCons

anyKindTyCon :: TyConSource

See Type for details of the distinction between the Kind TyCons

Type free variables

tyVarsOfType :: Type -> VarSetSource

NB: for type synonyms tyVarsOfType does not expand the synonym tyVarsOfType returns only the free variables of a type For example, tyVarsOfType (a::k) returns {a}, not including the kind variable {k}

expandTypeSynonyms :: Type -> TypeSource

Expand out all type synonyms. Actually, it'd suffice to expand out just the ones that discard type variables (e.g. type Funny a = Int) But we don't know which those are currently, so we just expand all.

Type comparison

eqType :: Type -> Type -> BoolSource

Type equality on source types. Does not look through newtypes or PredTypes, but it does look through type synonyms.

Forcing evaluation of types

seqTypes :: [Type] -> ()Source

Other views onto Types

coreView :: Type -> Maybe TypeSource

In Core, we "look through" non-recursive newtypes and PredTypes: this function tries to obtain a different view of the supplied type given this

Strips off the top layer only of a type to give its underlying representation type. Returns Nothing if there is nothing to look through.

By being non-recursive and inlined, this case analysis gets efficiently joined onto the case analysis that the caller is already doing

tcView :: Type -> Maybe TypeSource

Similar to coreView, but for the type checker, which just looks through synonyms

repType :: Type -> RepTypeSource

Looks through:

  1. For-alls 2. Synonyms 3. Predicates 4. All newtypes, including recursive ones, but not newtype families

It's useful in the back end of the compiler.

Type representation for the code generator

typePrimRep :: UnaryType -> PrimRepSource

Discovers the primitive representation of a more abstract UnaryType

Main type substitution data types

type TvSubstEnv = TyVarEnv TypeSource

A substitition of Types for TyVars and Kinds for KindVars

data TvSubst Source

Type substitution

The following invariants must hold of a TvSubst:

  1. The in-scope set is needed only to guide the generation of fresh uniques
  2. In particular, the kind of the type variables in the in-scope set is not relevant
  3. The substition is only applied ONCE! This is because in general such application will not reached a fixed point.

Instances

Manipulating type substitutions

mkOpenTvSubst :: TvSubstEnv -> TvSubstSource

Generates the in-scope set for the TvSubst from the types in the incoming environment, hence open

zipOpenTvSubst :: [TyVar] -> [Type] -> TvSubstSource

Generates the in-scope set for the TvSubst from the types in the incoming environment, hence open

mkTopTvSubst :: [(TyVar, Type)] -> TvSubstSource

Called when doing top-level substitutions. Here we expect that the free vars of the range of the substitution will be empty.

composeTvSubst :: InScopeSet -> TvSubstEnv -> TvSubstEnv -> TvSubstEnvSource

(compose env1 env2)(x) is env1(env2(x)); i.e. apply env2 then env1. It assumes that both are idempotent. Typically, env1 is the refinement to a base substitution env2

Performing substitution on types and kinds

substTy :: TvSubst -> Type -> TypeSource

Substitute within a Type

substTys :: TvSubst -> [Type] -> [Type]Source

Substitute within several Types

substTyWith :: [TyVar] -> [Type] -> Type -> TypeSource

Type substitution making use of an TvSubst that is assumed to be open, see zipOpenTvSubst

substTysWith :: [TyVar] -> [Type] -> [Type] -> [Type]Source

Type substitution making use of an TvSubst that is assumed to be open, see zipOpenTvSubst

deShadowTy :: TyVarSet -> Type -> TypeSource

Remove any nested binders mentioning the TyVars in the TyVarSet

Pretty-printing

pprSourceTyCon :: TyCon -> SDocSource

Pretty prints a TyCon, using the family instance in case of a representation tycon. For example:

 data T [a] = ...

In that case we want to print T [a], where T is the family TyCon

Tidying type related things up for printing

tidyOpenType :: TidyEnv -> Type -> (TidyEnv, Type)Source

Grabs the free type variables, tidies them and then uses tidyType to work over the type itself

tidyTyVarBndrs :: TidyEnv -> [TyVar] -> (TidyEnv, [TyVar])Source

This tidies up a type for printing in an error message, or in an interface file.

It doesn't change the uniques at all, just the print names.

tidyFreeTyVars :: TidyEnv -> TyVarSet -> TidyEnvSource

Add the free TyVars to the env in tidy form, so that we can tidy the type they are free in

tidyOpenTyVar :: TidyEnv -> TyVar -> (TidyEnv, TyVar)Source

Treat a new TyVar as a binder, and give it a fresh tidy name using the environment if one has not already been allocated. See also tidyTyVarBndr

tidyTopType :: Type -> TypeSource

Calls tidyType on a top-level type (i.e. with an empty tidying environment)