Safe Haskell | None |
---|---|

Language | Haskell98 |

- data Gen m a
- shrink :: Monad m => (a -> [a]) -> Gen m a -> Gen m a
- prune :: Monad m => Gen m a -> Gen m a
- small :: Gen m a -> Gen m a
- scale :: (Size -> Size) -> Gen m a -> Gen m a
- resize :: Size -> Gen m a -> Gen m a
- sized :: (Size -> Gen m a) -> Gen m a
- integral :: (Monad m, Integral a) => Range a -> Gen m a
- integral_ :: (Monad m, Integral a) => Range a -> Gen m a
- int :: Monad m => Range Int -> Gen m Int
- int8 :: Monad m => Range Int8 -> Gen m Int8
- int16 :: Monad m => Range Int16 -> Gen m Int16
- int32 :: Monad m => Range Int32 -> Gen m Int32
- int64 :: Monad m => Range Int64 -> Gen m Int64
- word :: Monad m => Range Word -> Gen m Word
- word8 :: Monad m => Range Word8 -> Gen m Word8
- word16 :: Monad m => Range Word16 -> Gen m Word16
- word32 :: Monad m => Range Word32 -> Gen m Word32
- word64 :: Monad m => Range Word64 -> Gen m Word64
- realFloat :: (Monad m, RealFloat a) => Range a -> Gen m a
- realFrac_ :: (Monad m, RealFrac a) => Range a -> Gen m a
- float :: Monad m => Range Float -> Gen m Float
- double :: Monad m => Range Double -> Gen m Double
- enum :: (Monad m, Enum a) => a -> a -> Gen m a
- enumBounded :: (Monad m, Enum a, Bounded a) => Gen m a
- bool :: Monad m => Gen m Bool
- bool_ :: Monad m => Gen m Bool
- binit :: Monad m => Gen m Char
- octit :: Monad m => Gen m Char
- digit :: Monad m => Gen m Char
- hexit :: Monad m => Gen m Char
- lower :: Monad m => Gen m Char
- upper :: Monad m => Gen m Char
- alpha :: Monad m => Gen m Char
- alphaNum :: Monad m => Gen m Char
- ascii :: Monad m => Gen m Char
- latin1 :: Monad m => Gen m Char
- unicode :: Monad m => Gen m Char
- unicodeAll :: Monad m => Gen m Char
- string :: Monad m => Range Int -> Gen m Char -> Gen m String
- text :: Monad m => Range Int -> Gen m Char -> Gen m Text
- utf8 :: Monad m => Range Int -> Gen m Char -> Gen m ByteString
- bytes :: Monad m => Range Int -> Gen m ByteString
- constant :: Monad m => a -> Gen m a
- element :: Monad m => [a] -> Gen m a
- choice :: Monad m => [Gen m a] -> Gen m a
- frequency :: Monad m => [(Int, Gen m a)] -> Gen m a
- recursive :: ([Gen m a] -> Gen m a) -> [Gen m a] -> [Gen m a] -> Gen m a
- discard :: Monad m => Gen m a
- filter :: Monad m => (a -> Bool) -> Gen m a -> Gen m a
- just :: Monad m => Gen m (Maybe a) -> Gen m a
- maybe :: Monad m => Gen m a -> Gen m (Maybe a)
- list :: Monad m => Range Int -> Gen m a -> Gen m [a]
- seq :: Monad m => Range Int -> Gen m a -> Gen m (Seq a)
- nonEmpty :: Monad m => Range Int -> Gen m a -> Gen m (NonEmpty a)
- set :: (Monad m, Ord a) => Range Int -> Gen m a -> Gen m (Set a)
- map :: (Monad m, Ord k) => Range Int -> Gen m (k, v) -> Gen m (Map k v)
- subterm :: Monad m => Gen m a -> (a -> a) -> Gen m a
- subtermM :: Monad m => Gen m a -> (a -> Gen m a) -> Gen m a
- subterm2 :: Monad m => Gen m a -> Gen m a -> (a -> a -> a) -> Gen m a
- subtermM2 :: Monad m => Gen m a -> Gen m a -> (a -> a -> Gen m a) -> Gen m a
- subterm3 :: Monad m => Gen m a -> Gen m a -> Gen m a -> (a -> a -> a -> a) -> Gen m a
- subtermM3 :: Monad m => Gen m a -> Gen m a -> Gen m a -> (a -> a -> a -> Gen m a) -> Gen m a
- subsequence :: Monad m => [a] -> Gen m [a]
- shuffle :: Monad m => [a] -> Gen m [a]
- actions :: (Monad n, Monad m) => Range Int -> (forall v. state v) -> [Command n m state] -> Gen n [Action m state]
- sample :: MonadIO m => Gen m a -> m [a]
- print :: (MonadIO m, Show a) => Gen m a -> m ()
- printTree :: (MonadIO m, Show a) => Gen m a -> m ()
- printWith :: (MonadIO m, Show a) => Size -> Seed -> Gen m a -> m ()
- printTreeWith :: (MonadIO m, Show a) => Size -> Seed -> Gen m a -> m ()

