Documentation

Plugin is the compiler plugin data type. Try to avoid constructing one of these directly, and just modify some fields of defaultPlugin instead: this is to try and preserve source-code compatibility when we add fields to this.

Nonetheless, this API is preliminary and highly likely to change in the future.

Lift a computation from the IO monad. This allows us to run IO computations in any monadic stack, so long as it supports these kinds of operations (i.e. IO is the base monad for the stack).

Example

import Control.Monad.Trans.State -- from the "transformers" library

printState :: Show s => StateT s IO ()
printState = do
  state <- get
  liftIO $ print state

• Couldn't match type ‘IO’ with ‘StateT s IO’
 Expected type: StateT s IO ()
   Actual type: IO ()

> evalStateT printState "hello"
"hello"

> evalStateT printState 3
3

Use a Data instance to implement a deserialization scheme dual to that of serializeWithData

If the Serialized value contains something of the given type, then use the specified deserializer to return Just that. Otherwise return Nothing.

Put a Typeable value that we are able to actually turn into bytes into a Serialized value ready for deserialization later

The result of successful typechecking. It also contains the parser result.

The result of successful parsing.

The result of successful desugaring (i.e., translation to core). Also contains all the information of a typechecked module.

Convert a typechecked module to Core

Find all the Names that this RdrName could mean, in GHCi

ASSUMES that the module is either in the HomePackageTable or is a package module with an interface on disk. If neither of these is true, then the result will be an error indicating the interface could not be found.

