Info Catalog cl: Blocks and Exits cl: Control Structure cl: Loop Facility

cl: Iteration

 
 4.6 Iteration
 =============
 
 The macros described here provide more sophisticated, high-level looping
 constructs to complement Emacs Lisp’s basic loop forms (
 (elisp)Iteration).
 
  -- Macro: cl-loop forms...
      This package supports both the simple, old-style meaning of ‘loop’
      and the extremely powerful and flexible feature known as the “Loop
      Facility” or “Loop Macro”.  This more advanced facility is
      discussed in the following section; Loop Facility.  The
      simple form of ‘loop’ is described here.
 
      If ‘cl-loop’ is followed by zero or more Lisp expressions, then
      ‘(cl-loop EXPRS...)’ simply creates an infinite loop executing the
      expressions over and over.  The loop is enclosed in an implicit
      ‘nil’ block.  Thus,
 
           (cl-loop (foo)  (if (no-more) (return 72))  (bar))
 
      is exactly equivalent to
 
           (cl-block nil (while t (foo)  (if (no-more) (return 72))  (bar)))
 
      If any of the expressions are plain symbols, the loop is instead
      interpreted as a Loop Macro specification as described later.
      (This is not a restriction in practice, since a plain symbol in the
      above notation would simply access and throw away the value of a
      variable.)
 
  -- Macro: cl-do (spec...) (end-test [result...]) forms...
      This macro creates a general iterative loop.  Each SPEC is of the
      form
 
           (VAR [INIT [STEP]])
 
      The loop works as follows: First, each VAR is bound to the
      associated INIT value as if by a ‘let’ form.  Then, in each
      iteration of the loop, the END-TEST is evaluated; if true, the loop
      is finished.  Otherwise, the body FORMS are evaluated, then each
      VAR is set to the associated STEP expression (as if by a ‘cl-psetq’
      form) and the next iteration begins.  Once the END-TEST becomes
      true, the RESULT forms are evaluated (with the VARs still bound to
      their values) to produce the result returned by ‘cl-do’.
 
      The entire ‘cl-do’ loop is enclosed in an implicit ‘nil’ block, so
      that you can use ‘(cl-return)’ to break out of the loop at any
      time.
 
      If there are no RESULT forms, the loop returns ‘nil’.  If a given
      VAR has no STEP form, it is bound to its INIT value but not
      otherwise modified during the ‘cl-do’ loop (unless the code
      explicitly modifies it); this case is just a shorthand for putting
      a ‘(let ((VAR INIT)) ...)’ around the loop.  If INIT is also
      omitted it defaults to ‘nil’, and in this case a plain ‘VAR’ can be
      used in place of ‘(VAR)’, again following the analogy with ‘let’.
 
      This example (from Steele) illustrates a loop that applies the
      function ‘f’ to successive pairs of values from the lists ‘foo’ and
      ‘bar’; it is equivalent to the call ‘(cl-mapcar 'f foo bar)’.  Note
      that this loop has no body FORMS at all, performing all its work as
      side effects of the rest of the loop.
 
           (cl-do ((x foo (cdr x))
                   (y bar (cdr y))
                   (z nil (cons (f (car x) (car y)) z)))
                ((or (null x) (null y))
                 (nreverse z)))
 
  -- Macro: cl-do* (spec...) (end-test [result...]) forms...
      This is to ‘cl-do’ what ‘let*’ is to ‘let’.  In particular, the
      initial values are bound as if by ‘let*’ rather than ‘let’, and the
      steps are assigned as if by ‘setq’ rather than ‘cl-psetq’.
 
      Here is another way to write the above loop:
 
           (cl-do* ((xp foo (cdr xp))
                    (yp bar (cdr yp))
                    (x (car xp) (car xp))
                    (y (car yp) (car yp))
                    z)
             ((or (null xp) (null yp))
              (nreverse z))
             (push (f x y) z))
 
  -- Macro: cl-dolist (var list [result]) forms...
      This is exactly like the standard Emacs Lisp macro ‘dolist’, but
      surrounds the loop with an implicit ‘nil’ block.
 
  -- Macro: cl-dotimes (var count [result]) forms...
      This is exactly like the standard Emacs Lisp macro ‘dotimes’, but
      surrounds the loop with an implicit ‘nil’ block.  The body is
      executed with VAR bound to the integers from zero (inclusive) to
      COUNT (exclusive), in turn.  Then the ‘result’ form is evaluated
      with VAR bound to the total number of iterations that were done
      (i.e., ‘(max 0 COUNT)’) to get the return value for the loop form.
 
  -- Macro: cl-do-symbols (var [obarray [result]]) forms...
      This loop iterates over all interned symbols.  If OBARRAY is
      specified and is not ‘nil’, it loops over all symbols in that
      obarray.  For each symbol, the body FORMS are evaluated with VAR
      bound to that symbol.  The symbols are visited in an unspecified
      order.  Afterward the RESULT form, if any, is evaluated (with VAR
      bound to ‘nil’) to get the return value.  The loop is surrounded by
      an implicit ‘nil’ block.
 
  -- Macro: cl-do-all-symbols (var [result]) forms...
      This is identical to ‘cl-do-symbols’ except that the OBARRAY
      argument is omitted; it always iterates over the default obarray.
 
    Mapping over Sequences, for some more functions for iterating
 over vectors or lists.
 

Info Catalog cl: Blocks and Exits cl: Control Structure cl: Loop Facility