Next: , Previous: Writing Drivers, Up: Rolling Your Own

7.3 Extensibility Aids

This section documents assorted features that may be of use in extending iterate.

— Unexported Variable: *result-var*

Holds the variable that is used to return a value as a result of the iterate form. You may examine this and use it in a with clause, but you should not change it.

— Macro: defsynonym syn word

Makes syn a synonym for the existing iterate keyword word. Only the first word in each clause can have synonyms.

— Macro: defclause-sequence element-name index-name &key access-fn size-fn sequence-type element-type element-doc-string index-doc-string

Provides a simple way to define sequence clauses. Generates two clauses, one for iterating over the sequence's elements, the other for iterating over its indices. The first symbol of both clauses will have print-name for. element-name and index-name should be symbols. element-name is the second keyword of the element iterator (typically of the form in-sequence-type), and index-name is the second keyword of the index-iterator (typically of the form index-of-sequence-type). Either name may be nil, in which case the corresponding clause is not defined. If both symbols are supplied, they should be in the same package. The for that begins the clauses will be in this package.

access-fn is the function to be used to access elements of the sequence in the element iterator. The function should take two arguments, a sequence and an index, and return the appropriate element. size-fn should denote a function of one argument, a sequence, that returns its size. Both access-fn and size-fn are required for the element iterator, but only size-fn is needed for the index iterator.

The sequence-type and element-type keywords are used to suggest types for the variables used to hold the sequence and the sequence elements, respectively. The usual rules about iterate's treatment of variable type declarations apply (see Types and Declarations).

element-doc-string and index-doc-string are the documentation strings, for use with display-iterate-clauses.

The generated element-iterator performs destructuring on the element variable.

As an example, the above for... in-whole-vector example could have been written:

       (defclause-sequence IN-WHOLE-VECTOR INDEX-OF-WHOLE-VECTOR
         :access-fn 'aref
         :size-fn (lambda (v) (array-dimension v 0))
         :sequence-type 'vector
         :element-type t
         :element-doc-string "Elements of a vector, disregarding fill-pointer"
         :index-doc-string  "Indices of vector, disregarding fill-pointer")