Replace the body of the function with this block to test the hsExprType function in GHC.Tc.Utils.Zonk: putSrcSpanDs loc $ do { core_expr <- dsExpr e ; if debugIsOn && not ( exprType core_expr eqType hsExprType e -- ) then (assertPprPanic "compiler.GHCHsToCoreExpr.hs" 249 ( ppr e + dcolon + ppr (hsExprType e) $$ -- ppr core_expr + dcolon + ppr (exprType core_expr) )) else return ()

Run a DsM action in the context of an existing ModGuts

Run a DsM action inside the TcM monad.

Desugaring monad. See also TcM.

How should we choose which constraints to quantify over?

Command line options gathered from the -PModule.Name:stuff syntax are given to you as this type

Default plugin: does nothing at all, except for marking that safe inference has failed unless -fplugin-trustworthy is passed. For compatibility reason you should base all your plugin definitions on this default value.

Run an IfG (top-level interface monad) computation inside an existing TcRn (typecheck-renaming monad) computation by initializing an IfGblEnv based on TcGblEnv.

Throw out any constraints emitted by the thing_inside

Historical "type-checking monad" (now it's just TcRn).

TcGblEnv describes the top-level of the module at the point at which the typechecker is finished work. It is this structure that is handed on to the desugarer For state that needs to be updated during the typechecking phase and returned at end, use a TcRef (= IORef).

A minimal implementation of a GhcMonad. If you need a custom monad, e.g., to maintain additional state consider wrapping this monad or using GhcT.

Call the argument with the current session.

Locate a module that was imported by the user. We have the module's name, and possibly a package name. Without a package name, this function will use the search path and the known exposed packages to find the module, if a package is specified then only that package is searched for the module.

HscEnv is like Session, except that some of the fields are immutable. An HscEnv is used to compile a single module from plain Haskell source code (after preprocessing) to either C, assembly or C--. It's also used to store the dynamic linker state to allow for multiple linkers in the same address space. Things like the module graph don't change during a single compilation.

Historical note: "hsc" used to be the name of the compiler binary, when there was a separate driver and compiler. To compile a single module, the driver would invoke hsc on the source code... so nowadays we think of hsc as the layer of the compiler that deals with compiling a single module.

Extract a suitable CtOrigin from a HsExpr

A ModGuts is carried through the compiler, accumulating stuff as it goes There is only one ModGuts at any time, the one for the module being compiled right now. Once it is compiled, a ModIface and ModDetails are extracted and the ModGuts is discarded.

Information about other packages that we have slurped in by reading their interface files

Helps us find information about modules in the home package

Information about modules in the package being compiled

A ModIface_ plus a ModDetails summarises everything we know about a compiled module. The ModIface_ is the stuff *before* linking, and can be written out to an interface file. The 'ModDetails is after linking and can be completely recovered from just the ModIface_.

When we read an interface file, we also construct a ModIface_ from it, except that we explicitly make the mi_decls and a few other fields empty; as when reading we consolidate the declarations etc. into a number of indexed maps and environments in the ExternalPackageState.

Data for a module node in a ModuleGraph. Module nodes of the module graph are one of:

• A regular Haskell source module
• A hi-boot source module

Haskell Module

All we actually declare here is the top-level structure for a module.

Bind a list of binding groups over an expression. The leftmost binding group becomes the outermost group in the resulting expression

Create a lambda where the given expression has a number of variables bound over it. The leftmost binder is that bound by the outermost lambda in the result

Construct an expression which represents the application of a number of expressions to that of a data constructor expression. The leftmost expression in the list is applied first

Construct an expression which represents the application of a number of expressions to another. The leftmost expression in the list is applied first Respects the let/app invariant by building a case expression where necessary See Note [Core let/app invariant] in GHC.Core

Convert an LHsType to an LHsSigWcType.

Convert an LHsType to an LHsSigType.

A Haskell Declaration

Signatures and pragmas

Fixity Signature

Located Haskell Type

Haskell Wildcard Binders

Haskell Type

Haskell Type Variable Binder The flag annotates the binder. It is Specificity in places where explicit specificity is allowed (e.g. x :: forall {a} b. ...) or () in other places.

A type signature that obeys the forall-or-nothing rule. In other words, an LHsType that uses an HsOuterSigTyVarBndrs to represent its outermost type variable quantification. See Note [Representing type signatures].

The outermost type variables in a type that obeys the forall-or-nothing rule. See Note [forall-or-nothing rule].

Located Import Declaration

as Module

Module name.

substExpr applies a substitution to an entire CoreExpr. Remember, you may only apply the substitution once: See Note [Substitutions apply only once] in GHC.Core.TyCo.Subst

Do *not* attempt to short-cut in the case of an empty substitution! See Note [Extending the Subst]

Add a substitution for an Id to the Subst: you must ensure that the in-scope set is such that TyCoSubst Note [The substitution invariant] holds after extending the substitution like this

Add a substitution from a CoVar to a Expr to the Subst: you must ensure that the in-scope set satisfies GHC.Core.TyCo.Subst Note [The substitution invariant] after extending the substitution like this

De-shadowing the program is sometimes a useful pre-pass. It can be done simply by running over the bindings with an empty substitution, because substitution returns a result that has no-shadowing guaranteed.

(Actually, within a single type there might still be shadowing, because substTy is a no-op for the empty substitution, but that's probably OK.)

Aug 09

This function is not used in GHC at the moment, but seems so short and simple that I'm going to leave it here

Recover the type of a well-typed Core expression. Fails when applied to the actual Type expression as it cannot really be said to have a type

A type-class instance. Note that there is some tricky laziness at work here. See Note [ClsInst laziness and the rough-match fields] for more details.

Find all locally-defined free Ids or type variables in an expression returning a deterministically ordered list.

Create a user local Id. These are local Ids (see GHC.Types.Var) with a name and location that the user might recognize

Create a local Id that is marked as exported. This prevents things attached to it from being removed as dead code. See Note [Exported LocalIds]

Get from either the worker or the wrapper Id to the DataCon. Currently used only in the desugarer.

INVARIANT: idDataCon (dataConWrapId d) = d: remember, dataConWrapId can return either the wrapper or the worker

Constant applicative form Information

Records whether an Id makes Constant Applicative Form references

Id CAF info

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 GHC.Core.Unfold

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 See Note [Variable occurrences in Core]
• Primitive literals
• Applications: note that the argument may be a Expr. See Note [Core 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.

See Note [Core letrec invariant] See Note [Core let/app invariant] See Note [Levity polymorphism invariants] See Note [Core type and coercion invariant]

• 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 Expr must be that of all the case alternatives

IMPORTANT: see Note [Case expression invariants]

• 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.
• Ticks. These are used to represent all the source annotation we support: profiling SCCs, HPC ticks, and GHCi breakpoints.
• A type: this should only show up at the top level of an Arg
• A coercion