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


-- | A property-based testing library
--   
--   SmallCheck is a testing library that allows to verify properties for
--   all test cases up to some depth. The test cases are generated
--   automatically by SmallCheck.
@package smallcheck
@version 1.1.2


-- | You need this module if you want to generate test values of your own
--   types.
--   
--   You'll typically need the following extensions:
--   
--   <pre>
--   {-# LANGUAGE FlexibleInstances, MultiParamTypeClasses #-}
--   </pre>
--   
--   SmallCheck itself defines data generators for all the data types used
--   by the <a>Prelude</a>.
--   
--   In order to generate values and functions of your own types, you need
--   to make them instances of <a>Serial</a> (for values) and
--   <a>CoSerial</a> (for functions). There are two main ways to do so:
--   using Generics or writing the instances by hand.
module Test.SmallCheck.Series
cons0 :: a -> Series m a
cons1 :: Serial m a => (a -> b) -> Series m b
cons2 :: (Serial m a, Serial m b) => (a -> b -> c) -> Series m c
cons3 :: (Serial m a, Serial m b, Serial m c) => (a -> b -> c -> d) -> Series m d
cons4 :: (Serial m a, Serial m b, Serial m c, Serial m d) => (a -> b -> c -> d -> e) -> Series m e

-- | Same as <a>cons1</a>, but preserves the depth.
newtypeCons :: Serial m a => (a -> b) -> Series m b
alts0 :: Series m a -> Series m a
alts1 :: CoSerial m a => Series m b -> Series m (a -> b)
alts2 :: (CoSerial m a, CoSerial m b) => Series m c -> Series m (a -> b -> c)
alts3 :: (CoSerial m a, CoSerial m b, CoSerial m c) => Series m d -> Series m (a -> b -> c -> d)
alts4 :: (CoSerial m a, CoSerial m b, CoSerial m c, CoSerial m d) => Series m e -> Series m (a -> b -> c -> d -> e)

-- | Same as <a>alts1</a>, but preserves the depth.
newtypeAlts :: CoSerial m a => Series m b -> Series m (a -> b)

-- | Maximum depth of generated test values.
--   
--   For data values, it is the depth of nested constructor applications.
--   
--   For functional values, it is both the depth of nested case analysis
--   and the depth of results.
type Depth = Int

-- | <a>Series</a> is a <a>MonadLogic</a> action that enumerates values of
--   a certain type, up to some depth.
--   
--   The depth bound is tracked in the <tt>SC</tt> monad and can be
--   extracted using <tt>getDepth</tt> and changed using
--   <tt>localDepth</tt>.
--   
--   To manipulate series at the lowest level you can use its <a>Monad</a>,
--   <a>MonadPlus</a> and <a>MonadLogic</a> instances. This module provides
--   some higher-level combinators which simplify creating series.
--   
--   A proper <a>Series</a> should be monotonic with respect to the depth —
--   i.e. <tt>localDepth (+1) s</tt> should emit all the values that
--   <tt>s</tt> emits (and possibly some more).
--   
--   It is also desirable that values of smaller depth come before the
--   values of greater depth.
data Series m a
class Monad m => Serial m a where series = to <$> gSeries
series :: Serial m a => Series m a
series :: (Serial m a, Generic a, GSerial m (Rep a)) => Series m a
class Monad m => CoSerial m a where coseries rs = (. from) <$> gCoseries rs

-- | A proper <a>coseries</a> implementation should pass the depth
--   unchanged to its first argument. Doing otherwise will make enumeration
--   of curried functions non-uniform in their arguments.
coseries :: CoSerial m a => Series m b -> Series m (a -> b)

-- | A proper <a>coseries</a> implementation should pass the depth
--   unchanged to its first argument. Doing otherwise will make enumeration
--   of curried functions non-uniform in their arguments.
coseries :: (CoSerial m a, Generic a, GCoSerial m (Rep a)) => Series m b -> Series m (a -> b)

-- | <tt>Positive x</tt>: guarantees that <tt>x &gt; 0</tt>.
newtype Positive a
Positive :: a -> Positive a
[getPositive] :: Positive a -> a

-- | <tt>NonNegative x</tt>: guarantees that <tt>x &gt;= 0</tt>.
newtype NonNegative a
NonNegative :: a -> NonNegative a
[getNonNegative] :: NonNegative a -> a

-- | <tt>NonEmpty xs</tt>: guarantees that <tt>xs</tt> is not null
newtype NonEmpty a
NonEmpty :: [a] -> NonEmpty a
[getNonEmpty] :: NonEmpty a -> [a]

-- | Sum (union) of series
(\/) :: Monad m => Series m a -> Series m a -> Series m a
infixr 7 \/

-- | Product of series
(><) :: Monad m => Series m a -> Series m b -> Series m (a, b)
infixr 8 ><

-- | Fair version of <a>ap</a> and <a>&lt;*&gt;</a>
(<~>) :: Monad m => Series m (a -> b) -> Series m a -> Series m b
infixl 4 <~>

-- | Fair conjunction. Similarly to the previous function, consider the
--   distributivity law for MonadPlus:
--   
--   <pre>
--   (mplus a b) &gt;&gt;= k = (a &gt;&gt;= k) `mplus` (b &gt;&gt;= k)
--   </pre>
--   
--   If 'a &gt;&gt;= k' can backtrack arbitrarily many tmes, (b &gt;&gt;=
--   k) may never be considered. (&gt;&gt;-) takes similar care to consider
--   both branches of a disjunctive computation.
(>>-) :: MonadLogic m => forall a b. m a -> (a -> m b) -> m b

-- | Run a series with a modified depth
localDepth :: (Depth -> Depth) -> Series m a -> Series m a

-- | Run a <a>Series</a> with the depth decreased by 1.
--   
--   If the current depth is less or equal to 0, the result is
--   <a>mzero</a>.
decDepth :: Series m a -> Series m a

-- | Query the current depth
getDepth :: Series m Depth

-- | A simple series specified by a function from depth to the list of
--   values up to that depth.
generate :: (Depth -> [a]) -> Series m a

-- | Given a depth, return the list of values generated by a Serial
--   instance.
--   
--   Example, list all integers up to depth 1:
--   
--   <ul>
--   <li><pre>listSeries 1 :: [Int] -- returns [0,1,-1]</pre></li>
--   </ul>
listSeries :: Serial Identity a => Depth -> [a]

-- | Return the list of values generated by a <a>Series</a>. Useful for
--   debugging <a>Serial</a> instances.
--   
--   Examples:
--   
--   <ul>
--   <li><pre>list 3 <a>series</a> :: [Int] -- returns
--   [0,1,-1,2,-2,3,-3]</pre></li>
--   <li><pre>list 3 (<a>series</a> :: <a>Series</a> <a>Identity</a> Int)
--   -- returns [0,1,-1,2,-2,3,-3]</pre></li>
--   <li><pre>list 2 <a>series</a> :: [[Bool]] -- returns
--   [[],[True],[False]]</pre></li>
--   </ul>
--   
--   The first two are equivalent. The second has a more explicit type
--   binding.
list :: Depth -> Series Identity a -> [a]

-- | Monadic version of <a>list</a>
listM :: Monad m => Depth -> Series m a -> m [a]

-- | Fix the depth of a series at the current level. The resulting series
--   will no longer depend on the "ambient" depth.
fixDepth :: Series m a -> Series m (Series m a)

-- | If the current depth is 0, evaluate the first argument. Otherwise,
--   evaluate the second argument with decremented depth.
decDepthChecked :: Series m a -> Series m a -> Series m a

-- | <pre>
--   <a>constM</a> = <a>liftM</a> <a>const</a>
--   </pre>
constM :: Monad m => m b -> m (a -> b)
instance GHC.Enum.Enum a => GHC.Enum.Enum (Test.SmallCheck.Series.NonNegative a)
instance GHC.Real.Real a => GHC.Real.Real (Test.SmallCheck.Series.NonNegative a)
instance GHC.Real.Integral a => GHC.Real.Integral (Test.SmallCheck.Series.NonNegative a)
instance GHC.Num.Num a => GHC.Num.Num (Test.SmallCheck.Series.NonNegative a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Test.SmallCheck.Series.NonNegative a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Test.SmallCheck.Series.NonNegative a)
instance GHC.Enum.Enum a => GHC.Enum.Enum (Test.SmallCheck.Series.Positive a)
instance GHC.Real.Real a => GHC.Real.Real (Test.SmallCheck.Series.Positive a)
instance GHC.Real.Integral a => GHC.Real.Integral (Test.SmallCheck.Series.Positive a)
instance GHC.Num.Num a => GHC.Num.Num (Test.SmallCheck.Series.Positive a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Test.SmallCheck.Series.Positive a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Test.SmallCheck.Series.Positive a)
instance GHC.Real.Integral a => GHC.Real.Integral (Test.SmallCheck.Series.N a)
instance GHC.Num.Num a => GHC.Num.Num (Test.SmallCheck.Series.N a)
instance GHC.Enum.Enum a => GHC.Enum.Enum (Test.SmallCheck.Series.N a)
instance GHC.Real.Real a => GHC.Real.Real (Test.SmallCheck.Series.N a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Test.SmallCheck.Series.N a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Test.SmallCheck.Series.N a)
instance Test.SmallCheck.Series.GSerial m f => Test.SmallCheck.Series.GSerial m (GHC.Generics.M1 i c f)
instance Test.SmallCheck.Series.GCoSerial m f => Test.SmallCheck.Series.GCoSerial m (GHC.Generics.M1 i c f)
instance Test.SmallCheck.Series.Serial m c => Test.SmallCheck.Series.GSerial m (GHC.Generics.K1 i c)
instance Test.SmallCheck.Series.CoSerial m c => Test.SmallCheck.Series.GCoSerial m (GHC.Generics.K1 i c)
instance Test.SmallCheck.Series.GSerial m GHC.Generics.U1
instance Test.SmallCheck.Series.GCoSerial m GHC.Generics.U1
instance (GHC.Base.Monad m, Test.SmallCheck.Series.GSerial m a, Test.SmallCheck.Series.GSerial m b) => Test.SmallCheck.Series.GSerial m (a GHC.Generics.:*: b)
instance (GHC.Base.Monad m, Test.SmallCheck.Series.GCoSerial m a, Test.SmallCheck.Series.GCoSerial m b) => Test.SmallCheck.Series.GCoSerial m (a GHC.Generics.:*: b)
instance (GHC.Base.Monad m, Test.SmallCheck.Series.GSerial m a, Test.SmallCheck.Series.GSerial m b) => Test.SmallCheck.Series.GSerial m (a GHC.Generics.:+: b)
instance (GHC.Base.Monad m, Test.SmallCheck.Series.GCoSerial m a, Test.SmallCheck.Series.GCoSerial m b) => Test.SmallCheck.Series.GCoSerial m (a GHC.Generics.:+: b)
instance Test.SmallCheck.Series.GSerial m f => Test.SmallCheck.Series.GSerial m (GHC.Generics.C1 c f)
instance GHC.Base.Monad m => Test.SmallCheck.Series.Serial m ()
instance GHC.Base.Monad m => Test.SmallCheck.Series.CoSerial m ()
instance GHC.Base.Monad m => Test.SmallCheck.Series.Serial m GHC.Types.Int
instance GHC.Base.Monad m => Test.SmallCheck.Series.CoSerial m GHC.Types.Int
instance GHC.Base.Monad m => Test.SmallCheck.Series.Serial m GHC.Integer.Type.Integer
instance GHC.Base.Monad m => Test.SmallCheck.Series.CoSerial m GHC.Integer.Type.Integer
instance (GHC.Real.Integral a, Test.SmallCheck.Series.Serial m a) => Test.SmallCheck.Series.Serial m (Test.SmallCheck.Series.N a)
instance (GHC.Real.Integral a, GHC.Base.Monad m) => Test.SmallCheck.Series.CoSerial m (Test.SmallCheck.Series.N a)
instance GHC.Base.Monad m => Test.SmallCheck.Series.Serial m GHC.Types.Float
instance GHC.Base.Monad m => Test.SmallCheck.Series.CoSerial m GHC.Types.Float
instance GHC.Base.Monad m => Test.SmallCheck.Series.Serial m GHC.Types.Double
instance GHC.Base.Monad m => Test.SmallCheck.Series.CoSerial m GHC.Types.Double
instance (GHC.Real.Integral i, Test.SmallCheck.Series.Serial m i) => Test.SmallCheck.Series.Serial m (GHC.Real.Ratio i)
instance (GHC.Real.Integral i, Test.SmallCheck.Series.CoSerial m i) => Test.SmallCheck.Series.CoSerial m (GHC.Real.Ratio i)
instance GHC.Base.Monad m => Test.SmallCheck.Series.Serial m GHC.Types.Char
instance GHC.Base.Monad m => Test.SmallCheck.Series.CoSerial m GHC.Types.Char
instance (Test.SmallCheck.Series.Serial m a, Test.SmallCheck.Series.Serial m b) => Test.SmallCheck.Series.Serial m (a, b)
instance (Test.SmallCheck.Series.CoSerial m a, Test.SmallCheck.Series.CoSerial m b) => Test.SmallCheck.Series.CoSerial m (a, b)
instance (Test.SmallCheck.Series.Serial m a, Test.SmallCheck.Series.Serial m b, Test.SmallCheck.Series.Serial m c) => Test.SmallCheck.Series.Serial m (a, b, c)
instance (Test.SmallCheck.Series.CoSerial m a, Test.SmallCheck.Series.CoSerial m b, Test.SmallCheck.Series.CoSerial m c) => Test.SmallCheck.Series.CoSerial m (a, b, c)
instance (Test.SmallCheck.Series.Serial m a, Test.SmallCheck.Series.Serial m b, Test.SmallCheck.Series.Serial m c, Test.SmallCheck.Series.Serial m d) => Test.SmallCheck.Series.Serial m (a, b, c, d)
instance (Test.SmallCheck.Series.CoSerial m a, Test.SmallCheck.Series.CoSerial m b, Test.SmallCheck.Series.CoSerial m c, Test.SmallCheck.Series.CoSerial m d) => Test.SmallCheck.Series.CoSerial m (a, b, c, d)
instance GHC.Base.Monad m => Test.SmallCheck.Series.Serial m GHC.Types.Bool
instance GHC.Base.Monad m => Test.SmallCheck.Series.CoSerial m GHC.Types.Bool
instance Test.SmallCheck.Series.Serial m a => Test.SmallCheck.Series.Serial m (GHC.Base.Maybe a)
instance Test.SmallCheck.Series.CoSerial m a => Test.SmallCheck.Series.CoSerial m (GHC.Base.Maybe a)
instance (Test.SmallCheck.Series.Serial m a, Test.SmallCheck.Series.Serial m b) => Test.SmallCheck.Series.Serial m (Data.Either.Either a b)
instance (Test.SmallCheck.Series.CoSerial m a, Test.SmallCheck.Series.CoSerial m b) => Test.SmallCheck.Series.CoSerial m (Data.Either.Either a b)
instance Test.SmallCheck.Series.Serial m a => Test.SmallCheck.Series.Serial m [a]
instance Test.SmallCheck.Series.CoSerial m a => Test.SmallCheck.Series.CoSerial m [a]
instance (Test.SmallCheck.Series.CoSerial m a, Test.SmallCheck.Series.Serial m b) => Test.SmallCheck.Series.Serial m (a -> b)
instance (Test.SmallCheck.Series.Serial m a, Test.SmallCheck.Series.CoSerial m a, Test.SmallCheck.Series.Serial m b, Test.SmallCheck.Series.CoSerial m b) => Test.SmallCheck.Series.CoSerial m (a -> b)
instance (Test.SmallCheck.Series.Serial Data.Functor.Identity.Identity a, GHC.Show.Show a, GHC.Show.Show b) => GHC.Show.Show (a -> b)
instance (GHC.Num.Num a, GHC.Classes.Ord a, Test.SmallCheck.Series.Serial m a) => Test.SmallCheck.Series.Serial m (Test.SmallCheck.Series.Positive a)
instance GHC.Show.Show a => GHC.Show.Show (Test.SmallCheck.Series.Positive a)
instance (GHC.Num.Num a, GHC.Classes.Ord a, Test.SmallCheck.Series.Serial m a) => Test.SmallCheck.Series.Serial m (Test.SmallCheck.Series.NonNegative a)
instance GHC.Show.Show a => GHC.Show.Show (Test.SmallCheck.Series.NonNegative a)
instance Test.SmallCheck.Series.Serial m a => Test.SmallCheck.Series.Serial m (Test.SmallCheck.Series.NonEmpty a)
instance GHC.Show.Show a => GHC.Show.Show (Test.SmallCheck.Series.NonEmpty a)


-- | You should only need this module if you wish to create your own way to
--   run SmallCheck tests
module Test.SmallCheck.Drivers

-- | A simple driver that runs the test in the <a>IO</a> monad and prints
--   the results.
smallCheck :: Testable IO a => Depth -> a -> IO ()

-- | Use this if:
--   
--   <ul>
--   <li>You need to run a test in a monad different from <a>IO</a></li>
--   <li>You need to analyse the results rather than just print them</li>
--   </ul>
smallCheckM :: Testable m a => Depth -> a -> m (Maybe PropertyFailure)

-- | Like <a>smallCheckM</a>, but allows to specify a monadic hook that
--   gets executed after each test is run.
--   
--   Useful for applications that want to report progress information to
--   the user.
smallCheckWithHook :: Testable m a => Depth -> (TestQuality -> m ()) -> a -> m (Maybe PropertyFailure)
test :: Testable m a => a -> Property m
ppFailure :: PropertyFailure -> String
data PropertyFailure
NotExist :: PropertyFailure
AtLeastTwo :: [Argument] -> PropertySuccess -> [Argument] -> PropertySuccess -> PropertyFailure
CounterExample :: [Argument] -> PropertyFailure -> PropertyFailure
PropertyFalse :: (Maybe Reason) -> PropertyFailure
data PropertySuccess
Exist :: [Argument] -> PropertySuccess -> PropertySuccess
ExistUnique :: [Argument] -> PropertySuccess -> PropertySuccess
PropertyTrue :: (Maybe Reason) -> PropertySuccess
Vacuously :: PropertyFailure -> PropertySuccess
type Argument = String

-- | An explanation for the test outcome
type Reason = String
data TestQuality
GoodTest :: TestQuality
BadTest :: TestQuality


-- | This module exports the main pieces of SmallCheck functionality.
--   
--   To generate test cases for your own types, refer to
--   <a>Test.SmallCheck.Series</a>.
--   
--   For pointers to other sources of information about SmallCheck, please
--   refer to the README at
--   <a>https://github.com/feuerbach/smallcheck/blob/master/README.md</a>
module Test.SmallCheck

-- | Set the universal quantification context
forAll :: Testable m a => a -> Property m

-- | Set the existential quantification context
exists :: Testable m a => a -> Property m

-- | Set the uniqueness quantification context.
--   
--   Bear in mind that ∃! (x, y): p x y is not the same as ∃! x: ∃! y: p x
--   y.
--   
--   For example, ∃! x: ∃! y: |x| = |y| is true (it holds only when x=0),
--   but ∃! (x,y): |x| = |y| is false (there are many such pairs).
--   
--   As is customary in mathematics, <tt><a>existsUnique</a> $ \x y -&gt; p
--   x y</tt> is equivalent to <tt><a>existsUnique</a> $ \(x,y) -&gt; p x
--   y</tt> and not to <tt><a>existsUnique</a> $ \x -&gt;
--   <a>existsUnique</a> $ \y -&gt; p x y</tt> (the latter, of course, may
--   be explicitly written when desired).
--   
--   That is, all the variables affected by the same uniqueness context are
--   quantified simultaneously as a tuple.
existsUnique :: Testable m a => a -> Property m

-- | <tt><a>over</a> s $ \x -&gt; p x</tt> makes <tt>x</tt> range over the
--   <a>Series</a> <tt>s</tt> (by default, all variables range over the
--   <a>series</a> for their types).
--   
--   Note that, unlike the quantification operators, this affects only the
--   variable following the operator and not subsequent variables.
--   
--   <a>over</a> does not affect the quantification context.
over :: (Show a, Testable m b) => Series m a -> (a -> b) -> Property m

-- | Execute a monadic test
monadic :: Testable m a => m a -> Property m

-- | The <a>==&gt;</a> operator can be used to express a restricting
--   condition under which a property should hold. It corresponds to
--   implication in the classical logic.
--   
--   Note that <a>==&gt;</a> resets the quantification context for its
--   operands to the default (universal).
(==>) :: (Testable m c, Testable m a) => c -> a -> Property m
infixr 0 ==>

-- | Run property with a modified depth. Affects all quantified variables
--   in the property.
changeDepth :: Testable m a => (Depth -> Depth) -> a -> Property m

-- | Quantify the function's argument over its <a>series</a>, but adjust
--   the depth. This doesn't affect any subsequent variables.
changeDepth1 :: (Show a, Serial m a, Testable m b) => (Depth -> Depth) -> (a -> b) -> Property m

-- | Maximum depth of generated test values.
--   
--   For data values, it is the depth of nested constructor applications.
--   
--   For functional values, it is both the depth of nested case analysis
--   and the depth of results.
type Depth = Int

-- | A simple driver that runs the test in the <a>IO</a> monad and prints
--   the results.
smallCheck :: Testable IO a => Depth -> a -> IO ()

-- | Class of tests that can be run in a monad. For pure tests, it is
--   recommended to keep their types polymorphic in <tt>m</tt> rather than
--   specialising it to <tt>Identity</tt>.
class Monad m => Testable m a
test :: Testable m a => a -> Property m

-- | The type of properties over the monad <tt>m</tt>
data Property m

-- | An explanation for the test outcome
type Reason = String