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


-- | Generic random generators
--   
--   Please see the README.
@package generic-random
@version 0.5.0.0

module Generic.Random.Internal.Generic

-- | Pick a constructor with a given distribution, and fill its fields
--   recursively.
genericArbitrary :: forall a. (Generic a, GA Unsized (Rep a)) => Weights a -> Gen a

-- | Shorthand for <tt><a>genericArbitrary</a> <a>uniform</a></tt>.
genericArbitraryU :: forall a. (Generic a, GA Unsized (Rep a), UniformWeight (Weights_ (Rep a))) => Gen a

-- | Like <a>genericArbitrary'</a>, with decreasing size to ensure
--   termination for recursive types, looking for base cases once the size
--   reaches 0.
genericArbitrary' :: forall n a. (Generic a, GA (Sized n) (Rep a)) => n -> Weights a -> Gen a

-- | Shorthand for <tt><a>genericArbitrary'</a> <a>Z</a>
--   <a>uniform</a></tt>, using nullary constructors as the base cases.
genericArbitraryU0 :: forall n a. (Generic a, GA (Sized Z) (Rep a), UniformWeight (Weights_ (Rep a))) => Gen a

-- | Shorthand for <tt><a>genericArbitrary'</a> (<a>S</a> <a>Z</a>)
--   <a>uniform</a></tt>, using nullary constructors and constructors whose
--   fields are all nullary as base cases.
genericArbitraryU1 :: forall n a. (Generic a, GA (Sized (S Z)) (Rep a), UniformWeight (Weights_ (Rep a))) => Gen a
data (:|) a b
N :: a -> Int -> b -> (:|) a b
data L (c :: Symbol)
L :: L

-- | Trees of weights assigned to constructors of type <tt>a</tt>, rescaled
--   to obtain a probability distribution.
--   
--   Two ways of constructing them.
--   
--   <pre>
--   <a>weights</a> (x1 <a>%</a> x2 <a>%</a> ... <a>%</a> xn <a>%</a> ()) :: <a>Weights</a> a
--   <a>uniform</a> :: <a>Weights</a> a
--   </pre>
--   
--   Using <tt>weights</tt>, there must be exactly as many weights as there
--   are constructors.
--   
--   <a>uniform</a> is equivalent to <tt><a>weights</a> (1 <a>%</a> ...
--   <a>%</a> 1 <a>%</a> ())</tt> (automatically fills out the right number
--   of 1s).
data Weights a
Weights :: (Weights_ (Rep a)) -> Int -> Weights a

-- | Type of a single weight, tagged with the name of the associated
--   constructor for additional compile-time checking.
--   
--   <pre>
--   <a>weights</a> ((9 :: <a>W</a> "Leaf") <a>%</a> (8 :: <a>W</a> "Node") <a>%</a> ())
--   </pre>
newtype W (c :: Symbol)
W :: Int -> W

-- | A smart constructor to specify a custom distribution.
weights :: (Weights_ (Rep a), Int, ()) -> Weights a

-- | Uniform distribution.
uniform :: UniformWeight (Weights_ (Rep a)) => Weights a
class WeightBuilder a where type Prec a r where {
    type family Prec a r;
}

-- | A binary constructor for building up trees of weights.
(%) :: WeightBuilder a => W (First a) -> Prec a r -> (a, Int, r)
class UniformWeight a
uniformWeight :: UniformWeight a => (a, Int)
newtype Gen' sized a
Gen' :: Gen a -> Gen' sized a
[unGen'] :: Gen' sized a -> Gen a
data Sized n
data Unsized
sized' :: (Int -> Gen' sized a) -> Gen' sized a

