# 1.0.0

An extensible iteration macro library.

For is a library for an extensible iteration macro. It allows you to write concise looping constructs similar to `loop` and `iterate`. Unlike loop however it is extensible and sensible, and unlike iterate it does not require code-walking and is easier to extend.

## How To

Load For using ASDF or Quicklisp.

``````(ql:quickload :for)
``````

Now we can use the `for` macro to do iteration. Most of the constructs you know from `loop` are available with the same name in For.

``````(for:for ((li in (list 1 2 3 4))
(vi across #(a b c d)))
(format T "~&~a ~a" li vi))
``````

In `loop` this might look as follows:

``````(loop for li in (list 1 2 3 4)
for vi across #(a b c d)
do (format T "~&~a ~a" li vi))
``````

Unlike `loop` and `iterate`, `for` makes a distinction between "bindings" and body forms. Body forms can also contain clauses:

``````(for:for ((li in (list 1 2 3 4)))
(thereis (evenp li)))
``````

In `loop` this might look as follows:

``````(loop for li in (list 1 2 3 4)
thereis (evenp li))
``````

Naturally, there's also accumulation bindings:

``````(for:for ((randoms collecting (random 10)))
(until (= 10 (length randoms))))
``````

In `loop` this might look as follows:

``````(loop collect (random 10) into randoms
until (= 10 (length randoms)))
``````

You might realise that the above is a rather inefficient way of writing the loop. Instead we can also use the `repeat` binding:

``````(for:for ((i repeat 10)
(randoms collecting (random 10))))
``````

In `loop` this might look as follows:

``````(loop repeat 10
collect (random 10))
``````

If we have multiple bindings or clauses that might have useful values to return, all of them are returned:

``````(for:for ((a over *random-state* :limit 10)
(b collect a))
(thereis (evenp a)))
``````

In `loop` this might look as follows:

``````(loop with iterator = (for-iterator:make-iterator *random-state* :limit 10)
while (for-iterator:has-more iterator)
for a = (for-iterator:next iterator)
collect a into b
when (evenp a)
return (values T b))
``````

In order for short-circuiting clauses to have highest priority on values, clause-values are always returned first followed by binding values. Otherwise the order follows the declaration order of the respective clauses/bindings. Note that clauses must appear as a "top-level" form within the `for` body and cannot appear as the result of a macroexpansion.

For also features a generic iterator construct that allows you to iterate over a multitude of different data types without having to do a case-distinction by yourself. We already saw this with the `over *random-state*` binding from the previous example.

``````(for:for ((a over '(1 2 3))
(b over #(a b c))
(c over (for:for ((table as (make-hash-table)))
(setf (gethash (random 10) table) (random 10)) (repeat 3)))
(d over *package*)
(e over *random-state*)
(f over (directory (merge-pathnames "*.*" (user-homedir-pathname))))
(g over (make-string-input-stream "Hi!")))
(print (list a b c d e f g)))
``````

Note that the `over` iterator construct can be drastically slower than a tailored iteration construct.

Some iterators also support updating the current element. If you require doing so, you can use the `updating` binding.

``````(for:for ((list as (list 1 2 3 4 5))
(item updating list))
(setf item (expt item item)))
``````

In `loop` this might look as follows:

``````(loop with list = (list 1 2 3 4 5)
with iterator = (for-iterator:make-iterator list)
while (for-iterator:has-more iterator)
do (for-iterator:next iterator)
(symbol-macrolet ((item (for-iterator:current iterator)))
(setf item (expt item item)))
finally (return list))
``````

Some of the bindings also support destructuring the current item by a destructuring-lambda-list.

``````(for:for (((type &key object limit) in '((counter :limit 5)
(package :object *package*))))
(format T "~&Type: ~a~@[ Object: ~a~]~@[ Limit: ~a~]" type object limit))
``````

In `loop` this might look as follows:

``````(loop for list in '((counter :limit 5)
(package :object *package*))
do (destructuring-bind (type &key object limit) list
(format T "~&Type: ~a~@[ Object: ~a~]~@[ Limit: ~a~]" type object limit)))
``````

You can check a binding's or clause's documentation with `(documentation 'in 'for:binding)` which will tell you whether it supports destructuring through `update`.

Sometimes you may want to iterate over multiple things in sequence rather than in parallel. For this you can use the `being` binding, which allows you to pass a list of sub-bindings to sequentially use.

``````(for:for (((k v) being
(in '((駅 station) (出口 exit) (特急 express-train)))
(across #((勉強 studying) (宿題 home-work) (授業 lesson) (試験 exam)))))
(format T "~&~a: ~a" k v))
``````

In `loop` this might look as follows:

``````(progn (loop for (k v) in '((駅 station) (出口 exit) (特急 express-train))
do (format T "~&~a: ~a" k v))
(loop for (k v) across #((勉強 studying) (宿題 home-work) (授業 lesson) (試験 exam))
do (format T "~&~a: ~a" k v)))
``````

If a binding should only be updated based on a condition, there's the `when` and `unless` bindings that defer based on a test.

``````(for:for ((random = (random 10))
(list when (evenp random) collect random))
(until (= 10 (length list))))
``````

In `loop` this might look as follows:

``````(loop with list = ()
for random = (random 10)
when (evenp random)
do (push random list)
until (= 10 (length list))
finally (return (nreverse list)))
``````

The following bindings are included in the `for-minimal` package:

• `=`
• `across`
• `appending` / `append`
• `as`
• `being`
• `collecting` / `collect`
• `counting` / `count`
• `from`
• `in`
• `lines-of`
• `maximizing` / `maximize`
• `minimizing` / `minimize`
• `nconcing` / `nconc`
• `on`
• `over`
• `ranging` / `range`
• `reducing` / `reduce`
• `repeating` / `repeat`
• `summing` / `sum`
• `symbols`
• `table-keys`
• `table-pairs`
• `table-values`
• `unless`
• `updating` / `update`
• `when`

The following clauses are included in the `for-minimal` package:

• `always`
• `never`
• `returning`
• `thereis`
• `until`
• `while`

Iterator classes for the following types is included in the `for-iterator` package:

• `list`
• `vector`
• `array`
• `stream`
• `pathname`
• `random-state`
• `package`
• `hash-table` each item is a list of key and value.

## Extending FOR

Both bindings and clauses are defined in terms of functions that return three values:

1. A surrounding form
Surrounding forms will be wrapped around the rest of the expanded for by appending the rest to it. This happens through `with-interleaving`.
2. A loop body form
The body form is put inside the loop where it will be evaluated once per iteration.
3. A return value form
The return value form is evaluated on loop end. The position within the returned values is dependent on the clauses and bindings present during expansion. If not provided, no return value is generated. Note that this is distinct from having NIL as a third value.

Passed to the functions are the literal arguments used in the binding or clause expression. In that way, a clause/binding function must work just like a macro would.

### Bindings

The most primitive way to define bindings is through the `define-direct-binding` macro. This defines a verbatim binding function as described above. Note that the loop body forms of bindings will always be evaluated before the proper for body.

In most cases you will want the arguments that are passed to the binding to be evaluated only once, before the loop starts properly. The `define-value-binding` macro will help you with that. Each argument you specify will be bound to a gensym within the definition body, and is automatically expanded to a variable with the value that is used in the binding. `&aux` arguments receive special treatment as they are expanded like regular variables and thus allow you to easily define helper variables necessary during iteration.

Let's look at an example binding definition:

``````(define-value-binding across (var vector &aux (i -1) (length (length vector)))
`(if (= ,length (incf ,i))
(end-for)
(update ,var (aref ,vector ,i))))
``````

Expanding a simple call `(for ((a across vec)))` results in this expansion (after cleaning it up a little):

``````(LET* ((#:VECTOR VEC)
(#:I -1)
(#:LENGTH (LENGTH #:VECTOR))
(A NIL))
(WITH-FOR-BODY
(IF (= #:LENGTH (INCF #:I))
(END-FOR)
(UPDATE A (AREF #:VECTOR #:I))))
``````

As you can see, our only argument, `vector` got expanded into a gensym-ed variable that is bound to the result of the `vector` argument. Our auxiliary variables received similar treatment. Note that references to other arguments automatically get translated to their proper gensyms.

In some cases however you'd like to re-evaluate an argument each iteration. To get this behaviour, you can use `define-form-binding`. Here's a simple example:

`````` (define-form-binding = (var form)
`(update ,var ,form))
``````

Expanding a simple call `(for ((a = (* 2 2))))` presents us with:

`````` (LET* ((A NIL))
(WITH-FOR-BODY
(UPDATE A (* 2 2)))
``````

Usually you will want form bindings if you want to accumulate the results of it over time in some manner. In that case you usually also want to return the result of the accumulation once you're done. `define-accumulation-binding` does exactly that. One note about form bindings is that the auxiliary variables still act the same as in the value bindings-- they automatically get expanded to bindings in the resulting loop construct.

Let's look at an example that shows both:

``````(define-accumulation-binding collecting (var form &aux (head (cons NIL NIL)) (tail head))
`(setf ,tail (setf (cdr ,tail) (cons ,form NIL))
``````

Expanding `(for ((a collecting 2)))` results in:

``````(LET* ((#:HEAD (CONS NIL NIL)) (#:TAIL #:HEAD) (A NIL))
(WITH-FOR-BODY
(SETF #:TAIL (SETF (CDR #:TAIL) (CONS 2 NIL))
(RETURN-FOR A))
``````

As before, the auxiliary arguments got expanded to variable bindings with their respective default values.

Finally we have two variants of form and value bindings, `define-form-symbol-macro-binding` and `define-value-symbol-macro-binding`. The difference to the previous definition forms here is that the `var` is not bound as a variable, but instead as a symbol macro. Its default value is the symbol-macro expansion. This is useful if you want to provide an updateable place as the iteration var, as is the case with the `updating` binding.

### Clauses

Clauses work the exact same as bindings in terms of the base function, which you can define with `define-direct-clause`. Unlike bindings however, clauses simply get the body of their call as arguments, without an iteration var.

In order to ease things a bit there is also `define-simple-clause` which provides the same handling for arguments as `define-form-binding` does.

One thing to note is that the surrounding forms of clauses always appear deeper than those of bindings and that the result value forms of clauses always appear before those of bindings. The loop body form of a clause appears at the exact position in the body where the clause expression previously appeared.

### Iterators

In order to provide the generic `over` iteration construct, For includes a protocol to define iterators. In order for an iterator to work, it has to subclass `iterator` and provide three methods: `make-iterator`, `has-more`, and `next`. The first is merely there so that we can dispatch on the type of object we'd like to iterate over and construct an appropriate iterator for it. The second should return a generalised boolean that tells us whether we can safely call `next`. Finally, `next` itself advances the iterator and returns a new element. If sensible and possible, a method on `(setf current)` can also be provided to allow updating the current element to a new value.

Let's look at the list iterator as an example:

``````(defclass list-iterator (iterator)
())

(defmethod initialize-instance :after ((iterator list-iterator) &key object)
(setf (object iterator) (cons NIL object)))

(defmethod has-more ((iterator list-iterator))
(cdr (object iterator)))

(defmethod next ((iterator list-iterator))
(setf (object iterator) (cdr (object iterator)))
(car (object iterator)))

(defmethod (setf current) (value (iterator list-iterator))
(setf (car (object iterator)) value))

(defmethod make-iterator ((list list) &key)
(make-instance 'list-iterator :object list))
``````

First we subclass `iterator`. Next we define an initialize method in order to prepend a cons to the list. We do this so that we know the next element will always be in the cadr of the `object` and we can still set the car of the current cons cell to update it. The `has-more` test is implemented accordingly. On `next` we then simply pop off the first cons and return our new current element. The `(setf current)` can then just update the car of the `object`. Finally we need a `make-iterator` method to dispatch on lists.

## Package Index

• ### FOR(ORG.SHIRAKUMO.FOR)

• class

#### `ARRAY-ITERATOR`

```Iterator for general arrays.

Iteration is in row-major order.

Supports setting the current element.

See VECTOR-ITERATOR
See TOTAL-LENGTH```
• class

#### `DIRECTORY-ITERATOR`

```Iterator for a DIRECTORY listing.

On construction, this performs a simple DIRECTORY call on the given object
and then iterates over the result list of pathnames. Thus, the pathname must
be wild.

See LIST-ITERATOR```
• class

#### `HASH-TABLE-ITERATOR`

```Iterator for the key/value pairs in a package.

Each value returned by this iterator's CURRENT/NEXT is always a list of two values, the
respective key and its value.

Supports setting the current element.

See PREFETCH
See ITERATOR```
• class

#### `ITERATOR`

```An iterator is responsible for iterating over a given data structure.

See HAS-MORE
See NEXT
See CURRENT
See MAKE-ITERATOR
See OBJECT```
• class

#### `LIST-ITERATOR`

```Iterator for proper lists.

Supports setting the current element.

See ITERATOR```
• class

#### `PACKAGE-ITERATOR`

```Iterator for the symbols in a package.

The type of symbols that are iterated can be set through the :STATUS initarg, which must
be a list containing any of the following keywords: :INTERNAL :EXTERNAL :INHERITED

See PREFETCH
See ITERATOR```
• class

#### `RANDOM-ITERATOR`

```Iterator for random numbers.

This iterator can be constructed through a RANDOM-STATE object. The argument for RANDOM
that determines its limit can be passed through the :LIMIT initarg.

See ITERATOR```
• class

#### `STREAM-ITERATOR`

```Iterator for input streams.

The stream is read through a buffer, the size of which can be set via the :BUFFER-SIZE
initarg. If :CLOSE-STREAM is set to non-NIL, CLOSE is performed on the stream upon END.

Supports setting the "current" element if the stream supports writing to it of course.

See BUFFER
See INDEX
See LIMIT
See ITERATOR```
• class

#### `STREAM-LINE-ITERATOR`

```Iterator for line based input streams.

If :CLOSE-STREAM is set to non-NIL, CLOSE is performed on the stream upon END.

See BUFFER
See CLOSE-STREAM
See ITERATOR```
• class

#### `VECTOR-ITERATOR`

```Iterator for vectors.

Supports setting the current element.

See START
See ITERATOR```
• accessor `(`

#### `BINDING`

`NAME``)`
```Accessor to the function that compiles the given binding.

If there is no binding named by the given symbol directly, another search is
performed using the symbol with the same symbol-name from the FOR package.

See REMOVE-BINDING```
• accessor `(`

#### `BUFFER`

`OBJECT``)`
```Accessor to the stream-iterator's buffer.

See STREAM-ITERATOR```
• accessor `(`

#### `CLAUSE`

`NAME``)`
```Accessor to the function that compiles the given clause.

If there is no clause named by the given symbol directly, another search is
performed using the symbol with the same symbol-name from the FOR package.

See REMOVE-CLAUSE```
• accessor `(`

#### `CLOSE-STREAM`

`OBJECT``)`
```Accessor to whether the stream should be closed on END call or not.

See STREAM-ITERATOR
See STREAM-LINE-ITERATOR```
• accessor `(`

#### `CURRENT`

`ITERATOR``)`
```Accessor to the current item of the iterator.

The behaviour is undefined if CURRENT is used before NEXT has been called for a first time.
Some (but not all) iterators may support setting the current element to a new value.

See NEXT```
• accessor `(`

#### `INDEX`

`OBJECT``)`
```Accessor to the current index within the buffer.

See STREAM-ITERATOR```
• accessor `(`

#### `LIMIT`

`OBJECT``)`
```Accessor to the amount of data that is currently filled in the buffer.

See STREAM-ITERATOR```
• accessor `(`

#### `OBJECT`

`OBJECT``)`
```Accessor to the data structure the iterator is iterating over.

Note that this is not necessarily the same object as what was passed into the
constructor of the iterator. The iterator is free to modify this slot as it sees fit.

See ITERATOR```
• accessor `(`

#### `PREFETCH`

`OBJECT``)`
```Cache for the next value

Since the iterator constructs provided by CL do not allow merely testing whether a next
element is available without losing it if there is one, we must cache the value on a
HAS-MORE call and then use that on NEXT instead of calling the iterator function twice.

See PACKAGE-ITERATOR
See HASH-TABLE-ITERATOR```
• accessor `(`

#### `START`

`OBJECT``)`
`Accessor to the index that points to the next element of the vector-iterator.`
• accessor `(`

#### `TOTAL-LENGTH`

`OBJECT``)`
```Slot holding the array-total-size.

See ARRAY-ITERATOR```
• function `(`

#### `=`

`NUMBER &REST MORE-NUMBERS``)`
`Return T if all of its arguments are numerically equal, NIL otherwise.`
• function `(`

#### `APPEND`

`&REST LISTS``)`
`Construct a new list by concatenating the list arguments`
• function `(`

#### `COUNT`

```ITEM SEQUENCE &REST ARGS &KEY FROM-END (START 0) (END NIL) (KEY NIL) (TEST (FUNCTION EQL) TEST-P) (TEST-NOT NIL TEST-NOT-P)````)`
```Return the number of elements in SEQUENCE satisfying a test with ITEM,
which defaults to EQL.```
• function `(`

#### `HASH-TABLE-ITERATOR`

`TABLE``)`
```Returns a function to iterate over a hash-table.

See CL:WITH-HASH-TABLE-ITERATOR```
• function `(`

#### `NCONC`

`&REST LISTS``)`
`Concatenates the lists given as arguments (by changing them)`
• function `(`

#### `PACKAGE-ITERATOR`

`PACKAGE STATUSES``)`
```Returns a function to iterate over a package's symbols.

See CL:WITH-PACKAGE-ITERATOR```
• function `(`

#### `REDUCE`

```FUNCTION SEQUENCE &REST ARGS &KEY (KEY NIL) FROM-END (START 0) (END NIL) (INITIAL-VALUE NIL IVP)````)`
No docstring provided.
• function `(`

#### `REMOVE-BINDING`

`NAME``)`
```Removes the given binding function.

See BINDING```
• function `(`

#### `REMOVE-CLAUSE`

`NAME``)`
```Removes the given clause function.

See CLAUSE```
• binding `(`

#### `=`

`VAR FORM``)`
```Updates the var by the value of the given form every time.

Supports UPDATE.```
• binding `(`

#### `ACROSS`

`VAR VECTOR``)`
```Iterates over a vector, binding the current item to the var every time.

Supports UPDATE.```
• binding `(`

#### `APPEND`

`VAR FORM``)`
```Appends the results of FORM into a list where the VAR points to the head of the list.

This returns the var on END-FOR.```
• binding `(`

#### `APPENDING`

`VAR FORM``)`
```Appends the results of FORM into a list where the VAR points to the head of the list.

This returns the var on END-FOR.```
• binding `(`

#### `AS`

`VAR VALUE``)`
```Simply binds the value of the form to the var.

This returns the var on END-FOR.```
• binding `(`

#### `BEING`

`VAR &REST SUB-BINDINGS``)`
```Sequences multiple bindings onto the same var.

Expected as arguments is a list of binding expressions, except with each of them missing
the initial var as that is supplied by the var of the BEING binding.

During the iteration the var is then updated by the first inner binding until that calls
END-FOR, after which the var is then updated by the second binding and so forth until the
last binding calls END-FOR, in which case the behaviour is as usual.

Essentially this just does what you expect it would: it chains multiple bindings onto the
same var, sequentially using the next one after the one before finishes.

May support UPDATE depending on the inner bindings.

Note that only bindings that output a LET/LET* as their surrounding form are supported
without potential warnings about unused variables. The bindings also must not output the
var as a symbol macro as it is not possible to update that depending on which binding
is currently active.```
• binding `(`

#### `COLLECT`

`VAR FORM``)`
```Collects the results of FORM into a list where the VAR points to the head of the list.

This returns the var on END-FOR.```
• binding `(`

#### `COLLECTING`

`VAR FORM``)`
```Collects the results of FORM into a list where the VAR points to the head of the list.

This returns the var on END-FOR.```
• binding `(`

#### `COUNT`

`VAR FORM``)`
```Increases the var by one if the FORM returns non-NIL.

This returns the var on END-FOR.```
• binding `(`

#### `COUNTING`

`VAR FORM``)`
```Increases the var by one if the FORM returns non-NIL.

This returns the var on END-FOR.```
• binding `(`

#### `FROM`

`VAR FROM &KEY (TO NIL TO-P) (BY 1)``)`
```Increases the var by a step every time up to an optional limit.

An optional BY keyword argument is accepted, which determines the step.
An optional TO keyword argument is accepted, which determines the exclusive limit.
This means (a from 0 :to 2) iterates over 0 and 1. If TO is smaller than FROM then
the variable is decreased by BY every step.```
• binding `(`

#### `IN`

`VAR LIST &KEY (BY NIL BY-P)``)`
```Iterates over a list, binding the current list element to the var every time.

Supports UPDATE.

Accepts a BY keyword argument, which determines how the list is stepped.```
• binding `(`

#### `LINES-OF`

`VAR PATHNAME/STREAM``)`
```Iterates over the given file or stream, reading a line each time.

The stream is always closed when the For loop exits.```
• binding `(`

#### `MAXIMIZE`

`VAR FORM``)`
```Sets the var to the maximum of the values returned by FORM so far each step.

This returns the var on END-FOR.```
• binding `(`

#### `MAXIMIZING`

`VAR FORM``)`
```Sets the var to the maximum of the values returned by FORM so far each step.

This returns the var on END-FOR.```
• binding `(`

#### `MINIMIZE`

`VAR FORM``)`
```Sets the var to the minimum of the values returned by FORM so far each step.

This returns the var on END-FOR.```
• binding `(`

#### `MINIMIZING`

`VAR FORM``)`
```Sets the var to the minimum of the values returned by FORM so far each step.

This returns the var on END-FOR.```
• binding `(`

#### `NCONC`

`VAR FORM``)`
```Appends the results of FORM destructively into a list where the VAR points to the head of the list.

This returns the var on END-FOR.```
• binding `(`

#### `NCONCING`

`VAR FORM``)`
```Appends the results of FORM destructively into a list where the VAR points to the head of the list.

This returns the var on END-FOR.```
• binding `(`

#### `ON`

`VAR LIST &KEY (BY NIL BY-P)``)`
```Iterates over a list, binding the current list cons to the var every time.

Supports UPDATE.

Accepts a BY keyword argument, which determines how the list is stepped.```
• binding `(`

#### `OVER`

`VAR ITERABLE &REST ITERATOR-ARGS``)`
```Iterates over a generic sequence using an ITERATOR, binding the current item to the var every step.

Supports UPDATE.

Potentially accepts arbitrary arguments, depending on which iterator is selected
for the respective object.

See FOR-ITERATOR:MAKE-ITERATOR```
• binding `(`

#### `RANGE`

`VAR FROM TO &KEY (BY 1)``)`
```Iterates the var over the given range.

Ranges can be either decreasing or increasing. Both limits are inclusive. This means that
(a ranging 0 2) iterates over 0, 1, and 2.

An optional BY keyword argument is accepted, which determines the step.```
• binding `(`

#### `RANGING`

`VAR FROM TO &KEY (BY 1)``)`
```Iterates the var over the given range.

Ranges can be either decreasing or increasing. Both limits are inclusive. This means that
(a ranging 0 2) iterates over 0, 1, and 2.

An optional BY keyword argument is accepted, which determines the step.```
• binding `(`

#### `REDUCE`

`VAR FORM &KEY (BY NIL BY-P)``)`
```Combines the results of FORM by a combination function BY into var.

On the first iteration the var is simply set to the result of the FORM. On every
successive step, the var is set to the result of calling BY with the var as the
first argument and the result of the FORM as the second argument.

This returns the var on END-FOR.```
• binding `(`

#### `REDUCING`

`VAR FORM &KEY (BY NIL BY-P)``)`
```Combines the results of FORM by a combination function BY into var.

On the first iteration the var is simply set to the result of the FORM. On every
successive step, the var is set to the result of calling BY with the var as the
first argument and the result of the FORM as the second argument.

This returns the var on END-FOR.```
• binding `(`

#### `REPEAT`

`VAR LIMIT``)`
```Increases the var the given amount of times starting with 1.

This is the same as (a between 1 n)```
• binding `(`

#### `REPEATING`

`VAR LIMIT``)`
```Increases the var the given amount of times starting with 1.

This is the same as (a between 1 n)```
• binding `(`

#### `SUM`

`VAR FORM``)`
```Sums up the value of the FORM into the var.

This returns the var on END-FOR.```
• binding `(`

#### `SUMMING`

`VAR FORM``)`
```Sums up the value of the FORM into the var.

This returns the var on END-FOR.```
• binding `(`

#### `SYMBOLS`

`VAR PACKAGE &REST STATUS``)`
```Iterates over the symbols of a package, binding the current symbol to the var every time.

Accepts an optional list of arguments that qualify the type of symbols to iterate over.
Each type must be one of :INTERNAL :EXTERNAL :INHERITED. If no arguments are given, it
defaults to (:INTERNAL :EXTERNAL :INHERITED).```
• binding `(`

#### `TABLE-KEYS`

`VAR TABLE``)`
```Iterates over a hash table, binding the current key to the var every time.

Supports UPDATE.```
• binding `(`

#### `TABLE-PAIRS`

`VAR TABLE``)`
```Iterates over a hash table, binding a list of the current key and value to the var every time.

Supports UPDATE.```
• binding `(`

#### `TABLE-VALUES`

`VAR TABLE``)`
```Iterates over a hash table, binding the current value to the var every time.

Supports UPDATE.```
• binding `(`

#### `UNLESS`

`VAR TEST SUB-BINDING &REST ARGS``)`
```Conditionally apply a binding.

The sub-binding's step form is only evaluated if the given test fails. This means that
the var is only updated and the loop can only be ended when the test returns NIL.

May support UPDATE depending on the sub-binding.```
• binding `(`

#### `UPDATE`

`VAR ITERABLE &REST ITERATOR-ARGS``)`
```Iterates over a generic sequence using an ITERATOR, with var being symbol macro to the current item.

You may SETF the var to update the item in the sequence, if the underlying iterator
supports doing so.

Potentially accepts arbitrary arguments, depending on which iterator is selected
for the respective object.

See FOR-ITERATOR:MAKE-ITERATOR```
• binding `(`

#### `UPDATING`

`VAR ITERABLE &REST ITERATOR-ARGS``)`
```Iterates over a generic sequence using an ITERATOR, with var being symbol macro to the current item.

You may SETF the var to update the item in the sequence, if the underlying iterator
supports doing so.

Potentially accepts arbitrary arguments, depending on which iterator is selected
for the respective object.

See FOR-ITERATOR:MAKE-ITERATOR```
• binding `(`

#### `WHEN`

`VAR TEST SUB-BINDING &REST ARGS``)`
```Conditionally apply a binding.

The sub-binding's step form is only evaluated if the given test succeeds. This means that
the var is only updated and the loop can only be ended when the test returns non-NIL.

May support UPDATE depending on the sub-binding.```
• clause `(`

#### `ALWAYS`

`FORM``)`
```If FORM always returns non-NIL, then T is returned.
As soon as FORM returns NIL the for is aborted with END-FOR and NIL is returned.```
• clause `(`

#### `NEVER`

`FORM``)`
```If FORM never returns non-NIL, then T is returned.
As soon as FORM returns non-NIL the for is aborted with END-FOR and NIL is returned.```
• clause `(`

#### `REPEAT`

`N``)`
`Makes sure the loop body is repeated a maximum of N times.`
• clause `(`

#### `RETURNING`

`FORM``)`
`Does nothing each step, but makes sure to evaluate and return the value of FORM on END-FOR.`
• clause `(`

#### `THEREIS`

`FORM``)`
```If FORM never returns non-NIL, then NIL is returned.
As soon as FORM returns non-NIL the for is aborted with END-FOR and the non-NIL value is returned.```
• clause `(`

#### `UNTIL`

`FORM``)`
`When FORM returns non-NIL, END-FOR is called.`
• clause `(`

#### `WHILE`

`FORM``)`
`When FORM returns NIL, END-FOR is called.`
• generic `(`

#### `END`

`ITERATOR``)`
```Ends the iterator and performs potential cleanup.

You should always call this function with your iterator object once you are done to ensure
proper termination.```
• generic `(`

#### `HAS-MORE`

`ITERATOR``)`
`Returns a generalised boolean indicating whether the iterator has more items or not.`
• generic `(`

#### `MAKE-ITERATOR`

```OBJECT &KEY LIMIT BUFFER-SIZE ELEMENT-TYPE CLOSE-STREAM START &ALLOW-OTHER-KEYS````)`
`Create an iterator object for the given type of object.`
• generic `(`

#### `NEXT`

`ITERATOR``)`
```Advances the iterator by one item and returns the new item.

The behaviour is undefined if the iterator does not have more items.

See HAS-MORE```
• macro `(`

#### `DEFINE-ACCUMULATION-BINDING`

`NAME (VAR &REST ARGS) &BODY BODY``)`
```Defines a binding for an accumulator.

This is identical to DEFINE-FORM-BINDING with the exception that the
secondary value is set to a (RETURN-FOR var) for you, meaning the
variable's contents are returned from the FOR upon normal termination.

See DEFINE-FORM-BINDING```
• macro `(`

#### `DEFINE-ALIAS-BINDING`

`NAME REFERENCED-BINDING-NAME``)`
```Defines an alias for a binding.

See BINDING```
• macro `(`

#### `DEFINE-DIRECT-BINDING`

`NAME ARGS &BODY BODY``)`
```Defines a binding function.

Binding functions can return three values:

1. A single "surrounding form" that will go around the resulting loop. If you
require multiple surrounding forms, you can use WITH-INTERLEAVING.
2. A form to run during each iteration. They will be run before any body forms.
3. A form whose value is returned by the FOR.

The arguments that the function receives are directly translated from the
respective binding expression. One argument will always be passed in the
very least: the variable specified for the binding.

Note that a binding function receives its arguments as literals and thus must
process them like a macro would (destructive operations are bad juju).

Also note that unlike normal functions, the &environment lambda-list argument
is available and its value will be passed on from the calling FOR macro.

See BINDING
See REMOVE-BINDING```
• macro `(`

#### `DEFINE-FORM-BINDING`

`NAME (VAR &REST ARGS) &BODY BODY``)`
```Defines a binding that receives its arguments as literals.

&AUX variables in the ARGS lambda-list receive special treatment: they are
bound to gensyms within the definition body. Their value is only evaluated
and set within the expanded binding. This means that &AUX variables give you a
convenient way to introduce necessary helper variables to the expanded binding.
References to other AUX variables or the VAR are automatically rewritten to
the appropriate gensym.

VAR can also accept a default value, which receives the same semantic treatment
as &AUX variables do, with the exception that it is always the last binding to
be evaluated in the resulting expansion, meaning every other &AUX variable can
be referenced.

The primary value returned must be the form to be evaluated on each iteration.
A secondary value may be returned, which is a form to be evaluated when the
loop ends normally.

See DEFINE-DIRECT-BINDING
See DEFINE-VALUE-BINDING```
• macro `(`

#### `DEFINE-FORM-SYMBOL-MACRO-BINDING`

`NAME (VAR &REST ARGS) &BODY BODY``)`
```Defines a binding that receives its arguments as literals and treats the VAR as a symbol-macro.

This is the exact same as DEFINE-FORM-BINDING with the exception that the
VAR is translated into a symbol-macro binding. Its value is still translated
accordingly to make sure references to AUX variables stay intact.

See DEFINE-FORM-BINDING```
• macro `(`

#### `DEFINE-VALUE-BINDING`

`NAME (VAR &REST ARGS) &BODY BODY``)`
```Defines a binding that receives its arguments as values.

The treatment of all arguments in the ARGS lambda-list is as follows:
Within the definition body, they are bound to gensyms. Upon expansion of the
binding, each variable is expanded to a variable binding with the respective
value that was passed to the binding definition. Special exception is made for
the present-p optional variables that can be specified for optional or key
arguments, which are bound as usual in the definition body such that expansion
may be aware of which parameters were passed. In essence, you can interpret all
arguments as if treated by ONCE-ONLY.

&AUX variables in the args lambda-list receive special treatment: they are
bound to gensyms within the definition body. Their value is only evaluated
and set within the expanded binding. This means that AUX variables give you a
convenient way to introduce necessary helper variables to the expanded binding.
References to other arguments or the VAR are automatically rewritten to
the appropriate gensym.

VAR can also accept a default value, which receives the same semantic treatment
as &AUX variables do, with the exception that it is always the last binding to
be evaluated in the resulting expansion, meaning every other argument can
be referenced.

The primary value returned must be the form to be evaluated on each iteration.
A secondary value may be returned, which is a form to be evaluated when the
loop ends normally.

See DEFINE-FORM-BINDING
See DEFINE-DIRECT-BINDING```
• macro `(`

#### `DEFINE-VALUE-SYMBOL-MACRO-BINDING`

`NAME (VAR &REST ARGS) &BODY BODY``)`
```Defines a binding that receives its arguments as values and treats the VAR as a symbol-macro.

This is the exact same as DEFINE-VALUE-BINDING with the exception that the
VAR is translated into a symbol-macro binding. Its value is still translated
accordingly to make sure references to arguments stay intact.

See DEFINE-VALUE-BINDING```
• macro `(`

#### `FOR`

`BINDINGS &BODY BODY``)`
```Loops the body with the given bindings established.

Each binding should have the form (var binding-type args*)

Sometimes a var can be either a single symbol denoting a variable, or a
lambda-list to which the result is destructured and bound via UPDATE.
The support thereof depends on the binding construct.

Within the body, special iteration clauses may be present. A clause must appear
at the "top-level" of the body and cannot appear as a macro-expansion.

If the loop is terminated normally by END-FOR then multiple values may be returned
depending on how many bindings or clauses are present that want to return values.
The order of the values is as follows: the clause values are returned in the
order that the clauses appear in the body, followed by the binding values in the
order of the binding expressions.

The loop may also be terminated abnormally by a direct call to RETURN-FOR or RETURN.

See UPDATE
See BINDING
See CLAUSE
See END-FOR
See SKIP-FOR
See RETURN-FOR
See WITH-FOR-TAGBODY
See WITH-FOR-BLOCK
See CONVERT-BINDINGS
See CONVERT-CLAUSES```
• macro `(`

#### `UNLESS`

`TEST &BODY FORMS``)`
```If the first argument is not true, the rest of the forms are
evaluated as a PROGN.```
• macro `(`

#### `UPDATE`

`PLACE VALUE-FORM``)`
```Allows updating the PLACE with a new value.

Unlike just (setf place value), PLACE can also be a lambda-list where each variable
is then properly updated with the respective element from value list.```
• macro `(`

#### `WHEN`

`TEST &BODY FORMS``)`
```If the first argument is true, the rest of the forms are
evaluated as a PROGN.```
• macro `(`

#### `WITH-INTERLEAVING`

`&BODY BODY``)`
```Interleave the body forms.

Essentially this means that the last form is appended to the form before it
and this is then appended to the form before that, and so on.```