calc: Loops in Macros
18.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.
Conditionals in Macros, for some additional notes about
conditional and looping commands.
Info Catalog
calc: Conditionals in Macros
calc: Keyboard Macros
calc: Local Values in Macros