debug

Suppose you have written a function definition that is intended to return the sum of the numbers 1 through a given number. (This is the triangle function discussed earlier. See section Example with decrementing counter, for a discussion.)

However, your function definition has a bug. You have mistyped `1=' for `1-'. Here is the broken definition:

(defun triangle-bugged (number)
  "Return sum of numbers 1 through NUMBER inclusive."
  (let ((total 0))
    (while (> number 0)
      (setq total (+ total number))
      (setq number (1= number)))      ; Error here.
    total))

If you are reading this in Info, you can evaluate this definition in the normal fashion. You will see triangle-bugged appear in the echo area.

Now evaluate the triangle-bugged function with an argument of 4:

(triangle-bugged 4)

You will produce an error message that says: 

Symbol's function definition is void: 1=

In practice, for a bug as simple as this, this error message will tell you what you need to know to correct the definition. However, suppose you are not quite certain what is going on?

You can turn on debugging by setting the value of debug-on-error to t:

(setq debug-on-error t)

This causes Emacs to enter the debugger next time it encounters an error.

You can turn off debug-on-error by setting it to nil:

(setq debug-on-error nil)

Set debug-on-error to t and evaluate the following:

(triangle-bugged 4)

This time, Emacs will create a buffer called `*Backtrace*' that looks like this:

---------- Buffer: *Backtrace* ----------
Signalling: (void-function 1=)
  (1= number))
  (setq number (1= number)))
  (while (> number 0) (setq total (+ total number))
        (setq number (1= number))))
  (let ((total 0)) (while (> number 0) (setq total ...)
        (setq number ...)) total))
  triangle-bugged(4)
  eval((triangle-bugged 4))
  eval-last-sexp(nil)
* call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

(I have reformatted this example slightly; the debugger does not fold long lines.)

You read the `*Backtrace*' buffer from the bottom up; it tells you what Emacs did that led to the error. In this case, what Emacs did was make an interactive call to C-x C-e (eval-last-sexp), which led to the evaluation of the triangle-bugged expression. Each line above tells you what the Lisp interpreter evaluated next.

The third line from the top of the buffer is

(setq number (1= number))

Emacs tried to evaluate this expression; in order to do so, it tried to evaluate the inner expression shown on the second line from the top:

(1= number)

This is where the error occurred; as the top line says:

Signalling: (void-function 1=)

You can correct the mistake, re-evaluate the function definition, and then run your test again.

If you are reading this in Info, you can now turn off debug-on-error by setting it to nil:

(setq debug-on-error nil)

Go to the first, previous, next, last section, table of contents.