[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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`,

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

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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 +`.
(

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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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 -`,

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

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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

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

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

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 `

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

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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 `n`th 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 `n`th 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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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;

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

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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

5.11.2 Recursion Depth | ||

5.11.3 Caches | ||

5.11.4 Debugging Calc |

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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.

[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

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.

[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |

This document was generated by