The picl Reference Manual

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

Table of Contents


1 Introduction


2 Systems

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


2.1 picl

Python Itertools in Common Lisp

Author

Anish Moorthy <>

Home Page

https://anlsh.github.io/picl/

License

MIT

Version

1.0.1

Dependencies
  • defclass-std (system).
  • alexandria (system).
Source

picl.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 picl/src

Source

picl.asd.

Parent Component

picl (system).

Child Components

4 Files

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


4.1 Lisp


4.1.1 picl/picl.asd

Source

picl.asd.

Parent Component

picl (system).

ASDF Systems

picl.


4.1.2 picl/src/package.lisp

Source

picl.asd.

Parent Component

src (module).

Packages

picl.


4.1.3 picl/src/interface.lisp

Dependency

package.lisp (file).

Source

picl.asd.

Parent Component

src (module).

Public Interface
Internals

def-iter (macro).


4.1.4 picl/src/default-iterators.lisp

Dependency

interface.lisp (file).

Source

picl.asd.

Parent Component

src (module).

Public Interface

4.1.5 picl/src/utils.lisp

Dependency

interface.lisp (file).

Source

picl.asd.

Parent Component

src (module).

Public Interface

4.1.6 picl/src/itertools.lisp

Dependency

utils.lisp (file).

Source

picl.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.7 picl/src/combinatoric.lisp

Dependency

utils.lisp (file).

Source

picl.asd.

Parent Component

src (module).

Public Interface

5 Packages

Packages are listed by definition order.


5.1 picl

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Ordinary functions

Function: always (iterable)

Truthy iff every element of the argument is truthy

“‘
(always ’(1 2 3))
;; t
(always ’(nil))
;; nil
(always nil)
t
“‘

Package

picl.

Source

utils.lisp.

Function: apply (fn &rest args)

Like regular apply, except that the final argument can be an arbitrary iterable.

