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 C-x * 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 Keyboard Macros, for some additional notes about conditional and looping commands.