7. Stack and Trail Commands

This chapter describes the Calc commands for manipulating objects on the
stack and in the trail buffer. (These commands operate on objects of any
type, such as numbers, vectors, formulas, and incomplete objects.)

7.1 Stack Manipulation Commands

To duplicate the top object on the stack, press RET or SPC
(two equivalent keys for the calc-enter command).
Given a positive numeric prefix argument, these commands duplicate
several elements at the top of the stack.
Given a negative argument,
these commands duplicate the specified element of the stack.
Given an argument of zero, they duplicate the entire stack.
For example, with `10 20 30' on the stack,
RET creates `10 20 30 30',
C-u 2 RET creates `10 20 30 20 30',
C-u - 2 RET creates `10 20 30 20', and
C-u 0 RET creates `10 20 30 10 20 30'.

The LFD (calc-over) command (on a key marked Line-Feed if you
have it, else on C-j) is like calc-enter
except that the sign of the numeric prefix argument is interpreted
oppositely. Also, with no prefix argument the default argument is 2.
Thus with `10 20 30' on the stack, LFD and C-u 2 LFD
are both equivalent to C-u - 2 RET, producing
`10 20 30 20'.

To remove the top element from the stack, press DEL (calc-pop).
The C-d key is a synonym for DEL.
(If the top element is an incomplete object with at least one element, the
last element is removed from it.) Given a positive numeric prefix argument,
several elements are removed. Given a negative argument, the specified
element of the stack is deleted. Given an argument of zero, the entire
stack is emptied.
For example, with `10 20 30' on the stack,
DEL leaves `10 20',
C-u 2 DEL leaves `10',
C-u - 2 DEL leaves `10 30', and
C-u 0 DEL leaves an empty stack.

The M-DEL (calc-pop-above) command is to DEL what
LFD is to RET: It interprets the sign of the numeric
prefix argument in the opposite way, and the default argument is 2.
Thus M-DEL by itself removes the second-from-top stack element,
leaving the first, third, fourth, and so on; M-3 M-DEL deletes
the third stack element.

To exchange the top two elements of the stack, press TAB
(calc-roll-down). Given a positive numeric prefix argument, the
specified number of elements at the top of the stack are rotated downward.
Given a negative argument, the entire stack is rotated downward the specified
number of times. Given an argument of zero, the entire stack is reversed
top-for-bottom.
For example, with `10 20 30 40 50' on the stack,
TAB creates `10 20 30 50 40',
C-u 3 TAB creates `10 20 50 30 40',
C-u - 2 TAB creates `40 50 10 20 30', and
C-u 0 TAB creates `50 40 30 20 10'.

A good way to view the operation of TAB and M-TAB is in
terms of moving a particular element to a new position in the stack.
With a positive argument n, TAB moves the top stack
element down to level n, making room for it by pulling all the
intervening stack elements toward the top. M-TAB moves the
element at level n up to the top. (Compare with LFD,
which copies instead of moving the element in level n.)

With a negative argument -n, TAB rotates the stack
to move the object in level n to the deepest place in the
stack, and the object in level n+1 to the top. M-TAB
rotates the deepest stack element to be in level n, also
putting the top stack element in level n+1.

7.2 Editing Stack Entries

The backquote, ` (calc-edit) command creates a temporary
buffer (`*Calc Edit*') for editing the top-of-stack value using
regular Emacs commands. With a numeric prefix argument, it edits the
specified number of stack entries at once. (An argument of zero edits
the entire stack; a negative argument edits one specific stack entry.)

When you are done editing, press M-# M-# to finish and return
to Calc. The RET and LFD keys also work to finish most
sorts of editing, though in some cases Calc leaves RET with its
usual meaning ("insert a newline") if it's a situation where you
might want to insert new lines into the editing buffer. The traditional
Emacs "finish" key sequence, C-c C-c, also works to finish
editing and may be easier to type, depending on your keyboard.

When you finish editing, the Calculator parses the lines of text in
the `*Calc Edit*' buffer as numbers or formulas, replaces the
original stack elements in the original buffer with these new values,
then kills the `*Calc Edit*' buffer. The original Calculator buffer
continues to exist during editing, but for best results you should be
careful not to change it until you have finished the edit. You can
also cancel the edit by pressing M-# x.

The formula is normally reevaluated as it is put onto the stack.
For example, editing `a + 2' to `3 + 2' and pressing
M-# M-# will push 5 on the stack. If you use LFD to
finish, Calc will put the result on the stack without evaluating it.

If you give a prefix argument to M-# M-# (or C-c C-c),
Calc will not kill the `*Calc Edit*' buffer. You can switch
back to that buffer and continue editing if you wish. However, you
should understand that if you initiated the edit with `, the
M-# M-# operation will be programmed to replace the top of the
stack with the new edited value, and it will do this even if you have
rearranged the stack in the meanwhile. This is not so much of a problem
with other editing commands, though, such as s e
(calc-edit-variable; see section 14.3 Other Operations on Variables).

