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 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:

  -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:

  -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:

  -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:

  -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 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:

  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 Symbols, but this change introduces ambiguity in derived code when OverloadedStrings is enabled. See #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 Chars, 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 Chars, 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:

  -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.

• 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 Nats. 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 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.