-- 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 mutually recursive types but is safe for simply
--   recursive ones and guarantees flat distribution for constructors of
--   sum-types.
@package generic-arbitrary
@version 1.0.0


-- | This module is a 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>
--   
--   This instance can also be derived using DerivingVia language extension
--   
--   <pre>
--   data Foo = Foo
--     { _fooX :: X
--     , _fooY :: Y
--     } deriving (Generic)
--       deriving (Arbitrary) via GenericArbitrary Foo
--   </pre>
--   
--   The generated <a>arbitrary</a> method is equivalent to
--   
--   <pre>
--   Foo <a>&lt;$&gt;</a> arbitrary <a>&lt;*&gt;</a> arbitrary
--   </pre>
--   
--   .
--   
--   It can also handle a recursive types problem. Assuming a type
--   
--   <pre>
--   data R = R R
--     deriving Generic
--   </pre>
--   
--   there is no instance
--   
--   <pre>
--   instance Arbitrary R where
--     arbitrary = genericArbitrary
--     shrink = genericShrink
--   </pre>
--   
--   If you try to compile this you will get a type level error
--   
--   <pre>
--   • R refers to itself in all constructors
--   </pre>
--   
--   Which means that there is no finite term for <tt>R</tt> because it is
--   recursive. But, if you correct the definition of <tt>R</tt> like this.
--   
--   <pre>
--   data R = R R | F
--     deriving Generic
--   </pre>
--   
--   Then it will compile. And the <tt>arbitrary</tt> generated will not
--   hang forever, because it respects the <tt>size</tt> parameter.
--   
--   There is a limitation of recursion detection:
--   
--   <pre>
--   data R1 = R1 R2
--     deriving (Eq, Ord, Show, Generic)
--     deriving anyclass NFData
--     deriving Arbitrary via (GenericArbitrary R1)
--   
--   data R2 = R2 R1
--     deriving (Eq, Ord, Show, Generic)
--     deriving anyclass NFData
--     deriving Arbitrary via (GenericArbitrary R2)
--   </pre>
--   
--   This code will compile and the <tt>arbitrary</tt> generated will
--   always hang. Yes, there is a problem with mutually recursive types.
--   
--   Now lets see an example of datatype with parameters
--   
--   <pre>
--   data A a = A a
--     deriving (Eq, Ord, Show)
--     deriving anyclass NFData
--     deriving (Generic)
--   
--   instance (Arbitrary a) =&gt; Arbitrary (A a) where
--     arbitrary = genericArbitrary
--     shrink = genericShrink
--   </pre>
--   
--   It should work from first glance, but when compile it will throw an
--   error:
--   
--   <pre>
--   • Could not deduce (Test.QuickCheck.Arbitrary.Generic.GArbitrary
--                         (A a)
--                         (GHC.Generics.D1
--                            ('GHC.Generics.MetaData <a>A</a> <a>ParametersTest</a> "main" 'False)
--                            (GHC.Generics.C1
--                               ('GHC.Generics.MetaCons <a>A</a> 'GHC.Generics.PrefixI 'False)
--                               (GHC.Generics.S1
--                                  ('GHC.Generics.MetaSel
--                                     'Nothing
--                                     'GHC.Generics.NoSourceUnpackedness
--                                     'GHC.Generics.NoSourceStrictness
--                                     'GHC.Generics.DecidedLazy)
--                                  (GHC.Generics.Rec0 a))))
--                         (TypesDiffer (A a) a))
--       arising from a use of ‘genericArbitrary’
--   </pre>
--   
--   Here the <tt>TypesDiffer</tt> is a type familty dealing with recursive
--   types and helping us to eliminate inproper instances. To convince the
--   compiller, that the <tt>a</tt> parameter is not an <tt>A a</tt> we
--   must fix the instance with additional constraint
--   
--   <pre>
--   instance (Arg (A a) a, Arbitrary a) =&gt; Arbitrary (A a) where
--     arbitrary = genericArbitrary
--     shrink = genericShrink
--   </pre>
--   
--   Now everything compiles and works as expected.
module Test.QuickCheck.Arbitrary.Generic
genericArbitrary :: forall a ga some. (Generic a, GArbitrary a ga some, ga ~ Rep a) => Gen a

-- | Newtype for <tt>DerivingVia</tt>
--   
--   Usage:
--   
--   <pre>
--   data Foo = Foo
--     { _fooX :: X
--     , _fooY :: Y
--     } deriving (Generic)
--       deriving (Arbitrary) via GenericArbitrary Foo
--   </pre>
newtype GenericArbitrary a
GenericArbitrary :: a -> GenericArbitrary a
[unGenericArbitrary] :: GenericArbitrary a -> a

-- | Constraint helper for types with parameters
--   
--   Usage:
--   
--   <pre>
--   data A a = A a
--     deriving (Generic)
--   instance (Arg (A a) a, Arbitrary a) =&gt; Arbitrary (A a) where
--     arbitrary = genericArbitrary
--     shrink = genericShrink
--   </pre>
type Arg self field = (TypesDiffer self field ~ 'True)

-- | Generic arbitrary.
--   
--   Parameters are: * self: the ADT we generating instance for * a: some
--   part of the `Rep self` * finite: Is <tt>a</tt> finite? Infinite type
--   has no finite values (like Stream)
class (Finite self a ~ finite) => GArbitrary self a (finite :: Bool)
class (Finite self a ~ af, Finite self b ~ bf) => FiniteSum self (a :: * -> *) (b :: * -> *) af bf
class FiniteSumElem self a
type family Finite self (a :: * -> *) :: Bool
type family AllFieldsFinal self (a :: * -> *) :: Bool
type family TypesDiffer a b
type family ArgumentsCount (a :: * -> *) :: Nat

-- | Calculates count of constructors encoded by particular <a>:+:</a>.
--   Internal use only.
type family SumLen a :: Nat

-- | Random generation and shrinking of values.
--   
--   QuickCheck provides <tt>Arbitrary</tt> instances for most types in
--   <tt>base</tt>, except those which incur extra dependencies. For a
--   wider range of <tt>Arbitrary</tt> instances see the
--   <a>quickcheck-instances</a> 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 <a>sample</a>, <tt>label</tt> and
--   <tt>classify</tt> to check the quality of your test data.
--   
--   There is no generic <tt>arbitrary</tt> implementation included because
--   we don't know how to make a high-quality one. If you want one,
--   consider using the <a>testing-feat</a> or <a>generic-random</a>
--   packages.
--   
--   The <a>QuickCheck manual</a> 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 <tt>shrink = <a>genericShrink</a></tt>,
--   but by customising the behaviour of <tt>shrink</tt> you can often get
--   simpler counterexamples.
--   
--   Most implementations of <a>shrink</a> should try at least three
--   things:
--   
--   <ol>
--   <li>Shrink a term to any of its immediate subterms. You can use
--   <a>subterms</a> to do this.</li>
--   <li>Recursively apply <a>shrink</a> to all immediate subterms. You can
--   use <a>recursivelyShrink</a> to do this.</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. 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]

-- | 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.FiniteSumElem self a, Test.QuickCheck.Arbitrary.Generic.FiniteSumElem self b, Test.QuickCheck.Arbitrary.Generic.Finite self a GHC.Types.~ 'GHC.Types.True, Test.QuickCheck.Arbitrary.Generic.Finite self b GHC.Types.~ 'GHC.Types.True) => Test.QuickCheck.Arbitrary.Generic.FiniteSum self a b 'GHC.Types.True 'GHC.Types.True
instance (Test.QuickCheck.Arbitrary.Generic.FiniteSumElem self a, Test.QuickCheck.Arbitrary.Generic.Finite self a GHC.Types.~ 'GHC.Types.True, Test.QuickCheck.Arbitrary.Generic.Finite self b GHC.Types.~ 'GHC.Types.False) => Test.QuickCheck.Arbitrary.Generic.FiniteSum self a b 'GHC.Types.True 'GHC.Types.False
instance (Test.QuickCheck.Arbitrary.Generic.FiniteSumElem self b, Test.QuickCheck.Arbitrary.Generic.Finite self a GHC.Types.~ 'GHC.Types.False, Test.QuickCheck.Arbitrary.Generic.Finite self b GHC.Types.~ 'GHC.Types.True) => Test.QuickCheck.Arbitrary.Generic.FiniteSum self a b 'GHC.Types.False 'GHC.Types.True
instance Test.QuickCheck.Arbitrary.Generic.FiniteSum self a b af bf => Test.QuickCheck.Arbitrary.Generic.FiniteSumElem self (a GHC.Generics.:+: b)
instance Test.QuickCheck.Arbitrary.Generic.GArbitrary self (GHC.Generics.M1 GHC.Generics.C c f) 'GHC.Types.True => Test.QuickCheck.Arbitrary.Generic.FiniteSumElem self (GHC.Generics.M1 GHC.Generics.C c f)
instance (Test.QuickCheck.Arbitrary.Generic.FiniteSum self a b af bf, Test.QuickCheck.Arbitrary.Generic.GArbitrary self (a GHC.Generics.:+: b) 'GHC.Types.True) => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (GHC.Generics.M1 GHC.Generics.D t (a GHC.Generics.:+: b)) 'GHC.Types.True
instance (GHC.Generics.Generic a, Test.QuickCheck.Arbitrary.Generic.GArbitrary a (GHC.Generics.Rep a) some, 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 self (GHC.Generics.M1 GHC.Generics.C c f) 'GHC.Types.True => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (GHC.Generics.M1 GHC.Generics.D t (GHC.Generics.M1 GHC.Generics.C c f)) 'GHC.Types.True
instance (Test.QuickCheck.Arbitrary.Generic.GArbitrary self f some, GHC.TypeNats.KnownNat (Test.QuickCheck.Arbitrary.Generic.ArgumentsCount f), Test.QuickCheck.Arbitrary.Generic.AllFieldsFinal self f GHC.Types.~ some) => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (GHC.Generics.M1 GHC.Generics.C c f) some
instance Test.QuickCheck.Arbitrary.Generic.GArbitrary self GHC.Generics.U1 'GHC.Types.True
instance Test.QuickCheck.Arbitrary.Generic.GArbitrary self f some => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (GHC.Generics.M1 GHC.Generics.S t f) some
instance (Test.QuickCheck.Arbitrary.Arbitrary t, Test.QuickCheck.Arbitrary.Generic.Finite self (GHC.Generics.K1 GHC.Generics.R t) GHC.Types.~ some) => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (GHC.Generics.K1 GHC.Generics.R t) some
instance (Test.QuickCheck.Arbitrary.Generic.GArbitrary self a af, Test.QuickCheck.Arbitrary.Generic.GArbitrary self b bf, (af Data.Type.Bool.&& bf) GHC.Types.~ some) => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (a GHC.Generics.:*: b) some
instance ((TypeError ...), Test.QuickCheck.Arbitrary.Generic.AllFieldsFinal self f GHC.Types.~ 'GHC.Types.False) => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (GHC.Generics.M1 GHC.Generics.D t (GHC.Generics.M1 GHC.Generics.C c f)) 'GHC.Types.False
instance (Test.QuickCheck.Arbitrary.Generic.GArbitrary self a af, Test.QuickCheck.Arbitrary.Generic.GArbitrary self b bf, GHC.TypeNats.KnownNat (Test.QuickCheck.Arbitrary.Generic.SumLen a), GHC.TypeNats.KnownNat (Test.QuickCheck.Arbitrary.Generic.SumLen b), (af Data.Type.Bool.|| bf) GHC.Types.~ some) => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (a GHC.Generics.:+: b) some
instance ((TypeError ...), (Test.QuickCheck.Arbitrary.Generic.Finite self a Data.Type.Bool.|| Test.QuickCheck.Arbitrary.Generic.Finite self b) GHC.Types.~ 'GHC.Types.False) => Test.QuickCheck.Arbitrary.Generic.GArbitrary self (GHC.Generics.M1 GHC.Generics.D t (a GHC.Generics.:+: b)) 'GHC.Types.False