The generators Reference Manual

Table of Contents

The generators Reference Manual

This is the generators Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 16:11:05 2021 GMT+0.

1 Introduction

Generators

Generators is a library that provides python style generators in common lisp, by using cl-cont delimited continuations

This library is more of an interesting toy, though as far as I know it does work. I dont think I have ever used this in application code, though I think that with care, it could be.

Requirements

• CL-CONT provides the continuations that make this work
• Alexandria
• Iterate

Gotchas

• Continuations don't play nicely with exception/signal handling, unwind-protect, throw/catch, or dynamic variables. Consider using cl-cont:without-call/cc, if you need this functionality in a generator. (see-also %mv-gen for an example)

• because cl-cont uses a code walker, it might get confused when interacting other code walkers (eg: iterate). Inside of generators, you might have better luck with less code walking

API

make-generator

Creates a new generator, the body of which can yield values to the calling scope

yield

yield - returns the next value from the generator to the caller

yielding

yielding - yields every value in the passed in generators

Iterate clauses

(for v in-generator gen)

iterates through the values produced by a generator

(FOR node a-node-of-lisp-tree tree)

iterates through all the nodes of a lisp tree eg: '(1 (2 3) 4) generates (1 (2 3) 2 3 4)

(FOR node a-leaf-of-lisp-tree tree)

iterates through all the leaves of a lisp tree eg: '(1 (2 3) 4) generates (1 2 3 4)

Example:

(defun generate-lisp-tree-nodes (trees &optional leaves-only?)
  "Do a depth first traversal of some set of trees yielding every node/leaf "
  (make-generator ()
    (iter (for n in (alexandria:ensure-list trees))
      (etypecase n
        (atom (yield n))
        (list
         (unless leaves-only? (yield n))
         (yielding (generate-lisp-tree-nodes n)))))))

Authors

• Acceleration.net
• Russ Tyndall
• Nathan Bird
• Ryan Davis

