You are looking at historical revision 30438 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-size 3 (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)))

Authors

David Krentzlin

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.

Defining your own generators

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

(define gen-foo (constantly "foo"))

(with-size 3 (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/>.