UHC.Light.Compiler.Core.API

Core Public API (provisional)

Intended for constructing basic Core Programs. Use the binary serialization from Binary to produce a core file, which can be compiled by UHC. You will need to install the full UHC Compiler Suite in addition to uhc-light for this. See https://github.com/UU-ComputerScience/uhc for more details.

A small example program can be found at https://github.com/UU-ComputerScience/uhc/tree/master/EHC/demo/CoreApi/ . In general, it is also a good idea to see what kind of Core UHC generates for Haskell files. To do this, call UHC with the option --coreopt=dump. This will produce an additional XXX.tcr file which you can read in any text editor. It may also be a good idea to add the NoGenericDeriving pragma to your haskell files, as this will make the produced Core code much smaller.

Restrictions:

• Extendable data types are not supported
• Generated code is not (type-)checked, might cause runtime crashes
• Core parsing/Pretty printing is incomplete and might be partially broken. The pretty printing should work good enough for dumping generated core code as debug output.
• Calling Haskell functions which use the haskell class system is not (yet?) supported.
• Avoiding name clashes is the responsibility of the user. The behaviour if duplicate names exists is undefined.

TODO:

• Should we add PatRest_Var? Does it actually work? (The HS frontend doesn't seem to use it?)
• Float, Double literals

Core AST

The datatypes making up a Core program.

data CModule

Instances

Data CModule

Serialize CModule

Typeable * CModule

data CImport

Instances

Eq CImport

Data CImport

Ord CImport

Serialize CImport

Typeable * CImport

data CExport

Instances

Eq CExport

Data CExport

Ord CExport

Serialize CExport

Typeable * CExport

data CDeclMeta

Instances

Data CDeclMeta

Serialize CDeclMeta

Typeable * CDeclMeta

data CDataCon

Instances

Data CDataCon

Serialize CDataCon

Typeable * CDataCon

data CExpr

Instances

Eq CExpr

Data CExpr

Show CExpr

Explicit dummy instances instead of derived ones which not really are used except as context for PP

Serialize CExpr

PP CExpr

Typeable * CExpr

data CBind

Instances

Eq CBind

Data CBind

Serialize CBind

Typeable * CBind

data CAlt

Instances

Eq CAlt

Data CAlt

Serialize CAlt

Typeable * CAlt

data CPat

Instances

Eq CPat

Data CPat

Serialize CPat

Typeable * CPat

data CPatFld

Instances

Eq CPatFld

Data CPatFld

Serialize CPatFld

Typeable * CPatFld

Construction functions

Constants

mkUnit :: EHCOpts -> CExpr

Creates the unit expresssion.

mkInt :: EHCOpts -> Int -> CExpr

Creates an Int constant.

mkInteger

Arguments

:: EHCOpts

-> Integer

The integer.

-> CExpr

Creates a Core Integer constant.

mkChar :: Char -> CExpr

Creates a char constant.

mkString

Arguments

:: EHCOpts

-> String

The string.

-> CExpr

Creates a string expression. The expression represents a packed String, which can be passed to Haskell generated Core functions.

mkError

Arguments

:: EHCOpts

-> String

The error message.

-> CExpr

Generates an error expression, failing with the given string when evaluated. (error in haskell)

mkUndefined :: EHCOpts -> CExpr

Generates an undefined expression, failing when evaluated. (undefined in haskell)

Variables

mkVar :: HsName -> CExpr

Creates a variable expression.

Let Bindings

mkLet1Plain

Arguments

:: HsName

The identifier.

-> CExpr

The expression to bind.

-> CExpr

The body.

-> CExpr

Creates a (non-recursive) let binding.

mkLet1Strict

Arguments

:: HsName

The identifer.

-> CExpr

The expression to bind. Will be evaluated to WHNF, before the body is evaluated.

-> CExpr

The body.

-> CExpr

Creates a let binding, which is strict in the bound expression.

mkLetRec

Arguments

:: [CBind]

The bindings.

-> CExpr

The body.

-> CExpr

Creates a let binding, where the bindings may be mutually recursive.

Abstraction

mkLam :: [HsName] -> CExpr -> CExpr

Application

mkApp

Arguments

:: CExpr

The lambda to apply.

-> [CExpr]

The arguments (the empty list is allowed).

-> CExpr

Applies the first expression to all given arguments.

Binds/Bounds

mkBind1 :: HsName -> CExpr -> CBind

mkBind1Nm1 :: HsName -> CBind

Constructor tags

mkCTag

Arguments

:: HsName

Fully qualified Datatype name.

-> HsName

Fully qualified Constructor name.

-> Int

Tag number.

-> Int

Arity.

-> CTag

Creates a constructor tag.

destructCTag

Arguments

:: a

Algebra for record/tuple case.

-> (HsName -> HsName -> Int -> Int -> a)

Algebra for datatype case. Order of arguments is the same as in makeCTag.

-> CTag

-> a

Destruct a CTag.

ctagUnit :: CTag

CTag for unit values ('()' in haskell).

ctagTup :: CTag

CTag of tuple/records.

ctagTrue :: EHCOpts -> CTag

ctagFalse :: EHCOpts -> CTag

ctagCons :: EHCOpts -> CTag

ctagNil :: EHCOpts -> CTag

Case

Scrutinizes an expression and executes the appropriate alternative. The scrutinee of a case statement is required to be in WHNF (weak head normal form).

mkCase

Arguments

:: CExpr

The scrutinee. Required to be in WHNF.

-> [CAlt]

The alternatives.

-> CExpr

A Case expression. The alternatives must be exhaustive, they must cover all possible constructors.

mkAlt

Arguments

:: CPat

The pattern with which to match the case scrutinee.

-> CExpr

The value of this alternative.

-> CAlt

Creates an alternative of a case statement.

mkPatCon

Arguments

:: CTag

The constructor to match.

-> CPatRest

???

-> [CPatFld]

???

-> CPat

Matches the case scrutinee with the given constructor tag.

mkPatRestEmpty :: CPatRest

The whole case scrutinee has already been matched on. There is nothing left. (If there is still something left, runtime behaviour is undefined)

mkPatFldBind

Arguments

:: (HsName, CExpr)

lbl, offset ???

-> CBind

??

-> CPatFld

TODO ??? pat field

Datatypes

mkTagTup :: CTag -> [CExpr] -> CExpr

Creates a new tuple/record with the given values. Has to be fully applied, partial application is not allowed.

Module

mkModule

Arguments

:: HsName

The name of the module.

-> [CExport]

The exports.

-> [CImport]

The imports (only direct imports, not transitive ones).

-> [CDeclMeta]

The meta information.

-> CExpr

The body of the module.

-> CModule

Creates a module.

mkImport

Arguments

:: HsName

The module to import.

-> CImport

Creates an import.

mkExport :: HsName -> CExport

Create a plain export. Exported names are unqualified, implicitly qualified by module name.

mkExportData

Arguments

:: HsName

type name

-> Maybe [HsName]

constructor names, if Nothing then all are exported

-> CExport

Create an export for data. Exported names are unqualified, implicitly qualified by module name. Constructor name exports may not overlap with plain exported names.

mkMetaData

Arguments

:: HsName

The name of the dataype.

-> [CDataCon]

The constructors of the dataype.

-> CDeclMeta

Creates the metadata for one datatype.

mkMetaDataCon

Arguments

:: HsName

The fully qualified name of the constructor.

-> Int

The tag of this constructor.

-> Int

The arity of this constructor.

-> CDataCon

Creates the metadata for one constructor.

mkMetaDataConFromCTag

Arguments

:: CTag

CTag to export.

-> Maybe CDataCon

The constructor description. Nothing if it is a record/tuple constructor.

Utilities

mkMain

Arguments

:: HsName

The function containing the user code to call.

-> CExpr

Creates the main entry point, calling the given function when run. The given function to call has to be in scope (either define it in the same module, or import it). In addition, the module UHC.Run has to be imported!

parseExpr :: EHCOpts -> String -> Either [String] CExpr

Parses an expression. The parser is not complete and may fail for complicated core code. For small fragments it should work.

printModule :: EHCOpts -> CModule -> PP_Doc

Re-exports (or not???)

module UHC.Light.Compiler.Base.API