# Transformer

Generator for random values of `a`

.

MMonad Gen Source # | |

MonadTrans Gen Source # | |

Distributive Gen Source # | |

MonadBase b m => MonadBase b (Gen m) Source # | |

MonadError e m => MonadError e (Gen m) Source # | |

MonadReader r m => MonadReader r (Gen m) Source # | |

MonadState s m => MonadState s (Gen m) Source # | |

MonadWriter w m => MonadWriter w (Gen m) Source # | |

Monad m => Monad (Gen m) Source # | |

Functor m => Functor (Gen m) Source # | |

Monad m => Applicative (Gen m) Source # | |

MonadIO m => MonadIO (Gen m) Source # | |

Monad m => Alternative (Gen m) Source # | |

Monad m => MonadPlus (Gen m) Source # | |

MonadCatch m => MonadCatch (Gen m) Source # | |

MonadThrow m => MonadThrow (Gen m) Source # | |

PrimMonad m => PrimMonad (Gen m) Source # | |

MonadResource m => MonadResource (Gen m) Source # | |

MFunctor * Gen Source # | |

type Transformer t Gen m Source # | |

type PrimState (Gen m) Source # | |

# Combinators

## Shrinking

shrink :: Monad m => (a -> [a]) -> Gen m a -> Gen m a Source #

Apply a shrinking function to a generator.

This will give the generator additional shrinking options, while keeping the existing shrinks intact.

## Size

scale :: (Size -> Size) -> Gen m a -> Gen m a Source #

Adjust the size parameter by transforming it with the given function.

resize :: Size -> Gen m a -> Gen m a Source #

Override the size parameter. Returns a generator which uses the given size instead of the runtime-size parameter.

sized :: (Size -> Gen m a) -> Gen m a Source #

Construct a generator that depends on the size parameter.

## Integral

integral :: (Monad m, Integral a) => Range a -> Gen m a Source #

Generates a random integral number in the given `[inclusive,inclusive]`

range.

When the generator tries to shrink, it will shrink towards the
`origin`

of the specified `Range`

.

For example, the following generator will produce a number between `1970`

and `2100`

, but will shrink towards `2000`

:

integral (Range.`constantFrom`

2000 1970 2100) ::`Gen`

`Int`

Some sample outputs from this generator might look like:

=== Outcome === 1973 === Shrinks === 2000 1987 1980 1976 1974

=== Outcome === 2061 === Shrinks === 2000 2031 2046 2054 2058 2060

integral_ :: (Monad m, Integral a) => Range a -> Gen m a Source #

Generates a random integral number in the [inclusive,inclusive] range.

*This generator does not shrink.*

int :: Monad m => Range Int -> Gen m Int Source #

Generates a random machine integer in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

int8 :: Monad m => Range Int8 -> Gen m Int8 Source #

Generates a random 8-bit integer in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

int16 :: Monad m => Range Int16 -> Gen m Int16 Source #

Generates a random 16-bit integer in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

int32 :: Monad m => Range Int32 -> Gen m Int32 Source #