“‘
(picl:apply #’+ 1 #(2 3))
;; 6
“‘

Package

picl.

Source

utils.lisp.

Function: chain (&rest iterables)

Yields the elements of the first iterable in ‘iterable‘, then the second, etc.

“‘
(chain ’(1 2 3) ’(4 5 6) (count 7))
;; 1, 2, 3, 4, 5, 6, 7 etc
“‘

Package

picl.

Source

itertools.lisp.

Function: chain-from-iter (iterable-of-iterables)

Yields the elements of the first iterable in ‘iterable‘, then the second, etc.

Equivalent to python’s chain.from_iterable(), and conceptually equivalent to ‘(picl:apply #’picl:chain iterable-of-iterables)‘.

“‘
(chain-from-iter (picl:map (lambda (x) (picl:range x))) (picl:count))
;; 0, 0, 1, 0, 1, 2, 0, 1, 2, 3, etc
“‘

Package

picl.

Source

itertools.lisp.

Function: combinations (r iterable)

r-combinations of input iterable, returned as vectors in lexicographic order.

“‘
(combinations 2 ’(1 2 3))
;; #(1 2), #(1 3), #(2 3)
“‘

Package

picl.

Source

combinatoric.lisp.

Function: combinations-with-rep (r iterable)

r-combinations with replacement of input iterable, returned as vectors in lexicographic order

“‘
(combinations 2 ’(1 2 3))
;; #(1 1), #(1 2), #(1 3), #(2 1), #(2 2), #(2 3), #(3 1), #(3 2), #(3 3)
“‘

Package

picl.

Source

combinatoric.lisp.

Function: compress (base-iterable bool-iterable)

Yields elements of ‘base-iterable‘ while the corresponding element in ‘bool-iterable‘ is truthy.

Stops when either of its arguments is consumed

“‘
(iterator-compress (count) (t nil t nil t nil))
;; 0 2 4
“‘

Package

picl.

Source

itertools.lisp.

Function: count (&optional start step)

Yields the elements ‘start, start + 1*step, start + 2*step, etc

“‘
(count 2 4)
;; 2, 6, 10, 14, etc
“‘

Package

picl.

Source

itertools.lisp.

Function: cycle (iterable)

Continually yields the elements of its argument in order, starting over when the end is reached

If the base iterator is empty, the result of iterator-cycle will be too

“‘
(cycle ’(1 2 3 4))
;; 1, 2, 3, 4, 1, 2, 3, 4, etc
(iter-to-list (cycle ’()))
;; nil
“‘

Package

picl.

Source

itertools.lisp.

Function: dropwhile (predicate iterable)

Drops all elements of ‘base-iter‘ until ‘pred‘ first returns false, then yields all further elements

“‘
(dropwhile (lambda (x) (< 3 x) (count)))
;; 3, 4, 5, etc
“‘

Package

picl.

Source

itertools.lisp.

Function: empty-iterator ()

Returns an empty iterator

“‘
(iter-to-list (empty-iterator)) ;; nil
“‘

Package

picl.

Source

utils.lisp.

Function: enumerate (iterable &optional curr)

Yield two-element lists of indices (beginning at curr) and their corresponding elements in ‘iterable‘

“‘
(enumerate ’(a b c d))
;; (0 a), (1 b), (2 c), (3 d)
(enumerate ’(a b c d) 3)
;; (3 a), (4 b), (5 c), (6 d)
“‘

Package

picl.

Source

itertools.lisp.

Function: filter (predicate iterable)

Yields elements of ‘iterable‘ for which ‘predicate‘ returns true

“‘
(filter (lambda (x) (evenp x) (count)))
;; 0, 2, 4, etc
“‘

Package

picl.

Source

itertools.lisp.

Function: filterfalse (predicate iterable)

Yields elements of ‘iterable‘ for which ‘predicate‘ returns false

“‘
(filterfalse (lambda (x) (evenp x) (count)))
;; 1, 3, 5, etc
“‘

Package

picl.

Source

itertools.lisp.

Function: islice (iterable start stop delta)

Works like Python’s [islice](https://docs.python.org/3.8/library/itertools.html#itertools.islice)

Package

picl.

Source

itertools.lisp.

Function: iter-to-list (iterable)

Reads ‘iterable‘ into a list

“‘
(iter-to-list (range 4)) ;; (0 1 2 3) (iter-to-list (count)) ;; Out of memory error! “‘

Package

picl.

Source

utils.lisp.

Function: iter-to-vec (iterable)

Reads ‘iterable‘ into a vector

“‘
(iter-to-list (range 4)) ;; #(0 1 2 3) (iter-to-list (count))
;; Out of memory error! “‘

Package

picl.

Source

utils.lisp.

Function: map (predicate &rest iterables)

Applies ‘fn‘ to the first elements of each iterable in ‘iterables‘, then to the seconds, etc

“‘
(map #’+ ’(1 2) ’(3 4))
;; 4, 6
“‘

Package

picl.

Source

itertools.lisp.

Function: never (iterable)

Truthy iff every element of the argument is nil

“‘
(never ’(1 2 3))
;; nil
(never ’(nil))
;; t
(never nil)
t
“‘

Package

picl.

Source

utils.lisp.

Function: next (iterator)

Produces two values, the payload and the alive-indicator

While iterator is not yet exhausted, calling next will yield its next item and a truthy alive-indicator

After iterator has been exhausted all further calls should yield an alive-indicator of nil, and the payload should be ignored by the callee

Package

picl.

Source

interface.lisp.

Function: nfold-product (n iterable)

Computes the n-fold Cartesian product of an iterable with itself.

Essentially equivalent to ‘(apply #’product (iter-to-list (tee n iterable))‘, but with much better memory usage

“‘
(nfold-product 3 ’(1 2))
;; #(1 1 1), #(1 1 2), #(1 2 1), #(1 2 2), #(2 1 1), #(2 1 2), #(2 2 1), #(2 2 2) “‘

Package

picl.

Source

combinatoric.lisp.

Function: permutations (s0 &optional s1)

‘r‘-permutations of input iterable, returned as vectors in lexicographic order.

When a single argument is given, it should be an iterable and ‘r‘ will default to its length.

When two arguments are given, the first corresponds to ‘r‘ and the second to the iterable

“‘
(permutations ’(1 2 3))
;; #(1 2 3), #(1 3 2), #(2 1 3), #(2 3 1), #(3 1 2), #(3 2 1)
(permutations 2 ’(1 2 3))
;; #(1 2), #(1 3), #(2 1), #(2 3), #(3 1), #(3 2)
“‘

Package

picl.

Source

combinatoric.lisp.

Function: product (&rest iterables)

Cartesian product of input iterables, returned as vectors in lexicographic order.

Due to the awkwardness in mixing ‘&rest‘ and ‘&key‘ parameters in lambda lists, this function does not implement the ‘repeat‘ argument supported in
[Python’s version](https://docs.python.org/3/library/itertools.html#itertools.product). Use ‘picl:nfold-product‘ instead.

“‘
(product ’(1 2) ’(3 4))
;; #(1 3), #(1 4), #(2 3), #(2 4)
“‘

Package

picl.

Source

combinatoric.lisp.

Function: range (s0 &optional s1 step)

Works [as in Python](https://docs.python.org/3/library/stdtypes.html#typesseq-range) but produces an iterator (as defined by PICL) instead of a Python-esque range object

“‘
(range 5)
;; 0, 1, 2, 3, 4
(range 2 5)
;; 2, 3, 4
(range -2)
;; 0, -1
(range 1 7 2)
;; 1, 3, 5
“‘

Package

picl.

Source

itertools.lisp.

Function: repeat (s0 &optional s1)

If a single argument is given, yields ‘s0‘ repeatedly forever

If two arguments are given, then yields ‘s1‘ ‘s0‘ times

“‘
(repeat t)
;; t, t, etc
(repeat 4 t)
;; t, t, t, t
“‘

Package

picl.

Source

itertools.lisp.

Function: starmap (fn iterable-of-iterables)

Applies ‘fn‘ to the first argument of ‘iterable-of-iterables‘, then the second, etc

“‘
(starmap #’+ ’(1 2) ’(3 4))
;; 3, 7
“‘

Package

picl.

Source

itertools.lisp.

Function: take (n iterable)

Returns a list consisting of the first ‘n‘ (or fewer, if the iterator runs out) items of iterable

“‘
(take 5 (count))
;; (0 1 2 3 4)
take 30 (range 4)
;; (0 1 2 3)
“‘

Package

picl.

Source

utils.lisp.

Function: takewhile (predicate iterable)

Yields elements of ‘iterable‘ for which ‘predicate‘ is truthy, terminating once it first returns nil

“‘
(takewhile (lambda (x) (< 3 x) (count)))
;; 0, 1, 2
“‘

Package

picl.

Source

itertools.lisp.

Function: tee (n iterable)

Returns a vector of ‘n‘ independent copies of ‘iterable‘. ‘iterable‘ itself should not be used after it has been passed to ‘tee‘, otherwise the tees will not be properly updated

If the base iterable is large be careful not to advance any copy too far ahead of the others, so as to avoid memory issues

“‘
tees = (tee 2 ’(1 2 3 4))
;; tees[0] => 1, 2, 3, 4
;; tees[1] => 1, 2, 3, 4
“‘

Package

picl.

Source

itertools.lisp.

Function: zip (&rest iterables)

Returns vectors consisting of the first elements from each iterable in ‘iterable‘, then the second, etc until one is consumed

“‘
(zip ’(1 2 3) ’(a b c d))
;; #(1 a). #(2 b), #(3 c)
“‘

Package

picl.

Source

itertools.lisp.

Function: zip-longest (fill-item &rest iterables)

Returns vectors consisting of the first elements from each iterable in ‘iterable‘, then the second, etc until *all* are consumed. Once a constituent iterable has been exhausted, ‘fill-value‘ is used to pad the vector in its place.

“‘
(zip nil ’(1 2 3) ’(a b c d))
;; #(1 a). #(2 b), #(3 c), #(nil d)
“‘

Package

picl.

Source

itertools.lisp.


6.1.2 Generic functions

Generic Function: make-iterator (iterable)

Creates an iterator from ‘iterable‘: an iterator is simply anything which can be passed as an argument to ‘next‘

Package

picl.

Source

interface.lisp.

Methods
Method: make-iterator ((obj vector))

Returns an iterator which traverses elements of a vector in sequential order

Source

default-iterators.lisp.

Method: make-iterator ((obj list))

Returns an iterator which traverses elements of a list in sequential order

Source

default-iterators.lisp.

Method: make-iterator ((obj function))

6.2 Internals


6.2.1 Macros

Macro: def-iter (name state-vars (constructor-name constructor-params &body constructor-body) &body next-body)

An anaphoric convenience macro which can be re-implemented to change how iterators are structured. Exposes the local ‘init-state‘ macro within ‘constructor-body‘

If you don’t want to-use this macro (which I totally understand) just write constructors for your iterators returning 0-argument closures representing the ‘next‘ function and you’ll be fine. This macro just helped me get through a lot of waffling during development

Parameters
———-
‘name‘ is a synbol naming the iterator’s backing state. However it’s actually
ignored, since PICL doesn’t currently expose iterators’ backing state

‘state-vars‘ is a list of symbols naming the iterator’s state variables.

The ‘constructor-name/params/body‘ will be ‘defun‘’d to create the user-facing constructor function. In ‘constructor-body‘, the return value should be an iterator or a call to local ‘init-state‘ macro

‘next-body‘ The definition of the ‘next‘ function for this iterator, which will be run in a lexical environment consisting of the state vars

Both ‘constructor-body‘ and ‘next-body‘ are defined in the lexical environment of the ‘def-iter‘ form, and as such can access any lexical bindings not shadowed by the ‘constructor-params‘ and ‘state-vars‘ respectively

The local ‘init-state‘ macro.
—————————-
The arguments to ‘init-state‘ should be of the form ‘(statevar-symbol value-form)‘or ‘statevar-symbol‘. In the first case, the value of ‘value-form‘ will be used to initialize the state variable named by ‘symbol‘. In the second case, ‘statevar-symbol‘ is also used as the corresponding ‘value-form‘

Example
——-
What follows is a sample implementation of the ‘count‘ iterator using this macro
“‘
(def-iter ignored-backing-name (curr-val step)
(count (start step)
(init-state (curr-val start) step))
(prog1 curr-val (incf curr-val step))))
““

Package

picl.

Source

interface.lisp.


6.2.2 Ordinary functions

Function: tee-item (iterable q)

Function had no docstring, so this one was inserted

Package

picl.

Source

itertools.lisp.

Function: zip-from-itl (itl-of-itls)

Function had no docstring, so this one was inserted

Package

picl.

Source

itertools.lisp.

Function: zip-longest-from-itl (itl-of-itls &optional fill-item)

Function had no docstring, so this one was inserted

Package

picl.

Source

itertools.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   D   E   F   G   I   M   N   P   R   S   T   Z  
Index Entry  Section

A
always: Public ordinary functions
apply: Public ordinary functions

C
chain: Public ordinary functions
chain-from-iter: Public ordinary functions
combinations: Public ordinary functions
combinations-with-rep: Public ordinary functions
compress: Public ordinary functions
count: Public ordinary functions
cycle: Public ordinary functions

D
def-iter: Private macros
dropwhile: Public ordinary functions

E
empty-iterator: Public ordinary functions
enumerate: Public ordinary functions

F
filter: Public ordinary functions
filterfalse: Public ordinary functions
Function, always: Public ordinary functions
Function, apply: Public ordinary functions
Function, chain: Public ordinary functions
Function, chain-from-iter: Public ordinary functions
Function, combinations: Public ordinary functions
Function, combinations-with-rep: Public ordinary functions
Function, compress: Public ordinary functions
Function, count: Public ordinary functions
Function, cycle: Public ordinary functions
Function, dropwhile: Public ordinary functions
Function, empty-iterator: Public ordinary functions
Function, enumerate: Public ordinary functions
Function, filter: Public ordinary functions
Function, filterfalse: Public ordinary functions
Function, islice: Public ordinary functions
Function, iter-to-list: Public ordinary functions
Function, iter-to-vec: Public ordinary functions
Function, map: Public ordinary functions
Function, never: Public ordinary functions
Function, next: Public ordinary functions
Function, nfold-product: Public ordinary functions
Function, permutations: Public ordinary functions
Function, product: Public ordinary functions
Function, range: Public ordinary functions
Function, repeat: Public ordinary functions
Function, starmap: Public ordinary functions
Function, take: Public ordinary functions
Function, takewhile: Public ordinary functions
Function, tee: Public ordinary functions
Function, tee-item: Private ordinary functions
Function, zip: Public ordinary functions
Function, zip-from-itl: Private ordinary functions
Function, zip-longest: Public ordinary functions
Function, zip-longest-from-itl: Private ordinary functions

G
Generic Function, make-iterator: Public generic functions

I
islice: Public ordinary functions
iter-to-list: Public ordinary functions
iter-to-vec: Public ordinary functions

M
Macro, def-iter: Private macros
make-iterator: Public generic functions
make-iterator: Public generic functions
make-iterator: Public generic functions
make-iterator: Public generic functions
map: Public ordinary functions
Method, make-iterator: Public generic functions
Method, make-iterator: Public generic functions
Method, make-iterator: Public generic functions

N
never: Public ordinary functions
next: Public ordinary functions
nfold-product: Public ordinary functions

P
permutations: Public ordinary functions
product: Public ordinary functions

R
range: Public ordinary functions
repeat: Public ordinary functions

S
starmap: Public ordinary functions

T
take: Public ordinary functions
takewhile: Public ordinary functions
tee: Public ordinary functions
tee-item: Private ordinary functions

Z
zip: Public ordinary functions
zip-from-itl: Private ordinary functions
zip-longest: Public ordinary functions
zip-longest-from-itl: Private ordinary functions


A.3 Variables