-- | Generic Arbitrary
class GA sized f
ga :: GA sized f => Weights_ f -> Int -> Gen' sized (f p)
gArbitrarySingle :: forall sized f p c0. (GA sized f, Weights_ f ~ L c0) => Gen' sized (f p)
gaSum' :: GASum sized f => Weights_ f -> Int -> Gen' sized (f p)
class GASum sized f
gaSum :: GASum sized f => Int -> Weights_ f -> Gen' sized (f p)
class GAProduct f
gaProduct :: GAProduct f => Gen (f p)
newtype Tagged a b
Tagged :: b -> Tagged a b
[unTagged] :: Tagged a b -> b

-- | Zero
data Z
Z :: Z

-- | Successor
data S n
S :: n -> S n
newtype Weighted a
Weighted :: (Maybe (Int -> Gen a, Int)) -> Weighted a
class BaseCases n f
baseCases :: BaseCases n f => Weights_ f -> Int -> Tagged n (Weighted (f p))

-- | A <tt>ListBaseCases n (<a>Rep</a> a)</tt> constraint basically
--   provides the list of values of type <tt>a</tt> with depth at most
--   <tt>n</tt>.
class ListBaseCases n f
listBaseCases :: (ListBaseCases n f, Alternative u) => Tagged n (u (f p))

