Changelog for the `singletons-base` project
===========================================

3.5 [2024.12.11]
----------------
* Require building with GHC 9.12.
* Remove the use of a custom `Setup.hs` script. This script has now been
  replaced with a [`cabal` code
  generator](https://cabal.readthedocs.io/en/stable/cabal-package-description-file.html#pkg-field-test-suite-code-generators)
  As such, `singletons-base` now requires the use of `Cabal-3.8` or later in
  order to build.
* The types of `sError`, `sErrorWithoutStackTrace`, and `sUndefined` are now
  less polymorphic than they were before:

  ```diff
  -sError :: forall a (str :: Symbol). HasCallStack => Sing str -> a
  +sError :: forall a (str :: Symbol). HasCallStack => Sing str -> Sing (Error @a str)

  -sErrorWithoutStackTrace :: forall a (str :: Symbol). Sing str -> a
  +sErrorWithoutStackTrace :: forall a (str :: Symbol). Sing str -> Sing (ErrorWithoutStackTrace @a str)

  -sUndefined :: forall a. HasCallStack => a
  +sUndefined :: forall a. HasCallStack => Sing (Undefined @a)
  ```

  This is because the old type signatures were _too_ polymorphic, and they
  required _ad hoc_ special casing in `singletons-th` in order to make them
  work in generated code. The more specific type signatures that these functions
  now have improve type inference and avoid the need for special casing. If you
  truly need the full polymorphism of the old type signatures, use `error`,
  `errorWithoutStackTrace`, or `undefined` instead.
* The kinds of `PAlternative` (and other classes in `singletons-base` that are
  parameterized over a higher-kinded type variable) are less polymorphic than
  they were before:

  ```diff
  -type PAlternative :: (k    -> Type) -> Constraint
  +type PAlternative :: (Type -> Type) -> Constraint

  -type PMonadZip :: (k    -> Type) -> Constraint
  +type PMonadZip :: (Type -> Type) -> Constraint

  -type PMonadPlus :: (k    -> Type) -> Constraint
  +type PMonadPlus :: (Type -> Type) -> Constraint
  ```

  Similarly, the kinds of defunctionalization symbols for these classes (e.g.,
  `EmptySym0` and `(<|>@#@$)`) now use `Type -> Type` instead of `k -> Type`.
  The fact that these were kind-polymorphic to begin with was an oversight, as
  these could not be used when `k` was instantiated to any other kind besides
  `Type`.
* The kinds in the `PFunctor` instance for `Compose` are less polymorphic than
  they were before:

  ```diff
  -instance PFunctor (Compose (f :: k    -> Type) (g :: Type -> k))
  +instance PFunctor (Compose (f :: Type -> Type) (g :: Type -> Type))
  ```

  Similarly for the `PFoldable`, `PTraversable`, `PApplicative`, and
  `PAlternative` instances for `Compose`. The fact that these instances were so
  polymorphic to begin with was an oversight, as these instances could not be
  used when `k` was instantiated to any other kind besides `Type`.
* The kinds of `Asum` and `Msum` are less polymorphic than they were before:

  ```diff
  -type Asum :: forall {j} {k} (t :: k    -> Type) (f :: j    -> k)    (a :: j).    t (f a) -> f a
  +type Asum :: forall         (t :: Type -> Type) (f :: Type -> Type) (a :: Type). t (f a) -> f a

  -type Msum :: forall {j} {k} (t :: k    -> Type) (m :: j    -> k)    (a :: j).    t (m a) -> m a
  +type Msum :: forall         (t :: Type -> Type) (m :: Type -> Type) (a :: Type). t (m a) -> m a
  ```

  Similarly, the kinds of defunctionalization symbols for these definitions
  (e.g., `AsumSym0` and `MSym0`) are less polymorphic. The fact that these were
  kind-polymorphic to begin with was an oversight, as these definitions could
  not be used when `j` or `k` was instantiated to any other kind besides `Type`.
* Define hand-written `Sing` instances such that they explicitly match on their
  types on the left-hand sides (e.g., define `type instance Sing @Symbol =
  SSymbol` instead of `type instance Sing = SSymbol`. Doing so will make
  `singletons-base` future-proof once
  [GHC#23515](https://gitlab.haskell.org/ghc/ghc/-/issues/23515) is fixed.

3.4 [2024.05.12]
----------------
* Require building with GHC 9.10.

3.3 [2023.10.13]
----------------
* Require building with GHC 9.8.
* All singleton types with `SEq` or `SOrd` instances now have `Eq` or `Ord`
  instances of the form:

  ```hs
  instance Eq (SExample a) where
    _ == _ = True

  instance Ord (SExample a) where
    compare _ _ = EQ
  ```
* Define `{P,S}Eq` and `{P,S}Ord` instances for `Sum`, `Product`, and `Compose`.
* Define `TestEquality` and `TestOrdering` instances for `SSum`, `SProduct`, and
  `SCompose`.

3.2 [2023.03.12]
----------------
* Require building with GHC 9.6.
* The kinds of the promoted `Error` and `ErrorWithoutStackTrace` functions have
  been monomorphized to `Symbol`. A previous release generalized the kinds of
  these arguments to allow passing arguments besides `Symbol`s, but this change
  introduces ambiguity in derived code when `OverloadedString`s is enabled.
  See [#89](https://github.com/goldfirere/singletons/issues/89) for the full
  story.

  If you were relying on the previous, kind-polymorphic behavior of `Error`, you
  can instead use the new `Data.Singletons.Base.PolyError` module that provides
  `PolyError`, a version of `Error` with a kind-polymorphic argument.
* `Data.Ord.Singletons` and `Data.Singletons.Base.TH` no longer define a
  `thenCmp :: Ordering -> Ordering -> Ordering` function, as this is not
  something that has ever existed in `base`. The existence of a `thenCmp`
  function was solely motivated by the code generated by derived `Ord`
  instances, but `singletons-base` now uses `(<>) @Ordering` instead.
* `GHC.TypeLits.Singletons` now re-exports the `SChar`, `SNat`, and `SSymbol`
  singleton types offered by `GHC.TypeLits` in `base-4.18.0.0` rather than
  defining its own versions. The versions of `SChar`, `SNat`, and `SSymbol`
  offered by `GHC.TypeLits` are nearly identical, minus some minor cosmetic
  changes (e.g., `GHC.TypeLits` defines pattern synonyms for `SNat` _et a._
  instead of data constructors).
* `GHC.TypeLits.Singletons` now re-exports the `SSymbol` pattern synonym
  from `GHC.TypeLits`. `GHC.TypeLits.Singletons` also continues to export `SSym`
  for backwards compatibility.
* `Prelude.Singletons` now re-exports `LiftA2` and `sLiftA2`, mirroring the
  fact that `Prelude` now re-exports `liftA2` in `base-4.18.0.0`.
* Provide `TestEquality` and `TestCoercion` instances for `SNat, `SSymbol`, and
  `SChar`.

3.1.1 [2022.08.23]
------------------
* Require building with GHC 9.4.

3.1 [2021.10.30]
----------------
* Require building with GHC 9.2.
* `singletons-base` now supports type-level `Char`s, a feature added in
  GHC 9.2. In particular:

  * Promoting and singling character literal expressions (e.g., `f = 'a'`) is
    now supported. Promoting (but not singling) character patterns
    (e.g., `g 'a' = ()`) is also supported.
  * `GHC.TypeLits.Singletons` now offers singled versions of the `ConsSymbol`,
    `UnconsSymbol`, `CharToNat`, and `NatToChar` type families that were
    introduced to `GHC.TypeLits` in GHC 9.2.
  * `Text.Show.Singletons` now makes use of type-level `Char`s, a feature added
    in GHC 9.2. As a result, there is no longer any need for the `SChar` type
    synonym, so it has been removed.
  * The `PShow` and `SShow` instances for `Symbol` now display escape characters
    properly rather than returning the input `Symbol` unchanged.

* In GHC 9.2, `Nat` is now a synonym for `Natural`. As a result, the bogus
  `Num`, `Eq`, `Ord`, `Enum`, and `Show` instances for `Nat` in
  `GHC.TypeLits.Singletons` have been removed, as they have replaced by the
  corresponding instances for `Natural`.
* Add `Data.Functor.{Compose,Product,Sum}.Singletons`.
* The types of various entities in `Data.Functor.Const.Singletons` and
  `Data.Proxy.Singletons` have been tweaked slightly such that their
  specificities match their term-level counterparts:

  ```diff
  -SConst :: forall {k} {a} {b :: k} (x :: a). Sing x -> Sing ('Const @a @b x)
  +SConst :: forall {k}  a  (b :: k) (x :: a). Sing x -> Sing ('Const @a @b x)

  -type ConstSym0 :: forall  k  a (b :: k). a ~> Const a b
  +type ConstSym0 :: forall {k} a (b :: k). a ~> Const a b

  -type ConstSym1 :: forall  k a  (b :: k). a -> Const a b
  +type ConstSym1 :: forall {k} a (b :: k). a -> Const a b

  -type ProxySym0 :: forall  k  (t :: k). Proxy t
  +type ProxySym0 :: forall {k} (t :: k). Proxy t
  ```
* Define instances of `SingI1` and `SingI2` when possible.

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-th` 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.
* The modules in `singletons-base` have been renamed to better reflect the
  modules from `base` from which they take inspiration. In particular, the
  following module renamings have been applied:

  * `Data.Singletons.CustomStar`            -> `Data.Singletons.Base.CustomStar`
  * `Data.Singletons.Prelude`               -> `Prelude.Singletons`
  * `Data.Singletons.Prelude.Applicative`   -> `Control.Applicative.Singletons`
  * `Data.Singletons.Prelude.Bool`          -> `Data.Bool.Singletons`
  * `Data.Singletons.Prelude.Const`         -> `Data.Functor.Const.Singletons`
  * `Data.Singletons.Prelude.Either`        -> `Data.Either.Singletons`
  * `Data.Singletons.Prelude.Enum`          -> `Data.Singletons.Base.Enum`
  * `Data.Singletons.Prelude.Eq`            -> `Data.Eq.Singletons`
  * `Data.Singletons.Prelude.Foldable`      -> `Data.Foldable.Singletons`
  * `Data.Singletons.Prelude.Function`      -> `Data.Function.Singletons`
  * `Data.Singletons.Prelude.Functor`       -> `Data.Functor.Const.Singletons`
  * `Data.Singletons.Prelude.Identity`      -> `Data.Functor.Identity.Singletons`
  * `Data.Singletons.Prelude.IsString`      -> `Data.String.Singletons`
  * `Data.Singletons.Prelude.Ord`           -> `Data.Ord.Singletons`
  * `Data.Singletons.Prelude.List`          -> `Data.List.Singletons`
  * `Data.Singletons.Prelude.List.NonEmpty` -> `Data.List.NonEmpty.Singletons`
  * `Data.Singletons.Prelude.Maybe`         -> `Data.Maybe.Singletons`
  * `Data.Singletons.Prelude.Monad`         -> `Control.Monad.Singletons`
  * `Data.Singletons.Prelude.Monad.Fail`    -> `Control.Monad.Fail.Singletons`
  * `Data.Singletons.Prelude.Monad.Zip`     -> `Control.Monad.Zip.Singletons`
  * `Data.Singletons.Prelude.Monoid`        -> `Data.Monoid.Singletons`
  * `Data.Singletons.Prelude.Proxy`         -> `Data.Proxy.Singletons`
  * `Data.Singletons.Prelude.Semigroup`     -> `Data.Semigroup.Singletons`
  * `Data.Singletons.Prelude.Show`          -> `Data.Show.Singletons`
  * `Data.Singletons.Prelude.Traversable`   -> `Data.Traversable.Singletons`
  * `Data.Singletons.Prelude.Tuple`         -> `Data.Tuple.Singletons`
  * `Data.Singletons.Prelude.Void`          -> `Data.Void.Singletons`
  * `Data.Singletons.TH`                    -> `Data.Singletons.Base.TH`
  * `Data.Singletons.TypeError`             -> `Data.Singletons.Base.TypeError`
  * `Data.Singletons.TypeLits`              -> `GHC.TypeLits.Singletons`
  * `Data.Singletons.TypeRepTYPE`           -> `Data.Singletons.Base.TypeRepTYPE`

  Note that modules that do not correspond to any particular module in `base`
  now have the prefix `Data.Singletons.Base.*`. This includes
  `Data.Singletons.Base.Enum`, a special module that exists to provide a
  home for the `Succ` and `Pred` promoted type families that is separate from
  `Prelude.Singletons` (which exports everything from `PEnum` _except_ `Succ`
  and `Pred`). This is done in an effort to make importing `Prelude.Singletons`
  less likely to induce name clashes with code that works over unary natural
  numbers, which often use the names "`Succ`" and "`Pred`".
* An effort has been made to make the API of `Prelude.Singletons` more closely
  mirror that of the `Prelude` in `base`. As a result, `Prelude.Singletons` now
  exports some different functions than it used to. In particular, it now
  exports the following:

  * `Until`/`sUntil`/`UntilSym{N}`
  * `type (++@#@$$$)`
  * `type (.@#@$$$$)`
  * `FlipSym3`
  * `type (!!)`/`(%!!)`/`type (!!@#@{$})`
  * `Length`/`sLength`/`LengthSym{N}`
  * `DropWhile`/`sDropWhile`
  * `LookupSym{N}`
  * `Unzip3Sym{N}`

  `Prelude.Singletons` also used to export some things that were _not_ exported
  by the `Prelude`. Accordingly, these exports have been removed from
  `Prelude.Singletons`. They are:

  * `(^)`/`(%^)`/`type (^@#@{$})`. Although the `Prelude` does define a
    function named `(^)`, it is more general than the one defined in
    `singletons-base`, which only works on `Nat`s. Import
    `GHC.TypeLits.Singletons` if you wish to use the `Nat`-specific versions.
  * `DefaultEq`, which has no counterpart in the `Prelude`.
    Import `Data.Eq.Singletons` if you wish to use this.
  * `bool_`, which has no counterpart in the `Prelude`.
    Import `Data.Bool.Singletons` if you wish to use this.
* Two previously public-facing modules—`Data.Singletons.Prelude.Base` and
  `Data.Singletons.Prelude.Num`—have been turned into internal modules. The
  contents of these modules are re-exported from `Prelude.Singletons`, so that
  can be used instead.
* Due to the `singletons` package split, the `Eq`, `Ord`, etc. instances for
  `SomeSing` are no longer provided in the `Data.Singletons` module in the
  `singletons` library. Instead, they are now provided in a new
  `Data.Singletons.Base.SomeSing` module, which defines `Eq`, `Ord`, etc.
  instances for `SomeSing` as orphans.
* The `PEq` class no longer uses `DefaultEq` as its default implementation for
  `(==)`. `DefaultEq`, despite its name, is actually not a suitable
  implementation for `(==)` for a good majority of singleton types
  (see the discussion in
  [this GitHub issue](https://github.com/goldfirere/singletons/issues/457)
  for more information). `(==)`'s default is now defined in terms of `(/=)`,
  just like its term-level counterpart in the `Eq` class.
* Since `base-4.15.0.0` now deprecates `Data.Singletons.Option` (in
  anticipation of its removal in a future version of `base`), this library no
  longer offers a singleton type for `Option`. Accordingly, the `option_`
  function has also been removed.