The cl-itertools Reference Manual

Table of Contents

The cl-itertools Reference Manual

This is the cl-itertools Reference Manual, version 0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 17:21:34 2020 GMT+0.

1 Introduction

cl-itertools

This is a port of Python itertools, that is a part of standard library, to CL. Original Python docs: https://docs.python.org/2/library/itertools.html

Also it defines couple of primitives, that make writing iterators in CL a joy (at least, for me).

To avoid collisions with CL names the "i" prefix is added to all functions. Thus, they are:

• icount
• icycle
• irepeat
• ichain
• icompress
• idropwhile
• igroupby
• ifilter
• ifilterfalse
• islice -- NOT IMPLEMENTED
• imap
• istarmap
• itee -- NOT IMPLEMENTED
• itakewhile
• izip
• izip-longest
• iproduct -- NOT IMPLEMENTED
• ipermutations -- NOT IMPLEMENTED
• icombinations -- NOT IMPLEMENTED
• icombinations-with-replacement -- NOT IMPLEMENTED
• irange -- this one is called 'xrange' in Python, is not part of itertools, but rather a part of core language, but is very useful anyway, so it's here.

Defined utils

The summary of things, that make working with iterators more convenient. For examples of use, see cl-itertools.lisp itself.

• DEFITER name lambda-list &body body -- conveniently define iterators, with syntax very close to Python ones. Special forms YIELD and COEXIT! are valid inside the body;
• YIELD value -- return next value from iterator, giving control to caller. On next call to iterator value of this form is equal to the argument, supplied by caller (see example below);
• YIELD-LAST-VALUE -- macrolet, which expands into the last value, supplied to the iterator by its caller (see example below);
• COEXIT! -- terminate iterator (analogous to 'raise StopIteration' of Python);
• MK-ITER thing -- generic, which tries to convert anything to CL-ITERTOOLS iterator;
• INEXT iter &optional value -- macro, useful when writing iterators which 'feed' on other iterators. Try to fetch next value from iter and if it's depleted, terminate. VALUE parameter is used to supply value to the iter being called;
• INEXT-NOEXIT iter &optional value -- same as INEXT, but when ITER is depleted, don't terminate, but return (VALUES NIL NIL) (like, e.g., GETHASH does);
• INEXT-OR-ERROR iter &optional value -- same as INEXT, but when ITER is depleted, raises STOP-ITERATION;
• LAMBDA-CORO &body body -- create anonymous coroutine. Inside, coroutine argument is gensymmed, but you can use (YIELD ...) to access values supplied to coroutine on successive invocations;
• FOR var IN-IT iter WITH-ARG arg -- iterate driver to iterate over generic stuff. If the stuff is not already CL-ITERTOOLS iterator, wrap it using MK-ITER generic. ARG is (re-evaluated on each cycle) form, whose result is supplied to iterator on each invocation;
• FOR var IN-CORO coro WITH-ARG arg -- iterate driver for coroutines. Iteration stops as soon as coroutine returns no values (i.e. (VALUES))
• DEF-LAUNCHED-ITER is like DEFITER, but calls iterator one time before returing it. Thus, returned iterator is at the first YIELD, when it's returned.

Technicalities

Iterators are implemented on top of CL-COROUTINE system.

To ease the work with iterators there is a universal "IN-IT" driver for ITERATE

(iter (for i in-it (irange 4 10))
      (collect i))
--> (4 5 6 7 8 9)

To ease definition of new iterators, there is "DEFITER" macro. The syntax is prettly self-explanatory, for example, ICOUNT is defined like

(defiter icount (start &optional (step 1))
  (let ((cur start))
    (iter (while t)
	  (yield cur)
	  (incf cur step))))

On each successful invocation of iterator (underlying iterator coroutine), YIELD form has a value, which is supplied to the coroutine on this invocation.

For example, let's define iterator that just prints whatever is supplied to it (and returns successive integers:

(defiter just-a-printer ()
  (iter (for i from 1)
  	(format t "~a~%" (yield i))))

