deriving-compat-0.5.6: Backports of GHC deriving extensions

Copyright | (C) 2015-2017 Ryan Scott
License | BSD-style (see the file LICENSE)
Maintainer | Ryan Scott
Portability | Template Haskell
Safe Haskell | None
Language | Haskell2010

Data.Deriving.Via

Contents

- `GeneralizedNewtypeDeriving`
- `DerivingVia`
- Limitations

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

- deriveGND :: Q Type -> Q [Dec]
- deriveVia :: Q Type -> Q [Dec]
- data Via a b

# `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.)