derive 2.5.17 → 2.5.18

raw patch · 10 files changed

+201/−276 lines, 10 filesPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

Files

• CHANGES.txt +2/−0
• Data/Derive/Class/Arities.hs +5/−5
• Data/Derive/Class/Default.hs +5/−5
• Data/Derive/Internal/Instance.hs +1/−2
• Data/Derive/Read.hs +4/−3
• Derive/Generate.hs +4/−6
• Derive/Test.hs +1/−1
• README.md +177/−0
• derive.cabal +2/−2
• derive.htm +0/−252

@@ -1,5 +1,7 @@ Changelog for Derive +2.5.18+    #4, fix the read instance for nullary constructors 2.5.17     Upgrade to haskell-src-exts-1.16     Remove GHC 7.2 support

@@ -1,5 +1,5 @@-
-module Data.Derive.Class.Arities where
-
-class Arities a where
-    arities :: a -> [Int]
++module Data.Derive.Class.Arities where++class Arities a where+    arities :: a -> [Int]

@@ -1,5 +1,5 @@-
-module Data.Derive.Class.Default where
-
-class Default a where
-    def :: a
++module Data.Derive.Class.Default where++class Default a where+    def :: a

@@ -11,7 +11,6 @@  data Ctor = Ctor     {ctorType :: Box-    ,ctorIndex :: Int     ,ctorRep :: Constr}  @@ -31,5 +30,5 @@ d_dataCtors :: Data a => a -> [Ctor] d_dataCtors x     | not $ isAlgType t = error "d_dataCtors only works on algebraic data types"-    | otherwise = zipWith (Ctor $ Box x) [0..] $ dataTypeConstrs t+    | otherwise = map (Ctor $ Box x) $ dataTypeConstrs t     where t = dataTypeOf x