If the calc-edit command involves more than one stack entry,
each line of the `*Calc Edit*' buffer is interpreted as a
separate formula. Otherwise, the entire buffer is interpreted as
one formula, with line breaks ignored. (You can use C-o or
C-q C-j to insert a newline in the buffer without pressing RET.)

The ` key also works during numeric or algebraic entry. The
text entered so far is moved to the *Calc Edit* buffer for
more extensive editing than is convenient in the minibuffer.

7.3 Trail Commands

The commands for manipulating the Calc Trail buffer are two-key sequences
beginning with the t prefix.

The t d (calc-trail-display) command turns display of the
trail on and off. Normally the trail display is toggled on if it was off,
off if it was on. With a numeric prefix of zero, this command always
turns the trail off; with a prefix of one, it always turns the trail on.
The other trail-manipulation commands described here automatically turn
the trail on. Note that when the trail is off values are still recorded
there; they are simply not displayed. To set Emacs to turn the trail
off by default, type t d and then save the mode settings with
m m (calc-save-modes).

The t i (calc-trail-in) and t o
(calc-trail-out) commands switch the cursor into and out of the
Calc Trail window. In practice they are rarely used, since the commands
shown below are a more convenient way to move around in the
trail, and they work "by remote control" when the cursor is still
in the Calculator window.

There is a trail pointer which selects some entry of the trail at
any given time. The trail pointer looks like a `>' symbol right
before the selected number. The following commands operate on the
trail pointer in various ways.

The t y (calc-trail-yank) command reads the selected value in
the trail and pushes it onto the Calculator stack. It allows you to
re-use any previously computed value without retyping. With a numeric
prefix argument n, it yanks the value n lines above the current
trail pointer.

The t < (calc-trail-scroll-left) and t >
(calc-trail-scroll-right) commands horizontally scroll the trail
window left or right by one half of its width.

The t n (calc-trail-next) and t p
(calc-trail-previous) commands move the trail pointer down or up
one line. The t f (calc-trail-forward) and t b
(calc-trail-backward) commands move the trail pointer down or up
one screenful at a time. All of these commands accept numeric prefix
arguments to move several lines or screenfuls at a time.

The t [ (calc-trail-first) and t ]
(calc-trail-last) commands move the trail pointer to the first or
last line of the trail. The t h (calc-trail-here) command
moves the trail pointer to the cursor position; unlike the other trail
commands, t h works only when Calc Trail is the selected window.

The t s (calc-trail-isearch-forward) and t r
(calc-trail-isearch-backward) commands perform an incremental
search forward or backward through the trail. You can press RET
to terminate the search; the trail pointer moves to the current line.
If you cancel the search with C-g, the trail pointer stays where
it was when the search began.

The t m (calc-trail-marker) command allows you to enter a
line of text of your own choosing into the trail. The text is inserted
after the line containing the trail pointer; this usually means it is
added to the end of the trail. Trail markers are useful mainly as the
targets for later incremental searches in the trail.

The t k (calc-trail-kill) command removes the selected line
from the trail. The line is saved in the Emacs kill ring suitable for
yanking into another buffer, but it is not easy to yank the text back
into the trail buffer. With a numeric prefix argument, this command
kills the n lines below or above the selected one.

7.4 Keep Arguments

The K (calc-keep-args) command acts like a prefix for
the following command. It prevents that command from removing its
arguments from the stack. For example, after 2 RET 3 +,
the stack contains the sole number 5, but after 2 RET 3 K +,
the stack contains the arguments and the result: `2 3 5'.

This works for all commands that take arguments off the stack. As
another example, K a s simplifies a formula, pushing the
simplified version of the formula onto the stack after the original
formula (rather than replacing the original formula).

Note that you could get the same effect by typing RET a s,
copying the formula and then simplifying the copy. One difference
is that for a very large formula the time taken to format the
intermediate copy in RET a s could be noticeable; K a s
would avoid this extra work.

Even stack manipulation commands are affected. TAB works by
popping two values and pushing them back in the opposite order,
so 2 RET 3 K TAB produces `2 3 3 2'.

A few Calc commands provide other ways of doing the same thing.
For example, ' sin($) replaces the number on the stack with
its sine using algebraic entry; to push the sine and keep the
original argument you could use either ' sin($1) or
K ' sin($). See section 5.5 Algebraic Entry. Also, the s s
command is effectively the same as K s t. See section 14.1 Storing Variables.

Keyboard macros may interact surprisingly with the K prefix.
If you have defined a keyboard macro to be, say, `Q +' to add
one number to the square root of another, then typing K X will
execute K Q +, probably not what you expected. The K
prefix will apply to just the first command in the macro rather than
the whole macro.

If you execute a command and then decide you really wanted to keep
the argument, you can press M-RET (calc-last-args).
This command pushes the last arguments that were popped by any command
onto the stack. Note that the order of things on the stack will be
different than with K: 2 RET 3 + M-RET leaves
`5 2 3' on the stack instead of `2 3 5'. See section 5.8 Undoing Mistakes.