Install some default exception handlers and run the inner computation. Unless you want to handle exceptions yourself, you should wrap this around the top level of your program. The default handlers output the error message(s) to stderr and exit cleanly.

Install a default cleanup handler to remove temporary files deposited by a GHC run. This is seperate from defaultErrorHandler, because you might want to override the error handling, but still get the ordinary cleanup behaviour.

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.

A monad transformer to add GHC specific features to another monad.

Note that the wrapped monad must support IO and handling of exceptions.

A monad that has all the features needed by GHC API calls.

In short, a GHC monad

• allows embedding of IO actions,
• can log warnings,
• allows handling of (extensible) exceptions, and
• maintains a current session.

If you do not use Ghc or GhcT, make sure to call initGhcMonad before any call to the GHC API functions can occur.

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--. 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.

Run function for the Ghc monad.

It initialises the GHC session and warnings via initGhcMonad. Each call to this function will create a new session which should not be shared among several threads.

Any errors not handled inside the Ghc action are propagated as IO exceptions.

Run function for GhcT monad transformer.

It initialises the GHC session and warnings via initGhcMonad. Each call to this function will create a new session which should not be shared among several threads.

Initialise a GHC session.

If you implement a custom GhcMonad you must call this function in the monad run function. It will initialise the session variable and clear all warnings.

The first argument should point to the directory where GHC's library files reside. More precisely, this should be the output of ghc --print-libdir of the version of GHC the module using this API is compiled with. For portability, you should use the ghc-paths package, available at http://hackage.haskell.org/cgi-bin/hackage-scripts/package/ghc-paths.

Generalised version of catch, allowing an arbitrary exception handling monad instead of just IO.

Generalised version of bracket, allowing an arbitrary exception handling monad instead of just IO.

Generalised version of finally, allowing an arbitrary exception handling monad instead of just IO.

Print the error message and all warnings. Useful inside exception handlers. Clears warnings after printing.

Perform the given action and call the exception handler if the action throws a SourceError. See SourceError for more information.

Determines whether a set of modules requires Template Haskell.

Note that if the session's DynFlags enabled Template Haskell when depanal was called, then each module in the returned module graph will have Template Haskell enabled whether it is actually needed or not.

Contains not only a collection of DynFlags but also a plethora of information relating to the compilation of a single file or GHC session

Enumerates the simple on-or-off dynamic flags

The target code type of the compilation (if any).

Whenever you change the target, also make sure to set ghcLink to something sensible.

HscNothing can be used to avoid generating any output, however, note that:

• This will not run the desugaring step, thus no warnings generated in this step will be output. In particular, this includes warnings related to pattern matching. You can run the desugarer manually using desugarModule.
• If a program uses Template Haskell the typechecker may try to run code from an imported module. This will fail if no code has been generated for this module. You can use needsTemplateHaskell to detect whether this might be the case and choose to either switch to a different target or avoid typechecking such modules. (The latter may be preferable for security reasons.)

Test whether a DynFlag is set

The GhcMode tells us whether we're doing multi-module compilation (controlled via the GHC API) or one-shot (single-module) compilation. This makes a difference primarily to the Finder: in one-shot mode we look for interface files for imported modules, but in multi-module mode we look for source files in order to check whether they need to be recompiled.

What to do in the link step, if there is one.

The HscTarget value corresponding to the default way to create object files on the current platform.

Grabs the DynFlags from the Session

Updates both the interactive and program DynFlags in a Session. This also reads the package database (unless it has already been read), and prepares the compilers knowledge about packages. It can be called again to load new packages: just add new package flags to (packageFlags dflags).

Returns a list of new packages that may need to be linked in using the dynamic linker (see linkPackages) as a result of new package flags. If you are not doing linking or doing static linking, you can ignore the list of packages returned.

Returns the program DynFlags.

Sets the program DynFlags.

Get the DynFlags used to evaluate interactive expressions.

Set the DynFlags used to evaluate interactive expressions. Note: this cannot be used for changes to packages. Use setSessionDynFlags, or setProgramDynFlags and then copy the pkgState into the interactive DynFlags.

