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


-- | Get counterexamples from QuickCheck as Haskell values
--   
--   When QuickCheck finds a counterexample, it prints it out but doesn't
--   save it so that the programmer can access it. This can be annoying
--   when debugging.
--   
--   This library provides a small extension to QuickCheck that returns
--   counterexamples as normal Haskell values. To use it, just import
--   <a>Test.QuickCheck.Counterexamples</a> <i>instead of</i>
--   <tt>Test.QuickCheck</tt>. The library is largely compatible with
--   normal QuickCheck, but the return types of <a>quickCheck</a> and
--   related functions are changed to include a counterexample.
--   
--   For usage information, see the <a>Test.QuickCheck.Counterexamples</a>
--   module.
@package quickcheck-with-counterexamples
@version 1.0


-- | This module extends QuickCheck so that it returns counterexamples as
--   Haskell values instead of just printing them. To use it, import this
--   module <i>instead of</i> <a>Test.QuickCheck</a>. The API and
--   functionality are the same as normal QuickCheck; the only difference
--   is that the return types of <a>quickCheck</a> (and related functions)
--   include a counterexample.
--   
--   Note that this module re-exports most functions from
--   <a>Test.QuickCheck</a>. Those functions are <i>not</i> documented
--   here! You will need to refer to the main <a>Test.QuickCheck</a>
--   documentation when using this module.
--   
--   Here is an example of getting counterexamples. Suppose we have the
--   following property:
--   
--   <pre>
--   prop_reverse_append :: [Int] -&gt; [Int] -&gt; Property
--   prop_reverse_append xs ys =
--     reverse (xs++ys) === reverse xs ++ reverse ys
--   </pre>
--   
--   If we look the type of <tt>quickCheck prop_reverse_append</tt>, we see
--   that it returns a counterexample:
--   
--   <pre>
--   &gt;&gt;&gt; :t quickCheck prop_reverse_append
--   quickCheck prop_reverse_append :: IO (Maybe ([Int] :&amp;: [Int] :&amp;: ()))
--   </pre>
--   
--   The <a>Maybe</a> is there because <a>quickCheck</a> will return
--   <a>Nothing</a> if the property succeeds; <a>:&amp;:</a> is a datatype
--   of pairs.
--   
--   If we run QuickCheck, we can get the counterexample as a normal
--   Haskell value:
--   
--   <pre>
--   &gt;&gt;&gt; Just (xs :&amp;: ys :&amp;: ()) &lt;- quickCheck prop_reverse_append
--   *** Failed! Falsifiable (after 5 tests and 4 shrinks):
--   [0]
--   [1]
--   [1,0] /= [0,1]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :t xs
--   xs :: [Int]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; xs
--   [0]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ys
--   [1]
--   </pre>
--   
--   Here is how this module's API differs from normal QuickCheck, in more
--   detail:
--   
--   <ul>
--   <li>The <a>Testable</a> class now has an associated type
--   <a>Counterexample</a> which describes the counterexample.
--   <a>Property</a> is now a synonym for <tt><a>PropertyOf</a> ()</tt>,
--   where <tt><a>PropertyOf</a> cex</tt> represents a property with an
--   associated counterexample <tt>cex</tt>. The QuickCheck property
--   combinators preserve the counterexample, by returning
--   <a>PropertyOf</a> instead of <a>Property</a>.</li>
--   <li><a>quickCheck</a> and related functions return a
--   <tt><a>Counterexample</a> prop</tt>.</li>
--   <li>Finally, there are a couple of new combinators, documented
--   below.</li>
--   </ul>
module Test.QuickCheck.Counterexamples

-- | A property. <tt>cex</tt> is the type of counterexamples to the
--   property.
--   
--   Note that there is a <a>Functor</a> instance, which is useful when you
--   want to manipulate the counterexample, e.g., to change its type. For
--   example, when some branches of your property produce a counterexample
--   and other branches do not, the types will not match up, but using
--   <a>fmap</a> you can make the counterexample be a <a>Maybe</a>.
newtype PropertyOf cex
MkProperty :: ((cex -> IO ()) -> Property) -> PropertyOf cex

