File: generator.el.html
This package implements generators for Emacs Lisp through a continuation-passing transformation. It provides essentially the same generator API and iterator facilities that Python and JavaScript ES6 provide.
iter-lambda and iter-defun work like lambda and defun,
except that they evaluate to or define, respectively, generator
functions. These functions, when called, return an iterator.
An iterator is an opaque object that generates a sequence of
values. Callers use iter-next to retrieve the next value from
the sequence; when the sequence is exhausted, iter-next will
raise the iter-end-of-sequence condition.
Generator functions are written like normal functions, except that
they can invoke iter-yield to suspend themselves and return a
value to callers; this value becomes the return value of
iter-next. On the next call to iter-next, execution of the
generator function resumes where it left off. When a generator
function returns normally, the iter-next raises
iter-end-of-sequence with the value the function returned.
iter-yield-from yields all the values from another iterator; it
then evaluates to the value the sub-iterator returned normally.
This facility is useful for functional composition of generators
and for implementing coroutines.
iter-yield is illegal inside the UNWINDFORMS of an
unwind-protect for various sordid internal reasons documented in
the code.
N.B. Each call to a generator function generates a *new* iterator, and each iterator maintains its own internal state.
This raw form of iteration is general, but a bit awkward to use, so this library also provides some convenience functions:
iter-do is like dolist, except that instead of walking a list,
it walks an iterator. cl-loop is also extended with a new
keyword, iter-by, that iterates over an iterator.
Defined variables (4)
cps--dynamic-wrappers | List of functions to apply to atomic forms. |
cps-inhibit-atomic-optimization | When non-nil, always rewrite forms into CPS even when they don’t yield. |
cps-standard-special-forms | List of special forms treated just like ordinary function applications. |
iter-empty | Trivial iterator that always signals the end of sequence. |