Generates a random 32-bit integer in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

int64 :: Monad m => Range Int64 -> Gen m Int64 Source #

Generates a random 64-bit integer in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

word :: Monad m => Range Word -> Gen m Word Source #

Generates a random machine word in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

word8 :: Monad m => Range Word8 -> Gen m Word8 Source #

Generates a random byte in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

word16 :: Monad m => Range Word16 -> Gen m Word16 Source #

Generates a random 16-bit word in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

word32 :: Monad m => Range Word32 -> Gen m Word32 Source #

Generates a random 32-bit word in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

word64 :: Monad m => Range Word64 -> Gen m Word64 Source #

Generates a random 64-bit word in the given `[inclusive,inclusive]`

range.

*This is a specialization of integral, offered for convenience.*

## Floating-point

realFloat :: (Monad m, RealFloat a) => Range a -> Gen m a Source #

Generates a random floating-point number in the `[inclusive,exclusive)`

range.

This generator works the same as `integral`

, but for floating point numbers.

realFrac_ :: (Monad m, RealFrac a) => Range a -> Gen m a Source #

Generates a random fractional number in the [inclusive,exclusive) range.

*This generator does not shrink.*

float :: Monad m => Range Float -> Gen m Float Source #

Generates a random floating-point number in the `[inclusive,exclusive)`

range.

*This is a specialization of realFloat, offered for convenience.*

double :: Monad m => Range Double -> Gen m Double Source #

Generates a random floating-point number in the `[inclusive,exclusive)`

range.

*This is a specialization of realFloat, offered for convenience.*

## Enumeration

bool :: Monad m => Gen m Bool Source #

Generates a random boolean.

This generator shrinks to `False`

.

*This is a specialization of enumBounded, offered for convenience.*

## Characters

alphaNum :: Monad m => Gen m Char Source #

Generates an ASCII letter or digit: `'a'..'z', 'A'..'Z', '0'..'9'`

unicode :: Monad m => Gen m Char Source #

Generates a Unicode character, excluding invalid standalone surrogates:
`'\0'..'\1114111' (excluding '\55296'..'\57343')`

unicodeAll :: Monad m => Gen m Char Source #

Generates a Unicode character, including invalid standalone surrogates:
`'\0'..'\1114111'`

## Strings

text :: Monad m => Range Int -> Gen m Char -> Gen m Text Source #

Generates a string using `Range`

to determine the length.

utf8 :: Monad m => Range Int -> Gen m Char -> Gen m ByteString Source #

Generates a UTF-8 encoded string, using `Range`

to determine the length.

bytes :: Monad m => Range Int -> Gen m ByteString Source #

Generates a random `ByteString`

, using `Range`

to determine the
length.

## Choice

element :: Monad m => [a] -> Gen m a Source #

Randomly selects one of the elements in the list.

This generator shrinks towards the first element in the list.

*The input list must be non-empty.*

choice :: Monad m => [Gen m a] -> Gen m a Source #

Randomly selects one of the generators in the list.

This generator shrinks towards the first generator in the list.

*The input list must be non-empty.*

frequency :: Monad m => [(Int, Gen m a)] -> Gen m a Source #

Uses a weighted distribution to randomly select one of the generators in the list.

This generator shrinks towards the first generator in the list.

*The input list must be non-empty.*

recursive :: ([Gen m a] -> Gen m a) -> [Gen m a] -> [Gen m a] -> Gen m a Source #

Modifies combinators which choose from a list of generators, like `choice`

or `frequency`

, so that they can be used in recursive scenarios.

This combinator modifies its target to select one of the generators in
either the non-recursive or the recursive list. When a selection is made
from the recursive list, the `Size`

is halved. When the `Size`

gets to one
or less, selections are no longer made from the recursive list, this
ensures termination.

A good example of where this might be useful is abstract syntax trees:

data Expr = Var String | Lam String Expr | App Expr Expr -- Assuming we have a name generator genName ::`Monad`

m =>`Gen`

m String -- We can write a generator for expressions genExpr ::`Monad`

m =>`Gen`

