-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Generic implementation for QuickCheck's Arbitrary
--
-- Generic implementations of methods of the Arbitrary 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.2.2
-- | Generic implementation of the arbitrary method. Example usage:
--
--
-- data Foo = Foo
-- { _fooX :: X
-- , _fooY :: Y
-- } deriving (Generic)
--
-- instance Arbitrary Foo where
-- arbitrary = genericArbitrary
-- shrink = genericShrink
--
--
-- This instance can also be derived using DerivingVia language extension
--
--
-- data Foo = Foo
-- { _fooX :: X
-- , _fooY :: Y
-- } deriving (Generic)
-- deriving (Arbitrary) via GenericArbitrary Foo
--
--
-- The generated arbitrary method is equivalent to
--
-- Foo $ arbitrary * arbitrary.
module Test.QuickCheck.Arbitrary.Generic
newtype GenericArbitrary a
GenericArbitrary :: a -> GenericArbitrary a
[unGenericArbitrary] :: GenericArbitrary a -> a
-- | Random generation and shrinking of values.
--
-- QuickCheck provides Arbitrary instances for most types in
-- base, except those which incur extra dependencies. For a
-- wider range of Arbitrary instances see the
-- quickcheck-instances package.
class Arbitrary a
-- | A generator for values of the given type.
--
-- It is worth spending time thinking about what sort of test data you
-- want - good generators are often the difference between finding bugs
-- and not finding them. You can use sample, label and
-- classify to check the quality of your test data.
--
-- There is no generic arbitrary implementation included because
-- we don't know how to make a high-quality one. If you want one,
-- consider using the testing-feat or generic-random
-- packages.
--
-- The QuickCheck manual goes into detail on how to write good
-- generators. Make sure to look at it, especially if your type is
-- recursive!
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. If your data type has no special invariants, you can
-- enable shrinking by defining shrink = genericShrink,
-- but by customising the behaviour of shrink you can often get
-- simpler counterexamples.
--
-- Most implementations of shrink should try at least three
-- things:
--
--
-- - Shrink a term to any of its immediate subterms. You can use
-- subterms to do this.
-- - Recursively apply shrink to all immediate subterms. You can
-- use recursivelyShrink to do this.
-- - 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 shrink x,
-- l and r 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. 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
-- shrink x = Nil:genericShrink x as this shrinks
-- Nil to Nil, and shrinking will go into an infinite
-- loop.
--
-- If all this leaves you bewildered, you might try shrink =
-- genericShrink to begin with, after deriving
-- Generic for your type. However, if your data type has any
-- special invariants, you will need to check that genericShrink
-- 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 GHC.Classes.Eq a => GHC.Classes.Eq (Test.QuickCheck.Arbitrary.Generic.GenericArbitrary a)
instance GHC.Show.Show a => GHC.Show.Show (Test.QuickCheck.Arbitrary.Generic.GenericArbitrary a)
instance (Test.QuickCheck.Arbitrary.Generic.GArbitrary a, Test.QuickCheck.Arbitrary.Generic.GArbitrary b, GHC.TypeNats.KnownNat (Test.QuickCheck.Arbitrary.Generic.SumLen a), GHC.TypeNats.KnownNat (Test.QuickCheck.Arbitrary.Generic.SumLen b)) => Test.QuickCheck.Arbitrary.Generic.GArbitrary (a GHC.Generics.:+: b)
instance (GHC.Generics.Generic a, Test.QuickCheck.Arbitrary.Generic.GArbitrary (GHC.Generics.Rep a), Test.QuickCheck.Arbitrary.RecursivelyShrink (GHC.Generics.Rep a), Test.QuickCheck.Arbitrary.GSubterms (GHC.Generics.Rep a) a) => Test.QuickCheck.Arbitrary.Arbitrary (Test.QuickCheck.Arbitrary.Generic.GenericArbitrary 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)