5. Introduction

This chapter is the beginning of the Calc reference manual. It covers basic concepts such as the stack, algebraic and numeric entry, undo, numeric prefix arguments, etc.

5.1 Basic Commands

To start the Calculator in its standard interface, type M-x calc. By default this creates a pair of small windows, `*Calculator*' and `*Calc Trail*'. The former displays the contents of the Calculator stack and is manipulated exclusively through Calc commands. It is possible (though not usually necessary) to create several Calc Mode buffers each of which has an independent stack, undo list, and mode settings. There is exactly one Calc Trail buffer; it records a list of the results of all calculations that have been done. The Calc Trail buffer uses a variant of Calc Mode, so Calculator commands still work when the trail buffer's window is selected. It is possible to turn the trail window off, but the `*Calc Trail*' buffer itself still exists and is updated silently. See section 7.3 Trail Commands.

In most installations, the M-# c key sequence is a more convenient way to start the Calculator. Also, M-# M-# and M-# # are synonyms for M-# c unless you last used Calc in its "keypad" mode.

Most Calc commands use one or two keystrokes. Lower- and upper-case letters are distinct. Commands may also be entered in full M-x form; for some commands this is the only form. As a convenience, the x key (calc-execute-extended-command) is like M-x except that it enters the initial string `calc-' for you. For example, the following key sequences are equivalent: S, M-x calc-sin RET, x sin RET.

The Calculator exists in many parts. When you type M-# c, the Emacs "auto-load" mechanism will bring in only the first part, which contains the basic arithmetic functions. The other parts will be auto-loaded the first time you use the more advanced commands like trig functions or matrix operations. This is done to improve the response time of the Calculator in the common case when all you need to do is a little arithmetic. If for some reason the Calculator fails to load an extension module automatically, you can force it to load all the extensions by using the M-# L (calc-load-everything) command. See section 8. Mode Settings.

If you type M-x calc or M-# c with any numeric prefix argument, the Calculator is loaded if necessary, but it is not actually started. If the argument is positive, the `calc-ext' extensions are also loaded if necessary. User-written Lisp code that wishes to make use of Calc's arithmetic routines can use `(calc 0)' or `(calc 1)' to auto-load the Calculator.

If you type M-# b, then next time you use M-# c you will get a Calculator that uses the full height of the Emacs screen. When full-screen mode is on, M-# c runs the full-calc command instead of calc. From the Unix shell you can type `emacs -f full-calc' to start a new Emacs specifically for use as a calculator. When Calc is started from the Emacs command line like this, Calc's normal "quit" commands actually quit Emacs itself.

The M-# o command is like M-# c except that the Calc window is not actually selected. If you are already in the Calc window, M-# o switches you out of it. (The regular Emacs C-x o command would also work for this, but it has a tendency to drop you into the Calc Trail window instead, which M-# o takes care not to do.)

For one quick calculation, you can type M-# q (quick-calc) which prompts you for a formula (like `2+3/4'). The result is displayed at the bottom of the Emacs screen without ever creating any special Calculator windows. See section 5.6 "Quick Calculator" Mode.

Finally, if you are using the X window system you may want to try M-# k (calc-keypad) which runs Calc with a "calculator keypad" picture as well as a stack display. Click on the keys with the mouse to operate the calculator. See section 17. "Keypad" Mode.

The q key (calc-quit) exits Calc Mode and closes the Calculator's window(s). It does not delete the Calculator buffers. If you type M-x calc again, the Calculator will reappear with the contents of the stack intact. Typing M-# c or M-# M-# again from inside the Calculator buffer is equivalent to executing calc-quit; you can think of M-# M-# as toggling the Calculator on and off.

The M-# x command also turns the Calculator off, no matter which user interface (standard, Keypad, or Embedded) is currently active. It also cancels calc-edit mode if used from there.

The d SPC key sequence (calc-refresh) redraws the contents of the Calculator buffer from memory. Use this if the contents of the buffer have been damaged somehow.

