[Haskell-cafe] [ANN] singletons-3.0, singletons-th-3.0, and singletons-base-3.0

[Ryan Scott]

I'm happy to announce the 3.0 release of the singletons library, as
well as the debut of its companion libraries, singletons-th and
singletons-base. There's been a fair bit of improvements, cleanup, and
reorganization since the last release, so I thought it appropriate to
give this release a super-major version bump. This announcement will
go over some highlights of the new releases, but if you want the full
details, you can consult the changelog entries for each library below:

* singletons-3.0: http://hackage.haskell.org/package/singletons-3.0/changelog
* singletons-th-3.0:
http://hackage.haskell.org/package/singletons-th-3.0/changelog
* singletons-base-3.0:
http://hackage.haskell.org/package/singletons-base-3.0/changelog

##########################
## Why three libraries? ##
##########################

Instead of there just being one singletons library, there are now
_three_ libraries:

* singletons: A small, foundational library that defines basic
singleton-related types and definitions. The new singletons library
supports GHC 8.0 or later, does not depend on any external libraries,
and does not make use of Template Haskell.
* singletons-th: A library that defines Template Haskell functionality
for promoting term-level functions to type-level equivalents and
singling functions to dependently typed equivalents. This library
requires bleeding-edge GHC features, and as a result, it only supports
GHC 9.0 or later.
* singletons-base: A library that uses singletons-th to define
promoted and singled functions from the base library, including the
Prelude. Similarly to singletons-th, this library only supports GHC
9.0 or later.

Previous singletons releases combined all of this functionality into a
single library. However, discussions with singletons users revealed
that this was a frequent source of pain:

* The total time it took to compile the old singletons library
dissuaded some from using it, especially for those who only wanted to
use a small part of the library.
* Some users wished to use singletons in environments where Template
Haskell is not an option.
* Some users wanted to use core definitions from Data.Singletons, but
because the old singletons library only ever supported one GHC at a
time, this was impractical.

The new package structure in the 3.0 release is an attempt to address
some of these pain points. In particular, most of the code which
results in extensive compile times is now confined to the
singletons-base library. For the full discussion that led up to this,
see [1].

###########################
## Module reorganization ##
###########################

Splitting up singletons into smaller packages provided a rare
opportunity to clean up the module naming conventions, which were
confusing and inconsistent in many places. The 3.0 releases now use
the following conventions:

* All modules in singletons now begin with Data.Singletons.*.
* All modules in singletons-th now begin with Data.Singletons.TH.*.
* Most modules in singletons-base now reflect the modules from base
from which they take inspiration. For example, the Prelude module now
has a Prelude.Singletons counterpart in singletons. Similarly, there
are also modules like Control.Monad.Singletons,
GHC.TypeLits.Singletons, etc. All other modules that do not correspond
to something in base now begin with Data.Singletons.Base.*.

The convention now used in singletons-base was inspired by the
conventions used in the lens library. The end result is that is now
somewhat easier to figure out what parts of singletons-base to import.
Because this is a significant departure from previous singletons
releases, if you want to continue supporting pre-3.0 releases, you
will likely need to put something like this in your .cabal file:

    flag singletons-3-0
      description:         Use @singletons-3.0@ or later.
      default:             True

    library
      ...
      if flag(singletons-3-0)
        build-depends:
          singletons-base >= 3.0
          -- You may also need to depend on singletons >= 3.0 or
singletons-th >= 3.0
      else
        build-depends:
          singletons < 3.0

###################
## Other changes ##
###################

Besides the package and module reorganization mentioned above,
singletons-{,th,base}-3.0 feature a variety of new quality-of-life
improvements. Here are a handful of the more notable improvements:

* The OptionsM type, used for configuring how the Template Haskell
machinery in singletons-th works, is now an instance of Quote. This
avoids the need to use the Control.Monad.Trans.Class.lift function to
lift quoted declarations into OptionsM. [2]
* Data.Singletons.TH.Options now defines a promotedDataTypeOrConName
option. 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. [3]
* The internals of the ShowSing class have been refactored to allow
deriving Show instances for Sing types (e.g., deriving instance
ShowSing a => Show (SList (z :: [a]))). [4]
* Improve the quality of GHCi's output when using :kind on types
defined by singletons-th. [5]

If you encounter any issues, feel free to leave a bug report at
https://github.com/goldfirere/singletons/issues.

Happy (type-level) hacking,

Ryan S.
-----
[1] https://github.com/goldfirere/singletons/issues/420
[2] https://github.com/goldfirere/singletons/pull/484
[3] https://github.com/goldfirere/singletons/pull/462
[4] https://github.com/goldfirere/singletons/pull/486
[5] https://github.com/goldfirere/singletons/pull/446