deriving-compat-0.5.2: Backports of GHC deriving extensions

Copyright(C) 2015-2017 Ryan Scott
LicenseBSD-style (see the file LICENSE)
MaintainerRyan Scott
PortabilityTemplate Haskell
Safe HaskellNone
LanguageHaskell2010

Data.Deriving.Via

Contents

Description

On template-haskell-2.12 or later (i.e., GHC 8.2 or later), this module exports functionality which emulates the GeneralizedNewtypeDeriving and DerivingVia GHC extensions (the latter of which was introduced in GHC 8.6).

On older versions of template-haskell/GHC, this module does not export anything.

Synopsis

GeneralizedNewtypeDeriving

deriveGND :: Q Type -> Q [Dec] Source #

Generates an instance for a type class at a newtype by emulating the behavior of the GeneralizedNewtypeDeriving extension. For example:

newtype Foo a = MkFoo a
$(deriveGND [t| forall a. Eq a => Eq (Foo a) |])

DerivingVia

deriveVia :: Q Type -> Q [Dec] Source #

Generates an instance for a type class by emulating the behavior of the DerivingVia extension. For example:

newtype Foo a = MkFoo a
$(deriveVia [t| forall a. Ord a => Ord (Foo a) `Via` Down a |])

As shown in the example above, the syntax is a tad strange. One must specify the type by which to derive the instance using the Via type. This requirement is in place to ensure that the type variables are scoped correctly across all the types being used (e.g., to make sure that the same a is used in Ord a, Ord (Foo a), and Down a).

data Via a b infix 0 Source #

A type-level modifier intended to be used in conjunction with deriveVia. Refer to the documentation for deriveVia for more details.

Limitations

Be aware of the following potential gotchas:

  • Unlike every other module in this library, the functions exported by Data.Deriving.Via only support GHC 8.2 and later, as they require Template Haskell functionality not present in earlier GHCs.

  • Additionally, using the functions in Data.Deriving.Via will likely require you to enable some language extensions (besides TemplateHaskell). These may include:

    • ImpredicativeTypes (if any class methods contain higher-rank types)
    • InstanceSigs
    • KindSignatures
    • RankNTypes
    • ScopedTypeVariables
    • TypeApplications
    • UndecidableInstances (if deriving an instance of a type class with associated type families)
  • The functions in Data.Deriving.Via are not terribly robust in the presence of PolyKinds. Alas, Template Haskell does not make this easy to fix.
  • The functions in Data.Deriving.Via make a best-effort attempt to derive instances for classes with associated type families. This is known not to work in all scenarios, however, especially when the last parameter to a type class appears as a kind variable in an associated type family. (See Trac #14728.)