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

## data-generators

### Requirements

### Repository

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

### Authors

### 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-size3 (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

#### 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 candidates)`

Generator that draws a random sample from the list of possible values

*[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-size3 (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/>.