Parses GHC's static flags from a list of command line arguments.

These flags are static in the sense that they can be set only once and they are global, meaning that they affect every instance of GHC running; multiple GHC threads will use the same flags.

This function must be called before any session is started, i.e., before the first call to withGhc.

Static flags are more of a hack and are static for more or less historical reasons. In the long run, most static flags should eventually become dynamic flags.

XXX: can we add an auto-generated list of static flags here?

A compilation target.

A target may be supplied with the actual text of the module. If so, use this instead of the file contents (this is for use in an IDE where the file hasn't been saved by the user yet).

Sets the targets for this session. Each target may be a module name or a filename. The targets correspond to the set of root modules for the program/library. Unloading the current program is achieved by setting the current set of targets to be empty, followed by load.

Returns the current set of targets

Add another target.

Remove a target

Attempts to guess what Target a string refers to. This function implements the --make/GHCi command-line syntax for filenames:

• if the string looks like a Haskell source filename, then interpret it as such
• if adding a .hs or .lhs suffix yields the name of an existing file, then use that
• otherwise interpret the string as a module name

Perform a dependency analysis starting from the current targets and update the session with the new module graph.

Dependency analysis entails parsing the import directives and may therefore require running certain preprocessors.

Note that each ModSummary in the module graph caches its DynFlags. These DynFlags are determined by the current session DynFlags and the OPTIONS and LANGUAGE pragmas of the parsed module. Thus if you want to changes to the DynFlags to take effect you need to call this function again.

Try to load the program. See LoadHowMuch for the different modes.

This function implements the core of GHC's --make mode. It preprocesses, compiles and loads the specified modules, avoiding re-compilation wherever possible. Depending on the target (see hscTarget) compilating and loading may result in files being created on disk.

Calls the reportModuleCompilationResult callback after each compiling each module, whether successful or not.

Throw a SourceError if errors are encountered before the actual compilation starts (e.g., during dependency analysis). All other errors are reported using the callback.

Describes which modules of the module graph need to be loaded.

A function called to log warnings and errors.

Inform GHC that the working directory has changed. GHC will flush its cache of module locations, since it may no longer be valid.

Note: Before changing the working directory make sure all threads running in the same session have stopped. If you change the working directory, you should also unload the current program (set targets to empty, followed by load).

Parse a module.

Throws a SourceError on parse error.

Typecheck and rename a parsed module.

Throws a SourceError if either fails.

Desugar a typechecked module.

Load a module. Input doesn't need to be desugared.

A module must be loaded before dependent modules can be typechecked. This always includes generating a ModIface and, depending on the hscTarget, may also include code generation.

This function will always cause recompilation and will always overwrite previous compilation results (potentially files on disk).

The result of successful parsing.

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

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

A CoreModule consists of just the fields of a ModGuts that are needed for the compileToCoreModule interface.

This is the way to get access to the Core bindings corresponding to a module. compileToCore parses, typechecks, and desugars the module, then returns the resulting Core module (consisting of the module name, type declarations, and function declarations) if successful.

Like compileToCoreModule, but invokes the simplifier, so as to return simplified and tidied Core.

Takes a CoreModule and compiles the bindings therein to object code. The first argument is a bool flag indicating whether to run the simplifier. The resulting .o, .hi, and executable files, if any, are stored in the current directory, and named according to the module name. This has only so far been tested with a single self-contained module.

A ModuleGraph contains all the nodes from the home package (only). There will be a node for each source module, plus a node for each hi-boot module.

The graph is not necessarily stored in topologically-sorted order. Use topSortModuleGraph and flattenSCC to achieve this.

A single node in a 'ModuleGraph. The nodes of the module graph are one of:

• A regular Haskell source module
• A hi-boot source module
• An external-core source module

Where a module lives on the file system: the actual locations of the .hs, .hi and .o files, if we have them

Return the ModSummary of a module with the given name.

The module must be part of the module graph (see hsc_mod_graph and ModuleGraph). If this is not the case, this function will throw a GhcApiError.

This function ignores boot modules and requires that there is only one non-boot module with the given name.

Get the module dependency graph.

Return True == module is loaded.

Topological sort of the module graph

Calculate SCCs of the module graph, possibly dropping the hi-boot nodes The resulting list of strongly-connected-components is in topologically sorted order, starting with the module(s) at the bottom of the dependency graph (ie compile them first) and ending with the ones at the top.

Drop hi-boot nodes (first boolean arg)?

• False: treat the hi-boot summaries as nodes of the graph, so the graph must be acyclic
• True: eliminate the hi-boot nodes, and instead pretend the a source-import of Foo is an import of Foo The resulting graph has no hi-boot nodes, but can be cyclic

Container for information about a Module.

Request information about a loaded Module

The list of top-level entities defined in a module

Returns the instances defined by the specified module. Warning: currently unimplemented for package modules.

Retrieve module safe haskell mode

Looks up a global name: that is, any top-level name in any visible module. Unlike lookupName, lookupGlobalName does not use the interactive context, and therefore does not require a preceding setContext.

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.

The various Safe Haskell modes

Return all external modules available in the package database. Modules from the current session (i.e., from the HomePackageTable) are not included.

Return the bindings for the current interactive session.

Return the instances for the current interactive session.

Takes a ModuleName and possibly a PackageId, and consults the filesystem and package database to find the corresponding Module, using the algorithm that is used for an import declaration.

Like findModule, but differs slightly when the module refers to a source file, and the file has not been loaded via load. In this case, findModule will throw an error (module not loaded), but lookupModule will check to see whether the module can also be found in a package, and if so, that package Module will be returned. If not, the usual module-not-found error will be thrown.

Check that a module is safe to import (according to Safe Haskell).

We return True to indicate the import is safe and False otherwise although in the False case an error may be thrown first.

Return if a module is trusted and the pkgs it depends on to be trusted.

Set the interactive evaluation context.

Setting the context doesn't throw away any bindings; the bindings we've built up in the InteractiveContext simply move to the new module. They always shadow anything in scope in the current context.

Get the interactive evaluation context, consisting of a pair of the set of modules from which we take the full top-level scope, and the set of modules from which we take just the exports respectively.

Returns all names in scope in the current interactive context

get the GlobalRdrEnv for a session

Returns True if the specified module is interpreted, and hence has its full top-level scope available.

Looks up an identifier in the current interactive context (for :info) Filter the instances by the ones whose tycons (or clases resp) are in scope (qualified or otherwise). Otherwise we list a whole lot too many! The exact choice of which ones to show, and which to hide, is a judgement call. (see Trac #1581)

Get the type of an expression

Get the kind of a type

Parses a string as an identifier, and returns the list of Names that the identifier can refer to in the current interactive context.

Run a statement in the current interactive context. Statement may bind multple values.

Run a statement in the current interactive context. Passing debug information Statement may bind multple values.

All the information about the breakpoints for a given module

Breakpoint index

Returns the TyThing for a Name. The Name may refer to any entity known to GHC, including Names defined using runStmt.

EXPERIMENTAL: DO NOT USE.

Set the monad GHCi lifts user statements into.

Checks that a type (in string form) is an instance of the GHC.GHCi.GHCiSandboxIO type class. Sets it to be the GHCi monad if it is, throws an error otherwise.

Essentially just a string identifying a package, including the version: e.g. parsec-1.0

A Module is a pair of a PackageId and a ModuleName.

A ModuleName is essentially a simple string, e.g. Data.List.

A unique, unambigious name for something, containing information about where that thing originated.

print a NamedThing, adding parentheses if the name is an operator.

A class allowing convenient access to the Name of various datatypes

Do not use the data constructors of RdrName directly: prefer the family of functions that creates them, such as mkRdrUnqual

isImplicitId tells whether an Ids info is implied by other declarations, so we don't need to put its signature in an interface file, even if it's mentioned in some other interface unfolding.

isExportedIdVar means "don't throw this away"

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

Returns true if an application to n args would diverge

If the Id is that for a record selector, extract the sel_tycon and label. Panic otherwise

TyCons represent type constructors. Type constructors are introduced by things such as:

1) Data declarations: data Foo = ... creates the Foo type constructor of kind *

2) Type synonyms: type Foo = ... creates the Foo type constructor

