This module implements a system for registering and using typeclass derivers and instantiators. This allows you to derive instances for typeclasses beyond GHC's ability to generate instances in deriving clauses.

For example, TH.Derive.Storable defines a Deriver for Storable. This allows us to use derive to generate an instance for Storable:

    data X = X Int Float

    $($(derive [d|
        instance Deriving (Storable X)
        |]))

In particular, note the use of double splicing, $($(derive [d| ... |])). The inner $(derive [d| ... |]) expression generates code which invokes the runDeriver method with appropriate arguments. The outer $( ... $) then runs that code in order to generate the resulting instances. This is how it does dispatch at compile time.

There are a number of advantages of re-using instance syntax in this way:

• It allows the user to specify constraints. Similarly to GHC's need for standalone deriving, it is sometimes very difficult for TH to figure out appropriate superclass constraints.
• The instance gets thoroughly checked by GHC (syntax, kind, and type checking). This means that you get reasonably nice error messages when you misuse these.
• It allows the user to specify methods. With Instantiators, the user can provide values which can be used in the definition of the generated instance. This is a bit like having Instance Templates. We don't have pretty ways of writing these quite yet, but I have worked on something similar in the past.
• Using compile-time dispatch allows for concise specification of a multiple of instances you'd like derived.
• In the case of use of a Derivers, the user doesn't need to know about anything but derive and the name of the class they want. (and the Deriver instance must be in scope one way or another)