17.2.3 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 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.