Template Haskell is enabled by the -XTemplateHaskell GHC extension. This extension enables all the syntactic features further detailed in this section. The full details on Template Haskell are given by the user guide (opens new window).

Splices

Expression quotations (note: not a QuasiQuotation)

The Q :: * -> * type constructor defined in Language.Haskell.TH.Syntax is an abstract type representing computations which have access to the compile-time environment of the module in which the computation is run. The Q type also handles variable substituion, called name capture by TH (and discussed here (opens new window).) All splices have type Q X for some X.

The compile-time environment includes:

The familiar

curry :: ((a,b) -> c) -> a -> b -> c
curry = \f a b -> f (a,b)

function can be generalized to tuples of arbitrary arity, for example:

curry3 :: ((a, b, c) -> d) -> a -> b -> c -> d
curry4 :: ((a, b, c, d) -> e) -> a -> b -> c -> d -> e 

However, writing such functions for tuples of arity 2 to (e.g.) 20 by hand would be tedious (and ignoring the fact that the presence of 20 tuples in your program almost certainly signal design issues which should be fixed with records).

We can use Template Haskell to produce such curryN functions for arbitrary n:

{-# LANGUAGE TemplateHaskell #-}
import Control.Monad (replicateM) 
import Language.Haskell.TH (ExpQ, newName, Exp(..), Pat(..))
import Numeric.Natural (Natural) 

curryN :: Natural -> Q Exp

The curryN function takes a natural number, and produces the curry function of that arity, as a Haskell AST.

curryN n = do
  f  <- newName "f"
  xs <- replicateM (fromIntegral n) (newName "x")

First we produces fresh type variables for each of the arguments of the function - one for the input function, and one for each of the arguments to said function.

 let args = map VarP (f:xs)

The expression args represents the pattern f x1 x2 .. xn. Note that a pattern is seperate syntactic entity - we could take this same pattern and place it in a lambda, or a function binding, or even the LHS of a let binding (which would be an error).

     ntup = TupE (map VarE xs)

The function must build the argument tuple from the sequence of arguments, which is what we've done here. Note the distinction between pattern variables (VarP) and expression variables (VarE).

 return $ LamE args (AppE (VarE f) ntup)

Finally, the value which we produce is the AST \f x1 x2 .. xn -> f (x1, x2, .. , xn).

We could have also written this function using quotations and 'lifted' constructors:

...
import Language.Haskell.TH.Lib  

curryN' :: Natural -> ExpQ
curryN' n = do
  f  <- newName "f"
  xs <- replicateM (fromIntegral n) (newName "x")
  lamE (map varP (f:xs)) 
        [| $(varE f) $(tupE (map varE xs)) |]

Note that quotations must be syntactically valid, so [| \ $(map varP (f:xs)) -> .. |] is invalid, because there is no way in regular Haskell to declare a 'list' of patterns - the above is interpreted as \ var -> .. and the spliced expression is expected to have type PatQ, i.e. a single pattern, not a list of patterns.

Finally, we can load this TH function in GHCi:

>:set -XTemplateHaskell
>:t $(curryN 5)
$(curryN 5)
  :: ((t1, t2, t3, t4, t5) -> t) -> t1 -> t2 -> t3 -> t4 -> t5 -> t
>$(curryN 5) (\(a,b,c,d,e) -> a+b+c+d+e) 1 2 3 4 5
15

This example is adapted primarily from here (opens new window).

Remarks

What is Template Haskell?

Template Haskell refers to the template meta-programming facilities built into GHC Haskell. The paper describing the original implementation can be found here (opens new window).

What are stages? (Or, what is the stage restriction?)

Stages refer to when code is executed. Normally, code is exectued only at runtime, but with Template Haskell, code can be executed at compile time. "Normal" code is stage 0 and compile-time code is stage 1.

The stage restriction refers to the fact that a stage 0 program may not be executed at stage 1 - this would be equivalent to being able to run any regular program (not just meta-program) at compile time.

By convention (and for the sake of implementation simplicity), code in the current module is always stage 0 and code imported from all other modules is stage 1. For this reason, only expressions from other modules may be spliced.

Note that a stage 1 program is a stage 0 expression of type Q Exp, Q Type, etc; but the converse is not true - not every value (stage 0 program) of type Q Exp is a stage 1 program,

Futhermore, since splices can be nested, identifiers can have stages greater than 1. The stage restriction can then be generalized - a stage n program may not be executed in any stage m>n. For example, one can see references to such stages greater than 1 in certain error messages:

>:t [| \x -> $x |]

<interactive>:1:10: error:
    * Stage error: `x' is bound at stage 2 but used at stage 1
    * In the untyped splice: $x
      In the Template Haskell quotation [| \ x -> $x |]

Using Template Haskell causes not-in-scope errors from unrelated identifiers?

Normally, all the declarations in a single Haskell module can be thought of as all being mutually recursive. In other words, every top-level declaration is in the scope of every other in a single module. When Template Haskell is enabled, the scoping rules change - the module is instead broken into groups of code seperated by TH splices, and each group is mutually recursive, and each group in the scope of all further groups.