# The genie Reference Manual

## Table of Contents

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.3 "Robert April" on Tue Feb 20 08:44:31 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.

## License

Copyright © 2016 Michael Fiano michael.fiano@gmail.com.

Licensed under the MIT License.

A copy of the license is available here.

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 <michael.fiano@gmail.com>

Author

Michael Fiano <michael.fiano@gmail.com>

Home Page
Source Control

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

Bug Tracker
License

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
(ql:quickload :genie)
“‘

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

## License

Copyright © 2016 Michael Fiano <michael.fiano@gmail.com>.

Licensed under the MIT License.

A copy of the license is available [here](LICENSE).

Version

1.0.0

Dependencies
• alexandria
• 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/quickbuilder/quicklisp/dists/quicklisp/software/genie-20171019-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
• alexandria.0.dev
• 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.
If INCLUSIVEP is non-nil, the range includes 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

Jump to: F   G   L
Jump to: F   G   L

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

### A.2 Functions

Jump to: F   G   M
Jump to: F   G   M

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

### A.3 Variables

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

### A.4 Data types

Jump to: G   P   S
Index Entry Section `genie`: The genie system `genie`: The genie package `Package, genie`: The genie package `System, genie`: The genie system
Jump to: G   P   S