th-compat: Backward- (and forward-)compatible Quote and Code types

[ bsd3, library, text ] [ Propose Tags ]

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.


[Skip to Readme]
Versions [RSS] [faq] 0.1, 0.1.1, 0.1.2, 0.1.3
Change log CHANGELOG.md
Dependencies base (>=4.3 && <5), fail (==4.9.*), template-haskell (>=2.5 && <2.19), transformers (>=0.2 && <0.6) [details]
License BSD-3-Clause
Copyright (C) 2020 Ryan Scott
Author Ryan Scott
Maintainer Ryan Scott <ryan.gl.scott@gmail.com>
Category Text
Home page https://github.com/haskell-compat/th-compat
Bug tracker https://github.com/haskell-compat/th-compat/issues
Source repo head: git clone https://github.com/haskell-compat/th-compat
Uploaded by ryanglscott at 2021-08-29T23:34:57Z
Distributions Arch:0.1.2, Fedora:0.1.2, LTSHaskell:0.1.3, NixOS:0.1.3, Stackage:0.1.3
Downloads 14327 total (1686 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2021-08-29 [all 1 reports]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Candidates


Readme for th-compat-0.1.3

[back to package description]

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.