Previous | Table of Contents | Next |
GNU Emacs provides a wealth of online documentation and help. It is well worth learning to use these riches.
Most functions and variables in Emacs Lisp are written with documentation that you can access using C-h a (command-apropos), M-x apropos, C-h f (describe-function), and C-h v (describe-variable).
The find-tag command locates and takes you to the source for a function, macro, variable, or special form. This is very helpful, both when reading the source code in the Emacs distribution and when working on your own code. (Simply run etags to create your tags tables for your own files.) See the section Tags Tables in The GNU Emacs Manual.
You can read the online copy of The GNU Emacs Lisp Reference Manual that is part of your system with C-h i (info), the built-in hypertext help system. The reference manual describes all of Emacs Lisp in considerable detail. Of course, you can also begin to learn Lisp by using Info to work through Programming in Emacs Lisp: An Introduction. Finally, The GNU Emacs Manual explains Emacs as a working environmenthow to edit, read mail, use the calendarrather than Emacs Lisp, the programming language.12
12These three manuals are written in Texinfo, which is a documentation system that uses a single source file to produce both online information and printed output. Hence, you can read the manuals in typeset printed form, you can print copies yourself, or you can order copies from the Free Software Foundation.
GNU Emacs has two debuggers, debug and edebug. The first is built into the internals of Emacs and is always available; the second requires that you specially evaluate the functions you want to debug.
Suppose you miswrote the add-37 function definition discussed previously. Assume you misspelled number as nmber and wrote the definition like this:
(defun add-37 (number) Add 37 to NUMBER. (interactive p) (message The new number is: %d! (+ 37 nmber)))
First, you evaluate the definition; no problem is apparent.
Then you evaluate this:
(add-37 5)
You see this:
Symbols value as variable is void: nmber
rather than the number 42.
In practice, for a bug as simple as this, this error message tells you what you need to know: number is a local variable and it has been misspelled. However, suppose you want to learn more. You can turn on the built-in debugger by setting the value of debug-on-error to t. Type this to set debug-on-error interactively13
13It goes without saying that you need not type the full name of the command set- variable; just type enough so that autocompletion does the rest. See the section Completion in The GNU Emacs Lisp Reference Manual.
M-x set-variable RET debug-on-error RET t
Or evaluate the following expression:
(setq debug-on-error t)
This causes Emacs to enter the debugger next time it encounters an error. (You can turn off debugging by setting debug-on-error to nil.)
If you turn on the debugger and evaluate this:
(add-37 5)
you see the following in an automatically created *Backtrace* buffer:
---------- Buffer: *Backtrace* ---------- Signaling: (void-variable nmber) (+ 37 nmber) (message The new number is: %d! (+ 37 nmber)) add-37(5) eval((add-37 5)) eval-last-sexp(nil) * call-interactively(eval-last-sexp) ---------- Buffer: *Backtrace* ----------
Read the *Backtrace* buffer from the bottom up; it tells what the Lisp interpreter did that led to the error. In this case, you made an interactive call by typing C-x C-e (eval-last-sexp), which led to the evaluation of the (add-37 5) expression. Each line above tells you what the Lisp interpreter evaluated next.
The interpreter attempted to evaluate this:
(message The new number is: %d! (+ 37 nmber))
To do that, it first attempted to evaluate the inner list,
(+ 37 nmber)
To evaluate (+ 37 nmber), it attempted to evaluate nmber.
The interpreter looked in the value cell of nmber, expecting to find a value there; but the value cell was empty, or void.
As a result, the interpreter signaled a void-variable error.
In addition to entering the built-in debugger when there is an error, you can cause the interpreter to enter the debugger when it enters a specified function, or when you signal quit by typing C-g.
The debug function is described in detail in the section The Lisp Debugger in The GNU Emacs Lisp Reference Manual.
The second debugger, Edebug, allows you to step through a function and much else.
To use Edebug, you need to prepare the function definition in which you are interested by evaluating it with a special Edebug version of eval. Usually, you do this by placing your cursor within the function definition and typing C-x X d, which runs the command edebug-eval-top-level-form. This action causes the Lisp interpreter to insert numerous edebug-before and edebug-after functions into the function definition that is in the function cell of the symbol.
If you want to see what occurs, first evaluate the add-37 function definition shown previously in the normal way with C-x C-e, and then evaluate this:
(symbol-function add-37)
You will see a lambda expression such as discussed previously.
Previous | Table of Contents | Next |