;; Copyright (c) 2013 Russ Tyndall , Acceleration.net http://www.acceleration.net
;; All rights reserved.
;;
;; Redistribution and use in source and binary forms, with or without
;; modification, are permitted provided that the following conditions are
;; met:
;;
;;  - Redistributions of source code must retain the above copyright
;;    notice, this list of conditions and the following disclaimer.
;;
;;  - Redistributions in binary form must reproduce the above copyright
;;    notice, this list of conditions and the following disclaimer in the
;;    documentation and/or other materials provided with the distribution.
;;
;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
;; A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
;; LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
;; DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
;; THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
;; (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
;; OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2 Systems

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

2.1 generators

Author

<programmers@acceleration.net>

License

BSD

Description

A common lisp package providing python style generators based on delimited continuations

Version

0.1

Dependencies

• cl-cont
• alexandria
• iterate

Source

generators.asd (file)

Components

• packages.lisp (file)
• generators.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 generators.asd

Location

generators.asd

Systems

generators (system)

Packages

generators.system

3.1.2 generators/packages.lisp

Parent

generators (system)

Location

packages.lisp

Packages

generators

3.1.3 generators/generators.lisp

Parent

generators (system)

Location

generators.lisp

Exported Definitions

• force (generic function)
• force (method)
• generate-lisp-tree-nodes (function)
• generator (method)
• (setf generator) (method)
• generator (class)
• make-generator (macro)
• next (generic function)
• next (method)
• reset (generic function)
• reset (method)
• stop-iteration (condition)

Internal Definitions

• %mv-gen (function)
• %stop-iteration (function)
• clause-for-a-leaf-of-lisp-tree-3 (macro)
• clause-for-a-node-of-lisp-tree-2 (macro)
• clause-for-in-generator-1 (macro)
• continuation (method)
• (setf continuation) (method)
• final-exception (method)
• (setf final-exception) (method)
• final-value (method)
• (setf final-value) (method)
• finished? (method)
• (setf finished?) (method)
• handled? (method)
• (setf handled?) (method)
• name (method)
• (setf name) (method)
• only-one? (function)
• original-continuation (method)
• (setf original-continuation) (method)
• use-final-value? (method)
• (setf use-final-value?) (method)

4 Packages

Packages are listed by definition order.

4.1 generators.system

Source

generators.asd

Use List

• asdf/interface
• common-lisp

4.2 generators

Source

packages.lisp (file)

Use List

• iterate
• common-lisp

Exported Definitions

• force (generic function)
• force (method)
• generate-lisp-tree-nodes (function)
• generator (generic function)
• generator (method)
• (setf generator) (method)
• (setf generator) (generic function)
• generator (class)
• make-generator (macro)
• next (generic function)
• next (method)
• reset (generic function)
• reset (method)
• stop-iteration (condition)

Internal Definitions

• %mv-gen (function)
• %stop-iteration (function)
• clause-for-a-leaf-of-lisp-tree-3 (macro)
• clause-for-a-node-of-lisp-tree-2 (macro)
• clause-for-in-generator-1 (macro)
• continuation (generic function)
• continuation (method)
• (setf continuation) (method)
• (setf continuation) (generic function)
• final-exception (generic function)
• final-exception (method)
• (setf final-exception) (method)
• (setf final-exception) (generic function)
• final-value (generic function)
• final-value (method)
• (setf final-value) (method)
• (setf final-value) (generic function)
• finished? (generic function)
• finished? (method)
• (setf finished?) (method)
• (setf finished?) (generic function)
• handled? (generic function)
• handled? (method)
• (setf handled?) (method)
• (setf handled?) (generic function)
• name (generic function)
• name (method)
• (setf name) (method)
• (setf name) (generic function)
• only-one? (function)
• original-continuation (generic function)
• original-continuation (method)
• (setf original-continuation) (method)
• (setf original-continuation) (generic function)
• use-final-value? (generic function)
• use-final-value? (method)
• (setf use-final-value?) (method)
• (setf use-final-value?) (generic function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: make-generator (&key FINAL-VALUE FINAL-EXCEPTION NAME) &body BODY

returns a function that when called yields the next values. Inside of body, you can yield any number of values that you wish by calling (yield &rest args) which is scoped to the body

Package

generators

Source

generators.lisp (file)

5.1.2 Functions

Function: generate-lisp-tree-nodes TREES &optional LEAVES-ONLY?

Do a depth first traversal of some set of trees yielding every node

Package

generators

Source

generators.lisp (file)

5.1.3 Generic functions

Generic Function: force GENERATOR

Forces the generator to produce a list of its output

Package

generators

Source

generators.lisp (file)

Methods

Method: force (G generator)

Generic Function: generator CONDITION

Generic Function: (setf generator) NEW-VALUE CONDITION

Package

generators

Methods

Method: generator (CONDITION stop-iteration)

Method: (setf generator) NEW-VALUE (CONDITION stop-iteration)

Source

generators.lisp (file)

Generic Function: next GENERATOR &rest ARGS

Returns the next value of this generator

Package

generators

Source

generators.lisp (file)

Methods

Method: next (GEN generator) &rest ARGS

Generic Function: reset GENERATOR

Restarts the generator from its original continuation

Package

generators

Source

generators.lisp (file)

Methods

Method: reset (GEN generator)

5.1.4 Conditions

Condition: stop-iteration ()

Package

generators

Source

generators.lisp (file)

Direct superclasses

error (condition)

Direct methods

• handled? (method)
• handled? (method)
• generator (method)
• generator (method)

Direct slots

Slot: generator

Initargs

:generator

Initform

(quote nil)

Readers

generator (generic function)

Writers

(setf generator) (generic function)

Slot: handled?

Initargs

:handled?

Initform

(quote nil)

Readers

handled? (generic function)

Writers

(setf handled?) (generic function)

5.1.5 Classes

Class: generator ()

A class that stores all the needed structure for a generator

Package

generators

Source

generators.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• force (method)
• reset (method)
• next (method)
• name (method)
• name (method)
• original-continuation (method)
• original-continuation (method)
• finished? (method)
• finished? (method)
• final-exception (method)
• final-exception (method)
• final-value (method)
• final-value (method)
• use-final-value? (method)
• use-final-value? (method)
• continuation (method)
• continuation (method)

Direct slots

Slot: continuation

The current continuation of the generator

Initargs

:continuation

Readers

continuation (generic function)

Writers

(setf continuation) (generic function)

Slot: use-final-value?

Should this generator, generate a sigil value when complete
if nil will raise the final-exception (defaults ’stop-iteration)

Initargs

:use-final-value?

Readers

use-final-value? (generic function)

Writers

(setf use-final-value?) (generic function)

Slot: final-value

The value to generate if we are using a final-value instead of raising exceptions

Initargs

:final-value

Readers

final-value (generic function)

Writers

(setf final-value) (generic function)

Slot: final-exception

An exception to raise when we are done iterating (if not using final-value)

Initargs

:final-exception

Initform

(quote generators:stop-iteration)

Readers

final-exception (generic function)

Writers

(setf final-exception) (generic function)

Slot: finished?

Has this generator generated all values?

Initargs

:finished?

Readers

finished? (generic function)

Writers

(setf finished?) (generic function)

Slot: original-continuation

The starting point of this generator

Initargs

:original-continuation

Readers

original-continuation (generic function)

Writers

(setf original-continuation) (generic function)

Slot: name

Initargs

:name

Readers

name (generic function)

Writers

(setf name) (generic function)

5.2 Internal definitions

5.2.1 Macros

Macro: clause-for-a-leaf-of-lisp-tree-3 &key (FOR NODE) (A-LEAF-OF-LISP-TREE TREE) GENERATE

Package

generators

Source

generators.lisp (file)

Macro: clause-for-a-node-of-lisp-tree-2 &key (FOR NODE) (A-NODE-OF-LISP-TREE TREE) GENERATE

Package

generators

Source

generators.lisp (file)

Macro: clause-for-in-generator-1 &key (FOR NODE) (IN-GENERATOR GEN) GENERATE

Package

generators

Source

generators.lisp (file)

5.2.2 Functions

Function: %mv-gen G

Generates a value from the generator, if the generator throws stop iteration returns (values nil T),
turns off call/cc so that this works

Package

generators

Source

generators.lisp (file)

Function: %stop-iteration GENERATOR

Package

generators

Source

generators.lisp (file)

Function: only-one? LIST

Package

generators

Source

generators.lisp (file)

5.2.3 Generic functions

Generic Function: continuation OBJECT

Generic Function: (setf continuation) NEW-VALUE OBJECT

Package

generators

Methods

Method: continuation (GENERATOR generator)

Method: (setf continuation) NEW-VALUE (GENERATOR generator)

The current continuation of the generator

Source

generators.lisp (file)

Generic Function: final-exception OBJECT

Generic Function: (setf final-exception) NEW-VALUE OBJECT

Package

generators

Methods

Method: final-exception (GENERATOR generator)

Method: (setf final-exception) NEW-VALUE (GENERATOR generator)

An exception to raise when we are done iterating (if not using final-value)

Source

generators.lisp (file)

Generic Function: final-value OBJECT

Generic Function: (setf final-value) NEW-VALUE OBJECT

Package

generators

Methods

Method: final-value (GENERATOR generator)

Method: (setf final-value) NEW-VALUE (GENERATOR generator)

The value to generate if we are using a final-value instead of raising exceptions

Source

generators.lisp (file)

Generic Function: finished? OBJECT

Generic Function: (setf finished?) NEW-VALUE OBJECT

Package

generators

Methods

Method: finished? (GENERATOR generator)

Method: (setf finished?) NEW-VALUE (GENERATOR generator)

Has this generator generated all values?

Source

generators.lisp (file)

Generic Function: handled? CONDITION

Generic Function: (setf handled?) NEW-VALUE CONDITION

Package

generators

Methods

Method: handled? (CONDITION stop-iteration)

Method: (setf handled?) NEW-VALUE (CONDITION stop-iteration)

Source

generators.lisp (file)

Generic Function: name OBJECT

Generic Function: (setf name) NEW-VALUE OBJECT

Package

generators

Methods

Method: name (GENERATOR generator)

automatically generated reader method

Source

generators.lisp (file)

Method: (setf name) NEW-VALUE (GENERATOR generator)

automatically generated writer method

Source

generators.lisp (file)

Generic Function: original-continuation OBJECT

Generic Function: (setf original-continuation) NEW-VALUE OBJECT

Package

generators

Methods

Method: original-continuation (GENERATOR generator)

Method: (setf original-continuation) NEW-VALUE (GENERATOR generator)

The starting point of this generator

Source

generators.lisp (file)

Generic Function: use-final-value? OBJECT

Generic Function: (setf use-final-value?) NEW-VALUE OBJECT

Package

generators

Methods

Method: use-final-value? (GENERATOR generator)

Method: (setf use-final-value?) NEW-VALUE (GENERATOR generator)

Should this generator, generate a sigil value when complete
if nil will raise the final-exception (defaults ’stop-iteration)

Source

generators.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types