calc: Local Values in Macros
18.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 '’.