Loops in Keyboard Macros
------------------------

The `Z <' (`calc-kbd-repeat') and `Z >' (`calc-kbd-end-repeat')
commands pop a number from the stack, which must be an integer, then
repeat the keystrokes between the brackets the specified number of
times.  If the integer is zero or negative, the body is skipped
altogether.  For example, `1 TAB Z < 2 * Z >' computes two to a
nonnegative integer power.  First, we push 1 on the stack and then
swap the integer argument back to the top.  The `Z <' pops that
argument leaving the 1 back on top of the stack.  Then, we repeat a
multiply-by-two step however many times.

Once again, the keyboard macro is executed as it is being entered.  In
this case it is especially important to set up reasonable initial
conditions before making the definition: Suppose the integer 1000 just
happened to be sitting on the stack before we typed the above
definition!  Another approach is to enter a harmless dummy definition
for the macro, then go back and edit in the real one with a `Z E'
command.  Yet another approach is to type the macro as written-out
keystroke names in a buffer, then use `M-# m' (`read-kbd-macro') to
read the macro.

The `Z /' (`calc-kbd-break') command allows you to break out of a
keyboard macro loop prematurely.  It pops an object from the stack; if
that object is true (a non-zero number), control jumps out of the
innermost enclosing `Z <' ... `Z >' loop and continues after the `Z
>'.  If the object is false, the `Z /' has no effect.  Thus `COND Z /'
is similar to `if (COND) break;' in the C language.

The `Z (' (`calc-kbd-for') and `Z )' (`calc-kbd-end-for') commands are
similar to `Z <' and `Z >', except that they make the value of the
counter available inside the loop.  The general layout is `INIT FINAL
Z ( BODY STEP Z )'.  The `Z (' command pops initial and final values
from the stack.  It then creates a temporary internal counter and
initializes it with the value INIT.  The `Z (' command then repeatedly
pushes the counter value onto the stack and executes BODY and STEP,
adding STEP to the counter each time until the loop finishes.

By default, the loop finishes when the counter becomes greater than
(or less than) FINAL, assuming INITIAL is less than (greater than)
FINAL.  If INITIAL is equal to FINAL, the body executes exactly once.
The body of the loop always executes at least once.  For example, `0 1
10 Z ( 2 ^ + 1 Z )' computes the sum of the squares of the integers
from 1 to 10, in steps of 1.

If you give a numeric prefix argument of 1 to `Z (', the loop is
forced to use upward-counting conventions.  In this case, if INITIAL
is greater than FINAL the body will not be executed at all.  Note that
STEP may still be negative in this loop; the prefix argument merely
constrains the loop-finished test.  Likewise, a prefix argument of -1
forces downward-counting conventions.

The `Z {' (`calc-kbd-loop') and `Z }' (`calc-kbd-end-loop') commands
are similar to `Z <' and `Z >', except that they do not pop a count
from the stack--they effectively create an infinite loop.  Every `Z {'
... `Z }' loop ought to include at least one `Z /' to make sure the
loop doesn't run forever.  (If any error message occurs which causes
Emacs to beep, the keyboard macro will also be halted; this is a
standard feature of Emacs.  You can also generally press `C-g' to halt
a running keyboard macro, although not all versions of Unix support
this feature.)

The conditional and looping constructs are not actually tied to
keyboard macros, but they are most often used in that context.  For
example, the keystrokes `10 Z < 23 RET Z >' push ten copies of 23 onto
the stack.  This can be typed "live" just as easily as in a macro
definition.

See Conditionals in Macros, for some additional notes about
conditional and looping commands.