-- | Implementation note: the property receives a callback to which it
--   should pass the counterexample after shrinking.
[unProperty] :: PropertyOf cex -> (cex -> IO ()) -> Property

-- | A property which doesn't produce a counterexample.
type Property = PropertyOf ()

-- | A type synonym for the property which comes from a particular
--   <a>Testable</a> instance.
type PropertyFrom prop = PropertyOf (Counterexample prop)

-- | The class of properties, i.e. types which QuickCheck knows how to
--   test.
class Testable prop => Testable prop where {
    type family Counterexample prop;
}

-- | Convert the property to a <a>PropertyOf</a>.
property :: Testable prop => prop -> PropertyFrom prop

-- | A type of pairs. Used in counterexamples.
data a (:&:) b
(:&:) :: a -> b -> (:&:) a b

-- | Add a value to the counterexample.
typedCounterexample :: Testable prop => a -> prop -> PropertyOf (a :&: Counterexample prop)

-- | Lift an ordinary QuickCheck property combinator to one with
--   counterexamples.
onProperty :: Testable prop => (Property -> Property) -> prop -> PropertyFrom prop

-- | See <a>quickCheck</a> in <a>Test.QuickCheck</a>.
quickCheck :: Testable prop => prop -> IO (Maybe (Counterexample prop))

-- | See <a>quickCheckWith</a> in <a>Test.QuickCheck</a>.
quickCheckWith :: Testable prop => Args -> prop -> IO (Maybe (Counterexample prop))

-- | See <a>quickCheckResult</a> in <a>Test.QuickCheck</a>.
quickCheckResult :: Testable prop => prop -> IO (Maybe (Counterexample prop), Result)

-- | See <a>quickCheckWithResult</a> in <a>Test.QuickCheck</a>.
quickCheckWithResult :: Testable prop => Args -> prop -> IO (Maybe (Counterexample prop), Result)

-- | See <a>verboseCheck</a> in <a>Test.QuickCheck</a>.
verboseCheck :: Testable prop => prop -> IO (Maybe (Counterexample prop))

-- | See <a>verboseCheckWith</a> in <a>Test.QuickCheck</a>.
verboseCheckWith :: Testable prop => Args -> prop -> IO (Maybe (Counterexample prop))

-- | See <a>verboseCheckResult</a> in <a>Test.QuickCheck</a>.
verboseCheckResult :: Testable prop => prop -> IO (Maybe (Counterexample prop), Result)

-- | See <a>verboseCheckWithResult</a> in <a>Test.QuickCheck</a>.
verboseCheckWithResult :: Testable prop => Args -> prop -> IO (Maybe (Counterexample prop), Result)

-- | See <a>polyQuickCheck</a> in <a>Test.QuickCheck</a>.
polyQuickCheck :: Name -> ExpQ

-- | See <a>polyVerboseCheck</a> in <a>Test.QuickCheck</a>.
polyVerboseCheck :: Name -> ExpQ

-- | See <a>forAll</a> in <a>Test.QuickCheck</a>.
forAll :: (Testable prop, Show a) => Gen a -> (a -> prop) -> PropertyOf (a :&: Counterexample prop)

-- | See <a>forAllShrink</a> in <a>Test.QuickCheck</a>.
forAllShrink :: (Testable prop, Show a) => Gen a -> (a -> [a]) -> (a -> prop) -> PropertyOf (a :&: Counterexample prop)

-- | See <a>shrinking</a> in <a>Test.QuickCheck</a>.
shrinking :: Testable prop => (a -> [a]) -> a -> (a -> prop) -> PropertyFrom prop

-- | See <a>==&gt;</a> in <a>Test.QuickCheck</a>.
(==>) :: Testable prop => Bool -> prop -> PropertyFrom prop
infixr 0 ==>

-- | See <a>===</a> in <a>Test.QuickCheck</a>.
(===) :: (Eq a, Show a) => a -> a -> Property
infix 4 ===

