Language.Haskell.TH.Lift

A Lift instance can have any of its values turned into a Template Haskell expression. This is needed when a value used within a Template Haskell quotation is bound outside the Oxford brackets ([| ... |] or [|| ... ||]) but not at the top level. As an example:

add1 :: Int -> Code Q Int
add1 x = [|| x + 1 ||]

Template Haskell has no way of knowing what value x will take on at splice-time, so it requires the type of x to be an instance of Lift.

A Lift instance must satisfy $(lift x) ≡ x and $$(liftTyped x) ≡ x for all x, where $(...) and $$(...) are Template Haskell splices. It is additionally expected that lift x ≡ unTypeCode (liftTyped x).

Lift instances can be derived automatically by use of the -XDeriveLift GHC language extension:

{-# LANGUAGE DeriveLift #-}
module Foo where

import Language.Haskell.TH.Syntax

data Bar a = Bar1 a (Bar a) | Bar2 String
  deriving Lift

Representation-polymorphic since template-haskell-2.16.0.0.

This is exposed both from the template-haskell-lift and template-haskell packages. Consider importing it from the more stable template-haskell-lift if you don't need the full breadth of the template-haskell interface.

In short, Q provides the Quasi operations in one neat monad for the user.

The longer story, is that Q wraps an arbitrary Quasi-able monad. The perceptive reader notices that Quasi has only two instances, Q itself and IO, neither of which have concrete implementations.Q plays the trick of dependency inversion, providing an abstract interface for the user which is later concretely fufilled by an concrete Quasi instance, internal to GHC.

Represents an expression which has type a, built in monadic context m. Built on top of TExp, typed expressions allow for type-safe splicing via:

• typed quotes, written as [|| ... ||] where ... is an expression; if that expression has type a, then the quotation has type Quote m => Code m a

• typed splices inside of typed quotes, written as $$(...) where ... is an arbitrary expression of type Quote m => Code m a

Traditional expression quotes and splices let us construct ill-typed expressions:

>>> fmap ppr $ runQ (unTypeCode [| True == $( [| "foo" |] ) |])GHC.Internal.Types.True GHC.Internal.Classes.== "foo">>> GHC.Internal.Types.True GHC.Internal.Classes.== "foo"<interactive> error:    • Couldn't match expected type ‘Bool’ with actual type ‘[Char]’    • In the second argument of ‘(==)’, namely ‘"foo"’      In the expression: True == "foo"      In an equation for ‘it’: it = True == "foo"

With typed expressions, the type error occurs when constructing the Template Haskell expression:

>>> fmap ppr $ runQ (unTypeCode [|| True == $$( [|| "foo" ||] ) ||])<interactive> error:    • Couldn't match type ‘[Char]’ with ‘Bool’      Expected type: Code Q Bool        Actual type: Code Q [Char]    • In the Template Haskell quotation [|| "foo" ||]      In the expression: [|| "foo" ||]      In the Template Haskell splice $$([|| "foo" ||])

The Quote class implements the minimal interface which is necessary for desugaring quotations.

• The Monad m superclass is needed to stitch together the different AST fragments.

• newName is used when desugaring binding structures such as lambdas to generate fresh names.

Therefore the type of an untyped quotation in GHC is `Quote m => m Exp`

For many years the type of a quotation was fixed to be `Q Exp` but by more precisely specifying the minimal interface it enables the Exp to be extracted purely from the quotation without interacting with Q.

A Haskell expression.

Convert an implementation of lift into one for liftTyped.

A compatibility shim for lifting an Addr# value.

A compatibility shim for lifting an Int value without triggering bugs if RebindableSyntax is used in a module.