This is the data type that represents GHCs core intermediate language. Currently GHC uses System FC https://www.microsoft.com/en-us/research/publication/system-f-with-type-equality-coercions/ for this purpose, which is closely related to the simpler and better known System F http://en.wikipedia.org/wiki/System_F.

We get from Haskell source to this Core language in a number of stages:

1. The source code is parsed into an abstract syntax tree, which is represented by the data type HsExpr with the names being RdrNames
2. This syntax tree is renamed, which attaches a Unique to every RdrName (yielding a Name) to disambiguate identifiers which are lexically identical. For example, this program:

     f x = let f x = x + 1
           in f (x - 2)

Would be renamed by having Uniques attached so it looked something like this:

     f_1 x_2 = let f_3 x_4 = x_4 + 1
               in f_3 (x_2 - 2)

But see Note [Shadowing] below.

1. The resulting syntax tree undergoes type checking (which also deals with instantiating type class arguments) to yield a HsExpr type that has Id as it's names.
2. Finally the syntax tree is desugared from the expressive HsExpr type into this Expr type, which has far fewer constructors and hence is easier to perform optimization, analysis and code generation on.

The type parameter b is for the type of binders in the expression tree.

The language consists of the following elements:

• Variables
• Primitive literals
• Applications: note that the argument may be a Type. See Note [CoreSyn let/app invariant] See Note [Levity polymorphism invariants]
• Lambda abstraction See Note [Levity polymorphism invariants]
• Recursive and non recursive lets. Operationally this corresponds to allocating a thunk for the things bound and then executing the sub-expression.

The right hand sides of all top-level and recursive lets must be of lifted type (see Type for the meaning of lifted vs. unlifted). There is one exception to this rule, top-level lets are allowed to bind primitive string literals, see Note [CoreSyn top-level string literals].

See Note [CoreSyn let/app invariant] See Note [Levity polymorphism invariants]

We allow a non-recursive let to bind a type variable, thus:

Let (NonRec tv (Type ty)) body

This can be very convenient for postponing type substitutions until the next run of the simplifier.

At the moment, the rest of the compiler only deals with type-let in a Let expression, rather than at top level. We may want to revist this choice.

• Case expression. Operationally this corresponds to evaluating the scrutinee (expression examined) to weak head normal form and then examining at most one level of resulting constructor (i.e. you cannot do nested pattern matching directly with this).

The binder gets bound to the value of the scrutinee, and the Type must be that of all the case alternatives

This is one of the more complicated elements of the Core language, and comes with a number of restrictions:

1. The list of alternatives may be empty; See Note [Empty case alternatives]
2. The DEFAULT case alternative must be first in the list, if it occurs at all.
3. The remaining cases are in order of increasing tag (for DataAlts) or lit (for LitAlts). This makes finding the relevant constructor easy, and makes comparison easier too.
4. The list of alternatives must be exhaustive. An exhaustive case does not necessarily mention all constructors:

           data Foo = Red | Green | Blue
      ... case x of
           Red   -> True
           other -> f (case x of
                           Green -> ...
                           Blue  -> ... ) ...
      

The inner case does not need a Red alternative, because x can't be Red at that program point.

1. Floating-point values must not be scrutinised against literals. See Trac #9238 and Note [Rules for floating-point comparisons] in PrelRules for rationale.

• Cast an expression to a particular type. This is used to implement newtypes (a newtype constructor or destructor just becomes a Cast in Core) and GADTs.
• Notes. These allow general information to be added to expressions in the syntax tree
• A type: this should only show up at the top level of an Arg
• A coercion

A case split alternative. Consists of the constructor leading to the alternative, the variables bound from the constructor, and the expression to be executed given that binding. The default alternative is (DEFAULT, [], rhs)

Binding, used for top level bindings in a module and local bindings in a let.

A case alternative constructor (i.e. pattern match)

Type synonym for expressions that occur in function argument positions. Only Arg should contain a Type at top level, general Expr should not

Allows attaching extra information to points in expressions

Specifies the scoping behaviour of ticks. This governs the behaviour of ticks that care about the covered code and the cost associated with it. Important for ticks relating to profiling.

Governs the kind of expression that the tick gets placed on when annotating for example using mkTick. If we find that we want to put a tickish on an expression ruled out here, we try to float it inwards until we find a suitable expression.

Expressions where binders are CoreBndrs

Case alternatives where binders are CoreBndrs

Binding groups where binders are CoreBndrs

Argument expressions where binders are CoreBndrs

The common case for the type of binders and variables when we are manipulating the Core language within GHC

Binders are tagged with a t

Bind all supplied binding groups over an expression in a nested let expression. Assumes that the rhs satisfies the let/app invariant. Prefer to use mkCoreLets if possible, which does guarantee the invariant

Bind all supplied binders over an expression in a nested lambda expression. Prefer to use mkCoreLams if possible

Apply a list of argument expressions to a function expression in a nested fashion. Prefer to use mkCoreApps if possible

Apply a list of type argument expressions to a function expression in a nested fashion

Apply a list of coercion argument expressions to a function expression in a nested fashion

Apply a list of type or value variables to a function expression in a nested fashion

Create a machine integer literal expression of type Int# from an Integer. If you want an expression of type Int use mkIntExpr

Create a machine integer literal expression of type Int# from an Int. If you want an expression of type Int use mkIntExpr

Create a machine word literal expression of type Word# from an Integer. If you want an expression of type Word use mkWordExpr

Create a machine word literal expression of type Word# from a Word. If you want an expression of type Word use mkWordExpr

Create a machine character literal expression of type Char#. If you want an expression of type Char use mkCharExpr

