constraints-deriving

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

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 Bar

check 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.

Blacklisting instances from being DeriveAll-ed

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-ed

For 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.

Overlapping instances

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

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

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 application

Check out test/Spec/ClassDict01.hs for a more elaborate example.

Further work

DeriveAll derivation mechanics currently ignores and may break functional dependencies.