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


-- | Testing utilities for the validity library
--   
--   Note: There are companion instance packages for this library:
--   
--   <ul>
--   <li><a>genvalidity-text</a></li>
--   <li><a>genvalidity-containers</a></li>
--   </ul>
@package genvalidity
@version 0.2.0.3


-- | <tt>GenValidity</tt> exists to make tests involving <tt>Validity</tt>
--   types easier and speed up the generation of data for them.
--   
--   Let's use the example from <tt>Data.Validity</tt> again: A datatype
--   that represents primes. To implement tests for this datatype, we would
--   have to be able to generate both primes and non-primes. We could do
--   this with <tt>(Prime <a>$</a> arbitrary) <a>suchThat</a> isValid</tt>
--   but this is tedious and inefficient.
--   
--   The <tt>GenValidity</tt> type class allows you to specify how to
--   (efficiently) generate data of the given type to allow for easier and
--   quicker testing. Just implementing <tt>genUnchecked</tt> already gives
--   you access to <tt>genValid</tt> and <tt>genInvalid</tt> but writing
--   custom implementations of these functions may speed up the generation
--   of data.
--   
--   For example, to generate primes, we don't have to consider even
--   numbers other than 2. A more efficient implementation could then look
--   as follows:
--   
--   <pre>
--   instance GenValidity Prime where
--       genUnchecked = Prime &lt;$&gt; arbitrary
--       genValid = Prime &lt;$&gt;
--          (oneof
--            [ pure 2
--            , (\y -&gt; 2 * y + 1) &lt;$&gt; (arbitrary `suchThat` (&gt; 0) `suchThat` isPrime)
--            ])
--   </pre>
--   
--   Typical examples of tests involving validity could look as follows:
--   
--   <pre>
--   it "succeeds when given valid input" $ do
--       forAll genValid $ \input -&gt;
--           myFunction input `shouldSatisfy` isRight
--   </pre>
--   
--   <pre>
--   it "produces valid output when it succeeds" $ do
--       forAll genUnchecked $ \input -&gt;
--           case myFunction input of
--               Nothing -&gt; return () -- Can happen
--               Just output -&gt; output `shouldSatisfy` isValid
--   </pre>
module Data.GenValidity

-- | A class of types for which <tt>Validity</tt>-related values can be
--   generated.
--   
--   If you also write <tt>Arbitrary</tt> instances for
--   <tt>GenValidity</tt> types, it may be best to simply write
--   <tt>arbitrary = genValid</tt>.
class Validity a => GenValidity a where genValid = genUnchecked `suchThat` isValid genInvalid = genUnchecked `suchThat` (not . isValid)

-- | Generate a truly arbitrary datum, this should cover all possible
--   values in the type
genUnchecked :: GenValidity a => Gen a

-- | Generate a valid datum, this should cover all possible valid values in
--   the type
--   
--   The default implementation is as follows:
--   
--   <pre>
--   genValid = genUnchecked `suchThat` isValid
--   </pre>
--   
--   To speed up testing, it may be a good idea to implement this yourself.
--   If you do, make sure that it is possible to generate all possible
--   valid data, otherwise your testing may not cover all cases.
genValid :: GenValidity a => Gen a

-- | Generate an invalid datum, this should cover all possible invalid
--   values
--   
--   <pre>
--   genInvalid = genUnchecked `suchThat` (not . isValid)
--   </pre>
--   
--   To speed up testing, it may be a good idea to implement this yourself.
--   If you do, make sure that it is possible to generate all possible
--   invalid data, otherwise your testing may not cover all cases.
genInvalid :: GenValidity a => Gen a

-- | If we can generate values of a certain type, we can also generate
--   lists of them. This instance ensures that <tt>genValid</tt> generates
--   only lists of valid data and that <tt>genInvalid</tt> generates lists
--   of data such that there is at least one value in there that does not
--   satisfy <tt>isValid</tt>, the rest is unchecked.
upTo :: Int -> Gen Int
genSplit :: Int -> Gen (Int, Int)
genSplit3 :: Int -> Gen (Int, Int, Int)
arbPartition :: Int -> Gen [Int]

-- | A version of <tt>listOf</tt> that takes size into account more
--   accurately.
genListOf :: Gen a -> Gen [a]
instance (Data.GenValidity.GenValidity a, Data.GenValidity.GenValidity b) => Data.GenValidity.GenValidity (a, b)
instance (Data.GenValidity.GenValidity a, Data.GenValidity.GenValidity b, Data.GenValidity.GenValidity c) => Data.GenValidity.GenValidity (a, b, c)
instance Data.GenValidity.GenValidity a => Data.GenValidity.GenValidity (GHC.Base.Maybe a)
instance Data.GenValidity.GenValidity a => Data.GenValidity.GenValidity [a]

module Data.GenRelativeValidity
class (GenValidity a, RelativeValidity a b) => GenRelativeValidity a b where genUncheckedFor _ = genUnchecked genValidFor b = genValid `suchThat` (`isValidFor` b) genInvalidFor b = genUncheckedFor b `suchThat` (not . (`isValidFor` b))
genUncheckedFor :: GenRelativeValidity a b => b -> Gen a
genValidFor :: GenRelativeValidity a b => b -> Gen a
genInvalidFor :: GenRelativeValidity a b => b -> Gen a