You are looking at historical revision 30551 of this page. It may differ significantly from its current revision.

data-generators

Requirements

random-bsd, numbers

Repository

https://bitbucket.org/certainty/data-generators/overview

Authors

David Krentzlin

Introduction

This egg provides primitives and combinators to generate random data. That may be useful for testing or other occasions where you just need a way to quickly generate data.

Examples

(use data-generators)

;; create generator for a random fixnum
(gen-fixnum)

;; make generator that generates a number n with gen-current-fixnum-min <= n <= 10
(gen-fixnum 10)

;; make genenator that generates a number n with 1 <= n <= 10
(gen-fixnum 1 10)


;; make generator that generates a random real
(gen-real)

;; bake generator that generates a random character
(gen-char)

;; make generator that generates a random character out of the given charset
(gen-char char-set:digit)

;; make generator that generates a random character in the given range
(gen-char #\a #\z)

;; == combinators ==

;; make a generator that generates a tuple where each member is generated by the given generator
(gen-tuple-of (gen-fixnum 10) (gen-real)) 

;; make a generator that generates a list where each element is generated by the given generator
(gen-list-of (gen-fixnum))

;; make a generator that generates a vector where each element is generated by the given generator
(gen-vector-of (gen-real))

;; make generator that generates a list that has exactly 3 elements
(gen-list-of (gen-fixnum) 3)
(with-size 3 (gen-list-of (gen-fixnum)))

;; make a generator that generates a list that has 2 to 10 elements
(with-size (2 . 10) (gen-list-of gen-fixnum))

;; make a generator that generates a list of fixnums between 0 and 10 which has 2 to 10 
elements
(with-size (2 . 10) (gen-list-of (gen-fixnum 0 10)))

;; retrieve a value from the generator
(<- (gen-fixnum))

;; retrieve n values from the generator
(<-* 2 (gen-fixnum))

;; invoke the generator n times passing each value to proc
(gen-for-each 3 (lambda (n) (+ n 3)) (gen-fixnum))

API

Generators

A generator is a means to create random values that possibly adhere to some constraints. By nature a generator represents and infinite stream of random values.

[syntax] (generator ?body ...)

Creates a new generator. You can use this to define your own generators.

Example:

(define (my-gen start)
 (generator (+ start 42))

(<- (my-gen 10)) ;=> 52

Extracting data from generators

[procedure] (<- gen)

Invokes the generator gen once and returns that value.

[procedure] (<-* n gen)

Invokes the generator n-times and returns a list of n values.

[procedure] (gen-for-each n proc gen)

Invokes the generator gen n times and applies proc to each value in turn.

Parameters

[parameter] gen-current-fixnum-min

The smallest fixnum that should be generated.

[parameter] gen-current-fixnum-max

The biggest fixnum that should be generated

Primitives

[procedure] (gen-constant value)

Generator that always returns value.

[procedure] (gen-fixnum)

Generator for a fixnum between gen-current-fixnum-min and gen-current-fixnum-max.

[procedure] (gen-fixnum upper-bound)

Generator for a fixnum between gen-current-fixnum-min and upper-bound

[procedure] (gen-fixnum lower-bound upper-bound)

Generator for a fixnum between lower-bound and upper-bound

[procedure] (gen-int8)

Generator for a fixnum between -127 and 127.

[procedure] (gen-uint8)

Generator for a fixnum between 0 and 255.

[procedure] (gen-int16)

Generator for a fixnum between -32767 and 3276.

[procedure] (gen-uint16)

Generator for a fixnum between 0 and 65535.

[procedure] (gen-int32)

Generator for a fixnum between -2147483647 and 2147483647.

[procedure] (gen-uint32)

Generator for a fixnum between 0 and 4294967295.

[procedure] (gen-int64)

Generator for a fixnum between -9223372036854775807 and 9223372036854775807.

[procedure] (gen-uint8)

Generator for a fixnum between 0 and 18446744073709551615.

[procedure] (gen-real)

Generator for a real number between 0.0 and 1.0.

[procedure] (gen-real upper-bound)

Generator for a real number between 0.0 and upper-bound.

[procedure] (gen-real lower-bound upper-bound)

Generator for a real number between lower-bound and upper-bound.

[procedure] (gen-char)

Generator for a character from char-set:graphic.

[procedure] (gen-char charset)

Generator for a character from the char-set charset

[procedure] (gen-char lower-bound upper-bound)

Generator for a character from the char-set build from lower-bound to upper-bound. lower-bound must be <= upper-bound as compared with char<=?.

Example:

(gen-char #\a #\z)
[procedure] (gen-bool)

Generator for a random boolean value

[procedure] (gen-sample candidates)

Generator that draws a random sample from the list of candidates.

Combinators

[parameter] (gen-current-default-size)

A generator that must return a fixnum. It's used to determine the size for generators that can have a length. This defaults to (gen-uint8).

[procedure] (gen-pair-of car-gen cdr-gen)

Generator for a pair where the car is generated with car-gen and the cdr is generated with with cdr-gen.

[procedure] (gen-sample-of . gens)

Generator that draws a random generator from the list of possible generators and invokes it once.

[procedure] (gen-tuple-of . gens)

Generator for a tuple where each element is generated by the given generators.

[procedure] (gen-string-of char-gen size #!optional (size (gen-current-default-size)))

Generator for a string where each character is generated from char-gen. The size parameter specifies the size of the strings that are generated. It is expected to be a thunk that returns the size as a fixnum. See with-size for a more convenient way to adjust this.

[procedure] (gen-list-of gen #!optional (size (gen-current-default-size)))

Generator for a list where each element is generated with the given generator gen. The size parameter specifies the size of the list that is generated. It is expected to be a thunk that returns the size as a fixnum. See with-size for a more convenient way to adjust this.

[procedure] (gen-alist-of car-gen cdr-gen #!optional (size (gen-current-default-size)))

Generator for an alist where each car is generated with car-gen and each cdr is generated with with cdr-gen. The size parameter specifies the size of the list that is generated. It is expected to be a thunk that returns the size as a fixnum. See with-size for a more convenient way to adjust this.

[procedure] (gen-vector-of gen #!optional (size (gen-current-default-size)))

Generator for a vector where each element is generated with the given generator gen. The size parameter specifies the size of the vector that is generated. It is expected to be a thunk that returns the size as a fixnum. See with-size for a more convenient way to adjust this.

[procedure] (gen-hash-table-of key-gen value-gen #!optional (size (gen-current-default-size)))

Generator for a hash-table where each key is generated by key-gen and each value is generated by value-gen. The size parameter specifies the size of the hash-table that is generated. It is expected to be a thunk that returns the size as a fixnum. See with-size for a more convenient way to adjust this.

[procedure] (gen-record ctor . slot-gens)

Generator for a record that is created with the given ctor where each slot is generated with the given slot-gens.

[syntax] (with-size size-spec ...)

Use this to constrain the size of the data generated by the combinators. size-spec is either a fixnum or a pair of fixnums. If it is a fixnum all data will be generated with the size equal to that fixnum. If it is a pair, all data will be generated with a size that lies between the car of the pair and the cdr of the pair.

Defining your own generators

To define your own generators you can use the generator-syntax.

(define (gen-foo) (generator "foo"))

(with-size 3 (gen-list-of (gen-foo))) ;=> ("foo" "foo" "foo")

See also

For a very exhaustive and systematic approach to all kinds of random sources see: srfi-27

License

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>.