Generics.Deriving.TH

This module contains Template Haskell code that can be used to automatically generate the boilerplate code for the generic deriving library.

To use these functions, pass the name of a data type as an argument:

{-# LANGUAGE TemplateHaskell #-}

data Example a = Example Int Char a
$(deriveAll0     ''Example) -- Derives Generic instance
$(deriveAll1     ''Example) -- Derives Generic1 instance
$(deriveAll0And1 ''Example) -- Derives Generic and Generic1 instances

On GHC 7.4 or later, this code can also be used with data families. To derive for a data family instance, pass the name of one of the instance's constructors:

{-# LANGUAGE FlexibleInstances, TemplateHaskell, TypeFamilies #-}

data family Family a b
newtype instance Family Char x = FamilyChar Char
data    instance Family Bool x = FamilyTrue | FamilyFalse

$(deriveAll0 'FamilyChar) -- instance Generic (Family Char b) where ...
$(deriveAll1 'FamilyTrue) -- instance Generic1 (Family Bool) where ...
-- Alternatively, one could type $(deriveAll1 'FamilyFalse)

derive- functions

deriveMeta :: Name -> Q [Dec]

Given the type and the name (as string) for the type to derive, generate the Data instance, the Constructor instances, and the Selector instances.

On GHC 7.11 and up, this functionality is no longer used in GHC generics, so this function generates no declarations.

deriveData :: Name -> Q [Dec]

Given a datatype name, derive a datatype and instance of class Datatype.

On GHC 7.11 and up, this functionality is no longer used in GHC generics, so this function generates no declarations.

deriveConstructors :: Name -> Q [Dec]

Given a datatype name, derive datatypes and instances of class Constructor.

On GHC 7.11 and up, this functionality is no longer used in GHC generics, so this function generates no declarations.

deriveSelectors :: Name -> Q [Dec]

Given a datatype name, derive datatypes and instances of class Selector.

On GHC 7.11 and up, this functionality is no longer used in GHC generics, so this function generates no declarations.

deriveAll :: Name -> Q [Dec]

A backwards-compatible synonym for deriveAll0.

deriveAll0 :: Name -> Q [Dec]

Given the type and the name (as string) for the type to derive, generate the Data instance, the Constructor instances, the Selector instances, and the Representable0 instance.

deriveAll1 :: Name -> Q [Dec]

Given the type and the name (as string) for the type to derive, generate the Data instance, the Constructor instances, the Selector instances, and the Representable1 instance.

deriveAll0And1 :: Name -> Q [Dec]

Given the type and the name (as string) for the type to derive, generate the Data instance, the Constructor instances, the Selector instances, the Representable0 instance, and the Representable1 instance.

deriveRepresentable0 :: Name -> Q [Dec]

Given the type and the name (as string) for the Representable0 type synonym to derive, generate the Representable0 instance.

deriveRepresentable1 :: Name -> Q [Dec]

Given the type and the name (as string) for the Representable1 type synonym to derive, generate the Representable1 instance.

deriveRep0 :: Name -> Q [Dec]

Derive only the Rep0 type synonym. Not needed if deriveRepresentable0 is used.

deriveRep1 :: Name -> Q [Dec]

Derive only the Rep1 type synonym. Not needed if deriveRepresentable1 is used.

make- functions

There are some data types for which the Template Haskell deriver functions in this module are not sophisticated enough to infer the correct Generic or Generic1 instances. As an example, consider this data type:

newtype Fix f a = Fix (f (Fix f a))

A proper Generic1 instance would look like this:

instance Functor f => Generic1 (Fix f) where ...

Unfortunately, deriveRepresentable1 cannot infer the Functor f constraint. One can still define a Generic1 instance for Fix, however, by using the functions in this module that are prefixed with make-. For example:

$(deriveMeta ''Fix)
$(deriveRep1 ''Fix)
instance Functor f => Generic1 (Fix f) where
  type Rep1 (Fix f) = $(makeRep1Inline ''Fix [t| Fix f |])
  from1 = $(makeFrom1 ''Fix)
  to1   = $(makeTo1   ''Fix)

Note that due to the lack of type-level lambdas in Haskell, one must manually apply makeRep1Inline ''Fix to the type Fix f.

Be aware that there is a bug on GHC 7.0, 7.2, and 7.4 which might prevent you from using makeRep0Inline and makeRep1Inline. In the Fix example above, you would experience the following error:

    Kinded thing f used as a type
    In the Template Haskell quotation [t| Fix f |]

Then a workaround is to use makeRep1 instead, which requires you to:

1. Invoke deriveRep1 beforehand
2. Pass as arguments the type variables that occur in the instance, in order from left to right, topologically sorted, excluding duplicates. (Normally, makeRep1Inline would figure this out for you.)

Using the above example:

$(deriveMeta ''Fix)
$(deriveRep1 ''Fix)
instance Functor f => Generic1 (Fix f) where
  type Rep1 (Fix f) = $(makeRep1 ''Fix) f
  from1 = $(makeFrom1 ''Fix)
  to1   = $(makeTo1   ''Fix)

On GHC 7.4, you might encounter more complicated examples involving data families. For instance:

data family Fix a b c d
newtype instance Fix b (f c) (g b) a = Fix (f (Fix b (f c) (g b) a))

$(deriveMeta ''Fix)
$(deriveRep1 ''Fix)
instance Functor f => Generic1 (Fix b (f c) (g b)) where
  type Rep1 (Fix b (f c) (g b)) = $(makeRep1 'Fix) b f c g
  from1 = $(makeFrom1 'Fix)
  to1   = $(makeTo1   'Fix)

Note that you don't pass b twice, only once.

makeRep0Inline :: Name -> Q Type -> Q Type

Generates the full Rep type inline. Since this type can be quite large, it is recommended you only use this to define Rep, e.g.,

type Rep (Foo (a :: k) b) = $(makeRep0Inline ''Foo [t| Foo (a :: k) b |])

You can then simply refer to Rep (Foo a b) elsewhere.

Note that the type passed as an argument to makeRep0Inline must match the type argument of Rep exactly, even up to including the explicit kind signature on a. This is due to a limitation of Template Haskell—without the kind signature, makeRep0Inline has no way of figuring out the kind of a, and the generated type might be completely wrong as a result!

makeRep0 :: Name -> Q Type

Generates the Rep type synonym constructor (as opposed to deriveRep0, which generates the type synonym declaration). After splicing it into Haskell source, it expects types as arguments. For example:

type Rep (Foo a b) = $(makeRep0 ''Foo) a b

The use of makeRep0 is generally discouraged, as it can sometimes be difficult to predict the order in which you are expected to pass type variables. As a result, makeRep0Inline is recommended instead. However, makeRep0Inline is not usable on GHC 7.0, 7.2, or 7.4 due to a GHC bug, so makeRep0 still exists for GHC 7.0, 7.2, and 7.4 users.

makeRep0FromType :: Name -> Q Type -> Q Type

Generates the Rep type synonym constructor (as opposed to deriveRep0, which generates the type synonym declaration) applied to its type arguments. Unlike makeRep0, this also takes a quoted Type as an argument, e.g.,

type Rep (Foo (a :: k) b) = $(makeRep0FromType ''Foo [t| Foo (a :: k) b |])

Note that the type passed as an argument to makeRep0FromType must match the type argument of Rep exactly, even up to including the explicit kind signature on a. This is due to a limitation of Template Haskell—without the kind signature, makeRep0FromType has no way of figuring out the kind of a, and the generated type might be completely wrong as a result!

The use of makeRep0FromType is generally discouraged, since makeRep0Inline does exactly the same thing but without having to go through an intermediate type synonym, and as a result, makeRep0Inline tends to be less buggy.

makeFrom :: Name -> Q Exp

A backwards-compatible synonym for makeFrom0.

makeFrom0 :: Name -> Q Exp

Generates a lambda expression which behaves like from.

makeTo :: Name -> Q Exp

A backwards-compatible synonym for makeTo0.

makeTo0 :: Name -> Q Exp

Generates a lambda expression which behaves like to.

makeRep1Inline :: Name -> Q Type -> Q Type

Generates the full Rep1 type inline. Since this type can be quite large, it is recommended you only use this to define Rep1, e.g.,

type Rep1 (Foo (a :: k)) = $(makeRep0Inline ''Foo [t| Foo (a :: k) |])

You can then simply refer to Rep1 (Foo a) elsewhere.

Note that the type passed as an argument to makeRep1Inline must match the type argument of Rep1 exactly, even up to including the explicit kind signature on a. This is due to a limitation of Template Haskell—without the kind signature, makeRep1Inline has no way of figuring out the kind of a, and the generated type might be completely wrong as a result!

makeRep1 :: Name -> Q Type

Generates the Rep1 type synonym constructor (as opposed to deriveRep1, which generates the type synonym declaration). After splicing it into Haskell source, it expects types as arguments. For example:

type Rep1 (Foo a) = $(makeRep1 ''Foo) a

The use of makeRep1 is generally discouraged, as it can sometimes be difficult to predict the order in which you are expected to pass type variables. As a result, makeRep1Inline is recommended instead. However, makeRep1Inline is not usable on GHC 7.0, 7.2, or 7.4 due to a GHC bug, so makeRep1 still exists for GHC 7.0, 7.2, and 7.4 users.

makeRep1FromType :: Name -> Q Type -> Q Type

Generates the Rep1 type synonym constructor (as opposed to deriveRep1, which generates the type synonym declaration) applied to its type arguments. Unlike makeRep1, this also takes a quoted Type as an argument, e.g.,

type Rep1 (Foo (a :: k)) = $(makeRep1FromType ''Foo [t| Foo (a :: k) |])

Note that the type passed as an argument to makeRep1FromType must match the type argument of Rep exactly, even up to including the explicit kind signature on a. This is due to a limitation of Template Haskell—without the kind signature, makeRep1FromType has no way of figuring out the kind of a, and the generated type might be completely wrong as a result!

The use of makeRep1FromType is generally discouraged, since makeRep1Inline does exactly the same thing but without having to go through an intermediate type synonym, and as a result, makeRep1Inline tends to be less buggy.

makeFrom1 :: Name -> Q Exp

Generates a lambda expression which behaves like from1.

makeTo1 :: Name -> Q Exp

Generates a lambda expression which behaves like to1.

Options

Options gives you a way to further tweak derived Generic and Generic1 instances:

• RepOptions: By default, all derived Rep and Rep1 type instances emit the code directly (the InlineRep option). One can also choose to emit a separate type synonym for the Rep type (this is the functionality of deriveRep0 and deriveRep1) and define a Rep instance in terms of that type synonym (the TypeSynonymRep option).
• KindSigOptions: By default, all derived instances will use explicit kind signatures (when the KindSigOptions is True). You might wish to set the KindSigOptions to False if you want a 'Generic'/'Generic1' instance at a particular kind that GHC will infer correctly, but the functions in this module won't guess correctly. For example, the following example will only compile with KindSigOptions set to False:

 newtype Compose (f :: k2 -> *) (g :: k1 -> k2) (a :: k1) = Compose (f (g a))
 $(deriveAll1Options False ''Compose)
 

• EmptyCaseOptions: By default, all derived instances for empty data types (i.e., data types with no constructors) use error in from(1)/to(1). For instance, data Empty would have this derived Generic instance:

 instance Generic Empty where
   type Rep Empty = D1 ('MetaData ...) V1
   from _ = M1 (error "No generic representation for empty datatype Empty")
   to (M1 _) = error "No generic representation for empty datatype Empty"
 

This matches the behavior of GHC up until 8.4, when derived Generic(1) instances began to use the EmptyCase extension. In GHC 8.4, the derived Generic instance for Empty would instead be:

 instance Generic Empty where
   type Rep Empty = D1 ('MetaData ...) V1
   from x = M1 (case x of {})
   to (M1 x) = case x of {}
 

This is a slightly better encoding since, for example, any divergent computations passed to from will actually diverge (as opposed to before, where the result would always be a call to error). On the other hand, using this encoding in generic-deriving has one large drawback: it requires enabling EmptyCase, an extension which was only introduced in GHC 7.8 (and only received reliable pattern-match coverage checking in 8.2).

The EmptyCaseOptions field controls whether code should be emitted that uses EmptyCase (i.e., EmptyCaseOptions set to True) or not (False). The default value is False. Note that even if set to True, this option has no effect on GHCs before 7.8, as EmptyCase did not exist then.

data Options

Additional options for configuring derived 'Generic'/'Generic1' instances using Template Haskell.

Constructors

Options

Fields

• repOptions :: RepOptions
• kindSigOptions :: KindSigOptions
• emptyCaseOptions :: EmptyCaseOptions

Instances

Eq Options

Methods

(==) :: Options -> Options -> Bool

(/=) :: Options -> Options -> Bool

Ord Options

Methods

compare :: Options -> Options -> Ordering

(<) :: Options -> Options -> Bool

(<=) :: Options -> Options -> Bool

(>) :: Options -> Options -> Bool

(>=) :: Options -> Options -> Bool

max :: Options -> Options -> Options

min :: Options -> Options -> Options

Read Options

Methods

readsPrec :: Int -> ReadS Options

readList :: ReadS [Options]

readPrec :: ReadPrec Options

readListPrec :: ReadPrec [Options]

Show Options

Methods

showsPrec :: Int -> Options -> ShowS

show :: Options -> String

showList :: [Options] -> ShowS

defaultOptions :: Options

Sensible default Options.

data RepOptions

Configures whether 'Rep'/'Rep1' type instances should be defined inline in a derived 'Generic'/'Generic1' instance (InlineRep) or defined in terms of a type synonym (TypeSynonymRep).

Constructors

InlineRep

TypeSynonymRep

Instances

Eq RepOptions

Methods

(==) :: RepOptions -> RepOptions -> Bool

(/=) :: RepOptions -> RepOptions -> Bool

Ord RepOptions

Methods

compare :: RepOptions -> RepOptions -> Ordering

(<) :: RepOptions -> RepOptions -> Bool

(<=) :: RepOptions -> RepOptions -> Bool

(>) :: RepOptions -> RepOptions -> Bool

(>=) :: RepOptions -> RepOptions -> Bool

max :: RepOptions -> RepOptions -> RepOptions

min :: RepOptions -> RepOptions -> RepOptions

Read RepOptions

Methods

readsPrec :: Int -> ReadS RepOptions

readList :: ReadS [RepOptions]

readPrec :: ReadPrec RepOptions

readListPrec :: ReadPrec [RepOptions]

Show RepOptions

Methods

showsPrec :: Int -> RepOptions -> ShowS

show :: RepOptions -> String

showList :: [RepOptions] -> ShowS

defaultRepOptions :: RepOptions

InlineRep, a sensible default RepOptions.

type KindSigOptions = Bool

True if explicit kind signatures should be used in derived 'Generic'/'Generic1' instances, False otherwise.

defaultKindSigOptions :: KindSigOptions

True, a sensible default KindSigOptions.

type EmptyCaseOptions = Bool

True if generated code for empty data types should use the EmptyCase extension, False otherwise. This has no effect on GHCs before 7.8, since EmptyCase is only available in 7.8 or later.

defaultEmptyCaseOptions :: EmptyCaseOptions

Sensible default EmptyCaseOptions.

Functions with optional arguments

deriveAll0Options :: Options -> Name -> Q [Dec]

Like deriveAll0, but takes an Options argument.

deriveAll1Options :: Options -> Name -> Q [Dec]

Like deriveAll1, but takes an Options argument.

deriveAll0And1Options :: Options -> Name -> Q [Dec]

Like deriveAll0And1, but takes an Options argument.

deriveRepresentable0Options :: Options -> Name -> Q [Dec]

Like deriveRepresentable0, but takes an Options argument.

deriveRepresentable1Options :: Options -> Name -> Q [Dec]

Like deriveRepresentable1, but takes an Options argument.

deriveRep0Options :: KindSigOptions -> Name -> Q [Dec]

Like deriveRep0, but takes an KindSigOptions argument.

deriveRep1Options :: KindSigOptions -> Name -> Q [Dec]

Like deriveRep1, but takes an KindSigOptions argument.

makeFrom0Options :: EmptyCaseOptions -> Name -> Q Exp

Like makeFrom0Options, but takes an EmptyCaseOptions argument.

makeTo0Options :: EmptyCaseOptions -> Name -> Q Exp

Like makeTo0Options, but takes an EmptyCaseOptions argument.

makeFrom1Options :: EmptyCaseOptions -> Name -> Q Exp

Like makeFrom1Options, but takes an EmptyCaseOptions argument.

makeTo1Options :: EmptyCaseOptions -> Name -> Q Exp

Like makeTo1Options, but takes an EmptyCaseOptions argument.