-- | See <a>ioProperty</a> in <a>Test.QuickCheck</a>.
ioProperty :: Testable prop => IO prop -> PropertyFrom prop

-- | See <a>verbose</a> in <a>Test.QuickCheck</a>.
verbose :: Testable prop => prop -> PropertyFrom prop

-- | See <a>once</a> in <a>Test.QuickCheck</a>.
once :: Testable prop => prop -> PropertyFrom prop

-- | See <a>again</a> in <a>Test.QuickCheck</a>.
again :: Testable prop => prop -> PropertyFrom prop

-- | See <a>within</a> in <a>Test.QuickCheck</a>.
within :: Testable prop => Int -> prop -> PropertyFrom prop

-- | See <a>noShrinking</a> in <a>Test.QuickCheck</a>.
noShrinking :: Testable prop => prop -> PropertyFrom prop

-- | See <a>counterexample</a> in <a>Test.QuickCheck</a>.
counterexample :: Testable prop => String -> prop -> PropertyFrom prop

-- | See <a>whenFail</a> in <a>Test.QuickCheck</a>.
whenFail :: Testable prop => IO () -> prop -> PropertyFrom prop

-- | See <a>whenFail'</a> in <a>Test.QuickCheck</a>.
whenFail' :: Testable prop => IO () -> prop -> PropertyFrom prop

-- | See <a>expectFailure</a> in <a>Test.QuickCheck</a>.
expectFailure :: Testable prop => prop -> PropertyFrom prop

-- | See <a>label</a> in <a>Test.QuickCheck</a>.
label :: Testable prop => String -> prop -> PropertyFrom prop

-- | See <a>collect</a> in <a>Test.QuickCheck</a>.
collect :: (Show a, Testable prop) => a -> prop -> PropertyFrom prop

-- | See <a>classify</a> in <a>Test.QuickCheck</a>.
classify :: Testable prop => Bool -> String -> prop -> PropertyFrom prop

-- | See <a>cover</a> in <a>Test.QuickCheck</a>.
cover :: Testable prop => Bool -> Int -> String -> prop -> PropertyFrom prop

-- | See <a>mapSize</a> in <a>Test.QuickCheck</a>.
mapSize :: Testable prop => (Int -> Int) -> prop -> PropertyFrom prop
instance (GHC.Read.Read b, GHC.Read.Read a) => GHC.Read.Read (a Test.QuickCheck.Counterexamples.:&: b)
instance (GHC.Show.Show b, GHC.Show.Show a) => GHC.Show.Show (a Test.QuickCheck.Counterexamples.:&: b)
instance (GHC.Classes.Ord b, GHC.Classes.Ord a) => GHC.Classes.Ord (a Test.QuickCheck.Counterexamples.:&: b)
instance (GHC.Classes.Eq b, GHC.Classes.Eq a) => GHC.Classes.Eq (a Test.QuickCheck.Counterexamples.:&: b)
instance GHC.Base.Functor Test.QuickCheck.Counterexamples.PropertyOf
instance (GHC.Show.Show a, Test.QuickCheck.Arbitrary.Arbitrary a, Test.QuickCheck.Counterexamples.Testable b) => Test.QuickCheck.Counterexamples.Testable (a -> b)
instance Test.QuickCheck.Counterexamples.Testable Test.QuickCheck.Property.Discard
instance Test.QuickCheck.Counterexamples.Testable GHC.Types.Bool
instance Test.QuickCheck.Counterexamples.Testable Test.QuickCheck.Property.Property
instance Test.QuickCheck.Counterexamples.Testable prop => Test.QuickCheck.Counterexamples.Testable (Test.QuickCheck.Gen.Gen prop)
instance Test.QuickCheck.Counterexamples.Testable (Test.QuickCheck.Counterexamples.PropertyOf cex)
instance Test.QuickCheck.Property.Testable (Test.QuickCheck.Counterexamples.PropertyOf cex)
