Copyright  (c) Colin Runciman et al. 

License  BSD3 
Maintainer  Roman Cheplyaka <roma@roche.info> 
Safe Haskell  Safe 
Language  Haskell2010 
You need this module if you want to generate test values of your own types.
You'll typically need the following extensions:
{# LANGUAGE FlexibleInstances, MultiParamTypeClasses #}
SmallCheck itself defines data generators for all the data types used by the Prelude.
In order to generate values and functions of your own types, you need
to make them instances of Serial
(for values) and CoSerial
(for
functions). There are two main ways to do so: using Generics or writing
the instances by hand.
Synopsis
 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
 cons5 :: (Serial m a, Serial m b, Serial m c, Serial m d, Serial m e) => (a > b > c > d > e > f) > Series m f
 cons6 :: (Serial m a, Serial m b, Serial m c, Serial m d, Serial m e, Serial m f) => (a > b > c > d > e > f > g) > Series m g
 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)
 alts5 :: (CoSerial m a, CoSerial m b, CoSerial m c, CoSerial m d, CoSerial m e) => Series m f > Series m (a > b > c > d > e > f)
 alts6 :: (CoSerial m a, CoSerial m b, CoSerial m c, CoSerial m d, CoSerial m e, CoSerial m f) => Series m g > Series m (a > b > c > d > e > f > g)
 newtypeAlts :: CoSerial m a => Series m b > Series m (a > b)
 type Depth = Int
 data Series m a
 class Monad m => Serial m a where
 class Monad m => CoSerial m a where
 genericSeries :: (Monad m, Generic a, GSerial m (Rep a)) => Series m a
 genericCoseries :: (Monad m, Generic a, GCoSerial m (Rep a)) => Series m b > Series m (a > b)
 newtype Positive a = Positive {
 getPositive :: a
 newtype NonNegative a = NonNegative {
 getNonNegative :: a
 newtype NonZero a = NonZero {
 getNonZero :: a
 newtype NonEmpty a = NonEmpty {
 getNonEmpty :: [a]
 (\/) :: Monad m => Series m a > Series m a > Series m a
 (><) :: Monad m => Series m a > Series m b > Series m (a, b)
 (<~>) :: Monad m => Series m (a > b) > Series m a > Series m b
 (>>) :: MonadLogic m => m a > (a > m b) > m b
 localDepth :: (Depth > Depth) > Series m a > Series m a
 decDepth :: Series m a > Series m a
 getDepth :: Series m Depth
 generate :: (Depth > [a]) > Series m a
 limit :: forall m a. Monad m => Int > Series m a > Series m a
 listSeries :: Serial Identity a => Depth > [a]
 list :: Depth > Series Identity a > [a]
 listM :: Applicative m => Depth > Series m a > m [a]
 fixDepth :: Series m a > Series m (Series m a)
 decDepthChecked :: Series m a > Series m a > Series m a
 constM :: Monad m => m b > m (a > b)
Generic instances
The easiest way to create the necessary instances is to use GHC generics (available starting with GHC 7.2.1).
Here's a complete example:
{# LANGUAGE FlexibleInstances, MultiParamTypeClasses #} {# LANGUAGE DeriveGeneric #} import Test.SmallCheck.Series import GHC.Generics data Tree a = Null  Fork (Tree a) a (Tree a) deriving Generic instance Serial m a => Serial m (Tree a)
Here we enable the DeriveGeneric
extension which allows to derive Generic
instance for our data type. Then we declare that Tree
a
is an instance of
Serial
, but do not provide any definitions. This causes GHC to use the
default definitions that use the Generic
instance.
One minor limitation of generic instances is that there's currently no way to distinguish newtypes and datatypes. Thus, newtype constructors will also count as one level of depth.
Data Generators
Writing Serial
instances for applicationspecific types is
straightforward. You need to define a series
generator, typically using
consN
family of generic combinators where N is constructor arity.
For example:
data Tree a = Null  Fork (Tree a) a (Tree a) instance Serial m a => Serial m (Tree a) where series = cons0 Null \/ cons3 Fork
For newtypes use newtypeCons
instead of cons1
.
The difference is that cons1
is counts as one level of depth, while
newtypeCons
doesn't affect the depth.
newtype Light a = Light a instance Serial m a => Serial m (Light a) where series = newtypeCons Light
For data types with more than 6 fields define consN
as
consN f = decDepth $ f <$> series <~> series <~> series <~> ... { series repeated N times in total }
What does consN
do, exactly?
consN
has type
(Serial t₁, ..., Serial tₙ) => (t₁ > ... > tₙ > t) > Series t
.
consN
f
is a series which, for a given depth \(d > 0\), produces values of the
form
f x₁ ... xₙ
where xₖ
ranges over all values of type tₖ
of depth up to \(d1\)
(as defined by the series
functions for tₖ
).
consN
functions also ensure that xₖ are enumerated in the
breadthfirst order. Thus, combinations of smaller depth come first
(assuming the same is true for tₖ
).
If \(d \le 0\), no values are produced.
cons3 :: (Serial m a, Serial m b, Serial m c) => (a > b > c > d) > Series m d Source #
Since: 1.0
cons4 :: (Serial m a, Serial m b, Serial m c, Serial m d) => (a > b > c > d > e) > Series m e Source #
Since: 1.0
cons5 :: (Serial m a, Serial m b, Serial m c, Serial m d, Serial m e) => (a > b > c > d > e > f) > Series m f Source #
Since: 1.2.0
cons6 :: (Serial m a, Serial m b, Serial m c, Serial m d, Serial m e, Serial m f) => (a > b > c > d > e > f > g) > Series m g Source #
Since: 1.2.0
newtypeCons :: Serial m a => (a > b) > Series m b Source #
Same as cons1
, but preserves the depth.
Since: 1.0
Function Generators
To generate functions of an applicationspecific argument type,
make the type an instance of CoSerial
.
Again there is a standard pattern, this time using the altsN
combinators where again N is constructor arity. Here are Tree
and
Light
instances:
instance CoSerial m a => CoSerial m (Tree a) where coseries rs = alts0 rs >> \z > alts3 rs >> \f > return $ \t > case t of Null > z Fork t1 x t2 > f t1 x t2
instance CoSerial m a => CoSerial m (Light a) where coseries rs = newtypeAlts rs >> \f > return $ \l > case l of Light x > f x
For data types with more than 6 fields define altsN
as
altsN rs = do rs < fixDepth rs decDepthChecked (constM $ constM $ ... $ constM rs) (coseries $ coseries $ ... $ coseries rs) { constM and coseries are repeated N times each }
What does altsN do, exactly?
altsN
has type
(Serial t₁, ..., Serial tₙ) => Series t > Series (t₁ > ... > tₙ > t)
.
altsN
s
is a series which, for a given depth \( d \), produces functions of
type
t₁ > ... > tₙ > t
If \( d \le 0 \), these are constant functions, one for each value produced
by s
.
If \( d > 0 \), these functions inspect each of their arguments up to the depth
\( d1 \) (as defined by the coseries
functions for the corresponding
types) and return values produced by s
. The depth to which the
values are enumerated does not depend on the depth of inspection.
alts3 :: (CoSerial m a, CoSerial m b, CoSerial m c) => Series m d > Series m (a > b > c > d) Source #
Since: 1.0
alts4 :: (CoSerial m a, CoSerial m b, CoSerial m c, CoSerial m d) => Series m e > Series m (a > b > c > d > e) Source #
Since: 1.0
alts5 :: (CoSerial m a, CoSerial m b, CoSerial m c, CoSerial m d, CoSerial m e) => Series m f > Series m (a > b > c > d > e > f) Source #
Since: 1.2.0
alts6 :: (CoSerial m a, CoSerial m b, CoSerial m c, CoSerial m d, CoSerial m e, CoSerial m f) => Series m g > Series m (a > b > c > d > e > f > g) Source #
Since: 1.2.0
newtypeAlts :: CoSerial m a => Series m b > Series m (a > b) Source #
Same as alts1
, but preserves the depth.
Since: 1.0
Basic definitions
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.
Since: 0.6
Series
is a MonadLogic
action that enumerates values of a certain
type, up to some depth.
The depth bound is tracked in the Series
monad and can be extracted using
getDepth
and changed using localDepth
.
To manipulate series at the lowest level you can use its Monad
,
MonadPlus
and MonadLogic
instances. This module provides some
higherlevel combinators which simplify creating series.
A proper Series
should be monotonic with respect to the depth — i.e.
localDepth
(+1)
s
should emit all the values that s
emits (and
possibly some more).
It is also desirable that values of smaller depth come before the values of greater depth.
Since: 1.0
Instances
MonadTrans Series Source #  
Defined in Test.SmallCheck.SeriesMonad  
Alternative (Series m) Source #  
Applicative (Series m) Source #  
Functor (Series m) Source #  
Monad (Series m) Source #  
MonadPlus (Series m) Source #  
Monad m => MonadLogic (Series m) Source #  
Defined in Test.SmallCheck.SeriesMonad msplit :: Series m a > Series m (Maybe (a, Series m a)) # interleave :: Series m a > Series m a > Series m a # (>>) :: Series m a > (a > Series m b) > Series m b # once :: Series m a > Series m a # lnot :: Series m a > Series m () # ifte :: Series m a > (a > Series m b) > Series m b > Series m b # 
class Monad m => Serial m a where Source #
Since: 1.0
Nothing
Instances
class Monad m => CoSerial m a where Source #
Since: 1.0
Nothing
coseries :: Series m b > Series m (a > b) Source #
A proper coseries
implementation should pass the depth unchanged to
its first argument. Doing otherwise will make enumeration of curried
functions nonuniform in their arguments.
Instances
Generic implementations
genericCoseries :: (Monad m, Generic a, GCoSerial m (Rep a)) => Series m b > Series m (a > b) Source #
Since: 1.1.5
Convenient wrappers
Positive
x
guarantees that \( x > 0 \).
Since: 1.0
Positive  

Instances
newtype NonNegative a Source #
NonNegative
x
guarantees that \( x \ge 0 \).
Since: 1.0
Instances
NonZero
x
guarantees that \( x \ne 0 \).
Since: 1.2.0
NonZero  

Instances
Other useful definitions
(\/) :: Monad m => Series m a > Series m a > Series m a infixr 7 Source #
Sum (union) of series.
Since: 1.0
(><) :: Monad m => Series m a > Series m b > Series m (a, b) infixr 8 Source #
Product of series
Since: 1.0
(>>) :: MonadLogic m => m a > (a > m b) > m b infixl 1 #
Fair conjunction. Similarly to the previous function, consider
the distributivity law, naturally expected from MonadPlus
:
(a <> b) >>= k = (a >>= k) <> (b >>= k)
If a
>>=
k
can backtrack arbitrarily many times, b
>>=
k
may never be considered. In logic statements,
"backtracking" is the process of discarding the current
possible solution value and returning to a previous decision
point where a new value can be obtained and tried. For
example:
>>>
do { x < pure 0 <> pure 1 <> pure 2; if even x then pure x else empty } :: [Int]
[0,2]
Here, the x
value can be produced three times, where
<>
represents the decision points of that
production. The subsequent if
statement specifies
empty
(fail)
if x
is odd, causing it to be discarded and a return
to an <>
decision point to get the next x
.
The statement "a
>>=
k
can backtrack arbitrarily many
times" means that the computation is resulting in empty
and
that a
has an infinite number of <>
applications to
return to. This is called a conjunctive computation because
the logic for a
and k
must both succeed (i.e. pure
a value instead of empty
).
Similar to the way interleave
allows both branches of a
disjunctive computation, the >>
operator takes care to
consider both branches of a conjunctive computation.
Consider the operation:
odds = pure 1 <> fmap (2 +) odds oddsPlus n = odds >>= \a > pure (a + n) g = do x < (pure 0 <> pure 1) >>= oddsPlus if even x then pure x else empty
>>>
observeMany 3 g
...never completes...
This will never produce any value because all values produced
by the do
program come from the pure
1
driven operation
(adding one to the sequence of odd values, resulting in the
even values that are allowed by the test in the second line),
but the pure
0
input to oddsPlus
generates an infinite
number of empty
failures so the even values generated by
the pure
1
alternative are never seen. Using
interleave
here instead of <>
does not help due
to the aforementioned distributivity law.
Also note that the do
notation desugars to >>=
bind
operations, so the following would also fail:
do a < pure 0 <> pure 1 x < oddsPlus a if even x then pure x else empty
The solution is to use the >>
in place of the normal
monadic bind operation >>=
when fairness between
alternative productions is needed in a conjunction of
statements (rules):
h = do x < (pure 0 <> pure 1) >> oddsPlus if even x then pure x else empty
>>>
observeMany 3 h
[2,4,6]
However, a bit of care is needed when using >>
because,
unlike >>=
, it is not associative. For example:
>>>
let m = [2,7] :: [Int]
>>>
let k x = [x, x + 1]
>>>
let h x = [x, x * 2]
>>>
m >>= (\x > k x >>= h)
[2,4,3,6,7,14,8,16]>>>
(m >>= k) >>= h  same as above
[2,4,3,6,7,14,8,16]>>>
m >> (\x > k x >> h)
[2,7,3,8,4,14,6,16]>>>
(m >> k) >> h  central elements are different
[2,7,4,3,14,8,6,16]
This means that the following will be productive:
(pure 0 <> pure 1) >> oddsPlus >> \x > if even x then pure x else empty
Which is equivalent to
((pure 0 <> pure 1) >> oddsPlus) >> (\x > if even x then pure x else empty)
But the following will not be productive:
(pure 0 <> pure 1) >> (\a > (oddsPlus a >> \x > if even x then pure x else empty))
Since do notation desugaring results in the latter, the
RebindableSyntax
language pragma cannot easily be used
either. Instead, it is recommended to carefully use explicit
>>
only when needed.
localDepth :: (Depth > Depth) > Series m a > Series m a Source #
Run a series with a modified depth.
Since: 1.0
generate :: (Depth > [a]) > Series m a Source #
A simple series specified by a function from depth to the list of values up to that depth.
Since: 1.0
limit :: forall m a. Monad m => Int > Series m a > Series m a Source #
Limit a Series
to its first n
elements.
Since: 1.1.5
listSeries :: Serial Identity a => Depth > [a] Source #
Given a depth, return the list of values generated by a Serial
instance.
For example, list all integers up to depth 1:
listSeries 1 :: [Int]  returns [0,1,1]
Since: 1.1.2
list :: Depth > Series Identity a > [a] Source #
Return the list of values generated by a Series
. Useful for
debugging Serial
instances.
Examples:
list
3series
:: [Int
]  returns [0,1,1,2,2,3,3]list
3 (series
::Series
Identity
Int
)  returns [0,1,1,2,2,3,3]list
2series
:: [[Bool
]]  returns [[],[True
],[False
]]
The first two are equivalent. The second has a more explicit type binding.
Since: 1.0
fixDepth :: Series m a > Series m (Series m a) Source #
Fix the depth of a series at the current level. The resulting series will no longer depend on the "ambient" depth.
Since: 1.1.1
decDepthChecked :: Series m a > Series m a > Series m a Source #
If the current depth is 0, evaluate the first argument. Otherwise, evaluate the second argument with decremented depth.
Since: 1.1.1