@@ -1,3 +1,4 @@+{-# LANGUAGE PatternGuards #-} {-|     Derives @Read@.  This is as defined by the Haskell report, except     there is no support for infix constructors.  If you attempt to@@ -21,7 +22,7 @@ test :: Sample instance Read a => Read (Sample a) where     readsPrec p0 r =-        readParen (p0 > 10) (\r0 ->+        readParen False (\r0 ->             [ (First, r1)             | ("First", r1) <- lex r0]) r         ++@@ -111,8 +112,8 @@ hasFields c = any ((/=) "" . fst) $ ctorDeclFields c  splice :: FullDataDecl -> Exp -> Exp-splice d (H.App x (H.Lit (H.Int y))) | x ~= "bracket" =-    if hasFields $ getCtor d y+splice d (H.App x (H.Lit (H.Int y))) | x ~= "bracket", let c = getCtor d y =+    if hasFields c || null (ctorDeclFields c)     then con "False"     else Paren $ InfixApp (var "p0") (QVarOp $ UnQual $ Symbol ">") (H.Lit $ H.Int 10) 

@@ -26,7 +26,7 @@         ["import Data.Derive." ++ x ++ replicate (4 + n - length x) ' ' ++ "as D" | x <- names] ++         ["derivations :: [Derivation]"         ,"derivations = [make" ++ concat (intersperse ",make" names) ++ "]"]-    writeGenerated "derive.htm" $ ["-->"] ++ lis ++ ["<!--"]+    writeGenerated "README.md" $ ["-->",""] ++ lis ++ ["","<!--"]     writeGenerated "derive.cabal" $ map ("        Data.Derive."++) names  @@ -69,11 +69,9 @@             error $ "Previously generated dynamic instance can not be regenerated, " ++ name      let imp = listToMaybe $ srcImport src-    return $ concat $-        ["<li>"-        ,"<b><a href='" ++ instUrl name imp ++ "'>" ++ name ++ "</a></b>"] ++-        [" - from the library <a href='" ++ pkgUrl pkg ++ "'>" ++ pkg ++ "</a>" | Just imp <- [imp], let pkg = fromMaybe "base" $ importPkg imp] ++-        ["</li>"]+    return $+        "* **[" ++ name ++ "](" ++ instUrl name imp ++ ")**" +++        concat [" - from the library [" ++ pkg ++ "](" ++ pkgUrl pkg ++ ")" | Just imp <- [imp], let pkg = fromMaybe "base" $ importPkg imp]  pkgUrl x = "http://hackage.haskell.org/package/" ++ x 

@@ -7,7 +7,7 @@ import Data.Maybe import Data.List import System.FilePath-import System.Cmd+import System.Process import System.Exit import Control.Arrow import Data.Derive.All

@@ -0,0 +1,177 @@+# Derive [![Hackage version](https://img.shields.io/hackage/v/derive.svg?style=flat)](http://hackage.haskell.org/package/derive) [![Build Status](http://img.shields.io/travis/ndmitchell/derive.svg?style=flat)](https://travis-ci.org/ndmitchell/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 <a href="http://repetae.net/~john/computer/haskell/DrIFT/">DrIFT</a>.++This document proceeds as follows:++* Obtaining and Installing Data.Derive+* Supported Derivations+* Using the Derive Program+* Using Template Haskell Derivations+* Writing a New Derivation++### Acknowledgements++Thanks to everyone who has submitted patches and given assistance, including: Twan van Laarhoven, Spencer Janssen, Andrea Vezzosi, Samuel Bronson, Joel Raymont, Benedikt Huber, Stefan O'Rear, Robin Green, Bertram Felgenhauer.+++## Obtaining and Installing Data.Derive++Installation follows the standard pattern of any Haskell library or program, type <tt>cabal update</tt> to update your local hackage database, then <tt>cabal install derive</tt> to install Derive.+++## Supported Derivations++Data.Derive is not limited to any prebuild set of derivations, see later for howto add your own. Out of the box, we provide instances for the following libraries.++<!--+-- GENERATED START+-->++* **[Arbitrary](http://hackage.haskell.org/packages/archive/QuickCheck/latest/doc/html/Test-QuickCheck.html#t%3AArbitrary)** - from the library [QuickCheck](http://hackage.haskell.org/package/QuickCheck)+* **[ArbitraryOld](http://hackage.haskell.org/packages/archive/QuickCheck/1.2.0.0/doc/html/Test-QuickCheck.html#t%3AArbitraryOld)** - from the library [QuickCheck-1.2.0.0](http://hackage.haskell.org/package/QuickCheck-1.2.0.0)+* **[Arities](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Class-Arities.html#t%3AArities)** - from the library [derive](http://hackage.haskell.org/package/derive)+* **[Binary](http://hackage.haskell.org/packages/archive/binary/latest/doc/html/Data-Binary.html#t%3ABinary)** - from the library [binary](http://hackage.haskell.org/package/binary)+* **[BinaryDefer](http://hackage.haskell.org/packages/archive/binarydefer/latest/doc/html/Data-Binary-Defer.html#t%3ABinaryDefer)** - from the library [binarydefer](http://hackage.haskell.org/package/binarydefer)+* **[Bounded](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3ABounded)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Data](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Data.html#t%3AData)** - from the library [base](http://hackage.haskell.org/package/base)+* **[DataAbstract](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Data.html#t%3ADataAbstract)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Default](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Class-Default.html#t%3ADefault)** - from the library [derive](http://hackage.haskell.org/package/derive)+* **[Enum](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AEnum)** - from the library [base](http://hackage.haskell.org/package/base)+* **[EnumCyclic](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AEnum)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Eq](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AEq)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Fold](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Fold.html)**+* **[Foldable](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Foldable.html#t%3AFoldable)** - from the library [base](http://hackage.haskell.org/package/base)+* **[From](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-From.html)**+* **[Functor](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AFunctor)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Has](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Has.html)**+* **[Is](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Is.html)**+* **[JSON](http://hackage.haskell.org/packages/archive/json/latest/doc/html/Text-JSON.html#t%3AJSON)** - from the library [json](http://hackage.haskell.org/package/json)+* **[LazySet](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-LazySet.html)**+* **[Lens](http://hackage.haskell.org/packages/archive/data/lens/doc/html/Data-Lens-Common.html#t%3ALens)** - from the library [data-lens](http://hackage.haskell.org/package/data-lens)+* **[Monoid](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Monoid.html#t%3AMonoid)** - from the library [base](http://hackage.haskell.org/package/base)+* **[NFData](http://hackage.haskell.org/packages/archive/deepseq/latest/doc/html/Control-DeepSeq.html#t%3ANFData)** - from the library [deepseq](http://hackage.haskell.org/package/deepseq)+* **[Ord](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AOrd)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Read](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3ARead)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Ref](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Ref.html)**+* **[Serial](http://hackage.haskell.org/packages/archive/smallcheck/latest/doc/html/Test-SmallCheck.html#t%3ASerial)** - from the library [smallcheck](http://hackage.haskell.org/package/smallcheck)+* **[Serialize](http://hackage.haskell.org/packages/archive/cereal/latest/doc/html/Data-Serialize.html#t%3ASerialize)** - from the library [cereal](http://hackage.haskell.org/package/cereal)+* **[Set](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Set.html)**+* **[Show](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AShow)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Traversable](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Traversable.html#t%3ATraversable)** - from the library [base](http://hackage.haskell.org/package/base)+* **[Typeable](http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Typeable.html#t%3ATypeable)** - from the library [base](http://hackage.haskell.org/package/base)+* **[UniplateDirect](http://hackage.haskell.org/packages/archive/uniplate/latest/doc/html/Data-Generics-Uniplate-Direct.html#t%3AUniplateDirect)** - from the library [uniplate](http://hackage.haskell.org/package/uniplate)+* **[UniplateTypeable](http://hackage.haskell.org/packages/archive/uniplate/latest/doc/html/Data-Generics-Uniplate-Typeable.html#t%3AUniplateTypeable)** - from the library [uniplate](http://hackage.haskell.org/package/uniplate)+* **[Update](http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Update.html)**++<!--+-- GENERATED STOP+-->++## Using the Derive program++Let's imagine we've defined a data type:++    data Color = RGB Int Int Int+               | CMYK Int Int Int Int+               deriving (Eq, Show)++Now we wish to extend this to derive <tt>Binary</tt> and change to defining <tt>Eq</tt> using our library. To do this we simply add to the <tt>deriving</tt> clause.++    data Color = RGB Int Int Int+               | CMYK Int Int Int Int+               deriving (Show {-! Eq, Binary !-})++Or alternatively write:++    {-!+    deriving instance Eq Color+    deriving instance Binary Color+    !-}++Now running <tt>derive</tt> 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 <tt>--append</tt> 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 (<tt>-F</tt>), and to use the preprocessor <tt>derive -F</tt>.++### Using CPP++One way is to use CPP. Ensure your compiler is set up for compiling with the C Pre Processor. For example:++    {-# LANGUAGE CPP #-}+    {-# OPTIONS_DERIVE --output=file.h #-}++    module ModuleName where+    +    #include "file.h"++### Side-by-side Modules++If you had Colour.Type, and wished to place the Binary instance in Colour.Binary, this can be done with:++    {-# OPTIONS_DERIVE --output=Binary.hs --module=Colour.Binary --import #-}++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</h2>++One of Derive's advantages over DrIFT is support for <a href="http://www.haskell.org/th/">Template Haskell</a> (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.++To use the TH deriving system, with the same example as before:++    {-# LANGUAGE TemplateHaskell #-}+    import Data.DeriveTH+    import Data.Binary+    +    data Color = RGB Int Int Int+               | CMYK Int Int Int Int+               deriving (Show)+    +    $( derive makeEq ''Color )+    $( derive makeBinary ''Color )++We need to tell the compiler to insert the instance using the TH <em>splice</em> construct, <tt>$( ... )</tt> (the spaces are optional).  The splice causes the compiler to run the function <tt>derive</tt> (exported from <tt>Data.DeriveTH</tt>), passing arguments <tt>makeFooBar</tt> and <tt>''Color</tt>.  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 <tt>'Color</tt> would look for a <i>data</i> constructor named <tt>Color</tt>.)++## 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. <tt>Binary</tt> 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. <tt>Typeable</tt> 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. <tt>Play</tt> and <tt>Functor</tt> both behave differently given differently typed fields.+* Not record based - the derivation must not change on record fields. <tt>Show</tt> 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: <tt>Eq</tt>, <tt>Ord</tt>, <tt>Data</tt>, <tt>Serial</tt> etc. If however you need to code the derivation manually see examples such as <tt>Update</tt> and <tt>Functor</tt>.++### 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:++* Copy `Data/Derive/Eq.hs` to `Data/Derive/Eq2.hs`+* Rename some of the bits in `Eq2.hs` from `Eq`+* `ghci` -- load derive+* `:main` --generate    -- this adds Eq2.hs to the .cabal/All.hs files etc+* `:reload`             -- reload with Eq2.hs++Now fix up `Eq2.hs` appropriately.

@@ -1,7 +1,7 @@ cabal-version:  >= 1.6 build-type:     Default name:           derive-version:        2.5.17+version:        2.5.18 build-type:     Simple copyright:      Neil Mitchell 2006-2014 author:         Neil Mitchell <ndmitchell@gmail.com>@@ -18,7 +18,7 @@     The tool requires GHC, but the generated code is portable to all compilers.     We see this tool as a competitor to DrIFT. extra-source-files:-    derive.htm+    README.md     CHANGES.txt tested-with:        GHC==7.8.2, GHC==7.6.3, GHC==7.4.2 

@@ -1,252 +0,0 @@-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"-        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">-<html>-    <head>-        <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />-        <title>Data.Derive: A User Manual</title>-        <style type="text/css">-pre {-    border: 2px solid gray;-    padding: 1px;-    padding-left: 5px;-    margin-left: 10px;-    background-color: #eee;-}--pre.define {-    background-color: #ffb;-    border-color: #cc0;-}--body {-    font-family: sans-serif;-}--h1, h2, h3 {-    font-family: serif;-}--h1 {-    color: rgb(23,54,93);-    border-bottom: 1px solid rgb(79,129,189);-    padding-bottom: 2px;-    font-variant: small-caps;-    text-align: center;-}--a {-    color: rgb(54,95,145);-}--h2 {-    color: rgb(54,95,145);-}--h3 {-    color: rgb(79,129,189);-}-        </style>-    </head>-    <body>--<h1>Data.Derive: A User Manual</h1>--<p style="text-align:right;margin-bottom:25px;">-    by <a href="http://community.haskell.org/~ndm/">Neil Mitchell</a>-</p>--<p>-    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 <a href="http://repetae.net/~john/computer/haskell/DrIFT/">DrIFT</a>.-</p>-<p>-    This document proceeds as follows:-</p>-<ol>-    <li>Obtaining and Installing Data.Derive</li>-    <li>Supported Derivations</li>-    <li>Using the Derive Program</li>-    <li>Using Template Haskell Derivations</li>-    <li>Writing a New Derivation</li>-</ol>--<h3>Acknowledgements</h3>--<p>-    Thanks to everyone who has submitted patches and given assistance, including: Twan van Laarhoven, Spencer Janssen, Andrea Vezzosi, Samuel Bronson, Joel Raymont, Benedikt Huber, Stefan O'Rear, Robin Green, Bertram Felgenhauer.-</p>---<h2>Obtaining and Installing Data.Derive</h2>--<p>-	Installation follows the standard pattern of any Haskell library or program, type <tt>cabal update</tt> to update your local hackage database, then <tt>cabal install derive</tt> to install Derive.-</p>---<h2>Supported Derivations</h2>--<p>-	Data.Derive is not limited to any prebuild set of derivations, see later for how to add your own. Out of the box, we provide instances for the following libraries.-</p>--<!----- GENERATED START--->-<li><b><a href='http://hackage.haskell.org/packages/archive/QuickCheck/latest/doc/html/Test-QuickCheck.html#t%3AArbitrary'>Arbitrary</a></b> - from the library <a href='http://hackage.haskell.org/package/QuickCheck'>QuickCheck</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/QuickCheck/1.2.0.0/doc/html/Test-QuickCheck.html#t%3AArbitraryOld'>ArbitraryOld</a></b> - from the library <a href='http://hackage.haskell.org/package/QuickCheck-1.2.0.0'>QuickCheck-1.2.0.0</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Class-Arities.html#t%3AArities'>Arities</a></b> - from the library <a href='http://hackage.haskell.org/package/derive'>derive</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/binary/latest/doc/html/Data-Binary.html#t%3ABinary'>Binary</a></b> - from the library <a href='http://hackage.haskell.org/package/binary'>binary</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/binarydefer/latest/doc/html/Data-Binary-Defer.html#t%3ABinaryDefer'>BinaryDefer</a></b> - from the library <a href='http://hackage.haskell.org/package/binarydefer'>binarydefer</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3ABounded'>Bounded</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Data.html#t%3AData'>Data</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Data.html#t%3ADataAbstract'>DataAbstract</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Class-Default.html#t%3ADefault'>Default</a></b> - from the library <a href='http://hackage.haskell.org/package/derive'>derive</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AEnum'>Enum</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AEnum'>EnumCyclic</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AEq'>Eq</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Fold.html'>Fold</a></b></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Foldable.html#t%3AFoldable'>Foldable</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-From.html'>From</a></b></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AFunctor'>Functor</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Has.html'>Has</a></b></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Is.html'>Is</a></b></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/json/latest/doc/html/Text-JSON.html#t%3AJSON'>JSON</a></b> - from the library <a href='http://hackage.haskell.org/package/json'>json</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-LazySet.html'>LazySet</a></b></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/data/lens/doc/html/Data-Lens-Common.html#t%3ALens'>Lens</a></b> - from the library <a href='http://hackage.haskell.org/package/data-lens'>data-lens</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Monoid.html#t%3AMonoid'>Monoid</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/deepseq/latest/doc/html/Control-DeepSeq.html#t%3ANFData'>NFData</a></b> - from the library <a href='http://hackage.haskell.org/package/deepseq'>deepseq</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AOrd'>Ord</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3ARead'>Read</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Ref.html'>Ref</a></b></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/smallcheck/latest/doc/html/Test-SmallCheck.html#t%3ASerial'>Serial</a></b> - from the library <a href='http://hackage.haskell.org/package/smallcheck'>smallcheck</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/cereal/latest/doc/html/Data-Serialize.html#t%3ASerialize'>Serialize</a></b> - from the library <a href='http://hackage.haskell.org/package/cereal'>cereal</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Set.html'>Set</a></b></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Prelude.html#t%3AShow'>Show</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Traversable.html#t%3ATraversable'>Traversable</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/base/latest/doc/html/Data-Typeable.html#t%3ATypeable'>Typeable</a></b> - from the library <a href='http://hackage.haskell.org/package/base'>base</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/uniplate/latest/doc/html/Data-Generics-Uniplate-Direct.html#t%3AUniplateDirect'>UniplateDirect</a></b> - from the library <a href='http://hackage.haskell.org/package/uniplate'>uniplate</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/uniplate/latest/doc/html/Data-Generics-Uniplate-Typeable.html#t%3AUniplateTypeable'>UniplateTypeable</a></b> - from the library <a href='http://hackage.haskell.org/package/uniplate'>uniplate</a></li>-<li><b><a href='http://hackage.haskell.org/packages/archive/derive/latest/doc/html/Data-Derive-Update.html'>Update</a></b></li>-<!----- GENERATED STOP--->--<h2>Using the Derive program</h2>--<p>-	Let's imagine we've defined a data type:-</p>-<pre>-data Color = RGB Int Int Int-           | CMYK Int Int Int Int-           deriving (Eq, Show)-</pre>-<p>-	Now we wish to extend this to derive <tt>Binary</tt> and change to defining <tt>Eq</tt> using our library. To do this we simply add to the <tt>deriving</tt> clause.-</p>-<pre>-data Color = RGB Int Int Int-           | CMYK Int Int Int Int-           deriving (Show {-! Eq, Binary !-})-</pre>-<p>-	Or alternatively write:-</p>-<pre>-{-!-deriving instance Eq Color-deriving instance Binary Color-!-}-</pre>-<p>-	Now running <tt>derive</tt> 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.-</p>--<h3>Appending to the module</h3>--<p>-	One way is to append the text to the bottom of the module, this can be done by passing the <tt>--append</tt> 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.-</p>--<h3>As a GHC preprocessor</h3>--<p>-	To use Derive as a GHC preprocessor, add the following line at the top of the source file:-</p>-<pre>-{-# OPTIONS_GHC -F -pgmFderive -optF-F #-}-</pre>-<p>-	This instructs GHC to apply a preprocessor (<tt>-F</tt>), and to use the preprocessor <tt>derive -F</tt>.-</p>--<h3>Using CPP</h3>--<p>-	One way is to use CPP. Ensure your compiler is set up for compiling with the C Pre Processor. For example:-</p>-<pre>-{-# LANGUAGE CPP #-}-{-# OPTIONS_DERIVE --output=file.h #-}--module ModuleName where--#include "file.h"-</pre>--<h3>Side-by-side Modules</h3>--<p>-	If you had Colour.Type, and wished to place the Binary instance in Colour.Binary, this can be done with:-</p>-<pre>-{-# OPTIONS_DERIVE --output=Binary.hs --module=Colour.Binary --import #-}-</pre>-<p>-	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.-</p>--<h2>Using Template Haskell Derivations</h2>--<p>-	One of Derive's advantages over DrIFT is support for <a href="http://www.haskell.org/th/">Template Haskell</a> (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.-</p>--<p>-	To use the TH deriving system, with the same example as before:-</p>--<pre>-{-# LANGUAGE TemplateHaskell #-}-import Data.DeriveTH-import Data.Binary--data Color = RGB Int Int Int-           | CMYK Int Int Int Int-           deriving (Show)--$( derive makeEq ''Color )-$( derive makeBinary ''Color )-</pre>--<p>-	We need to tell the compiler to insert the instance using the TH <em>splice</em> construct, <tt>$( ... )</tt> (the spaces are optional).  The splice causes the compiler to run the function <tt>derive</tt> (exported from <tt>Data.DeriveTH</tt>), passing arguments <tt>makeFooBar</tt> and <tt>''Color</tt>.  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 <tt>'Color</tt> would look for a <i>data</i> constructor named <tt>Color</tt>.)-</p>--<h2>Writing a New Derivation</h2>--<p>-	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:-</p>-<ul>-	<li>Inductive - each derivation must be similar to the previous one. <tt>Binary</tt> does not have this property as a 1 item derivation does not have a tag, but a 2 item derivation does.</li>-	<li>Not inductive on the type - it must be an instance for the constructors, not for the type. <tt>Typeable</tt> violates this property by inducting on the free variables in the data type.</li>-	<li>Not type based - the derivation must not change based on the types of the fields. <tt>Play</tt> and <tt>Functor</tt> both behave differently given differently typed fields.</li>-	<li>Not record based - the derivation must not change on record fields. <tt>Show</tt> outputs the fields, so this is not allowed.</li>-</ul>-<p>-	If however your instance does meet these properties, you can use derivation by guess. Many instances do meet these conditions, for examples see: <tt>Eq</tt>, <tt>Ord</tt>, <tt>Data</tt>, <tt>Serial</tt> etc. If however you need to code the derivation manually see examples such as <tt>Update</tt> and <tt>Functor</tt>.-</p>--    </body>-</html>