The for Reference Manual

Table of Contents

The for Reference Manual

This is the for Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Dec 02 10:16:22 2019 GMT+0.

1 Introduction

About For

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))
         ,var (cdr ,head)))

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))
         A (CDR #:HEAD))
   (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

2 Systems

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

2.1 for

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://Shinmera.github.io/for/

Source Control

(:git "https://github.com/shinmera/for.git")

Bug Tracker

https://github.com/Shinmera/for/issues

License

zlib

Description

An extensible iteration macro library.

Version

1.0.0

Dependencies

• documentation-utils
• lambda-fiddle
• form-fiddle

Source

for.asd (file)

Components

• package.lisp (file)
• toolkit.lisp (file)
• binding.lisp (file)
• clause.lisp (file)
• for.lisp (file)
• iterator.lisp (file)
• standard.lisp (file)
• documentation.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 for.asd

Location

for.asd

Systems

for (system)

3.1.2 for/package.lisp

Parent

for (system)

Location

package.lisp

Packages

• for-iterator
• for-minimal
• for

3.1.3 for/toolkit.lisp

Dependency

package.lisp (file)

Parent

for (system)

Location

toolkit.lisp

Exported Definitions

• hash-table-iterator (function)
• package-iterator (function)
• update (macro)
• with-interleaving (macro)

Internal Definitions

• collect-for-values (function)
• copy-list* (function)
• delist (function)
• enlist (function)
• replace-lambda-vars (function)
• unwind-protect* (macro)
• values* (macro)

3.1.4 for/binding.lisp

Dependency

toolkit.lisp (file)

Parent

for (system)

Location

binding.lisp

Exported Definitions

• binding (function)
• (setf binding) (function)
• define-accumulation-binding (macro)
• define-alias-binding (macro)
• define-direct-binding (macro)
• define-form-binding (macro)
• define-form-symbol-macro-binding (macro)
• define-value-binding (macro)
• define-value-symbol-macro-binding (macro)
• remove-binding (function)

Internal Definitions

• *bindings* (special variable)
• bindings-for-gens (function)
• compute-binding-parts (function)
• compute-declaration-parts (function)
• convert-bindings (function)
• emit-binding-definition (function)
• normalize-declaration-inner (function)
• normalize-declarations (function)
• translate-form-vars (function)

3.1.5 for/clause.lisp

Dependency

binding.lisp (file)

Parent

for (system)

Location

clause.lisp

Exported Definitions

• clause (function)
• (setf clause) (function)
• remove-clause (function)

Internal Definitions

• *clauses* (special variable)
• convert-clauses (function)
• define-direct-clause (macro)
• define-simple-clause (macro)

3.1.6 for/for.lisp

Dependency

clause.lisp (file)

Parent

for (system)

Location

for.lisp

Exported Definitions

for (macro)

Internal Definitions

• *environment* (special variable)
• with-for-block (macro)
• with-for-tagbody (macro)

3.1.7 for/iterator.lisp

Dependency

for.lisp (file)

Parent

for (system)

Location

iterator.lisp

Exported Definitions

• array-iterator (class)
• buffer (method)
• (setf buffer) (method)
• buffer (method)
• (setf buffer) (method)
• close-stream (method)
• (setf close-stream) (method)
• close-stream (method)
• (setf close-stream) (method)
• current (generic function)
• current (method)
• (setf current) (method)
• (setf current) (generic function)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• directory-iterator (class)
• end (generic function)
• end (method)
• end (method)
• end (method)
• has-more (generic function)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• hash-table-iterator (class)
• index (method)
• (setf index) (method)
• iterator (class)
• limit (method)
• limit (method)
• (setf limit) (method)
• list-iterator (class)
• make-iterator (generic function)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• next (generic function)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• object (method)
• (setf object) (method)
• package-iterator (class)
• prefetch (method)
• (setf prefetch) (method)
• prefetch (method)
• (setf prefetch) (method)
• random-iterator (class)
• start (method)
• (setf start) (method)
• stream-iterator (class)
• stream-line-iterator (class)
• total-length (method)
• (setf total-length) (method)
• vector-iterator (class)

3.1.8 for/standard.lisp

Dependency

iterator.lisp (file)

Parent

for (system)

Location

standard.lisp

Internal Definitions

• *unbound* (special variable)
• remove-bindings (function)

3.1.9 for/documentation.lisp

Dependency

standard.lisp (file)

Parent

for (system)

Location

documentation.lisp

4 Packages

Packages are listed by definition order.

4.1 for-iterator

Source

package.lisp (file)

Nickname

org.shirakumo.for.iterator

Use List

common-lisp

Used By List

for

Exported Definitions

• array-iterator (class)
• buffer (generic function)
• buffer (method)
• (setf buffer) (method)
• buffer (method)
• (setf buffer) (method)
• (setf buffer) (generic function)
• close-stream (generic function)
• close-stream (method)
• (setf close-stream) (method)
• close-stream (method)
• (setf close-stream) (method)
• (setf close-stream) (generic function)
• current (generic function)
• current (method)
• (setf current) (method)
• (setf current) (generic function)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• directory-iterator (class)
• end (generic function)
• end (method)
• end (method)
• end (method)
• has-more (generic function)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• has-more (method)
• hash-table-iterator (function)
• hash-table-iterator (class)
• index (generic function)
• index (method)
• (setf index) (method)
• (setf index) (generic function)
• iterator (class)
• limit (generic function)
• limit (method)
• limit (method)
• (setf limit) (method)
• (setf limit) (generic function)
• list-iterator (class)
• make-iterator (generic function)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• make-iterator (method)
• next (generic function)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• next (method)
• object (generic function)
• object (method)
• (setf object) (method)
• (setf object) (generic function)
• package-iterator (function)
• package-iterator (class)
• prefetch (generic function)
• prefetch (method)
• (setf prefetch) (method)
• prefetch (method)
• (setf prefetch) (method)
• (setf prefetch) (generic function)
• random-iterator (class)
• start (generic function)
• start (method)
• (setf start) (method)
• (setf start) (generic function)
• stream-iterator (class)
• stream-line-iterator (class)
• total-length (generic function)
• total-length (method)
• (setf total-length) (method)
• (setf total-length) (generic function)
• vector-iterator (class)

4.2 for-minimal

Source

package.lisp (file)

Nickname

org.shirakumo.for.minimal

Use List

common-lisp

Used By List

for

Exported Definitions

• for (macro)
• update (macro)

4.3 for

Source

package.lisp (file)

Nickname

org.shirakumo.for

Use List

• for-minimal
• for-iterator
• common-lisp

Exported Definitions

• binding (function)
• (setf binding) (function)
• clause (function)
• (setf clause) (function)
• define-accumulation-binding (macro)
• define-alias-binding (macro)
• define-direct-binding (macro)
• define-form-binding (macro)
• define-form-symbol-macro-binding (macro)
• define-value-binding (macro)
• define-value-symbol-macro-binding (macro)
• remove-binding (function)
• remove-clause (function)
• with-interleaving (macro)

Internal Definitions

• *bindings* (special variable)
• *clauses* (special variable)
• *environment* (special variable)
• *unbound* (special variable)
• bindings-for-gens (function)
• collect-for-values (function)
• compute-binding-parts (function)
• compute-declaration-parts (function)
• convert-bindings (function)
• convert-clauses (function)
• copy-list* (function)
• define-direct-clause (macro)
• define-simple-clause (macro)
• delist (function)
• emit-binding-definition (function)
• enlist (function)
• normalize-declaration-inner (function)
• normalize-declarations (function)
• remove-bindings (function)
• replace-lambda-vars (function)
• translate-form-vars (function)
• unwind-protect* (macro)
• values* (macro)
• with-for-block (macro)
• with-for-tagbody (macro)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

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

Package

for

Source

binding.lisp (file)

Macro: define-alias-binding NAME REFERENCED-BINDING-NAME

Defines an alias for a binding.

See BINDING

Package

for

Source

binding.lisp (file)

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

Package

for

Source

binding.lisp (file)

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

Package

for

Source

binding.lisp (file)

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

Package

for

Source

binding.lisp (file)

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

Package

for

Source

binding.lisp (file)

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

Package

for

Source

binding.lisp (file)

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

Package

for-minimal

Source

for.lisp (file)

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.

Package

for-minimal

Source

toolkit.lisp (file)

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.

Package

for

Source

toolkit.lisp (file)

5.1.2 Functions

Function: 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

Package

for

Source

binding.lisp (file)

Writer

(setf binding) (function)

Function: (setf binding) FUNC NAME

Package

for

Source

binding.lisp (file)

Reader

binding (function)

Function: 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

Package

for

Source

clause.lisp (file)

Writer

(setf clause) (function)

Function: (setf clause) FUNC NAME

Package

for

Source

clause.lisp (file)

Reader

clause (function)

Function: hash-table-iterator TABLE

Returns a function to iterate over a hash-table.

See CL:WITH-HASH-TABLE-ITERATOR

Package

for-iterator

Source

toolkit.lisp (file)

Function: package-iterator PACKAGE STATUSES

Returns a function to iterate over a package’s symbols.

See CL:WITH-PACKAGE-ITERATOR

Package

for-iterator

Source

toolkit.lisp (file)

Function: remove-binding NAME

Removes the given binding function.

See BINDING

Package

for

Source

binding.lisp (file)

Function: remove-clause NAME

Removes the given clause function.

See CLAUSE

Package

for

Source

clause.lisp (file)

5.1.3 Generic functions

Generic Function: buffer OBJECT

Accessor to the stream-iterator’s buffer.

See STREAM-ITERATOR

Package

for-iterator

Writer

(setf buffer) (generic function)

Methods

Method: buffer (STREAM-LINE-ITERATOR stream-line-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Method: buffer (STREAM-ITERATOR stream-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Generic Function: (setf buffer) NEW-VALUE OBJECT

Package

for-iterator

Reader

buffer (generic function)

Methods

Method: (setf buffer) NEW-VALUE (STREAM-LINE-ITERATOR stream-line-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Method: (setf buffer) NEW-VALUE (STREAM-ITERATOR stream-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Generic Function: close-stream OBJECT

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

See STREAM-ITERATOR
See STREAM-LINE-ITERATOR

Package

for-iterator

Writer

(setf close-stream) (generic function)

Methods

Method: close-stream (STREAM-LINE-ITERATOR stream-line-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Method: close-stream (STREAM-ITERATOR stream-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Generic Function: (setf close-stream) NEW-VALUE OBJECT

Package

for-iterator

Reader

close-stream (generic function)

Methods

Method: (setf close-stream) NEW-VALUE (STREAM-LINE-ITERATOR stream-line-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Method: (setf close-stream) NEW-VALUE (STREAM-ITERATOR stream-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Generic Function: 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

Package

for-iterator

Source

iterator.lisp (file)

Writer

(setf current) (generic function)

Methods

Method: current (ITERATOR iterator)

automatically generated reader method

Generic Function: (setf current) VALUE ITERATOR

Package

for-iterator

Source

iterator.lisp (file)

Reader

current (generic function)

Methods

Method: (setf current) NEW-VALUE (ITERATOR iterator)

automatically generated writer method

Method: (setf current) VALUE (ITERATOR hash-table-iterator)

Method: (setf current) (VALUE sequence) (ITERATOR stream-iterator)

Method: (setf current) (VALUE character) (ITERATOR stream-iterator)

Method: (setf current) (VALUE integer) (ITERATOR stream-iterator)

Method: (setf current) VALUE (ITERATOR array-iterator)

Method: (setf current) VALUE (ITERATOR vector-iterator)

Method: (setf current) VALUE (ITERATOR list-iterator)

Generic Function: 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.

Package

for-iterator

Source

iterator.lisp (file)

Methods

Method: end (ITERATOR stream-line-iterator)

Method: end (ITERATOR stream-iterator)

Method: end (ITERATOR iterator)

Generic Function: has-more ITERATOR

Returns a generalised boolean indicating whether the iterator has more items or not.

Package

for-iterator

Source

iterator.lisp (file)

Methods

Method: has-more (ITERATOR hash-table-iterator)

Method: has-more (ITERATOR package-iterator)

Method: has-more (ITERATOR random-iterator)

Method: has-more (ITERATOR stream-line-iterator)

Method: has-more (ITERATOR stream-iterator)

Method: has-more (ITERATOR array-iterator)

Method: has-more (ITERATOR vector-iterator)

Method: has-more (ITERATOR list-iterator)

Generic Function: index OBJECT

Accessor to the current index within the buffer.

See STREAM-ITERATOR

Package

for-iterator

Writer

(setf index) (generic function)

Methods

Method: index (STREAM-ITERATOR stream-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Generic Function: (setf index) NEW-VALUE OBJECT

Package

for-iterator

Reader

index (generic function)

Methods

Method: (setf index) NEW-VALUE (STREAM-ITERATOR stream-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Generic Function: limit OBJECT

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

See STREAM-ITERATOR

Package

for-iterator

Writer

(setf limit) (generic function)

Methods

Method: limit (RANDOM-ITERATOR random-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Method: limit (STREAM-ITERATOR stream-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Generic Function: (setf limit) NEW-VALUE OBJECT

Package

for-iterator

Reader

limit (generic function)

Methods

Method: (setf limit) NEW-VALUE (STREAM-ITERATOR stream-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Generic Function: 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.

Package

for-iterator

Source

iterator.lisp (file)

Methods

Method: make-iterator (HASH-TABLE hash-table) &key

Method: make-iterator (PACKAGE package) &key

Method: make-iterator (RANDOM-STATE random-state) &key LIMIT

Method: make-iterator (PATHNAME pathname) &key BUFFER-SIZE ELEMENT-TYPE

Method: make-iterator (STREAM stream) &key BUFFER-SIZE CLOSE-STREAM

Method: make-iterator (ARRAY array) &key START

Method: make-iterator (VECTOR vector) &key START

Method: make-iterator (LIST list) &key

Generic Function: 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

Package

for-iterator

Source

iterator.lisp (file)

Methods

Method: next (ITERATOR hash-table-iterator)

Method: next (ITERATOR package-iterator)

Method: next (ITERATOR random-iterator)

Method: next (ITERATOR stream-line-iterator)

Method: next (ITERATOR stream-iterator)

Method: next (ITERATOR array-iterator)

Method: next (ITERATOR vector-iterator)

Method: next (ITERATOR list-iterator)

Method: next (ITERATOR iterator) around

Generic Function: 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

Package

for-iterator

Writer

(setf object) (generic function)

Methods

Method: object (ITERATOR iterator)

automatically generated reader method

Source

iterator.lisp (file)

Generic Function: (setf object) NEW-VALUE OBJECT

Package

for-iterator

Reader

object (generic function)

Methods

Method: (setf object) NEW-VALUE (ITERATOR iterator)

automatically generated writer method

Source

iterator.lisp (file)

Generic Function: 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

Package

for-iterator

Writer

(setf prefetch) (generic function)

Methods

Method: prefetch (HASH-TABLE-ITERATOR hash-table-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Method: prefetch (PACKAGE-ITERATOR package-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Generic Function: (setf prefetch) NEW-VALUE OBJECT

Package

for-iterator

Reader

prefetch (generic function)

Methods

Method: (setf prefetch) NEW-VALUE (HASH-TABLE-ITERATOR hash-table-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Method: (setf prefetch) NEW-VALUE (PACKAGE-ITERATOR package-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Generic Function: start OBJECT

Accessor to the index that points to the next element of the vector-iterator.

Package

for-iterator

Writer

(setf start) (generic function)

Methods

Method: start (VECTOR-ITERATOR vector-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Generic Function: (setf start) NEW-VALUE OBJECT

Package

for-iterator

Reader

start (generic function)

Methods

Method: (setf start) NEW-VALUE (VECTOR-ITERATOR vector-iterator)

automatically generated writer method

Source

iterator.lisp (file)

Generic Function: total-length OBJECT

Slot holding the array-total-size.

See ARRAY-ITERATOR

Package

for-iterator

Writer

(setf total-length) (generic function)

Methods

Method: total-length (ARRAY-ITERATOR array-iterator)

automatically generated reader method

Source

iterator.lisp (file)

Generic Function: (setf total-length) NEW-VALUE OBJECT

Package

for-iterator

Reader

total-length (generic function)

Methods

Method: (setf total-length) NEW-VALUE (ARRAY-ITERATOR array-iterator)

automatically generated writer method

Source

iterator.lisp (file)

5.1.4 Classes

Class: array-iterator ()

Iterator for general arrays.

Iteration is in row-major order.

Supports setting the current element.

See VECTOR-ITERATOR
See TOTAL-LENGTH

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

vector-iterator (class)

Direct methods

• (setf current) (method)
• next (method)
• has-more (method)
• initialize-instance (method)
• total-length (method)
• total-length (method)

Direct slots

Slot: total-length

Readers

total-length (generic function)

Writers

(setf total-length) (generic function)

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

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

list-iterator (class)

Direct methods

initialize-instance (method)

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

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

iterator (class)

Direct methods

• (setf current) (method)
• next (method)
• has-more (method)
• initialize-instance (method)
• prefetch (method)
• prefetch (method)

Direct slots

Slot: prefetch

Readers

prefetch (generic function)

Writers

(setf prefetch) (generic function)

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

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• list-iterator (class)
• vector-iterator (class)
• stream-iterator (class)
• stream-line-iterator (class)
• random-iterator (class)
• package-iterator (class)
• hash-table-iterator (class)

Direct methods

• end (method)
• next (method)
• current (method)
• current (method)
• object (method)
• object (method)

Direct slots

Slot: object

Initargs

:object

Readers

object (generic function)

Writers

(setf object) (generic function)

Slot: current

Readers

current (generic function)

Writers

(setf current) (generic function)

Class: list-iterator ()

Iterator for proper lists.

Supports setting the current element.

See ITERATOR

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

iterator (class)

Direct subclasses

directory-iterator (class)

Direct methods

• (setf current) (method)
• next (method)
• has-more (method)
• initialize-instance (method)

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

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

iterator (class)

Direct methods

• next (method)
• has-more (method)
• initialize-instance (method)
• prefetch (method)
• prefetch (method)

Direct slots

Slot: prefetch

Readers

prefetch (generic function)

Writers

(setf prefetch) (generic function)

Direct Default Initargs

Initarg	Value
:status	(quote (:internal :external :inherited))

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

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

iterator (class)

Direct methods

• next (method)
• has-more (method)
• limit (method)

Direct slots

Slot: limit

Initargs

:limit

Readers

limit (generic function)

Direct Default Initargs

Initarg	Value
:limit	1.0

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

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

iterator (class)

Direct methods

• end (method)
• (setf current) (method)
• (setf current) (method)
• (setf current) (method)
• next (method)
• has-more (method)
• initialize-instance (method)
• close-stream (method)
• close-stream (method)
• limit (method)
• limit (method)
• index (method)
• index (method)
• buffer (method)
• buffer (method)

Direct slots

Slot: buffer

Readers

buffer (generic function)

Writers

(setf buffer) (generic function)

Slot: index

Initform

1

Readers

index (generic function)

Writers

(setf index) (generic function)

Slot: limit

Initform

1

Readers

limit (generic function)

Writers

(setf limit) (generic function)

Slot: close-stream

Initargs

:close-stream

Readers

close-stream (generic function)

Writers

(setf close-stream) (generic function)

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

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

iterator (class)

Direct methods

• end (method)
• next (method)
• has-more (method)
• close-stream (method)
• close-stream (method)
• buffer (method)
• buffer (method)

Direct slots

Slot: buffer

Readers

buffer (generic function)

Writers

(setf buffer) (generic function)

Slot: close-stream

Initargs

:close-stream

Readers

close-stream (generic function)

Writers

(setf close-stream) (generic function)

Class: vector-iterator ()

Iterator for vectors.

Supports setting the current element.

See START
See ITERATOR

Package

for-iterator

Source

iterator.lisp (file)

Direct superclasses

iterator (class)

Direct subclasses

array-iterator (class)

Direct methods

• (setf current) (method)
• next (method)
• has-more (method)
• start (method)
• start (method)

Direct slots

Slot: start

Initargs

:start

Readers

start (generic function)

Writers

(setf start) (generic function)

Direct Default Initargs

Initarg	Value
:start	0

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *bindings*

Package

for

Source

binding.lisp (file)

Special Variable: *clauses*

Package

for

Source

clause.lisp (file)

Special Variable: *environment*

This variable will be bound to the environment object during the expansion of the FOR macro.

Package

for

Source

for.lisp (file)

Special Variable: *unbound*

Package

for

Source

standard.lisp (file)

5.2.2 Macros

Macro: define-direct-clause NAME ARGS &body BODY

Defines a clause function.

Clause 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.
3. A form whose value is returned by the FOR.

The arguments that the function receives are directly translated from the respective clause expression.

Note that a clause 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 CLAUSE
See REMOVE-CLAUSE

Package

for

Source

clause.lisp (file)

Macro: define-simple-clause NAME ARGS &body BODY

Defines a simple clause.

&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 clause. This means that AUX variables give you a convenient way to introduce necessary helper variables to the expanded clause. References to other &AUX are automatically rewritten to the appropriate gensym.

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-CLAUSE

Package

for

Source

clause.lisp (file)

Macro: unwind-protect* CLEANUP &body BODY

Package

for

Source

toolkit.lisp (file)

Macro: values* &rest VALUES

The same idea as LIST* except for values.

Package

for

Source

toolkit.lisp (file)

Macro: with-for-block () &body BODY

Wraps the body in a looping block.

This establishes a NIL block.

See RETURN-FOR

Package

for

Source

for.lisp (file)

Macro: with-for-tagbody BODY &body EXIT

Wraps the body in a looping tagbody, running the EXIT forms when the loop ends.

See END-FOR
See SKIP-FOR

Package

for

Source

for.lisp (file)

5.2.3 Functions

Function: bindings-for-gens AUX GENS

Package

for

Source

binding.lisp (file)

Function: collect-for-values EXPRESSIONS FUNCTION

Package

for

Source

toolkit.lisp (file)

Function: compute-binding-parts VAR VARS ARGS

Package

for

Source

binding.lisp (file)

Function: compute-declaration-parts BODY INNER-LET

Package

for

Source

binding.lisp (file)

Function: convert-bindings BINDINGS

Translates the given binding expressions into their respective parts.

Each binding must be a list of the following structure:

BINDING ::= (PLACE binding-type argument*)
PLACE ::= variable | lambda-list
variable — A symbol naming a variable to bind the result of the binding to. lambda-list — If the binding result is a list, destructure it by this lambda- list, binding the respective symbols.
binding-type — The type of binding determines how the PLACE is initialised and how it changes each iteration.
argument — An argument to the binding. Depending on the binding it may be evaluated once or in every iteration.

If an unknown binding is referenced, an error is signalled.

Returns three values:
1. A list of all surrounding forms
2. A list of all body forms
3. A list of all value forms

See BINDING

Package

for

Source

binding.lisp (file)

Function: convert-clauses FORMS

Translates the given body forms into their respective parts.

If a body form is noticed that matches a clause –by virtue of being a list and the first item thereof being a symbol that translates to a clause name– then it is replaced by the form computed by the clause function.

Returns three values:
1. A list of all surrounding forms
2. A list of all body forms
3. A list of all value forms

See CLAUSE

Package

for

Source

clause.lisp (file)

Function: copy-list* LIST

Same as COPY-LIST, but also returning the last cons of the new list as a second value.

Package

for

Source

toolkit.lisp (file)

Function: delist A &optional KEY

If A is a list, return the element that KEY retrieves.

Package

for

Source

toolkit.lisp (file)

Function: emit-binding-definition NAME VAR ARGS BODY &key EXTRA-VARS SYMBOL-MACRO-P

Package

for

Source

binding.lisp (file)

Function: enlist A &rest ELS

If A is not a list, turn it into one with the given ELS as further items.

Package

for

Source

toolkit.lisp (file)

Function: normalize-declaration-inner INNER

Package

for

Source

binding.lisp (file)

Function: normalize-declarations BODY

Package

for

Source

binding.lisp (file)

Function: remove-bindings BINDINGS FORM

Package

for

Source

standard.lisp (file)

Function: replace-lambda-vars LAMBDA-LIST VARS NEW-VARS

Replaces all VARS in LAMBDA-LIST with the NEW-VAR at the same position.

Package

for

Source

toolkit.lisp (file)

Function: translate-form-vars FORM FROM TO

Package

for

Source

binding.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables