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

The command M-TAB (calc-roll-up) is analogous to TAB except that it rotates upward instead of downward. Also, the default with no prefix argument is to rotate the top 3 elements. For example, with `10 20 30 40 50' on the stack, M-TAB creates `10 20 40 50 30', C-u 4 M-TAB creates `10 30 40 50 20', C-u - 2 M-TAB creates `30 40 50 10 20', and C-u 0 M-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.

See section 12.1 Selecting Sub-Formulas, for a way to apply these commands to any portion of a vector or formula on the stack.

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.

The t . (calc-full-trail-vectors) command is described elsewhere; see section 11.9 Vector and Matrix Display Formats.

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.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.