Document a law for TH's Lift class
authorRyan Scott <ryan.gl.scott@gmail.com>
Sat, 30 Sep 2017 03:32:41 +0000 (23:32 -0400)
committerBen Gamari <ben@smart-cactus.org>
Sat, 30 Sep 2017 13:30:09 +0000 (09:30 -0400)
Inspired by the discussion in #14296, I've decided to
document a law which is usually in the back of my mind when I'm using
Template Haskell's `Lift` class, but isn't formally stated anywhere.
That is, every `Lift` instance should satisfy (for all `x`):

```lang=haskell
$(lift x) == x
```

Test Plan: Read it

Reviewers: austin, goldfire, bgamari

Subscribers: rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D4050

libraries/template-haskell/Language/Haskell/TH/Syntax.hs

index 419d944..0541a08 100644 (file)
@@ -565,6 +565,9 @@ sequenceQ = sequence
 -- 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@ for all @x@, where @$(...)@
+-- is a Template Haskell splice.
+--
 -- 'Lift' instances can be derived automatically by use of the @-XDeriveLift@
 -- GHC language extension:
 --