17.2.4 Local Values in Macros

Keyboard macros sometimes want to operate under known conditions without affecting surrounding conditions. For example, a keyboard macro may wish to turn on Fraction mode, or set a particular precision, independent of the user’s normal setting for those modes.

Macros also sometimes need to use local variables. Assignments to local variables inside the macro should not affect any variables outside the macro. The Z ` (calc-kbd-push) and Z ' (calc-kbd-pop) commands give you both of these capabilities.

When you type Z ` (with a grave accent), the values of various mode settings are saved away. The ten “quick” variables q0 through q9 are also saved. When you type Z ' (with an apostrophe), these values are restored. Pairs of Z ` and Z ' commands may be nested.

If a keyboard macro halts due to an error in between a Z ` and a Z ', the saved values will be restored correctly even though the macro never reaches the Z ' command. Thus you can use Z ` and Z ' without having to worry about what happens in exceptional conditions.

If you type Z ` “live” (not in a keyboard macro), Calc puts you into a “recursive edit.” You can tell you are in a recursive edit because there will be extra square brackets in the mode line, as in ‘[(Calculator)]’. These brackets will go away when you type the matching Z ' command. The modes and quick variables will be saved and restored in just the same way as if actual keyboard macros were involved.

The modes saved by Z ` and Z ' are the current precision and binary word size, the angular mode (Deg, Rad, or HMS), the simplification mode, Algebraic mode, Symbolic mode, Infinite mode, Matrix or Scalar mode, Fraction mode, and the current complex mode (Polar or Rectangular). The ten “quick” variables’ values (or lack thereof) are also saved.

Most mode-setting commands act as toggles, but with a numeric prefix they force the mode either on (positive prefix) or off (negative or zero prefix). Since you don’t know what the environment might be when you invoke your macro, it’s best to use prefix arguments for all mode-setting commands inside the macro.

In fact, C-u Z ` is like Z ` except that it sets the modes listed above to their default values. As usual, the matching Z ' will restore the modes to their settings from before the C-u Z `. Also, Z ` with a negative prefix argument resets the algebraic mode to its default (off) but leaves the other modes the same as they were outside the construct.

The contents of the stack and trail, values of non-quick variables, and other settings such as the language mode and the various display modes, are not affected by Z ` and Z '.