-- | For convenience.
type BaseCases' n a = (Generic a, ListBaseCases n (Rep a))
instance GHC.Base.Functor Generic.Random.Internal.Generic.Weighted
instance GHC.Base.Functor (Generic.Random.Internal.Generic.Tagged a)
instance GHC.Base.Monad (Generic.Random.Internal.Generic.Gen' sized)
instance GHC.Base.Applicative (Generic.Random.Internal.Generic.Gen' sized)
instance GHC.Base.Functor (Generic.Random.Internal.Generic.Gen' sized)
instance GHC.Num.Num (Generic.Random.Internal.Generic.W c)
instance Generic.Random.Internal.Generic.WeightBuilder a => Generic.Random.Internal.Generic.WeightBuilder (a Generic.Random.Internal.Generic.:| b)
instance Generic.Random.Internal.Generic.WeightBuilder (Generic.Random.Internal.Generic.L c)
instance Generic.Random.Internal.Generic.WeightBuilder ()
instance (Generic.Random.Internal.Generic.UniformWeight a, Generic.Random.Internal.Generic.UniformWeight b) => Generic.Random.Internal.Generic.UniformWeight (a Generic.Random.Internal.Generic.:| b)
instance Generic.Random.Internal.Generic.UniformWeight (Generic.Random.Internal.Generic.L c)
instance Generic.Random.Internal.Generic.UniformWeight ()
instance Generic.Random.Internal.Generic.GA sized f => Generic.Random.Internal.Generic.GA sized (GHC.Generics.M1 GHC.Generics.D c f)
instance Generic.Random.Internal.Generic.GAProduct f => Generic.Random.Internal.Generic.GA Generic.Random.Internal.Generic.Unsized (GHC.Generics.M1 GHC.Generics.C c f)
instance (Generic.Random.Internal.Generic.GAProduct f, GHC.TypeLits.KnownNat (Generic.Random.Internal.Generic.Arity f)) => Generic.Random.Internal.Generic.GA (Generic.Random.Internal.Generic.Sized n) (GHC.Generics.M1 GHC.Generics.C c f)
instance (Generic.Random.Internal.Generic.GASum (Generic.Random.Internal.Generic.Sized n) f, Generic.Random.Internal.Generic.GASum (Generic.Random.Internal.Generic.Sized n) g, Generic.Random.Internal.Generic.BaseCases n f, Generic.Random.Internal.Generic.BaseCases n g) => Generic.Random.Internal.Generic.GA (Generic.Random.Internal.Generic.Sized n) (f GHC.Generics.:+: g)
instance (Generic.Random.Internal.Generic.GASum Generic.Random.Internal.Generic.Unsized f, Generic.Random.Internal.Generic.GASum Generic.Random.Internal.Generic.Unsized g) => Generic.Random.Internal.Generic.GA Generic.Random.Internal.Generic.Unsized (f GHC.Generics.:+: g)
instance (Generic.Random.Internal.Generic.GASum sized f, Generic.Random.Internal.Generic.GASum sized g) => Generic.Random.Internal.Generic.GASum sized (f GHC.Generics.:+: g)
instance Generic.Random.Internal.Generic.GAProduct f => Generic.Random.Internal.Generic.GASum sized (GHC.Generics.M1 i c f)
instance Generic.Random.Internal.Generic.GAProduct GHC.Generics.U1
instance Test.QuickCheck.Arbitrary.Arbitrary c => Generic.Random.Internal.Generic.GAProduct (GHC.Generics.K1 i c)
instance Generic.Random.Internal.Generic.GAProduct f => Generic.Random.Internal.Generic.GAProduct (GHC.Generics.M1 i c f)
instance (Generic.Random.Internal.Generic.GAProduct f, Generic.Random.Internal.Generic.GAProduct g) => Generic.Random.Internal.Generic.GAProduct (f GHC.Generics.:*: g)
instance GHC.Base.Applicative Generic.Random.Internal.Generic.Weighted
instance GHC.Base.Alternative Generic.Random.Internal.Generic.Weighted
instance (Generic.Random.Internal.Generic.BaseCases n f, Generic.Random.Internal.Generic.BaseCases n g) => Generic.Random.Internal.Generic.BaseCases n (f GHC.Generics.:+: g)
instance Generic.Random.Internal.Generic.ListBaseCases n f => Generic.Random.Internal.Generic.BaseCases n (GHC.Generics.M1 i c f)
instance Generic.Random.Internal.Generic.ListBaseCases n GHC.Generics.U1
instance Generic.Random.Internal.Generic.ListBaseCases n f => Generic.Random.Internal.Generic.ListBaseCases n (GHC.Generics.M1 i c f)
instance Generic.Random.Internal.Generic.ListBaseCases Generic.Random.Internal.Generic.Z (GHC.Generics.K1 i c)
instance (GHC.Generics.Generic c, Generic.Random.Internal.Generic.ListBaseCases n (GHC.Generics.Rep c)) => Generic.Random.Internal.Generic.ListBaseCases (Generic.Random.Internal.Generic.S n) (GHC.Generics.K1 i c)
instance (Generic.Random.Internal.Generic.ListBaseCases n f, Generic.Random.Internal.Generic.ListBaseCases n g) => Generic.Random.Internal.Generic.ListBaseCases n (f GHC.Generics.:+: g)
instance (Generic.Random.Internal.Generic.ListBaseCases n f, Generic.Random.Internal.Generic.ListBaseCases n g) => Generic.Random.Internal.Generic.ListBaseCases n (f GHC.Generics.:*: g)


-- | Simple <a>Generics</a>-based <tt>arbitrary</tt> generators.
--   
--   Here is an example. Define your type.
--   
--   <pre>
--   data Tree a = Leaf a | Node (Tree a) (Tree a)
--     deriving Generic
--   </pre>
--   
--   Pick an <tt>arbitrary</tt> implementation.
--   
--   <pre>
--   instance Arbitrary a =&gt; Arbitrary (Tree a) where
--     arbitrary = <a>genericArbitrary</a> (<a>weights</a> (9 <a>%</a> 8 <a>%</a> ()))
--   </pre>
--   
--   <tt>arbitrary :: <tt>Gen</tt> (Tree a)</tt> picks a <tt>Leaf</tt> with
--   probability 9/17, or a <tt>Node</tt> with probability 8/17, and
--   recursively fills their fields with <tt>arbitrary</tt>.
--   
--   <h2>Distribution of constructors</h2>
--   
--   The distribution of constructors can be specified using <a>weights</a>
--   applied to a special list of <i>weights</i> in the same order as the
--   data type definition. This assigns to each constructor a probability
--   proportional to its weight; in other words, <tt>p_C = weight_C /
--   sumOfWeights</tt>.
--   
--   The list of weights is built up with the <tt>(<a>%</a>)</tt> operator
--   as a cons, and using the unit <tt>()</tt> as the empty list, in the
--   order corresponding to the data type definition. The uniform
--   distribution can be obtained with <a>uniform</a>.
--   
--   <h3>Example</h3>
--   
--   For <tt>Tree</tt>, <a>genericArbitrary</a> produces code equivalent to
--   the following:
--   
--   <pre>
--   <a>genericArbitrary</a> :: Arbitrary a =&gt; <a>Weights</a> (Tree a) -&gt; Gen (Tree a)
--   <a>genericArbitrary</a> (<tt>weighted</tt> (x <a>%</a> y <a>%</a> ())) =
--     frequency
--       [ (x, Leaf &lt;$&gt; arbitrary)
--       , (y, Node &lt;$&gt; arbitrary &lt;*&gt; arbitrary)
--       ]
--   </pre>
--   
--   <h3>Uniform distribution</h3>
--   
--   You can specify the uniform distribution (all weights equal) with
--   <a>uniform</a>. <a>genericArbitraryU</a> is available as a shorthand
--   for <tt><a>genericArbitrary</a> <a>uniform</a></tt>.
--   
--   Note that for many types, a uniform distribution tends to produce big
--   values. For instance for <tt>Tree a</tt>, generated values are finite
--   but the <b>average</b> number of <tt>Leaf</tt> and <tt>Node</tt>
--   constructors is <b>infinite</b>.
--   
--   <h3>Checked weights</h3>
--   
--   <i>GHC 8.0.1 and above only.</i>
--   
--   The weights actually have type <tt><a>W</a> "ConstructorName"</tt>
--   (just a newtype around <a>Int</a>), so that you can annotate a weight
--   with its corresponding constructor, and it will be checked that you
--   got the order right.
--   
--   This will type-check.
--   
--   <pre>
--   <tt>weighted</tt> ((x :: <a>W</a> "Leaf") <a>%</a> (y :: <a>W</a> "Node") <a>%</a> ()) :: <a>Weights</a> (Tree a)
--   <tt>weighted</tt> (x <a>%</a> (y :: <a>W</a> "Node") <a>%</a> ()) :: <a>Weights</a> (Tree a)
--   </pre>
--   
--   This will not: the first requires an order of constructors different
--   from the definition of the <tt>Tree</tt> type; the second doesn't have
--   the right number of weights.
--   
--   <pre>
--   <tt>weighted</tt> ((x :: <a>W</a> "Node") <a>%</a> y <a>%</a> ()) :: <a>Weights</a> (Tree a)
--   <tt>weighted</tt> (x <a>%</a> y <a>%</a> z <a>%</a> ()) :: <a>Weights</a> (Tree a)
--   </pre>
--   
--   <h2>Ensuring termination</h2>
--   
--   As was just mentioned, one must be careful with recursive types to
--   avoid producing extremely large values.
--   
--   The alternative <a>genericArbitrary'</a> implements a simple strategy
--   to keep values at reasonable sizes: the size parameter of <tt>Gen</tt>
--   is divided among the fields of the chosen constructor. When it reaches
--   zero, the generator selects a finite term whenever it can find any of
--   the given type. This generally ensures that the number of constructors
--   remains close to the initial size parameter passed to <tt>Gen</tt>.
--   
--   A natural number <tt>n</tt> determines the maximum <i>depth</i> of
--   terms that can be used to end recursion. It is encoded using
--   <tt><a>Z</a> :: <a>Z</a></tt> and <tt><a>S</a> :: n -&gt; <a>S</a>
--   n</tt>.
--   
--   <pre>
--   <a>genericArbitrary'</a> n (<a>weights</a> (...))
--   </pre>
--   
--   With <tt>n = <a>Z</a></tt>, the generator looks for a simple nullary
--   constructor. If none exist at the current type, as is the case for our
--   <tt>Tree</tt> type, it carries on as in <a>genericArbitrary</a>.
--   
--   <pre>
--   <a>genericArbitrary'</a> <a>Z</a> :: Arbitrary a =&gt; <a>Weights</a> (Tree a) -&gt; Gen (Tree a)
--   <a>genericArbitrary'</a> <a>Z</a> (<a>weights</a> (x <a>%</a> y <a>%</a> ())) =
--     frequency
--       [ (x, Leaf &lt;$&gt; arbitrary)
--       , (y, scale (`div` 2) $ Node &lt;$&gt; arbitrary &lt;*&gt; arbitrary)
--       -- 2 because Node is 2-ary.
--       ]
--   </pre>
--   
--   Here is another example with nullary constructors:
--   
--   <pre>
--   data Tree' = Leaf1 | Leaf2 | Node3 Tree' Tree' Tree'
--     deriving Generic
--   
--   instance Arbitrary Tree' where
--     arbitrary = <a>genericArbitrary'</a> <a>Z</a> (<a>weights</a> (1 <a>%</a> 2 <a>%</a> 3 <a>%</a> ()))
--   </pre>
--   
--   Here, <tt><a>genericArbitrary'</a> <a>Z</a></tt> is equivalent to:
--   
--   <pre>
--   <a>genericArbitrary'</a> <a>Z</a> :: <a>Weights</a> Tree' -&gt; Gen Tree'
--   <a>genericArbitrary'</a> <a>Z</a> (<a>weights</a> (x <a>%</a> y <a>%</a> z <a>%</a> ())) =
--     sized $ n -&gt;
--       if n == 0 then
--         -- If the size parameter is zero, the non-nullary alternative is discarded.
--         frequency $
--           [ (x, return Leaf1)
--           , (y, return Leaf2)
--           ]
--       else
--         frequency $
--           [ (x, return Leaf1)
--           , (y, return Leaf2)
--           , (z, resize (n `div` 3) node)  -- 3 because Node3 is 3-ary
--           ]
--     where
--       node = Node3 &lt;$&gt; arbitrary &lt;*&gt; arbitrary &lt;*&gt; arbitrary
--   </pre>
--   
--   To increase the chances of termination when no nullary constructor is
--   directly available, such as in <tt>Tree</tt>, we can pass a larger
--   depth <tt>n</tt>. The effectiveness of this parameter depends on the
--   concrete type the generator is used for.
--   
--   For instance, if we want to generate a value of type <tt>Tree ()</tt>,
--   there is a value of depth 1 (represented by <tt><a>S</a>
--   <a>Z</a></tt>) that we can use to end recursion: <tt>Leaf ()</tt>.
--   
--   <pre>
--   <a>genericArbitrary'</a> (<a>S</a> <a>Z</a>) :: <a>Weights</a> (Tree ()) -&gt; Gen (Tree ())
--   <a>genericArbitrary'</a> (<a>S</a> <a>Z</a>) (<a>weights</a> (x <a>%</a> y <a>%</a> ())) =
--     sized $ n -&gt;
--       if n == 0 then
--         return (Leaf ())
--       else
--         frequency
--           [ (x, Leaf &lt;$&gt; arbitrary)
--           , (y, scale (`div` 2) $ Node &lt;$&gt; arbitrary &lt;*&gt; arbitrary)
--           ]
--   </pre>
--   
--   Because the argument of <tt>Tree</tt> must be inspected in order to
--   discover values of type <tt>Tree ()</tt>, we incur some extra
--   constraints if we want polymorphism.
--   
--   <tt>UndecidableInstances</tt> is also required.
--   
--   <pre>
--   instance (Arbitrary a, Generic a, <a>ListBaseCases</a> <a>Z</a> (Rep a))
--     =&gt; Arbitrary (Tree a) where
--     arbitrary = <a>genericArbitrary'</a> (<a>S</a> <a>Z</a>) (<a>weights</a> (1 <a>%</a> 2 <a>%</a> ()))
--   </pre>
--   
--   A synonym is provided for brevity.
--   
--   <pre>
--   instance (Arbitrary a, <a>BaseCases'</a> Z a) =&gt; Arbitrary (Tree a) where
--     arbitrary = <a>genericArbitrary'</a> (<a>S</a> <a>Z</a>) (<a>weights</a> (1 <a>%</a> 2 <a>%</a> ()))
--   </pre>
module Generic.Random.Generic

-- | Pick a constructor with a given distribution, and fill its fields
--   recursively.
genericArbitrary :: forall a. (Generic a, GA Unsized (Rep a)) => Weights a -> Gen a

-- | Shorthand for <tt><a>genericArbitrary</a> <a>uniform</a></tt>.
genericArbitraryU :: forall a. (Generic a, GA Unsized (Rep a), UniformWeight (Weights_ (Rep a))) => Gen a

-- | Like <a>genericArbitrary'</a>, with decreasing size to ensure
--   termination for recursive types, looking for base cases once the size
--   reaches 0.
genericArbitrary' :: forall n a. (Generic a, GA (Sized n) (Rep a)) => n -> Weights a -> Gen a

-- | Shorthand for <tt><a>genericArbitrary'</a> <a>Z</a>
--   <a>uniform</a></tt>, using nullary constructors as the base cases.
genericArbitraryU0 :: forall n a. (Generic a, GA (Sized Z) (Rep a), UniformWeight (Weights_ (Rep a))) => Gen a

-- | Shorthand for <tt><a>genericArbitrary'</a> (<a>S</a> <a>Z</a>)
--   <a>uniform</a></tt>, using nullary constructors and constructors whose
--   fields are all nullary as base cases.
genericArbitraryU1 :: forall n a. (Generic a, GA (Sized (S Z)) (Rep a), UniformWeight (Weights_ (Rep a))) => Gen a

-- | Trees of weights assigned to constructors of type <tt>a</tt>, rescaled
--   to obtain a probability distribution.
--   
--   Two ways of constructing them.
--   
--   <pre>
--   <a>weights</a> (x1 <a>%</a> x2 <a>%</a> ... <a>%</a> xn <a>%</a> ()) :: <a>Weights</a> a
--   <a>uniform</a> :: <a>Weights</a> a
--   </pre>
--   
--   Using <tt>weights</tt>, there must be exactly as many weights as there
--   are constructors.
--   
--   <a>uniform</a> is equivalent to <tt><a>weights</a> (1 <a>%</a> ...
--   <a>%</a> 1 <a>%</a> ())</tt> (automatically fills out the right number
--   of 1s).
data Weights a

-- | Type of a single weight, tagged with the name of the associated
--   constructor for additional compile-time checking.
--   
--   <pre>
--   <a>weights</a> ((9 :: <a>W</a> "Leaf") <a>%</a> (8 :: <a>W</a> "Node") <a>%</a> ())
--   </pre>
data W (c :: Symbol)

-- | A smart constructor to specify a custom distribution.
weights :: (Weights_ (Rep a), Int, ()) -> Weights a

-- | A binary constructor for building up trees of weights.
(%) :: WeightBuilder a => W (First a) -> Prec a r -> (a, Int, r)

-- | Uniform distribution.
uniform :: UniformWeight (Weights_ (Rep a)) => Weights a

-- | Zero
data Z
Z :: Z

-- | Successor
data S n
S :: n -> S n

-- | For convenience.
type BaseCases' n a = (Generic a, ListBaseCases n (Rep a))
class BaseCases n f

-- | A <tt>ListBaseCases n (<a>Rep</a> a)</tt> constraint basically
--   provides the list of values of type <tt>a</tt> with depth at most
--   <tt>n</tt>.
class ListBaseCases n f