This project is based on the constraints library.
Module Data.Constraint.Deriving is a GHC Core compiler plugin that
provides new flexible programmable ways to generate class instances.
The main goal of this project is to make possible a sort of ad-hoc polymorphism that I wanted to implement in easytensor for performance reasons: an umbrella type unifies multiple specialized type family backend instances; if the type instance is known, GHC picks a specialized (overlapping) class instance for a required function; otherwise, GHC resorts to a unified (overlappable) instance that is defined for the whole type family.
To use the plugin, add
{-# OPTIONS_GHC -fplugin Data.Constraint.Deriving #-}to the header of your module.
For debugging, add a plugin option dump-instances:
{-# OPTIONS_GHC -fplugin-opt Data.Constraint.Deriving:dump-instances #-}to the header of your file; it will print all instances declared in the module (hand-written and auto-generated).
To enable much more verbose debug output, use library flag dev (for debugging the plugin itself).
Check out example folder for a motivating use case (enabled with flag examples).
The plugin is controlled via GHC annotations; there are three types of annotations corresponding to plugin passes. All passes are core-to-core, which means the plugin runs after the typechecker, which in turn means the generated class instances are available only outside of the module. A sort of inconvenience you may have experienced with template haskell 😉.
DeriveAll plugin pass inspects a newtype declaration.
To enable DeriveAll for a newtype Foo, add an annotation as follows:
data Bar a = ...
{-# ANN type Foo DeriveAll #-}
newtype Foo a = Foo (Bar a)
-- the result is that Foo has the same set of instances as Barcheck out test/Spec/ for more examples.
DeriveAll plugin pass looks through all possible type instances (in the presence of type families) of the base type,
and copies all class instances for the newtype wrapper.
Sometimes, you may need to refine the relation between the base type and the newtype;
you can do this via a special type family DeriveContext newtype :: Constraint.
By adding equality constraints, you can specify custom dependencies between type variables present in the newtype declaration
(e.g. test/Spec/DeriveAll01.hs).
By adding class constraints, you force these class constraints for all generated class instances
(e.g. in test/Spec/DeriveAll02.hs
all class instances of BazTy a b c d e f have an additional constraint Show e).
Note, the internal machinery is different from GeneralizedNewtypeDeriving approach:
rather than coercing every function in the instance definition from the base type to the newtype,
it coerces the whole instance dictionary.
Sometimes you may want to avoid deriving a number of instances for your newtype.
Use DeriveAllBut [String] constructor in the annotation and specify names of type classes you don't want to derive.
{-# ANN type CHF (DeriveAllBut ["Show"]) #-}
newtype CHF = CHF Double deriving Show
-- the result is a normal `Show CHF` instance and the rest of `Double`'s instances are DeriveAll-edFor your safety,
the plugin is hardcoded to not generate instances for any classes and types in
GHC.Generics, Data.Data, Data.Typeable, Language.Haskell.TH.
By default DeriveAll marks all instances as NoOverlap if there are no overlapping
closed type families involved.
Otherwise, it marks overlapped type instances as Incoherent.
If this logic does not suit you, you can enforce OverlapMode using DeriveAll' data constructor.
ToInstance plugin pass converts a top-level Ctx => Dict (Class t1..tn) value declaration into
an instance of the form instance Ctx => Class t1..tn.
Thus, one can write arbitrary Haskell code (returning a class dictionary) to be executed every time
an instance is looked up by the GHC machinery.
To derive an instance this way, use ToInstance (x :: OverlapMode) for a declaration, e.g. as follows:
newtype Foo t = Foo t
{-# ANN deriveEq (ToInstance NoOverlap) #-}
deriveEq :: Eq t => Dict (Eq (Foo t))
deriveEq = mapDict (unsafeDerive Foo) Dict
-- the result of the above is equal to
-- deriving instance Eq t => Eq (Foo t)You can find a more meaningful example in test/Spec/ToInstance01.hs or
example/Lib/VecBackend.hs.
Danger: ToInstance removes duplicate instances;
if you have defined an instance with the same head using vanilla Haskell and the plugin,
the latter will try to replace the former in place.
Behavior of the instance in the same module is undefined in this case
(the other modules should be fine seeing the plugin version).
I used this trick to convince .hs-boot to see the instances generated by the plugin.
ClassDict plugin pass lets you construct a new class dictionary without
actually creating a class instance:
{-# ANN defineEq ClassDict #-}
defineEq :: (a -> a -> Bool) -> (a -> a -> Bool) -> Dict (Eq a)
defineEq = defineEq
-- the plugin replaces the above line with an actual class data constructor applicationCheck out test/Spec/ClassDict01.hs for a more elaborate example.
DeriveAll derivation mechanics currently ignores and may break functional dependencies.