The o key (calc-realign) moves the cursor back to its "home" position at the bottom of the Calculator buffer.

The < and > keys are bound to calc-scroll-left and calc-scroll-right. These are just like the normal horizontal scrolling commands except that they scroll one half-screen at a time by default. (Calc formats its output to fit within the bounds of the window whenever it can.)

The { and } keys are bound to calc-scroll-down and calc-scroll-up. They scroll up or down by one-half the height of the Calc window.

The M-# 0 command (calc-reset; that's M-# followed by a zero) resets the Calculator to its default state. This clears the stack, resets all the modes, clears the caches (see section 5.11.3 Caches), and so on. (It does not erase the values of any variables.) With a numeric prefix argument, M-# 0 preserves the contents of the stack but resets everything else.

The M-x calc-version command displays the current version number of Calc and the name of the person who installed it on your system. (This information is also present in the `*Calc Trail*' buffer, and in the output of the h h command.)

5.2 Help Commands

The ? key (calc-help) displays a series of brief help messages. Some keys (such as b and d) are prefix keys, like Emacs' ESC and C-x prefixes. You can type ? after a prefix to see a list of commands beginning with that prefix. (If the message includes `[MORE]', press ? again to see additional commands for that prefix.)

The h h (calc-full-help) command displays all the ? responses at once. When printed, this makes a nice, compact (three pages) summary of Calc keystrokes.

In general, the h key prefix introduces various commands that provide help within Calc. Many of the h key functions are Calc-specific analogues to the C-h functions for Emacs help.

The h i (calc-info) command runs the Emacs Info system to read this manual on-line. This is basically the same as typing C-h i (the regular way to run the Info system), then, if Info is not already in the Calc manual, selecting the beginning of the manual. The M-# i command is another way to read the Calc manual; it is different from h i in that it works any time, not just inside Calc. The plain i key is also equivalent to h i, though this key is obsolete and may be replaced with a different command in a future version of Calc.

The h t (calc-tutorial) command runs the Info system on the Tutorial section of the Calc manual. It is like h i, except that it selects the starting node of the tutorial rather than the beginning of the whole manual. (It actually selects the node "Interactive Tutorial" which tells a few things about using the Info system before going on to the actual tutorial.) The M-# t key is equivalent to h t (but it works at all times).

The h s (calc-info-summary) command runs the Info system on the Summary node of the Calc manual. See section C. Calc Summary. The M-# s key is equivalent to h s.

The h k (calc-describe-key) command looks up a key sequence in the Calc manual. For example, h k H a S looks up the documentation on the H a S (calc-solve-for) command. This works by looking up the textual description of the key(s) in the Key Index of the manual, then jumping to the node indicated by the index.

Most Calc commands do not have traditional Emacs documentation strings, since the h k command is both more convenient and more instructive. This means the regular Emacs C-h k (describe-key) command will not be useful for Calc keystrokes.

The h c (calc-describe-key-briefly) command reads a key sequence and displays a brief one-line description of it at the bottom of the screen. It looks for the key sequence in the Summary node of the Calc manual; if it doesn't find the sequence there, it acts just like its regular Emacs counterpart C-h c (describe-key-briefly). For example, h c H a S gives the description:

H a S runs calc-solve-for:  a `H a S' v  => fsolve(a,v)  (?=notes)

which means the command H a S or H M-x calc-solve-for takes a value a from the stack, prompts for a value v, then applies the algebraic function fsolve to these values. The `?=notes' message means you can now type ? to see additional notes from the summary that apply to this command.

The h f (calc-describe-function) command looks up an algebraic function or a command name in the Calc manual. The prompt initially contains `calcFunc-'; follow this with an algebraic function name to look up that function in the Function Index. Or, backspace and enter a command name beginning with `calc-' to look it up in the Command Index. This command will also look up operator symbols that can appear in algebraic formulas, like `%' and `=>'.

The h v (calc-describe-variable) command looks up a variable in the Calc manual. The prompt initially contains the `var-' prefix; just add a variable name like pi or PlotRejects.

The h b (calc-describe-bindings) command is just like C-h b, except that only local (Calc-related) key bindings are listed.

The h n or h C-n (calc-view-news) command displays the "news" or change history of Calc. This is kept in the file `README', which Calc looks for in the same directory as the Calc source files.

The h C-c, h C-d, and h C-w keys display copying, distribution, and warranty information about Calc. These work by pulling up the appropriate parts of the "Copying" or "Reporting Bugs" sections of the manual.

5.3 Stack Basics

Calc uses RPN notation. If you are not familar with RPN, see section 4.1.1 RPN Calculations and the Stack.

To add the numbers 1 and 2 in Calc you would type the keys: 1 RET 2 +. (RET corresponds to the ENTER key on most calculators.) The first three keystrokes "push" the numbers 1 and 2 onto the stack. The + key always "pops" the top two numbers from the stack, adds them, and pushes the result (3) back onto the stack. This number is ready for further calculations: 5 - pushes 5 onto the stack, then pops the 3 and 5, subtracts them, and pushes the result (-2).

Note that the "top" of the stack actually appears at the bottom of the buffer. A line containing a single `.' character signifies the end of the buffer; Calculator commands operate on the number(s) directly above this line. The d t (calc-truncate-stack) command allows you to move the `.' marker up and down in the stack; see section 8.7.8 Truncating the Stack.

Stack elements are numbered consecutively, with number 1 being the top of the stack. These line numbers are ordinarily displayed on the lefthand side of the window. The d l (calc-line-numbering) command controls whether these numbers appear. (Line numbers may be turned off since they slow the Calculator down a bit and also clutter the display.)

The unshifted letter o (calc-realign) command repositions the cursor to its top-of-stack "home" position. It also undoes any horizontal scrolling in the window. If you give it a numeric prefix argument, it instead moves the cursor to the specified stack element.

The RET (or equivalent SPC) key is only required to separate two consecutive numbers. (After all, if you typed 1 2 by themselves the Calculator would enter the number 12.) If you press RET or SPC not right after typing a number, the key duplicates the number on the top of the stack. RET * is thus a handy way to square a number.

The DEL key pops and throws away the top number on the stack. The TAB key swaps the top two objects on the stack. See section 7. Stack and Trail Commands, for descriptions of these and other stack-related commands.

5.4 Numeric Entry

Pressing a digit or other numeric key begins numeric entry using the minibuffer. The number is pushed on the stack when you press the RET or SPC keys. If you press any other non-numeric key, the number is pushed onto the stack and the appropriate operation is performed. If you press a numeric key which is not valid, the key is ignored.

There are three different concepts corresponding to the word "minus," typified by a-b (subtraction), -x (change-sign), and -5 (negative number). Calc uses three different keys for these operations, respectively: -, n, and _ (the underscore). The - key subtracts the two numbers on the top of the stack. The n key changes the sign of the number on the top of the stack or the number currently being entered. The _ key begins entry of a negative number or changes the sign of the number currently being entered. The following sequences all enter the number -5 onto the stack: 0 RET 5 -, 5 n RET, 5 RET n, _ 5 RET, 5 _ RET.

Some other keys are active during numeric entry, such as # for non-decimal numbers, : for fractions, and @ for HMS forms. These notations are described later in this manual with the corresponding data types. See section 6. Data Types.

During numeric entry, the only editing key available is DEL.

5.5 Algebraic Entry

Calculations can also be entered in algebraic form. This is accomplished by typing the apostrophe key, ', followed by the expression in standard format: ' 2+3*4 RET computes 2+(3*4) = 14 and pushes that on the stack. If you wish you can ignore the RPN aspect of Calc altogether and simply enter algebraic expressions in this way. You may want to use DEL every so often to clear previous results off the stack.

You can press the apostrophe key during normal numeric entry to switch the half-entered number into algebraic entry mode. One reason to do this would be to use the full Emacs cursor motion and editing keys, which are available during algebraic entry but not during numeric entry.

In the same vein, during either numeric or algebraic entry you can press ` (backquote) to switch to calc-edit mode, where you complete your half-finished entry in a separate buffer. See section 7.2 Editing Stack Entries.

If you prefer algebraic entry, you can use the command m a (calc-algebraic-mode) to set Algebraic mode. In this mode, digits and other keys that would normally start numeric entry instead start full algebraic entry; as long as your formula begins with a digit you can omit the apostrophe. Open parentheses and square brackets also begin algebraic entry. You can still do RPN calculations in this mode, but you will have to press RET to terminate every number: 2 RET 3 RET * 4 RET + would accomplish the same thing as 2*3+4 RET.

If you give a numeric prefix argument like C-u to the m a command, it enables Incomplete Algebraic mode; this is like regular Algebraic mode except that it applies to the ( and [ keys only. Numeric keys still begin a numeric entry in this mode.

The m t (calc-total-algebraic-mode) gives you an even stronger algebraic-entry mode, in which all regular letter and punctuation keys begin algebraic entry. Use this if you prefer typing sqrt( ) instead of Q, factor( ) instead of a f, and so on. To type regular Calc commands when you are in "total" algebraic mode, hold down the META key. Thus M-q is the command to quit Calc, M-p sets the precision, and M-m t (or M-m M-t, if you prefer) turns total algebraic mode back off again. Meta keys also terminate algebraic entry, so that 2+3 M-S is equivalent to 2+3 RET M-S. The symbol `Alg*' will appear in the mode line whenever you are in this mode.

Pressing ' (the apostrophe) a second time re-enters the previous algebraic formula. You can then use the normal Emacs editing keys to modify this formula to your liking before pressing RET.

Within a formula entered from the keyboard, the symbol $ represents the number on the top of the stack. If an entered formula contains any $ characters, the Calculator replaces the top of stack with that formula rather than simply pushing the formula onto the stack. Thus, ' 1+2 RET pushes 3 on the stack, and $*2 RET replaces it with 6. Note that the $ key always initiates algebraic entry; the ' is unnecessary if $ is the first character in the new formula.

Higher stack elements can be accessed from an entered formula with the symbols $$, $$$, and so on. The number of stack elements removed (to be replaced by the entered values) equals the number of dollar signs in the longest such symbol in the formula. For example, `$$+$$$' adds the second and third stack elements, replacing the top three elements with the answer. (All information about the top stack element is thus lost since no single `$' appears in this formula.)

A slightly different way to refer to stack elements is with a dollar sign followed by a number: `$1', `$2', and so on are much like `$', `$$', etc., except that stack entries referred to numerically are not replaced by the algebraic entry. That is, while `$+1' replaces 5 on the stack with 6, `$1+1' leaves the 5 on the stack and pushes an additional 6.

If a sequence of formulas are entered separated by commas, each formula is pushed onto the stack in turn. For example, `1,2,3' pushes those three numbers onto the stack (leaving the 3 at the top), and `$+1,$-1' replaces a 5 on the stack with 4 followed by 6. Also, `$,$$' exchanges the top two elements of the stack, just like the TAB key.

You can finish an algebraic entry with M-= or M-RET instead of RET. This uses = to evaluate the variables in each formula that goes onto the stack. (Thus ' pi RET pushes the variable `pi', but ' pi M-RET pushes 3.1415.)

If you finish your algebraic entry by pressing LFD (or C-j) instead of RET, Calc disables the default simplifications (as if by m O; see section 8.5 Simplification Modes) while the entry is being pushed on the stack. Thus ' 1+2 RET pushes 3 on the stack, but ' 1+2 LFD pushes the formula 1+2; you might then press = when it is time to evaluate this formula.

5.6 "Quick Calculator" Mode

There is another way to invoke the Calculator if all you need to do is make one or two quick calculations. Type M-# q (or M-x quick-calc), then type any formula as an algebraic entry. The Calculator will compute the result and display it in the echo area, without ever actually putting up a Calc window.

You can use the $ character in a Quick Calculator formula to refer to the previous Quick Calculator result. Older results are not retained; the Quick Calculator has no effect on the full Calculator's stack or trail. If you compute a result and then forget what it was, just run M-# q again and enter `$' as the formula.

If this is the first time you have used the Calculator in this Emacs session, the M-# q command will create the *Calculator* buffer and perform all the usual initializations; it simply will refrain from putting that buffer up in a new window. The Quick Calculator refers to the *Calculator* buffer for all mode settings. Thus, for example, to set the precision that the Quick Calculator uses, simply run the full Calculator momentarily and use the regular p command.

If you use M-# q from inside the Calculator buffer, the effect is the same as pressing the apostrophe key (algebraic entry).

The result of a Quick calculation is placed in the Emacs "kill ring" as well as being displayed. A subsequent C-y command will yank the result into the editing buffer. You can also use this to yank the result into the next M-# q input line as a more explicit alternative to $ notation, or to yank the result into the Calculator stack after typing M-# c.

If you finish your formula by typing LFD (or C-j) instead of RET, the result is inserted immediately into the current buffer rather than going into the kill ring.

Quick Calculator results are actually evaluated as if by the = key (which replaces variable names by their stored values, if any). If the formula you enter is an assignment to a variable using the `:=' operator, say, `foo := 2 + 3' or `foo := foo + 1', then the result of the evaluation is stored in that Calc variable. See section 14. Storing and Recalling.

If the result is an integer and the current display radix is decimal, the number will also be displayed in hex and octal formats. If the integer is in the range from 1 to 126, it will also be displayed as an ASCII character.

For example, the quoted character `"x"' produces the vector result `[120]' (because 120 is the ASCII code of the lower-case `x'; see section 6.7 Strings). Since this is a vector, not an integer, it is displayed only according to the current mode settings. But running Quick Calc again and entering `120' will produce the result `120 (16#78, 8#170, x)' which shows the number in its decimal, hexadecimal, octal, and ASCII forms.

Please note that the Quick Calculator is not any faster at loading or computing the answer than the full Calculator; the name "quick" merely refers to the fact that it's much less hassle to use for small calculations.

5.7 Numeric Prefix Arguments

Many Calculator commands use numeric prefix arguments. Some, such as d s (calc-sci-notation), set a parameter to the value of the prefix argument or use a default if you don't use a prefix. Others (like d f (calc-fix-notation)) require an argument and prompt for a number if you don't give one as a prefix.

As a rule, stack-manipulation commands accept a numeric prefix argument which is interpreted as an index into the stack. A positive argument operates on the top n stack entries; a negative argument operates on the nth stack entry in isolation; and a zero argument operates on the entire stack.

Most commands that perform computations (such as the arithmetic and scientific functions) accept a numeric prefix argument that allows the operation to be applied across many stack elements. For unary operations (that is, functions of one argument like absolute value or complex conjugate), a positive prefix argument applies that function to the top n stack entries simultaneously, and a negative argument applies it to the nth stack entry only. For binary operations (functions of two arguments like addition, GCD, and vector concatenation), a positive prefix argument "reduces" the function across the top n stack elements (for example, C-u 5 + sums the top 5 stack entries; see section 11.8 Reducing and Mapping Vectors), and a negative argument maps the next-to-top n stack elements with the top stack element as a second argument (for example, 7 c-u -5 + adds 7 to the top 5 stack elements). This feature is not available for operations which use the numeric prefix argument for some other purpose.

Numeric prefixes are specified the same way as always in Emacs: Press a sequence of META-digits, or press ESC followed by digits, or press C-u followed by digits. Some commands treat plain C-u (without any actual digits) specially.

You can type ~ (calc-num-prefix) to pop an integer from the top of the stack and enter it as the numeric prefix for the next command. For example, C-u 16 p sets the precision to 16 digits; an alternate (silly) way to do this would be 2 RET 4 ^ ~ p, i.e., compute 2 to the fourth power and set the precision to that value.

Conversely, if you have typed a numeric prefix argument the ~ key pushes it onto the stack in the form of an integer.

5.8 Undoing Mistakes

The shift-U key (calc-undo) undoes the most recent operation. If that operation added or dropped objects from the stack, those objects are removed or restored. If it was a "store" operation, you are queried whether or not to restore the variable to its original value. The U key may be pressed any number of times to undo successively farther back in time; with a numeric prefix argument it undoes a specified number of operations. The undo history is cleared only by the q (calc-quit) command. (Recall that M-# c is synonymous with calc-quit while inside the Calculator; this also clears the undo history.)

Currently the mode-setting commands (like calc-precision) are not undoable. You can undo past a point where you changed a mode, but you will need to reset the mode yourself.

The shift-D key (calc-redo) redoes an operation that was mistakenly undone. Pressing U with a negative prefix argument is equivalent to executing calc-redo. You can redo any number of times, up to the number of recent consecutive undo commands. Redo information is cleared whenever you give any command that adds new undo information, i.e., if you undo, then enter a number on the stack or make any other change, then it will be too late to redo.

The M-RET key (calc-last-args) is like undo in that it restores the arguments of the most recent command onto the stack; however, it does not remove the result of that command. Given a numeric prefix argument, this command applies to the nth most recent command which removed items from the stack; it pushes those items back onto the stack.

The K (calc-keep-args) command provides a related function to M-RET. See section 7. Stack and Trail Commands.

It is also possible to recall previous results or inputs using the trail. See section 7.3 Trail Commands.

The standard Emacs C-_ undo key is recognized as a synonym for U.

5.9 Error Messages

Many situations that would produce an error message in other calculators simply create unsimplified formulas in the Emacs Calculator. For example, 1 RET 0 / pushes the formula 1 / 0; 0 L pushes the formula `ln(0)'. Floating-point overflow and underflow are also reasons for this to happen.

When a function call must be left in symbolic form, Calc usually produces a message explaining why. Messages that are probably surprising or indicative of user errors are displayed automatically. Other messages are simply kept in Calc's memory and are displayed only if you type w (calc-why). You can also press w if the same computation results in several messages. (The first message will end with `[w=more]' in this case.)

The d w (calc-auto-why) command controls when error messages are displayed automatically. (Calc effectively presses w for you after your computation finishes.) By default, this occurs only for "important" messages. The other possible modes are to report all messages automatically, or to report none automatically (so that you must always press w yourself to see the messages).

5.10 Multiple Calculators

It is possible to have any number of Calc Mode buffers at once. Usually this is done by executing M-x another-calc, which is similar to M-# c except that if a `*Calculator*' buffer already exists, a new, independent one with a name of the form `*Calculator*<n>' is created. You can also use the command calc-mode to put any buffer into Calculator mode, but this would ordinarily never be done.

The q (calc-quit) command does not destroy a Calculator buffer; it only closes its window. Use M-x kill-buffer to destroy a Calculator buffer.

Each Calculator buffer keeps its own stack, undo list, and mode settings such as precision, angular mode, and display formats. In Emacs terms, variables such as calc-stack are buffer-local variables. The global default values of these variables are used only when a new Calculator buffer is created. The calc-quit command saves the stack and mode settings of the buffer being quit as the new defaults.

There is only one trail buffer, `*Calc Trail*', used by all Calculator buffers.

5.11 Troubleshooting Commands

This section describes commands you can use in case a computation incorrectly fails or gives the wrong answer.

See section B. Reporting Bugs, if you find a problem that appears to be due to a bug or deficiency in Calc.

5.11.1 Autoloading Problems

The Calc program is split into many component files; components are loaded automatically as you use various commands that require them. Occasionally Calc may lose track of when a certain component is necessary; typically this means you will type a command and it won't work because some function you've never heard of was undefined.

If this happens, the easiest workaround is to type M-# L (calc-load-everything) to force all the parts of Calc to be loaded right away. This will cause Emacs to take up a lot more memory than it would otherwise, but it's guaranteed to fix the problem.

If you seem to run into this problem no matter what you do, or if even the M-# L command crashes, Calc may have been improperly installed. See section A. Installation, for details of the installation process.

5.11.2 Recursion Depth

Calc uses recursion in many of its calculations. Emacs Lisp keeps a variable max-lisp-eval-depth which limits the amount of recursion possible in an attempt to recover from program bugs. If a calculation ever halts incorrectly with the message "Computation got stuck or ran too long," use the M command (calc-more-recursion-depth) to increase this limit. (Of course, this will not help if the calculation really did get stuck due to some problem inside Calc.)

The limit is always increased (multiplied) by a factor of two. There is also an I M (calc-less-recursion-depth) command which decreases this limit by a factor of two, down to a minimum value of 200. The default value is 1000.

These commands also double or halve max-specpdl-size, another internal Lisp recursion limit. The minimum value for this limit is 600.

5.11.3 Caches

Calc saves certain values after they have been computed once. For example, the P (calc-pi) command initially "knows" the constant pi to about 20 decimal places; if the current precision is greater than this, it will recompute pi using a series approximation. This value will not need to be recomputed ever again unless you raise the precision still further. Many operations such as logarithms and sines make use of similarly cached values such as pi/4 and ln(2). The visible effect of caching is that high-precision computations may seem to do extra work the first time. Other things cached include powers of two (for the binary arithmetic functions), matrix inverses and determinants, symbolic integrals, and data points computed by the graphing commands.

If you suspect a Calculator cache has become corrupt, you can use the calc-flush-caches command to reset all caches to the empty state. (This should only be necessary in the event of bugs in the Calculator.) The M-# 0 (with the zero key) command also resets caches along with all other aspects of the Calculator's state.

5.11.4 Debugging Calc

A few commands exist to help in the debugging of Calc commands. See section 19. Programming, to see the various ways that you can write your own Calc commands.

The Z T (calc-timing) command turns on and off a mode in which the timing of slow commands is reported in the Trail. Any Calc command that takes two seconds or longer writes a line to the Trail showing how many seconds it took. This value is accurate only to within one second.

All steps of executing a command are included; in particular, time taken to format the result for display in the stack and trail is counted. Some prompts also count time taken waiting for them to be answered, while others do not; this depends on the exact implementation of the command. For best results, if you are timing a sequence that includes prompts or multiple commands, define a keyboard macro to run the whole sequence at once. Calc's X command (see section 19.2 Programming with Keyboard Macros) will then report the time taken to execute the whole macro.

Another advantage of the X command is that while it is executing, the stack and trail are not updated from step to step. So if you expect the output of your test sequence to leave a result that may take a long time to format and you don't wish to count this formatting time, end your sequence with a DEL keystroke to clear the result from the stack. When you run the sequence with X, Calc will never bother to format the large result.

Another thing Z T does is to increase the Emacs variable gc-cons-threshold to a much higher value (two million; the usual default in Calc is 250,000) for the duration of each command. This generally prevents garbage collection during the timing of the command, though it may cause your Emacs process to grow abnormally large. (Garbage collection time is a major unpredictable factor in the timing of Emacs operations.)

Another command that is useful when debugging your own Lisp extensions to Calc is M-x calc-pass-errors, which disables the error handler that changes the "max-lisp-eval-depth exceeded" message to the much more friendly "Computation got stuck or ran too long." This handler interferes with the Emacs Lisp debugger's debug-on-error mode. Errors are reported in the handler itself rather than at the true location of the error. After you have executed calc-pass-errors, Lisp errors will be reported correctly but the user-friendly message will be lost.

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