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