-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Generic implementation for QuickCheck's Arbitrary
--   
--   Generic implementations of methods of the <a>Arbitrary</a> class from
--   the QuickCheck library. The approach taken here can lead to diverging
--   instances for recursive types but is safe for non-recursive ones and
--   guarantees flat distribution for constructors of sum-types.
@package generic-arbitrary
@version 0.1.0


-- | Generic implementation of the <a>arbitrary</a> method. Example usage:
--   
--   <pre>
--   data Foo = Foo
--     { _fooX :: X
--     , _fooY :: Y
--     } deriving (Generic)
--   
--   instance Arbitrary Foo where
--     arbitrary = genericArbitrary
--     shrink = genericShrink
--   </pre>
--   
--   The generated <a>arbitrary</a> method is equivalent to
--   
--   <tt>Foo <a>$</a> arbitrary <a>*</a> arbitrary</tt>.
module Test.QuickCheck.Arbitrary.Generic

-- | Random generation and shrinking of values.
class Arbitrary a

-- | A generator for values of the given type.
arbitrary :: Arbitrary a => Gen 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 <a>shrink</a> should try at least three
--   things:
--   
--   <ol>
--   <li>Shrink a term to any of its immediate subterms.</li>
--   <li>Recursively apply <a>shrink</a> to all immediate subterms.</li>
--   <li>Type-specific shrinkings such as replacing a constructor by a
--   simpler constructor.</li>
--   </ol>
--   
--   For example, suppose we have the following implementation of binary
--   trees:
--   
--   <pre>
--   data Tree a = Nil | Branch a (Tree a) (Tree a)
--   </pre>
--   
--   We can then define <a>shrink</a> as follows:
--   
--   <pre>
--   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') &lt;- shrink (x, l, r)]
--   </pre>
--   
--   There are a couple of subtleties here:
--   
--   <ul>
--   <li>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 <tt>Nil</tt>) before smaller ones (such as
--   recursively shrinking the subtrees).</li>
--   <li>It is tempting to write the last line as <tt>[Branch x' l' r' | x'
--   &lt;- shrink x, l' &lt;- shrink l, r' &lt;- shrink r]</tt> but this is
--   the <i>wrong thing</i>! It will force QuickCheck to shrink <tt>x</tt>,
--   <tt>l</tt> and <tt>r</tt> in tandem, and shrinking will stop once
--   <i>one</i> of the three is fully shrunk.</li>
--   </ul>
--   
--   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 <a>genericShrink</a> tries shrinking a
--   term to all of its subterms and, failing that, recursively shrinks the
--   subterms. Using it, we can define <a>shrink</a> as:
--   
--   <pre>
--   shrink x = shrinkToNil x ++ genericShrink x
--     where
--       shrinkToNil Nil = []
--       shrinkToNil (Branch _ l r) = [Nil]
--   </pre>
--   
--   <a>genericShrink</a> is a combination of <a>subterms</a>, which
--   shrinks a term to any of its subterms, and <a>recursivelyShrink</a>,
--   which shrinks all subterms of a term. These may be useful if you need
--   a bit more control over shrinking than <a>genericShrink</a> gives you.
--   
--   A final gotcha: we cannot define <a>shrink</a> as simply
--   <tt><a>shrink</a> x = Nil:<a>genericShrink</a> x</tt> as this shrinks
--   <tt>Nil</tt> to <tt>Nil</tt>, and shrinking will go into an infinite
--   loop.
--   
--   If all this leaves you bewildered, you might try <tt><a>shrink</a> =
--   <a>genericShrink</a></tt> to begin with, after deriving
--   <tt>Generic</tt> for your type. However, if your data type has any
--   special invariants, you will need to check that <a>genericShrink</a>
--   can't break those invariants.
shrink :: Arbitrary a => a -> [a]
genericArbitrary :: (Generic a, GArbitrary ga, ga ~ Rep a) => Gen a

-- | Shrink a term to any of its immediate subterms, and also recursively
--   shrink all subterms.
genericShrink :: (Generic a, RecursivelyShrink (Rep a), GSubterms (Rep a) a) => a -> [a]
instance Test.QuickCheck.Arbitrary.Generic.GArbitrary GHC.Generics.U1
instance Test.QuickCheck.Arbitrary.Arbitrary c => Test.QuickCheck.Arbitrary.Generic.GArbitrary (GHC.Generics.K1 i c)
instance Test.QuickCheck.Arbitrary.Generic.GArbitrary f => Test.QuickCheck.Arbitrary.Generic.GArbitrary (GHC.Generics.M1 i c f)
instance (Test.QuickCheck.Arbitrary.Generic.GArbitrary a, Test.QuickCheck.Arbitrary.Generic.GArbitrary b) => Test.QuickCheck.Arbitrary.Generic.GArbitrary (a GHC.Generics.:*: b)
instance (Test.QuickCheck.Arbitrary.Generic.GArbitrary a, Test.QuickCheck.Arbitrary.Generic.GArbitrary b, GHC.TypeLits.KnownNat (Test.QuickCheck.Arbitrary.Generic.SumLen a), GHC.TypeLits.KnownNat (Test.QuickCheck.Arbitrary.Generic.SumLen b)) => Test.QuickCheck.Arbitrary.Generic.GArbitrary (a GHC.Generics.:+: b)