Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the picl Reference Manual, version 1.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 14:40:09 2020 GMT+0.
| • Introduction | What picl is all about | |
| • Systems | The systems documentation | |
| • Modules | The modules documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
Python Itertools in Common Lisp (v1.0.0). Pronounced like "pickle"
A (very nearly) complete port of Python's itertools package, complete with laziness where applicable.
This project currently lives on Github. Pull requests welcome!
PICL aims to provide a complete port of itertools, complete with laziness,
without any reliance on cl-cont.
cl-itertools
and snakes, provide similar functionality.
Unfortunately both libraries rely on cl-cont, meaning they wont always play
nice with the condition system, and cl-itertools remains very incomplete on
top of that
PICL is in Quicklisp, and can be installed as follows
(ql:quickload :picl)
Thanks to Staple you can read the documentation online or build it yourself like so
(staple:generate :picl :if-exists :supersede)
If you don't have PICL's dependencies loaded into your image yet, you'll get some harmless warnings about invalid definitions
A fairly comprehensive test suite written with FiveAM is provided. You can run it yourself either manually or through asdf
;; The easy way
(asdf:test-system :picl)
;; The slightly less easy way
(ql:quickload :picl/tests)
(fiveam:run! 'picl/tests:suite)
An "iterator" in PICL is simply a thunk producing two values: the payload and the alive-indicator. The he alive-indicator should be truthy until after the iterator is consumed.
By example
(let ((it (make-iterator '(1 2))))
(next it) ;; (values 1 t)
(next it) ;; (values 2 t)
(next it)) ;; (values nil nil)
After returning nil, all further next calls should also produce nil as
quickly as possible. Furthermore when the alive indicator is nil, the payload
should be ignored.
To create iterators over your own objects, specialize the make-iterator
generic function appropriately. For instance, the make-iterator definition for
lists is
(defmethod make-iterator ((obj list))
(lambda ()
(if obj
(values (prog1 (car obj) (setf obj (cdr obj))) t)
(values nil nil))))
Specializations for lists and vectors are predefined. A universal in-it
driver is also provided for Iterate
through the picl/iterate system.
(ql:quickload '(:picl :picl/iterate))
(iterate:iter
(iterate:for i in-it (picl:permutations '(1 2 3)))
(iterate:collect i))
;; (#(1 2 3) #(1 3 2) #(2 1 3) #(2 3 1) #(3 1 2) #(3 2 1))
:useDo not :use this package. This library might export new symbols in the
future. You have been forewarned.
Missing functions from Python's itertools
Extensions to library
This project is provided under the MIT License (see LICENSE.md)
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The picl system |
Anish Moorthy <anlsh@protonmail.com>
MIT
Python Itertools in Common Lisp
1.0.1
picl.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
| • The picl/src module |
picl (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The picl/src/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
picl.asd
picl (system)
Next: The picl/src/interface․lisp file, Previous: The picl․asd file, Up: Lisp files [Contents][Index]
Next: The picl/src/default-iterators․lisp file, Previous: The picl/src/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
src (module)
src/interface.lisp
def-iter (macro)
Next: The picl/src/utils․lisp file, Previous: The picl/src/interface․lisp file, Up: Lisp files [Contents][Index]
interface.lisp (file)
src (module)
src/default-iterators.lisp
Next: The picl/src/itertools․lisp file, Previous: The picl/src/default-iterators․lisp file, Up: Lisp files [Contents][Index]
interface.lisp (file)
src (module)
src/utils.lisp
Next: The picl/src/combinatoric․lisp file, Previous: The picl/src/utils․lisp file, Up: Lisp files [Contents][Index]
utils.lisp (file)
src (module)
src/itertools.lisp
Previous: The picl/src/itertools․lisp file, Up: Lisp files [Contents][Index]
utils.lisp (file)
src (module)
src/combinatoric.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The picl package |
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported functions | ||
| • Exported generic functions |
Next: Exported generic functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Truthy iff every element of the argument is truthy
“‘
(always ’(1 2 3))
;; t
(always ’(nil))
;; nil
(always nil)
t
“‘
utils.lisp (file)
Like regular apply, except that the final argument can be an arbitrary
iterable.
“‘
(picl:apply #’+ 1 #(2 3))
;; 6
“‘
utils.lisp (file)
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
“‘
itertools.lisp (file)
r-combinations of input iterable, returned as vectors in lexicographic order.
“‘
(combinations 2 ’(1 2 3))
;; #(1 2), #(1 3), #(2 3)
“‘
combinatoric.lisp (file)
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)
“‘
combinatoric.lisp (file)
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
“‘
itertools.lisp (file)
Yields the elements ‘start, start + 1*step, start + 2*step, etc
“‘
(count 2 4)
;; 2, 6, 10, 14, etc
“‘
itertools.lisp (file)
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
“‘
itertools.lisp (file)
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
“‘
itertools.lisp (file)
Returns an empty iterator
“‘
(iter-to-list (empty-iterator))
;; nil
“‘
utils.lisp (file)
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)
“‘
itertools.lisp (file)
Yields elements of ‘iterable‘ for which ‘predicate‘ returns true
“‘
(filter (lambda (x) (evenp x) (count)))
;; 0, 2, 4, etc
“‘
itertools.lisp (file)
Yields elements of ‘iterable‘ for which ‘predicate‘ returns false
“‘
(filterfalse (lambda (x) (evenp x) (count)))
;; 1, 3, 5, etc
“‘
itertools.lisp (file)
Works like Python’s [islice](https://docs.python.org/3.8/library/itertools.html#itertools.islice)
itertools.lisp (file)
Reads ‘iterable‘ into a list
“‘
(iter-to-list (range 4))
;; (0 1 2 3)
(iter-to-list (count))
;; Out of memory error!
“‘
utils.lisp (file)
Reads ‘iterable‘ into a vector
“‘
(iter-to-list (range 4))
;; #(0 1 2 3)
(iter-to-list (count))
;; Out of memory error!
“‘
utils.lisp (file)
Applies ‘fn‘ to the first elements of each iterable in ‘iterables‘, then to the seconds, etc
“‘
(map #’+ ’(1 2) ’(3 4))
;; 4, 6
“‘
itertools.lisp (file)
Truthy iff every element of the argument is nil
“‘
(never ’(1 2 3))
;; nil
(never ’(nil))
;; t
(never nil)
t
“‘
utils.lisp (file)
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
interface.lisp (file)
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)
“‘
combinatoric.lisp (file)
‘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)
“‘
combinatoric.lisp (file)
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)
“‘
combinatoric.lisp (file)
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
“‘
itertools.lisp (file)
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
“‘
itertools.lisp (file)
Applies ‘fn‘ to the first argument of ‘iterable-of-iterables‘, then the second, etc
“‘
(starmap #’+ ’(1 2) ’(3 4))
;; 3, 7
“‘
itertools.lisp (file)
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)
“‘
utils.lisp (file)
Yields elements of ‘iterable‘ for which ‘predicate‘ is truthy, terminating once it
first returns nil
“‘
(takewhile (lambda (x) (< 3 x) (count)))
;; 0, 1, 2
“‘
itertools.lisp (file)
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
“‘
itertools.lisp (file)
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)
“‘
itertools.lisp (file)
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)
“‘
itertools.lisp (file)
Previous: Exported functions, Up: Exported definitions [Contents][Index]
Creates an iterator from ‘iterable‘: an iterator is simply anything which can be passed as an argument to ‘next‘
interface.lisp (file)
Returns an iterator which traverses elements of a vector in sequential order
default-iterators.lisp (file)
Returns an iterator which traverses elements of a list in sequential order
default-iterators.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal macros | ||
| • Internal functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
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))))
““
interface.lisp (file)
Previous: Internal macros, Up: Internal definitions [Contents][Index]
Function had no docstring, so this one was inserted
itertools.lisp (file)
Function had no docstring, so this one was inserted
itertools.lisp (file)
Function had no docstring, so this one was inserted
itertools.lisp (file)
Function had no docstring, so this one was inserted
itertools.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L M P |
|---|
| Jump to: | F L M P |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | A C D E F G I M N P R S T Z |
|---|
| Jump to: | A C D E F G I M N P R S T Z |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | P S |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| P | |||
Package, picl: | The picl package | ||
picl: | The picl system | ||
picl: | The picl package | ||
| | |||
| S | |||
System, picl: | The picl system | ||
| | |||
| Jump to: | P S |
|---|