3) Newtypes: newtype Foo a = MkFoo ... creates the Foo type constructor of kind * -> *

4) Class declarations: class Foo where creates the Foo type constructor of kind *

This data type also encodes a number of primitive, built in type constructors such as those for function and tuple types.

The kind and type variables used in the type constructor. Invariant: length tyvars = arity Precisely, this list scopes over:

1. The algTcStupidTheta 2. The cached types in 'algTyConRhs.NewTyCon' 3. The family instance types if present

Note that it does not scope over the data constructors.

As tyConDataCons_maybe, but returns the empty list of constructors if no constructors could be found

n if ty_con :: * -> ... -> * n times

Is this TyCon that for a class instance?

Is this a TyCon representing a type synonym (type)?

Is this TyCon that for a newtype

Does this TyCon represent something that cannot be defined in Haskell?

Is this a TyCon, synonym or otherwise, that may have further instances appear?

If this TyCon is that for a class instance, return the class it is for. Otherwise returns Nothing

Extract the TyVars bound by a type synonym and the corresponding (unsubstituted) right hand side. If the given TyCon is not a type synonym, panics

Find the expansion of the type synonym represented by the given TyCon. The free variables of this type will typically include those TyVars bound by the TyCon. Panics if the TyCon is not that of a type synonym

Find the result Kind of a type synonym, after applying it to its arity number of type variables Actually this function works fine on data types too, but they'd always return *, so we never need to ask

