th-compat

Backward- (and forward-)compatible Quote and Code types

https://github.com/haskell-compat/th-compat

Version on this page:0.1.4@rev:2
LTS Haskell 22.37:0.1.5@rev:2
Stackage Nightly 2024-10-06:0.1.5@rev:2
Latest on Hackage:0.1.5@rev:2

See all snapshots th-compat appears in

BSD-3-Clause licensed by Ryan Scott
Maintained by Ryan Scott
This version can be pinned in stack with:th-compat-0.1.4@sha256:e5ae7c083ef3a22248558f8451669bb1c55ea8090f5908b86b9033743c161730,3224

Module documentation for 0.1.4

th-compat

Hackage Hackage Dependencies Haskell Programming Language BSD3 License Build Status

This package defines a Language.Haskell.TH.Syntax.Compat module, which backports the Quote and Code types to work across a wide range of template-haskell versions. On recent versions of template-haskell (2.17.0.0 or later), this module simply reexports Quote and Code from Language.Haskell.TH.Syntax. Refer to the Haddocks for Language.Haskell.TH.Syntax.Compat for examples of how to use this module.

Quick Start Guide

Let’s say you have a library that offers a foo :: Q (TExp a), you want to make it compatible with the new Code type, and you intend that foo is spliced directly in to user code.

Use SpliceQ as a type alias for the return of your function. This is Q (TExp a) prior to GHC 9, and Code Q a after. This allows your code to be spliced in regardless of GHC version.

Use liftSplice to convert a m (TExp a) into a Splice m a.

Use examineSplice before typed quoters. This will allow a typed quasiquotation to work regardless of GHC version.

When splicing in a TExp a value into a typed quoter, use expToSplice.

For a real life example, consider this conversion, from this PR:

discoverInstances
    :: forall c. (Typeable c)
    => Q (TExp [SomeDict c])
discoverInstances = do
    let className = show (typeRep (Proxy @c))
    instanceDecs <- reifyInstances (mkName className) [VarT (mkName "a")]

    dicts <- fmap listTE $ traverse decToDict instanceDecs

    [|| concat $$(pure dicts) ||]

listTE :: [TExp a] -> TExp [a]
listTE = TExp . ListE . map unType

decToDict :: InstanceDec -> Q (TExp [SomeDict c])

With GHC 9, this will have the following problems:

  1. reifyInstances operates in Q, not Code, so it will not type check with the [|| concat $$(pure dicts) ||] line.
  2. We cannot call pure in Code, since Code is not an applicative.
  3. Typed quasiquotes return a Quote m => Code m a, not Q (TExp a).

To fix these problems, we make the following diff:

 discoverInstances
     :: forall c. (Typeable c)
-    => Q (TExp [SomeDict c])
+    => SpliceQ [SomeDict c]
- discoverInstances = do
+ discoverInstances = liftSplice $ do
     let className = show (typeRep (Proxy @c))
     instanceDecs <- reifyInstances (mkName className) [VarT (mkName "a")]

     dicts <- fmap listTE $ traverse decToDict instanceDecs

-     [|| concat $$(pure dicts) ||]
+     examineSplice [|| concat $$(expToSplice dicts) ||]

The above pattern should work to ensure that code is compatible across a wide range of GHC versions.

Changes

0.1.4 [2022.07.23]

  • Backport the getPackageRoot and makeRelativeToProject functions introduced in template-haskell-2.19.0.0 (GHC 9.4).
  • Implement qGetPackageRoot in the Quasi instance for QuoteToQuasi when building with template-haskell-2.19.0.0 (GHC 9.4) or later.

0.1.3 [2021.08.29]

  • Implement qGetDoc and qPutDoc in the Quasi instance for QuoteToQuasi.
  • Add expToSplice.

0.1.2 [2021.03.12]

  • Add bindSplice, bindSplice_, examineSplice, joinSplice, hoistSplice, liftSplice, and unTypeSplice to Language.Haskell.TH.Syntax.Compat.

0.1.1 [2021.02.07]

  • Mark Language.Haskell.TH.Syntax.Compat as Trustworthy.

0.1 [2020.09.29]

  • Initial release