Module documentation for 2.5.18

This version can be pinned in stack with:[email protected]:81cae1f18874c2e50402616a1e8909aeadebfe54baa365a1c99badbe76baa0fb,3388

Exact lookup

Data

Data.Derive

Data.Derive.All

Data.Derive.Arbitrary

Data.Derive.ArbitraryOld

Data.Derive.Arities

Data.Derive.Binary

Data.Derive.BinaryDefer

Data.Derive.Bounded

Data.Derive.Class

Data.Derive.Class.Arities

Data.Derive.Class.Default

Data.Derive.DSL

Data.Derive.DSL.Apply

Data.Derive.DSL.DSL

Data.Derive.DSL.Derive

Data.Derive.DSL.HSE

Data.Derive.DSL.SYB

Data.Derive.Data

Data.Derive.DataAbstract

Data.Derive.Default

Data.Derive.Enum

Data.Derive.EnumCyclic

Data.Derive.Eq

Data.Derive.Fold

Data.Derive.Foldable

Data.Derive.From

Data.Derive.Functor

Data.Derive.Has

Data.Derive.Instance

Data.Derive.Instance.Arities

Data.Derive.Internal

Data.Derive.Internal.Derivation

Data.Derive.Is

Data.Derive.JSON

Data.Derive.LazySet

Data.Derive.Lens

Data.Derive.Monoid

Data.Derive.NFData

Data.Derive.Ord

Data.Derive.Read

Data.Derive.Ref

Data.Derive.Serial

Data.Derive.Serialize

Data.Derive.Set

Data.Derive.Show

Data.Derive.Traversable

Data.Derive.Typeable

Data.Derive.UniplateDirect

Data.Derive.UniplateTypeable

Data.Derive.Update

Data.DeriveDSL

Data.DeriveMain

Data.DeriveTH

Language

Language.Haskell

Language.Haskell.Convert

Language.Haskell.TH

Language.Haskell.TH.All

Language.Haskell.TH.Compat

Language.Haskell.TH.Data

Language.Haskell.TH.ExpandSynonym

Language.Haskell.TH.FixedPpr

Language.Haskell.TH.Helper

Language.Haskell.TH.Peephole

Derive

Data.Derive is a library and a tool for deriving instances for Haskell programs. It is designed to work with custom derivations, SYB and Template Haskell mechanisms. The tool requires GHC, but the generated code is portable to all compilers. We see this tool as a competitor to DrIFT.

Now running derive on the program containing this code will generate appropriate instances. How do you combine these instances back into the code? There are various mechanisms supported.

Appending to the module

One way is to append the text to the bottom of the module, this can be done by passing the –append flag. If this is done, Derive will generate the required instances and place them at the bottom of the file, along with a checksum. Do not modify these instances.

As a GHC preprocessor

To use Derive as a GHC preprocessor, add the following line at the top of the source file:

{-# OPTIONS_GHC -F -pgmFderive -optF-F #-}

This instructs GHC to apply a preprocessor (-F), and to use the preprocessor derive -F.

Using CPP

One way is to use CPP. Ensure your compiler is set up for compiling with the C Pre Processor. For example:

Side-by-side Modules

Here you ask for the output to go to a particular file, give a specific module name and import this module. This will only work if the data structure is exported non-abstractly.

Using Template Haskell Derivations

One of Derive’s advantages over DrIFT is support for Template Haskell (abbreviated TH). Derive can be invoked automatically during the compilation process, and transparently supports deriving across module boundaries. The main disadvantage of TH-based deriving is that it is only portable to compilers that support TH; currently that is GHC only.

We need to tell the compiler to insert the instance using the TH splice construct, $( … ) (the spaces are optional). The splice causes the compiler to run the function derive (exported from Data.DeriveTH), passing arguments makeFooBar and ’’Color. The second argument deserves more explanation; it is a quoted symbol, somewhat like a quoted symbol in Lisp and with deliberately similar syntax. (Two apostrophes are used to specify that this name is to be resolved as a type constructor; just ’Color would look for a data constructor named Color.)

Writing a New Derivation

There are two methods for writing a new derivation, guessing or coding. The guessing method is substantially easier if it will work for you, but is limited to derivations with the following properties:

Inductive - each derivation must be similar to the previous one. Binary does not have this property as a 1 item derivation does not have a tag, but a 2 item derivation does.

Not inductive on the type - it must be an instance for the constructors, not for the type. Typeable violates this property by inducting on the free variables in the data type.

Not type based - the derivation must not change based on the types of the fields. Play and Functor both behave differently given differently typed fields.

Not record based - the derivation must not change on record fields. Show outputs the fields, so this is not allowed.

If however your instance does meet these properties, you can use derivation by guess. Many instances do meet these conditions, for examples see: Eq, Ord, Data, Serial etc. If however you need to code the derivation manually see examples such as Update and Functor.

Modifying Derive

The standard sequence for testing Derive is:

$ ghci Main.hs
:main --generate
:reload
:main --test

The --generate option will automatically generate DSL’s for derivations derived by example. The --test option runs all test comparisons and then loads the file with Template Haskell.

Coding a new derivation

My best suggestion, start with a similar instance, i.e. to make Eq2 from Eq do: