The snakes Reference Manual

This is the snakes Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 19:36:17 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 snakes

Python style generators for Common Lisp.

Author

Ben McGunigle <>

License

Apache 2.0

Dependencies
  • cl-cont (system).
  • closer-mop (system).
  • fiveam (system).
  • iterate (system).
  • cl-utilities (system).
  • alexandria (system).
Source

snakes.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 snakes/snakes.asd

Source

snakes.asd.

Parent Component

snakes (system).

ASDF Systems

snakes.


3.1.2 snakes/package.lisp

Source

snakes.asd.

Parent Component

snakes (system).

Packages

snakes.


3.1.3 snakes/util.lisp

Dependency

package.lisp (file).

Source

snakes.asd.

Parent Component

snakes (system).

Internals

3.1.4 snakes/snakes.lisp

Dependency

util.lisp (file).

Source

snakes.asd.

Parent Component

snakes (system).

Public Interface
Internals

3.1.5 snakes/do-generators.lisp

Dependency

snakes.lisp (file).

Source

snakes.asd.

Parent Component

snakes (system).

Public Interface
Internals

3.1.6 snakes/itertools.lisp

Dependency

do-generators.lisp (file).

Source

snakes.asd.

Parent Component

snakes (system).

Public Interface
Internals

append! (function).


3.1.7 snakes/iterate.lisp

Dependency

itertools.lisp (file).

Source

snakes.asd.

Parent Component

snakes (system).

Internals

clause-for-in-generator-1 (macro).


4 Packages

Packages are listed by definition order.


4.1 snakes

Source

package.lisp.

Use List
  • cl-cont.
  • common-lisp.
  • iterate.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *snakes-multi-mode*
Package

snakes.

Source

snakes.lisp.


5.1.2 Macros

Macro: defgenerator (name arguments &body body)
Package

snakes.

Source

snakes.lisp.

Macro: do-generator ((var &rest vars-and-generator) &body body)

Steps through the specified generator, binding the value it returns to var, then executing the body for each step. If multiple variables are specified and the generator returns multiple values, the extra values will be bound to the extra variables.

Package

snakes.

Source

snakes.lisp.

Macro: do-generator-value-list ((var generator) &body body)

Like do-generator, except all values emitted by the generator are placed in a list under the user defined variable.

Package

snakes.

Source

snakes.lisp.

Macro: do-generators (genspecs &body body)

Simultaneously iterate through multiple generators at once. By default
do-generators terminates when the shortest generator ends, but individual
generators can be padded out with the :fill-value keyword. Do-generators can
also iterate over lists in parallel with generators. To use lists, start the genspec with the :list keyword. Eg: (do-generators ((a (repeat 2))
(:list b ’(4 5 6))
(c (list->generator ’(8 9)) :fill-value 30))
(print (* a (+ b c))))
24
28
72
NIL

Package

snakes.

Source

do-generators.lisp.

Macro: gen-lambda (params &body rest)

Version of lambda that wraps the anonymous function in an instance of the basic-generator class. This allows the lambda to be identified as a generator by its type. Basic-generator objects are derived from funcallable-standard-class, therefore they can be called as functions.

Package

snakes.

Source

snakes.lisp.

Macro: gen-lambda-with-sticky-stop (&rest rest)
Package

snakes.

Source

snakes.lisp.

Macro: with-yield (&body body)
Package

snakes.

Source

snakes.lisp.

Macro: yield-all (generator)

Walks through generator, re-yielding all of the items in it. Only meant for use inside of a defgenerator or with-yield block.

Package

snakes.

Source

snakes.lisp.


5.1.3 Ordinary functions

Function: chain (&rest generators)

Chains a number of generators together head to tail. Eg:
(chain (list->generator ’(1 2 3) (list->generator ’(6 7))) -> 1 2 3 6 7

Package

snakes.

Source

itertools.lisp.

Function: combinations (list r)

Emits every possible combination of the items in list in sets of size r. Eg: (combinations ’(a b c d) 2) -(values)-> (a b) (a c) (a d) (b c) (b d) (c d)

Package

snakes.

Source

itertools.lisp.

Function: combinations-with-replacement (list r)

Emits every possible combination, including repetitions, of the items in list in sets of size r. Eg: (combinations-with-replacement ’(a b c) 2) -(values)-> (a a) (a b) (a c)
(b b) (b c) (c c)

Package

snakes.

Source

itertools.lisp.

Function: compress (data selectors)

Moves through the data and selectors generators in parallel, only yielding elements of data that are paired with a value from selectors that evaluates to true. Eg: (compress (list->generator ’(a b c d e f))
(list->generator ’(t nil t nil t t))) -> a c e f

Package

snakes.

Source

itertools.lisp.

Function: consume (n gen &key fail-if-short)

Takes N items from generator gen, returning nothing. If the generator contains less than n items, consume will empty the generator silently if fail-if-short is set to nil, otherwise it will raise an error.

Package

snakes.

Source

snakes.lisp.

Function: cycle (list-or-gen)

Repeatedly cycles through a list or generator, yielding its elements indefinitely. Eg: (cycle ’(a b c d)) -> a b c d a b c d a b ...
Note that this tool may consume considerable storage if the source iterable is long.

Package

snakes.

Source

itertools.lisp.

Function: dropwhile (predicate generator)

Goes through generator, dropping the items until the predicate fails, then emits the rest of the source generator’s items. Eg: (dropwhile (lambda (x) (< x 5))
(list->generator ’(1 4 6 4 1))) -> 6 4 1

Package

snakes.

Source

itertools.lisp.

Function: enumerate (generator)
Package

snakes.

Source

itertools.lisp.

Function: file->generator (path)

Given a path, will attempt to open the file specified and emit it line by line. Note: it will not close the file until the generator is exhausted.

Package

snakes.

Source

snakes.lisp.

Function: function->generator (source-func predicate)

Returns a generator that repeatedly calls source-func, tests the result against the predicate function, terminates when the predicate tests false, otherwise yielding the result

Package

snakes.

Source

snakes.lisp.

Function: generator->list (gen)
Package

snakes.

Source

snakes.lisp.

Function: groupby (generator &key key comp)

Groups the items from generator by the results of the key func. Each item emitted by groupby will be a pair: the key value, followed by a list of items that produced the key value when passed to the key function. Note: groupby does NOT sort the source generator. In other words it will only group matching items that are adjacent. To get SQL style GROUP BY functionality, sort the source generator before passing it to groupby. Eg: (groupby (list->generator ’(A A A A B B B C C))) ->
(A (A A A A)) (B (B B B)) ...

Package

snakes.

Source

itertools.lisp.

Function: icount (n &optional step)

Make a generator that returns evenly spaced values starting with n. Step can be fractional. Eg: (counter 10) -> 10 11 12 13 14 ...
(counter 2.5 0.5) -> 2.5 3.0 3.5 ...

Package

snakes.

Source

itertools.lisp.

Function: ifilter (predicate generator)

Emits only those items in generator that are true by predicate. The generator equivalent of remove-if-not

Package

snakes.

Source

itertools.lisp.

Function: ifilter-false (predicate generator)

Emits only those items in generator that are false by predicate. The generator equivalent of remove-if

Package

snakes.

Source

itertools.lisp.

Function: imap (function &rest generators)

The generator equivalent of the mapcar function. Applies function to the values of the supplied generators, emitting the result. Eg:
(imap #’* (list->generator ’(2 3 4)) (list->generator ’(4 5 6))) -> 8 15 24

Package

snakes.

Source

itertools.lisp.

Function: islice (generator stop-or-start &optional stop step)

Emits a subrange of generator. If only stop-or-start is set, islice will emit up to it and stop. If both stop-or-start and stop are set, islice will emit the stretch between stop and start. If step is set, then islice will emit every step-th item between start and stop. If stop is set to nil, then islice will continue through the source generator until it terminates. Eg: (islice (list->generator ’(a b c d e f g)) 2) -> A B
(islice (list->generator ’(a b c d e f g)) 2 4) -> C D
(islice (list->generator ’(a b c d e f g)) 2 nil) -> C D E F G
(islice (list->generator ’(a b c d e f g)) 0 nil 2) -> A C E G

Package

snakes.

Source

itertools.lisp.

Function: izip (&rest generators)

Steps through multiple generators in parallel, emitting each of their items as values. Stops with the end of the shortest source generator.

Package

snakes.

Source

itertools.lisp.

Function: izip-longest (&rest generators-and-fill-value)

Steps through multiple generators in parallel, emitting each of their items as values. Keeps going until the end of the longest source generator, padding the rest out with the value specified by :fill-value

Package

snakes.

Source

itertools.lisp.

Function: list->generator (source)
Package

snakes.

Source

snakes.lisp.

Function: list->generator-with-tail (source)
Package

snakes.

Source

snakes.lisp.

Function: mapc-generator (function generator)
Package

snakes.

Source

snakes.lisp.

Function: mapcar-generator (function generator)
Package

snakes.

Source

snakes.lisp.

Function: multi-gen (&rest genspecs)
Package

snakes.

Source

do-generators.lisp.

Function: permutations (list &optional r)

Emits every possible permutation of the items in list in a set of size r. If r is not specified, the size of list is used. Eg: (permutations ’(a b c d) 2) -(values)-> (a b) (a c) (a d) (b a) (b c) (b d)
(c a) (c b) (c d) (d a) (d b) (d c)

Package

snakes.

Source

itertools.lisp.

Function: product (&rest lists)

Iterates through each of the supplied lists with nested dolists, yielding an element from each for every iteration of the innermost loop. The yielded values cycle in an odometer-like fashion, with the first value changing seldom and the last changing on every yield. Eg: (product ’(a b c d) ’(x y)) -(values)-> (a x) (a y) (b x) (b y) (c x) (c y)...

Package

snakes.

Source

itertools.lisp.

Function: reduce-generator (function generator &key initial-value)

Reduce items from generator using a binary operation
FUNCTION. Reduction is left-associative. Optional INITIAL-VALUE is
logically placed before items in the generator. Eg:
(foldl #’+ (list->generator ’(1 2 3 4))) -> 10

For consistency with CL:REDUCE do the following if the generator has insufficient items:

* If GENERATOR has no values, return result of FUNCTION called without arguments.
* If GENERATOR has exactly one item, return that item.

Package

snakes.

Source

itertools.lisp.

Function: sequence->generator (seq)
Package

snakes.

Source

snakes.lisp.

Function: starmap (function generator)

Sequentially applies the function to the output of the generator. Like imap, but assumes that the contents of the generator are already merged. Eg: (starmap #’expt (list->generator ’((2 5) (3 2) (10 3)))) -> 32 9 1000

Package

snakes.

Source

itertools.lisp.

Function: take (n gen &key fail-if-short)

Takes n items from generator gen, returning them as a list. If the generator contains less than n items, take will return what is available if fail-if-short is set to nil, otherwise it will raise an error.

Package

snakes.

Source

snakes.lisp.

Function: take-as-generator (n generator &key fail-if-short)

This function has the same meaning as TAKE but returns a generator
instead of a list. Eg:

(generator->list (take-as-generator 10 (list->generator ’(1 2 3)))) -> Signals a condition (generator->list (take-as-generator 10 (list->generator ’(1 2 3)) :fail-if-short nil)) -> (1 2 3) (generator->list (take-as-generator 3 (repeat 1))) -> (1 1 1)

Package

snakes.

Source

itertools.lisp.

Function: takewhile (predicate generator)

Emits items from generator until predicate fails. Eg: (takewhile (lambda (x) (< x 5)) (list->generator ’(1 4 6 4 1))) -> 1 4

Package

snakes.

Source

itertools.lisp.

Function: tee (generator &optional n)

Creates independent copies of generator, returned as values. If the child generators are consumed at different times, tee will store all of the items from the least consumed child generator through to the most. It can, if used incautiously, require considerable memory.

Note also that this implementation of tee does not create independent copies of the parent items. Modifying items from a child generator and tampering with the parent generator have undefined consequences.

Package

snakes.

Source

itertools.lisp.

Function: value-func->generator (source)

Converts to a generator that sort of function which uses the second value as
a completion signal. Will keep emitting the first return value of the source function until the second value is a nil.

Package

snakes.

Source

snakes.lisp.


5.1.4 Generic functions

Generic Function: generatorp (obj)
Package

snakes.

Source

snakes.lisp.

Methods
Method: generatorp ((obj basic-generator))
Method: generatorp (obj)

5.1.5 Standalone methods

Method: initialize-instance :after ((g basic-generator) &key function)
Source

snakes.lisp.


5.1.6 Classes

Class: basic-generator
Package

snakes.

Source

snakes.lisp.

Direct superclasses

funcallable-standard-object.

Direct methods

5.2 Internals


5.2.1 Macros

Macro: clause-for-in-generator-1 (&key for in-generator generate)

Iterate through a snakes generator

Package

snakes.

Source

iterate.lisp.

Macro: if-generator ((var gen) true-clause &optional false-clause)

Pulls a single iteration out of gen. If a single var is specified, it places all the values from the iteration in a list under var. If var is a list, destructures values into the vars in the list. If the generator has stopped, evaluates false-clause, otherwise evaluates true-clause.

Package

snakes.

Source

snakes.lisp.

Macro: sticky-stop-lambda (params &body body)

Once a generator function has sent a generator-stop symbol, it should continue to do so every time it is called. This macro helps with obeying that rule.

Package

snakes.

Source

snakes.lisp.


5.2.2 Ordinary functions

Function: append! (lst obj)
Package

snakes.

Source

itertools.lisp.

Function: bind-clause (datavar varnames body)
Package

snakes.

Source

do-generators.lisp.

Function: create-values-handler ()

Returns a function to transform ready-to-be-yielded values according to *snakes-multi-mode*. This should be set up at generator creation time, not at consumption time, so that generators in a chain can be set individually.

Package

snakes.

Source

snakes.lisp.

Function: extract-keywords (keywords alist &optional stack)
Package

snakes.

Source

util.lisp.

Function: fill-info (fillspec)
Package

snakes.

Source

do-generators.lisp.

Function: get-generator (g)
Package

snakes.

Source

do-generators.lisp.

Function: get-nextval-func (genspec)
Package

snakes.

Source

do-generators.lisp.

Function: last-car (list)
Package

snakes.

Source

util.lisp.

Function: next-generator-value (gen)
Package

snakes.

Source

do-generators.lisp.

Function: next-generator-value-filled (fill)

Returns a closure that acts like next-generator-value, but returns fill when the generator runs out. The :filled keyword instead of T in the first value slot still evaluates as true, but indicates that the generator has ended.

Package

snakes.

Source

do-generators.lisp.

Function: proc-list-spec (spec)
Package

snakes.

Source

do-generators.lisp.

Function: process-genspecs (genspecs)
Package

snakes.

Source

do-generators.lisp.

Function: stream->generator (stream)

Emits stream line at a time as a generator.

Package

snakes.

Source

snakes.lisp.

Function: xsubseq (sequence start end &key type)

Returns sequence with start->end chopped out of it

Package

snakes.

Source

util.lisp.


5.2.3 Conditions

Condition: insufficient-items

Generator has run out of items before expected.

Package

snakes.

Source

snakes.lisp.

Direct superclasses

snakes-error.

Condition: snakes-error
Package

snakes.

Source

snakes.lisp.

Direct superclasses

simple-error.

Direct subclasses

insufficient-items.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   E   F   G   I   L   M   N   P   R   S   T   V   W   X   Y  
Index Entry  Section

A
append!: Private ordinary functions

B
bind-clause: Private ordinary functions

C
chain: Public ordinary functions
clause-for-in-generator-1: Private macros
combinations: Public ordinary functions
combinations-with-replacement: Public ordinary functions
compress: Public ordinary functions
consume: Public ordinary functions
create-values-handler: Private ordinary functions
cycle: Public ordinary functions

D
defgenerator: Public macros
do-generator: Public macros
do-generator-value-list: Public macros
do-generators: Public macros
dropwhile: Public ordinary functions

E
enumerate: Public ordinary functions
extract-keywords: Private ordinary functions

F
file->generator: Public ordinary functions
fill-info: Private ordinary functions
Function, append!: Private ordinary functions
Function, bind-clause: Private ordinary functions
Function, chain: Public ordinary functions
Function, combinations: Public ordinary functions
Function, combinations-with-replacement: Public ordinary functions
Function, compress: Public ordinary functions
Function, consume: Public ordinary functions
Function, create-values-handler: Private ordinary functions
Function, cycle: Public ordinary functions
Function, dropwhile: Public ordinary functions
Function, enumerate: Public ordinary functions
Function, extract-keywords: Private ordinary functions
Function, file->generator: Public ordinary functions
Function, fill-info: Private ordinary functions
Function, function->generator: Public ordinary functions
Function, generator->list: Public ordinary functions
Function, get-generator: Private ordinary functions
Function, get-nextval-func: Private ordinary functions
Function, groupby: Public ordinary functions
Function, icount: Public ordinary functions
Function, ifilter: Public ordinary functions
Function, ifilter-false: Public ordinary functions
Function, imap: Public ordinary functions
Function, islice: Public ordinary functions
Function, izip: Public ordinary functions
Function, izip-longest: Public ordinary functions
Function, last-car: Private ordinary functions
Function, list->generator: Public ordinary functions
Function, list->generator-with-tail: Public ordinary functions
Function, mapc-generator: Public ordinary functions
Function, mapcar-generator: Public ordinary functions
Function, multi-gen: Public ordinary functions
Function, next-generator-value: Private ordinary functions
Function, next-generator-value-filled: Private ordinary functions
Function, permutations: Public ordinary functions
Function, proc-list-spec: Private ordinary functions
Function, process-genspecs: Private ordinary functions
Function, product: Public ordinary functions
Function, reduce-generator: Public ordinary functions
Function, sequence->generator: Public ordinary functions
Function, starmap: Public ordinary functions
Function, stream->generator: Private ordinary functions
Function, take: Public ordinary functions
Function, take-as-generator: Public ordinary functions
Function, takewhile: Public ordinary functions
Function, tee: Public ordinary functions
Function, value-func->generator: Public ordinary functions
Function, xsubseq: Private ordinary functions
function->generator: Public ordinary functions

G
gen-lambda: Public macros
gen-lambda-with-sticky-stop: Public macros
generator->list: Public ordinary functions
generatorp: Public generic functions
generatorp: Public generic functions
generatorp: Public generic functions
Generic Function, generatorp: Public generic functions
get-generator: Private ordinary functions
get-nextval-func: Private ordinary functions
groupby: Public ordinary functions

I
icount: Public ordinary functions
if-generator: Private macros
ifilter: Public ordinary functions
ifilter-false: Public ordinary functions
imap: Public ordinary functions
initialize-instance: Public standalone methods
islice: Public ordinary functions
izip: Public ordinary functions
izip-longest: Public ordinary functions

L
last-car: Private ordinary functions
list->generator: Public ordinary functions
list->generator-with-tail: Public ordinary functions

M
Macro, clause-for-in-generator-1: Private macros
Macro, defgenerator: Public macros
Macro, do-generator: Public macros
Macro, do-generator-value-list: Public macros
Macro, do-generators: Public macros
Macro, gen-lambda: Public macros
Macro, gen-lambda-with-sticky-stop: Public macros
Macro, if-generator: Private macros
Macro, sticky-stop-lambda: Private macros
Macro, with-yield: Public macros
Macro, yield-all: Public macros
mapc-generator: Public ordinary functions
mapcar-generator: Public ordinary functions
Method, generatorp: Public generic functions
Method, generatorp: Public generic functions
Method, initialize-instance: Public standalone methods
multi-gen: Public ordinary functions

N
next-generator-value: Private ordinary functions
next-generator-value-filled: Private ordinary functions

P
permutations: Public ordinary functions
proc-list-spec: Private ordinary functions
process-genspecs: Private ordinary functions
product: Public ordinary functions

R
reduce-generator: Public ordinary functions

S
sequence->generator: Public ordinary functions
starmap: Public ordinary functions
sticky-stop-lambda: Private macros
stream->generator: Private ordinary functions

T
take: Public ordinary functions
take-as-generator: Public ordinary functions
takewhile: Public ordinary functions
tee: Public ordinary functions

V
value-func->generator: Public ordinary functions

W
with-yield: Public macros

X
xsubseq: Private ordinary functions

Y
yield-all: Public macros


A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*snakes-multi-mode*: Public special variables

S
Special Variable, *snakes-multi-mode*: Public special variables