A data constructor

The "signature" of the DataCon returns, in order:

1) The result of dataConAllTyVars,

2) All the ThetaTypes relating to the DataCon (coercion, dictionary, implicit parameter - whatever)

3) The type arguments to the constructor

4) The original result type of the DataCon

The type constructor that we are building via this data constructor

The labels for the fields of this particular DataCon

Should the DataCon be presented infix?

Vanilla DataCons are those that are nice boring Haskell 98 constructors

The user-declared type of the data constructor in the nice-to-read form:

 T :: forall a b. a -> b -> T [a]

rather than:

 T :: forall a c. forall b. (c~[a]) => a -> b -> T c

NB: If the constructor is part of a data instance, the result type mentions the family tycon, not the internal one.

The strictness markings decided on by the compiler. Does not include those for existential dictionaries. The list is in one-to-one correspondence with the arity of the DataCon

The key representation of types within the compiler

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

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

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)

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"

A collection of PredTypes

A typecheckable-thing, essentially anything that has a name

Represents a single point within a file

Built-in bad SrcLoc values for particular locations

Gives the filename of the RealSrcLoc

Raises an error when used on a bad SrcLoc

Raises an error when used on a bad SrcLoc

A SrcSpan delimits a portion of a text file. It could be represented by a pair of (line,column) coordinates, but in fact we optimise slightly by using more compact representations for single-line and zero-length spans, both of which are quite common.

The end position is defined to be the column after the end of the span. That is, a span of (1,1)-(1,2) is one character long, and a span of (1,1)-(1,1) is zero characters long.

Create a SrcSpan between two points in a file

Create a SrcSpan corresponding to a single point

Test if a SrcSpan is good, i.e. has precise location information

Built-in bad SrcSpans for common sources of location uncertainty

Returns the location at the start of the SrcSpan or a bad SrcSpan if that is unavailable

Returns the location at the end of the SrcSpan or a bad SrcSpan if that is unavailable

We attach SrcSpans to lots of things, so let's have a datatype for it.

Tests whether the two located things are equal

Tests the ordering of the two located things

Combine locations from two Located things and add them to a third thing

Alternative strategies for ordering SrcSpans

Alternative strategies for ordering SrcSpans

Alternative strategies for ordering SrcSpans

Determines whether a span encloses a given line and column index

Determines whether a span is enclosed by another one

GHC's own exception type error messages all take the form:

      location: error

If the location is on the command line, or in GHC itself, then location=ghc. All of the error types below correspond to a location of ghc, except for ProgramError (where the string is assumed to contain a location already, so we don't print one).