(defparameter *a* (just-a-printer))
(inext-noexit *a* 'a)
  1
  T
(inext-noexit *a* 'b)
  B
  2
  T
(inext-noexit *a* 'c)
  C
  3
  T

This example also shows use of INEXT-NOEXIT macro, which fetches next value from iterator. Note how symbol A is not printed on first call to INEXT-NOEXIT (because control flow is returned from YIELD, before FORMAT is entered). On second call to INEXT-NOEXIT symbol 'B is correctly printed and the next integer -- 2 -- is returned. Second value T is an artefact of realization.

We can modify this example, so that it would also print symbol A

(defiter just-a-printer ()
  (format t "~a~%" (yield-last-value))
  (iter (for i from 1)
  	(format t "~a~%" (yield i))))

(defparameter *a* (just-a-printer))
(inext-noexit *a* 'a)
  A
  1
  T
(inext-noexit *a* 'b)
  B
  2
  T

For this we need to use (YIELD-LAST-VALUE) macrolet, that always gives the last value, supplied to iterator (to the coroutine) by its caller. Thus, before we encountered any YIELDs in the control flow of the iterator, this value is equal to the value first supplied to the iterator (i.e. 'A).

TODO

• implement ITEE, ISLICE, IPRODUCT, IPERMUTATIONS, ICOMBINATIONS, ICOMBINATIONS-WITH-REPLACEMENT
• make lisp aliases for functions a la IFILTER --> IREMOVE-IF-NOT

2 Systems

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

2.1 cl-itertools

Author

Alexandr Popolitov <popolit@gmail.com>

License

MIT

Description

itertools Python lib ported to CL

Version

0.2

Dependencies

• cl-coroutine
• iterate
• alexandria

Source

cl-itertools.asd (file)

Components

• package.lisp (file)
• cl-itertools.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 cl-itertools.asd

Location

cl-itertools.asd

Systems

cl-itertools (system)

Packages

cl-itertools-system

3.1.2 cl-itertools/package.lisp

Parent

cl-itertools (system)

Location

package.lisp

Packages

cl-itertools

3.1.3 cl-itertools/cl-itertools.lisp

Dependency

package.lisp (file)

Parent

cl-itertools (system)

Location

cl-itertools.lisp

Exported Definitions

• coexit! (macro)
• collect-iter (function)
• def-launched-iter (macro)
• defiter (macro)
• ichain (function)
• icompress (function)
• icount (function)
• icycle (function)
• idropwhile (function)
• ifilter (function)
• ifilterfalse (function)
• igroupby (function)
• imap (function)
• inext (macro)
• inext-noexit (macro)
• inext-or-error (macro)
• irange (function)
• irepeat (function)
• istarmap (function)
• itakewhile (function)
• izip (function)
• izip-longest (function)
• lambda-coro (macro)
• mk-iter (generic function)
• mk-iter (method)
• mk-iter (method)
• mk-iter (method)
• mk-iter (method)
• mk-iter (method)
• mk-iter (method)
• stop-iteration (condition)

Internal Definitions

• clause-for-in-coro-1 (macro)
• clause-for-in-it-2 (macro)
• i-coro (method)
• (setf i-coro) (method)
• i-printing-count (function)
• iterator (class)
• parse-out-keywords (function)

4 Packages

Packages are listed by definition order.

4.1 cl-itertools-system

Source

cl-itertools.asd

Use List

• asdf/interface
• common-lisp

4.2 cl-itertools

Source

package.lisp (file)

Use List

• cl-coroutine
• iterate
• common-lisp

Exported Definitions

• coexit! (macro)
• collect-iter (function)
• def-launched-iter (macro)
• defiter (macro)
• ichain (function)
• icompress (function)
• icount (function)
• icycle (function)
• idropwhile (function)
• ifilter (function)
• ifilterfalse (function)
• igroupby (function)
• imap (function)
• inext (macro)
• inext-noexit (macro)
• inext-or-error (macro)
• irange (function)
• irepeat (function)
• istarmap (function)
• itakewhile (function)
• izip (function)
• izip-longest (function)
• lambda-coro (macro)
• mk-iter (generic function)
• mk-iter (method)
• mk-iter (method)
• mk-iter (method)
• mk-iter (method)
• mk-iter (method)
• mk-iter (method)
• stop-iteration (condition)

Internal Definitions

• clause-for-in-coro-1 (macro)
• clause-for-in-it-2 (macro)
• i-coro (generic function)
• i-coro (method)
• (setf i-coro) (method)
• (setf i-coro) (generic function)
• i-printing-count (function)
• iterator (class)
• parse-out-keywords (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: coexit! ()

Package

cl-itertools

Source

cl-itertools.lisp (file)

Macro: def-launched-iter NAME ARGS &body BODY

Package

cl-itertools

Source

cl-itertools.lisp (file)

Macro: defiter NAME ARGS &body BODY

Package

cl-itertools

Source

cl-itertools.lisp (file)

Macro: inext ITER-VAR &optional ARG

Iter is supposed to be created using DEFITER or MK-ITER – hence its coro always accepts an arg.

Package

cl-itertools

Source

cl-itertools.lisp (file)

Macro: inext-noexit ITER-VAR &optional ARG

Like INEXT, only when iterator is depleted, return (VALUES NIL NIL) and don’t COEXIT.

Package

cl-itertools

Source

cl-itertools.lisp (file)

Macro: inext-or-error ITER-VAR &optional ARG

Package

cl-itertools

Source

cl-itertools.lisp (file)

Macro: lambda-coro &body BODY

The coroutine argument is passed through YIELD macro.

Package

cl-itertools

Source

cl-itertools.lisp (file)

5.1.2 Functions

Function: collect-iter THING

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: ichain &rest THINGS

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: icompress DATA SELECTORS

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: icount START &optional STEP

start, start + step, start + 2*step, ...

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: icycle P

p0, p1, ... plast, p0, p1, ...

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: idropwhile PRED SEQ

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: ifilter PRED SEQ

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: ifilterfalse PRED SEQ

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: igroupby ITERABLE &optional KEY

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: imap FUNC &rest THINGS

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: irange &rest ARGS

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: irepeat ELEM &optional N

elem, elem, elem, ... endlessly or up to n times

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: istarmap FUNC SEQ

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: itakewhile PRED SEQ

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: izip &rest THINGS

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: izip-longest &rest THINGS

Package

cl-itertools

Source

cl-itertools.lisp (file)

5.1.3 Generic functions

Generic Function: mk-iter THING

Package

cl-itertools

Source

cl-itertools.lisp (file)

Methods

Method: mk-iter (THING vector)

Method: mk-iter (THING string)

Method: mk-iter (THING list)

Method: mk-iter (THING function)

Method: mk-iter (THING iterator)

Method: mk-iter THING

5.1.4 Conditions

Condition: stop-iteration ()

Package

cl-itertools

Source

cl-itertools.lisp (file)

Direct superclasses

error (condition)

5.2 Internal definitions

5.2.1 Macros

Macro: clause-for-in-coro-1 &key (FOR VAR) (IN-CORO CORO) (WITH-ARG ARG) GENERATE

Package

cl-itertools

Source

cl-itertools.lisp (file)

Macro: clause-for-in-it-2 &key (FOR VAR) (IN-IT THING) (WITH-ARG ARG) GENERATE

Package

cl-itertools

Source

cl-itertools.lisp (file)

5.2.2 Functions

Function: i-printing-count START &optional STEP

Package

cl-itertools

Source

cl-itertools.lisp (file)

Function: parse-out-keywords KWD-LST LAMBDA-LIST

Return list (KWD1 KWD2 ... KWDn . OTHER-ARGS) collecting all keyword-looking pairs of arguments in lambda list

Package

cl-itertools

Source

cl-itertools.lisp (file)

5.2.3 Generic functions

Generic Function: i-coro OBJECT

Generic Function: (setf i-coro) NEW-VALUE OBJECT

Package

cl-itertools

Methods

Method: i-coro (ITERATOR iterator)

automatically generated reader method

Source

cl-itertools.lisp (file)

Method: (setf i-coro) NEW-VALUE (ITERATOR iterator)

automatically generated writer method

Source

cl-itertools.lisp (file)

5.2.4 Classes

Class: iterator ()

Package

cl-itertools

Source

cl-itertools.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• mk-iter (method)
• i-coro (method)
• i-coro (method)

Direct slots

Slot: coro

Initargs

:coro

Readers

i-coro (generic function)

Writers

(setf i-coro) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types