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.

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)

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.

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.

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

This clause iterates over an array, with var a setf-able reference onto the elements; see in-ref above.

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.

This clause iterates over a sequence, with var a setf-able reference onto the elements; see in-ref above.

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.

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.

This clause iterates over the entries in keymap. In GNU Emacs 18 and 19, keymaps are either alists or vectors, and key-codes are integers or symbols. In Lucid Emacs 19, keymaps are a special new data type, and key-codes are symbols or lists of symbols. 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.

This clause iterates over all key sequences defined by keymap and its nested keymaps, where var takes on values which are strings in Emacs 18 or vectors in Emacs 19. 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.

This clause iterates over the Emacs 19 ``overlays'' or Lucid Emacs ``extents'' of a buffer (the clause extents is synonymous with overlays). Under Emacs 18, this clause iterates zero times. 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.

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. This clause is useful only in GNU Emacs 19; in other versions, all buffers and strings consist of a single interval.

This clause iterates over all frames, i.e., X window system windows open on Emacs files. This clause works only under Emacs 19. The clause screens is a synonym for frames. The frames are visited in next-frame order starting from selected-frame.

This clause iterates over the windows (in the Emacs sense) of the current frame, or of the specified frame. (In Emacs 18 there is only ever one frame, and the of term is not allowed there.)

This clause iterates over all buffers in Emacs. It is equivalent to `for var in (buffer-list)'.

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.