m Expr genExpr = Gen.`recursive`

Gen.`choice`

[ -- non-recursive generators Var`<$>`

genName ] [ -- recursive generators Gen.`subtermM`

genExpr (x -> Lam`<$>`

genName`<*>`

pure x) , Gen.`subterm2`

genExpr genExpr App ]

If we wrote the above example using only `choice`

, it is likely that it
would fail to terminate. This is because for every call to `genExpr`

,
there is a 2 in 3 chance that we will recurse again.

## Conditional

## Collections

list :: Monad m => Range Int -> Gen m a -> Gen m [a] Source #

Generates a list using a `Range`

to determine the length.

seq :: Monad m => Range Int -> Gen m a -> Gen m (Seq a) Source #

Generates a seq using a `Range`

to determine the length.

nonEmpty :: Monad m => Range Int -> Gen m a -> Gen m (NonEmpty a) Source #

Generates a non-empty list using a `Range`

to determine the length.

set :: (Monad m, Ord a) => Range Int -> Gen m a -> Gen m (Set a) Source #

Generates a set using a `Range`

to determine the length.

*This may fail to generate anything if the element generator*
*cannot produce a large enough number of unique items to satify*
*the required set size.*

map :: (Monad m, Ord k) => Range Int -> Gen m (k, v) -> Gen m (Map k v) Source #

Generates a map using a `Range`

to determine the length.

*This may fail to generate anything if the keys produced by the*
*generator do not account for a large enough number of unique*
*items to satify the required map size.*

## Subterms

subterm :: Monad m => Gen m a -> (a -> a) -> Gen m a Source #

Constructs a generator from a sub-term generator.

*Shrinks to the sub-term if possible.*

subtermM :: Monad m => Gen m a -> (a -> Gen m a) -> Gen m a Source #

Constructs a generator from a sub-term generator.

*Shrinks to the sub-term if possible.*

subterm2 :: Monad m => Gen m a -> Gen m a -> (a -> a -> a) -> Gen m a Source #

Constructs a generator from two sub-term generators.

*Shrinks to one of the sub-terms if possible.*

subtermM2 :: Monad m => Gen m a -> Gen m a -> (a -> a -> Gen m a) -> Gen m a Source #

Constructs a generator from two sub-term generators.

*Shrinks to one of the sub-terms if possible.*

subterm3 :: Monad m => Gen m a -> Gen m a -> Gen m a -> (a -> a -> a -> a) -> Gen m a Source #

Constructs a generator from three sub-term generators.

*Shrinks to one of the sub-terms if possible.*

subtermM3 :: Monad m => Gen m a -> Gen m a -> Gen m a -> (a -> a -> a -> Gen m a) -> Gen m a Source #

Constructs a generator from three sub-term generators.

*Shrinks to one of the sub-terms if possible.*

## Combinations & Permutations

subsequence :: Monad m => [a] -> Gen m [a] Source #

Generates a random subsequence of a list.

shuffle :: Monad m => [a] -> Gen m [a] Source #

Generates a random permutation of a list.

This shrinks towards the order of the list being identical to the input list.

## Abstract State Machine

actions :: (Monad n, Monad m) => Range Int -> (forall v. state v) -> [Command n m state] -> Gen n [Action m state] Source #

Generates a sequence of actions from an initial model state and set of commands.

# Sampling Generators

sample :: MonadIO m => Gen m a -> m [a] Source #

Generate a random sample of data from the a generator.

print :: (MonadIO m, Show a) => Gen m a -> m () Source #

Run a generator with a random seed and print the outcome, and the first level of shrinks.

`Gen.print (Gen.``enum`

'a' 'f')

=== Outcome === 'd' === Shrinks === 'a' 'b' 'c'

printTree :: (MonadIO m, Show a) => Gen m a -> m () Source #

Run a generator with a random seed and print the resulting shrink tree.

`Gen.printTree (Gen.``enum`

'a' 'f')

'd' ├╼'a' ├╼'b' │ └╼'a' └╼'c' ├╼'a' └╼'b' └╼'a'

*This may not terminate when the tree is very large.*