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

## data-generators

### 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.

### Repository

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

### Examples

(use data-generators) ;; generate a random number (gen-fixnum) ;; generate a number n with 1 <= n <= 10 (between gen-fixnum 1 10) ;; generate a number n with n <= 10 (at-most gen-fixnum 10) ;; generate a number n with n >= 10 (at-least gen-fixnum 10) ;; generate a random real (gen-real) ;; generate a random character (gen-char) ;; generate a random character out of the given charset (gen-char char-set:digit) ;; generate a random character in the given range (between gen-char #\a #\z) ;; == combinators == ;; generate a tuple where each member is generated by the given generator (gen-tuple-of gen-fixnum gen-real) ;; generate a list where each element is generated by the given generator (gen-list-of gen-fixnum) ;; generate a vector where each element is generated by the given generator (gen-vector-of gen-real) ;; generate a list that has exactly 3 elements (with-size3 (gen-list-of gen-fixnum)) ;; generate a list that has 2 to 10 elements (with-size(2 . 10) (gen-list-of gen-fixnum)) ;; generate a list of fixnums between 0 and 10 which has 2 to 10 elements (with-size(2 . 10) (gen-list-of (cut between gen-fixnum 0 10))) ;; create a sequence for a given generator (definelist-seq (gen->sequence 3 (with-size5 (gen-list-of (cut between gen-fixnum 0 10))))) ;; run a sequence (run-sequence list-seq (lambda(value) (print value)))

### Authors

### API

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

Generates a fixnum between **gen-current-fixnum-min** and **gen-current-fixnum-max**.

*[procedure]*

`(gen-int8)`

Generates a fixnum between -127 and 127.

*[procedure]*

`(gen-uint8)`

Generates a fixnum between 0 and 255.

*[procedure]*

`(gen-int16)`

Generates a fixnum between -32767 and 3276.

*[procedure]*

`(gen-uint16)`

Generates a fixnum between 0 and 65535.

*[procedure]*

`(gen-int32)`

Generates a fixnum between -2147483647 and 2147483647.

*[procedure]*

`(gen-uint32)`

Generates a fixnum between 0 and 4294967295.

*[procedure]*

`(gen-int64)`

Generates a fixnum between -9223372036854775807 and 9223372036854775807.

*[procedure]*

`(gen-uint8)`

Generates a fixnum between 0 and 18446744073709551615.

*[procedure]*

`(gen-real)`

Generates a real number between 0.0 and 1.0.

*[procedure]*

`(gen-char #!optional (charset-or-sizer char-set:graphic))`

Generates a character from a given charset. The charset defaults to **char-set:graphic**.

*[procedure]*

`(gen-bool)`

Generates a random boolean value.

#### Range operators

*[procedure]*

`(between gen lower-bound upper-bound)`

Invokes the the generator **gen** but restricts the possible range of values to those delimited by (inlusive) **lower-bound** and **upper-bound**. There is a special-case for **gen-char** in which case you can pass characters as the boundaries.

*[procedure]*

`(at-most gen upper-bound)`

Invokes the the generator **gen** but restricts the possible range of values to those delimited by (inlusive) **gen-current-fixnum-min** and **upper-bound**.

*[procedure]*

`(at-least gen lower-bound)`

Invokes the the generator **gen** but restricts the possible range of values to those delimited by (inlusive) **lower-bound** and **current-fixnum-max**.

#### Combinators

*[procedure]*

`(gen-pair-of car-gen cdr-gen)`

Generates a pair where the car is generated with **car-gen** and the cdr is generated with with **cdr-gen**.

*[procedure]*

`(gen-sample-of list-of-gen)`

Draws a random sample from the list of generators

*[procedure]*

`(gen-tuple-of . gens)`

Generates a tuple where each element is generated by the given generator.

*[procedure]*

`(gen-string-of #!optional (charset char-set:graphic) (size (gen-current-default-size)))`

Generates a string where each character is generated for the given **charset**. 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)))`

Generates 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)))`

Generates 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)))`

Generates 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)))`

Generates a list 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.

*[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.

*[syntax]*

`(gen->sequence amount body0 ...)`

Creates a sequence for the given generator expression. A sequence is a procedure that accepts another procedure as its argument. It runs the generator expression **amount** times and passes the result of the expression to its argmuent.

(definefixnum-seq 10 (gen-fixnum)) (fixnum-seq (lambda(value) (print value)))

*[procedure]*

`(run-sequence seq proc)`

Runs the sequence **seq** by applying **proc**. Currently (run-sequence seq proc) is equivalent to (seq proc).

#### Defining your own generators

A simple generator is really just a procedure of zero arguments that returns the generated value upon invocation.

(definegen-foo (constantly "foo")) (with-size3 (gen-list-of gen-foo)) ;=> ("foo" "foo" "foo")

It you want your generators to be usable with range-constraints you have

to adjust them to take an additional argument

(define(gen-value-of-range #!optional (sizer (make-sizer 1 1))) (cons (sizer/lb sizer) (sizer/ub sizer))) (between gen-value-of-range 1 10) ;=> (1 . 10) (at-most gen-value-of-range 10) ;=> (-65536 . 10) (at-least gen-value-of-range 1) ;=> (1 . 65536)

### 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/>.