You are looking at historical revision 30552 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 json data-generators)

;; generate a json document
(define (gen-json-doc #!optional (nesting 5))
  (generator
   (with-output-to-string
     (lambda ()
       (json-write (<- (gen-json-value nesting)))))))

(define (gen-json-value nesting)
  (generator
   (if (positive? nesting)
       (<- (gen-sample-of (gen-json-string) (gen-json-array nesting) (gen-json-null) (gen-json-number) (gen-json-object nesting)))
       (<- (gen-sample-of (gen-json-string) (gen-json-null) (gen-json-number))))))

(define (gen-json-string)
  (with-size (0 . 20)
    (gen-string-of (gen-char char-set:letter+digit))))

(define (gen-json-object nesting)
  (with-size (0 . 5)
    (gen-vector-of (gen-pair-of (gen-json-string) (gen-json-value (sub1 nesting))))))

(define (gen-json-null)
  (gen-constant (void)))

(define (gen-json-number)
  (gen-sample-of (gen-fixnum) (gen-real)))

(define (gen-json-array nesting)
  (with-size (0 . 5)
    (gen-list-of (gen-json-value (sub1 nesting)))))


(gen-for-each 10 print (gen-json-doc))

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