Summary: Functions for generating the representation for using a datatype with EMGM.

The simplest way to get a representation for a datatype is using derive in a Template Haskell declaration, e.g. $(derive ''MyType). This generates all of the appropriate instances, e.g. Rep, FRep, etc., for the type MyType.

Generating datatype support can be done in a fully automatic way using derive or deriveWith, or it can be done piecemeal using a number of other functions. For most needs, the automatic approach is fine. But if you find you need more control, use the manual deriving approach.

Naming conventions:

• derive - Template Haskell function that generates instance declarations (and possibly also value declarations).
• declare - Template Haskell function that generates only value declarations.
• ep - Embedding-project pair.
• con - Constructor description.
• rep - Value representation meant for rep.
• frep - Value representation meant for frep.
• frep2 - Value representation meant for frep2.
• frep3 - Value representation meant for frep3.
• bifrep2 - Value representation meant for bifrep2.

The functions derive and deriveWith determine which representations can be supported by your datatype. The indications are as follows for each class:

Rep

This instance will be generated for every type.

FRep, FRep2, FRep3

These instances will only be generated for functor types (kind * -> *).

BiFRep2

This instance will only be generated for bifunctor types (kind * -> * -> *).

Derive all appropriate instances for using EMGM with a datatype.

Here is an example module that shows how to use derive:

   {-# LANGUAGE TemplateHaskell       #-}
   {-# LANGUAGE MultiParamTypeClasses #-}
   {-# LANGUAGE FlexibleContexts      #-}
   {-# LANGUAGE FlexibleInstances     #-}
   {-# LANGUAGE OverlappingInstances  #-}
   {-# LANGUAGE UndecidableInstances  #-}

   module Example where
   import Generics.EMGM.Derive
   data T a = C a Int

   $(derive ''T)

The Template Haskell derive declaration in the above example generates the following (annotated) code:

   -- (1) Constructor description declarations

   conC :: ConDescr
   conC = ConDescr "C" 2 [] Nonfix

   -- (2) Embedding-projection pair declaration

   epT :: EP (T a) (a :*: Int)
   epT = EP fromT toT
     where fromT (C v1 v2) = v1 :*: v2
           toT (v1 :*: v2) = C v1 v2

   -- (3) Representation values

   repT :: (Generic g, Rep g a, Rep g Int) => g (T a)
   repT = rtype epT (rcon conC (rprod rep rep))

   frepT :: (Generic g) => g a1 -> g (T a1)
   frepT a = rtype epT (rcon conC (rprod a rint))

   frep2T :: (Generic2 g) => g a1 a2 -> g (T a1) (T a2)
   frep2T a = rtype2 epT epT (rcon2 conC (rprod2 a rint2))

   frep3T :: (Generic3 g) => g a1 a2 a3 -> g (T a1) (T a2) (T a3)
   frep3T a = rtype3 epT epT epT (rcon3 conC (rprod3 a rint3))

   bifrep2T :: (Generic2 g) => g a1 a2 -> g (T a1) (T a2)
   bifrep2T a = rtype2 epT epT (rcon2 conC (rprod2 a rint2))

   -- (4) Representation instances

   instance (Generic g, Rep g a, Rep g Int) => Rep g (T a) where
     rep = repT

   instance (Generic g) => FRep g T where
     frep = frepT

   instance (Generic2 g) => FRep2 g T where
     frep2 = frep2T

   instance (Generic3 g) => FRep3 g T where
     frep3 = frep3T

   -- In this case, no instances for BiFRep2 is generated, because T is not
   -- a bifunctor type; however, the bifrep2T value is always generated in
   -- case T is used in a bifunctor type.

   -- (5) Generic function-specific instances

   instance Rep (Collect (T a)) (T a) where
     rep = Collect (\x -> [x])

   instance (Rep (Everywhere (T a)) a, Rep (Everywhere (T a)) Int)
            => Rep (Everywhere (T a)) (T a) where
     rep = Everywhere (\f x ->
       case x of
         C v1 v2 -> f (C (selEverywhere rep f v1) (selEverywhere rep f v2))

   instance Rep (Everywhere' (T a)) (T a) where
     rep = Everywhere' (\f x -> f x)

Note that all the values are top-level. This allows them to be shared between multiple instances. For example, if you have two mutually recursive functor datatypes, you may need to have each other's derived code in scope.

Same as derive except that you can pass a list of name modifications to the deriving mechanism.

Use deriveWith if:

1. You want to use the generated constructor descriptions or embedding-projection pairs and one of your constructors or types is an infix symbol. In other words, if you have a constructor :*, you cannot refer to the (invalid) generated name for its description, con:*. It appears that GHC has no problem with that name internally, so this is only if you want access to it.
2. You want to define your own constructor description. This allows you to give a precise implementation different from the one generated for you.

For option 1, use ChangeTo as in this example:

   data U = Int :* Char
   $(deriveWith [(":*", ChangeTo "Star")] ''U)
   x = ... conStar ...

For option 2, use DefinedAs as in this example:

   data V = (:=) { i :: Int, j :: Char }
   $(deriveWith [(":=", DefinedAs "Equals")] ''V)
   conEquals = ConDescr ":=" 2 [] (Infix 4)

Using the example for option 2 with Generics.EMGM.Functions.Show will print values of V as infix instead of the default record syntax.

Note that only the first pair with its first field matching the type or constructor name in the Modifiers list will be used. Any other matches will be ignored.

Same as derive except that only the monomorphic Rep representation value and instance are generated. This is a convenience function that can be used instead of the following declarations:

   $(declareConDescrs ''T)
   $(declareEP ''T)
   $(declareMonoRep ''T)
   $(deriveRep ''T)
   $(deriveFRep ''T)
   $(deriveCollect ''T)

Use the functions in this section for more control over the declarations and instances that are generated.

Since each function here generates one component needed for the entire datatype representation, you will most likely need to use multiple TH declarations. To get the equivalent of the resulting code described in derive, you will need the following:

   {-# LANGUAGE TemplateHaskell        #-}
   {-# LANGUAGE MultiParamTypeClasses  #-}
   {-# LANGUAGE FlexibleContexts       #-}
   {-# LANGUAGE FlexibleInstances      #-}
   {-# LANGUAGE OverlappingInstances   #-}
   {-# LANGUAGE UndecidableInstances   #-}

   module Example where
   import Generics.EMGM.Derive
   data T a = C a Int

   $(declareConDescrs ''T)
   $(declareEP ''T)
   $(declareRepValues ''T)
   $(deriveRep ''T)
   $(deriveFRep ''T)
   $(deriveCollect ''T)
   $(deriveEverywhere ''T)
   $(deriveEverywhere' ''T)