# The genie Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

# The genie Reference Manual

This is the genie Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:52:24 2018 GMT+0.

Next: , Previous: , Up: Top   [Contents][Index]

# genie

A simple wrapper to generate portably seedable pseudo-random numbers.

## Overview

This library allows you to generate random numbers, with a portable and seedable generator. This means that a generator initialized with a particular seed will yield the same sequence of generated numbers on every Common Lisp implementation.

## Install

``````(ql:quickload :genie)
``````

## Usage

To generate a random number, you first need to create a generator object seeded with an integer:

``````(make-generator 123)
``````

Alternatively, you can leave out the seed, to have one generated for you:

``````(make-generator)
``````

The above will print a log message with the generator's seed value:

``````[INFO ] [2016-12-07 23:51:29] Random seed: 123258810179538
``````

Once you have a generator, we can use the `GEN` function to generate a number. There are a few different methods to use for generating a number.

### Generate a boolean value (T or NIL)

To generate a boolean, supply the `:BOOL` keyword to `GEN`, optionally with a probability for true:

``````(let ((generator (make-generator)))
(gen :bool generator :probability 0.9))
``````

The above will generate `T` 90% of the time, and `NIL` otherwise.

### Generate a floating-point number within a range

To generate a number that falls within a range, supply the `:RANGE` keyword to `GEN` like so:

``````(let ((generator (make-generator)))
(gen :range generator :min 0.0 :max 1.0))
``````

The above will generate a floating-point number between 0 and 10.

### Generate an integer

To generate an integer within a range, supply the `:INT` keyword to `GEN`:

``````(let ((generator (make-generator)))
(gen :int generator :min 1 :max 100))
``````

The above will generate an integer between 1 and 100, both inclusive. You may also tell it to generate an odd or an even integer within this range, by using the `:PARITYP` keyword as such:

``````(let ((generator (make-generator)))
(gen :int generator :min 1 :max 100 :parityp t))
``````

This will generate an odd integer between 1 and 100. The value of `:MIN` determines the parity of the result - a value of 2 for `:MIN` would generate an even number between 2 and 100.

### Choose a random element from a sequence

To choose a random element from a list or other sequence, supply the `:ELT` keyword to `GEN`:

``````(let ((generator (make-generator))
(some-sequence '(1 2 3)))
(gen :elt generator :sequence some-sequence))
``````

The above will choose a random element from the sequence given.

Next: , Previous: , Up: Top   [Contents][Index]

## 2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

### 2.1 genie

Maintainer

Michael Fiano <mail@michaelfiano.com>

Author

Michael Fiano <mail@michaelfiano.com>

Source Control

(:git "git@github.com:mfiano/genie.git")

Bug Tracker

MIT

Description

A simple wrapper to generate portably seedable pseudo-random numbers.

Long Description

# genie

A simple wrapper to generate portably seedable pseudo-random numbers.

## Overview

This library allows you to generate random numbers, with a portable and seedable generator. This means that a generator initialized with a particular seed will yield the same sequence of generated numbers on every Common Lisp implementation.

## Install

“‘ lisp
“‘

## Usage

To generate a random number, you first need to create a generator object seeded with an integer:

“‘ lisp
(make-generator 123)
“‘

Alternatively, you can leave out the seed, to have one generated for you:

“‘ lisp
(make-generator)
“‘

The above will print a log message with the generator’s seed value:

“‘
[INFO ] [2016-12-07 23:51:29] Random seed: 123258810179538
“‘

Once you have a generator, we can use the ‘GEN‘ function to generate a number. There are a few different methods to use for generating a number.

### Generate a boolean value (T or NIL)

To generate a boolean, supply the ‘:BOOL‘ keyword to ‘GEN‘, optionally with a probability for true:

“‘ lisp
(let ((generator (make-generator)))
(gen :bool generator :probability 0.9))
“‘

The above will generate ‘T‘ 90% of the time, and ‘NIL‘ otherwise.

### Generate a floating-point number within a range

To generate a number that falls within a range, supply the ‘:RANGE‘ keyword to ‘GEN‘ like so:

“‘ lisp
(let ((generator (make-generator)))
(gen :range generator :min 0.0 :max 1.0))
“‘

The above will generate a floating-point number between 0 and 10.

### Generate an integer

To generate an integer within a range, supply the ‘:INT‘ keyword to ‘GEN‘:

“‘ lisp
(let ((generator (make-generator)))
(gen :int generator :min 1 :max 100))
“‘

The above will generate an integer between 1 and 100, both inclusive. You may also tell it to generate an odd or an even integer within this range, by using the ‘:PARITYP‘ keyword as such:

“‘ lisp
(let ((generator (make-generator)))
(gen :int generator :min 1 :max 100 :parityp t))
“‘

This will generate an odd integer between 1 and 100. The value of ‘:MIN‘ determines the parity of the result - a value of 2 for ‘:MIN‘ would generate an even number between 2 and 100.

### Choose a random element from a sequence

To choose a random element from a list or other sequence, supply the ‘:ELT‘ keyword to ‘GEN‘:

“‘ lisp
(let ((generator (make-generator))
(some-sequence ’(1 2 3)))
(gen :elt generator :sequence some-sequence))
“‘

The above will choose a random element from the sequence given.

Version

1.0.0

Dependencies
• cl-variates
• simple-logger
Source

genie.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

## 3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

### 3.1 Lisp

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.1 genie.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/genie-20180228-git/genie.asd

Systems

genie (system)

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.2 genie/package.lisp

Parent

genie (system)

Location

package.lisp

Packages

Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.3 genie/genie.lisp

Dependency

package.lisp (file)

Parent

genie (system)

Location

genie.lisp

Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 4 Packages

Packages are listed by definition order.

Previous: , Up: Packages   [Contents][Index]

### 4.1 genie

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Previous: , Up: Definitions   [Contents][Index]

### 5.1 Exported definitions

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.1 Functions

Function: make-generator &optional SEED

Create a random number generator object, using SEED to initialize it. If SEED is not supplied, a new seed will be generated.

Package
Source

genie.lisp (file)

Function: make-seed ()

Compute a seed to be given to a generator.

Package
Source

genie.lisp (file)

Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.2 Generic functions

Generic Function: gen KIND GENERATOR &key SEQUENCE MIN MAX PARITYP PROBABILITY

Generate a random number of a certain kind.

Package
Source

genie.lisp (file)

Methods
Method: gen (KIND (eql elt)) GENERATOR &key SEQUENCE

Randomly select an element from SEQUENCE.

Method: gen (KIND (eql int)) GENERATOR &key MIN MAX PARITYP

Generate an integer between MIN and MAX (inclusive). If PARITYP is non-nil, generate an even number if MIN is even, or an odd number if MIN is odd.

Method: gen (KIND (eql range)) GENERATOR &key MIN MAX

Generate a number between MIN and MAX.

Method: gen (KIND (eql bool)) GENERATOR &key PROBABILITY

Generate a true or false value, with the given PROBABILITY for true.

Previous: , Up: Top   [Contents][Index]

## Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.1 Concepts

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.2 Functions

Index Entry Section `genie`: The genie system `genie`: The genie package `Package, genie`: The genie package `System, genie`: The genie system