-- 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.1


-- | 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
class Monad m => CoSerial m a where coseries rs = (. from) <$> gCoseries rs
coseries :: CoSerial m 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

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

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

-- | 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

-- | Return the list of values generated by a <a>Series</a>. Useful for
--   debugging <a>Serial</a> instances.
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 [overlap ok] Eq a => Eq (N a)
instance [overlap ok] Ord a => Ord (N a)
instance [overlap ok] Real a => Real (N a)
instance [overlap ok] Enum a => Enum (N a)
instance [overlap ok] Num a => Num (N a)
instance [overlap ok] Integral a => Integral (N a)
instance [overlap ok] Eq a => Eq (Positive a)
instance [overlap ok] Ord a => Ord (Positive a)
instance [overlap ok] Num a => Num (Positive a)
instance [overlap ok] Integral a => Integral (Positive a)
instance [overlap ok] Real a => Real (Positive a)
instance [overlap ok] Enum a => Enum (Positive a)
instance [overlap ok] Eq a => Eq (NonNegative a)
instance [overlap ok] Ord a => Ord (NonNegative a)
instance [overlap ok] Num a => Num (NonNegative a)
instance [overlap ok] Integral a => Integral (NonNegative a)
instance [overlap ok] Real a => Real (NonNegative a)
instance [overlap ok] Enum a => Enum (NonNegative a)
instance [overlap ok] Show a => Show (NonEmpty a)
instance [overlap ok] Serial m a => Serial m (NonEmpty a)
instance [overlap ok] Show a => Show (NonNegative a)
instance [overlap ok] (Num a, Ord a, Serial m a) => Serial m (NonNegative a)
instance [overlap ok] Show a => Show (Positive a)
instance [overlap ok] (Num a, Ord a, Serial m a) => Serial m (Positive a)
instance [overlap ok] (Serial Identity a, Show a, Show b) => Show (a -> b)
instance [overlap ok] (Serial m a, CoSerial m a, Serial m b, CoSerial m b) => CoSerial m (a -> b)
instance [overlap ok] (CoSerial m a, Serial m b) => Serial m (a -> b)
instance [overlap ok] CoSerial m a => CoSerial m [a]
instance [overlap ok] Serial m a => Serial m [a]
instance [overlap ok] (CoSerial m a, CoSerial m b) => CoSerial m (Either a b)
instance [overlap ok] (Serial m a, Serial m b) => Serial m (Either a b)
instance [overlap ok] CoSerial m a => CoSerial m (Maybe a)
instance [overlap ok] Serial m a => Serial m (Maybe a)
instance [overlap ok] Monad m => CoSerial m Bool
instance [overlap ok] Monad m => Serial m Bool
instance [overlap ok] (CoSerial m a, CoSerial m b, CoSerial m c, CoSerial m d) => CoSerial m (a, b, c, d)
instance [overlap ok] (Serial m a, Serial m b, Serial m c, Serial m d) => Serial m (a, b, c, d)
instance [overlap ok] (CoSerial m a, CoSerial m b, CoSerial m c) => CoSerial m (a, b, c)
instance [overlap ok] (Serial m a, Serial m b, Serial m c) => Serial m (a, b, c)
instance [overlap ok] (CoSerial m a, CoSerial m b) => CoSerial m (a, b)
instance [overlap ok] (Serial m a, Serial m b) => Serial m (a, b)
instance [overlap ok] Monad m => CoSerial m Char
instance [overlap ok] Monad m => Serial m Char
instance [overlap ok] (Integral i, CoSerial m i) => CoSerial m (Ratio i)
instance [overlap ok] (Integral i, Serial m i) => Serial m (Ratio i)
instance [overlap ok] Monad m => CoSerial m Double
instance [overlap ok] Monad m => Serial m Double
instance [overlap ok] Monad m => CoSerial m Float
instance [overlap ok] Monad m => Serial m Float
instance [overlap ok] (Integral a, Monad m) => CoSerial m (N a)
instance [overlap ok] (Integral a, Serial m a) => Serial m (N a)
instance [overlap ok] Monad m => CoSerial m Integer
instance [overlap ok] Monad m => Serial m Integer
instance [overlap ok] Monad m => CoSerial m Int
instance [overlap ok] Monad m => Serial m Int
instance [overlap ok] Monad m => CoSerial m ()
instance [overlap ok] Monad m => Serial m ()
instance [overlap ok] GSerial m f => GSerial m (C1 c f)
instance [overlap ok] (Monad m, GCoSerial m a, GCoSerial m b) => GCoSerial m (a :+: b)
instance [overlap ok] (Monad m, GSerial m a, GSerial m b) => GSerial m (a :+: b)
instance [overlap ok] (Monad m, GCoSerial m a, GCoSerial m b) => GCoSerial m (a :*: b)
instance [overlap ok] (Monad m, GSerial m a, GSerial m b) => GSerial m (a :*: b)
instance [overlap ok] GCoSerial m U1
instance [overlap ok] GSerial m U1
instance [overlap ok] CoSerial m c => GCoSerial m (K1 i c)
instance [overlap ok] Serial m c => GSerial m (K1 i c)
instance [overlap ok] GCoSerial m f => GCoSerial m (M1 i c f)
instance [overlap ok] GSerial m f => GSerial m (M1 i c f)


-- | 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

-- | 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

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

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