Changelog for the `singletons-th` project
=========================================
3.2 [2023.03.12]
----------------
* Require building with GHC 9.6.
* Derived `POrd` and `SOrd` instances (arising from a use of `deriving Ord`)
now use `(<>) @Ordering` in their implementations instead of the custom
`thenCmp :: Ordering -> Ordering -> Ordering` function. While most code will
likely continue to work after this change, this may break code that attempts
to prove properties about the implementation of a derived `POrd`/`SOrd`
instance.
* Fix a bug in which the `singDecideInstances` and `showSingInstances`, as well
as `deriving Show` declarations, would not respect custom
`promotedDataTypeOrConName` options.
* Allow building with `mtl-2.3.*`.
3.1.1 [2022.08.23]
------------------
* Require building with GHC 9.4.
* Improve error messages when attempting to promote a partial application of
a function arrow `(->)`, which is not currently supported.
3.1 [2021.10.30]
----------------
* Require building with GHC 9.2.
* Allow promoting and singling type applications in data constructor patterns.
* Make the Template Haskell machinery generate `SingI1` and `SingI2` instances
when possible.
* Make `genDefunSymbols` and related functions less likely to trigger
[GHC#19743](https://gitlab.haskell.org/ghc/ghc/-/issues/19743).
3.0 [2021.03.12]
----------------
* The `singletons` library has been split into three libraries:
* The new `singletons` library is now a minimal library that only provides
`Data.Singletons`, `Data.Singletons.Decide`, `Data.Singletons.Sigma`, and
`Data.Singletons.ShowSing` (if compiled with GHC 8.6 or later).
`singletons` now supports building GHCs back to GHC 8.0, as well as GHCJS.
* The `singletons-th` library defines Template Haskell functionality for
promoting and singling term-level definitions, but but nothing else. This
library continues to require the latest stable release of GHC.
* The `singletons-base` library defines promoted and singled versions of
definitions from the `base` library, including the `Prelude`. This library
continues to require the latest stable release of GHC.
Consult the changelogs for `singletons` and `singletons-base` for changes
specific to those libraries. For more information on this split, see the
[relevant GitHub discussion](https://github.com/goldfirere/singletons/issues/420).
* Require building with GHC 9.0.
* `Data.Singletons.CustomStar` and `Data.Singletons.SuppressUnusedWarnings`
have been renamed to `Data.Singletons.TH.CustomStar` and
`Data.Singletons.SuppressUnusedWarnings`, respectively, to give every module
in `singletons-th` a consistent module prefix.
* Due to the `singletons` package split, the `singletons-th` modules
`Data.Singletons.TH` and `Data.Singletons.TH.CustomStar` (formerly known as
`Data.Singletons.CustomStar`) no longer re-export any definitions from the
`singletons-base` module `Prelude.Singletons` (formerly known as
`Data.Singletons.Prelude`). The `singletons-base` library now provides
versions of these modules—`Data.Singletons.Base.CustomStar` and
`Data.Singletons.Base.TH`, respectively—that do re-export definitions
from `Prelude.Singletons`.
* "Fully saturated" defunctionalization symbols (e.g., `IdSym1`) are now
defined as type families instead of type synonyms. This has two notable
benefits:
* Fully saturated defunctionalization symbols can now be given standalone
kind signatures, which ensures that the order of kind variables is the
same as the user originally declared them.
* This fixes a minor regression in `singletons-2.7` in which the quality
of `:kind!` output in GHCi would become worse when using promoted type
families generated by Template Haskell.
Under certain circumstances, this can be a breaking change:
* Since more TH-generated promoted functions now have type families on
their right-hand sides, some programs will now require
`UndecidableInstances` where they didn't before.
* Certain definitions that made use of overlapping patterns, such as
`natMinus` below, will no longer typecheck:
```hs
$(singletons [d|
data Nat = Z | S Nat
natMinus :: Nat -> Nat -> Nat
natMinus Z _ = Z
natMinus (S a) (S b) = natMinus a b
natMinus a Z = a
|])
```
This can be worked around by avoiding the use of overlapping patterns.
In the case of `natMinus`, this amounts to changing the third equation
to match on its first argument:
```hs
$(singletons [d|
natMinus :: Nat -> Nat -> Nat
natMinus Z _ = Z
natMinus (S a) (S b) = natMinus a b
natMinus a@(S _) Z = a
|])
```
* The specification for how `singletons` deals with record selectors has been
simplified. Previously, `singletons` would try to avoid promoting so-called
"naughty" selectors (those whose types mention existential type variables
that do not appear in the constructor's return type) to top-level functions.
Determing if a selector is naughty is quite challenging in practice, as
determining if a type variable is existential or not in the context of
Template Haskell is difficult in the general case. As a result, `singletons`
now adopts the dumb-but-predictable approach of always promoting record
selectors to top-level functions, naughty or not.
This means that attempting to promote code with a naughty record selector,
like in the example below, will no longer work:
```hs
$(promote [d|
data Some :: (Type -> Type) -> Type where
MkSome :: { getSome :: f a } -> Some f
-- getSome is naughty due to mentioning the type variable `a`
|])
```
Please open an issue if you find this restriction burdensome in practice.
* The `singEqInstanceOnly` and `singEqInstancesOnly` functions, which generate
`SEq` (but not `PEq`) instances, have been removed. There is not much point
in keeping these functions around now that `PEq` now longer has a special
default implementation. Use `singEqInstance{s}` instead.
* The Template Haskell machinery will no longer promote `TypeRep` to `Type`,
as this special case never worked properly in the first place.
* The Template Haskell machinery will now preserve strict fields in data types
when generating their singled counterparts.
* Introduce a new `promotedDataTypeOrConName` option to
`Data.Singletons.TH.Options`. Overriding this option can be useful in
situations where one wishes to promote types such as `Nat`, `Symbol`, or
data types built on top of them. See the
"Arrows, `Nat`, `Symbol`, and literals" section of the `README` for more
information.
* Define a `Quote` instance for `OptionsM`. A notable benefit of this instance
is that it avoids the need to explicitly `lift` TH quotes into `OptionsM`.
Before, you would have to do this:
```hs
import Control.Monad.Trans.Class (lift)
withOptions defaultOptions
$ singletons
$ lift [d| data T = MkT |]
```
But now, it suffices to simply do this:
```hs
withOptions defaultOptions
$ singletons [d| data T = MkT |]
```