Copyright | (c) 2010-2011 Patrick Bahr |
---|---|
License | BSD3 |
Maintainer | Patrick Bahr <paba@diku.dk> |
Stability | experimental |
Portability | non-portable (GHC Extensions) |
Safe Haskell | None |
Language | Haskell98 |
This module contains functionality for automatically deriving boilerplate
code using Template Haskell. Examples include instances of Functor
,
Foldable
, and Traversable
.
- derive :: [Name -> Q [Dec]] -> [Name] -> Q [Dec]
- class ShowF f where
- makeShowF :: Name -> Q [Dec]
- class ShowConstr f where
- showConstr :: f a -> String
- makeShowConstr :: Name -> Q [Dec]
- class EqF f where
- makeEqF :: Name -> Q [Dec]
- class EqF f => OrdF f where
- makeOrdF :: Name -> Q [Dec]
- class Functor f
- makeFunctor :: Name -> Q [Dec]
- class Foldable t
- makeFoldable :: Name -> Q [Dec]
- class (Functor t, Foldable t) => Traversable t
- makeTraversable :: Name -> Q [Dec]
- makeHaskellStrict :: Name -> Q [Dec]
- haskellStrict :: (Monad m, HaskellStrict f, f :<: g) => f (TermT m g) -> TermT m g
- haskellStrict' :: (Monad m, HaskellStrict f, f :<: g) => f (TermT m g) -> TermT m g
- class ArbitraryF f where
- arbitraryF' :: Arbitrary v => [(Int, Gen (f v))]
- arbitraryF :: Arbitrary v => Gen (f v)
- shrinkF :: Arbitrary v => f v -> [f v]
- makeArbitraryF :: Name -> Q [Dec]
- class Arbitrary a where
- makeArbitrary :: Name -> Q [Dec]
- class NFData a where
- rnf :: a -> ()
- makeNFData :: Name -> Q [Dec]
- class NFDataF f where
- makeNFDataF :: Name -> Q [Dec]
- smartConstructors :: Name -> Q [Dec]
- smartAConstructors :: Name -> Q [Dec]
- liftSum :: Name -> Q [Dec]
Documentation
derive :: [Name -> Q [Dec]] -> [Name] -> Q [Dec] Source
Helper function for generating a list of instances for a list of named
signatures. For example, in order to derive instances Functor
and
ShowF
for a signature Exp
, use derive as follows (requires Template
Haskell):
$(derive [makeFunctor, makeShowF] [''Exp])
Derive boilerplate instances for compositional data type signatures.
ShowF
Signature printing. An instance ShowF f
gives rise to an instance
Show (Term f)
.
makeShowF :: Name -> Q [Dec] Source
Derive an instance of ShowF
for a type constructor of any first-order kind
taking at least one argument.
class ShowConstr f where Source
Constructor printing.
showConstr :: f a -> String Source
(ShowConstr f, Show p) => ShowConstr ((:&:) f p) | |
(ShowConstr f, ShowConstr g) => ShowConstr ((:+:) f g) |
makeShowConstr :: Name -> Q [Dec] Source
Derive an instance of showConstr
for a type constructor of any first-order kind
taking at least one argument.
EqF
Signature equality. An instance EqF f
gives rise to an instance
Eq (Term f)
.
EqF [] | |
EqF Maybe | |
Eq a0 => EqF ((,) a) | |
(Eq a0, Eq b0) => EqF ((,,) a b) | |
(EqF f, EqF g) => EqF ((:+:) f g) |
|
EqF f => EqF (Cxt h f) | |
(Eq a0, Eq b0, Eq c0) => EqF ((,,,) a b c) | |
(Eq a0, Eq b0, Eq c0, Eq d0) => EqF ((,,,,) a b c d) | |
(Eq a0, Eq b0, Eq c0, Eq d0, Eq e0) => EqF ((,,,,,) a b c d e) | |
(Eq a0, Eq b0, Eq c0, Eq d0, Eq e0, Eq f0) => EqF ((,,,,,,) a b c d e f) | |
(Eq a0, Eq b0, Eq c0, Eq d0, Eq e0, Eq f0, Eq g0) => EqF ((,,,,,,,) a b c d e f g) | |
(Eq a0, Eq b0, Eq c0, Eq d0, Eq e0, Eq f0, Eq g0, Eq h0) => EqF ((,,,,,,,,) a b c d e f g h) | |
(Eq a0, Eq b0, Eq c0, Eq d0, Eq e0, Eq f0, Eq g0, Eq h0, Eq i0) => EqF ((,,,,,,,,,) a b c d e f g h i) |
makeEqF :: Name -> Q [Dec] Source
Derive an instance of EqF
for a type constructor of any first-order kind
taking at least one argument.
OrdF
class EqF f => OrdF f where Source
Signature ordering. An instance OrdF f
gives rise to an instance
Ord (Term f)
.
OrdF [] | |
OrdF Maybe | |
Ord a0 => OrdF ((,) a) | |
(Ord a0, Ord b0) => OrdF ((,,) a b) | |
(OrdF f, OrdF g) => OrdF ((:+:) f g) |
|
OrdF f => OrdF (Cxt h f) | |
(Ord a0, Ord b0, Ord c0) => OrdF ((,,,) a b c) | |
(Ord a0, Ord b0, Ord c0, Ord d0) => OrdF ((,,,,) a b c d) | |
(Ord a0, Ord b0, Ord c0, Ord d0, Ord e0) => OrdF ((,,,,,) a b c d e) | |
(Ord a0, Ord b0, Ord c0, Ord d0, Ord e0, Ord f0) => OrdF ((,,,,,,) a b c d e f) | |
(Ord a0, Ord b0, Ord c0, Ord d0, Ord e0, Ord f0, Ord g0) => OrdF ((,,,,,,,) a b c d e f g) | |
(Ord a0, Ord b0, Ord c0, Ord d0, Ord e0, Ord f0, Ord g0, Ord h0) => OrdF ((,,,,,,,,) a b c d e f g h) | |
(Ord a0, Ord b0, Ord c0, Ord d0, Ord e0, Ord f0, Ord g0, Ord h0, Ord i0) => OrdF ((,,,,,,,,,) a b c d e f g h i) |
makeOrdF :: Name -> Q [Dec] Source
Derive an instance of OrdF
for a type constructor of any first-order kind
taking at least one argument.
Functor
class Functor f
The Functor
class is used for types that can be mapped over.
Instances of Functor
should satisfy the following laws:
fmap id == id fmap (f . g) == fmap f . fmap g
The instances of Functor
for lists, Maybe
and IO
satisfy these laws.
makeFunctor :: Name -> Q [Dec] Source
Derive an instance of Functor
for a type constructor of any first-order
kind taking at least one argument.
Foldable
class Foldable t
Data structures that can be folded.
Minimal complete definition: foldMap
or foldr
.
For example, given a data type
data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
a suitable instance would be
instance Foldable Tree where foldMap f Empty = mempty foldMap f (Leaf x) = f x foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
This is suitable even for abstract types, as the monoid is assumed
to satisfy the monoid laws. Alternatively, one could define foldr
:
instance Foldable Tree where foldr f z Empty = z foldr f z (Leaf x) = f x z foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
makeFoldable :: Name -> Q [Dec] Source
Derive an instance of Foldable
for a type constructor of any first-order
kind taking at least one argument.
Traversable
class (Functor t, Foldable t) => Traversable t
Functors representing data structures that can be traversed from left to right.
Minimal complete definition: traverse
or sequenceA
.
A definition of traverse
must satisfy the following laws:
- naturality
t .
for every applicative transformationtraverse
f =traverse
(t . f)t
- identity
traverse
Identity = Identity- composition
traverse
(Compose .fmap
g . f) = Compose .fmap
(traverse
g) .traverse
f
A definition of sequenceA
must satisfy the following laws:
- naturality
t .
for every applicative transformationsequenceA
=sequenceA
.fmap
tt
- identity
sequenceA
.fmap
Identity = Identity- composition
sequenceA
.fmap
Compose = Compose .fmap
sequenceA
.sequenceA
where an applicative transformation is a function
t :: (Applicative f, Applicative g) => f a -> g a
preserving the Applicative
operations, i.e.
and the identity functor Identity
and composition of functors Compose
are defined as
newtype Identity a = Identity a instance Functor Identity where fmap f (Identity x) = Identity (f x) instance Applicative Indentity where pure x = Identity x Identity f <*> Identity x = Identity (f x) newtype Compose f g a = Compose (f (g a)) instance (Functor f, Functor g) => Functor (Compose f g) where fmap f (Compose x) = Compose (fmap (fmap f) x) instance (Applicative f, Applicative g) => Applicative (Compose f g) where pure x = Compose (pure (pure x)) Compose f <*> Compose x = Compose ((<*>) <$> f <*> x)
(The naturality law is implied by parametricity.)
Instances are similar to Functor
, e.g. given a data type
data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
a suitable instance would be
instance Traversable Tree where traverse f Empty = pure Empty traverse f (Leaf x) = Leaf <$> f x traverse f (Node l k r) = Node <$> traverse f l <*> f k <*> traverse f r
This is suitable even for abstract types, as the laws for <*>
imply a form of associativity.
The superclass instances should satisfy the following:
- In the
Functor
instance,fmap
should be equivalent to traversal with the identity applicative functor (fmapDefault
). - In the
Foldable
instance,foldMap
should be equivalent to traversal with a constant applicative functor (foldMapDefault
).
makeTraversable :: Name -> Q [Dec] Source
Derive an instance of Traversable
for a type constructor of any
first-order kind taking at least one argument.
HaskellStrict
makeHaskellStrict :: Name -> Q [Dec] Source
Derive an instance of HaskellStrict
for a type constructor of any
first-order kind taking at least one argument.
Arbitrary
class ArbitraryF f where Source
Signature arbitration. An instance ArbitraryF f
gives rise to an instance
Arbitrary (Term f)
.
Nothing
arbitraryF' :: Arbitrary v => [(Int, Gen (f v))] Source
arbitraryF :: Arbitrary v => Gen (f v) Source
makeArbitraryF :: Name -> Q [Dec] Source
Derive an instance of ArbitraryF
for a type constructor of any
first-order kind taking at least one argument. It is necessary that
all types that are used by the data type definition are themselves
instances of Arbitrary
.
class Arbitrary a where
Random generation and shrinking of values.
Nothing
A generator for values of the given type.
shrink :: a -> [a]
Produces a (possibly) empty list of all the possible immediate shrinks of the given value. The default implementation returns the empty list, so will not try to shrink the value.
Most implementations of shrink
should try at least three things:
- Shrink a term to any of its immediate subterms.
- Recursively apply
shrink
to all immediate subterms. - Type-specific shrinkings such as replacing a constructor by a simpler constructor.
For example, suppose we have the following implementation of binary trees:
data Tree a = Nil | Branch a (Tree a) (Tree a)
We can then define shrink
as follows:
shrink Nil = [] shrink (Branch x l r) = -- shrink Branch to Nil [Nil] ++ -- shrink to subterms [l, r] ++ -- recursively shrink subterms [Branch x' l' r' | (x', l', r') <- shrink (x, l, r)]
There are a couple of subtleties here:
- QuickCheck tries the shrinking candidates in the order they
appear in the list, so we put more aggressive shrinking steps
(such as replacing the whole tree by
Nil
) before smaller ones (such as recursively shrinking the subtrees). - It is tempting to write the last line as
[Branch x' l' r' | x' <- shrink x, l' <- shrink l, r' <- shrink r]
but this is the wrong thing! It will force QuickCheck to shrinkx
,l
andr
in tandem, and shrinking will stop once one of the three is fully shrunk.
There is a fair bit of boilerplate in the code above.
We can avoid it with the help of some generic functions;
note that these only work on GHC 7.2 and above.
The function genericShrink
tries shrinking a term to all of its
subterms and, failing that, recursively shrinks the subterms.
Using it, we can define shrink
as:
shrink x = shrinkToNil x ++ genericShrink x where shrinkToNil Nil = [] shrinkToNil (Branch _ l r) = [Nil]
genericShrink
is a combination of subterms
, which shrinks
a term to any of its subterms, and recursivelyShrink
, which shrinks
all subterms of a term. These may be useful if you need a bit more
control over shrinking than genericShrink
gives you.
A final gotcha: we cannot define shrink
as simply
as this shrinks shrink
x = Nil:genericShrink
xNil
to Nil
, and shrinking will go into an
infinite loop.
If all this leaves you bewildered, you might try
to begin with,
after deriving shrink
= genericShrink
Generic
and Typeable
for your type. However, if your data type has any
special invariants, you will need to check that genericShrink
can't break those invariants.
class NFData a where
A class of types that can be fully evaluated.
Since: 1.1.0.0
Nothing
rnf :: a -> ()
rnf should reduce its argument to normal form (that is, fully evaluate all sub-components), and then return '()'.
The default implementation of rnf
is
rnf a = a `seq` ()
which may be convenient when defining instances for data types with no unevaluated fields (e.g. enumerations).
DeepSeq
Signature normal form. An instance NFDataF f
gives rise to an instance
NFData (Term f)
.
makeNFDataF :: Name -> Q [Dec] Source
Derive an instance of NFDataF
for a type constructor of any first-order
kind taking at least one argument.
Smart Constructors
smartConstructors :: Name -> Q [Dec] Source
Derive smart constructors for a type constructor of any first-order kind
taking at least one argument. The smart constructors are similar to the
ordinary constructors, but an inject
is automatically inserted.
Smart Constructors w/ Annotations
smartAConstructors :: Name -> Q [Dec] Source
Derive smart constructors with products for a type constructor of any
parametric kind taking at least one argument. The smart constructors are
similar to the ordinary constructors, but an injectA
is automatically
inserted.