GNU Info
(cl)For Clauses
For Clauses
-----------
Most loops are governed by one or more `for' clauses. A `for' clause
simultaneously describes variables to be bound, how those variables are
to be stepped during the loop, and usually an end condition based on
those variables.
The word `as' is a synonym for the word `for'. This word is
followed by a variable name, then a word like `from' or `across' that
describes the kind of iteration desired. In Common Lisp, the phrase
`being the' sometimes precedes the type of iteration; in this package
both `being' and `the' are optional. The word `each' is a synonym for
`the', and the word that follows it may be singular or plural: `for x
being the elements of y' or `for x being each element of y'. Which
form you use is purely a matter of style.
The variable is bound around the loop as if by `let':
(setq i 'happy)
(loop for i from 1 to 10 do (do-something-with i))
i
=> happy
`for VAR from EXPR1 to EXPR2 by EXPR3'
This type of `for' clause creates a counting loop. Each of the
three sub-terms is optional, though there must be at least one
term so that the clause is marked as a counting clause.
The three expressions are the starting value, the ending value, and
the step value, respectively, of the variable. The loop counts
upwards by default (EXPR3 must be positive), from EXPR1 to EXPR2
inclusively. If you omit the `from' term, the loop counts from
zero; if you omit the `to' term, the loop counts forever without
stopping (unless stopped by some other loop clause, of course); if
you omit the `by' term, the loop counts in steps of one.
You can replace the word `from' with `upfrom' or `downfrom' to
indicate the direction of the loop. Likewise, you can replace
`to' with `upto' or `downto'. For example, `for x from 5 downto
1' executes five times with `x' taking on the integers from 5 down
to 1 in turn. Also, you can replace `to' with `below' or `above',
which are like `upto' and `downto' respectively except that they
are exclusive rather than inclusive limits:
(loop for x to 10 collect x)
=> (0 1 2 3 4 5 6 7 8 9 10)
(loop for x below 10 collect x)
=> (0 1 2 3 4 5 6 7 8 9)
The `by' value is always positive, even for downward-counting
loops. Some sort of `from' value is required for downward loops;
`for x downto 5' is not a legal loop clause all by itself.
`for VAR in LIST by FUNCTION'
This clause iterates VAR over all the elements of LIST, in turn.
If you specify the `by' term, then FUNCTION is used to traverse
the list instead of `cdr'; it must be a function taking one
argument. For example:
(loop for x in '(1 2 3 4 5 6) collect (* x x))
=> (1 4 9 16 25 36)
(loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
=> (1 9 25)
`for VAR on LIST by FUNCTION'
This clause iterates VAR over all the cons cells of LIST.
(loop for x on '(1 2 3 4) collect x)
=> ((1 2 3 4) (2 3 4) (3 4) (4))
With `by', there is no real reason that the `on' expression must
be a list. For example:
(loop for x on first-animal by 'next-animal collect x)
where `(next-animal x)' takes an "animal" X and returns the next
in the (assumed) sequence of animals, or `nil' if X was the last
animal in the sequence.
`for VAR in-ref LIST by FUNCTION'
This is like a regular `in' clause, but VAR becomes a `setf'-able
"reference" onto the elements of the list rather than just a
temporary variable. For example,
(loop for x in-ref my-list do (incf x))
increments every element of `my-list' in place. This clause is an
extension to standard Common Lisp.
`for VAR across ARRAY'
This clause iterates VAR over all the elements of ARRAY, which may
be a vector or a string.
(loop for x across "aeiou"
do (use-vowel (char-to-string x)))
`for VAR across-ref ARRAY'
This clause iterates over an array, with VAR a `setf'-able
reference onto the elements; see `in-ref' above.
`for VAR being the elements of SEQUENCE'
This clause iterates over the elements of SEQUENCE, which may be a
list, vector, or string. Since the type must be determined at
run-time, this is somewhat less efficient than `in' or `across'.
The clause may be followed by the additional term `using (index
VAR2)' to cause VAR2 to be bound to the successive indices
(starting at 0) of the elements.
This clause type is taken from older versions of the `loop' macro,
and is not present in modern Common Lisp. The `using (sequence
...)' term of the older macros is not supported.
`for VAR being the elements of-ref SEQUENCE'
This clause iterates over a sequence, with VAR a `setf'-able
reference onto the elements; see `in-ref' above.
`for VAR being the symbols [of OBARRAY]'
This clause iterates over symbols, either over all interned symbols
or over all symbols in OBARRAY. The loop is executed with VAR
bound to each symbol in turn. The symbols are visited in an
unspecified order.
As an example,
(loop for sym being the symbols
when (fboundp sym)
when (string-match "^map" (symbol-name sym))
collect sym)
returns a list of all the functions whose names begin with `map'.
The Common Lisp words `external-symbols' and `present-symbols' are
also recognized but are equivalent to `symbols' in Emacs Lisp.
Due to a minor implementation restriction, it will not work to have
more than one `for' clause iterating over symbols, hash tables,
keymaps, overlays, or intervals in a given `loop'. Fortunately,
it would rarely if ever be useful to do so. It _is_ legal to mix
one of these types of clauses with other clauses like `for ... to'
or `while'.
`for VAR being the hash-keys of HASH-TABLE'
This clause iterates over the entries in HASH-TABLE. For each
hash table entry, VAR is bound to the entry's key. If you write
`the hash-values' instead, VAR is bound to the values of the
entries. The clause may be followed by the additional term `using
(hash-values VAR2)' (where `hash-values' is the opposite word of
the word following `the') to cause VAR and VAR2 to be bound to the
two parts of each hash table entry.
`for VAR being the key-codes of KEYMAP'
This clause iterates over the entries in KEYMAP. The iteration
does not enter nested keymaps or inherited (parent) keymaps. You
can use `the key-bindings' to access the commands bound to the
keys rather than the key codes, and you can add a `using' clause
to access both the codes and the bindings together.
`for VAR being the key-seqs of KEYMAP'
This clause iterates over all key sequences defined by KEYMAP and
its nested keymaps, where VAR takes on values which are vectors.
The strings or vectors are reused for each iteration, so you must
copy them if you wish to keep them permanently. You can add a
`using (key-bindings ...)' clause to get the command bindings as
well.
`for VAR being the overlays [of BUFFER] ...'
This clause iterates over the "overlays" of a buffer (the clause
`extents' is synonymous with `overlays'). If the `of' term is
omitted, the current buffer is used. This clause also accepts
optional `from POS' and `to POS' terms, limiting the clause to
overlays which overlap the specified region.
`for VAR being the intervals [of BUFFER] ...'
This clause iterates over all intervals of a buffer with constant
text properties. The variable VAR will be bound to conses of
start and end positions, where one start position is always equal
to the previous end position. The clause allows `of', `from',
`to', and `property' terms, where the latter term restricts the
search to just the specified property. The `of' term may specify
either a buffer or a string.
`for VAR being the frames'
This clause iterates over all frames, i.e., X window system windows
open on Emacs files. The clause `screens' is a synonym for
`frames'. The frames are visited in `next-frame' order starting
from `selected-frame'.
`for VAR being the windows [of FRAME]'
This clause iterates over the windows (in the Emacs sense) of the
current frame, or of the specified FRAME.
`for VAR being the buffers'
This clause iterates over all buffers in Emacs. It is equivalent
to `for VAR in (buffer-list)'.
`for VAR = EXPR1 then EXPR2'
This clause does a general iteration. The first time through the
loop, VAR will be bound to EXPR1. On the second and successive
iterations it will be set by evaluating EXPR2 (which may refer to
the old value of VAR). For example, these two loops are
effectively the same:
(loop for x on my-list by 'cddr do ...)
(loop for x = my-list then (cddr x) while x do ...)
Note that this type of `for' clause does not imply any sort of
terminating condition; the above example combines it with a
`while' clause to tell when to end the loop.
If you omit the `then' term, EXPR1 is used both for the initial
setting and for successive settings:
(loop for x = (random) when (> x 0) return x)
This loop keeps taking random numbers from the `(random)' function
until it gets a positive one, which it then returns.
If you include several `for' clauses in a row, they are treated
sequentially (as if by `let*' and `setq'). You can instead use the
word `and' to link the clauses, in which case they are processed in
parallel (as if by `let' and `psetq').
(loop for x below 5 for y = nil then x collect (list x y))
=> ((0 nil) (1 1) (2 2) (3 3) (4 4))
(loop for x below 5 and y = nil then x collect (list x y))
=> ((0 nil) (1 0) (2 1) (3 2) (4 3))
In the first loop, `y' is set based on the value of `x' that was just
set by the previous clause; in the second loop, `x' and `y' are set
simultaneously so `y' is set based on the value of `x' left over from
the previous time through the loop.
Another feature of the `loop' macro is "destructuring", similar in
concept to the destructuring provided by `defmacro'. The VAR part of
any `for' clause can be given as a list of variables instead of a
single variable. The values produced during loop execution must be
lists; the values in the lists are stored in the corresponding
variables.
(loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
=> (5 9 13)
In loop destructuring, if there are more values than variables the
trailing values are ignored, and if there are more variables than
values the trailing variables get the value `nil'. If `nil' is used as
a variable name, the corresponding values are ignored. Destructuring
may be nested, and dotted lists of variables like `(x . y)' are allowed.
automatically generated by info2www version 1.2.2.9