Create a machine string literal expression of type Addr#. If you want an expression of type String use mkStringExpr

Create a machine single precision literal expression of type Float# from a Rational. If you want an expression of type Float use mkFloatExpr

Create a machine single precision literal expression of type Float# from a Float. If you want an expression of type Float use mkFloatExpr

Create a machine double precision literal expression of type Double# from a Rational. If you want an expression of type Double use mkDoubleExpr

Create a machine double precision literal expression of type Double# from a Double. If you want an expression of type Double use mkDoubleExpr

Apply a list of argument expressions to a data constructor in a nested fashion. Prefer to use mkCoreConApps if possible

Create a binding group where a type variable is bound to a type. Per CoreSyn, this can only be used to bind something in a non-recursive let expression

Create a binding group where a type variable is bound to a type. Per CoreSyn, this can only be used to bind something in a non-recursive let expression

Convert a binder into either a Var or Type Expr appropriately

Compares AltCons within a single list of alternatives

Extract every variable by this group

bindersOf applied to a list of binding groups

We often want to strip off leading lambdas before getting down to business. Variants are collectTyBinders, collectValBinders, and collectTyAndValBinders

Strip off exactly N leading lambdas (type or value). Good for use with join points.

Takes a nested application expression and returns the the function being applied and the arguments to which it is applied

Like collectArgs, but also collects looks through floatable ticks if it means that we can find more arguments.

Collapse all the bindings in the supplied groups into a single list of lhs/rhs pairs suitable for binding in a Rec binding group

If the expression is a Type, converts. Otherwise, panics. NB: This does not convert Coercion to CoercionTy.

If the expression is a Coercion, converts.

Determines the type resulting from applying an expression with given type to a given argument expression

Returns True for value arguments, false for type args NB: coercions are value arguments (zero width, to be sure, like State#, but still value args).

Returns True iff the expression is a Type expression at its top level. Note this does NOT include Coercions.

Returns True iff the expression is a Type or Coercion expression at its top level

The number of argument expressions that are values rather than types at their top level

The number of binders that bind values rather than types

Will this argument expression exist at runtime?

Will this variable exist at runtime?

A "counting tick" (where tickishCounts is True) is one that counts evaluations in some way. We cannot discard a counting tick, and the compiler should preserve the number of counting ticks as far as possible.

However, we still allow the simplifier to increase or decrease sharing, so in practice the actual number of ticks may vary, except that we never change the value from zero to non-zero or vice versa.

Returns the intended scoping rule for a Tickish

Returns whether the tick scoping rule is at least as permissive as the given scoping rule.

Returns True for ticks that can be floated upwards easily even where it might change execution counts, such as:

Just (tick... foo) ==> tick... (Just foo)

This is a combination of tickishSoftScope and tickishCounts. Note that in principle splittable ticks can become floatable using mkNoTick -- even though there's currently no tickish for which that is the case.

Returns True for a tick that is both counting and scoping and can be split into its (tick, scope) parts using mkNoScope and mkNoTick respectively.

Return True if this source annotation compiles to some backend code. Without this flag, the tickish is seen as a simple annotation that does not have any associated evaluation code.

What this means that we are allowed to disregard the tick if doing so means that we can skip generating any code in the first place. A typical example is top-level bindings:

foo = tick... y -> ... ==> foo = y -> tick... ...

Here there is just no operational difference between the first and the second version. Therefore code generation should simply translate the code as if it found the latter.

Placement behaviour we want for the ticks

Returns whether one tick "contains" the other one, therefore making the second tick redundant.

Records the unfolding of an identifier, which is approximately the form the identifier would have if we substituted its definition in for the identifier. This type should be treated as abstract everywhere except in CoreUnfold

UnfoldingGuidance says when unfolding should take place

There is no known Unfolding

There is no known Unfolding, because this came from an hi-boot file.

This unfolding marks the associated thing as being evaluated

Retrieves the template of an unfolding: panics if none is known

Retrieves the template of an unfolding if possible maybeUnfoldingTemplate is used mainly wnen specialising, and we do want to specialise DFuns, so it's important to return a template for DFunUnfoldings

The constructors that the unfolding could never be: returns [] if no information is available

Determines if it is certainly the case that the unfolding will yield a value (something in HNF): returns False if unsure

Determines if it possibly the case that the unfolding will yield a value. Unlike isValueUnfolding it returns True for OtherCon

Is the thing we will unfold into certainly cheap?

True if the unfolding is a constructor application, the application of a CONLIKE function or OtherCon

Only returns False if there is no unfolding information available at all

Annotated core: allows annotation at every node in the tree

A clone of the Expr type but allowing annotation at every tree node

A clone of the Bind type but allowing annotation at every tree node

A clone of the Alt type but allowing annotation at every tree node

Takes a nested application expression and returns the the function being applied and the arguments to which it is applied

As collectBinders but for AnnExpr rather than Expr

As collectNBinders but for AnnExpr rather than Expr

Is this instance an orphan? If it is not an orphan, contains an OccName witnessing the instance's non-orphanhood. See Note [Orphans]

Returns true if IsOrphan is orphan.

Returns true if IsOrphan is not an orphan.

A CoreRule is:

• "Local" if the function it is a rule for is defined in the same module as the rule itself.
• "Orphan" if nothing on the LHS is defined in the same module as the rule itself

Gathers a collection of CoreRules. Maps (the name of) an Id to its rules

A full rule environment which we can apply rules from. Like a RuleBase, but it also includes the set of visible orphans we use to filter out orphan rules which are not visible (even though we can see them...)

The number of arguments the ru_fn must be applied to before the rule can match on it

The Name of the Id at the head of the rule left hand side

Set the Name of the Id at the head of the rule left hand side